master-assistant-query-routing 0.2.0

Corpus-coupled, drift-free routing for multi-collection RAG.

Master Assistant Query Routing (MAA)

Drift-free query routing for multi-collection RAG via parallel corpus probing.

Given a natural-language query, MAA decides which document collection(s) it belongs to — by probing every configured vector-store collection in parallel, scoring each from the actual retrieved chunks, and asking a routing LLM to read those chunks and return a structured JSON decision. The routing signal is the live corpus itself, so re-indexing your data updates routing automatically — there is no description or utterance list to keep in sync.

Paper: https://doi.org/10.5281/zenodo.20348330

Install

# everything — all providers (Gemini, OpenAI, Anthropic, Ollama) + Qdrant
pip install "master-assistant-query-routing[all]"

# or install only what you need
pip install "master-assistant-query-routing[openai,qdrant]"

Usage

import asyncio
from maa import route_query, Config
from maa.providers.openai import OpenAIEmbedder, OpenAIRoutingLLM
from maa.stores.qdrant import QdrantVectorStore

async def main():
    embedder = OpenAIEmbedder(api_key="sk-...", model="text-embedding-3-large")
    llm      = OpenAIRoutingLLM(api_key="sk-...", model="gpt-5.4-mini")
    store    = QdrantVectorStore(host="localhost", port=6333)

    cfg = Config(collections=["billing", "technical", "accounts"])

    result = await route_query(
        "why was I charged twice this month",
        cfg, embedder=embedder, llm=llm, store=store,
    )
    print(result["collections"])   # e.g. ['billing']

asyncio.run(main())

Returns a dict with collections (the routing decision), analysis (per-collection confidence + evidence), and reasoning. Pass verbose=True to also include the raw probe scores and retrieved chunks.

License

Apache-2.0.