@framers/agentos 0.2.6 → 0.2.8

package/dist/read-router/classifier.js

@@ -0,0 +1,104 @@
+/**
+ * @file classifier.ts
+ * @description LLM-as-judge classifier that maps a query+evidence pair
+ * to one of the five {@link ReadIntent} values.
+ *
+ * @module @framers/agentos/read-router/classifier
+ */
+import { READ_INTENTS } from './routing-tables.js';
+// ============================================================================
+// Prompts
+// ============================================================================
+export const READ_INTENT_CLASSIFIER_SYSTEM_PROMPT = `You are classifying a user query (with retrieved evidence) into one of five read intents.
+
+Return ONLY the intent token (no explanation, no quotes, no punctuation).
+
+Intents:
+- precise-fact: the user wants a specific named entity, number, date, or fact. Examples: "What is X's email?", "When was the last release?"
+- multi-source-synthesis: the answer requires combining information from multiple evidence chunks. Examples: "Summarize all the topics we discussed", "Aggregate counts across sessions."
+- time-interval: the query asks about durations, orderings, or "how long ago / before / after" timing. Examples: "How many days since X?", "In what order did Y, Z, W happen?"
+- preference-recommendation: the user wants tips, suggestions, advice, or recommendations grounded in their own context. Examples: "Any tips for X?", "Can you suggest Y?"
+- abstention-candidate: the question may be unanswerable from the evidence. Adversarial or off-topic. Examples: "Where did I move to last year?" when no move is in evidence.`;
+export const READ_INTENT_CLASSIFIER_SYSTEM_PROMPT_FEWSHOT = `You are classifying a user query (with retrieved evidence) into one of five read intents.
+
+Return ONLY the intent token (no explanation, no quotes, no punctuation).
+
+Intents:
+- precise-fact: a specific named entity, number, date, or fact.
+- multi-source-synthesis: combining information across multiple evidence chunks.
+- time-interval: durations, orderings, or "how long ago".
+- preference-recommendation: tips / suggestions / advice grounded in user context.
+- abstention-candidate: question may be unanswerable from evidence.
+
+Examples:
+
+Question: What was my final boss's name in the game I played last week?
+Intent: precise-fact
+
+Question: What topics did we discuss across our last five conversations?
+Intent: multi-source-synthesis
+
+Question: How many weeks have passed since I started the new job?
+Intent: time-interval
+
+Question: Any tips for improving my morning routine?
+Intent: preference-recommendation
+
+Question: Where did I move to four years ago?
+Intent: abstention-candidate`;
+export const SAFE_READ_INTENT_FALLBACK = 'multi-source-synthesis';
+export function normalizeReadIntentClassifierOutput(raw) {
+    const lines = raw.split('\n');
+    let firstLine = '';
+    for (const ln of lines) {
+        if (ln.trim().length > 0) {
+            firstLine = ln;
+            break;
+        }
+    }
+    let cleaned = firstLine.trim().toLowerCase();
+    cleaned = cleaned.replace(/^(intent|category|type|answer|label|class)\s*[:\-=]\s*/, '');
+    cleaned = cleaned.replace(/^["'`]+|["'`]+$/g, '');
+    cleaned = cleaned.replace(/[.,;!?]+$/g, '');
+    return cleaned.trim();
+}
+export function parseReadIntentClassifierOutput(raw) {
+    const cleaned = normalizeReadIntentClassifierOutput(raw);
+    for (const token of READ_INTENTS) {
+        if (cleaned === token ||
+            cleaned.startsWith(`${token} `) ||
+            cleaned.startsWith(`${token}\n`)) {
+            return token;
+        }
+    }
+    return SAFE_READ_INTENT_FALLBACK;
+}
+export class LLMReadIntentClassifier {
+    constructor(options) {
+        this.llm = options.llm;
+        this.maxTokens = options.maxTokens ?? 16;
+        this.maxEvidenceChars = options.maxEvidenceChars ?? 600;
+    }
+    async classify(query, evidence, options) {
+        const system = options?.useFewShotPrompt
+            ? READ_INTENT_CLASSIFIER_SYSTEM_PROMPT_FEWSHOT
+            : READ_INTENT_CLASSIFIER_SYSTEM_PROMPT;
+        const evidencePreview = evidence
+            .join('\n---\n')
+            .slice(0, this.maxEvidenceChars);
+        const user = `Question: ${query}\n\nEvidence (preview):\n${evidencePreview}\n\nIntent:`;
+        const response = await this.llm.invoke({
+            system,
+            user,
+            maxTokens: this.maxTokens,
+            temperature: 0,
+        });
+        return {
+            intent: parseReadIntentClassifierOutput(response.text),
+            tokensIn: response.tokensIn,
+            tokensOut: response.tokensOut,
+            model: response.model,
+        };
+    }
+}
+//# sourceMappingURL=classifier.js.map

package/dist/read-router/classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../src/read-router/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AAiDpE,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,MAAM,CAAC,MAAM,oCAAoC,GAAG;;;;;;;;;8KAS0H,CAAC;AAE/K,MAAM,CAAC,MAAM,4CAA4C,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;6BA0B/B,CAAC;AAE9B,MAAM,CAAC,MAAM,yBAAyB,GAAe,wBAAwB,CAAC;AAE9E,MAAM,UAAU,mCAAmC,CAAC,GAAW;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,SAAS,GAAG,EAAE,CAAC;YACf,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,wDAAwD,EAAE,EAAE,CAAC,CAAC;IACxF,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;IAClD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,GAAW;IACzD,MAAM,OAAO,GAAG,mCAAmC,CAAC,GAAG,CAAC,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,IACE,OAAO,KAAK,KAAK;YACjB,OAAO,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC;YAC/B,OAAO,CAAC,UAAU,CAAC,GAAG,KAAK,IAAI,CAAC,EAChC,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,yBAAyB,CAAC;AACnC,CAAC;AAaD,MAAM,OAAO,uBAAuB;IAKlC,YAAY,OAAuC;QACjD,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QACzC,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,GAAG,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,KAAa,EACb,QAA2B,EAC3B,OAA6C;QAE7C,MAAM,MAAM,GAAG,OAAO,EAAE,gBAAgB;YACtC,CAAC,CAAC,4CAA4C;YAC9C,CAAC,CAAC,oCAAoC,CAAC;QACzC,MAAM,eAAe,GAAG,QAAQ;aAC7B,IAAI,CAAC,SAAS,CAAC;aACf,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,aAAa,KAAK,4BAA4B,eAAe,aAAa,CAAC;QAExF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YACrC,MAAM;YACN,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,CAAC;SACf,CAAC,CAAC;QAEH,OAAO;YACL,MAAM,EAAE,+BAA+B,CAAC,QAAQ,CAAC,IAAI,CAAC;YACtD,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC;IACJ,CAAC;CACF"}

package/dist/read-router/costs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file costs.ts
+ * @description Per-strategy cost-points for ReadRouter budget logic.
+ * Numbers are illustrative averages on gpt-4o reader; consumers should
+ * override with measurements from their own workload.
+ *
+ * @module @framers/agentos/read-router/costs
+ */
+import type { ReadStrategyId } from './routing-tables.js';
+export interface ReadStrategyCostPoint {
+    readonly strategy: ReadStrategyId;
+    readonly avgCostPerReadUsd: number;
+    readonly avgLatencyMs: number;
+    readonly callCount: number;
+    readonly description: string;
+}
+export declare const SINGLE_CALL_COST: ReadStrategyCostPoint;
+export declare const TWO_CALL_EXTRACT_ANSWER_COST: ReadStrategyCostPoint;
+export declare const COMMIT_VS_ABSTAIN_COST: ReadStrategyCostPoint;
+export declare const VERBATIM_CITATION_COST: ReadStrategyCostPoint;
+export declare const SCRATCHPAD_COST: ReadStrategyCostPoint;
+export declare const DEFAULT_READ_COSTS: Readonly<Record<ReadStrategyId, ReadStrategyCostPoint>>;
+//# sourceMappingURL=costs.d.ts.map

package/dist/read-router/costs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"costs.d.ts","sourceRoot":"","sources":["../../src/read-router/costs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,gBAAgB,EAAE,qBAMJ,CAAC;AAE5B,eAAO,MAAM,4BAA4B,EAAE,qBAMhB,CAAC;AAE5B,eAAO,MAAM,sBAAsB,EAAE,qBAMV,CAAC;AAE5B,eAAO,MAAM,sBAAsB,EAAE,qBAMV,CAAC;AAE5B,eAAO,MAAM,eAAe,EAAE,qBAMH,CAAC;AAE5B,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CACvC,MAAM,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAO7C,CAAC"}

package/dist/read-router/costs.js

@@ -0,0 +1,51 @@
+/**
+ * @file costs.ts
+ * @description Per-strategy cost-points for ReadRouter budget logic.
+ * Numbers are illustrative averages on gpt-4o reader; consumers should
+ * override with measurements from their own workload.
+ *
+ * @module @framers/agentos/read-router/costs
+ */
+export const SINGLE_CALL_COST = Object.freeze({
+    strategy: 'single-call',
+    avgCostPerReadUsd: 0.0150,
+    avgLatencyMs: 1500,
+    callCount: 1,
+    description: 'one reader.invoke call',
+});
+export const TWO_CALL_EXTRACT_ANSWER_COST = Object.freeze({
+    strategy: 'two-call-extract-answer',
+    avgCostPerReadUsd: 0.0280,
+    avgLatencyMs: 2900,
+    callCount: 2,
+    description: 'extract-then-answer: claim extraction call + answer call',
+});
+export const COMMIT_VS_ABSTAIN_COST = Object.freeze({
+    strategy: 'commit-vs-abstain',
+    avgCostPerReadUsd: 0.0220,
+    avgLatencyMs: 2200,
+    callCount: 2,
+    description: 'binary commit/abstain decision + answer-or-refuse call',
+});
+export const VERBATIM_CITATION_COST = Object.freeze({
+    strategy: 'verbatim-citation',
+    avgCostPerReadUsd: 0.0170,
+    avgLatencyMs: 1700,
+    callCount: 1,
+    description: 'single call with verbatim-citation prompt rule',
+});
+export const SCRATCHPAD_COST = Object.freeze({
+    strategy: 'scratchpad-then-answer',
+    avgCostPerReadUsd: 0.0190,
+    avgLatencyMs: 1900,
+    callCount: 1,
+    description: 'single call with explicit scratchpad-before-answer scaffold',
+});
+export const DEFAULT_READ_COSTS = Object.freeze({
+    'single-call': SINGLE_CALL_COST,
+    'two-call-extract-answer': TWO_CALL_EXTRACT_ANSWER_COST,
+    'commit-vs-abstain': COMMIT_VS_ABSTAIN_COST,
+    'verbatim-citation': VERBATIM_CITATION_COST,
+    'scratchpad-then-answer': SCRATCHPAD_COST,
+});
+//# sourceMappingURL=costs.js.map

package/dist/read-router/costs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costs.js","sourceRoot":"","sources":["../../src/read-router/costs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,MAAM,CAAC,MAAM,gBAAgB,GAA0B,MAAM,CAAC,MAAM,CAAC;IACnE,QAAQ,EAAE,aAAsB;IAChC,iBAAiB,EAAE,MAAM;IACzB,YAAY,EAAE,IAAI;IAClB,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,wBAAwB;CACtC,CAA0B,CAAC;AAE5B,MAAM,CAAC,MAAM,4BAA4B,GAA0B,MAAM,CAAC,MAAM,CAAC;IAC/E,QAAQ,EAAE,yBAAkC;IAC5C,iBAAiB,EAAE,MAAM;IACzB,YAAY,EAAE,IAAI;IAClB,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,0DAA0D;CACxE,CAA0B,CAAC;AAE5B,MAAM,CAAC,MAAM,sBAAsB,GAA0B,MAAM,CAAC,MAAM,CAAC;IACzE,QAAQ,EAAE,mBAA4B;IACtC,iBAAiB,EAAE,MAAM;IACzB,YAAY,EAAE,IAAI;IAClB,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,wDAAwD;CACtE,CAA0B,CAAC;AAE5B,MAAM,CAAC,MAAM,sBAAsB,GAA0B,MAAM,CAAC,MAAM,CAAC;IACzE,QAAQ,EAAE,mBAA4B;IACtC,iBAAiB,EAAE,MAAM;IACzB,YAAY,EAAE,IAAI;IAClB,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,gDAAgD;CAC9D,CAA0B,CAAC;AAE5B,MAAM,CAAC,MAAM,eAAe,GAA0B,MAAM,CAAC,MAAM,CAAC;IAClE,QAAQ,EAAE,wBAAiC;IAC3C,iBAAiB,EAAE,MAAM;IACzB,YAAY,EAAE,IAAI;IAClB,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,6DAA6D;CAC3E,CAA0B,CAAC;AAE5B,MAAM,CAAC,MAAM,kBAAkB,GAE3B,MAAM,CAAC,MAAM,CAAC;IAChB,aAAa,EAAE,gBAAgB;IAC/B,yBAAyB,EAAE,4BAA4B;IACvD,mBAAmB,EAAE,sBAAsB;IAC3C,mBAAmB,EAAE,sBAAsB;IAC3C,wBAAwB,EAAE,eAAe;CAC1C,CAAC,CAAC"}

package/dist/read-router/dispatcher.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file dispatcher.ts
+ * @description Per-strategy execution layer for ReadRouter. Same
+ * registry-of-functions pattern as ingest-router and memory-router.
+ *
+ * @module @framers/agentos/read-router/dispatcher
+ */
+import type { ReadStrategyId } from './routing-tables.js';
+export type ReadStrategyExecutor<TOutcome, TPayload = undefined> = (query: string, evidence: readonly string[], payload: TPayload) => Promise<TOutcome>;
+export interface ReadDispatchArgs<TPayload = undefined> {
+    readonly strategy: ReadStrategyId;
+    readonly query: string;
+    readonly evidence: readonly string[];
+    readonly payload?: TPayload;
+}
+export interface ReadDispatchResult<TOutcome> {
+    readonly outcome: TOutcome;
+    readonly strategy: ReadStrategyId;
+}
+export interface IReadDispatcher<TOutcome = unknown, TPayload = unknown> {
+    dispatch(args: ReadDispatchArgs<TPayload>): Promise<ReadDispatchResult<TOutcome>>;
+}
+export declare class UnsupportedReadStrategyError extends Error {
+    readonly strategy: ReadStrategyId;
+    constructor(strategy: ReadStrategyId);
+}
+export type ReadStrategyRegistry<TOutcome, TPayload> = Partial<Record<ReadStrategyId, ReadStrategyExecutor<TOutcome, TPayload>>>;
+export declare class FunctionReadDispatcher<TOutcome, TPayload = undefined> implements IReadDispatcher<TOutcome, TPayload> {
+    private readonly registry;
+    constructor(registry: ReadStrategyRegistry<TOutcome, TPayload>);
+    dispatch(args: ReadDispatchArgs<TPayload>): Promise<ReadDispatchResult<TOutcome>>;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/read-router/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/read-router/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,MAAM,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,IAAI,CACjE,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,SAAS;IACpD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB,CAAC,QAAQ;IAC1C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAED,MAAM,WAAW,eAAe,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IACrE,QAAQ,CACN,IAAI,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAC/B,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC;CAC1C;AAED,qBAAa,4BAA6B,SAAQ,KAAK;aACzB,QAAQ,EAAE,cAAc;gBAAxB,QAAQ,EAAE,cAAc;CAOrD;AAED,MAAM,MAAM,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,IAAI,OAAO,CAC5D,MAAM,CAAC,cAAc,EAAE,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CACjE,CAAC;AAEF,qBAAa,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAChE,YAAW,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;gBAExD,QAAQ,EAAE,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAIxD,QAAQ,CACZ,IAAI,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAC/B,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;CAYzC"}

package/dist/read-router/dispatcher.js

@@ -0,0 +1,29 @@
+/**
+ * @file dispatcher.ts
+ * @description Per-strategy execution layer for ReadRouter. Same
+ * registry-of-functions pattern as ingest-router and memory-router.
+ *
+ * @module @framers/agentos/read-router/dispatcher
+ */
+export class UnsupportedReadStrategyError extends Error {
+    constructor(strategy) {
+        super(`ReadDispatcher: strategy '${strategy}' is not registered. ` +
+            `Supply an executor for this strategy at construction.`);
+        this.strategy = strategy;
+        this.name = 'UnsupportedReadStrategyError';
+    }
+}
+export class FunctionReadDispatcher {
+    constructor(registry) {
+        this.registry = registry;
+    }
+    async dispatch(args) {
+        const exec = this.registry[args.strategy];
+        if (!exec) {
+            throw new UnsupportedReadStrategyError(args.strategy);
+        }
+        const outcome = await exec(args.query, args.evidence, args.payload);
+        return { outcome, strategy: args.strategy };
+    }
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/read-router/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/read-router/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4BH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrD,YAA4B,QAAwB;QAClD,KAAK,CACH,6BAA6B,QAAQ,uBAAuB;YAC1D,uDAAuD,CAC1D,CAAC;QAJwB,aAAQ,GAAR,QAAQ,CAAgB;QAKlD,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAMD,MAAM,OAAO,sBAAsB;IAKjC,YAAY,QAAkD;QAC5D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,IAAgC;QAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,4BAA4B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxD,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,IAAI,CACxB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,OAAmB,CACzB,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC9C,CAAC;CACF"}

package/dist/read-router/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AgentOS ReadRouter Module
+ *
+ * Read-stage LLM-as-judge orchestrator that picks a reader strategy per
+ * query+evidence pair. Sibling of {@link IngestRouter} (input-stage),
+ * {@link MemoryRouter} (recall-stage), and the output-stage guardrails.
+ *
+ * @module @framers/agentos/read-router
+ */
+export type { ReadIntent, ReadStrategyId, ReadRouterPreset, ReadRoutingTable, } from './routing-tables.js';
+export { READ_INTENTS } from './routing-tables.js';
+export type { ReadStrategyCostPoint } from './costs.js';
+export type { ReadBudgetMode, ReadRouterConfig, ReadRoutingDecision, } from './select-strategy.js';
+export type { IReadIntentClassifier, IReadIntentClassifierLLM, ReadIntentClassifierLLMRequest, ReadIntentClassifierLLMResponse, ReadIntentClassifierClassifyOptions, ReadIntentClassifierResult, LLMReadIntentClassifierOptions, } from './classifier.js';
+export type { IReadDispatcher, ReadDispatchArgs, ReadDispatchResult, ReadStrategyExecutor, ReadStrategyRegistry, } from './dispatcher.js';
+export type { ReadBudgetPolicy, ReadRouterOptions, ReadRouterDecideOptions, ReadRouterDecision, ReadRouterDispatchedResult, } from './ReadRouter.js';
+export { PRECISE_FACT_TABLE, SYNTHESIS_TABLE, TEMPORAL_TABLE, PRESET_READ_TABLES, } from './routing-tables.js';
+export { SINGLE_CALL_COST, TWO_CALL_EXTRACT_ANSWER_COST, COMMIT_VS_ABSTAIN_COST, VERBATIM_CITATION_COST, SCRATCHPAD_COST, DEFAULT_READ_COSTS, } from './costs.js';
+export { selectReadStrategy, ReadRouterUnknownIntentError, ReadRouterBudgetExceededError, } from './select-strategy.js';
+export { READ_INTENT_CLASSIFIER_SYSTEM_PROMPT, READ_INTENT_CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_READ_INTENT_FALLBACK, LLMReadIntentClassifier, normalizeReadIntentClassifierOutput, parseReadIntentClassifierOutput, } from './classifier.js';
+export { FunctionReadDispatcher, UnsupportedReadStrategyError, } from './dispatcher.js';
+export { ReadRouter, ReadRouterDispatcherMissingError, } from './ReadRouter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/read-router/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/read-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,qBAAqB,EACrB,wBAAwB,EACxB,8BAA8B,EAC9B,+BAA+B,EAC/B,mCAAmC,EACnC,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,oCAAoC,EACpC,4CAA4C,EAC5C,yBAAyB,EACzB,uBAAuB,EACvB,mCAAmC,EACnC,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,UAAU,EACV,gCAAgC,GACjC,MAAM,iBAAiB,CAAC"}

package/dist/read-router/index.js

@@ -0,0 +1,17 @@
+/**
+ * AgentOS ReadRouter Module
+ *
+ * Read-stage LLM-as-judge orchestrator that picks a reader strategy per
+ * query+evidence pair. Sibling of {@link IngestRouter} (input-stage),
+ * {@link MemoryRouter} (recall-stage), and the output-stage guardrails.
+ *
+ * @module @framers/agentos/read-router
+ */
+export { READ_INTENTS } from './routing-tables.js';
+export { PRECISE_FACT_TABLE, SYNTHESIS_TABLE, TEMPORAL_TABLE, PRESET_READ_TABLES, } from './routing-tables.js';
+export { SINGLE_CALL_COST, TWO_CALL_EXTRACT_ANSWER_COST, COMMIT_VS_ABSTAIN_COST, VERBATIM_CITATION_COST, SCRATCHPAD_COST, DEFAULT_READ_COSTS, } from './costs.js';
+export { selectReadStrategy, ReadRouterUnknownIntentError, ReadRouterBudgetExceededError, } from './select-strategy.js';
+export { READ_INTENT_CLASSIFIER_SYSTEM_PROMPT, READ_INTENT_CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_READ_INTENT_FALLBACK, LLMReadIntentClassifier, normalizeReadIntentClassifierOutput, parseReadIntentClassifierOutput, } from './classifier.js';
+export { FunctionReadDispatcher, UnsupportedReadStrategyError, } from './dispatcher.js';
+export { ReadRouter, ReadRouterDispatcherMissingError, } from './ReadRouter.js';
+//# sourceMappingURL=index.js.map

package/dist/read-router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/read-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAoCnD,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,oCAAoC,EACpC,4CAA4C,EAC5C,yBAAyB,EACzB,uBAAuB,EACvB,mCAAmC,EACnC,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,UAAU,EACV,gCAAgC,GACjC,MAAM,iBAAiB,CAAC"}

package/dist/read-router/routing-tables.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link ReadRouter}.
+ *
+ * ReadRouter is the read-stage sibling of MemoryRouter (recall-stage)
+ * and IngestRouter (input-stage). It picks a reader strategy after
+ * retrieval has produced candidate evidence — single-call generation
+ * vs two-call extract-then-answer (Emergence pattern) vs commit-vs-
+ * abstain (explicit binary decision before answer) vs verbatim citation
+ * vs scratchpad-then-answer (chain-of-thought-lite for temporal questions).
+ *
+ * @module @framers/agentos/read-router/routing-tables
+ */
+export declare const READ_INTENTS: readonly ["precise-fact", "multi-source-synthesis", "time-interval", "preference-recommendation", "abstention-candidate"];
+/**
+ * Why the user is reading. Determines the optimal reader strategy.
+ *
+ * - `precise-fact`: a specific named entity / number / date is wanted.
+ *   Reader should commit to a single best fact from the evidence.
+ * - `multi-source-synthesis`: requires combining evidence from multiple
+ *   chunks. Two-call extract-then-answer often beats single-call here.
+ * - `time-interval`: durations / orderings / "how long ago" questions.
+ *   Scratchpad-then-answer (compute interval inline before final answer)
+ *   beats single-call on these.
+ * - `preference-recommendation`: "any tips for X" / "do you have ideas".
+ *   Reader must reference user-specific context from the evidence;
+ *   single-call with a personalization rule works.
+ * - `abstention-candidate`: question is likely unanswerable from the
+ *   evidence (adversarial, off-topic). Commit-vs-abstain forces the
+ *   reader to pick refuse-or-commit explicitly before generating prose.
+ */
+export type ReadIntent = (typeof READ_INTENTS)[number];
+/**
+ * Reader strategies. Different prompt scaffolds + call counts.
+ *
+ * - `single-call`: one reader.invoke call. Cheapest, fastest. Default
+ *   for precise-fact and preference-recommendation intents.
+ * - `two-call-extract-answer`: first call extracts relevant claims from
+ *   evidence; second call answers using the extracted claims. Reduces
+ *   distractor influence on multi-source synthesis. Emergence Simple
+ *   pattern.
+ * - `commit-vs-abstain`: an explicit upfront binary judgment ("can this
+ *   evidence answer the question? yes/no") before generating prose.
+ *   Reduces over-commit on abstention-candidate questions.
+ * - `verbatim-citation`: appends a verbatim-citation rule to the system
+ *   prompt for KU/SSU-style questions where the answer should be a
+ *   direct quote from the evidence.
+ * - `scratchpad-then-answer`: writes a short scratchpad before the final
+ *   answer line. Best for temporal-reasoning where date arithmetic
+ *   benefits from explicit reasoning.
+ */
+export type ReadStrategyId = 'single-call' | 'two-call-extract-answer' | 'commit-vs-abstain' | 'verbatim-citation' | 'scratchpad-then-answer';
+export type ReadRouterPreset = 'precise-fact' | 'synthesis' | 'temporal';
+export interface ReadRoutingTable {
+    readonly preset: ReadRouterPreset;
+    readonly defaultMapping: Readonly<Record<ReadIntent, ReadStrategyId>>;
+}
+/**
+ * Preset: precise-fact (default for fact-recall workloads).
+ *
+ * Precise facts get single-call (cheap, accurate when evidence is clear).
+ * Synthesis gets two-call extract-then-answer. Time intervals get
+ * scratchpad. Preferences get single-call. Abstention candidates get the
+ * explicit commit-vs-abstain decision.
+ */
+export declare const PRECISE_FACT_TABLE: ReadRoutingTable;
+/**
+ * Preset: synthesis (synthesis-heavy workloads).
+ *
+ * Routes more aggressively to two-call extract-then-answer for both
+ * synthesis and precise-fact (the extract pass cleans up noisy evidence).
+ * Verbatim citation for KU/SSU-style precise facts to reduce paraphrase
+ * loss. Higher cost, higher fidelity.
+ */
+export declare const SYNTHESIS_TABLE: ReadRoutingTable;
+/**
+ * Preset: temporal (time-heavy workloads).
+ *
+ * Almost everything goes through scratchpad-then-answer because the
+ * scratchpad's date-arithmetic discipline transfers to non-temporal
+ * questions about WHEN events happened.
+ */
+export declare const TEMPORAL_TABLE: ReadRoutingTable;
+export declare const PRESET_READ_TABLES: Readonly<Record<ReadRouterPreset, ReadRoutingTable>>;
+//# sourceMappingURL=routing-tables.d.ts.map

package/dist/read-router/routing-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.d.ts","sourceRoot":"","sources":["../../src/read-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,YAAY,2HAMf,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,yBAAyB,GACzB,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,CAAC;AAE7B,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,WAAW,GACX,UAAU,CAAC;AAEf,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;CACvE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,gBASX,CAAC;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,gBASR,CAAC;AAEvB;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,gBASP,CAAC;AAEvB,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CACvC,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAK1C,CAAC"}

package/dist/read-router/routing-tables.js

@@ -0,0 +1,79 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link ReadRouter}.
+ *
+ * ReadRouter is the read-stage sibling of MemoryRouter (recall-stage)
+ * and IngestRouter (input-stage). It picks a reader strategy after
+ * retrieval has produced candidate evidence — single-call generation
+ * vs two-call extract-then-answer (Emergence pattern) vs commit-vs-
+ * abstain (explicit binary decision before answer) vs verbatim citation
+ * vs scratchpad-then-answer (chain-of-thought-lite for temporal questions).
+ *
+ * @module @framers/agentos/read-router/routing-tables
+ */
+export const READ_INTENTS = [
+    'precise-fact',
+    'multi-source-synthesis',
+    'time-interval',
+    'preference-recommendation',
+    'abstention-candidate',
+];
+/**
+ * Preset: precise-fact (default for fact-recall workloads).
+ *
+ * Precise facts get single-call (cheap, accurate when evidence is clear).
+ * Synthesis gets two-call extract-then-answer. Time intervals get
+ * scratchpad. Preferences get single-call. Abstention candidates get the
+ * explicit commit-vs-abstain decision.
+ */
+export const PRECISE_FACT_TABLE = Object.freeze({
+    preset: 'precise-fact',
+    defaultMapping: Object.freeze({
+        'precise-fact': 'single-call',
+        'multi-source-synthesis': 'two-call-extract-answer',
+        'time-interval': 'scratchpad-then-answer',
+        'preference-recommendation': 'single-call',
+        'abstention-candidate': 'commit-vs-abstain',
+    }),
+});
+/**
+ * Preset: synthesis (synthesis-heavy workloads).
+ *
+ * Routes more aggressively to two-call extract-then-answer for both
+ * synthesis and precise-fact (the extract pass cleans up noisy evidence).
+ * Verbatim citation for KU/SSU-style precise facts to reduce paraphrase
+ * loss. Higher cost, higher fidelity.
+ */
+export const SYNTHESIS_TABLE = Object.freeze({
+    preset: 'synthesis',
+    defaultMapping: Object.freeze({
+        'precise-fact': 'verbatim-citation',
+        'multi-source-synthesis': 'two-call-extract-answer',
+        'time-interval': 'scratchpad-then-answer',
+        'preference-recommendation': 'two-call-extract-answer',
+        'abstention-candidate': 'commit-vs-abstain',
+    }),
+});
+/**
+ * Preset: temporal (time-heavy workloads).
+ *
+ * Almost everything goes through scratchpad-then-answer because the
+ * scratchpad's date-arithmetic discipline transfers to non-temporal
+ * questions about WHEN events happened.
+ */
+export const TEMPORAL_TABLE = Object.freeze({
+    preset: 'temporal',
+    defaultMapping: Object.freeze({
+        'precise-fact': 'scratchpad-then-answer',
+        'multi-source-synthesis': 'scratchpad-then-answer',
+        'time-interval': 'scratchpad-then-answer',
+        'preference-recommendation': 'single-call',
+        'abstention-candidate': 'commit-vs-abstain',
+    }),
+});
+export const PRESET_READ_TABLES = Object.freeze({
+    'precise-fact': PRECISE_FACT_TABLE,
+    synthesis: SYNTHESIS_TABLE,
+    temporal: TEMPORAL_TABLE,
+});
+//# sourceMappingURL=routing-tables.js.map

package/dist/read-router/routing-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.js","sourceRoot":"","sources":["../../src/read-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,cAAc;IACd,wBAAwB;IACxB,eAAe;IACf,2BAA2B;IAC3B,sBAAsB;CACd,CAAC;AAyDX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAqB,MAAM,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,cAAuB;IAC/B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,cAAc,EAAE,aAAa;QAC7B,wBAAwB,EAAE,yBAAyB;QACnD,eAAe,EAAE,wBAAwB;QACzC,2BAA2B,EAAE,aAAa;QAC1C,sBAAsB,EAAE,mBAAmB;KAC5C,CAAC;CACH,CAAqB,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqB,MAAM,CAAC,MAAM,CAAC;IAC7D,MAAM,EAAE,WAAoB;IAC5B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,cAAc,EAAE,mBAAmB;QACnC,wBAAwB,EAAE,yBAAyB;QACnD,eAAe,EAAE,wBAAwB;QACzC,2BAA2B,EAAE,yBAAyB;QACtD,sBAAsB,EAAE,mBAAmB;KAC5C,CAAC;CACH,CAAqB,CAAC;AAEvB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAqB,MAAM,CAAC,MAAM,CAAC;IAC5D,MAAM,EAAE,UAAmB;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,cAAc,EAAE,wBAAwB;QACxC,wBAAwB,EAAE,wBAAwB;QAClD,eAAe,EAAE,wBAAwB;QACzC,2BAA2B,EAAE,aAAa;QAC1C,sBAAsB,EAAE,mBAAmB;KAC5C,CAAC;CACH,CAAqB,CAAC;AAEvB,MAAM,CAAC,MAAM,kBAAkB,GAE3B,MAAM,CAAC,MAAM,CAAC;IAChB,cAAc,EAAE,kBAAkB;IAClC,SAAS,EAAE,eAAe;IAC1B,QAAQ,EAAE,cAAc;CACzB,CAAC,CAAC"}

package/dist/read-router/select-strategy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file select-strategy.ts
+ * @description Pure selection function for ReadRouter. Mirrors the
+ * memory-router and ingest-router patterns.
+ *
+ * @module @framers/agentos/read-router/select-strategy
+ */
+import type { ReadStrategyCostPoint } from './costs.js';
+import type { ReadIntent, ReadRouterPreset, ReadRoutingTable, ReadStrategyId } from './routing-tables.js';
+export type ReadBudgetMode = 'hard' | 'soft' | 'cheapest-fallback';
+export interface ReadRouterConfig {
+    readonly table: ReadRoutingTable;
+    readonly budgetPerReadUsd: number | null;
+    readonly budgetMode: ReadBudgetMode;
+    readonly strategyCosts: Readonly<Record<ReadStrategyId, ReadStrategyCostPoint>>;
+}
+export interface ReadRoutingDecision {
+    readonly predictedIntent: ReadIntent;
+    readonly groundTruthIntent: ReadIntent | null;
+    readonly chosenStrategy: ReadStrategyId;
+    readonly chosenStrategyReason: string;
+    readonly estimatedCostUsd: number;
+    readonly budgetCeiling: number | null;
+    readonly budgetExceeded: boolean;
+    readonly preset: ReadRouterPreset;
+}
+export declare class ReadRouterUnknownIntentError extends Error {
+    readonly intent: string;
+    constructor(intent: string);
+}
+export declare class ReadRouterBudgetExceededError extends Error {
+    readonly strategy: ReadStrategyId;
+    readonly cost: number;
+    readonly budget: number;
+    constructor(strategy: ReadStrategyId, cost: number, budget: number);
+}
+export declare function selectReadStrategy(args: {
+    predictedIntent: ReadIntent;
+    groundTruthIntent: ReadIntent | null;
+    config: ReadRouterConfig;
+}): ReadRoutingDecision;
+//# sourceMappingURL=select-strategy.d.ts.map

package/dist/read-router/select-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-strategy.d.ts","sourceRoot":"","sources":["../../src/read-router/select-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACf,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED,qBAAa,4BAA6B,SAAQ,KAAK;aACzB,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAI3C;AAED,qBAAa,6BAA8B,SAAQ,KAAK;aAEpC,QAAQ,EAAE,cAAc;aACxB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAFd,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAQjC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,eAAe,EAAE,UAAU,CAAC;IAC5B,iBAAiB,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC,MAAM,EAAE,gBAAgB,CAAC;CAC1B,GAAG,mBAAmB,CAoFtB"}

package/dist/read-router/select-strategy.js

@@ -0,0 +1,92 @@
+/**
+ * @file select-strategy.ts
+ * @description Pure selection function for ReadRouter. Mirrors the
+ * memory-router and ingest-router patterns.
+ *
+ * @module @framers/agentos/read-router/select-strategy
+ */
+export class ReadRouterUnknownIntentError extends Error {
+    constructor(intent) {
+        super(`ReadRouter: intent '${intent}' not in routing table`);
+        this.intent = intent;
+        this.name = 'ReadRouterUnknownIntentError';
+    }
+}
+export class ReadRouterBudgetExceededError extends Error {
+    constructor(strategy, cost, budget) {
+        super(`ReadRouter: strategy '${strategy}' cost $${cost.toFixed(4)} ` +
+            `exceeds hard budget $${budget.toFixed(4)}`);
+        this.strategy = strategy;
+        this.cost = cost;
+        this.budget = budget;
+        this.name = 'ReadRouterBudgetExceededError';
+    }
+}
+export function selectReadStrategy(args) {
+    const { predictedIntent, groundTruthIntent, config } = args;
+    const { table, budgetPerReadUsd, budgetMode, strategyCosts } = config;
+    const picked = table.defaultMapping[predictedIntent];
+    if (!picked) {
+        throw new ReadRouterUnknownIntentError(predictedIntent);
+    }
+    const pickedCost = strategyCosts[picked].avgCostPerReadUsd;
+    if (budgetPerReadUsd === null || pickedCost <= budgetPerReadUsd) {
+        return {
+            predictedIntent,
+            groundTruthIntent,
+            chosenStrategy: picked,
+            chosenStrategyReason: budgetPerReadUsd === null
+                ? 'routing-table pick, no budget'
+                : 'routing-table pick fits budget',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerReadUsd,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    if (budgetMode === 'hard') {
+        throw new ReadRouterBudgetExceededError(picked, pickedCost, budgetPerReadUsd);
+    }
+    const candidates = Object.values(strategyCosts).map((c) => ({
+        strategy: c.strategy,
+        cost: c.avgCostPerReadUsd,
+    }));
+    const fits = candidates.filter((c) => c.cost <= budgetPerReadUsd);
+    const cheapestFits = fits.length > 0 ? fits.reduce((a, b) => (a.cost <= b.cost ? a : b)) : null;
+    if (!cheapestFits) {
+        const globallyCheapest = candidates.reduce((a, b) => a.cost <= b.cost ? a : b);
+        return {
+            predictedIntent,
+            groundTruthIntent,
+            chosenStrategy: globallyCheapest.strategy,
+            chosenStrategyReason: 'no strategy fits budget; picking absolute cheapest',
+            estimatedCostUsd: globallyCheapest.cost,
+            budgetCeiling: budgetPerReadUsd,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    if (budgetMode === 'cheapest-fallback') {
+        return {
+            predictedIntent,
+            groundTruthIntent,
+            chosenStrategy: cheapestFits.strategy,
+            chosenStrategyReason: 'budget downgrade (cheapest-fallback mode)',
+            estimatedCostUsd: cheapestFits.cost,
+            budgetCeiling: budgetPerReadUsd,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    return {
+        predictedIntent,
+        groundTruthIntent,
+        chosenStrategy: picked,
+        chosenStrategyReason: 'soft exceed: keeping picked despite budget breach',
+        estimatedCostUsd: pickedCost,
+        budgetCeiling: budgetPerReadUsd,
+        budgetExceeded: true,
+        preset: table.preset,
+    };
+}
+//# sourceMappingURL=select-strategy.js.map

package/dist/read-router/select-strategy.js.map

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