@framers/agentos 0.2.7 → 0.2.8

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

@@ -0,0 +1,79 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link ReadRouter}.
+ *
+ * ReadRouter is the read-stage sibling of MemoryRouter (recall-stage)
+ * and IngestRouter (input-stage). It picks a reader strategy after
+ * retrieval has produced candidate evidence — single-call generation
+ * vs two-call extract-then-answer (Emergence pattern) vs commit-vs-
+ * abstain (explicit binary decision before answer) vs verbatim citation
+ * vs scratchpad-then-answer (chain-of-thought-lite for temporal questions).
+ *
+ * @module @framers/agentos/read-router/routing-tables
+ */
+export const READ_INTENTS = [
+    'precise-fact',
+    'multi-source-synthesis',
+    'time-interval',
+    'preference-recommendation',
+    'abstention-candidate',
+];
+/**
+ * Preset: precise-fact (default for fact-recall workloads).
+ *
+ * Precise facts get single-call (cheap, accurate when evidence is clear).
+ * Synthesis gets two-call extract-then-answer. Time intervals get
+ * scratchpad. Preferences get single-call. Abstention candidates get the
+ * explicit commit-vs-abstain decision.
+ */
+export const PRECISE_FACT_TABLE = Object.freeze({
+    preset: 'precise-fact',
+    defaultMapping: Object.freeze({
+        'precise-fact': 'single-call',
+        'multi-source-synthesis': 'two-call-extract-answer',
+        'time-interval': 'scratchpad-then-answer',
+        'preference-recommendation': 'single-call',
+        'abstention-candidate': 'commit-vs-abstain',
+    }),
+});
+/**
+ * Preset: synthesis (synthesis-heavy workloads).
+ *
+ * Routes more aggressively to two-call extract-then-answer for both
+ * synthesis and precise-fact (the extract pass cleans up noisy evidence).
+ * Verbatim citation for KU/SSU-style precise facts to reduce paraphrase
+ * loss. Higher cost, higher fidelity.
+ */
+export const SYNTHESIS_TABLE = Object.freeze({
+    preset: 'synthesis',
+    defaultMapping: Object.freeze({
+        'precise-fact': 'verbatim-citation',
+        'multi-source-synthesis': 'two-call-extract-answer',
+        'time-interval': 'scratchpad-then-answer',
+        'preference-recommendation': 'two-call-extract-answer',
+        'abstention-candidate': 'commit-vs-abstain',
+    }),
+});
+/**
+ * Preset: temporal (time-heavy workloads).
+ *
+ * Almost everything goes through scratchpad-then-answer because the
+ * scratchpad's date-arithmetic discipline transfers to non-temporal
+ * questions about WHEN events happened.
+ */
+export const TEMPORAL_TABLE = Object.freeze({
+    preset: 'temporal',
+    defaultMapping: Object.freeze({
+        'precise-fact': 'scratchpad-then-answer',
+        'multi-source-synthesis': 'scratchpad-then-answer',
+        'time-interval': 'scratchpad-then-answer',
+        'preference-recommendation': 'single-call',
+        'abstention-candidate': 'commit-vs-abstain',
+    }),
+});
+export const PRESET_READ_TABLES = Object.freeze({
+    'precise-fact': PRECISE_FACT_TABLE,
+    synthesis: SYNTHESIS_TABLE,
+    temporal: TEMPORAL_TABLE,
+});
+//# sourceMappingURL=routing-tables.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.js","sourceRoot":"","sources":["../../src/read-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,cAAc;IACd,wBAAwB;IACxB,eAAe;IACf,2BAA2B;IAC3B,sBAAsB;CACd,CAAC;AAyDX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAqB,MAAM,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,cAAuB;IAC/B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,cAAc,EAAE,aAAa;QAC7B,wBAAwB,EAAE,yBAAyB;QACnD,eAAe,EAAE,wBAAwB;QACzC,2BAA2B,EAAE,aAAa;QAC1C,sBAAsB,EAAE,mBAAmB;KAC5C,CAAC;CACH,CAAqB,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqB,MAAM,CAAC,MAAM,CAAC;IAC7D,MAAM,EAAE,WAAoB;IAC5B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,cAAc,EAAE,mBAAmB;QACnC,wBAAwB,EAAE,yBAAyB;QACnD,eAAe,EAAE,wBAAwB;QACzC,2BAA2B,EAAE,yBAAyB;QACtD,sBAAsB,EAAE,mBAAmB;KAC5C,CAAC;CACH,CAAqB,CAAC;AAEvB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAqB,MAAM,CAAC,MAAM,CAAC;IAC5D,MAAM,EAAE,UAAmB;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,cAAc,EAAE,wBAAwB;QACxC,wBAAwB,EAAE,wBAAwB;QAClD,eAAe,EAAE,wBAAwB;QACzC,2BAA2B,EAAE,aAAa;QAC1C,sBAAsB,EAAE,mBAAmB;KAC5C,CAAC;CACH,CAAqB,CAAC;AAEvB,MAAM,CAAC,MAAM,kBAAkB,GAE3B,MAAM,CAAC,MAAM,CAAC;IAChB,cAAc,EAAE,kBAAkB;IAClC,SAAS,EAAE,eAAe;IAC1B,QAAQ,EAAE,cAAc;CACzB,CAAC,CAAC"}

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

@@ -0,0 +1,42 @@
+/**
+ * @file select-strategy.ts
+ * @description Pure selection function for ReadRouter. Mirrors the
+ * memory-router and ingest-router patterns.
+ *
+ * @module @framers/agentos/read-router/select-strategy
+ */
+import type { ReadStrategyCostPoint } from './costs.js';
+import type { ReadIntent, ReadRouterPreset, ReadRoutingTable, ReadStrategyId } from './routing-tables.js';
+export type ReadBudgetMode = 'hard' | 'soft' | 'cheapest-fallback';
+export interface ReadRouterConfig {
+    readonly table: ReadRoutingTable;
+    readonly budgetPerReadUsd: number | null;
+    readonly budgetMode: ReadBudgetMode;
+    readonly strategyCosts: Readonly<Record<ReadStrategyId, ReadStrategyCostPoint>>;
+}
+export interface ReadRoutingDecision {
+    readonly predictedIntent: ReadIntent;
+    readonly groundTruthIntent: ReadIntent | null;
+    readonly chosenStrategy: ReadStrategyId;
+    readonly chosenStrategyReason: string;
+    readonly estimatedCostUsd: number;
+    readonly budgetCeiling: number | null;
+    readonly budgetExceeded: boolean;
+    readonly preset: ReadRouterPreset;
+}
+export declare class ReadRouterUnknownIntentError extends Error {
+    readonly intent: string;
+    constructor(intent: string);
+}
+export declare class ReadRouterBudgetExceededError extends Error {
+    readonly strategy: ReadStrategyId;
+    readonly cost: number;
+    readonly budget: number;
+    constructor(strategy: ReadStrategyId, cost: number, budget: number);
+}
+export declare function selectReadStrategy(args: {
+    predictedIntent: ReadIntent;
+    groundTruthIntent: ReadIntent | null;
+    config: ReadRouterConfig;
+}): ReadRoutingDecision;
+//# sourceMappingURL=select-strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"select-strategy.d.ts","sourceRoot":"","sources":["../../src/read-router/select-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACf,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,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,gBAAgB,CAAC;CACnC;AAED,qBAAa,4BAA6B,SAAQ,KAAK;aACzB,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAI3C;AAED,qBAAa,6BAA8B,SAAQ,KAAK;aAEpC,QAAQ,EAAE,cAAc;aACxB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAFd,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAQjC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,eAAe,EAAE,UAAU,CAAC;IAC5B,iBAAiB,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC,MAAM,EAAE,gBAAgB,CAAC;CAC1B,GAAG,mBAAmB,CAoFtB"}

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

@@ -0,0 +1,92 @@
+/**
+ * @file select-strategy.ts
+ * @description Pure selection function for ReadRouter. Mirrors the
+ * memory-router and ingest-router patterns.
+ *
+ * @module @framers/agentos/read-router/select-strategy
+ */
+export class ReadRouterUnknownIntentError extends Error {
+    constructor(intent) {
+        super(`ReadRouter: intent '${intent}' not in routing table`);
+        this.intent = intent;
+        this.name = 'ReadRouterUnknownIntentError';
+    }
+}
+export class ReadRouterBudgetExceededError extends Error {
+    constructor(strategy, cost, budget) {
+        super(`ReadRouter: strategy '${strategy}' cost $${cost.toFixed(4)} ` +
+            `exceeds hard budget $${budget.toFixed(4)}`);
+        this.strategy = strategy;
+        this.cost = cost;
+        this.budget = budget;
+        this.name = 'ReadRouterBudgetExceededError';
+    }
+}
+export function selectReadStrategy(args) {
+    const { predictedIntent, groundTruthIntent, config } = args;
+    const { table, budgetPerReadUsd, budgetMode, strategyCosts } = config;
+    const picked = table.defaultMapping[predictedIntent];
+    if (!picked) {
+        throw new ReadRouterUnknownIntentError(predictedIntent);
+    }
+    const pickedCost = strategyCosts[picked].avgCostPerReadUsd;
+    if (budgetPerReadUsd === null || pickedCost <= budgetPerReadUsd) {
+        return {
+            predictedIntent,
+            groundTruthIntent,
+            chosenStrategy: picked,
+            chosenStrategyReason: budgetPerReadUsd === null
+                ? 'routing-table pick, no budget'
+                : 'routing-table pick fits budget',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerReadUsd,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    if (budgetMode === 'hard') {
+        throw new ReadRouterBudgetExceededError(picked, pickedCost, budgetPerReadUsd);
+    }
+    const candidates = Object.values(strategyCosts).map((c) => ({
+        strategy: c.strategy,
+        cost: c.avgCostPerReadUsd,
+    }));
+    const fits = candidates.filter((c) => c.cost <= budgetPerReadUsd);
+    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 {
+            predictedIntent,
+            groundTruthIntent,
+            chosenStrategy: globallyCheapest.strategy,
+            chosenStrategyReason: 'no strategy fits budget; picking absolute cheapest',
+            estimatedCostUsd: globallyCheapest.cost,
+            budgetCeiling: budgetPerReadUsd,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    if (budgetMode === 'cheapest-fallback') {
+        return {
+            predictedIntent,
+            groundTruthIntent,
+            chosenStrategy: cheapestFits.strategy,
+            chosenStrategyReason: 'budget downgrade (cheapest-fallback mode)',
+            estimatedCostUsd: cheapestFits.cost,
+            budgetCeiling: budgetPerReadUsd,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    return {
+        predictedIntent,
+        groundTruthIntent,
+        chosenStrategy: picked,
+        chosenStrategyReason: 'soft exceed: keeping picked despite budget breach',
+        estimatedCostUsd: pickedCost,
+        budgetCeiling: budgetPerReadUsd,
+        budgetExceeded: true,
+        preset: table.preset,
+    };
+}
+//# sourceMappingURL=select-strategy.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",
@@ -263,6 +263,21 @@
       "default": "./dist/memory-router/index.js",
       "types": "./dist/memory-router/index.d.ts"
     },
+    "./ingest-router": {
+      "import": "./dist/ingest-router/index.js",
+      "default": "./dist/ingest-router/index.js",
+      "types": "./dist/ingest-router/index.d.ts"
+    },
+    "./read-router": {
+      "import": "./dist/read-router/index.js",
+      "default": "./dist/read-router/index.js",
+      "types": "./dist/read-router/index.d.ts"
+    },
+    "./multi-stage-guardrails": {
+      "import": "./dist/multi-stage-guardrails/index.js",
+      "default": "./dist/multi-stage-guardrails/index.js",
+      "types": "./dist/multi-stage-guardrails/index.d.ts"
+    },
     "./memory/index": {
       "import": "./dist/memory/index.js",
       "default": "./dist/memory/index.js",