@framers/agentos 0.2.7 → 0.2.8

package/dist/memory-router/adaptive.js

@@ -0,0 +1,202 @@
+/**
+ * @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 } from './MemoryRouter.js';
+import { PRESET_TABLES, } from './routing-tables.js';
+// ============================================================================
+// Aggregation
+// ============================================================================
+/**
+ * Roll up raw calibration samples into per-(category, backend) cells.
+ * Each cell carries n, meanCost, meanAccuracy.
+ */
+export function aggregateCalibration(samples) {
+    const acc = {};
+    for (const s of samples) {
+        if (!acc[s.category])
+            acc[s.category] = {};
+        if (!acc[s.category][s.backend]) {
+            acc[s.category][s.backend] = { n: 0, sumCost: 0, sumCorrect: 0 };
+        }
+        const cell = acc[s.category][s.backend];
+        cell.n += 1;
+        cell.sumCost += s.costUsd;
+        cell.sumCorrect += s.correct;
+    }
+    const out = {};
+    for (const cat of Object.keys(acc)) {
+        out[cat] = {};
+        const inner = out[cat];
+        for (const backend of Object.keys(acc[cat])) {
+            const cell = acc[cat][backend];
+            inner[backend] = {
+                n: cell.n,
+                meanCost: cell.sumCost / cell.n,
+                meanAccuracy: cell.sumCorrect / cell.n,
+            };
+        }
+    }
+    return out;
+}
+// ============================================================================
+// Per-category selection
+// ============================================================================
+/**
+ * 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 function selectByPreset(args) {
+    const { category, agg, preset, minSamplesPerCell = 1, accuracyTolerance = 0.02, } = args;
+    const fallbackTable = PRESET_TABLES[preset];
+    const fallback = fallbackTable.defaultMapping[category];
+    const cells = agg[category];
+    if (!cells)
+        return fallback;
+    // Filter cells meeting min-sample threshold.
+    const eligible = Object.entries(cells)
+        .filter(([, cell]) => cell.n >= minSamplesPerCell);
+    if (eligible.length === 0)
+        return fallback;
+    if (preset === 'maximize-accuracy') {
+        return eligible.reduce((best, [backend, cell]) => {
+            const [bestBackend, bestCell] = best;
+            if (cell.meanAccuracy > bestCell.meanAccuracy)
+                return [backend, cell];
+            if (cell.meanAccuracy === bestCell.meanAccuracy) {
+                return cell.meanCost < bestCell.meanCost ? [backend, cell] : best;
+            }
+            return best;
+        }, eligible[0])[0];
+    }
+    if (preset === 'balanced') {
+        // best $/correct (skip zero-accuracy cells to avoid div-by-zero)
+        const valid = eligible.filter(([, cell]) => cell.meanAccuracy > 0);
+        if (valid.length === 0)
+            return fallback;
+        return valid.reduce((best, [backend, cell]) => {
+            const [bestBackend, bestCell] = best;
+            const cellCpc = cell.meanCost / cell.meanAccuracy;
+            const bestCpc = bestCell.meanCost / bestCell.meanAccuracy;
+            return cellCpc < bestCpc ? [backend, cell] : best;
+        }, valid[0])[0];
+    }
+    // minimize-cost: cheapest within accuracyTolerance of best accuracy.
+    const bestAccuracy = Math.max(...eligible.map(([, cell]) => cell.meanAccuracy));
+    const withinTolerance = eligible.filter(([, cell]) => bestAccuracy - cell.meanAccuracy <= accuracyTolerance);
+    if (withinTolerance.length === 0) {
+        // No candidates within tolerance is impossible (the best-accuracy
+        // backend itself qualifies), but guard anyway.
+        return fallback;
+    }
+    return withinTolerance.reduce((best, [backend, cell]) => {
+        const [bestBackend, bestCell] = best;
+        return cell.meanCost < bestCell.meanCost ? [backend, cell] : best;
+    }, withinTolerance[0])[0];
+}
+// ============================================================================
+// Table construction
+// ============================================================================
+const ALL_CATEGORIES = [
+    'single-session-user',
+    'single-session-assistant',
+    'single-session-preference',
+    'knowledge-update',
+    'multi-session',
+    'temporal-reasoning',
+];
+/**
+ * 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 function buildAdaptiveRoutingTable(args) {
+    const { samples, preset, minSamplesPerCell, accuracyTolerance, fallbackTable, } = args;
+    const agg = aggregateCalibration(samples);
+    const fb = fallbackTable ?? PRESET_TABLES[preset];
+    const mapping = {};
+    for (const cat of ALL_CATEGORIES) {
+        mapping[cat] = selectByPreset({
+            category: cat,
+            agg,
+            preset,
+            minSamplesPerCell,
+            accuracyTolerance,
+        });
+        // selectByPreset falls back to the preset's STATIC default mapping,
+        // not the caller-supplied fallback table. Apply the explicit
+        // fallback only when the static fallback wasn't applied because of
+        // missing data — easiest is to override after the fact.
+        if (!agg[cat] && fb !== PRESET_TABLES[preset]) {
+            mapping[cat] = fb.defaultMapping[cat];
+        }
+    }
+    return Object.freeze({
+        preset: preset,
+        defaultMapping: Object.freeze(mapping),
+    });
+}
+// ============================================================================
+// AdaptiveMemoryRouter class
+// ============================================================================
+/**
+ * Memory router whose routing table is derived from a calibration
+ * dataset rather than a static preset. Otherwise identical API to
+ * {@link MemoryRouter}.
+ */
+export class AdaptiveMemoryRouter extends MemoryRouter {
+    constructor(options) {
+        const derivedTable = buildAdaptiveRoutingTable({
+            samples: options.calibrationSamples,
+            preset: options.preset,
+            minSamplesPerCell: options.minSamplesPerCell,
+            accuracyTolerance: options.accuracyTolerance,
+        });
+        super({
+            ...options,
+            preset: options.preset,
+            routingTable: derivedTable,
+        });
+        this.derivedTable = derivedTable;
+    }
+    /**
+     * Inspect the derived routing table for debugging / telemetry.
+     */
+    getRoutingTable() {
+        return this.derivedTable;
+    }
+}
+//# sourceMappingURL=adaptive.js.map

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

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

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

@@ -121,4 +121,6 @@ export { selectBackend, MemoryRouterUnknownCategoryError, MemoryRouterBudgetExce
 export { CLASSIFIER_SYSTEM_PROMPT, CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_FALLBACK_CATEGORY, LLMMemoryClassifier, normalizeClassifierOutput, parseClassifierOutput, } from './classifier.js';
 export { FunctionMemoryDispatcher, UnsupportedMemoryBackendError, } from './dispatcher.js';
 export { MemoryRouter, MemoryRouterDispatcherMissingError, } from './MemoryRouter.js';
+export type { CalibrationSample, CalibrationCell, AggregatedCalibration, AdaptivePresetRule, SelectByPresetArgs, BuildAdaptiveRoutingTableArgs, AdaptiveMemoryRouterOptions, } from './adaptive.js';
+export { aggregateCalibration, selectByPreset, buildAdaptiveRoutingTable, AdaptiveMemoryRouter, } from './adaptive.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,GACb,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,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,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,GACnC,MAAM,mBAAmB,CAAC"}
+{"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,GACb,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,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,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,GACnC,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"}

package/dist/memory-router/index.js

@@ -118,4 +118,5 @@ export { selectBackend, MemoryRouterUnknownCategoryError, MemoryRouterBudgetExce
 export { CLASSIFIER_SYSTEM_PROMPT, CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_FALLBACK_CATEGORY, LLMMemoryClassifier, normalizeClassifierOutput, parseClassifierOutput, } from './classifier.js';
 export { FunctionMemoryDispatcher, UnsupportedMemoryBackendError, } from './dispatcher.js';
 export { MemoryRouter, MemoryRouterDispatcherMissingError, } from './MemoryRouter.js';
+export { aggregateCalibration, selectByPreset, buildAdaptiveRoutingTable, AdaptiveMemoryRouter, } from './adaptive.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;AAYH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAoC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,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,GACnC,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAYH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAoC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,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,GACnC,MAAM,mBAAmB,CAAC;AAgB3B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}

package/dist/multi-stage-guardrails/index.d.ts

@@ -0,0 +1,190 @@
+/**
+ * AgentOS MultiStageGuardrails Module
+ *
+ * Composition primitive that wires the LLM-as-judge stages of the
+ * agentos pipeline into one orchestrator. Each stage is independent and
+ * optional — wire only the stages you need, or compose all four.
+ *
+ * **The four stages:**
+ *
+ * ```
+ *   Content                 Query                    Query
+ *      │                      │                       │
+ *      ▼                      ▼                       ▼
+ *  ┌─────────┐          ┌─────────────┐         ┌─────────────┐
+ *  │ Ingest  │          │   Recall    │         │    Read     │
+ *  │ Stage   │          │   Stage     │         │   Stage     │
+ *  │ (input) │          │  (memory)   │         │  (reader)   │
+ *  └─────────┘          └─────────────┘         └─────────────┘
+ *      │                      │                       │
+ *      ▼                      ▼                       ▼
+ *  Memory state          Retrieved traces         Final answer
+ * ```
+ *
+ * Plus the existing output-stage `core/guardrails` and
+ * `agentos-ext-grounding-guard` which validate the answer post-generation.
+ *
+ * **Why a composition primitive:** each individual router is independently
+ * useful and ships with its own classifier + dispatcher + table machinery.
+ * MultiStageGuardrails gives consumers a single object to coordinate the
+ * stages without duplicating per-stage wiring. It does NOT add new
+ * routing logic — it's a thin facade over the four primitives.
+ *
+ * The interfaces below ({@link IngestStage}, {@link RecallStage},
+ * {@link ReadStage}) are deliberately minimal so consumers can wire any
+ * implementation:
+ *
+ * - The shipping `IngestRouter` / `MemoryRouter` / `ReadRouter` classes
+ *   each satisfy the corresponding stage interface via thin adapters
+ *   (see `agentosStageAdapters` below).
+ * - Custom implementations (rule-based, ML-driven, mock for tests) can
+ *   satisfy the same interfaces and slot in.
+ *
+ * @module @framers/agentos/multi-stage-guardrails
+ */
+/**
+ * Generic decision metadata bundled with each stage's result. Stages
+ * report enough information for downstream telemetry without leaking
+ * stage-specific types into the orchestrator.
+ */
+export interface IngestStageResult {
+    readonly writtenTraces: number;
+    readonly strategy: string;
+    readonly ingestRouterDecision: unknown;
+}
+export interface RecallStageResult<TTrace> {
+    readonly traces: TTrace[];
+    readonly backend: string;
+    readonly memoryRouterDecision: unknown;
+}
+export interface ReadStageResult<TOutcome> {
+    readonly outcome: TOutcome;
+    readonly strategy: string;
+    readonly readRouterDecision: unknown;
+}
+/**
+ * Pluggable input-stage. Wrap an {@link IngestRouter} or any equivalent
+ * implementation that turns content into stored traces.
+ */
+export interface IngestStage {
+    ingest(content: string, payload?: unknown): Promise<IngestStageResult>;
+}
+/**
+ * Pluggable recall-stage. Wrap a {@link MemoryRouter} or any equivalent
+ * implementation that turns a query into retrieved traces.
+ */
+export interface RecallStage<TTrace> {
+    recall(query: string, payload?: unknown): Promise<RecallStageResult<TTrace>>;
+}
+/**
+ * Pluggable read-stage. Wrap a {@link ReadRouter} or any equivalent
+ * implementation that turns a query+evidence pair into a final answer.
+ */
+export interface ReadStage<TTrace, TOutcome> {
+    read(query: string, traces: TTrace[], payload?: unknown): Promise<ReadStageResult<TOutcome>>;
+}
+export interface RecallAndReadResult<TTrace, TOutcome> {
+    readonly recallStage: RecallStageResult<TTrace>;
+    readonly readStage: ReadStageResult<TOutcome>;
+    readonly outcome: TOutcome;
+}
+export interface MultiStageGuardrailsOptions<TTrace, TOutcome> {
+    readonly ingest?: IngestStage;
+    readonly recall?: RecallStage<TTrace>;
+    readonly read?: ReadStage<TTrace, TOutcome>;
+}
+export declare class MissingStageError extends Error {
+    constructor(stage: 'IngestStage' | 'RecallStage' | 'ReadStage');
+}
+/**
+ * Top-level pipeline composition. One instance per agent / endpoint;
+ * reuse across requests.
+ *
+ * @example Full pipeline
+ * ```ts
+ * import { MultiStageGuardrails } from '../multi-stage-guardrails';
+ * import { ingestRouterAsStage } from '../multi-stage-guardrails';
+ *
+ * const guardrails = new MultiStageGuardrails({
+ *   ingest: ingestRouterAsStage(myIngestRouter),
+ *   recall: memoryRouterAsStage(myMemoryRouter),
+ *   read: readRouterAsStage(myReadRouter),
+ * });
+ *
+ * await guardrails.ingest(newContent);
+ * const { outcome } = await guardrails.recallAndRead("what's my latest job?");
+ * ```
+ */
+export declare class MultiStageGuardrails<TTrace, TOutcome> {
+    private readonly ingestStage;
+    private readonly recallStage;
+    private readonly readStage;
+    constructor(options: MultiStageGuardrailsOptions<TTrace, TOutcome>);
+    get hasIngestStage(): boolean;
+    get hasRecallStage(): boolean;
+    get hasReadStage(): boolean;
+    ingest(content: string, payload?: unknown): Promise<IngestStageResult>;
+    recall(query: string, payload?: unknown): Promise<RecallStageResult<TTrace>>;
+    read(query: string, traces: TTrace[], payload?: unknown): Promise<ReadStageResult<TOutcome>>;
+    /**
+     * Recall traces for the query, then run the reader on those traces.
+     * Standard "ask a question, get an answer" path.
+     */
+    recallAndRead(query: string, recallPayload?: unknown, readPayload?: unknown): Promise<RecallAndReadResult<TTrace, TOutcome>>;
+}
+/**
+ * Wrap an {@link IngestRouter} as an {@link IngestStage}. The IngestRouter
+ * must have been constructed with a dispatcher; otherwise the stage will
+ * throw on every call.
+ */
+export declare function ingestRouterAsStage<TOutcome extends {
+    writtenTraces?: number;
+}>(router: {
+    decideAndDispatch: (content: string, payload?: unknown) => Promise<{
+        decision: {
+            routing: {
+                chosenStrategy: string;
+            };
+        };
+        outcome: TOutcome;
+    }>;
+}): IngestStage;
+/**
+ * Wrap a {@link MemoryRouter} as a {@link RecallStage}. The MemoryRouter
+ * must have been constructed with a dispatcher.
+ */
+export declare function memoryRouterAsStage<TTrace>(router: {
+    decideAndDispatch: <T = TTrace>(query: string, payload?: unknown) => Promise<{
+        decision: {
+            routing: {
+                chosenBackend: string;
+            };
+        };
+        traces: T[];
+        backend: string;
+    }>;
+}): RecallStage<TTrace>;
+/**
+ * Wrap a {@link ReadRouter} as a {@link ReadStage}. The ReadRouter must
+ * have been constructed with a dispatcher.
+ */
+export declare function readRouterAsStage<TTrace extends {
+    id?: string;
+    text?: string;
+}, TOutcome>(router: {
+    decideAndDispatch: <T = TOutcome>(query: string, evidence: readonly string[], payload?: unknown) => Promise<{
+        decision: {
+            routing: {
+                chosenStrategy: string;
+            };
+        };
+        outcome: T;
+    }>;
+}, 
+/**
+ * Optional adapter to turn a TTrace into a string for the read-router's
+ * evidence array. Default: serialize `{id, text}`-shaped traces by
+ * concatenating text fields.
+ */
+traceToString?: (trace: TTrace) => string): ReadStage<TTrace, TOutcome>;
+//# sourceMappingURL=index.d.ts.map

package/dist/multi-stage-guardrails/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/multi-stage-guardrails/index.ts"],"names":[],"mappings":"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"}

package/dist/multi-stage-guardrails/index.js

@@ -0,0 +1,186 @@
+/**
+ * AgentOS MultiStageGuardrails Module
+ *
+ * Composition primitive that wires the LLM-as-judge stages of the
+ * agentos pipeline into one orchestrator. Each stage is independent and
+ * optional — wire only the stages you need, or compose all four.
+ *
+ * **The four stages:**
+ *
+ * ```
+ *   Content                 Query                    Query
+ *      │                      │                       │
+ *      ▼                      ▼                       ▼
+ *  ┌─────────┐          ┌─────────────┐         ┌─────────────┐
+ *  │ Ingest  │          │   Recall    │         │    Read     │
+ *  │ Stage   │          │   Stage     │         │   Stage     │
+ *  │ (input) │          │  (memory)   │         │  (reader)   │
+ *  └─────────┘          └─────────────┘         └─────────────┘
+ *      │                      │                       │
+ *      ▼                      ▼                       ▼
+ *  Memory state          Retrieved traces         Final answer
+ * ```
+ *
+ * Plus the existing output-stage `core/guardrails` and
+ * `agentos-ext-grounding-guard` which validate the answer post-generation.
+ *
+ * **Why a composition primitive:** each individual router is independently
+ * useful and ships with its own classifier + dispatcher + table machinery.
+ * MultiStageGuardrails gives consumers a single object to coordinate the
+ * stages without duplicating per-stage wiring. It does NOT add new
+ * routing logic — it's a thin facade over the four primitives.
+ *
+ * The interfaces below ({@link IngestStage}, {@link RecallStage},
+ * {@link ReadStage}) are deliberately minimal so consumers can wire any
+ * implementation:
+ *
+ * - The shipping `IngestRouter` / `MemoryRouter` / `ReadRouter` classes
+ *   each satisfy the corresponding stage interface via thin adapters
+ *   (see `agentosStageAdapters` below).
+ * - Custom implementations (rule-based, ML-driven, mock for tests) can
+ *   satisfy the same interfaces and slot in.
+ *
+ * @module @framers/agentos/multi-stage-guardrails
+ */
+// ============================================================================
+// Errors
+// ============================================================================
+export class MissingStageError extends Error {
+    constructor(stage) {
+        super(`MultiStageGuardrails: ${stage} is not configured. ` +
+            `Pass it in options at construction.`);
+        this.name = 'MissingStageError';
+    }
+}
+// ============================================================================
+// Orchestrator
+// ============================================================================
+/**
+ * Top-level pipeline composition. One instance per agent / endpoint;
+ * reuse across requests.
+ *
+ * @example Full pipeline
+ * ```ts
+ * import { MultiStageGuardrails } from '../multi-stage-guardrails/index.js';
+ * import { ingestRouterAsStage } from '../multi-stage-guardrails';
+ *
+ * const guardrails = new MultiStageGuardrails({
+ *   ingest: ingestRouterAsStage(myIngestRouter),
+ *   recall: memoryRouterAsStage(myMemoryRouter),
+ *   read: readRouterAsStage(myReadRouter),
+ * });
+ *
+ * await guardrails.ingest(newContent);
+ * const { outcome } = await guardrails.recallAndRead("what's my latest job?");
+ * ```
+ */
+export class MultiStageGuardrails {
+    constructor(options) {
+        this.ingestStage = options.ingest ?? null;
+        this.recallStage = options.recall ?? null;
+        this.readStage = options.read ?? null;
+    }
+    get hasIngestStage() {
+        return this.ingestStage !== null;
+    }
+    get hasRecallStage() {
+        return this.recallStage !== null;
+    }
+    get hasReadStage() {
+        return this.readStage !== null;
+    }
+    async ingest(content, payload) {
+        if (!this.ingestStage)
+            throw new MissingStageError('IngestStage');
+        return this.ingestStage.ingest(content, payload);
+    }
+    async recall(query, payload) {
+        if (!this.recallStage)
+            throw new MissingStageError('RecallStage');
+        return this.recallStage.recall(query, payload);
+    }
+    async read(query, traces, payload) {
+        if (!this.readStage)
+            throw new MissingStageError('ReadStage');
+        return this.readStage.read(query, traces, payload);
+    }
+    /**
+     * Recall traces for the query, then run the reader on those traces.
+     * Standard "ask a question, get an answer" path.
+     */
+    async recallAndRead(query, recallPayload, readPayload) {
+        if (!this.recallStage)
+            throw new MissingStageError('RecallStage');
+        if (!this.readStage)
+            throw new MissingStageError('ReadStage');
+        const recallStage = await this.recallStage.recall(query, recallPayload);
+        const readStage = await this.readStage.read(query, recallStage.traces, readPayload);
+        return {
+            recallStage,
+            readStage,
+            outcome: readStage.outcome,
+        };
+    }
+}
+// ============================================================================
+// Adapters: shipping routers → stage interfaces
+// ============================================================================
+/**
+ * Wrap an {@link IngestRouter} as an {@link IngestStage}. The IngestRouter
+ * must have been constructed with a dispatcher; otherwise the stage will
+ * throw on every call.
+ */
+export function ingestRouterAsStage(router) {
+    return {
+        async ingest(content, payload) {
+            const result = await router.decideAndDispatch(content, payload);
+            return {
+                writtenTraces: result.outcome.writtenTraces ?? 0,
+                strategy: result.decision.routing.chosenStrategy,
+                ingestRouterDecision: result.decision,
+            };
+        },
+    };
+}
+/**
+ * Wrap a {@link MemoryRouter} as a {@link RecallStage}. The MemoryRouter
+ * must have been constructed with a dispatcher.
+ */
+export function memoryRouterAsStage(router) {
+    return {
+        async recall(query, payload) {
+            const result = await router.decideAndDispatch(query, payload);
+            return {
+                traces: result.traces,
+                backend: result.backend,
+                memoryRouterDecision: result.decision,
+            };
+        },
+    };
+}
+/**
+ * Wrap a {@link ReadRouter} as a {@link ReadStage}. The ReadRouter must
+ * have been constructed with a dispatcher.
+ */
+export function readRouterAsStage(router, 
+/**
+ * Optional adapter to turn a TTrace into a string for the read-router's
+ * evidence array. Default: serialize `{id, text}`-shaped traces by
+ * concatenating text fields.
+ */
+traceToString) {
+    const toString = traceToString ??
+        ((t) => t.text ?? JSON.stringify(t));
+    return {
+        async read(query, traces, payload) {
+            const evidenceStrings = traces.map(toString);
+            const result = await router.decideAndDispatch(query, evidenceStrings, payload);
+            return {
+                outcome: result.outcome,
+                strategy: result.decision.routing.chosenStrategy,
+                readRouterDecision: result.decision,
+            };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/multi-stage-guardrails/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/multi-stage-guardrails/index.ts"],"names":[],"mappings":"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"}