ann_router.api module

FastAPI HTTP surface — the web-API door (optional [api] extra).

The third of ann-router’s five surfaces exposes the router over HTTP so a service can ask “which backend for this problem?” (and benchmark/inspect backends) without a Python import. FastAPI + uvicorn live behind the [api] extra, imported lazily here so the core package never pays for a web stack it does not use — the same quarantine os-helper applies to its GUI. Every endpoint delegates to ann_router._core_cli, so the HTTP behaviour matches the CLI and library exactly.

Each route carries an explicit operation_id (route/capabilities/ bench) — not just OpenAPI hygiene: ann_router.mcp_server mounts fastapi-mcp on a copy of this same app and selects exactly these operation ids as the exposed MCP tools, so the id is the tool name an agent calls. Rename a route here and the MCP door renames with it, automatically.

Run it with:

pip install 'ann-router[api]'
uvicorn ann_router.api:app --reload   # or: python -m ann_router.api

Consumes: fastapi (optional), ann_router._core_cli. Produces: app (the ASGI application), create_app().

Author: Warith Harchaoui <warith.harchaoui@deraison.ai>

class ann_router.api.CriteriaModel(*, n_vectors, dim, target_recall=0.95, latency_budget_ms=10.0, memory_budget_gb=None, dynamic=False, metadata_filtering=False, hardware='cpu', persistence=False, batch_queries=False, metric='cosine', extra={})[source]

Bases: BaseModel

Request body mirroring ann_router.spec.Criteria.

Only n_vectors and dim are required; the rest carry the same house defaults as the dataclass so a minimal request still routes.

Parameters:

n_vectors (int)
dim (int)
target_recall (float)
latency_budget_ms (float)
memory_budget_gb (float | None)
dynamic (bool)
metadata_filtering (bool)
hardware (str)
persistence (bool)
batch_queries (bool)
metric (str)
extra (dict[str, Any])

batch_queries: bool

dim: int

dynamic: bool

extra: dict[str, Any]

hardware: str

latency_budget_ms: float

memory_budget_gb: float | None

metadata_filtering: bool

metric: str

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_vectors: int

persistence: bool

target_recall: float

ann_router.api.create_app()[source]

Build and return the FastAPI application.

Returns:: The ASGI app with the /route, /capabilities and /bench routes wired to the shared core.
Return type:: FastAPI

Examples

>>> app = create_app()
>>> [r.path for r in app.routes]
['/openapi.json', '/docs', ..., '/route', '/capabilities', '/bench']