@framers/agentos 0.5.6 → 0.5.7

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

@@ -127,4 +127,6 @@ export { EntityRetrievalRanker, createEntityRetrievalRanker, } from './backends/
 export type { RankedCandidate, RankedCandidateWithBoost, EntityRetrievalRankerOptions, } from './backends/index.js';
 export { RETRIEVAL_CONFIG_IDS, RETRIEVAL_CONFIG_SPECS, M_PHASE_A_PER_CATEGORY_ACCURACY, M_PHASE_A_COST_PER_CORRECT, M_TUNED_PER_CATEGORY_TABLE, selectBestRetrievalConfig, computeOracleAggregate, computeOracleCostPerCorrect, } from './retrieval-config.js';
 export type { RetrievalConfigId, RetrievalConfigSpec, } from './retrieval-config.js';
+export { MIN_COST_BEST_CAT_2026_04_28_TABLE as READER_MIN_COST_BEST_CAT_2026_04_28_TABLE, MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE as READER_MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE, READER_ROUTER_PRESET_TABLES, ReaderRouterUnknownCategoryError, ReaderRouterUnknownPresetError, selectReader, } from './reader-router.js';
+export type { ReaderTier, ReaderRouterPreset, ReaderRouterTable, } from './reader-router.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,EACZ,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,GAClB,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,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,EAC9B,6BAA6B,EAC7B,uCAAuC,GACxC,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,EACb,6BAA6B,EAC7B,mCAAmC,EACnC,2CAA2C,EAC3C,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,GACxB,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,EAClC,sCAAsC,GACvC,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;AAMvB,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,+BAA+B,EAC/B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"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"}

package/dist/memory-router/index.js

@@ -128,4 +128,10 @@ export { EntityRetrievalRanker, createEntityRetrievalRanker, } from './backends/
 // from 2026-04-26 LongMemEval-M Phase A N=54 ablation matrix)
 // ============================================================================
 export { RETRIEVAL_CONFIG_IDS, RETRIEVAL_CONFIG_SPECS, M_PHASE_A_PER_CATEGORY_ACCURACY, M_PHASE_A_COST_PER_CORRECT, M_TUNED_PER_CATEGORY_TABLE, selectBestRetrievalConfig, computeOracleAggregate, computeOracleCostPerCorrect, } from './retrieval-config.js';
+// ============================================================================
+// ReaderRouter (per-query reader-tier dispatch, calibrated from
+// 2026-04-28 LongMemEval-S Phase B N=500 per-category gpt-4o vs
+// gpt-5-mini split)
+// ============================================================================
+export { MIN_COST_BEST_CAT_2026_04_28_TABLE as READER_MIN_COST_BEST_CAT_2026_04_28_TABLE, MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE as READER_MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE, READER_ROUTER_PRESET_TABLES, ReaderRouterUnknownCategoryError, ReaderRouterUnknownPresetError, selectReader, } from './reader-router.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;AAeH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAuC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,EACb,6BAA6B,EAC7B,mCAAmC,EACnC,2CAA2C,EAC3C,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,GACxB,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,EAClC,sCAAsC,GACvC,MAAM,mBAAmB,CAAC;AAgB3B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAE/E,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAO7B,+EAA+E;AAC/E,yEAAyE;AACzE,8DAA8D;AAC9D,+EAA+E;AAE/E,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,+BAA+B,EAC/B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAeH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAuC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,EACb,6BAA6B,EAC7B,mCAAmC,EACnC,2CAA2C,EAC3C,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,GACxB,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,EAClC,sCAAsC,GACvC,MAAM,mBAAmB,CAAC;AAgB3B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAE/E,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAO7B,+EAA+E;AAC/E,yEAAyE;AACzE,8DAA8D;AAC9D,+EAA+E;AAE/E,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,+BAA+B,EAC/B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAO/B,+EAA+E;AAC/E,gEAAgE;AAChE,gEAAgE;AAChE,oBAAoB;AACpB,+EAA+E;AAE/E,OAAO,EACL,kCAAkC,IAAI,yCAAyC,EAC/E,0CAA0C,IAAI,iDAAiD,EAC/F,2BAA2B,EAC3B,gCAAgC,EAChC,8BAA8B,EAC9B,YAAY,GACb,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,155 @@
+/**
+ * @file reader-router.ts
+ * @description ReaderRouter primitive — per-query reader-tier dispatch.
+ *
+ * **What this primitive does:**
+ *
+ * The shipping {@link MemoryRouter} dispatches per-query among recall
+ * BACKENDS (canonical-hybrid, OM-v10, OM-v11). The
+ * {@link RetrievalConfigRouter} dispatches per-query retrieval-CONFIG
+ * (canonical, hyde, topk50-mult5, etc.). The ReaderRouter completes
+ * the orchestration triplet by dispatching per-query among READER
+ * MODELS (`gpt-4o`, `gpt-5`, `gpt-5-mini`) using the same
+ * `gpt-5-mini` classifier output.
+ *
+ * **Why this exists:**
+ *
+ * The 2026-04-28 LongMemEval-S Phase B per-category accuracy split
+ * between `gpt-4o` and `gpt-5-mini` at the canonical-hybrid retrieval
+ * stack revealed dramatic per-category preference: `gpt-4o` wins TR
+ * (+11.8 pp) and SSU (+4.3 pp); `gpt-5-mini` wins SSP (+23.4 pp), and
+ * the rest are statistically tied with `gpt-5-mini` cheaper. A static
+ * always-on reader at either tier leaves ~3 pp of accuracy on the table
+ * vs per-category-oracle dispatch (which the gpt-5-mini classifier
+ * already provides through the policy router and retrieval-config
+ * router pipelines).
+ *
+ * **Calibration sources:**
+ *
+ * `MIN_COST_BEST_CAT_2026_04_28_TABLE` (the v1 publication preset) is
+ * calibrated from LongMemEval-S Phase B N=500 runs:
+ *
+ *   - results/runs/2026-04-27T06-27-24-170--longmemeval-s--gpt-4o--full-cognitive--ingest.json
+ *   - results/runs/2026-04-28T08-07-48-754--longmemeval-s--gpt-5-mini--full-cognitive--ingest.json
+ *
+ * Per-category accuracy (judge `gpt-4o-2024-08-06`, rubric 2026-04-18.1):
+ *
+ * | Category                  | gpt-4o | gpt-5-mini | Pick      | Δ        |
+ * | ------------------------- | -----: | ---------: | :-------- | -------- |
+ * | temporal-reasoning (n=133)|  84.7% |      72.9% | gpt-4o    | +11.8 pp |
+ * | single-session-user (n=70)|  94.3% |      90.0% | gpt-4o    |  +4.3 pp |
+ * | single-session-pref (n=30)|  63.3% |      86.7% | gpt-5-mini| +23.4 pp |
+ * | single-session-asst (n=56)|  98.2% |     100.0% | gpt-5-mini|  +1.8 pp |
+ * | knowledge-update    (n=78)|  85.7% |      87.2% | gpt-5-mini|  +1.5 pp |
+ * | multi-session      (n=133)|  76.2% |      79.7% | gpt-5-mini|  +3.5 pp |
+ *
+ * Oracle aggregate at this calibration: 435/500 = 87.0% (+3.8 pp over
+ * either reader alone). Realized at ~80% classifier accuracy: ~85-86%
+ * (validated at 85.6% Phase B N=500 with the standalone classifier).
+ *
+ * `MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE` (the v1.1 follow-up)
+ * replaces the gpt-4o picks for TR and SSU with `gpt-5`, on Phase A
+ * signal of +4 pp on TR + cheaper input pricing (gpt-5 input is half
+ * gpt-4o's per-1K-token rate). Phase B at N=500 is the validation
+ * gate.
+ *
+ * **Opt-in by registration:**
+ *
+ * Consumers register only the {@link ReaderRouterPreset} they support
+ * in their dispatcher. The selector throws a typed error if asked for
+ * a category that's missing from the active preset's table — the
+ * shipped presets cover every {@link MemoryQueryCategory}.
+ *
+ * @module @framers/agentos/memory-router/reader-router
+ */
+import type { MemoryQueryCategory } from './routing-tables.js';
+/**
+ * Reader tier the router can dispatch to. Restricted to OpenAI models
+ * the shipped presets were calibrated against. Future presets (e.g.
+ * `claude-opus-4-7` + `gpt-5-mini`) would extend this union.
+ */
+export type ReaderTier = 'gpt-4o' | 'gpt-5' | 'gpt-5-mini';
+/**
+ * Registered preset identifier. Each preset names the calibration
+ * source + the date the calibration table was derived, mirroring the
+ * `MINIMIZE_COST_*` preset naming convention in this package.
+ */
+export type ReaderRouterPreset = 'min-cost-best-cat-2026-04-28' | 'min-cost-best-cat-gpt5-tr-2026-04-29';
+/**
+ * A complete reader-router calibration: every {@link MemoryQueryCategory}
+ * MUST map to a {@link ReaderTier}. The runtime guard in
+ * {@link selectReader} fires if a future table addition forgets a
+ * category.
+ */
+export interface ReaderRouterTable {
+    readonly preset: ReaderRouterPreset;
+    /** Per-category reader assignment. */
+    readonly mapping: Readonly<Record<MemoryQueryCategory, ReaderTier>>;
+}
+/**
+ * Error thrown when {@link selectReader} is called with a category
+ * that is not present in the active routing table. Should never fire
+ * in production (TypeScript guards exhaustive {@link MemoryQueryCategory}
+ * at compile time), but the runtime check protects against structural
+ * casts and future table refactors that introduce a partial mapping.
+ */
+export declare class ReaderRouterUnknownCategoryError extends Error {
+    constructor(category: string, preset: string);
+}
+/**
+ * Error thrown when {@link selectReader} is called with a preset that
+ * is not registered in {@link READER_ROUTER_PRESET_TABLES}. Guards
+ * against typos in CLI flag passthrough — `min-cost-best-cat-2026-04-27`
+ * (off-by-one date) would fail fast here rather than silently routing
+ * every case to a default reader.
+ */
+export declare class ReaderRouterUnknownPresetError extends Error {
+    constructor(preset: string);
+}
+/**
+ * The MIN_COST_BEST_CAT_2026_04_28 calibration. See file header for
+ * the derivation table and source runs.
+ */
+export declare const MIN_COST_BEST_CAT_2026_04_28_TABLE: ReaderRouterTable;
+/**
+ * The MIN_COST_BEST_CAT_GPT5_TR_2026_04_29 calibration. Replaces the
+ * gpt-4o picks for `temporal-reasoning` and `single-session-user`
+ * with `gpt-5` (cheaper input than gpt-4o + Phase A signal of +4 pp
+ * on TR). Keeps the gpt-5-mini picks for `single-session-assistant`,
+ * `single-session-preference`, `knowledge-update`, and `multi-session`
+ * unchanged.
+ *
+ * **Calibration source:** Phase A N=54 stratified probe at
+ * canonical+RR + `--reader gpt-5` (no router) measured TR 88.9%
+ * [66.7%, 100%] vs the gpt-4o Phase B baseline 84.7% — a +4.2 pp
+ * point estimate at small sample. SSU was 100% at N=9 vs 94.3%
+ * baseline. Phase A only; Phase B at N=500 is the validation gate.
+ *
+ * **Why ship as a preset rather than defaulting:** preset is opt-in
+ * via the bench's `--reader-router min-cost-best-cat-gpt5-tr-2026-04-29`
+ * flag. Phase B may show the gpt-5 lift collapses (Phase A → Phase B
+ * compressions have happened repeatedly in this benchmark on small
+ * samples).
+ */
+export declare const MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE: ReaderRouterTable;
+/**
+ * Registry of all calibrated reader-router tables. Adding a new
+ * preset means (a) extending {@link ReaderRouterPreset}, (b) defining
+ * a `*_TABLE` const with the calibration, (c) adding the entry here.
+ * Frozen at module load.
+ */
+export declare const READER_ROUTER_PRESET_TABLES: Readonly<Record<ReaderRouterPreset, ReaderRouterTable>>;
+/**
+ * Pick a reader tier for a given predicted category under a calibration
+ * preset. Stateless. Deterministic. No I/O. Suitable for use inside
+ * cache-key construction and hot dispatch loops.
+ *
+ * @throws {ReaderRouterUnknownPresetError} when `preset` is not in
+ *   {@link READER_ROUTER_PRESET_TABLES}.
+ * @throws {ReaderRouterUnknownCategoryError} when the table for
+ *   `preset` is missing an entry for `category`. (Defensive runtime
+ *   guard; not reachable through the type system on a properly-
+ *   constructed table.)
+ */
+export declare function selectReader(category: MemoryQueryCategory, preset: ReaderRouterPreset): ReaderTier;
+//# sourceMappingURL=reader-router.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reader-router.d.ts","sourceRoot":"","sources":["../../src/memory-router/reader-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,8BAA8B,GAC9B,sCAAsC,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,UAAU,CAAC,CAAC,CAAC;CACrE;AAED;;;;;;GAMG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;gBAC7C,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM7C;AAED;;;;;;GAMG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;gBAC3C,MAAM,EAAE,MAAM;CAO3B;AAED;;;GAGG;AACH,eAAO,MAAM,kCAAkC,EAAE,iBAU1B,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,0CAA0C,EAAE,iBAUlC,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAChD,MAAM,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAI7C,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,kBAAkB,GACzB,UAAU,CAUZ"}

package/dist/memory-router/reader-router.js

@@ -0,0 +1,171 @@
+/**
+ * @file reader-router.ts
+ * @description ReaderRouter primitive — per-query reader-tier dispatch.
+ *
+ * **What this primitive does:**
+ *
+ * The shipping {@link MemoryRouter} dispatches per-query among recall
+ * BACKENDS (canonical-hybrid, OM-v10, OM-v11). The
+ * {@link RetrievalConfigRouter} dispatches per-query retrieval-CONFIG
+ * (canonical, hyde, topk50-mult5, etc.). The ReaderRouter completes
+ * the orchestration triplet by dispatching per-query among READER
+ * MODELS (`gpt-4o`, `gpt-5`, `gpt-5-mini`) using the same
+ * `gpt-5-mini` classifier output.
+ *
+ * **Why this exists:**
+ *
+ * The 2026-04-28 LongMemEval-S Phase B per-category accuracy split
+ * between `gpt-4o` and `gpt-5-mini` at the canonical-hybrid retrieval
+ * stack revealed dramatic per-category preference: `gpt-4o` wins TR
+ * (+11.8 pp) and SSU (+4.3 pp); `gpt-5-mini` wins SSP (+23.4 pp), and
+ * the rest are statistically tied with `gpt-5-mini` cheaper. A static
+ * always-on reader at either tier leaves ~3 pp of accuracy on the table
+ * vs per-category-oracle dispatch (which the gpt-5-mini classifier
+ * already provides through the policy router and retrieval-config
+ * router pipelines).
+ *
+ * **Calibration sources:**
+ *
+ * `MIN_COST_BEST_CAT_2026_04_28_TABLE` (the v1 publication preset) is
+ * calibrated from LongMemEval-S Phase B N=500 runs:
+ *
+ *   - results/runs/2026-04-27T06-27-24-170--longmemeval-s--gpt-4o--full-cognitive--ingest.json
+ *   - results/runs/2026-04-28T08-07-48-754--longmemeval-s--gpt-5-mini--full-cognitive--ingest.json
+ *
+ * Per-category accuracy (judge `gpt-4o-2024-08-06`, rubric 2026-04-18.1):
+ *
+ * | Category                  | gpt-4o | gpt-5-mini | Pick      | Δ        |
+ * | ------------------------- | -----: | ---------: | :-------- | -------- |
+ * | temporal-reasoning (n=133)|  84.7% |      72.9% | gpt-4o    | +11.8 pp |
+ * | single-session-user (n=70)|  94.3% |      90.0% | gpt-4o    |  +4.3 pp |
+ * | single-session-pref (n=30)|  63.3% |      86.7% | gpt-5-mini| +23.4 pp |
+ * | single-session-asst (n=56)|  98.2% |     100.0% | gpt-5-mini|  +1.8 pp |
+ * | knowledge-update    (n=78)|  85.7% |      87.2% | gpt-5-mini|  +1.5 pp |
+ * | multi-session      (n=133)|  76.2% |      79.7% | gpt-5-mini|  +3.5 pp |
+ *
+ * Oracle aggregate at this calibration: 435/500 = 87.0% (+3.8 pp over
+ * either reader alone). Realized at ~80% classifier accuracy: ~85-86%
+ * (validated at 85.6% Phase B N=500 with the standalone classifier).
+ *
+ * `MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE` (the v1.1 follow-up)
+ * replaces the gpt-4o picks for TR and SSU with `gpt-5`, on Phase A
+ * signal of +4 pp on TR + cheaper input pricing (gpt-5 input is half
+ * gpt-4o's per-1K-token rate). Phase B at N=500 is the validation
+ * gate.
+ *
+ * **Opt-in by registration:**
+ *
+ * Consumers register only the {@link ReaderRouterPreset} they support
+ * in their dispatcher. The selector throws a typed error if asked for
+ * a category that's missing from the active preset's table — the
+ * shipped presets cover every {@link MemoryQueryCategory}.
+ *
+ * @module @framers/agentos/memory-router/reader-router
+ */
+/**
+ * Error thrown when {@link selectReader} is called with a category
+ * that is not present in the active routing table. Should never fire
+ * in production (TypeScript guards exhaustive {@link MemoryQueryCategory}
+ * at compile time), but the runtime check protects against structural
+ * casts and future table refactors that introduce a partial mapping.
+ */
+export class ReaderRouterUnknownCategoryError extends Error {
+    constructor(category, preset) {
+        super(`ReaderRouter: category '${category}' not in routing table for preset '${preset}'`);
+        this.name = 'ReaderRouterUnknownCategoryError';
+    }
+}
+/**
+ * Error thrown when {@link selectReader} is called with a preset that
+ * is not registered in {@link READER_ROUTER_PRESET_TABLES}. Guards
+ * against typos in CLI flag passthrough — `min-cost-best-cat-2026-04-27`
+ * (off-by-one date) would fail fast here rather than silently routing
+ * every case to a default reader.
+ */
+export class ReaderRouterUnknownPresetError extends Error {
+    constructor(preset) {
+        super(`ReaderRouter: preset '${preset}' is not registered. ` +
+            `Known presets: ${Object.keys(READER_ROUTER_PRESET_TABLES).join(', ')}`);
+        this.name = 'ReaderRouterUnknownPresetError';
+    }
+}
+/**
+ * The MIN_COST_BEST_CAT_2026_04_28 calibration. See file header for
+ * the derivation table and source runs.
+ */
+export const MIN_COST_BEST_CAT_2026_04_28_TABLE = Object.freeze({
+    preset: 'min-cost-best-cat-2026-04-28',
+    mapping: Object.freeze({
+        'temporal-reasoning': 'gpt-4o',
+        'single-session-user': 'gpt-4o',
+        'single-session-preference': 'gpt-5-mini',
+        'single-session-assistant': 'gpt-5-mini',
+        'knowledge-update': 'gpt-5-mini',
+        'multi-session': 'gpt-5-mini',
+    }),
+});
+/**
+ * The MIN_COST_BEST_CAT_GPT5_TR_2026_04_29 calibration. Replaces the
+ * gpt-4o picks for `temporal-reasoning` and `single-session-user`
+ * with `gpt-5` (cheaper input than gpt-4o + Phase A signal of +4 pp
+ * on TR). Keeps the gpt-5-mini picks for `single-session-assistant`,
+ * `single-session-preference`, `knowledge-update`, and `multi-session`
+ * unchanged.
+ *
+ * **Calibration source:** Phase A N=54 stratified probe at
+ * canonical+RR + `--reader gpt-5` (no router) measured TR 88.9%
+ * [66.7%, 100%] vs the gpt-4o Phase B baseline 84.7% — a +4.2 pp
+ * point estimate at small sample. SSU was 100% at N=9 vs 94.3%
+ * baseline. Phase A only; Phase B at N=500 is the validation gate.
+ *
+ * **Why ship as a preset rather than defaulting:** preset is opt-in
+ * via the bench's `--reader-router min-cost-best-cat-gpt5-tr-2026-04-29`
+ * flag. Phase B may show the gpt-5 lift collapses (Phase A → Phase B
+ * compressions have happened repeatedly in this benchmark on small
+ * samples).
+ */
+export const MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE = Object.freeze({
+    preset: 'min-cost-best-cat-gpt5-tr-2026-04-29',
+    mapping: Object.freeze({
+        'temporal-reasoning': 'gpt-5',
+        'single-session-user': 'gpt-5',
+        'single-session-preference': 'gpt-5-mini',
+        'single-session-assistant': 'gpt-5-mini',
+        'knowledge-update': 'gpt-5-mini',
+        'multi-session': 'gpt-5-mini',
+    }),
+});
+/**
+ * Registry of all calibrated reader-router tables. Adding a new
+ * preset means (a) extending {@link ReaderRouterPreset}, (b) defining
+ * a `*_TABLE` const with the calibration, (c) adding the entry here.
+ * Frozen at module load.
+ */
+export const READER_ROUTER_PRESET_TABLES = Object.freeze({
+    'min-cost-best-cat-2026-04-28': MIN_COST_BEST_CAT_2026_04_28_TABLE,
+    'min-cost-best-cat-gpt5-tr-2026-04-29': MIN_COST_BEST_CAT_GPT5_TR_2026_04_29_TABLE,
+});
+/**
+ * Pick a reader tier for a given predicted category under a calibration
+ * preset. Stateless. Deterministic. No I/O. Suitable for use inside
+ * cache-key construction and hot dispatch loops.
+ *
+ * @throws {ReaderRouterUnknownPresetError} when `preset` is not in
+ *   {@link READER_ROUTER_PRESET_TABLES}.
+ * @throws {ReaderRouterUnknownCategoryError} when the table for
+ *   `preset` is missing an entry for `category`. (Defensive runtime
+ *   guard; not reachable through the type system on a properly-
+ *   constructed table.)
+ */
+export function selectReader(category, preset) {
+    const table = READER_ROUTER_PRESET_TABLES[preset];
+    if (!table) {
+        throw new ReaderRouterUnknownPresetError(preset);
+    }
+    const reader = table.mapping[category];
+    if (!reader) {
+        throw new ReaderRouterUnknownCategoryError(category, preset);
+    }
+    return reader;
+}
+//# sourceMappingURL=reader-router.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reader-router.js","sourceRoot":"","sources":["../../src/memory-router/reader-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAgCH;;;;;;GAMG;AACH,MAAM,OAAO,gCAAiC,SAAQ,KAAK;IACzD,YAAY,QAAgB,EAAE,MAAc;QAC1C,KAAK,CACH,2BAA2B,QAAQ,sCAAsC,MAAM,GAAG,CACnF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;IACjD,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACvD,YAAY,MAAc;QACxB,KAAK,CACH,yBAAyB,MAAM,uBAAuB;YACpD,kBAAkB,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC1E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAsB,MAAM,CAAC,MAAM,CAAC;IACjF,MAAM,EAAE,8BAAuC;IAC/C,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;QACrB,oBAAoB,EAAE,QAAiB;QACvC,qBAAqB,EAAE,QAAiB;QACxC,2BAA2B,EAAE,YAAqB;QAClD,0BAA0B,EAAE,YAAqB;QACjD,kBAAkB,EAAE,YAAqB;QACzC,eAAe,EAAE,YAAqB;KACvC,CAAC;CACH,CAAsB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,0CAA0C,GAAsB,MAAM,CAAC,MAAM,CAAC;IACzF,MAAM,EAAE,sCAA+C;IACvD,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;QACrB,oBAAoB,EAAE,OAAgB;QACtC,qBAAqB,EAAE,OAAgB;QACvC,2BAA2B,EAAE,YAAqB;QAClD,0BAA0B,EAAE,YAAqB;QACjD,kBAAkB,EAAE,YAAqB;QACzC,eAAe,EAAE,YAAqB;KACvC,CAAC;CACH,CAAsB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAEpC,MAAM,CAAC,MAAM,CAAC;IAChB,8BAA8B,EAAE,kCAAkC;IAClE,sCAAsC,EAAE,0CAA0C;CACnF,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,QAA6B,EAC7B,MAA0B;IAE1B,MAAM,KAAK,GAAG,2BAA2B,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,8BAA8B,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,gCAAgC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",