# aurelio-labs/semantic-router architecture

> Architecture diagram of the GitHub repository aurelio-labs/semantic-router, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aurelio-labs/semantic-router
- Repository: https://github.com/aurelio-labs/semantic-router
- Video tour (about a minute): https://gitdiagram.com/aurelio-labs/semantic-router/video

## Overview

Semantic Router is a Python decision layer that maps a user query to a configured route using semantic similarity, returning no match when none qualifies. The principal workflow is to define routes and utterances, select an encoder, initialize a router, and submit queries; router implementations also support hybrid routing and index synchronization. Routes can invoke LLM-backed dynamic parameter or function-call extraction. The README also documents multimodal routing, threshold optimization, and local execution. Some subsystem links are based on documented capabilities or module references; unsampled implementation details are not assumed.

Main entry points: [`semantic_router/routers/semantic.py`](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/routers/semantic.py) (Semantic router), [`semantic_router/route.py`](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/route.py) (Route definitions), [`semantic_router/routers/base.py`](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/routers/base.py) (Router core), [`semantic_router/encoders/base.py`](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/encoders/base.py) (Encoder interfaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing"]
  node_route_defs["Route definitions<br/>[route.py]"]
  node_semantic_router["Semantic router<br/>[semantic.py]"]
  node_router_core["Router core<br/>[base.py]"]
  node_hybrid_router["Hybrid router<br/>[hybrid.py]"]
  node_thresholds["Threshold optimization<br/>[linear.py]"]
end

subgraph group_encoding["Encoding"]
  node_encoder_base["Encoder interfaces<br/>[base.py]"]
  node_encoder_types["Encoder input types"]
  node_encoder_providers["Encoder providers"]
  node_multimodal["Multimodal encoding<br/>[clip.py]"]
end

subgraph group_indexes["Indexes"]
  node_index_base["Index interface<br/>[base.py]"]
  node_local_index["Local index<br/>[local.py]"]
  node_hybrid_index["Hybrid local index<br/>[hybrid_local.py]"]
  node_pinecone_index[("Pinecone index<br/>[pinecone.py]")]
  node_postgres_index[("Postgres index<br/>[postgres.py]")]
  node_qdrant_index[("Qdrant index<br/>[qdrant.py]")]
end

subgraph group_generation["LLM and calls"]
  node_llm_base["LLM interface<br/>[base.py]"]
  node_llm_providers["LLM providers<br/>[openai.py]"]
  node_function_call["Function extraction<br/>[function_call.py]"]
end

subgraph group_shared["Shared models"]
  node_schema["Route and index schemas<br/>[schema.py]"]
  node_defaults["Model defaults<br/>[defaults.py]"]
end

node_user(("User query"))

node_user -->|"submits query"| node_semantic_router
node_route_defs -->|"configures routes"| node_semantic_router
node_semantic_router -->|"builds on"| node_router_core
node_router_core -->|"calls route"| node_route_defs
node_route_defs -->|"extracts inputs"| node_llm_base
node_route_defs -->|"uses helpers"| node_function_call
node_semantic_router -->|"uses encoder"| node_encoder_base
node_router_core -->|"uses index"| node_index_base
node_hybrid_router -->|"queries index"| node_hybrid_index
node_hybrid_router -->|"encodes query"| node_encoder_base
node_encoder_providers -.->|"implements interface"| node_encoder_base
node_multimodal -.->|"provides encoding"| node_encoder_base
node_semantic_router -->|"supports local sync"| node_local_index
node_semantic_router -->|"supports integration"| node_pinecone_index
node_semantic_router -->|"supports integration"| node_qdrant_index
node_index_base -->|"uses metadata"| node_schema
node_router_core -->|"builds config"| node_schema
node_llm_providers -->|"implements interface"| node_llm_base
node_encoder_providers -->|"reads defaults"| node_defaults
node_thresholds -.->|"optimizes thresholds"| node_semantic_router
node_route_defs -.->|"dynamic generation"| node_llm_providers

click node_route_defs "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/route.py"
click node_semantic_router "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/routers/semantic.py"
click node_router_core "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/routers/base.py"
click node_hybrid_router "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/routers/hybrid.py"
click node_encoder_base "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/encoders/base.py"
click node_encoder_types "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/encoders/encode_input_type.py"
click node_encoder_providers "https://github.com/aurelio-labs/semantic-router/tree/main/semantic_router/encoders"
click node_multimodal "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/encoders/clip.py"
click node_index_base "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/base.py"
click node_local_index "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/local.py"
click node_hybrid_index "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/hybrid_local.py"
click node_pinecone_index "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/pinecone.py"
click node_postgres_index "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/postgres.py"
click node_qdrant_index "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/qdrant.py"
click node_llm_base "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/llms/base.py"
click node_llm_providers "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/llms/openai.py"
click node_function_call "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/utils/function_call.py"
click node_schema "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/schema.py"
click node_defaults "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/utils/defaults.py"
click node_thresholds "https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/linear.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_route_defs,node_semantic_router,node_router_core,node_hybrid_router,node_thresholds,node_user toneBlue
class node_encoder_base,node_encoder_types,node_encoder_providers,node_multimodal toneAmber
class node_index_base,node_local_index,node_hybrid_index,node_pinecone_index,node_postgres_index,node_qdrant_index toneMint
class node_llm_base,node_llm_providers,node_function_call toneRose
class node_schema,node_defaults toneIndigo
```

## Components

### Routing

- [Route definitions](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/route.py): `semantic_router/route.py`
- [Semantic router](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/routers/semantic.py): `semantic_router/routers/semantic.py`
- [Router core](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/routers/base.py): `semantic_router/routers/base.py`
- [Hybrid router](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/routers/hybrid.py): `semantic_router/routers/hybrid.py`
- [Threshold optimization](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/linear.py): `semantic_router/linear.py`

### Encoding

- [Encoder interfaces](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/encoders/base.py): `semantic_router/encoders/base.py`
- [Encoder input types](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/encoders/encode_input_type.py): `semantic_router/encoders/encode_input_type.py`
- [Encoder providers](https://github.com/aurelio-labs/semantic-router/tree/main/semantic_router/encoders): `semantic_router/encoders`
- [Multimodal encoding](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/encoders/clip.py): `semantic_router/encoders/clip.py`

### Indexes

- [Index interface](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/base.py): `semantic_router/index/base.py`
- [Local index](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/local.py): `semantic_router/index/local.py`
- [Hybrid local index](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/hybrid_local.py): `semantic_router/index/hybrid_local.py`
- [Pinecone index](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/pinecone.py): `semantic_router/index/pinecone.py`
- [Postgres index](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/postgres.py): `semantic_router/index/postgres.py`
- [Qdrant index](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/index/qdrant.py): `semantic_router/index/qdrant.py`

### LLM and calls

- [LLM interface](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/llms/base.py): `semantic_router/llms/base.py`
- [LLM providers](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/llms/openai.py): `semantic_router/llms/openai.py`
- [Function extraction](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/utils/function_call.py): `semantic_router/utils/function_call.py`

### Shared models

- [Route and index schemas](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/schema.py): `semantic_router/schema.py`
- [Model defaults](https://github.com/aurelio-labs/semantic-router/blob/main/semantic_router/utils/defaults.py): `semantic_router/utils/defaults.py`

### Other components

- **User query**

## Connections

- User query → Semantic router: submits query
- Route definitions → Semantic router: configures routes (evidence: `semantic_router/routers/semantic.py`)
- Semantic router → Router core: builds on (evidence: `semantic_router/routers/semantic.py`)
- Router core → Route definitions: calls route (evidence: `semantic_router/routers/base.py`)
- Route definitions → LLM interface: extracts inputs (evidence: `semantic_router/route.py`)
- Route definitions → Function extraction: uses helpers (evidence: `semantic_router/route.py`)
- Semantic router → Encoder interfaces: uses encoder (evidence: `semantic_router/routers/semantic.py`)
- Router core → Index interface: uses index (evidence: `semantic_router/routers/base.py`)
- Hybrid router → Hybrid local index: queries index (evidence: `semantic_router/routers/hybrid.py`)
- Hybrid router → Encoder interfaces: encodes query (evidence: `semantic_router/routers/hybrid.py`)
- Encoder providers → Encoder interfaces: implements interface (evidence: `semantic_router/encoders/litellm.py`)
- Multimodal encoding → Encoder interfaces: provides encoding
- Semantic router → Local index: supports local sync
- Semantic router → Pinecone index: supports integration
- Semantic router → Qdrant index: supports integration
- Index interface → Route and index schemas: uses metadata (evidence: `semantic_router/index/base.py`)
- Router core → Route and index schemas: builds config (evidence: `semantic_router/routers/base.py`)
- LLM providers → LLM interface: implements interface (evidence: `semantic_router/llms/openai.py`)
- Encoder providers → Model defaults: reads defaults (evidence: `semantic_router/encoders/openai.py`)
- Threshold optimization → Semantic router: optimizes thresholds
- Route definitions → LLM providers: dynamic generation