# Semantic Router

> A superfast decision-making layer for LLMs and agents that uses semantic vector space to route requests by meaning instead of slow LLM calls.

Semantic Router is an open-source Python library built by Aurelio Labs that adds a deterministic, sub-millisecond decision layer on top of LLMs and AI agents. Rather than relying on slow, unpredictable LLM generations to decide which tool to call or whether a request is safe, it encodes utterances into semantic vector space and routes incoming queries by meaning — returning decisions in roughly 4ms versus several seconds for a full LLM round-trip. The project is MIT-licensed, requires Python 3.9+, and is installable via `pip install semantic-router`.

## What It Is

Semantic Router sits between user input and your LLM or agent logic, acting as a fast classification and guardrail layer. Developers define `Route` objects — each with a name and a set of example utterances — and the library encodes those utterances into a vector index. At inference time, an incoming query is encoded and compared against the index; the closest matching route (above a configurable score threshold) is returned deterministically, with zero LLM calls. If no route clears the threshold, the router returns `None`, letting the query fall through to a default handler without hallucinating a tool call.

The library supports three routing modes:
- **Static routes** — pure vector-space classification, no LLM involved
- **Dynamic routes** — routes that trigger parameter extraction via an LLM after the routing decision
- **Guardrails** — routes used to block or flag unsafe or off-topic inputs before they reach the model

## Encoder and Index Ecosystem

Semantic Router is encoder-agnostic and ships integrations for a wide range of embedding providers:

- **Proprietary APIs**: OpenAI, Cohere, Azure OpenAI, AWS Bedrock, Google Vertex, Mistral, Jina AI, VoyageAI
- **Local / open-weight**: HuggingFace Sentence Transformers, FastEmbed, ONNX, Llama.cpp
- **Vector indexes**: Local NumPy (default), Pinecone, Qdrant, PostgreSQL with pgvector

This means teams can run the router entirely offline with local models or connect to managed embedding APIs, depending on their latency, cost, and data-privacy requirements.

## Why It Got Attention

The project launched in late 2023 and accumulated over 3,900 GitHub stars and 373 forks. Community commentary highlighted by the project page describes it as filling a gap in LangChain-style agent frameworks — providing "fuzzy if/else statements" over embedding space rather than brittle string matching. The library has been cited in an IEEE GlobeCom 2024 paper on semantic routing for 5G network management, and the project page lists organizations including McGraw Hill, Red Hat, Pinecone, the Internet Archive, and the UK Government as users (vendor-published claim).

## Performance Characteristics

The project homepage benchmarks Semantic Router at approximately 4ms per decision versus 3,860ms time-to-first-token for Claude Opus 5 (sourced from Artificial Analysis, July 2026). This three-orders-of-magnitude gap is the core value proposition: for high-frequency agent loops where every turn requires a routing or safety decision, replacing LLM calls with vector-space lookups dramatically reduces latency and cost. The score threshold is user-configurable and can be optimized via a built-in threshold-tuning notebook.

## Update: v0.2.0.dev1

The latest release on GitHub is `v0.2.0.dev1`, published August 24, 2026, indicating active development toward a 0.2 major version. The stable release shown on the project homepage is `0.1.16`. The repository was last pushed to on September 12, 2026, and last updated September 20, 2026, showing ongoing maintenance. Aurelio Labs also publishes a companion online course for Semantic Router and maintains related open-source libraries — `semantic-chunkers` (0.0.10) and `graphai` (0.0.7) — as part of a broader "semantic mesh" for production AI systems.

## Features
- Deterministic semantic routing with zero LLM calls
- Static, dynamic, and guardrail routing modes
- Configurable score threshold for route matching
- Support for 12+ embedding encoders including local and API-based
- Vector index integrations: NumPy, Pinecone, Qdrant, pgvector
- Multi-modal route support
- Route threshold optimization/training
- LangChain agent integration
- Fully local execution with HuggingFace and Llama.cpp
- Auto-sync route layer to local or remote index
- Sub-millisecond routing decisions
- MIT licensed and fully open source

## Integrations
OpenAI, Cohere, HuggingFace, FastEmbed, Azure OpenAI, AWS Bedrock, Google Vertex AI, Mistral, Jina AI, VoyageAI, Pinecone, Qdrant, PostgreSQL pgvector, LangChain, Llama.cpp, ONNX

## Platforms
CLI, API, DEVELOPER_SDK

## Pricing
Open Source

## Version
0.1.16

## Links
- Website: https://www.aurelio.ai/semantic-router
- Documentation: https://docs.aurelio.ai/semantic-router/get-started/introduction
- Repository: https://github.com/aurelio-labs/semantic-router
- EveryDev.ai: https://www.everydev.ai/tools/semantic-router