fix: bad format in docs

[jamescalam]

PR Type

Documentation

---

Description

This PR addresses formatting issues in the documentation notebooks to improve readability and clarity:

• Reformatted markdown cells in docs/02-dynamic-routes.ipynb and docs/09-route-filter.ipynb.
• Reorganized code cells for better structure and understanding.
• Added missing code outputs to ensure completeness.

---

Changes walkthrough 📝

	Relevant files
Documentation	02-dynamic-routes.ipynb Reformat and reorganize dynamic routes documentation notebook docs/02-dynamic-routes.ipynb Reformatted markdown cells for better readability. Reorganized code cells for clarity. Added missing code outputs. +1125/-1044 09-route-filter.ipynb Reformat and reorganize route filter documentation notebook docs/09-route-filter.ipynb Reformatted markdown cells for better readability. Reorganized code cells for clarity. Added missing code outputs. +381/-321
Additional files (token-limit)	05-local-execution.ipynb ...                                                                                                            docs/05-local-execution.ipynb ... +835/-780 03-basic-langchain-agent.ipynb ...                                                                                                            docs/03-basic-langchain-agent.ipynb ... +754/-760 06-threshold-optimization.ipynb ...                                                                                                            docs/06-threshold-optimization.ipynb ... +568/-500 04-chat-history.ipynb ...                                                                                                            docs/04-chat-history.ipynb ... +249/-230 01-save-load-from-file.ipynb ...                                                                                                            docs/01-save-load-from-file.ipynb ... +428/-361 00-introduction.ipynb ...                                                                                                            docs/00-introduction.ipynb ... +357/-301

---

💡 PR-Agent usage:
Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[github-actions]

PR Reviewer Guide 🔍

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review Possible Bug: The PR introduces a large amount of changes in the Jupyter notebooks, which are not fully displayed due to token limitations. It's crucial to ensure that all changes are intended and correctly implemented, especially in dynamic code execution cells. Documentation Clarity: The changes in the documentation should be reviewed for clarity and accuracy. Ensure that the new content is well-organized and enhances the user's understanding without introducing confusion. Code Execution: For the Jupyter notebooks, it's important to verify that all cells execute correctly without errors and that the outputs are as expected. This includes checking for any deprecated functions or methods that might have been introduced.

[github-actions]

PR Code Suggestions ✨

Category	Suggestion	Score
Possible bug	Correct the concatenation error in the 'utterances' list The concatenated string in the 'utterances' list seems to be a mistake. It should be split into two separate strings to match the intended list of phrases. docs/01-save-load-from-file.ipynb [95] -"don't you just love the president" "don't you just hate the president", +"don't you just love the president", +"don't you just hate the president", Suggestion importance[1-10]: 10 Why: Fixing the concatenation error in the 'utterances' list is essential to ensure the list of phrases is correctly interpreted. This addresses a potential bug that could affect the functionality of the code.	10
	Add a check to ensure the API key is set to prevent runtime errors To avoid potential runtime errors and ensure that the API key is always set before use, add a check to ensure the environment variable for the API key is not None or empty. Raise an exception or log a clear error message if the key is missing. docs/03-basic-langchain-agent.ipynb [160-161] -os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY") or getpass("Enter OpenAI API Key: ") +api_key = os.getenv("OPENAI_API_KEY") or getpass("Enter OpenAI API Key: ") +if not api_key: + raise ValueError("OPENAI_API_KEY is required but not set.") +os.environ["OPENAI_API_KEY"] = api_key Suggestion importance[1-10]: 8 Why: This suggestion adds a necessary check to ensure the API key is set, which can prevent potential runtime errors and improve the robustness of the code.	8
Securit	Improve security by removing hardcoded API key retrieval logic It is recommended to remove the hardcoded API key retrieval logic from the notebook to enhance security and maintainability. Instead, use environment variables set outside of the notebook or a secure vault service. docs/00-introduction.ipynb [153-158] -os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY") or getpass( - "Enter OpenAI API Key: " -) +# Ensure the OPENAI_API_KEY environment variable is set outside this notebook +os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY") Suggestion importance[1-10]: 9 Why: The suggestion correctly identifies a security concern by recommending the removal of hardcoded API key retrieval logic, which enhances security and maintainability. However, it assumes that users will set the environment variable externally, which may require additional instructions.	9
Best practice	Add error handling for JSON file loading to improve robustness It's recommended to handle potential exceptions when loading JSON files to prevent the notebook from crashing due to file not found or corrupted JSON data. This can be done using a try-except block. docs/01-save-load-from-file.ipynb [285-286] -with open("layer.json", "r") as f: - layer_json = json.load(f) +try: + with open("layer.json", "r") as f: + layer_json = json.load(f) +except FileNotFoundError: + print("File not found. Please check the file path.") +except json.JSONDecodeError: + print("Failed to decode JSON. Please check the file content.") Suggestion importance[1-10]: 9 Why: Adding error handling for JSON file loading is a best practice that can prevent the notebook from crashing due to common issues like file not found or corrupted JSON data. This significantly improves the robustness of the code.	9
	Specify the package version to ensure reproducibility To avoid potential issues with package versions and ensure reproducibility, specify the version of the 'semantic-router' package when installing it. docs/01-save-load-from-file.ipynb [49] -!pip install -qU semantic-router +!pip install -qU semantic-router==1.2.3 # Specify the version you need Suggestion importance[1-10]: 7 Why: Specifying the package version when installing ensures reproducibility and avoids potential issues with package updates. This is a good practice for maintaining consistent environments, although it is not as critical as fixing bugs or security issues.	7
Enhancement	Improve the robustness of timezone handling in the get_time function It's recommended to use a more robust method for handling user input for timezone in the get_time function. Instead of directly passing the timezone string to ZoneInfo, validate it against a list of known timezones from the zoneinfo module to prevent potential errors from invalid timezone strings. docs/02-dynamic-routes.ipynb [277-288] -now = datetime.now(ZoneInfo(timezone)) +if timezone in zoneinfo.available_timezones(): + now = datetime.now(ZoneInfo(timezone)) +else: + raise ValueError("Invalid timezone provided") Suggestion importance[1-10]: 9 Why: This suggestion enhances the robustness of the get_time function by validating the timezone against known timezones, which prevents potential errors from invalid timezone strings. This is a significant improvement in terms of error handling and reliability.	9
	Refactor conditional statements into a dictionary mapping to streamline function calls To improve the efficiency of the code, consider using a dictionary to map route names to their corresponding functions. This approach can simplify the logic in the semantic_layer function by reducing the number of conditional statements. docs/03-basic-langchain-agent.ipynb [348-358] -if route.name == "get_time": - query += f" (SYSTEM NOTE: {get_time()})" -elif route.name == "supplement_brand": - query += f" (SYSTEM NOTE: {supplement_brand()})" -elif route.name == "business_inquiry": - query += f" (SYSTEM NOTE: {business_inquiry()})" -elif route.name == "product": - query += f" (SYSTEM NOTE: {product()})" -else: - pass +route_actions = { + "get_time": get_time, + "supplement_brand": supplement_brand, + "business_inquiry": business_inquiry, + "product": product +} +action = route_actions.get(route.name) +if action: + query += f" (SYSTEM NOTE: {action()})" Suggestion importance[1-10]: 7 Why: The suggestion improves code efficiency and readability by reducing the number of conditional statements. Using a dictionary to map route names to functions is a cleaner and more maintainable approach.	7
Security	Improve security by handling sensitive API key more securely To ensure that the API key is not accidentally hardcoded or exposed, it's safer to use environment variables directly or prompt for input without assigning it to a variable that might get printed or logged. docs/01-save-load-from-file.ipynb [146] -os.environ["COHERE_API_KEY"] = os.getenv("COHERE_API_KEY") or getpass("Enter Cohere API Key: ") +if "COHERE_API_KEY" not in os.environ: + os.environ["COHERE_API_KEY"] = getpass("Enter Cohere API Key: ") Suggestion importance[1-10]: 8 Why: The suggested change enhances security by ensuring that the API key is not accidentally hardcoded or exposed. This is a crucial improvement for handling sensitive information securely.	8
	Secure the handling of the OpenAI API key by using environment variables directly To ensure that the API keys are securely handled and not accidentally exposed or hardcoded, use environment variables directly in the code. Avoid using getpass in a script where it might lead to unintentional exposure or operational issues in a non-interactive environment. docs/02-dynamic-routes.ipynb [202] -os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_API_KEY") or getpass("Enter OpenAI API Key: ") +os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY") Suggestion importance[1-10]: 8 Why: This suggestion enhances security by ensuring that API keys are handled securely through environment variables, avoiding potential exposure or operational issues in non-interactive environments.	8
	Improve the security and maintainability of environment variable management Consider using a more robust method for handling environment variables to improve security and maintainability. Instead of directly using os.getenv in the assignment, use a dedicated configuration management system or a more secure method of handling sensitive data. docs/03-basic-langchain-agent.ipynb [160-161] -os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY") or getpass("Enter OpenAI API Key: ") +from config import get_config +os.environ["OPENAI_API_KEY"] = get_config("OPENAI_API_KEY") Suggestion importance[1-10]: 5 Why: While using a dedicated configuration management system can improve security and maintainability, the suggestion does not provide a clear implementation for the get_config function, making it less practical without additional context. The current method using getpass is still a common practice for handling sensitive data in scripts.	5
Maintainability	Refactor the function call mechanism to use a mapping dictionary for better maintainability To enhance the readability and maintainability of the code, consider using a dictionary to map utterances to their respective functions instead of multiple if-else conditions. This approach simplifies modifications and additions to the function mappings. docs/02-dynamic-routes.ipynb [529-531] -if call["function_name"] == "get_time": +function_map = { + "get_time": get_time +} +if call["function_name"] in function_map: args = call["arguments"] - result = get_time(**args) + result = function_map[call["function_name"]](**args) Suggestion importance[1-10]: 7 Why: Using a dictionary to map function names to their respective functions improves code readability and maintainability. This refactor simplifies future modifications and additions to the function mappings.	7
	Use a loop to dynamically construct the routes list To enhance code readability and maintainability, consider using a loop to append routes to the list instead of manually adding each route. This approach reduces the risk of errors and simplifies modifications. docs/03-basic-langchain-agent.ipynb [137] -routes = [time_route, supplement_route, business_route, product_route] +route_names = ["time_route", "supplement_route", "business_route", "product_route"] +routes = [globals()[name] for name in route_names] Suggestion importance[1-10]: 4 Why: The suggestion improves maintainability by reducing manual additions, but it introduces the use of globals(), which can be error-prone and less readable. The current method is straightforward and clear.	4