{"id":6877,"library":"semantic-router","title":"Semantic Router","description":"Semantic Router is a superfast decision-making layer for LLMs and agents. It routes requests based on semantic meaning using vector space, rather than relying on slow LLM generations for tool-use or safety decisions. It supports various embedding models (e.g., OpenAI, Cohere, Hugging Face) and integrates with vector databases like Pinecone and Qdrant. The library is actively maintained with frequent updates and a focus on speed, safety, and scalability.","status":"active","version":"0.1.12","language":"en","source_language":"en","source_url":"https://github.com/aurelio-labs/semantic-router","tags":["AI","LLM","routing","semantic search","decision-making","agents","embeddings"],"install":[{"cmd":"pip install semantic-router","lang":"bash","label":"Standard Installation"},{"cmd":"pip install \"semantic-router[local]\"","lang":"bash","label":"Local Models (HuggingFaceEncoder, LlamaCppLLM)"},{"cmd":"pip install \"semantic-router[hybrid]\"","lang":"bash","label":"Hybrid Routing"},{"cmd":"pip install \"semantic-router[cohere]\"","lang":"bash","label":"Cohere Encoder"},{"cmd":"pip install \"semantic-router[openai]\"","lang":"bash","label":"OpenAI Encoder"}],"dependencies":[{"reason":"Required Python version compatibility","package":"python","optional":false},{"reason":"For using OpenAIEncoder and related functionalities","package":"openai","optional":true},{"reason":"For using CohereEncoder","package":"cohere","optional":true},{"reason":"For using HuggingFaceEncoder","package":"huggingface-hub","optional":true},{"reason":"For using Pinecone as a vector index","package":"pinecone-client","optional":true},{"reason":"For using Qdrant as a vector index","package":"qdrant-client","optional":true}],"imports":[{"symbol":"Route","correct":"from semantic_router import Route"},{"note":"`RouteLayer` was renamed to `SemanticRouter` and moved to `semantic_router.routers` in versions 0.1.3+.","wrong":"from semantic_router import RouteLayer","symbol":"SemanticRouter","correct":"from semantic_router.routers import SemanticRouter"},{"symbol":"OpenAIEncoder","correct":"from semantic_router.encoders import OpenAIEncoder"},{"symbol":"CohereEncoder","correct":"from semantic_router.encoders import CohereEncoder"},{"symbol":"LocalIndex","correct":"from semantic_router.index import LocalIndex"},{"symbol":"HybridRouter","correct":"from semantic_router.routers import HybridRouter"}],"quickstart":{"code":"import os\nfrom semantic_router import Route\nfrom semantic_router.encoders import OpenAIEncoder\nfrom semantic_router.routers import SemanticRouter\nfrom semantic_router.index import LocalIndex\n\n# Ensure API key is set or prompt for it\nif not os.getenv(\"OPENAI_API_KEY\"): #\n    print(\"Please set the OPENAI_API_KEY environment variable.\")\n    # In a real application, you might raise an error or use getpass\n    os.environ[\"OPENAI_API_KEY\"] = os.environ.get(\"OPENAI_API_KEY\", \"sk-YOUR_OPENAI_KEY_HERE\")\n\n# 1. Define routes\npolitics = Route(\n    name=\"politics\",\n    utterances=[\n        \"isn't politics the best thing ever\",\n        \"why don't you tell me about your political opinions\",\n        \"they're going to destroy this country!\"\n    ]\n)\nchitchat = Route(\n    name=\"chitchat\",\n    utterances=[\n        \"how's the weather today?\",\n        \"how are things going?\",\n        \"lovely weather today\"\n    ]\n)\nroutes = [politics, chitchat]\n\n# 2. Initialize an encoder (e.g., OpenAIEncoder)\nencoder = OpenAIEncoder()\n\n# 3. Create a SemanticRouter instance with an index (e.g., LocalIndex)\n# For persistent storage, consider PineconeIndex, QdrantIndex, etc.\nrouter = SemanticRouter(\n    encoder=encoder,\n    routes=routes,\n    index=LocalIndex()\n)\n\n# 4. Route a query\nquery1 = \"What do you think about the government?\"\nroute_result1 = router(query1)\nprint(f\"Query: '{query1}' -> Routed to: {route_result1.name} (Score: {route_result1.score:.2f})\")\n\nquery2 = \"How's life treating you?\"\nroute_result2 = router(query2)\nprint(f\"Query: '{query2}' -> Routed to: {route_result2.name} (Score: {route_result2.score:.2f})\")\n\nquery3 = \"Tell me a story.\"\nroute_result3 = router(query3) # Should return None if no match above threshold\nprint(f\"Query: '{query3}' -> Routed to: {route_result3.name if route_result3 else 'None'} (Score: {route_result3.score:.2f} if route_result3 else 'N/A')\")","lang":"python","description":"This quickstart demonstrates how to define semantic routes, initialize an encoder (OpenAI in this case), create a router with a local index, and then use it to categorize incoming queries based on their semantic meaning. Ensure your OpenAI API key is set as an environment variable."},"warnings":[{"fix":"Update imports from `from semantic_router import RouteLayer` to `from semantic_router.routers import SemanticRouter`.","message":"The `RouteLayer` class has been renamed to `SemanticRouter` and moved from the top-level `semantic_router` module to `semantic_router.routers`.","severity":"breaking","affected_versions":"0.1.3+"},{"fix":"For similar functionality, you might use `router.__call__(limit=None)` or `router.acall(limit=None)`, or the deprecated `_semantic_classify_multiple_routes` in versions 0.1.0-0.1.2. Consult documentation for the specific version you are using.","message":"The `retrieve_multiple_routes` method on the router has been removed.","severity":"deprecated","affected_versions":"0.1.3+"},{"fix":"Set the required API keys as environment variables before initializing the corresponding encoder, e.g., `os.environ[\"OPENAI_API_KEY\"] = \"your_key_here\"`.","message":"Many encoders (e.g., OpenAIEncoder, CohereEncoder) require API keys set as environment variables (e.g., `OPENAI_API_KEY`). The library will not function correctly without these being properly configured.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install the necessary optional dependencies using the `pip install \"semantic-router[extra]\"` syntax for the features you intend to use.","message":"Specific features like using local models (`HuggingFaceEncoder`, `LlamaCppLLM`) or hybrid routing (`HybridRouter`) require extra installation commands (e.g., `pip install \"semantic-router[local]\"`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure the `threshold` parameter during router initialization. For dynamic thresholding, ensure `OPENAI_API_KEY` is set if using an `OpenAIEncoder`.","message":"To prevent incorrect routing decisions, especially for queries that don't strongly match any defined route, it is crucial to set an appropriate similarity threshold.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}