@framers/agentos 0.2.6 → 0.2.7

package/dist/memory-router/select-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-backend.d.ts","sourceRoot":"","sources":["../../src/memory-router/select-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAClF;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,iBAAiB,EAAE,mBAAmB,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,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;;;;GAIG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;aAC7B,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAI7C;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;aAEtC,OAAO,EAAE,eAAe;aACxB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAFd,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAQjC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,mBAAmB,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAChD,MAAM,EAAE,kBAAkB,CAAC;CAC5B,GAAG,qBAAqB,CA6IxB"}

package/dist/memory-router/select-backend.js

@@ -0,0 +1,210 @@
+/**
+ * @file select-backend.ts
+ * @description Pure function that turns a classifier-predicted category
+ * + a {@link MemoryRouterConfig} into a {@link MemoryRoutingDecision}.
+ *
+ * Stateless. Deterministic. No I/O. Suitable for use inside hot dispatch
+ * loops and inside cache-key construction (the function's output is a
+ * pure function of its inputs).
+ *
+ * The decision carries:
+ *   - the chosen {@link MemoryBackendId},
+ *   - the predicted category (and optional ground-truth for telemetry),
+ *   - the estimated USD cost of the routing pick,
+ *   - the budget ceiling (if any) and whether the pick exceeded it,
+ *   - a human-readable reason explaining the routing path taken.
+ *
+ * @module @framers/agentos/memory-router/select-backend
+ */
+/**
+ * Thrown when the predicted category is not in the routing table. Should
+ * never fire with the three shipping presets (each covers all six
+ * categories) but guards custom-table misuse.
+ */
+export class MemoryRouterUnknownCategoryError extends Error {
+    constructor(category) {
+        super(`MemoryRouter: category '${category}' not in routing table`);
+        this.category = category;
+        this.name = 'MemoryRouterUnknownCategoryError';
+    }
+}
+/**
+ * Thrown by `hard` budget mode when the routing-table pick exceeds the
+ * per-query USD ceiling. Carries the picked backend + cost + budget so
+ * application-layer fallbacks can decide what to do (fall back to a
+ * different memory architecture, return a typed 402 to the user, etc).
+ */
+export class MemoryRouterBudgetExceededError extends Error {
+    constructor(backend, cost, budget) {
+        super(`MemoryRouter: backend '${backend}' cost $${cost.toFixed(4)} ` +
+            `exceeds hard budget $${budget.toFixed(4)}`);
+        this.backend = backend;
+        this.cost = cost;
+        this.budget = budget;
+        this.name = 'MemoryRouterBudgetExceededError';
+    }
+}
+/**
+ * Pure routing decision: maps a predicted category to a backend choice
+ * given a routing table + budget policy + cost-points data.
+ *
+ * Algorithm:
+ *   1. Look up the table's preferred backend for the predicted category.
+ *      Throw if missing (custom-table misuse).
+ *   2. If no budget is set, return the table's pick.
+ *   3. If the pick fits the budget, return it.
+ *   4. If the pick exceeds:
+ *      - `hard`: throw {@link MemoryRouterBudgetExceededError}.
+ *      - `cheapest-fallback`: pick the cheapest backend that fits;
+ *        if none fits, pick the absolute cheapest and flag exceeded.
+ *      - `soft`: keep the pick if its $/correct beats the cheapest fits;
+ *        otherwise downgrade to the cheapest fits. Globally-no-fit case
+ *        falls through to absolute-cheapest with budgetExceeded=true.
+ *
+ * @param args
+ * @param args.predictedCategory - Category predicted by the LLM-as-judge classifier.
+ * @param args.groundTruthCategory - Gold-label category for telemetry, or null in production.
+ * @param args.config - Routing table + budget policy + cost-points map.
+ *
+ * @returns A {@link MemoryRoutingDecision} describing the chosen backend.
+ *
+ * @throws {@link MemoryRouterUnknownCategoryError} when the table does not
+ *   cover `predictedCategory`.
+ * @throws {@link MemoryRouterBudgetExceededError} when `budgetMode === 'hard'`
+ *   and the routing-table pick exceeds the budget.
+ *
+ * @example
+ * ```ts
+ * const decision = selectBackend({
+ *   predictedCategory: 'multi-session',
+ *   groundTruthCategory: null,
+ *   config: {
+ *     table: MINIMIZE_COST_TABLE,
+ *     budgetPerQuery: 0.05,
+ *     budgetMode: 'cheapest-fallback',
+ *     backendCosts: DEFAULT_MEMORY_BACKEND_COSTS,
+ *   },
+ * });
+ * console.log(decision.chosenBackend); // 'observational-memory-v11' (fits)
+ * ```
+ */
+export function selectBackend(args) {
+    const { predictedCategory, groundTruthCategory, config } = args;
+    const { table, budgetPerQuery, budgetMode, backendCosts } = config;
+    // 1. Validate: category must be in routing table.
+    const picked = table.defaultMapping[predictedCategory];
+    if (!picked) {
+        throw new MemoryRouterUnknownCategoryError(predictedCategory);
+    }
+    // 2. Compute per-query cost for the picked backend on this category.
+    const pickedCost = backendCosts[picked].perCategoryCostPerQuery[predictedCategory];
+    // 3. Budget pass-through: no budget OR pick fits.
+    if (budgetPerQuery === null || pickedCost <= budgetPerQuery) {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: picked,
+            chosenBackendReason: budgetPerQuery === null
+                ? 'routing-table pick, no budget'
+                : 'routing-table pick fits budget',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    // 4. Budget exceeded. Hard mode bails immediately.
+    if (budgetMode === 'hard') {
+        throw new MemoryRouterBudgetExceededError(picked, pickedCost, budgetPerQuery);
+    }
+    // Find the cheapest backend that fits the budget on this category.
+    const candidates = Object.values(backendCosts).map((c) => ({
+        backend: c.backend,
+        cost: c.perCategoryCostPerQuery[predictedCategory],
+    }));
+    const fits = candidates.filter((c) => c.cost <= budgetPerQuery);
+    const cheapestFits = fits.length > 0
+        ? fits.reduce((a, b) => (a.cost <= b.cost ? a : b))
+        : null;
+    // No backend fits at all -> globally cheapest with budgetExceeded=true.
+    if (!cheapestFits) {
+        const globallyCheapest = candidates.reduce((a, b) => a.cost <= b.cost ? a : b);
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: globallyCheapest.backend,
+            chosenBackendReason: 'no backend fits budget; picking absolute cheapest',
+            estimatedCostUsd: globallyCheapest.cost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    // cheapest-fallback: silently downgrade.
+    if (budgetMode === 'cheapest-fallback') {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: cheapestFits.backend,
+            chosenBackendReason: 'budget downgrade (cheapest-fallback mode)',
+            estimatedCostUsd: cheapestFits.cost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    // soft: keep the pick only if it's better $/correct than cheapest-fits.
+    const pickedAcc = backendCosts[picked].perCategoryAccuracy[predictedCategory];
+    const cheapestAcc = backendCosts[cheapestFits.backend].perCategoryAccuracy[predictedCategory];
+    // Edge case: picked has zero accuracy -> always downgrade.
+    if (pickedAcc === 0) {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: cheapestFits.backend,
+            chosenBackendReason: 'soft budget downgrade: picked has 0 acc on category',
+            estimatedCostUsd: cheapestFits.cost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    // Edge case: cheapest has zero accuracy -> stay with picked even though exceeded.
+    if (cheapestAcc === 0) {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: picked,
+            chosenBackendReason: 'soft exceed: cheapest has 0 acc',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    const pickedCPC = pickedCost / pickedAcc;
+    const cheapestCPC = cheapestFits.cost / cheapestAcc;
+    if (pickedCPC <= cheapestCPC) {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: picked,
+            chosenBackendReason: 'soft exceed: better $/correct',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    return {
+        predictedCategory,
+        groundTruthCategory,
+        chosenBackend: cheapestFits.backend,
+        chosenBackendReason: 'soft budget downgrade: cheaper $/correct',
+        estimatedCostUsd: cheapestFits.cost,
+        budgetCeiling: budgetPerQuery,
+        budgetExceeded: false,
+        preset: table.preset,
+    };
+}
+//# sourceMappingURL=select-backend.js.map

package/dist/memory-router/select-backend.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",
@@ -258,6 +258,11 @@
       "default": "./dist/query-router/index.js",
       "types": "./dist/query-router/index.d.ts"
     },
+    "./memory-router": {
+      "import": "./dist/memory-router/index.js",
+      "default": "./dist/memory-router/index.js",
+      "types": "./dist/memory-router/index.d.ts"
+    },
     "./memory/index": {
       "import": "./dist/memory/index.js",
       "default": "./dist/memory/index.js",