@framers/agentos 0.2.7 → 0.2.9

package/dist/memory-router/adaptive.js

@@ -0,0 +1,202 @@
+/**
+ * @file adaptive.ts
+ * @description Self-calibrating routing-table generator.
+ *
+ * The shipping {@link MINIMIZE_COST_TABLE} / {@link BALANCED_TABLE} /
+ * {@link MAXIMIZE_ACCURACY_TABLE} are calibrated from LongMemEval-S
+ * Phase B N=500 measurements. For workloads whose cost-accuracy profile
+ * diverges from that distribution, those tables are not optimal.
+ *
+ * AdaptiveMemoryRouter takes a workload-specific calibration dataset
+ * (a list of {category, backend, costUsd, correct} samples) and derives
+ * a routing table from it. Same MemoryRouter API; different table
+ * source.
+ *
+ * Calibration workflow:
+ *   1. Run a Phase A sweep on your workload (a few hundred queries
+ *      across a small subset of expected categories, dispatched to all
+ *      candidate backends).
+ *   2. Each sample contributes one (category, backend, costUsd, correct)
+ *      data point.
+ *   3. AdaptiveMemoryRouter aggregates these into per-(category, backend)
+ *      mean cost + mean accuracy.
+ *   4. Apply a preset selection rule:
+ *        - 'minimize-cost': cheapest backend within 2pp of best accuracy;
+ *          if none within tolerance, pick best accuracy.
+ *        - 'maximize-accuracy': highest accuracy; ties broken by cost.
+ *        - 'balanced': best $/correct (mean cost divided by mean
+ *          accuracy).
+ *   5. Categories with insufficient samples fall back to the static
+ *      preset table.
+ *
+ * The router is otherwise identical to {@link MemoryRouter} — same
+ * decide() / decideAndDispatch() / budget-aware dispatch.
+ *
+ * @module @framers/agentos/memory-router/adaptive
+ */
+import { MemoryRouter } from './MemoryRouter.js';
+import { PRESET_TABLES, } from './routing-tables.js';
+// ============================================================================
+// Aggregation
+// ============================================================================
+/**
+ * Roll up raw calibration samples into per-(category, backend) cells.
+ * Each cell carries n, meanCost, meanAccuracy.
+ */
+export function aggregateCalibration(samples) {
+    const acc = {};
+    for (const s of samples) {
+        if (!acc[s.category])
+            acc[s.category] = {};
+        if (!acc[s.category][s.backend]) {
+            acc[s.category][s.backend] = { n: 0, sumCost: 0, sumCorrect: 0 };
+        }
+        const cell = acc[s.category][s.backend];
+        cell.n += 1;
+        cell.sumCost += s.costUsd;
+        cell.sumCorrect += s.correct;
+    }
+    const out = {};
+    for (const cat of Object.keys(acc)) {
+        out[cat] = {};
+        const inner = out[cat];
+        for (const backend of Object.keys(acc[cat])) {
+            const cell = acc[cat][backend];
+            inner[backend] = {
+                n: cell.n,
+                meanCost: cell.sumCost / cell.n,
+                meanAccuracy: cell.sumCorrect / cell.n,
+            };
+        }
+    }
+    return out;
+}
+// ============================================================================
+// Per-category selection
+// ============================================================================
+/**
+ * Select a backend for one category from aggregated calibration data
+ * using the named preset rule. Falls back to the preset's static table
+ * when calibration is insufficient.
+ */
+export function selectByPreset(args) {
+    const { category, agg, preset, minSamplesPerCell = 1, accuracyTolerance = 0.02, } = args;
+    const fallbackTable = PRESET_TABLES[preset];
+    const fallback = fallbackTable.defaultMapping[category];
+    const cells = agg[category];
+    if (!cells)
+        return fallback;
+    // Filter cells meeting min-sample threshold.
+    const eligible = Object.entries(cells)
+        .filter(([, cell]) => cell.n >= minSamplesPerCell);
+    if (eligible.length === 0)
+        return fallback;
+    if (preset === 'maximize-accuracy') {
+        return eligible.reduce((best, [backend, cell]) => {
+            const [bestBackend, bestCell] = best;
+            if (cell.meanAccuracy > bestCell.meanAccuracy)
+                return [backend, cell];
+            if (cell.meanAccuracy === bestCell.meanAccuracy) {
+                return cell.meanCost < bestCell.meanCost ? [backend, cell] : best;
+            }
+            return best;
+        }, eligible[0])[0];
+    }
+    if (preset === 'balanced') {
+        // best $/correct (skip zero-accuracy cells to avoid div-by-zero)
+        const valid = eligible.filter(([, cell]) => cell.meanAccuracy > 0);
+        if (valid.length === 0)
+            return fallback;
+        return valid.reduce((best, [backend, cell]) => {
+            const [bestBackend, bestCell] = best;
+            const cellCpc = cell.meanCost / cell.meanAccuracy;
+            const bestCpc = bestCell.meanCost / bestCell.meanAccuracy;
+            return cellCpc < bestCpc ? [backend, cell] : best;
+        }, valid[0])[0];
+    }
+    // minimize-cost: cheapest within accuracyTolerance of best accuracy.
+    const bestAccuracy = Math.max(...eligible.map(([, cell]) => cell.meanAccuracy));
+    const withinTolerance = eligible.filter(([, cell]) => bestAccuracy - cell.meanAccuracy <= accuracyTolerance);
+    if (withinTolerance.length === 0) {
+        // No candidates within tolerance is impossible (the best-accuracy
+        // backend itself qualifies), but guard anyway.
+        return fallback;
+    }
+    return withinTolerance.reduce((best, [backend, cell]) => {
+        const [bestBackend, bestCell] = best;
+        return cell.meanCost < bestCell.meanCost ? [backend, cell] : best;
+    }, withinTolerance[0])[0];
+}
+// ============================================================================
+// Table construction
+// ============================================================================
+const ALL_CATEGORIES = [
+    'single-session-user',
+    'single-session-assistant',
+    'single-session-preference',
+    'knowledge-update',
+    'multi-session',
+    'temporal-reasoning',
+];
+/**
+ * Build a complete frozen routing table from calibration samples + a
+ * preset rule. Categories without enough calibration fall back to the
+ * preset's static table.
+ */
+export function buildAdaptiveRoutingTable(args) {
+    const { samples, preset, minSamplesPerCell, accuracyTolerance, fallbackTable, } = args;
+    const agg = aggregateCalibration(samples);
+    const fb = fallbackTable ?? PRESET_TABLES[preset];
+    const mapping = {};
+    for (const cat of ALL_CATEGORIES) {
+        mapping[cat] = selectByPreset({
+            category: cat,
+            agg,
+            preset,
+            minSamplesPerCell,
+            accuracyTolerance,
+        });
+        // selectByPreset falls back to the preset's STATIC default mapping,
+        // not the caller-supplied fallback table. Apply the explicit
+        // fallback only when the static fallback wasn't applied because of
+        // missing data — easiest is to override after the fact.
+        if (!agg[cat] && fb !== PRESET_TABLES[preset]) {
+            mapping[cat] = fb.defaultMapping[cat];
+        }
+    }
+    return Object.freeze({
+        preset: preset,
+        defaultMapping: Object.freeze(mapping),
+    });
+}
+// ============================================================================
+// AdaptiveMemoryRouter class
+// ============================================================================
+/**
+ * Memory router whose routing table is derived from a calibration
+ * dataset rather than a static preset. Otherwise identical API to
+ * {@link MemoryRouter}.
+ */
+export class AdaptiveMemoryRouter extends MemoryRouter {
+    constructor(options) {
+        const derivedTable = buildAdaptiveRoutingTable({
+            samples: options.calibrationSamples,
+            preset: options.preset,
+            minSamplesPerCell: options.minSamplesPerCell,
+            accuracyTolerance: options.accuracyTolerance,
+        });
+        super({
+            ...options,
+            preset: options.preset,
+            routingTable: derivedTable,
+        });
+        this.derivedTable = derivedTable;
+    }
+    /**
+     * Inspect the derived routing table for debugging / telemetry.
+     */
+    getRoutingTable() {
+        return this.derivedTable;
+    }
+}
+//# sourceMappingURL=adaptive.js.map

package/dist/memory-router/adaptive.js.map

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

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

@@ -121,4 +121,6 @@ export { selectBackend, MemoryRouterUnknownCategoryError, MemoryRouterBudgetExce
 export { CLASSIFIER_SYSTEM_PROMPT, CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_FALLBACK_CATEGORY, LLMMemoryClassifier, normalizeClassifierOutput, parseClassifierOutput, } from './classifier.js';
 export { FunctionMemoryDispatcher, UnsupportedMemoryBackendError, } from './dispatcher.js';
 export { MemoryRouter, MemoryRouterDispatcherMissingError, } from './MemoryRouter.js';
+export type { CalibrationSample, CalibrationCell, AggregatedCalibration, AdaptivePresetRule, SelectByPresetArgs, BuildAdaptiveRoutingTableArgs, AdaptiveMemoryRouterOptions, } from './adaptive.js';
+export { aggregateCalibration, selectByPreset, buildAdaptiveRoutingTable, AdaptiveMemoryRouter, } from './adaptive.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAMH,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,YAAY,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,kCAAkC,GACnC,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAMH,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,YAAY,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,kCAAkC,GACnC,MAAM,mBAAmB,CAAC;AAM3B,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}

package/dist/memory-router/index.js

@@ -118,4 +118,5 @@ export { selectBackend, MemoryRouterUnknownCategoryError, MemoryRouterBudgetExce
 export { CLASSIFIER_SYSTEM_PROMPT, CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_FALLBACK_CATEGORY, LLMMemoryClassifier, normalizeClassifierOutput, parseClassifierOutput, } from './classifier.js';
 export { FunctionMemoryDispatcher, UnsupportedMemoryBackendError, } from './dispatcher.js';
 export { MemoryRouter, MemoryRouterDispatcherMissingError, } from './MemoryRouter.js';
+export { aggregateCalibration, selectByPreset, buildAdaptiveRoutingTable, AdaptiveMemoryRouter, } from './adaptive.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAYH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAoC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,kCAAkC,GACnC,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAYH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAoC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,kCAAkC,GACnC,MAAM,mBAAmB,CAAC;AAgB3B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}

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

@@ -0,0 +1,58 @@
+/**
+ * @file ReadRouter.ts
+ * @description Top-level read-stage orchestrator composing the read-intent
+ * classifier with the pure {@link selectReadStrategy} into a single
+ * per-query routing call.
+ *
+ * @module @framers/agentos/read-router/ReadRouter
+ */
+import type { IReadIntentClassifier, ReadIntentClassifierResult } from './classifier.js';
+import { type ReadStrategyCostPoint } from './costs.js';
+import { type ReadIntent, type ReadRouterPreset, type ReadRoutingTable, type ReadStrategyId } from './routing-tables.js';
+import { type ReadBudgetMode, type ReadRoutingDecision } from './select-strategy.js';
+import type { IReadDispatcher } from './dispatcher.js';
+export interface ReadBudgetPolicy {
+    readonly perReadUsd?: number;
+    readonly mode?: ReadBudgetMode;
+}
+export interface ReadRouterOptions {
+    readonly classifier: IReadIntentClassifier;
+    readonly preset?: ReadRouterPreset;
+    readonly routingTable?: ReadRoutingTable;
+    readonly mapping?: Partial<Record<ReadIntent, ReadStrategyId>>;
+    readonly budget?: ReadBudgetPolicy;
+    readonly strategyCosts?: Readonly<Record<ReadStrategyId, ReadStrategyCostPoint>>;
+    readonly useFewShotPrompt?: boolean;
+    readonly dispatcher?: IReadDispatcher<unknown, unknown>;
+}
+export interface ReadRouterDecideOptions {
+    readonly manualIntent?: ReadIntent;
+    readonly groundTruthIntent?: ReadIntent | null;
+    readonly useFewShotPrompt?: boolean;
+}
+export interface ReadRouterDecision {
+    readonly classifier: ReadIntentClassifierResult;
+    readonly routing: ReadRoutingDecision;
+}
+export interface ReadRouterDispatchedResult<TOutcome> {
+    readonly decision: ReadRouterDecision;
+    readonly outcome: TOutcome;
+    readonly strategy: ReadStrategyId;
+}
+export declare class ReadRouterDispatcherMissingError extends Error {
+    constructor();
+}
+export declare class ReadRouter {
+    private readonly classifier;
+    private readonly preset;
+    private readonly routingTable;
+    private readonly budgetPerReadUsd;
+    private readonly budgetMode;
+    private readonly strategyCosts;
+    private readonly defaultUseFewShotPrompt;
+    private readonly dispatcher;
+    constructor(options: ReadRouterOptions);
+    decide(query: string, evidence: readonly string[], options?: ReadRouterDecideOptions): Promise<ReadRouterDecision>;
+    decideAndDispatch<TOutcome, TPayload = undefined>(query: string, evidence: readonly string[], dispatchPayload?: TPayload, options?: ReadRouterDecideOptions): Promise<ReadRouterDispatchedResult<TOutcome>>;
+}
+//# sourceMappingURL=ReadRouter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReadRouter.d.ts","sourceRoot":"","sources":["../../src/read-router/ReadRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAC/B,MAAM,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAC9C,CAAC;IACF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACvC;AAED,MAAM,WAAW,0BAA0B,CAAC,QAAQ;IAClD,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAED,qBAAa,gCAAiC,SAAQ,KAAK;;CAQ1D;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAE5B;IACF,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2C;gBAE1D,OAAO,EAAE,iBAAiB;IA4BhC,MAAM,CACV,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,kBAAkB,CAAC;IAiCxB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EACpD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,eAAe,CAAC,EAAE,QAAQ,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,0BAA0B,CAAC,QAAQ,CAAC,CAAC;CAmBjD"}

package/dist/read-router/ReadRouter.js

@@ -0,0 +1,91 @@
+/**
+ * @file ReadRouter.ts
+ * @description Top-level read-stage orchestrator composing the read-intent
+ * classifier with the pure {@link selectReadStrategy} into a single
+ * per-query routing call.
+ *
+ * @module @framers/agentos/read-router/ReadRouter
+ */
+import { DEFAULT_READ_COSTS } from './costs.js';
+import { PRESET_READ_TABLES, } from './routing-tables.js';
+import { selectReadStrategy, } from './select-strategy.js';
+export class ReadRouterDispatcherMissingError extends Error {
+    constructor() {
+        super('ReadRouter.decideAndDispatch requires a dispatcher. ' +
+            'Either pass a dispatcher in options or call `decide` and dispatch yourself.');
+        this.name = 'ReadRouterDispatcherMissingError';
+    }
+}
+export class ReadRouter {
+    constructor(options) {
+        this.classifier = options.classifier;
+        this.preset = options.preset ?? 'precise-fact';
+        this.dispatcher = options.dispatcher ?? null;
+        const baseTable = options.routingTable ?? PRESET_READ_TABLES[this.preset];
+        if (options.mapping) {
+            const patched = {
+                ...baseTable.defaultMapping,
+            };
+            for (const key of Object.keys(options.mapping)) {
+                const ov = options.mapping[key];
+                if (ov)
+                    patched[key] = ov;
+            }
+            this.routingTable = Object.freeze({
+                preset: baseTable.preset,
+                defaultMapping: Object.freeze(patched),
+            });
+        }
+        else {
+            this.routingTable = baseTable;
+        }
+        this.budgetPerReadUsd = options.budget?.perReadUsd ?? null;
+        this.budgetMode = options.budget?.mode ?? 'cheapest-fallback';
+        this.strategyCosts = options.strategyCosts ?? DEFAULT_READ_COSTS;
+        this.defaultUseFewShotPrompt = options.useFewShotPrompt ?? false;
+    }
+    async decide(query, evidence, options) {
+        let classifier;
+        if (options?.manualIntent) {
+            classifier = {
+                intent: options.manualIntent,
+                tokensIn: 0,
+                tokensOut: 0,
+                model: 'manual',
+            };
+        }
+        else {
+            const useFewShot = options?.useFewShotPrompt ?? this.defaultUseFewShotPrompt;
+            classifier = await this.classifier.classify(query, evidence, useFewShot ? { useFewShotPrompt: true } : undefined);
+        }
+        const routing = selectReadStrategy({
+            predictedIntent: classifier.intent,
+            groundTruthIntent: options?.groundTruthIntent ?? null,
+            config: {
+                table: this.routingTable,
+                budgetPerReadUsd: this.budgetPerReadUsd,
+                budgetMode: this.budgetMode,
+                strategyCosts: this.strategyCosts,
+            },
+        });
+        return { classifier, routing };
+    }
+    async decideAndDispatch(query, evidence, dispatchPayload, options) {
+        if (!this.dispatcher) {
+            throw new ReadRouterDispatcherMissingError();
+        }
+        const decision = await this.decide(query, evidence, options);
+        const dispatched = (await this.dispatcher.dispatch({
+            strategy: decision.routing.chosenStrategy,
+            query,
+            evidence,
+            payload: dispatchPayload,
+        }));
+        return {
+            decision,
+            outcome: dispatched.outcome,
+            strategy: dispatched.strategy,
+        };
+    }
+}
+//# sourceMappingURL=ReadRouter.js.map

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * @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 { type ReadIntent } from './routing-tables.js';
+export interface ReadIntentClassifierLLMRequest {
+    readonly system: string;
+    readonly user: string;
+    readonly maxTokens: number;
+    readonly temperature: number;
+}
+export interface ReadIntentClassifierLLMResponse {
+    readonly text: string;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly model: string;
+}
+export interface IReadIntentClassifierLLM {
+    invoke(request: ReadIntentClassifierLLMRequest): Promise<ReadIntentClassifierLLMResponse>;
+}
+export interface ReadIntentClassifierClassifyOptions {
+    readonly useFewShotPrompt?: boolean;
+}
+export interface ReadIntentClassifierResult {
+    readonly intent: ReadIntent;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly model: string;
+}
+export interface IReadIntentClassifier {
+    classify(query: string, evidence: readonly string[], options?: ReadIntentClassifierClassifyOptions): Promise<ReadIntentClassifierResult>;
+}
+export declare const READ_INTENT_CLASSIFIER_SYSTEM_PROMPT = "You are classifying a user query (with retrieved evidence) into one of five read intents.\n\nReturn ONLY the intent token (no explanation, no quotes, no punctuation).\n\nIntents:\n- precise-fact: the user wants a specific named entity, number, date, or fact. Examples: \"What is X's email?\", \"When was the last release?\"\n- multi-source-synthesis: the answer requires combining information from multiple evidence chunks. Examples: \"Summarize all the topics we discussed\", \"Aggregate counts across sessions.\"\n- 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?\"\n- preference-recommendation: the user wants tips, suggestions, advice, or recommendations grounded in their own context. Examples: \"Any tips for X?\", \"Can you suggest Y?\"\n- 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 declare const READ_INTENT_CLASSIFIER_SYSTEM_PROMPT_FEWSHOT = "You are classifying a user query (with retrieved evidence) into one of five read intents.\n\nReturn ONLY the intent token (no explanation, no quotes, no punctuation).\n\nIntents:\n- precise-fact: a specific named entity, number, date, or fact.\n- multi-source-synthesis: combining information across multiple evidence chunks.\n- time-interval: durations, orderings, or \"how long ago\".\n- preference-recommendation: tips / suggestions / advice grounded in user context.\n- abstention-candidate: question may be unanswerable from evidence.\n\nExamples:\n\nQuestion: What was my final boss's name in the game I played last week?\nIntent: precise-fact\n\nQuestion: What topics did we discuss across our last five conversations?\nIntent: multi-source-synthesis\n\nQuestion: How many weeks have passed since I started the new job?\nIntent: time-interval\n\nQuestion: Any tips for improving my morning routine?\nIntent: preference-recommendation\n\nQuestion: Where did I move to four years ago?\nIntent: abstention-candidate";
+export declare const SAFE_READ_INTENT_FALLBACK: ReadIntent;
+export declare function normalizeReadIntentClassifierOutput(raw: string): string;
+export declare function parseReadIntentClassifierOutput(raw: string): ReadIntent;
+export interface LLMReadIntentClassifierOptions {
+    readonly llm: IReadIntentClassifierLLM;
+    readonly maxTokens?: number;
+    /** Max evidence-preview chars forwarded to the classifier. Default 600. */
+    readonly maxEvidenceChars?: number;
+}
+export declare class LLMReadIntentClassifier implements IReadIntentClassifier {
+    private readonly llm;
+    private readonly maxTokens;
+    private readonly maxEvidenceChars;
+    constructor(options: LLMReadIntentClassifierOptions);
+    classify(query: string, evidence: readonly string[], options?: ReadIntentClassifierClassifyOptions): Promise<ReadIntentClassifierResult>;
+}
+//# sourceMappingURL=classifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../src/read-router/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMpE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CACJ,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,+BAA+B,CAAC,CAAC;CAC7C;AAMD,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,CAAC,EAAE,mCAAmC,GAC5C,OAAO,CAAC,0BAA0B,CAAC,CAAC;CACxC;AAMD,eAAO,MAAM,oCAAoC,8hCAS6H,CAAC;AAE/K,eAAO,MAAM,4CAA4C,ggCA0B5B,CAAC;AAE9B,eAAO,MAAM,yBAAyB,EAAE,UAAqC,CAAC;AAE9E,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAcvE;AAED,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAYvE;AAMD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,GAAG,EAAE,wBAAwB,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,qBAAa,uBAAwB,YAAW,qBAAqB;IACnE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA2B;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,EAAE,8BAA8B;IAM7C,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,CAAC,EAAE,mCAAmC,GAC5C,OAAO,CAAC,0BAA0B,CAAC;CAuBvC"}

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"}