Class QueryClassifier

Chain-of-thought LLM classifier that determines retrieval depth (T0-T3) and retrieval strategy (none/simple/moderate/complex) for each incoming query.

The strategy field controls whether HyDE (Hypothetical Document Embedding) is engaged during retrieval and at what depth.

Example

const classifier = new QueryClassifier({
  model: 'gpt-4o-mini',
  provider: 'openai',
  confidenceThreshold: 0.7,
  maxTier: 3,
  topicList: 'Auth (docs/auth.md)\nDB (docs/db.md)',
  toolList: 'search_code, read_file',
});

const result = await classifier.classify('How does auth work?');
console.log(result.tier);     // 1
console.log(result.strategy); // 'moderate'

Constructors

constructor

Methods

setCapabilityDiscoveryEngine getCapabilityDiscoveryEngine classify classifyWithPlan

Constructors

constructor

Methods

setCapabilityDiscoveryEngine

  • setCapabilityDiscoveryEngine(engine): void

  • Attach a CapabilityDiscoveryEngine for Tier 0 capability summaries.

    When attached, the plan-aware classifier (classifyWithPlan) injects category-level summaries of all available skills, tools, and extensions into the LLM prompt. This allows the LLM to recommend capability activations alongside the retrieval plan, without loading full schemas.

    Parameters

    • engine: null | CapabilityDiscoveryEngine

      A configured and initialized CapabilityDiscoveryEngine, or null to detach.

    Returns void

    Example

    const engine = new CapabilityDiscoveryEngine(embeddingManager, vectorStore);
    await engine.initialize({ tools, skills, extensions, channels });
    classifier.setCapabilityDiscoveryEngine(engine);

getCapabilityDiscoveryEngine

  • getCapabilityDiscoveryEngine(): null | CapabilityDiscoveryEngine

  • Get the attached CapabilityDiscoveryEngine, if any.

    Returns null | CapabilityDiscoveryEngine

    The discovery engine instance, or null if not configured.

classify

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

  • Classifies a user query into a retrieval tier and strategy.

    Steps:

    1. Builds a chain-of-thought system prompt with tier definitions, strategy definitions, topic list, tool list, and optional conversation context.
    2. Calls the LLM via generateText.
    3. Parses the JSON response (handling optional markdown code fences).
    4. Validates and normalises the strategy field (falls back to tier-inferred).
    5. Applies confidence-based tier bumping: if confidence < threshold, tier += 1.
    6. Caps the tier at the configured maxTier.
    7. On ANY error, returns a safe T1/simple fallback with confidence 0.

    Parameters

    • query: string

      The user's query text to classify.

    • Optional conversationHistory: ConversationMessage[]

      Optional recent conversation messages for context.

    • Optional _options: QueryRouterRequestOptions

    Returns Promise<ClassificationResult>

    A ClassificationResult with tier, strategy, confidence, reasoning, and metadata.

classifyWithPlan

  • classifyWithPlan(query, conversationHistory?, options?): Promise<[ClassificationResult, ExecutionPlan]>

  • Classifies a query and produces a full ExecutionPlan.

    This is an enhanced alternative to classify that evaluates more dimensions (source selection, memory relevance, modality, temporal preferences, decomposability, capability recommendations) and outputs a structured plan that the UnifiedRetriever can execute directly, along with skill/tool/extension recommendations for the agent runtime.

    When a CapabilityDiscoveryEngine is attached (via setCapabilityDiscoveryEngine), the LLM prompt includes Tier 0 summaries (~150 tokens) of all available capabilities, enabling the LLM to recommend specific skills, tools, and extensions.

    Falls back to buildDefaultExecutionPlan with heuristic capability selection when classification fails or the LLM response is malformed.

    Parameters

    • query: string

      The user's query text to classify.

    • Optional conversationHistory: ConversationMessage[]

      Optional recent conversation messages for context.

    • Optional options: QueryRouterRequestOptions

    Returns Promise<[ClassificationResult, ExecutionPlan]>

    A tuple of [ClassificationResult, ExecutionPlan].

    Example

    const [classification, plan] = await classifier.classifyWithPlan(
      'Search the web for recent AI news and summarize findings',
    );
    // plan.skills → [{ skillId: 'web-search', ... }]
    // plan.tools → []
    const result = await unifiedRetriever.retrieve(query, plan);

    See

    • classify for the simpler tier+strategy classification
    • buildDefaultExecutionPlan for execution plan defaults per strategy level

Settings

Member Visibility

Theme

On This Page

constructorsetCapabilityDiscoveryEnginegetCapabilityDiscoveryEngineclassifyclassifyWithPlan