Server

This section contains auto-generated documentation for the server module.

Serve Module

async routir.serve.startup()

Initialize resources before the server starts.

async routir.serve.process_query()

Retrieve ranked documents for a query.

Request (JSON):

{
    "service": "my-retriever",
    "query":   "what is machine learning?",
    "limit":   20
}

service (required) selects the registered search service. All other fields are forwarded to the processor as-is; common extra fields include limit and subset.

Response (200 OK):

{
    "scores":    {"doc1": 12.3, "doc2": 9.8},
    "cached":    false,
    "timestamp": 1700000000.0
}

Returns 400 for missing data or unknown service; 500 for engine errors.

async routir.serve.process_scoring()

Score query-passage pairs (reranking).

Request (JSON):

{
    "service":  "my-reranker",
    "query":    "what is machine learning?",
    "passages": ["ML is a subset of AI", "Pizza is popular in Italy"]
}

passages is a flat list of text strings to score against the query.

Response (200 OK):

{
    "scores":    [0.95, 0.02],
    "cached":    false,
    "timestamp": 1700000000.0
}

scores is a list of floats in the same order as passages.

Returns 400 for missing data or unknown service; 500 for engine errors.

async routir.serve.process_get_content()

Retrieve document text by ID from a registered collection.

Request (JSON):

{
    "collection": "my-corpus",
    "id":         "doc_42"
}

Response (200 OK):

{
    "collection": "my-corpus",
    "id":         "doc_42",
    "text":       "Full document text here…"
}

Returns 400 for missing id, unknown collection, or lookup failure; 500 for unexpected errors.

async routir.serve.process_pipeline()

Execute a multi-stage pipeline defined by the pipeline DSL.

Request (JSON):

{
    "pipeline":       "bm25%100 >> my-reranker%20",
    "collection":     "my-corpus",
    "query":          "what is machine learning?",
    "runtime_kwargs": {"bm25": {"subset": "en"}}
}

Required fields: pipeline, query. collection is required only when the pipeline contains a reranking stage (which needs document text).

pipeline is a DSL string; see routir.pipeline.parser for syntax. collection, when supplied, must be a registered content service. runtime_kwargs is optional and maps pipeline aliases to extra per-stage parameters.

Response (200 OK):

{
    "query":     "what is machine learning?",
    "scores":    {"doc1": 0.95, "doc2": 0.82},
    "cached":    false,
    "timestamp": 1700000000.0
}

expanded_queries is included when the pipeline contains a query decomposition stage.

Returns 400 for missing required fields or DSL/service errors; 500 for unexpected errors.

async routir.serve.health_check()

Simple health check endpoint.

async routir.serve.get_avail_service()

List all services registered with the server, grouped by type.

Response (200 OK):

{
    "search":           ["bm25", "dense"],
    "score":            ["cross-encoder", "kf-rerank"],
    "fuse":             ["rrf"],
    "decompose_query":  [],
    "collection": {
        "my-corpus": {
            "views":   {"asr": "text", "ocr": "text", "keyframe": "bytes"},
            "default": "asr"
        }
    },
    "score_view_kinds": {"cross-encoder": "text", "kf-rerank": "bytes"},
    "pipeline_aliases": {"ragtime2": "{zho%100, rus%100, ...}ScoreFusion"}
}

Used by auto_add_relay_services() to discover services on remote servers. The collection key carries per-collection view metadata (views map + default view).

routir.serve.main()

CLI entry point: parse arguments and start the Hypercorn ASGI server.

Usage:

routir config.json [--port 5000] [--host 0.0.0.0]

The startup timeout is 600 s to accommodate slow model loading.

Args (CLI):

config: Path to the JSON config file (required positional argument). –port: TCP port to listen on (default 5000). –host: Interface to bind (default 0.0.0.0 for all interfaces). –cache_dir: Directory for local cache files (default ./.cache). –api_key: Bearer token required on every request (except /ping).

When unset, the server accepts unauthenticated requests. Falls back to the ROUTIR_API_KEY env var, which is preferred since CLI arguments are visible in process listings.

–grpc: When set, additionally start a gRPC server on the same event

loop. Off by default; the REST-only path is unchanged.

–grpc-port: TCP port for the gRPC server (default 50051). –grpc-max-message-mb: Cap on inbound and outbound gRPC message size

in megabytes (default 64).

–allow-tar-gz-decompress-cache: Directory into which any .tar.gz

tar_template references in the config should be decompressed once at startup. Without this flag, .tar.gz references raise at startup (random-access on compressed tar requires indexed_gzip, which is not yet wired into the runtime path).