{"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":"python","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,"search_vec":"'activ':62 'agent':15,83 'ai':75 'base':19 'coher':47 'databas':54 'decis':9,39,81 'decision-mak':8,80 'e.g':45 'embed':43,84 'face':49 'focus':69 'frequent':65 'generat':32 'hug':48 'integr':51 'layer':11 'librari':60 'like':55 'llm':31,76 'llms':13 'maintain':63 'make':10,82 'mean':22 'model':44 'openai':46 'pinecon':56 'qdrant':58 'rather':26 'reli':28 'request':18 'rout':17,77 'router':2,4 'safeti':38,72 'scalabl':74 'search':79 'semant':1,3,21,78 'slow':30 'space':25 'speed':71 'superfast':7 'support':41 'tool':35 'tool-us':34 'updat':66 'use':23,36 'various':42 'vector':24,53","created_at":"2026-04-15T18:46:52.084694+00:00","updated_at":"2026-04-16T21:34:07.592528+00:00","problems":[{"fix":"Install the library using pip: `pip install semantic-router`","cause":"The `semantic-router` library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'semantic_router'"},{"fix":"Ensure the `OPENAI_API_KEY` environment variable is set to a valid key: `export OPENAI_API_KEY='your_api_key_here'`","cause":"The OpenAI API key is missing, invalid, or incorrectly configured as an environment variable, preventing successful authentication with the OpenAI API.","error":"openai.AuthenticationError: Incorrect API key provided"},{"fix":"Verify that all required API keys (e.g., `OPENAI_API_KEY`, `COHERE_API_KEY`, `HUGGINGFACE_HUB_API_TOKEN`) are correctly set as environment variables before initializing `semantic-router` components.","cause":"This error often occurs when an LLM or Encoder component (e.g., `OpenAIEncoder`) fails to initialize properly due to a missing API key or invalid configuration, causing a `None` object to be used where a callable is expected.","error":"TypeError: 'NoneType' object is not callable"},{"fix":"Ensure all required fields for `Route` (e.g., `name`, `utterances`) are provided with correct data types when defining your routes.","cause":"A `Route` object was instantiated with invalid or missing data, failing Pydantic's schema validation (e.g., missing required fields like `name` or `utterances`, or incorrect data types).","error":"pydantic.ValidationError: 1 validation error for Route"},{"fix":"Install `semantic-router` with the necessary extra dependency. For `FastEmbedEncoder`, use: `pip install semantic-router[fastembed]`. Other extras include `[cohere]`, `[openai]`, `[huggingface]`, etc.","cause":"You are attempting to use an encoder or LLM provider (e.g., `FastEmbedEncoder`) that requires an optional dependency which has not been installed.","error":"ModuleNotFoundError: No module named 'fastembed'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.15","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/semantic-router/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","vector-search","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}