routir CLAUDE.md

RoutIR — src/routir

RoutIR is an async search/retrieval service. It hosts retrieval models (dense, sparse, rerankers, fusion, query expanders) behind a uniform HTTP/gRPC API and lets you compose them into multi-stage pipelines with a small DSL. This file orients an agent who needs to add a new engine (a reranker, search engine, query expander, or fusion method).

For task-oriented walkthroughs — calling the client, standing up a local server that imports a master server, wrapping a bi-encoder or reranker via file_imports, and serving multi-view collections — see SKILL.md.

The one concept that matters: Engine

Everything pluggable is a subclass of Engine (src/routir/models/abstract.py). An engine declares its capabilities simply by which methods it overrides — there is no registration boilerplate, no capability flag to set. The base class auto-detects capabilities by checking whether you overrode the *_batch method:

Override this method	Capability (can_*)	Pipeline role	Service type registered
search_batch	can_search	search	search
score_batch	can_score	rerank	score
decompose_query_batch	can_decompose_query	expander	decompose_query
fuse_batch	can_fuse	merger	fuse

(The role→service-type map lives in src/routir/pipeline/pipeline.py as _role_to_service.)

A single engine may implement several of these. SentenceTransformerEngine implements both search_batch and score_batch, for example. Implement only the methods that apply; the rest raise NotImplementedError and the capability stays off.

*_batch is always the method to override. The singular convenience wrappers (search, score, decompose_query, fuse) just call the batch form with one item — don't override them. The exception is legacy code like MT5Reranker, which overrode score; prefer score_batch in new engines.