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
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.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')")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'semantic_router'
The `semantic-router` library is not installed in your current Python environment.
fixInstall 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.
fixEnsure 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.
fixVerify 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).
fixEnsure 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.
fixInstall `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