ann_router.router module

The router — measure criteria, select an available backend, justify it.

This is the recommend.py analogue: it takes a Criteria, consults the pure policy (policy.rank_backends), applies availability (a policy pick whose dependency is missing is skipped, with the fallback explained), attaches recommended build parameters, and returns a fully discussable BackendChoice. A convenience auto_index() closes the loop: route -> instantiate -> build.

The contract mirrors the sibling router’s promise — the answer is never just a name, it is a name plus the criteria that drove it plus the alternatives that were considered, so a human can audit or override it.

Consumes: ann_router.policy, ann_router.registry, ann_router.spec, os_helper (logging). Produces: route(), auto_index(), to_markdown().

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

ann_router.router.auto_index(vectors, criteria, ids=None, thresholds=None)[source]

Route the criteria, instantiate the winning backend, and build the index.

Parameters:

  • vectors (numpy.ndarray) – Corpus of shape (n, dim).

  • criteria (Criteria) – The problem description. If its n_vectors/dim disagree with vectors the array wins (the criteria are advisory for routing).

  • ids (numpy.ndarray, optional) – Explicit ids of shape (n,); defaults to range(n).

  • thresholds (dict, optional) – Policy threshold overrides.

Returns:

  • index (ANNIndex) – A built, queryable index of the chosen backend.

  • choice (BackendChoice) – The routing decision (so the caller can inspect/log the rationale).

Return type:

tuple[ANNIndex, BackendChoice]

Examples

>>> rng = np.random.default_rng(0)
>>> vecs = rng.standard_normal((500, 32)).astype(np.float32)
>>> idx, choice = auto_index(vecs, Criteria(n_vectors=500, dim=32))
>>> choice.backend
'exact'
>>> ids, dists = idx.search(vecs[:1], k=5)
>>> ids.shape
(1, 5)
ann_router.router.route(c, thresholds=None)[source]

Select an available backend for the criteria and justify the choice.

Parameters:

  • c (Criteria) – The measured problem description.

  • thresholds (dict, optional) – Overrides for the policy thresholds (tunable). See ann_router.policy.THRESHOLDS.

Returns:

The chosen backend, its rationale, recommended config, and the full considered shortlist (each entry flagged eligible/available/chosen).

Return type:

BackendChoice

Examples

>>> route(Criteria(n_vectors=500, dim=64)).backend
'exact'
>>> choice = route(Criteria(n_vectors=500_000, dim=768, metadata_filtering=True))
>>> choice.backend in {"qdrant", "pgvector", "hnsw", "exact", "turbovec"}
True
ann_router.router.to_markdown(choice)[source]

Render a routing decision as a human-readable Markdown report.

Parameters:

choice (BackendChoice) – A decision produced by route().

Returns:

Markdown with the pick, the rationale, and the considered table.

Return type:

str

Examples

>>> md = to_markdown(route(Criteria(n_vectors=500, dim=64)))
>>> md.splitlines()[0]
'# ann-router decision: `exact`'