@framers/agentos 0.5.2 → 0.5.3

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

@@ -22,6 +22,13 @@
  *   temporal-reasoning back to canonical-hybrid after Phase B revealed the
  *   v1 routing's accuracy gain was within CI noise but paid OM ingest cost.
  *
+ * **Augmented routing (2026-04-26):** The {@link AugmentedRoutingTable}
+ * extends the basic dispatch contract with an orthogonal axis — a
+ * per-category {@link RetrievalConfigId} pick — so the router can
+ * dispatch on (backend × retrieval-config) rather than backend alone.
+ * The {@link MINIMIZE_COST_AUGMENTED_TABLE} preset is calibrated from
+ * the LongMemEval-M Phase A N=54 ablation matrix (2026-04-26).
+ *
  * @module @framers/agentos/memory-router/routing-tables
  */
 // ============================================================================
@@ -134,4 +141,110 @@ export const PRESET_TABLES = Object.freeze({
     'balanced': BALANCED_TABLE,
     'maximize-accuracy': MAXIMIZE_ACCURACY_TABLE,
 });
+// ============================================================================
+// Augmented routing: (backend × retrieval-config) dispatch
+// ============================================================================
+/**
+ * The cheapest-and-safest {@link MemoryBackendId} the router can ever
+ * pick. Used by {@link SAFE_FALLBACK_DISPATCH_KEY} when an augmented
+ * lookup misses (e.g. the predicted category is not in the table or
+ * the table is malformed). Matches the existing behavior of
+ * {@link MINIMIZE_COST_TABLE} for unknown categories: degrade to the
+ * cheap path rather than the OM-premium path.
+ */
+export const SAFE_FALLBACK_BACKEND = 'canonical-hybrid';
+/**
+ * Default {@link MemoryDispatchKey} used when an augmented lookup
+ * misses. Matches the cheap-and-safe path: canonical-hybrid backend
+ * with the canonical retrieval config (no HyDE, default rerank,
+ * default reader top-K).
+ *
+ * Frozen at module load.
+ */
+export const SAFE_FALLBACK_DISPATCH_KEY = Object.freeze({
+    backend: SAFE_FALLBACK_BACKEND,
+    retrievalConfig: 'canonical',
+});
+/**
+ * Preset: minimize-cost-augmented (2026-04-26 v2).
+ *
+ * Combines two calibrations into one dispatch table:
+ *
+ * - **Backend axis** from the LongMemEval-S Phase B N=500
+ *   {@link MINIMIZE_COST_TABLE}: SSP and MS pay the OM-v11 premium
+ *   (architectural lift earns it); every other category routes to
+ *   canonical-hybrid (cheapest Pareto-dominant).
+ * - **Retrieval-config axis** from the LongMemEval-M Phase A N=54
+ *   ablation matrix (per-category-oracle picks): SSA + SSU + MS use
+ *   the full combined `hyde-topk50-mult5`; KU uses `topk50` (top-K
+ *   alone is sufficient and cheaper); TR + SSP use `hyde` alone (the
+ *   wider rerank pool actively hurts these categories).
+ *
+ * The 2026-04-26 forecasted aggregate at this dispatch table on
+ * LongMemEval-M is **68.5%** (per-category-oracle empirical from the
+ * ablation matrix), vs **57.4%** static M-tuned (`hyde-topk50-mult5`
+ * everywhere) and **30.6%** baseline (`canonical` everywhere).
+ * Phase A validation at this preset is the next gate (see
+ * `2026-04-26-retrieval-config-router-productionization-plan.md`).
+ *
+ * **Calibration validity,** N=54 single-seed Phase A on M plus N=500
+ * Phase B on S. Phase B at full N=500 on M will tighten per-category
+ * confidence intervals; the table here is the directional best-guess
+ * for v2 and SHOULD be re-derived from any future Phase B run.
+ */
+export const MINIMIZE_COST_AUGMENTED_TABLE = Object.freeze({
+    preset: 'minimize-cost-augmented',
+    defaultMapping: Object.freeze({
+        'single-session-assistant': Object.freeze({
+            backend: 'canonical-hybrid',
+            retrievalConfig: 'hyde-topk50-mult5',
+        }),
+        'single-session-user': Object.freeze({
+            backend: 'canonical-hybrid',
+            retrievalConfig: 'hyde-topk50-mult5',
+        }),
+        'single-session-preference': Object.freeze({
+            backend: 'observational-memory-v11',
+            retrievalConfig: 'hyde',
+        }),
+        'knowledge-update': Object.freeze({
+            backend: 'canonical-hybrid',
+            retrievalConfig: 'topk50',
+        }),
+        'multi-session': Object.freeze({
+            backend: 'observational-memory-v11',
+            retrievalConfig: 'hyde-topk50-mult5',
+        }),
+        'temporal-reasoning': Object.freeze({
+            backend: 'canonical-hybrid',
+            retrievalConfig: 'hyde',
+        }),
+    }),
+});
+/**
+ * Convenience registry of augmented preset tables, keyed by preset
+ * name. v2 ships only `minimize-cost-augmented`; the other two
+ * preset names will be wired in v3 alongside Stage E.
+ */
+export const AUGMENTED_PRESET_TABLES = Object.freeze({
+    'minimize-cost-augmented': MINIMIZE_COST_AUGMENTED_TABLE,
+});
+/**
+ * Pure-function selector: given a category and an
+ * {@link AugmentedRoutingTable}, return the calibrated
+ * {@link MemoryDispatchKey}. Falls back to
+ * {@link SAFE_FALLBACK_DISPATCH_KEY} when the table is missing the
+ * category (a defensive guard for custom-table misuse; the shipping
+ * presets cover every category).
+ *
+ * Stateless. Deterministic. No I/O. Suitable for use inside
+ * cache-key construction and hot dispatch loops.
+ *
+ * @param category - The classifier-predicted query category.
+ * @param table - The augmented routing table to consult.
+ * @returns A frozen {@link MemoryDispatchKey} for the category.
+ */
+export function selectAugmentedDispatch(category, table) {
+    return table.defaultMapping[category] ?? SAFE_FALLBACK_DISPATCH_KEY;
+}
 //# sourceMappingURL=routing-tables.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"routing-tables.js","sourceRoot":"","sources":["../../src/memory-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,qBAAqB;IACrB,0BAA0B;IAC1B,2BAA2B;IAC3B,kBAAkB;IAClB,eAAe;IACf,oBAAoB;CACZ,CAAC;AA+CX,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAiB,MAAM,CAAC,MAAM,CAAC;IAC7D,MAAM,EAAE,eAAwB;IAChC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,kBAAkB;QACzC,oBAAoB,EAAE,kBAAkB;QACxC,kBAAkB,EAAE,kBAAkB;QACtC,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiB,MAAM,CAAC,MAAM,CAAC;IACxD,MAAM,EAAE,UAAmB;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,kBAAkB;QACzC,oBAAoB,EAAE,0BAA0B;QAChD,kBAAkB,EAAE,0BAA0B;QAC9C,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAiB,MAAM,CAAC,MAAM,CAAC;IACjE,MAAM,EAAE,mBAA4B;IACpC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,0BAA0B;QACjD,oBAAoB,EAAE,kBAAkB;QACxC,kBAAkB,EAAE,0BAA0B;QAC9C,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,MAAM,CAAC,MAAM,CAAC;IACZ,eAAe,EAAE,mBAAmB;IACpC,UAAU,EAAE,cAAc;IAC1B,mBAAmB,EAAE,uBAAuB;CAC7C,CAAC,CAAC"}
+{"version":3,"file":"routing-tables.js","sourceRoot":"","sources":["../../src/memory-router/routing-tables.ts"],"names":[],"mappings":"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"}

package/package.json

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