Interface QueryRouterConfig

Public constructor configuration for the QueryRouter pipeline.

knowledgeCorpus is required. All other fields are optional and default to the values in DEFAULT_QUERY_ROUTER_CONFIG.

Example

const router = new QueryRouter({
  knowledgeCorpus: ['./docs', './packages/agentos/docs'],
  availableTools: ['web_search', 'deep_research'],
  maxTier: 3,
});
interface QueryRouterConfig {
    knowledgeCorpus: string[];
    confidenceThreshold?: number;
    classifierModel?: string;
    classifierProvider?: string;
    maxTier?: QueryTier;
    embeddingProvider?: string;
    embeddingModel?: string;
    generationModel?: string;
    generationModelDeep?: string;
    generationProvider?: string;
    graphEnabled?: boolean;
    deepResearchEnabled?: boolean;
    conversationWindowSize?: number;
    maxContextTokens?: number;
    cacheResults?: boolean;
    availableTools?: string[];
    graphExpand?: ((seedChunks) => Promise<RetrievedChunk[]>);
    rerank?: ((query, chunks, topN) => Promise<RetrievedChunk[]>);
    verifyCitations?: boolean;
    deepResearch?: ((query, sources) => Promise<{
        synthesis: string;
        sources: RetrievedChunk[];
    }>);
    onClassification?: ((result) => void);
    onRetrieval?: ((result) => void);
    apiKey?: string;
    baseUrl?: string;
    embeddingApiKey?: string;
    embeddingBaseUrl?: string;
    githubRepos?: RepoIndexConfig;
    strategyConfig?: QueryRouterStrategyConfig;
    includePlatformKnowledge?: boolean;
}

Properties

knowledgeCorpus confidenceThreshold? classifierModel? classifierProvider? maxTier? embeddingProvider? embeddingModel? generationModel? generationModelDeep? generationProvider? graphEnabled? deepResearchEnabled? conversationWindowSize? maxContextTokens? cacheResults? availableTools? graphExpand? rerank? verifyCitations? deepResearch? onClassification? onRetrieval? apiKey? baseUrl? embeddingApiKey? embeddingBaseUrl? githubRepos? strategyConfig? includePlatformKnowledge?

Properties

knowledgeCorpus

knowledgeCorpus: string[]

Directories containing .md / .mdx files to ingest as the knowledge corpus.

init() will throw if these paths resolve to zero readable markdown sections, because a successful router init should imply a non-empty corpus.

Optional confidenceThreshold

confidenceThreshold?: number

Minimum confidence threshold for accepting a classification result. If confidence falls below this, the router may escalate to a higher tier.

Default

0.7

Optional classifierModel

classifierModel?: string

LLM model for the classifier.

Default

'gpt-4o-mini'

Optional classifierProvider

classifierProvider?: string

LLM provider for the classifier.

Default

'openai'

Optional maxTier

maxTier?: QueryTier

Maximum tier the classifier may assign.

Default

3

Optional embeddingProvider

embeddingProvider?: string

Embedding provider name.

Default

'openai'

Optional embeddingModel

embeddingModel?: string

Embedding model identifier.

Default

'text-embedding-3-small'

Optional generationModel

generationModel?: string

LLM model for T0/T1 generation.

Default

'gpt-4o-mini'

Optional generationModelDeep

generationModelDeep?: string

LLM model for T2/T3 generation (deep).

Default

'gpt-4o'

Optional generationProvider

generationProvider?: string

LLM provider for generation.

Default

'openai'

Optional graphEnabled

graphEnabled?: boolean

Whether to enable GraphRAG-based retrieval for tier >= 2 queries. Requires a configured GraphRAG engine.

Default

true

Optional deepResearchEnabled

deepResearchEnabled?: boolean

Whether to enable deep research mode for tier 3 queries. Research mode performs iterative multi-pass retrieval and synthesis.

Default

true

Optional conversationWindowSize

conversationWindowSize?: number

Number of recent conversation messages to include as context for classification and generation.

Default

5

Optional maxContextTokens

maxContextTokens?: number

Maximum estimated tokens to allocate for documentation context.

Default

4000

Optional cacheResults

cacheResults?: boolean

Whether to cache query results.

Default

true

Optional availableTools

availableTools?: string[]

Optional tool/capability names exposed to the classifier prompt so it can reason about what the runtime can actually do.

Default

[]

Optional graphExpand

graphExpand?: ((seedChunks) => Promise<RetrievedChunk[]>)

Optional host-provided graph expansion callback.

Provide this to replace the built-in placeholder graphExpand() branch with a real GraphRAG or relationship-expansion implementation.

Type declaration

Optional rerank

rerank?: ((query, chunks, topN) => Promise<RetrievedChunk[]>)

Optional host-provided reranker callback.

Provide this to replace the built-in lexical heuristic reranker with a provider-backed or cross-encoder reranker.

Type declaration

Optional verifyCitations

verifyCitations?: boolean

Enable automatic citation verification on deep research responses. When true, moderate-depth queries also verify citations. Default: false (only deep research verifies automatically).

Optional deepResearch

deepResearch?: ((query, sources) => Promise<{
    synthesis: string;
    sources: RetrievedChunk[];
}>)

Optional host-provided deep research callback.

Provide this to replace the built-in placeholder research branch with a real multi-source research runtime. The sources argument receives normalized research-source hints such as web, docs, or media, not raw classifier retrieval labels.

Type declaration

    • (query, sources): Promise<{
          synthesis: string;
          sources: RetrievedChunk[];
      }>

    • Parameters

      • query: string
      • sources: string[]

      Returns Promise<{
          synthesis: string;
          sources: RetrievedChunk[];
      }>

Optional onClassification

onClassification?: ((result) => void)

Hook called after classification completes. Receives the ClassificationResult for consumer integration.

Type declaration

Optional onRetrieval

onRetrieval?: ((result) => void)

Hook called after retrieval completes. Receives the RetrievalResult for consumer integration.

Type declaration

Optional apiKey

apiKey?: string

Optional API key override for classifier and generator LLM calls.

When omitted, QueryRouter prefers OPENAI_API_KEY and falls back to OPENROUTER_API_KEY with the OpenRouter compatibility base URL.

Optional baseUrl

baseUrl?: string

Optional base URL override for classifier and generator LLM providers.

When omitted, QueryRouter auto-selects the OpenRouter compatibility URL only when OPENROUTER_API_KEY is being used implicitly.

Optional embeddingApiKey

embeddingApiKey?: string

Optional API key override for embeddings only.

When omitted, embeddings fall back to apiKey, then OPENAI_API_KEY, then OPENROUTER_API_KEY. This is useful when generation uses an OpenAI-compatible endpoint like OpenRouter but embeddings should stay on a direct OpenAI key.

Optional embeddingBaseUrl

embeddingBaseUrl?: string

Optional base URL override for embeddings only.

When omitted, embeddings inherit baseUrl unless embeddingApiKey is explicitly set, in which case the embedding path assumes the provider's default endpoint. If neither override is set and QueryRouter falls back to OPENROUTER_API_KEY, it automatically uses the OpenRouter compatibility URL for embeddings as well.

Optional githubRepos

githubRepos?: RepoIndexConfig

Configuration for background GitHub repository indexing.

When provided, the router will asynchronously index GitHub repos after init() completes and merge the resulting chunks into the corpus.

Optional strategyConfig

strategyConfig?: QueryRouterStrategyConfig

Retrieval strategy configuration for the HyDE-aware query router.

Controls how the classifier selects between none, simple, moderate (HyDE), and complex (HyDE + decompose) retrieval strategies.

See

QueryRouterStrategyConfig

Optional includePlatformKnowledge

includePlatformKnowledge?: boolean

Load bundled platform knowledge (tools, skills, FAQ, API reference, troubleshooting) into the corpus during init().

When enabled, the router ships with instant knowledge about every AgentOS capability — no external docs required for platform questions.

Default

true

Settings

Member Visibility

Theme

On This Page

knowledgeCorpusconfidenceThresholdclassifierModelclassifierProvidermaxTierembeddingProviderembeddingModelgenerationModelgenerationModelDeepgenerationProvidergraphEnableddeepResearchEnabledconversationWindowSizemaxContextTokenscacheResultsavailableToolsgraphExpandrerankverifyCitationsdeepResearchonClassificationonRetrievalapiKeybaseUrlembeddingApiKeyembeddingBaseUrlgithubReposstrategyConfigincludePlatformKnowledge