@framers/agentos 0.2.7 → 0.2.9

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

@@ -0,0 +1,145 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link IngestRouter}.
+ *
+ * IngestRouter is the input-stage sibling of MemoryRouter. Where MemoryRouter
+ * picks the recall architecture for a query, IngestRouter picks the storage
+ * architecture for incoming content. The choice affects what's STORED, which
+ * downstream MemoryRouter then queries.
+ *
+ * Four shipping presets express different cost-vs-recall priorities:
+ *
+ * - {@link RAW_CHUNKS_TABLE}: stores everything as raw chunks. Cheapest at
+ *   ingest time. Pushes all complexity to retrieval. Default for cost-
+ *   sensitive workloads.
+ * - {@link SUMMARIZED_TABLE}: applies session/article summarization on long
+ *   content. Anthropic-style "contextual retrieval" — every chunk gets a
+ *   dense session-summary prefix before embedding.
+ * - {@link OBSERVATIONAL_TABLE}: extracts observation logs (Mastra-style)
+ *   from long conversational content. Most expensive at ingest, best for
+ *   multi-session synthesis recall.
+ * - {@link HYBRID_TABLE}: applies multiple ingest strategies in parallel
+ *   for long content (raw chunks + summary + observations). Highest cost,
+ *   highest recall flexibility — every retrieval strategy has its substrate.
+ *
+ * @module @framers/agentos/ingest-router/routing-tables
+ */
+// ============================================================================
+// Types
+// ============================================================================
+/**
+ * The six content kinds the LLM-as-judge ingest classifier can emit.
+ * Coarse taxonomy chosen to map cleanly onto distinct ingest strategies —
+ * extending the taxonomy means extending the routing tables consistently.
+ */
+export const INGEST_CONTENT_KINDS = [
+    'short-conversation',
+    'long-conversation',
+    'long-article',
+    'code',
+    'structured-data',
+    'multimodal',
+];
+// ============================================================================
+// Preset tables
+// ============================================================================
+/**
+ * Preset: raw-chunks (default for cost-sensitive workloads).
+ *
+ * Stores everything as raw chunks regardless of content kind. Zero LLM
+ * cost at ingest time. All complexity is pushed to retrieval where the
+ * MemoryRouter can compose hybrid retrieval over the raw chunks.
+ *
+ * Recommended when: ingest volume is high, retrieval-side compute is
+ * cheap, and you trust the retrieval stage to do the heavy lifting.
+ */
+export const RAW_CHUNKS_TABLE = Object.freeze({
+    preset: 'raw-chunks',
+    defaultMapping: Object.freeze({
+        'short-conversation': 'raw-chunks',
+        'long-conversation': 'raw-chunks',
+        'long-article': 'raw-chunks',
+        code: 'raw-chunks',
+        'structured-data': 'raw-chunks',
+        multimodal: 'raw-chunks',
+    }),
+});
+/**
+ * Preset: summarized (contextual retrieval for long content).
+ *
+ * Long content (long-conversation, long-article) gets a session/document
+ * summary prepended to every chunk before embedding. Short content stays
+ * as raw chunks. Code and structured data are summarized for the
+ * cross-file context. Multimodal stays raw — embedding modality is
+ * orthogonal to summarization.
+ *
+ * Recommended when: documents and conversations have meaningful global
+ * context that improves retrieval recall.
+ */
+export const SUMMARIZED_TABLE = Object.freeze({
+    preset: 'summarized',
+    defaultMapping: Object.freeze({
+        'short-conversation': 'raw-chunks',
+        'long-conversation': 'summarized',
+        'long-article': 'summarized',
+        code: 'summarized',
+        'structured-data': 'raw-chunks',
+        multimodal: 'raw-chunks',
+    }),
+});
+/**
+ * Preset: observational (Mastra-style for multi-session synthesis).
+ *
+ * Long conversational content (long-conversation) becomes a structured
+ * observation log via LLM extraction at ingest. Long articles get the
+ * cheaper summarized treatment. Short content, code, structured, and
+ * multimodal stay raw.
+ *
+ * Recommended when: workload is conversational and includes many
+ * multi-session synthesis questions ("what have we agreed to so far",
+ * "across our chats, what topics recur").
+ */
+export const OBSERVATIONAL_TABLE = Object.freeze({
+    preset: 'observational',
+    defaultMapping: Object.freeze({
+        'short-conversation': 'raw-chunks',
+        'long-conversation': 'observational',
+        'long-article': 'summarized',
+        code: 'raw-chunks',
+        'structured-data': 'raw-chunks',
+        multimodal: 'raw-chunks',
+    }),
+});
+/**
+ * Preset: hybrid (maximum-recall workloads).
+ *
+ * Applies multiple ingest strategies in parallel for long content. Every
+ * downstream retrieval architecture has its substrate (raw chunks for
+ * canonical hybrid, summary prefix for contextual retrieval, observation
+ * log for OM-style synthesis). Highest cost at ingest; highest flexibility
+ * at retrieval.
+ *
+ * Recommended when: cost-per-ingest is acceptable AND retrieval workload
+ * is heterogeneous enough that no single strategy dominates.
+ */
+export const HYBRID_TABLE = Object.freeze({
+    preset: 'hybrid',
+    defaultMapping: Object.freeze({
+        'short-conversation': 'raw-chunks',
+        'long-conversation': 'hybrid',
+        'long-article': 'hybrid',
+        code: 'summarized',
+        'structured-data': 'raw-chunks',
+        multimodal: 'raw-chunks',
+    }),
+});
+/**
+ * Preset registry keyed by name.
+ */
+export const PRESET_INGEST_TABLES = Object.freeze({
+    'raw-chunks': RAW_CHUNKS_TABLE,
+    summarized: SUMMARIZED_TABLE,
+    observational: OBSERVATIONAL_TABLE,
+    hybrid: HYBRID_TABLE,
+});
+//# sourceMappingURL=routing-tables.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.js","sourceRoot":"","sources":["../../src/ingest-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+EAA+E;AAC/E,QAAQ;AACR,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,oBAAoB;IACpB,mBAAmB;IACnB,cAAc;IACd,MAAM;IACN,iBAAiB;IACjB,YAAY;CACJ,CAAC;AAqDX,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuB,MAAM,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,YAAqB;IAC7B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,oBAAoB,EAAE,YAAY;QAClC,mBAAmB,EAAE,YAAY;QACjC,cAAc,EAAE,YAAY;QAC5B,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,YAAY;QAC/B,UAAU,EAAE,YAAY;KACzB,CAAC;CACH,CAAuB,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuB,MAAM,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,YAAqB;IAC7B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,oBAAoB,EAAE,YAAY;QAClC,mBAAmB,EAAE,YAAY;QACjC,cAAc,EAAE,YAAY;QAC5B,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,YAAY;QAC/B,UAAU,EAAE,YAAY;KACzB,CAAC;CACH,CAAuB,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAuB,MAAM,CAAC,MAAM,CAAC;IACnE,MAAM,EAAE,eAAwB;IAChC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,oBAAoB,EAAE,YAAY;QAClC,mBAAmB,EAAE,eAAe;QACpC,cAAc,EAAE,YAAY;QAC5B,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,YAAY;QAC/B,UAAU,EAAE,YAAY;KACzB,CAAC;CACH,CAAuB,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAuB,MAAM,CAAC,MAAM,CAAC;IAC5D,MAAM,EAAE,QAAiB;IACzB,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,oBAAoB,EAAE,YAAY;QAClC,mBAAmB,EAAE,QAAQ;QAC7B,cAAc,EAAE,QAAQ;QACxB,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,YAAY;QAC/B,UAAU,EAAE,YAAY;KACzB,CAAC;CACH,CAAuB,CAAC;AAEzB;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAE7B,MAAM,CAAC,MAAM,CAAC;IAChB,YAAY,EAAE,gBAAgB;IAC9B,UAAU,EAAE,gBAAgB;IAC5B,aAAa,EAAE,mBAAmB;IAClC,MAAM,EAAE,YAAY;CACrB,CAAC,CAAC"}

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

@@ -0,0 +1,67 @@
+/**
+ * @file select-strategy.ts
+ * @description Pure function that picks an ingest strategy from a
+ * predicted content kind + routing table + budget policy.
+ *
+ * Stateless. Deterministic. No I/O. Same shape as
+ * {@link selectBackend} in memory-router so the multi-stage guardrails
+ * orchestrator can compose them uniformly.
+ *
+ * @module @framers/agentos/ingest-router/select-strategy
+ */
+import type { IngestStrategyCostPoint } from './costs.js';
+import type { IngestContentKind, IngestRouterPreset, IngestRoutingTable, IngestStrategyId } from './routing-tables.js';
+/**
+ * Budget enforcement modes for ingest dispatch:
+ *   - `hard`: throw {@link IngestRouterBudgetExceededError} if the
+ *     routing-table pick exceeds the per-ingest USD ceiling.
+ *   - `soft`: keep the picked strategy when the ceiling is exceeded
+ *     (best-effort enforcement; flag exceeded in the decision).
+ *   - `cheapest-fallback`: silently downgrade to the cheapest strategy
+ *     that fits. If none fits, pick the absolute cheapest and flag.
+ */
+export type IngestBudgetMode = 'hard' | 'soft' | 'cheapest-fallback';
+/**
+ * Configuration object for {@link selectIngestStrategy}.
+ */
+export interface IngestRouterConfig {
+    readonly table: IngestRoutingTable;
+    readonly budgetPerIngestUsd: number | null;
+    readonly budgetMode: IngestBudgetMode;
+    readonly strategyCosts: Readonly<Record<IngestStrategyId, IngestStrategyCostPoint>>;
+}
+/**
+ * Output of {@link selectIngestStrategy}. Carries the chosen strategy
+ * plus full telemetry about how the decision was made.
+ */
+export interface IngestRoutingDecision {
+    readonly predictedKind: IngestContentKind;
+    /** Optional ground-truth kind (telemetry only; null in production). */
+    readonly groundTruthKind: IngestContentKind | null;
+    readonly chosenStrategy: IngestStrategyId;
+    readonly chosenStrategyReason: string;
+    readonly estimatedCostUsd: number;
+    readonly budgetCeiling: number | null;
+    readonly budgetExceeded: boolean;
+    readonly preset: IngestRouterPreset;
+}
+export declare class IngestRouterUnknownKindError extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+export declare class IngestRouterBudgetExceededError extends Error {
+    readonly strategy: IngestStrategyId;
+    readonly cost: number;
+    readonly budget: number;
+    constructor(strategy: IngestStrategyId, cost: number, budget: number);
+}
+/**
+ * Pure ingest-strategy selection. Mirrors selectBackend (memory-router)
+ * in structure for multi-stage composability.
+ */
+export declare function selectIngestStrategy(args: {
+    predictedKind: IngestContentKind;
+    groundTruthKind: IngestContentKind | null;
+    config: IngestRouterConfig;
+}): IngestRoutingDecision;
+//# sourceMappingURL=select-strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"select-strategy.d.ts","sourceRoot":"","sources":["../../src/ingest-router/select-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAC9B,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAClD,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC;IAC1C,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,kBAAkB,CAAC;CACrC;AAED,qBAAa,4BAA6B,SAAQ,KAAK;aACzB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAIzC;AAED,qBAAa,+BAAgC,SAAQ,KAAK;aAEtC,QAAQ,EAAE,gBAAgB;aAC1B,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAFd,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAQjC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,aAAa,EAAE,iBAAiB,CAAC;IACjC,eAAe,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,MAAM,EAAE,kBAAkB,CAAC;CAC5B,GAAG,qBAAqB,CAsFxB"}

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

@@ -0,0 +1,100 @@
+/**
+ * @file select-strategy.ts
+ * @description Pure function that picks an ingest strategy from a
+ * predicted content kind + routing table + budget policy.
+ *
+ * Stateless. Deterministic. No I/O. Same shape as
+ * {@link selectBackend} in memory-router so the multi-stage guardrails
+ * orchestrator can compose them uniformly.
+ *
+ * @module @framers/agentos/ingest-router/select-strategy
+ */
+export class IngestRouterUnknownKindError extends Error {
+    constructor(kind) {
+        super(`IngestRouter: kind '${kind}' not in routing table`);
+        this.kind = kind;
+        this.name = 'IngestRouterUnknownKindError';
+    }
+}
+export class IngestRouterBudgetExceededError extends Error {
+    constructor(strategy, cost, budget) {
+        super(`IngestRouter: strategy '${strategy}' cost $${cost.toFixed(4)} ` +
+            `exceeds hard budget $${budget.toFixed(4)}`);
+        this.strategy = strategy;
+        this.cost = cost;
+        this.budget = budget;
+        this.name = 'IngestRouterBudgetExceededError';
+    }
+}
+/**
+ * Pure ingest-strategy selection. Mirrors selectBackend (memory-router)
+ * in structure for multi-stage composability.
+ */
+export function selectIngestStrategy(args) {
+    const { predictedKind, groundTruthKind, config } = args;
+    const { table, budgetPerIngestUsd, budgetMode, strategyCosts } = config;
+    const picked = table.defaultMapping[predictedKind];
+    if (!picked) {
+        throw new IngestRouterUnknownKindError(predictedKind);
+    }
+    const pickedCost = strategyCosts[picked].avgCostPerIngest;
+    if (budgetPerIngestUsd === null || pickedCost <= budgetPerIngestUsd) {
+        return {
+            predictedKind,
+            groundTruthKind,
+            chosenStrategy: picked,
+            chosenStrategyReason: budgetPerIngestUsd === null
+                ? 'routing-table pick, no budget'
+                : 'routing-table pick fits budget',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerIngestUsd,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    if (budgetMode === 'hard') {
+        throw new IngestRouterBudgetExceededError(picked, pickedCost, budgetPerIngestUsd);
+    }
+    const candidates = Object.values(strategyCosts).map((c) => ({ strategy: c.strategy, cost: c.avgCostPerIngest }));
+    const fits = candidates.filter((c) => c.cost <= budgetPerIngestUsd);
+    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 {
+            predictedKind,
+            groundTruthKind,
+            chosenStrategy: globallyCheapest.strategy,
+            chosenStrategyReason: 'no strategy fits budget; picking absolute cheapest',
+            estimatedCostUsd: globallyCheapest.cost,
+            budgetCeiling: budgetPerIngestUsd,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    if (budgetMode === 'cheapest-fallback') {
+        return {
+            predictedKind,
+            groundTruthKind,
+            chosenStrategy: cheapestFits.strategy,
+            chosenStrategyReason: 'budget downgrade (cheapest-fallback mode)',
+            estimatedCostUsd: cheapestFits.cost,
+            budgetCeiling: budgetPerIngestUsd,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    // soft: keep the pick, flag exceeded.
+    return {
+        predictedKind,
+        groundTruthKind,
+        chosenStrategy: picked,
+        chosenStrategyReason: 'soft exceed: keeping picked despite budget breach',
+        estimatedCostUsd: pickedCost,
+        budgetCeiling: budgetPerIngestUsd,
+        budgetExceeded: true,
+        preset: table.preset,
+    };
+}
+//# sourceMappingURL=select-strategy.js.map

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

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

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

@@ -0,0 +1,142 @@
+/**
+ * @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, type MemoryRouterOptions } from './MemoryRouter.js';
+import { type MemoryBackendId, type MemoryQueryCategory, type RoutingTable } from './routing-tables.js';
+/**
+ * One calibration sample. Caller produces these from running their own
+ * workload through each candidate backend and recording the outcome.
+ */
+export interface CalibrationSample {
+    readonly category: MemoryQueryCategory;
+    readonly backend: MemoryBackendId;
+    readonly costUsd: number;
+    /** 1 = correct, 0 = incorrect (or score in [0,1] for soft graders). */
+    readonly correct: number;
+}
+/**
+ * Aggregated calibration cell: one (category, backend) → mean cost +
+ * mean accuracy + sample count.
+ */
+export interface CalibrationCell {
+    readonly n: number;
+    readonly meanCost: number;
+    readonly meanAccuracy: number;
+}
+/**
+ * Map of (category, backend) → CalibrationCell. Categories or backends
+ * with no samples are simply absent from the map.
+ */
+export type AggregatedCalibration = Partial<Record<MemoryQueryCategory, Partial<Record<MemoryBackendId, CalibrationCell>>>>;
+/**
+ * Preset selection rules for {@link selectByPreset}.
+ *
+ * - `minimize-cost`: pick the cheapest backend whose meanAccuracy is
+ *   within `accuracyTolerance` (default 0.02 = 2pp) of the best
+ *   meanAccuracy on this category. If no backend is within tolerance,
+ *   pick the best-accuracy backend (the gap exceeds the tolerance,
+ *   meaning accuracy gain justifies cost).
+ * - `maximize-accuracy`: pick the highest-meanAccuracy backend;
+ *   ties broken by lower meanCost.
+ * - `balanced`: pick the lowest meanCost / meanAccuracy ratio
+ *   ($/correct). Backends with zero meanAccuracy are skipped (would
+ *   produce divide-by-zero).
+ */
+export type AdaptivePresetRule = 'minimize-cost' | 'balanced' | 'maximize-accuracy';
+export interface SelectByPresetArgs {
+    readonly category: MemoryQueryCategory;
+    readonly agg: AggregatedCalibration;
+    readonly preset: AdaptivePresetRule;
+    /**
+     * Minimum sample count per (category, backend) cell required for
+     * adaptive selection. Cells below this threshold are ignored. Default
+     * 1 (any sample qualifies). Increase for noisier workloads.
+     */
+    readonly minSamplesPerCell?: number;
+    /**
+     * For `minimize-cost`: max accuracy gap from the best-accuracy backend
+     * tolerated when picking the cheaper alternative. Default 0.02 (2pp).
+     */
+    readonly accuracyTolerance?: number;
+}
+export interface BuildAdaptiveRoutingTableArgs {
+    readonly samples: readonly CalibrationSample[];
+    readonly preset: AdaptivePresetRule;
+    readonly minSamplesPerCell?: number;
+    readonly accuracyTolerance?: number;
+    /**
+     * Fallback static table for categories with insufficient calibration.
+     * Defaults to the preset's shipping static table.
+     */
+    readonly fallbackTable?: RoutingTable;
+}
+export interface AdaptiveMemoryRouterOptions extends Omit<MemoryRouterOptions, 'routingTable' | 'preset'> {
+    readonly calibrationSamples: readonly CalibrationSample[];
+    readonly preset: AdaptivePresetRule;
+    readonly minSamplesPerCell?: number;
+    readonly accuracyTolerance?: number;
+}
+/**
+ * Roll up raw calibration samples into per-(category, backend) cells.
+ * Each cell carries n, meanCost, meanAccuracy.
+ */
+export declare function aggregateCalibration(samples: readonly CalibrationSample[]): AggregatedCalibration;
+/**
+ * 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 declare function selectByPreset(args: SelectByPresetArgs): MemoryBackendId;
+/**
+ * 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 declare function buildAdaptiveRoutingTable(args: BuildAdaptiveRoutingTableArgs): RoutingTable;
+/**
+ * Memory router whose routing table is derived from a calibration
+ * dataset rather than a static preset. Otherwise identical API to
+ * {@link MemoryRouter}.
+ */
+export declare class AdaptiveMemoryRouter extends MemoryRouter {
+    private readonly derivedTable;
+    constructor(options: AdaptiveMemoryRouterOptions);
+    /**
+     * Inspect the derived routing table for debugging / telemetry.
+     */
+    getRoutingTable(): RoutingTable;
+}
+//# sourceMappingURL=adaptive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive.d.ts","sourceRoot":"","sources":["../../src/memory-router/adaptive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAExB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAM7B;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,CACzC,MAAM,CAAC,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,CAAC,CAC/E,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,UAAU,GACV,mBAAmB,CAAC;AAExB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,YAAY,CAAC;CACvC;AAED,MAAM,WAAW,2BACf,SAAQ,IAAI,CAAC,mBAAmB,EAAE,cAAc,GAAG,QAAQ,CAAC;IAC5D,QAAQ,CAAC,kBAAkB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACpC,qBAAqB,CA4BvB;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CA8DxE;AAeD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,6BAA6B,GAClC,YAAY,CAqCd;AAMD;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAEhC,OAAO,EAAE,2BAA2B;IAiBhD;;OAEG;IACH,eAAe,IAAI,YAAY;CAGhC"}