Registry / llm-agents / semantic-router

semantic-router

JSON →
library0.1.15pypypi✓ verified 84d ago

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.

pip install semantic-router
INSTALL
IMPORT
SIG · SEMANTIC-ROUTER
S
semantic-router
llm-agentspythonv0.1.15
Install
17.1s avg
Import
9658ms
Disk
312MB
Pass rate
2/ 10
Env Coverage2 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.15 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
16/20 runs
16/20 runs
py 3.11
16/20 runs
16/20 runs
py 3.12
16/20 runs
16/20 runs
py 3.13
✓ —
✓ 17.1s
py 3.9
16/20 runs
16/20 runs
312MB installed
● package 312MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Route
from semantic_router import Route
SemanticRouter
from semantic_router.routers import SemanticRouter
from semantic_router import RouteLayer
`RouteLayer` was renamed to `SemanticRouter` and moved to `semantic_router.routers` in versions 0.1.3+.
OpenAIEncoder
from semantic_router.encoders import OpenAIEncoder
CohereEncoder
from semantic_router.encoders import CohereEncoder
LocalIndex
from semantic_router.index import LocalIndex
HybridRouter
from semantic_router.routers import HybridRouter

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.

import os from semantic_router import Route from semantic_router.encoders import OpenAIEncoder from semantic_router.routers import SemanticRouter from semantic_router.index import LocalIndex # Ensure API key is set or prompt for it if not os.getenv("OPENAI_API_KEY"): # print("Please set the OPENAI_API_KEY environment variable.") # In a real application, you might raise an error or use getpass os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-YOUR_OPENAI_KEY_HERE") # 1. Define routes politics = Route( name="politics", utterances=[ "isn't politics the best thing ever", "why don't you tell me about your political opinions", "they're going to destroy this country!" ] ) chitchat = Route( name="chitchat", utterances=[ "how's the weather today?", "how are things going?", "lovely weather today" ] ) routes = [politics, chitchat] # 2. Initialize an encoder (e.g., OpenAIEncoder) encoder = OpenAIEncoder() # 3. Create a SemanticRouter instance with an index (e.g., LocalIndex) # For persistent storage, consider PineconeIndex, QdrantIndex, etc. router = SemanticRouter( encoder=encoder, routes=routes, index=LocalIndex() ) # 4. Route a query query1 = "What do you think about the government?" route_result1 = router(query1) print(f"Query: '{query1}' -> Routed to: {route_result1.name} (Score: {route_result1.score:.2f})") query2 = "How's life treating you?" route_result2 = router(query2) print(f"Query: '{query2}' -> Routed to: {route_result2.name} (Score: {route_result2.score:.2f})") query3 = "Tell me a story." route_result3 = router(query3) # Should return None if no match above threshold print(f"Query: '{query3}' -> Routed to: {route_result3.name if route_result3 else 'None'} (Score: {route_result3.score:.2f} if route_result3 else 'N/A')")
Debug
Known issues
breakingThe `RouteLayer` class has been renamed to `SemanticRouter` and moved from the top-level `semantic_router` module to `semantic_router.routers`.
fix
Update imports from `from semantic_router import RouteLayer` to `from semantic_router.routers import SemanticRouter`.
affects: 0.1.3+
deprecatedThe `retrieve_multiple_routes` method on the router has been removed.
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.
affects: 0.1.3+
gotchaMany 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.
fix
Set the required API keys as environment variables before initializing the corresponding encoder, e.g., `os.environ["OPENAI_API_KEY"] = "your_key_here"`.
affects: All versions
gotchaSpecific features like using local models (`HuggingFaceEncoder`, `LlamaCppLLM`) or hybrid routing (`HybridRouter`) require extra installation commands (e.g., `pip install "semantic-router[local]"`).
fix
Install the necessary optional dependencies using the `pip install "semantic-router[extra]"` syntax for the features you intend to use.
affects: All versions
gotchaTo prevent incorrect routing decisions, especially for queries that don't strongly match any defined route, it is crucial to set an appropriate similarity threshold.
fix
Configure the `threshold` parameter during router initialization. For dynamic thresholding, ensure `OPENAI_API_KEY` is set if using an `OpenAIEncoder`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'semantic_router'
The `semantic-router` library is not installed in your current Python environment.
fix
Install the library using pip: `pip install semantic-router`
openai.AuthenticationError: Incorrect API key provided
The OpenAI API key is missing, invalid, or incorrectly configured as an environment variable, preventing successful authentication with the OpenAI API.
fix
Ensure the `OPENAI_API_KEY` environment variable is set to a valid key: `export OPENAI_API_KEY='your_api_key_here'`
TypeError: 'NoneType' object is not callable
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.
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.
pydantic.ValidationError: 1 validation error for Route
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).
fix
Ensure all required fields for `Route` (e.g., `name`, `utterances`) are provided with correct data types when defining your routes.
ModuleNotFoundError: No module named 'fastembed'
You are attempting to use an encoder or LLM provider (e.g., `FastEmbedEncoder`) that requires an optional dependency which has not been installed.
fix
Install `semantic-router` with the necessary extra dependency. For `FastEmbedEncoder`, use: `pip install semantic-router[fastembed]`. Other extras include `[cohere]`, `[openai]`, `[huggingface]`, etc.
Upgrade
Version history
0.1.15latest on PyPI · released May 23, 2026
Audit
Dependencies
pythonrequiredRequired Python version compatibility
openaioptionalFor using OpenAIEncoder and related functionalities
cohereoptionalFor using CohereEncoder
huggingface-huboptionalFor using HuggingFaceEncoder
pinecone-clientoptionalFor using Pinecone as a vector index
qdrant-clientoptionalFor using Qdrant as a vector index
Agent activity
66 hits · last 30 days
node
56
OpenAI (training)
1
Resources
semantic-router — pip install semantic-router · libregistry