@framers/agentos 0.1.112 → 0.1.114

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

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview QueryDispatcher — routes classified queries to the
+ * tier-appropriate retrieval pipeline with graceful fallbacks.
+ * @module @framers/agentos/query-router/QueryDispatcher
+ *
+ * The dispatcher is the second stage of the QueryRouter pipeline, invoked
+ * after the QueryClassifier has assigned a complexity tier. It orchestrates
+ * vector search, knowledge-graph expansion, reranking, and deep research
+ * by delegating to injected callback functions — it has no direct coupling
+ * to EmbeddingManager, VectorStoreManager, or any concrete service.
+ *
+ * **Tier behaviour:**
+ * - T0: Trivial — no retrieval, returns empty immediately
+ * - T1: Simple lookup — vector search only (topK=5)
+ * - T2: Multi-source — vector(15) + graph expand + merge/dedup + rerank(5)
+ * - T3: Research — everything in T2 + deep research with synthesis
+ *
+ * **Fallback guarantees:**
+ * Every external call is wrapped in a try/catch so partial failures degrade
+ * gracefully rather than crashing the pipeline. A `retrieve:fallback` event
+ * is emitted for each degradation so consumers have full observability.
+ */
+import type { QueryTier, RetrievedChunk, RetrievalResult, QueryRouterEventUnion } from './types.js';
+/**
+ * Callback dependencies injected into the QueryDispatcher.
+ *
+ * Each retrieval capability is represented as a plain async function so the
+ * dispatcher remains decoupled from concrete implementations and is trivially
+ * testable with vi.fn() mocks.
+ */
+export interface QueryDispatcherDeps {
+    /**
+     * Dense vector similarity search.
+     * @param query - The user query string.
+     * @param topK  - Maximum number of chunks to return.
+     */
+    vectorSearch: (query: string, topK: number) => Promise<RetrievedChunk[]>;
+    /**
+     * Knowledge-graph expansion starting from seed chunks.
+     * Returns additional related chunks discovered via graph traversal.
+     * @param seedChunks - Initial chunks from vector search.
+     */
+    graphExpand: (seedChunks: RetrievedChunk[]) => Promise<RetrievedChunk[]>;
+    /**
+     * Cross-encoder or LLM-based reranker that scores and prunes chunks.
+     * @param query  - The user query string for relevance scoring.
+     * @param chunks - Candidate chunks to rerank.
+     * @param topN   - Maximum number of chunks to keep after reranking.
+     */
+    rerank: (query: string, chunks: RetrievedChunk[], topN: number) => Promise<RetrievedChunk[]>;
+    /**
+     * Multi-pass deep research synthesis.
+     * @param query   - The user query string.
+     * @param sources - Source identifiers to consult (e.g., ['web', 'docs']).
+     */
+    deepResearch: (query: string, sources: string[]) => Promise<{
+        synthesis: string;
+        sources: RetrievedChunk[];
+    }>;
+    /**
+     * Event emitter callback for lifecycle observability events.
+     * @param event - A typed QueryRouter event.
+     */
+    emit: (event: QueryRouterEventUnion) => void;
+    /** Whether graph-based retrieval is available / enabled. */
+    graphEnabled: boolean;
+    /** Whether deep research is available / enabled. */
+    deepResearchEnabled: boolean;
+}
+/**
+ * Routes classified queries to the tier-appropriate retrieval pipeline.
+ *
+ * @example
+ * ```typescript
+ * const dispatcher = new QueryDispatcher({
+ *   vectorSearch: async (q, k) => vectorStore.search(q, k),
+ *   graphExpand:  async (seeds) => graphRag.expand(seeds),
+ *   rerank:       async (q, chunks, n) => reranker.rerank(q, chunks, n),
+ *   deepResearch: async (q, srcs) => researcher.research(q, srcs),
+ *   emit:         (e) => eventBus.emit(e),
+ *   graphEnabled: true,
+ *   deepResearchEnabled: true,
+ * });
+ *
+ * const result = await dispatcher.dispatch('How does auth work?', 2);
+ * ```
+ */
+export declare class QueryDispatcher {
+    /** Injected retrieval dependencies. */
+    private readonly deps;
+    constructor(deps: QueryDispatcherDeps);
+    /**
+     * Dispatch a classified query to the tier-appropriate retrieval pipeline.
+     *
+     * @param query            - The user's natural-language query.
+     * @param tier             - Complexity tier assigned by the QueryClassifier.
+     * @param suggestedSources - Optional source hints for deep research (T3).
+     *                           Defaults to `['web']` when not provided.
+     * @returns Aggregated retrieval result with chunks, optional synthesis,
+     *          and timing metadata.
+     */
+    dispatch(query: string, tier: QueryTier, suggestedSources?: string[]): Promise<RetrievalResult>;
+    /**
+     * Tier 1 pipeline: vector search only, topK=5.
+     * No graph traversal, no reranking, no research.
+     */
+    private dispatchTier1;
+    /**
+     * Tier 2 pipeline: vector(15) + graph expand + merge/dedup + rerank(5).
+     *
+     * Fallbacks:
+     * - If graph expand fails, continues with vector-only chunks.
+     * - If rerank fails, falls back to sorting by score and taking top 5.
+     */
+    private dispatchTier2;
+    /**
+     * Internal Tier 2 pipeline used by both direct T2 routing and the T3
+     * pre-research retrieval stage. T3 suppresses the early retrieve:complete
+     * event so the final completion event reflects the post-research result.
+     */
+    private dispatchTier2Internal;
+    /**
+     * Tier 3 pipeline: everything in T2 + deep research synthesis.
+     *
+     * Fallback: if deep research fails, the result is identical to T2
+     * (no synthesis, no research chunks), and a fallback event is emitted.
+     */
+    private dispatchTier3;
+    /**
+     * Merge two arrays of chunks and deduplicate by chunk ID.
+     * When duplicates exist, the chunk with the higher relevanceScore is kept.
+     *
+     * @param primary   - Primary chunk array (typically vector results).
+     * @param secondary - Secondary chunk array (typically graph or research results).
+     * @returns Merged, deduplicated array preserving insertion order of first occurrence.
+     */
+    private mergeAndDedup;
+}
+//# sourceMappingURL=QueryDispatcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"QueryDispatcher.d.ts","sourceRoot":"","sources":["../../src/query-router/QueryDispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAMpB;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAEzE;;;;OAIG;IACH,WAAW,EAAE,CAAC,UAAU,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE7F;;;;OAIG;IACH,YAAY,EAAE,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,KACd,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC,CAAC;IAE/D;;;OAGG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAE7C,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IAEtB,oDAAoD;IACpD,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAe;IAC1B,uCAAuC;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;gBAE/B,IAAI,EAAE,mBAAmB;IAQrC;;;;;;;;;OASG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,EACf,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAC1B,OAAO,CAAC,eAAe,CAAC;IAgC3B;;;OAGG;YACW,aAAa;IA0B3B;;;;;;OAMG;YACW,aAAa;IAI3B;;;;OAIG;YACW,qBAAqB;IA0FnC;;;;;OAKG;YACW,aAAa;IAiF3B;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CAsBtB"}

package/dist/query-router/QueryDispatcher.js

@@ -0,0 +1,297 @@
+/**
+ * @fileoverview QueryDispatcher — routes classified queries to the
+ * tier-appropriate retrieval pipeline with graceful fallbacks.
+ * @module @framers/agentos/query-router/QueryDispatcher
+ *
+ * The dispatcher is the second stage of the QueryRouter pipeline, invoked
+ * after the QueryClassifier has assigned a complexity tier. It orchestrates
+ * vector search, knowledge-graph expansion, reranking, and deep research
+ * by delegating to injected callback functions — it has no direct coupling
+ * to EmbeddingManager, VectorStoreManager, or any concrete service.
+ *
+ * **Tier behaviour:**
+ * - T0: Trivial — no retrieval, returns empty immediately
+ * - T1: Simple lookup — vector search only (topK=5)
+ * - T2: Multi-source — vector(15) + graph expand + merge/dedup + rerank(5)
+ * - T3: Research — everything in T2 + deep research with synthesis
+ *
+ * **Fallback guarantees:**
+ * Every external call is wrapped in a try/catch so partial failures degrade
+ * gracefully rather than crashing the pipeline. A `retrieve:fallback` event
+ * is emitted for each degradation so consumers have full observability.
+ */
+// ============================================================================
+// QUERY DISPATCHER
+// ============================================================================
+/**
+ * Routes classified queries to the tier-appropriate retrieval pipeline.
+ *
+ * @example
+ * ```typescript
+ * const dispatcher = new QueryDispatcher({
+ *   vectorSearch: async (q, k) => vectorStore.search(q, k),
+ *   graphExpand:  async (seeds) => graphRag.expand(seeds),
+ *   rerank:       async (q, chunks, n) => reranker.rerank(q, chunks, n),
+ *   deepResearch: async (q, srcs) => researcher.research(q, srcs),
+ *   emit:         (e) => eventBus.emit(e),
+ *   graphEnabled: true,
+ *   deepResearchEnabled: true,
+ * });
+ *
+ * const result = await dispatcher.dispatch('How does auth work?', 2);
+ * ```
+ */
+export class QueryDispatcher {
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // --------------------------------------------------------------------------
+    // PUBLIC API
+    // --------------------------------------------------------------------------
+    /**
+     * Dispatch a classified query to the tier-appropriate retrieval pipeline.
+     *
+     * @param query            - The user's natural-language query.
+     * @param tier             - Complexity tier assigned by the QueryClassifier.
+     * @param suggestedSources - Optional source hints for deep research (T3).
+     *                           Defaults to `['web']` when not provided.
+     * @returns Aggregated retrieval result with chunks, optional synthesis,
+     *          and timing metadata.
+     */
+    async dispatch(query, tier, suggestedSources) {
+        // T0 — trivial queries need no retrieval at all
+        if (tier === 0) {
+            return { chunks: [], durationMs: 0 };
+        }
+        const start = Date.now();
+        this.deps.emit({
+            type: 'retrieve:start',
+            tier,
+            timestamp: Date.now(),
+        });
+        // T1 — simple vector-only retrieval
+        if (tier === 1) {
+            return this.dispatchTier1(query, start);
+        }
+        // T2 — hybrid: vector + graph + rerank
+        if (tier === 2) {
+            return this.dispatchTier2(query, start);
+        }
+        // T3 — hybrid + deep research
+        return this.dispatchTier3(query, suggestedSources ?? ['web'], start);
+    }
+    // --------------------------------------------------------------------------
+    // TIER PIPELINES
+    // --------------------------------------------------------------------------
+    /**
+     * Tier 1 pipeline: vector search only, topK=5.
+     * No graph traversal, no reranking, no research.
+     */
+    async dispatchTier1(query, start) {
+        const vectorStart = Date.now();
+        const chunks = await this.deps.vectorSearch(query, 5);
+        const vectorDuration = Date.now() - vectorStart;
+        this.deps.emit({
+            type: 'retrieve:vector',
+            chunkCount: chunks.length,
+            durationMs: vectorDuration,
+            timestamp: Date.now(),
+        });
+        const result = {
+            chunks,
+            durationMs: Date.now() - start,
+        };
+        this.deps.emit({
+            type: 'retrieve:complete',
+            result,
+            timestamp: Date.now(),
+        });
+        return result;
+    }
+    /**
+     * Tier 2 pipeline: vector(15) + graph expand + merge/dedup + rerank(5).
+     *
+     * Fallbacks:
+     * - If graph expand fails, continues with vector-only chunks.
+     * - If rerank fails, falls back to sorting by score and taking top 5.
+     */
+    async dispatchTier2(query, start) {
+        return this.dispatchTier2Internal(query, start, true);
+    }
+    /**
+     * Internal Tier 2 pipeline used by both direct T2 routing and the T3
+     * pre-research retrieval stage. T3 suppresses the early retrieve:complete
+     * event so the final completion event reflects the post-research result.
+     */
+    async dispatchTier2Internal(query, start, emitComplete) {
+        // --- Vector search (topK=15) ---
+        const vectorStart = Date.now();
+        const vectorChunks = await this.deps.vectorSearch(query, 15);
+        const vectorDuration = Date.now() - vectorStart;
+        this.deps.emit({
+            type: 'retrieve:vector',
+            chunkCount: vectorChunks.length,
+            durationMs: vectorDuration,
+            timestamp: Date.now(),
+        });
+        // --- Graph expansion (fallback-safe) ---
+        let graphChunks = [];
+        if (this.deps.graphEnabled) {
+            const graphStart = Date.now();
+            try {
+                graphChunks = await this.deps.graphExpand(vectorChunks);
+                const graphDuration = Date.now() - graphStart;
+                this.deps.emit({
+                    type: 'retrieve:graph',
+                    entityCount: graphChunks.length,
+                    durationMs: graphDuration,
+                    timestamp: Date.now(),
+                });
+            }
+            catch (err) {
+                this.deps.emit({
+                    type: 'retrieve:fallback',
+                    strategy: 'graph-skip',
+                    reason: `Graph expansion failed: ${err.message}`,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        // --- Merge + deduplicate by id ---
+        const merged = this.mergeAndDedup(vectorChunks, graphChunks);
+        // --- Rerank (fallback-safe) ---
+        let finalChunks;
+        const rerankStart = Date.now();
+        try {
+            finalChunks = await this.deps.rerank(query, merged, 5);
+            const rerankDuration = Date.now() - rerankStart;
+            this.deps.emit({
+                type: 'retrieve:rerank',
+                inputCount: merged.length,
+                outputCount: finalChunks.length,
+                durationMs: rerankDuration,
+                timestamp: Date.now(),
+            });
+        }
+        catch (err) {
+            // Fallback: sort by score descending, take top 5
+            finalChunks = [...merged]
+                .sort((a, b) => b.relevanceScore - a.relevanceScore)
+                .slice(0, 5);
+            this.deps.emit({
+                type: 'retrieve:fallback',
+                strategy: 'rerank-skip',
+                reason: `Rerank failed: ${err.message}`,
+                timestamp: Date.now(),
+            });
+        }
+        const result = {
+            chunks: finalChunks,
+            durationMs: Date.now() - start,
+        };
+        if (emitComplete) {
+            this.deps.emit({
+                type: 'retrieve:complete',
+                result,
+                timestamp: Date.now(),
+            });
+        }
+        return result;
+    }
+    /**
+     * Tier 3 pipeline: everything in T2 + deep research synthesis.
+     *
+     * Fallback: if deep research fails, the result is identical to T2
+     * (no synthesis, no research chunks), and a fallback event is emitted.
+     */
+    async dispatchTier3(query, suggestedSources, start) {
+        // Run the T2 pipeline first to get hybrid chunks
+        const t2Result = await this.dispatchTier2Internal(query, start, false);
+        // --- Deep research (fallback-safe) ---
+        if (this.deps.deepResearchEnabled) {
+            this.deps.emit({
+                type: 'research:start',
+                query,
+                maxIterations: 3,
+                timestamp: Date.now(),
+            });
+            try {
+                const researchResult = await this.deps.deepResearch(query, suggestedSources);
+                this.deps.emit({
+                    type: 'research:phase',
+                    iteration: 1,
+                    totalIterations: 1,
+                    newChunksFound: researchResult.sources.length,
+                    timestamp: Date.now(),
+                });
+                this.deps.emit({
+                    type: 'research:complete',
+                    iterationsUsed: 1,
+                    totalChunks: researchResult.sources.length,
+                    durationMs: Date.now() - start,
+                    timestamp: Date.now(),
+                });
+                // Merge research chunks with T2 chunks, dedup
+                const allChunks = this.mergeAndDedup(t2Result.chunks, researchResult.sources);
+                const result = {
+                    chunks: allChunks,
+                    researchSynthesis: researchResult.synthesis,
+                    durationMs: Date.now() - start,
+                };
+                this.deps.emit({
+                    type: 'retrieve:complete',
+                    result,
+                    timestamp: Date.now(),
+                });
+                return result;
+            }
+            catch (err) {
+                this.deps.emit({
+                    type: 'retrieve:fallback',
+                    strategy: 'research-skip',
+                    reason: `Deep research failed: ${err.message}`,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        // If research was disabled or failed, return T2 result with updated duration
+        const result = {
+            ...t2Result,
+            durationMs: Date.now() - start,
+        };
+        this.deps.emit({
+            type: 'retrieve:complete',
+            result,
+            timestamp: Date.now(),
+        });
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // UTILITIES
+    // --------------------------------------------------------------------------
+    /**
+     * Merge two arrays of chunks and deduplicate by chunk ID.
+     * When duplicates exist, the chunk with the higher relevanceScore is kept.
+     *
+     * @param primary   - Primary chunk array (typically vector results).
+     * @param secondary - Secondary chunk array (typically graph or research results).
+     * @returns Merged, deduplicated array preserving insertion order of first occurrence.
+     */
+    mergeAndDedup(primary, secondary) {
+        const seen = new Map();
+        for (const chunk of primary) {
+            const existing = seen.get(chunk.id);
+            if (!existing || chunk.relevanceScore > existing.relevanceScore) {
+                seen.set(chunk.id, chunk);
+            }
+        }
+        for (const chunk of secondary) {
+            const existing = seen.get(chunk.id);
+            if (!existing || chunk.relevanceScore > existing.relevanceScore) {
+                seen.set(chunk.id, chunk);
+            }
+        }
+        return Array.from(seen.values());
+    }
+}
+//# sourceMappingURL=QueryDispatcher.js.map

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

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

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

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview QueryGenerator — tier-appropriate prompt construction and LLM
+ * answer generation for the QueryRouter pipeline.
+ *
+ * The generator is the final stage of the routing pipeline: it takes the
+ * classified {@link QueryTier}, a set of {@link RetrievedChunk}s from the
+ * retrieval phase, and an optional research synthesis narrative, then builds
+ * a tier-specific system prompt and invokes the LLM via {@link generateText}.
+ *
+ * **Tier-specific behaviour:**
+ *
+ * | Tier | Model   | Context | Temperature | Max Tokens | Instruction                                        |
+ * |------|---------|---------|-------------|------------|----------------------------------------------------|
+ * | T0   | standard| none    | 0.7         | 512        | (base prompt only)                                 |
+ * | T1   | standard| chunks  | 0.3         | 512        | "Answer based on the documentation context provided."|
+ * | T2   | deep    | chunks  | 0.3         | 1024       | "cross-reference" sources                          |
+ * | T3   | deep    | chunks + research | 0.3 | 1024   | "Synthesize information from both internal documentation and external research." |
+ *
+ * **Context injection:**
+ * Each chunk is formatted as `## heading (sourcePath)\ncontent` and appended
+ * until the estimated token budget (`maxContextTokens`) is exhausted. Token
+ * estimation uses the common heuristic of `Math.ceil(text.length / 4)`.
+ *
+ * @module @framers/agentos/query-router/QueryGenerator
+ */
+import type { QueryTier, RetrievedChunk } from './types.js';
+/**
+ * Configuration for the {@link QueryGenerator}.
+ */
+export interface QueryGeneratorConfig {
+    /**
+     * Model identifier for T0 and T1 queries (standard complexity).
+     * @example 'openai:gpt-4.1-mini'
+     */
+    model: string;
+    /**
+     * Model identifier for T2 and T3 queries (deep reasoning).
+     * @example 'openai:gpt-4.1'
+     */
+    modelDeep: string;
+    /**
+     * LLM provider name (e.g. 'openai', 'anthropic').
+     */
+    provider: string;
+    /**
+     * Optional API key override. When omitted, the provider resolves
+     * credentials from environment variables.
+     */
+    apiKey?: string;
+    /**
+     * Optional base URL override for local proxies or alternative endpoints.
+     */
+    baseUrl?: string;
+    /**
+     * Maximum number of estimated tokens to allocate for documentation
+     * context in the system prompt. Chunks are added in order until
+     * this budget is exhausted.
+     * @default 4000
+     */
+    maxContextTokens?: number;
+}
+/**
+ * Structured result returned by {@link QueryGenerator.generate}.
+ */
+export interface GenerateResult {
+    /** The generated answer text. */
+    answer: string;
+    /** The model identifier that was actually used for generation. */
+    model: string;
+    /** Token usage figures reported by the provider. */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Builds tier-appropriate prompts and generates LLM answers.
+ *
+ * The generator selects a model (standard vs. deep) based on the query tier,
+ * constructs a system prompt with optional documentation context and research
+ * synthesis, then delegates to {@link generateText} for the actual LLM call.
+ *
+ * @example
+ * ```typescript
+ * const gen = new QueryGenerator({
+ *   model: 'openai:gpt-4.1-mini',
+ *   modelDeep: 'openai:gpt-4.1',
+ *   provider: 'openai',
+ * });
+ *
+ * const result = await gen.generate('How does auth work?', 1, chunks);
+ * console.log(result.answer);
+ * ```
+ */
+export declare class QueryGenerator {
+    /** Resolved configuration with defaults applied. */
+    private readonly config;
+    /**
+     * Create a new QueryGenerator instance.
+     *
+     * @param config - Generator configuration specifying models, provider,
+     *                 and optional credential overrides.
+     */
+    constructor(config: QueryGeneratorConfig);
+    /**
+     * Generate an answer for the given query at the specified complexity tier.
+     *
+     * @param query - The user's original question.
+     * @param tier - The classified complexity tier (0–3).
+     * @param chunks - Retrieved documentation chunks, sorted by relevance.
+     * @param researchSynthesis - Optional research narrative (T3 only).
+     * @returns A promise resolving to the generated answer, model used, and token usage.
+     */
+    generate(query: string, tier: QueryTier, chunks: RetrievedChunk[], researchSynthesis?: string): Promise<GenerateResult>;
+    /**
+     * Select the appropriate model based on query tier.
+     * T0–T1 use the standard model; T2–T3 use the deep model.
+     *
+     * @param tier - The classified query tier.
+     * @returns The model identifier string.
+     */
+    private selectModel;
+    /**
+     * Select the sampling temperature for the given tier.
+     * T0 uses a higher temperature (0.7) for more creative general answers;
+     * all other tiers use 0.3 for focused, grounded responses.
+     *
+     * @param tier - The classified query tier.
+     * @returns The temperature value.
+     */
+    private selectTemperature;
+    /**
+     * Select the maximum output tokens for the given tier.
+     * T0–T1 cap at 512 tokens; T2–T3 allow 1024 for more detailed answers.
+     *
+     * @param tier - The classified query tier.
+     * @returns The maxTokens value.
+     */
+    private selectMaxTokens;
+    /**
+     * Build the full system prompt by composing the base prompt with optional
+     * tier-specific context blocks and instructions.
+     *
+     * @param tier - The classified query tier.
+     * @param chunks - Retrieved documentation chunks.
+     * @param researchSynthesis - Optional research narrative for T3.
+     * @returns The assembled system prompt string.
+     */
+    private buildSystemPrompt;
+    /**
+     * Format retrieved chunks into a documentation context block, respecting
+     * the configured token budget.
+     *
+     * Each chunk is formatted as:
+     * ```
+     * ## heading (sourcePath)
+     * content
+     * ```
+     *
+     * Chunks are added in the order provided (typically by relevance) until the
+     * estimated token count would exceed `maxContextTokens`.
+     *
+     * @param chunks - The retrieved chunks to format.
+     * @returns The formatted context string, or an empty string if no chunks fit.
+     */
+    private formatChunksAsContext;
+    /**
+     * Return the tier-specific instruction appended to the system prompt.
+     *
+     * @param tier - The classified query tier.
+     * @returns The instruction string, or `undefined` for T0 (no extra instruction).
+     */
+    private getTierInstruction;
+    /**
+     * Estimate the token count for a string using the common heuristic of
+     * approximately 4 characters per token.
+     *
+     * @param text - The text to estimate.
+     * @returns Estimated token count (ceiling).
+     */
+    private estimateTokens;
+}
+//# sourceMappingURL=QueryGenerator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"QueryGenerator.d.ts","sourceRoot":"","sources":["../../src/query-router/QueryGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAM5D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IAEf,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IAEd,oDAAoD;IACpD,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAsBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAc;IACzB,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAC4B;IAEnD;;;;;OAKG;gBACS,MAAM,EAAE,oBAAoB;IAWxC;;;;;;;;OAQG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,cAAc,EAAE,EACxB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,cAAc,CAAC;IAgC1B;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAGvB"}