Models

This section contains auto-generated documentation for all model classes in Routir.

Base Classes

class routir.models.abstract.Engine(name=None, config=None, **kwargs)

Bases: FactoryEnabled

Abstract class for all search and retrieval engines.

Provides a common interface for search, scoring, query decomposition, and result fusion operations. Subclasses should implement the specific batch operations they support.

name

Engine identifier

config

Engine configuration dictionary

index_path

Path to the search index (if applicable)

__init__(name=None, config=None, **kwargs)

Initialize the engine.

Parameters:

• name (str) – Optional name for the engine

• config (str | Path | Dict[str, Any]) – Configuration as dict, JSON file path, or JSON string

• **kwargs – Additional configuration parameters

async search_batch(queries, limit=20, **kwargs)

Perform batch search for multiple queries.

Parameters:

• queries (List[str]) – List of search queries

• limit (int | List[int]) – Maximum results per query (int for all, list for per-query limits)

• **kwargs – Additional search parameters

Returns:

List of dicts mapping document IDs to scores for each query

Return type:

List[Dict[str, float]]

async search(query, limit=20, **kwargs)

Perform single query search.

async score_batch(queries, passages, candidate_length=None, **kwargs)

Score query-passage pairs in batch.

Parameters:

• queries (List[str]) – List of queries

• passages (List[str]) – Flattened list of passages for all queries

• candidate_length (List[int]) – Number of passages per query

• **kwargs – Additional scoring parameters

Returns:

List of score lists for each query

Return type:

List[List[float]]

async score(query, passages, **kwargs)

Score a single query against multiple passages.

async decompose_query_batch(queries, limit=None, **kwargs)

Decompose queries into sub-queries.

Parameters:

• queries (List[str]) – List of queries to decompose

• limit (List[int]) – Optional limit on sub-queries per query

• **kwargs – Additional parameters

Returns:

List of sub-query lists for each query

Return type:

List[List[str]]

async decompose_query(query, **kwargs)

Decompose a single query into sub-queries.

async fuse_batch(queries, batch_scores, **kwargs)

Fuse multiple result sets per query.

Parameters:

• queries (List[str]) – List of queries

• batch_scores (List[List[Dict[str, float]]]) – List of result lists to fuse for each query

• **kwargs – Fusion parameters

Returns:

List of fused results for each query

Return type:

List[Dict[str, float]]

async fuse(query, scores, **kwargs)

Fuse multiple result sets for a single query.

property can_search: bool

Check if this engine implements search functionality.

property can_score: bool

Check if this engine implements scoring functionality.

property can_decompose_query: bool

Check if this engine implements query decomposition.

property can_fuse: bool

Check if this engine implements result fusion.

class routir.models.abstract.Reranker(name=None, config=None, **kwargs)

Bases: Engine

Abstract class for reranking engines.

Rerankers retrieve candidates from an upstream engine and rescore them. They require document text, either from a text service or other source.

This is a helper class for rerankers that provides supports to gather document text and perform the reranking process. If you do not need these functionalities, you can directly inherit from Engine.

upstream

Upstream retrieval engine for candidate generation

text_service

Configuration for retrieving document text

rerank_topk_max

Maximum candidates to rerank

rerank_multiplier

Factor to multiply requested limit for upstream retrieval

__init__(name=None, config=None, **kwargs)

Initialize the reranker.

Parameters:

• name – Reranker name

• config – Configuration dict or path

• **kwargs – Additional configuration

async get_text(docids)

Retrieve document text for the given document IDs.

Parameters:

docids (str | List[str]) – Single document ID or list of document IDs

Returns:

Dict mapping document IDs to their text content

Raises:

RuntimeError – If no text service is configured

async search_batch(queries, limit=20, **kwargs)

Helper method to perform reranking based on initial retrieval using upstream engine.

class routir.models.abstract.Aggregation(passage_mapping)

Bases: object

Maps passages to documents and aggregates passage scores to document scores.

Used for passage-level retrieval where results need to be aggregated to the document level using MaxP (maximum passage score).

mapping

Dict mapping passage IDs to document IDs

__init__(passage_mapping)

Initialize with passage-to-document mapping.

Parameters:

passage_mapping (Dict[str, str]) – Dict mapping passage IDs to document IDs

__contains__(pid)

Check if passage ID exists in mapping.

__getitem__(pid)

Get document ID for a passage ID.

maxp(passage_scores)

Aggregate passage scores to document scores using MaxP.

Takes the maximum score among all passages belonging to each document.

Parameters:

passage_scores (Dict[str, float]) – Dict mapping passage IDs to scores

Returns:

Dict mapping document IDs to their maximum passage scores

Return type:

Dict[str, float]

property n_docs

Get number of unique documents.

__len__()

Get number of passages.

PLAID-X (ColBERT)

routir.models.plaidx.colbert_all_pair_scores(Q, D, Dm=None)

class routir.models.plaidx.PLAIDX(name='PLAID-X', config=None, **kwargs)

Bases: Engine

PLAID-X engine for late-interaction dense retrieval using ColBERT.

Provides fast and effective neural retrieval with token-level interactions.

colbert_config

ColBERT configuration

searcher

ColBERT searcher instance

passage_mapper

Optional mapping for passage-to-document aggregation

subset_mapper

Optional mapping of document IDs to subsets

inference_batch_size

Batch size for inference operations

__init__(name='PLAID-X', config=None, **kwargs)

Initialize PLAID-X engine.

Parameters:

• name (str) – Engine name

• config (str | Path | Dict[str, Any]) – Configuration with index_path, checkpoint, use_gpu, etc.

• **kwargs – Additional configuration

filter_subset(scores, only_subset=None)

async search_batch(queries, limit=20, subsets=None, maxp=True)

Perform batch search for multiple queries.

Parameters:

• queries (List[str]) – List of search queries

• limit (int | List[int]) – Maximum results per query (int for all, list for per-query limits)

• **kwargs – Additional search parameters

Returns:

List of dicts mapping document IDs to scores for each query

Return type:

List[Dict[str, float]]

async score_batch(queries, passages, candidate_length)

Score query-passage pairs in batch.

Parameters:

• queries (List[str]) – List of queries

• passages (List[str]) – Flattened list of passages for all queries

• candidate_length (List[int]) – Number of passages per query

• **kwargs – Additional scoring parameters

Returns:

List of score lists for each query

Return type:

List[List[float]]

LSR (SPLADE)

class routir.models.lsr.LSR(name='LSR', config=None, **kwargs)

Bases: Engine

Learned Sparse Retrieval engine using SPLADE model as the query encoder.

Performs sparse retrieval with learned term weights using Anserini indexes.

anserini

Anserini index interface

model

SPLADE model for query encoding

subset_mapper

Optional mapping of document IDs to subsets

__init__(name='LSR', config=None, **kwargs)

Initialize LSR engine.

Parameters:

• name (str) – Engine name

• config (str | Path | Dict[str, Any]) – Configuration with index_path, model_name, max_length, etc.

• **kwargs – Additional configuration

filter_subset(scores, only_subset=None)

async search_batch(queries, limit=20, subsets=None, maxp=True)

Perform batch search for multiple queries.

Parameters:

• queries (List[str]) – List of search queries

• limit (int | List[int]) – Maximum results per query (int for all, list for per-query limits)

• **kwargs – Additional search parameters

Returns:

List of dicts mapping document IDs to scores for each query

Return type:

List[Dict[str, float]]

mT5

class routir.models.mt5.MT5Reranker(name=None, config=None, **kwargs)

Bases: Reranker

mT5-based reranker for passage scoring.

Uses sequence-to-sequence T5 models fine-tuned for relevance scoring.

prompt

Template for formatting query-document pairs

model

T5 model instance

tokenizer

T5 tokenizer

q_max_length

Maximum query length

d_max_length

Maximum document length

batch_size

Batch size for inference

token_false_id

Token ID for “false” prediction

token_true_id

Token ID for “true” prediction

prompt = 'Query: {query} Document: {document} Relevant:'

__init__(name=None, config=None, **kwargs)

Initialize MT5 reranker.

Parameters:

• name – Reranker name

• config – Configuration with model_name_or_path, max_lengths, etc.

• **kwargs – Additional configuration

tokenize_pairs(batch)

forward(input_ids, attention_mask=None)

async score(queries, passages, candidate_length=None, with_progress=False, **kwargs)

Score a single query against multiple passages.

Qwen3

Relay

Fusion

class routir.models.fusion.Fusion(name=None, config=None, **kwargs)

Bases: Engine

Engine that fuses results from multiple upstream engines.

Retrieves results from multiple engines and combines them using a fusion method (RRF or score-based).

upstream

List of upstream engines

fusion_function

Function to use for fusion

fusion_args

Arguments for the fusion function

__init__(name=None, config=None, **kwargs)

Initialize fusion engine.

Parameters:

• name – Engine name

• config – Must contain ‘upstream_service’ list

• **kwargs – Additional configuration

async search_batch(queries, limit=20, **kwargs)

Perform batch search for multiple queries.

Parameters:

• queries – List of search queries

• limit – Maximum results per query (int for all, list for per-query limits)

• **kwargs – Additional search parameters

Returns:

List of dicts mapping document IDs to scores for each query

Return type:

List[Dict[str, float]]

class routir.models.fusion.RRF(name=None, config=None, **kwargs)

Bases: Engine

Reciprocal Rank Fusion engine for combining result lists.

async fuse_batch(queries, batch_rankings, **kwargs)

Fuse multiple rankings using RRF algorithm.

class routir.models.fusion.ScoreFusion(name=None, config=None, **kwargs)

Bases: Engine

Score-based fusion engine for combining result lists.

async fuse_batch(queries, batch_rankings, **kwargs)

Fuse multiple rankings by summing scores.

LLM Rerankers