@framers/agentos 0.1.112 → 0.1.114

package/dist/query-router/KeywordFallback.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview KeywordFallback — simple keyword-matching search used as
+ * the degraded-mode fallback when the embedding API is unavailable.
+ * @module @framers/agentos/query-router/KeywordFallback
+ *
+ * When the vector store or embedding service is down, the QueryRouter
+ * activates this fallback to provide best-effort retrieval via plain
+ * keyword matching. It is intentionally simple: split query into words,
+ * filter stop words, score each corpus chunk by keyword hits (heading
+ * matches weighted higher than content matches), and return the top-K
+ * results sorted by score.
+ */
+import type { CorpusChunk, RetrievedChunk } from './types.js';
+/**
+ * Simple keyword-matching search over a corpus of chunks.
+ *
+ * Used as a degraded-mode fallback when the embedding API is unavailable.
+ * Splits the query into keywords, filters out stop words and short tokens,
+ * then scores each chunk by the number of keyword hits (heading matches
+ * receive a higher weight than content matches).
+ *
+ * @example
+ * ```typescript
+ * const fallback = new KeywordFallback(corpusChunks);
+ * const results = fallback.search('authentication tokens', 5);
+ * // results: RetrievedChunk[] sorted by relevance, at most 5 entries
+ * ```
+ */
+export declare class KeywordFallback {
+    /** The corpus chunks to search over. */
+    private readonly chunks;
+    /**
+     * Creates a new KeywordFallback instance.
+     * @param chunks - The corpus chunks to search over.
+     */
+    constructor(chunks: CorpusChunk[]);
+    /**
+     * Searches the corpus for chunks matching the given query keywords.
+     *
+     * Scoring algorithm:
+     * - Each keyword found in the chunk heading awards {@link HEADING_MATCH_SCORE} points.
+     * - Each keyword found in the chunk content awards {@link CONTENT_MATCH_SCORE} point.
+     * - Chunks with zero total score are excluded.
+     * - Scores are normalized to the 0-1 range (relative to the maximum observed score).
+     * - Results are sorted by score descending and sliced to topK.
+     *
+     * @param query - The user query string to match.
+     * @param topK - Maximum number of results to return. Defaults to 5.
+     * @returns Array of RetrievedChunk sorted by relevance, at most topK entries.
+     */
+    search(query: string, topK?: number): RetrievedChunk[];
+    /**
+     * Extracts meaningful keywords from a query string.
+     * Splits on whitespace, lowercases, and filters out stop words
+     * and tokens shorter than 3 characters.
+     *
+     * @param query - The raw query string.
+     * @returns Array of lowercase keyword strings.
+     */
+    private extractKeywords;
+    /**
+     * Scores a single chunk against the given keywords.
+     *
+     * @param chunk - The corpus chunk to score.
+     * @param keywords - The extracted query keywords (lowercase).
+     * @returns The raw score (sum of heading and content matches).
+     */
+    private scoreChunk;
+}
+//# sourceMappingURL=KeywordFallback.d.ts.map

package/dist/query-router/KeywordFallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeywordFallback.d.ts","sourceRoot":"","sources":["../../src/query-router/KeywordFallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAsB9D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAe;IAC1B,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC;;;OAGG;gBACS,MAAM,EAAE,WAAW,EAAE;IAIjC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,cAAc,EAAE;IA2CzD;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAOvB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;CAgBnB"}

package/dist/query-router/KeywordFallback.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview KeywordFallback — simple keyword-matching search used as
+ * the degraded-mode fallback when the embedding API is unavailable.
+ * @module @framers/agentos/query-router/KeywordFallback
+ *
+ * When the vector store or embedding service is down, the QueryRouter
+ * activates this fallback to provide best-effort retrieval via plain
+ * keyword matching. It is intentionally simple: split query into words,
+ * filter stop words, score each corpus chunk by keyword hits (heading
+ * matches weighted higher than content matches), and return the top-K
+ * results sorted by score.
+ */
+/**
+ * Common English stop words that add noise to keyword matching.
+ * Words shorter than 3 characters are also filtered out automatically.
+ */
+const STOP_WORDS = new Set([
+    'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'can', 'has',
+    'her', 'was', 'one', 'our', 'out', 'had', 'hot', 'how', 'its', 'let',
+    'may', 'who', 'did', 'get', 'got', 'him', 'his', 'she', 'too', 'use',
+    'that', 'with', 'have', 'this', 'will', 'your', 'from', 'they', 'been',
+    'than', 'them', 'then', 'what', 'when', 'were', 'which', 'their', 'there',
+    'these', 'those', 'would', 'about', 'could', 'other', 'into', 'more',
+    'some', 'such', 'only', 'also', 'just', 'does', 'each', 'very',
+]);
+/** Points awarded for a keyword match in the chunk heading. */
+const HEADING_MATCH_SCORE = 4;
+/** Points awarded for a keyword match in the chunk content. */
+const CONTENT_MATCH_SCORE = 1;
+/**
+ * Simple keyword-matching search over a corpus of chunks.
+ *
+ * Used as a degraded-mode fallback when the embedding API is unavailable.
+ * Splits the query into keywords, filters out stop words and short tokens,
+ * then scores each chunk by the number of keyword hits (heading matches
+ * receive a higher weight than content matches).
+ *
+ * @example
+ * ```typescript
+ * const fallback = new KeywordFallback(corpusChunks);
+ * const results = fallback.search('authentication tokens', 5);
+ * // results: RetrievedChunk[] sorted by relevance, at most 5 entries
+ * ```
+ */
+export class KeywordFallback {
+    /**
+     * Creates a new KeywordFallback instance.
+     * @param chunks - The corpus chunks to search over.
+     */
+    constructor(chunks) {
+        this.chunks = chunks;
+    }
+    /**
+     * Searches the corpus for chunks matching the given query keywords.
+     *
+     * Scoring algorithm:
+     * - Each keyword found in the chunk heading awards {@link HEADING_MATCH_SCORE} points.
+     * - Each keyword found in the chunk content awards {@link CONTENT_MATCH_SCORE} point.
+     * - Chunks with zero total score are excluded.
+     * - Scores are normalized to the 0-1 range (relative to the maximum observed score).
+     * - Results are sorted by score descending and sliced to topK.
+     *
+     * @param query - The user query string to match.
+     * @param topK - Maximum number of results to return. Defaults to 5.
+     * @returns Array of RetrievedChunk sorted by relevance, at most topK entries.
+     */
+    search(query, topK = 5) {
+        const keywords = this.extractKeywords(query);
+        if (keywords.length === 0) {
+            return [];
+        }
+        const scored = [];
+        for (const chunk of this.chunks) {
+            const rawScore = this.scoreChunk(chunk, keywords);
+            if (rawScore > 0) {
+                scored.push({ chunk, rawScore });
+            }
+        }
+        if (scored.length === 0) {
+            return [];
+        }
+        // Sort by raw score descending
+        scored.sort((a, b) => b.rawScore - a.rawScore);
+        // Find the maximum score for normalization
+        const maxScore = scored[0].rawScore;
+        // Slice to topK and map to RetrievedChunk
+        return scored.slice(0, topK).map(({ chunk, rawScore }) => ({
+            id: chunk.id,
+            content: chunk.content,
+            heading: chunk.heading,
+            sourcePath: chunk.sourcePath,
+            relevanceScore: maxScore > 0 ? rawScore / maxScore : 0,
+            matchType: 'vector',
+        }));
+    }
+    /**
+     * Extracts meaningful keywords from a query string.
+     * Splits on whitespace, lowercases, and filters out stop words
+     * and tokens shorter than 3 characters.
+     *
+     * @param query - The raw query string.
+     * @returns Array of lowercase keyword strings.
+     */
+    extractKeywords(query) {
+        return query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((word) => word.length >= 3 && !STOP_WORDS.has(word));
+    }
+    /**
+     * Scores a single chunk against the given keywords.
+     *
+     * @param chunk - The corpus chunk to score.
+     * @param keywords - The extracted query keywords (lowercase).
+     * @returns The raw score (sum of heading and content matches).
+     */
+    scoreChunk(chunk, keywords) {
+        const headingLower = chunk.heading.toLowerCase();
+        const contentLower = chunk.content.toLowerCase();
+        let score = 0;
+        for (const keyword of keywords) {
+            if (headingLower.includes(keyword)) {
+                score += HEADING_MATCH_SCORE;
+            }
+            if (contentLower.includes(keyword)) {
+                score += CONTENT_MATCH_SCORE;
+            }
+        }
+        return score;
+    }
+}
+//# sourceMappingURL=KeywordFallback.js.map

package/dist/query-router/KeywordFallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeywordFallback.js","sourceRoot":"","sources":["../../src/query-router/KeywordFallback.ts"],"names":[],"mappings":"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"}

package/dist/query-router/QueryClassifier.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview QueryClassifier — chain-of-thought LLM classifier that
+ * determines the retrieval depth tier (T0-T3) for each incoming query.
+ *
+ * The classifier is the first stage of the QueryRouter pipeline. It examines
+ * the user's query (and optional conversation history) to decide how much
+ * retrieval effort is needed:
+ *
+ * - **T0 (Trivial)**: No retrieval — answer from internal knowledge or context.
+ * - **T1 (Simple lookup)**: Single-source vector search.
+ * - **T2 (Multi-source)**: Cross-document retrieval + optional graph traversal.
+ * - **T3 (Research)**: Deep iterative research across the full corpus.
+ *
+ * The classifier calls an LLM with a chain-of-thought system prompt, parses
+ * the structured JSON response, and applies confidence-based tier bumping
+ * and maxTier capping before returning a {@link ClassificationResult}.
+ *
+ * On any failure (LLM error, JSON parse error), a safe T1 fallback is returned
+ * to ensure the pipeline never completely stalls.
+ *
+ * @module @framers/agentos/query-router/QueryClassifier
+ */
+import type { ClassificationResult, ConversationMessage, QueryTier } from './types.js';
+/**
+ * Configuration for the {@link QueryClassifier}.
+ *
+ * Controls model selection, confidence thresholds, tier limits, and the
+ * knowledge context (topic list, tool list) injected into the system prompt.
+ */
+export interface QueryClassifierConfig {
+    /** LLM model identifier (e.g. "gpt-4o-mini"). */
+    model: string;
+    /** LLM provider name (e.g. "openai", "anthropic"). */
+    provider: string;
+    /**
+     * Minimum confidence threshold for accepting a classification.
+     * If the LLM's confidence falls below this, the tier is bumped up by 1
+     * to request broader retrieval as a safety measure.
+     */
+    confidenceThreshold: number;
+    /** Maximum tier the classifier is allowed to assign. */
+    maxTier: QueryTier;
+    /**
+     * Newline-delimited list of known topics in the corpus.
+     * Injected into the system prompt via `{{TOPIC_LIST}}`.
+     */
+    topicList: string;
+    /**
+     * Comma-delimited list of available tools.
+     * Injected into the system prompt via `{{TOOL_LIST}}`.
+     */
+    toolList: string;
+    /** Optional API key override (otherwise resolved from environment). */
+    apiKey?: string;
+    /** Optional base URL override for the LLM provider. */
+    baseUrl?: string;
+}
+/**
+ * Chain-of-thought LLM classifier that determines retrieval depth (T0-T3)
+ * for each incoming query.
+ *
+ * @example
+ * ```ts
+ * 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
+ * ```
+ */
+export declare class QueryClassifier {
+    /** Immutable classifier configuration. */
+    private readonly config;
+    /**
+     * Creates a new QueryClassifier instance.
+     * @param config - Classifier configuration with model, provider, and thresholds.
+     */
+    constructor(config: QueryClassifierConfig);
+    /**
+     * Classifies a user query into a retrieval tier.
+     *
+     * Steps:
+     * 1. Builds a chain-of-thought system prompt with tier 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. Applies confidence-based tier bumping: if confidence < threshold, tier += 1.
+     * 5. Caps the tier at the configured `maxTier`.
+     * 6. On ANY error, returns a safe T1 fallback with confidence 0.
+     *
+     * @param query - The user's query text to classify.
+     * @param conversationHistory - Optional recent conversation messages for context.
+     * @returns A {@link ClassificationResult} with tier, confidence, reasoning, and metadata.
+     */
+    classify(query: string, conversationHistory?: ConversationMessage[]): Promise<ClassificationResult>;
+    /**
+     * Builds the system prompt by replacing template placeholders with actual
+     * topic list, tool list, and conversation context.
+     *
+     * @param conversationHistory - Optional conversation messages to include as context.
+     * @returns The fully rendered system prompt string.
+     */
+    private buildSystemPrompt;
+    /**
+     * Parses the LLM response text into a {@link ClassificationResult}.
+     *
+     * Handles two response formats:
+     * - Raw JSON object
+     * - JSON wrapped in markdown code fences (```json ... ```)
+     *
+     * @param text - Raw text from the LLM response.
+     * @returns A parsed {@link ClassificationResult}.
+     * @throws If the response cannot be parsed as valid JSON.
+     */
+    private parseResponse;
+    /**
+     * Applies post-classification constraints:
+     * 1. If confidence < threshold, bump tier by 1 (request broader retrieval).
+     * 2. Cap tier at the configured maxTier.
+     *
+     * @param result - The raw classification result from the LLM.
+     * @returns The constrained classification result.
+     */
+    private applyConstraints;
+    /**
+     * Returns a safe T1 fallback result when classification fails for any reason.
+     * T1 ensures at least a basic vector search is performed, which is a
+     * reasonable default when the classifier cannot determine the right tier.
+     *
+     * @returns A T1 {@link ClassificationResult} with confidence 0.
+     */
+    private fallbackResult;
+}
+//# sourceMappingURL=QueryClassifier.d.ts.map

package/dist/query-router/QueryClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryClassifier.d.ts","sourceRoot":"","sources":["../../src/query-router/QueryClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACV,MAAM,YAAY,CAAC;AAMpB;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IAEd,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAE5B,wDAAwD;IACxD,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAuED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAe;IAC1B,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAE/C;;;OAGG;gBACS,MAAM,EAAE,qBAAqB;IAIzC;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,GAC1C,OAAO,CAAC,oBAAoB,CAAC;IAyBhC;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IAmBrB;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAUvB"}

package/dist/query-router/QueryClassifier.js

@@ -0,0 +1,223 @@
+/**
+ * @fileoverview QueryClassifier — chain-of-thought LLM classifier that
+ * determines the retrieval depth tier (T0-T3) for each incoming query.
+ *
+ * The classifier is the first stage of the QueryRouter pipeline. It examines
+ * the user's query (and optional conversation history) to decide how much
+ * retrieval effort is needed:
+ *
+ * - **T0 (Trivial)**: No retrieval — answer from internal knowledge or context.
+ * - **T1 (Simple lookup)**: Single-source vector search.
+ * - **T2 (Multi-source)**: Cross-document retrieval + optional graph traversal.
+ * - **T3 (Research)**: Deep iterative research across the full corpus.
+ *
+ * The classifier calls an LLM with a chain-of-thought system prompt, parses
+ * the structured JSON response, and applies confidence-based tier bumping
+ * and maxTier capping before returning a {@link ClassificationResult}.
+ *
+ * On any failure (LLM error, JSON parse error), a safe T1 fallback is returned
+ * to ensure the pipeline never completely stalls.
+ *
+ * @module @framers/agentos/query-router/QueryClassifier
+ */
+import { generateText } from '../api/generateText.js';
+// ============================================================================
+// System Prompt Template
+// ============================================================================
+/**
+ * Chain-of-thought system prompt template for the query classifier.
+ *
+ * Placeholders:
+ * - `{{TOPIC_LIST}}` — known corpus topics
+ * - `{{TOOL_LIST}}` — available tools
+ * - `{{CONVERSATION_CONTEXT}}` — recent conversation history (may be empty)
+ */
+const SYSTEM_PROMPT_TEMPLATE = `You are a query complexity classifier. Your job is to analyze the user's query and determine how much retrieval effort is needed to answer it accurately.
+
+## Tier Definitions
+
+- **T0 (Trivial)**: Greetings, small talk, or questions answerable from general knowledge or the conversation context alone. No retrieval needed.
+- **T1 (Simple lookup)**: Questions about a specific fact, config value, or code snippet. A single vector search should suffice.
+- **T2 (Multi-source)**: Questions that span multiple documents or require combining information from different parts of the codebase. May need graph traversal.
+- **T3 (Research)**: Deep investigation questions that require iterative multi-pass retrieval, synthesis, and comparison across the entire corpus.
+
+## Known Topics
+{{TOPIC_LIST}}
+
+## Available Tools
+{{TOOL_LIST}}
+
+## Conversation Context
+{{CONVERSATION_CONTEXT}}
+
+## Instructions
+
+Think step-by-step about the query:
+1. What is the user actually asking?
+2. Can this be answered from general knowledge or conversation context alone?
+3. How many sources/documents would be needed?
+4. Are any tools required?
+
+Respond with ONLY a JSON object (no markdown fences, no extra text):
+{
+  "thinking": "<your step-by-step reasoning>",
+  "tier": <0|1|2|3>,
+  "confidence": <0.0 to 1.0>,
+  "internal_knowledge_sufficient": <true|false>,
+  "suggested_sources": [<"vector"|"graph"|"research">],
+  "tools_needed": [<tool names or empty>]
+}`;
+// ============================================================================
+// QueryClassifier
+// ============================================================================
+/**
+ * Chain-of-thought LLM classifier that determines retrieval depth (T0-T3)
+ * for each incoming query.
+ *
+ * @example
+ * ```ts
+ * 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
+ * ```
+ */
+export class QueryClassifier {
+    /**
+     * Creates a new QueryClassifier instance.
+     * @param config - Classifier configuration with model, provider, and thresholds.
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Classifies a user query into a retrieval tier.
+     *
+     * Steps:
+     * 1. Builds a chain-of-thought system prompt with tier 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. Applies confidence-based tier bumping: if confidence < threshold, tier += 1.
+     * 5. Caps the tier at the configured `maxTier`.
+     * 6. On ANY error, returns a safe T1 fallback with confidence 0.
+     *
+     * @param query - The user's query text to classify.
+     * @param conversationHistory - Optional recent conversation messages for context.
+     * @returns A {@link ClassificationResult} with tier, confidence, reasoning, and metadata.
+     */
+    async classify(query, conversationHistory) {
+        try {
+            const systemPrompt = this.buildSystemPrompt(conversationHistory);
+            const response = await generateText({
+                provider: this.config.provider,
+                model: this.config.model,
+                system: systemPrompt,
+                prompt: query,
+                temperature: 0.1,
+                apiKey: this.config.apiKey,
+                baseUrl: this.config.baseUrl,
+            });
+            const parsed = this.parseResponse(response.text);
+            return this.applyConstraints(parsed);
+        }
+        catch {
+            return this.fallbackResult();
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    /**
+     * Builds the system prompt by replacing template placeholders with actual
+     * topic list, tool list, and conversation context.
+     *
+     * @param conversationHistory - Optional conversation messages to include as context.
+     * @returns The fully rendered system prompt string.
+     */
+    buildSystemPrompt(conversationHistory) {
+        let conversationContext = 'No prior conversation.';
+        if (conversationHistory && conversationHistory.length > 0) {
+            conversationContext = conversationHistory
+                .map((msg) => `${msg.role}: ${msg.content}`)
+                .join('\n');
+        }
+        return SYSTEM_PROMPT_TEMPLATE
+            .replace('{{TOPIC_LIST}}', this.config.topicList)
+            .replace('{{TOOL_LIST}}', this.config.toolList)
+            .replace('{{CONVERSATION_CONTEXT}}', conversationContext);
+    }
+    /**
+     * Parses the LLM response text into a {@link ClassificationResult}.
+     *
+     * Handles two response formats:
+     * - Raw JSON object
+     * - JSON wrapped in markdown code fences (```json ... ```)
+     *
+     * @param text - Raw text from the LLM response.
+     * @returns A parsed {@link ClassificationResult}.
+     * @throws If the response cannot be parsed as valid JSON.
+     */
+    parseResponse(text) {
+        // Extract JSON from the response — handle optional markdown code fences
+        const jsonMatch = text.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            throw new Error(`Failed to extract JSON from classifier response: ${text.slice(0, 200)}`);
+        }
+        const raw = JSON.parse(jsonMatch[0]);
+        return {
+            tier: raw.tier,
+            confidence: raw.confidence,
+            reasoning: raw.thinking,
+            internalKnowledgeSufficient: raw.internal_knowledge_sufficient,
+            suggestedSources: raw.suggested_sources,
+            toolsNeeded: raw.tools_needed,
+        };
+    }
+    /**
+     * Applies post-classification constraints:
+     * 1. If confidence < threshold, bump tier by 1 (request broader retrieval).
+     * 2. Cap tier at the configured maxTier.
+     *
+     * @param result - The raw classification result from the LLM.
+     * @returns The constrained classification result.
+     */
+    applyConstraints(result) {
+        let tier = result.tier;
+        // Bump tier when confidence is below the threshold
+        if (result.confidence < this.config.confidenceThreshold) {
+            tier = Math.min(tier + 1, 3);
+        }
+        // Cap at maxTier
+        tier = Math.min(tier, this.config.maxTier);
+        return {
+            ...result,
+            tier,
+        };
+    }
+    /**
+     * Returns a safe T1 fallback result when classification fails for any reason.
+     * T1 ensures at least a basic vector search is performed, which is a
+     * reasonable default when the classifier cannot determine the right tier.
+     *
+     * @returns A T1 {@link ClassificationResult} with confidence 0.
+     */
+    fallbackResult() {
+        return {
+            tier: 1,
+            confidence: 0,
+            reasoning: 'Classification failed; falling back to T1 for safety.',
+            internalKnowledgeSufficient: false,
+            suggestedSources: ['vector'],
+            toolsNeeded: [],
+        };
+    }
+}
+//# sourceMappingURL=QueryClassifier.js.map

package/dist/query-router/QueryClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryClassifier.js","sourceRoot":"","sources":["../../src/query-router/QueryClassifier.ts"],"names":[],"mappings":"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"}