Skip to main content

Class: QueryRouter

Defined in: packages/agentos/src/query-router/QueryRouter.ts:120

Main orchestrator that wires together the QueryClassifier, QueryDispatcher, and QueryGenerator into a complete classify -> dispatch -> generate pipeline.

Example​

const router = new QueryRouter({
  knowledgeCorpus: ['./docs'],
  generationModel: 'gpt-4o-mini',
  generationModelDeep: 'gpt-4o',
  generationProvider: 'openai',
});

await router.init();
const result = await router.route('How does authentication work?');
console.log(result.answer);
console.log(result.sources);

await router.close();

Constructors​

Constructor​

new QueryRouter(config): QueryRouter

Defined in: packages/agentos/src/query-router/QueryRouter.ts:174

Creates a new QueryRouter instance.

Merges user-supplied configuration over QUERY_ROUTER_DEFAULTS. The router is NOT ready to use until init is called.

Parameters​

config​

QueryRouterConfig

Partial configuration; knowledgeCorpus is required.

Returns​

QueryRouter

Methods​

classify()​

classify(query, conversationHistory?): Promise<ClassificationResult>

Defined in: packages/agentos/src/query-router/QueryRouter.ts:376

Classify a query into a complexity tier without dispatching or generating.

Useful when consumers want to inspect the classification before deciding whether to proceed with the full pipeline.

Parameters​

query​

string

The user's natural-language query.

conversationHistory?​

ConversationMessage[]

Optional recent conversation messages.

Returns​

Promise<ClassificationResult>

The classification result with tier, confidence, and reasoning.

Throws​

If the router has not been initialised via init.

close()​

close(): Promise<void>

Defined in: packages/agentos/src/query-router/QueryRouter.ts:535

Tear down resources and release references.

Shuts down embedding and vector store managers if they were initialised, then nulls out all component references. Safe to call multiple times. After close(), the router must be re-initialised via init before further use.

Returns​

Promise<void>

getCorpusStats()​

getCorpusStats(): QueryRouterCorpusStats

Defined in: packages/agentos/src/query-router/QueryRouter.ts:574

Return lightweight corpus/index stats for observability and host startup logs.

Useful after init so callers can confirm the router loaded a real corpus instead of only knowing that initialisation completed.

Returns​

QueryRouterCorpusStats

init()​

init(): Promise<void>

Defined in: packages/agentos/src/query-router/QueryRouter.ts:199

Initialise the router: load corpus from disk, extract topics, build keyword fallback index, embed the corpus into a vector store, and instantiate classifier/dispatcher/generator.

Must be called before classify(), retrieve(), or route().

The embedding step uses real EmbeddingManager + VectorStoreManager when an LLM provider is available (e.g., OPENAI_API_KEY is set). If embedding initialisation fails for any reason, the router falls back gracefully to KeywordFallback for all retrieval.

Returns​

Promise<void>

retrieve()​

retrieve(query, tier): Promise<RetrievalResult>

Defined in: packages/agentos/src/query-router/QueryRouter.ts:424

Retrieve context at a specific tier, bypassing the classifier.

Useful when the caller already knows the appropriate retrieval depth and wants to skip classification overhead.

Parameters​

query​

string

The user's natural-language query.

tier​

QueryTier

The complexity tier to retrieve at (0-3).

Returns​

Promise<RetrievalResult>

The retrieval result with chunks and optional graph/research data.

Throws​

If the router has not been initialised via init.

route()​

route(query, conversationHistory?): Promise<QueryRouterResult>

Defined in: packages/agentos/src/query-router/QueryRouter.ts:443

Full end-to-end pipeline: classify -> dispatch -> generate.

This is the primary method for answering user queries. It:

  1. Classifies the query to determine retrieval depth.
  2. Dispatches retrieval at the classified tier.
  3. Generates a grounded answer from the retrieved context.
  4. Emits lifecycle events throughout for observability.

Parameters​

query​

string

The user's natural-language query.

conversationHistory?​

ConversationMessage[]

Optional recent conversation messages.

Returns​

Promise<QueryRouterResult>

The final query result with answer, classification, sources, and timing.

Throws​

If the router has not been initialised via init.