@framers/agentos 0.2.6 → 0.2.8

package/dist/ingest-router/index.js

@@ -0,0 +1,37 @@
+/**
+ * AgentOS IngestRouter Module
+ *
+ * Input-stage LLM-as-judge orchestrator for memory ingest. Sibling of
+ * {@link MemoryRouter} (recall-stage), {@link QueryRouter} (Q&A-stage),
+ * and the output-stage guardrails. Together they form the agentos
+ * multi-stage guardrails pattern.
+ *
+ * Where MemoryRouter picks the recall architecture for a query,
+ * IngestRouter picks the storage architecture for incoming content. The
+ * choice affects what's STORED, which downstream MemoryRouter then queries.
+ *
+ * **Architecture Overview:**
+ * ```
+ *   Content stream
+ *         │
+ *         ▼
+ *  ┌────────────────────────────────────────────────┐
+ *  │              IngestRouter                      │
+ *  │  classify content → pick strategy → store      │
+ *  └────────────────────────────────────────────────┘
+ *         │             │              │
+ *         ▼             ▼              ▼
+ *   raw-chunks      summarized    observational
+ *   fact-graph      hybrid        skip
+ * ```
+ *
+ * @module @framers/agentos/ingest-router
+ */
+export { INGEST_CONTENT_KINDS } from './routing-tables.js';
+export { RAW_CHUNKS_TABLE, SUMMARIZED_TABLE, OBSERVATIONAL_TABLE, HYBRID_TABLE, PRESET_INGEST_TABLES, } from './routing-tables.js';
+export { RAW_CHUNKS_COST, SUMMARIZED_COST, OBSERVATIONAL_COST, FACT_GRAPH_COST, HYBRID_COST, SKIP_COST, DEFAULT_INGEST_COSTS, } from './costs.js';
+export { selectIngestStrategy, IngestRouterUnknownKindError, IngestRouterBudgetExceededError, } from './select-strategy.js';
+export { INGEST_CLASSIFIER_SYSTEM_PROMPT, INGEST_CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_INGEST_FALLBACK_KIND, LLMIngestClassifier, normalizeIngestClassifierOutput, parseIngestClassifierOutput, } from './classifier.js';
+export { FunctionIngestDispatcher, UnsupportedIngestStrategyError, } from './dispatcher.js';
+export { IngestRouter, IngestRouterDispatcherMissingError, } from './IngestRouter.js';
+//# sourceMappingURL=index.js.map

package/dist/ingest-router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ingest-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAoC3D,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,SAAS,EACT,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,+BAA+B,GAChC,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,+BAA+B,EAC/B,uCAAuC,EACvC,yBAAyB,EACzB,mBAAmB,EACnB,+BAA+B,EAC/B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,kCAAkC,GACnC,MAAM,mBAAmB,CAAC"}

package/dist/ingest-router/routing-tables.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link IngestRouter}.
+ *
+ * IngestRouter is the input-stage sibling of MemoryRouter. Where MemoryRouter
+ * picks the recall architecture for a query, IngestRouter picks the storage
+ * architecture for incoming content. The choice affects what's STORED, which
+ * downstream MemoryRouter then queries.
+ *
+ * Four shipping presets express different cost-vs-recall priorities:
+ *
+ * - {@link RAW_CHUNKS_TABLE}: stores everything as raw chunks. Cheapest at
+ *   ingest time. Pushes all complexity to retrieval. Default for cost-
+ *   sensitive workloads.
+ * - {@link SUMMARIZED_TABLE}: applies session/article summarization on long
+ *   content. Anthropic-style "contextual retrieval" — every chunk gets a
+ *   dense session-summary prefix before embedding.
+ * - {@link OBSERVATIONAL_TABLE}: extracts observation logs (Mastra-style)
+ *   from long conversational content. Most expensive at ingest, best for
+ *   multi-session synthesis recall.
+ * - {@link HYBRID_TABLE}: applies multiple ingest strategies in parallel
+ *   for long content (raw chunks + summary + observations). Highest cost,
+ *   highest recall flexibility — every retrieval strategy has its substrate.
+ *
+ * @module @framers/agentos/ingest-router/routing-tables
+ */
+/**
+ * The six content kinds the LLM-as-judge ingest classifier can emit.
+ * Coarse taxonomy chosen to map cleanly onto distinct ingest strategies —
+ * extending the taxonomy means extending the routing tables consistently.
+ */
+export declare const INGEST_CONTENT_KINDS: readonly ["short-conversation", "long-conversation", "long-article", "code", "structured-data", "multimodal"];
+export type IngestContentKind = (typeof INGEST_CONTENT_KINDS)[number];
+/**
+ * The six storage strategies an IngestDispatcher can execute.
+ *
+ * - `raw-chunks`: standard turn-by-turn (or semantic) chunking, no LLM at
+ *   ingest. The Memory.remember() default.
+ * - `summarized`: every chunk prepended with a dense session/document
+ *   summary before embedding (Anthropic Sep 2024 "contextual retrieval").
+ *   One LLM summarize call per session/document at ingest time.
+ * - `observational`: extract a structured observation log from the content
+ *   (Mastra Observational Memory pattern). Multiple LLM extraction calls
+ *   per session at ingest time. Recalled traces are observations rather
+ *   than raw turns.
+ * - `fact-graph`: extract atomic fact triples from the content (Mem0-style).
+ *   LLM-triple-extraction at ingest. Recall queries the fact graph.
+ * - `hybrid`: apply multiple strategies in parallel (e.g., raw-chunks +
+ *   summarized + observational). Most expensive at ingest. Highest recall
+ *   flexibility.
+ * - `skip`: do not ingest the content. For low-value session noise that
+ *   wastes recall slots and inflates retrieval cost.
+ */
+export type IngestStrategyId = 'raw-chunks' | 'summarized' | 'observational' | 'fact-graph' | 'hybrid' | 'skip';
+/**
+ * The shipping preset names. Each names a cost-vs-recall point.
+ */
+export type IngestRouterPreset = 'raw-chunks' | 'summarized' | 'observational' | 'hybrid';
+/**
+ * A routing table maps every {@link IngestContentKind} to its preferred
+ * {@link IngestStrategyId}. Tables are frozen so consumers cannot mutate
+ * the routing surface from outside the module.
+ */
+export interface IngestRoutingTable {
+    readonly preset: IngestRouterPreset;
+    readonly defaultMapping: Readonly<Record<IngestContentKind, IngestStrategyId>>;
+}
+/**
+ * Preset: raw-chunks (default for cost-sensitive workloads).
+ *
+ * Stores everything as raw chunks regardless of content kind. Zero LLM
+ * cost at ingest time. All complexity is pushed to retrieval where the
+ * MemoryRouter can compose hybrid retrieval over the raw chunks.
+ *
+ * Recommended when: ingest volume is high, retrieval-side compute is
+ * cheap, and you trust the retrieval stage to do the heavy lifting.
+ */
+export declare const RAW_CHUNKS_TABLE: IngestRoutingTable;
+/**
+ * Preset: summarized (contextual retrieval for long content).
+ *
+ * Long content (long-conversation, long-article) gets a session/document
+ * summary prepended to every chunk before embedding. Short content stays
+ * as raw chunks. Code and structured data are summarized for the
+ * cross-file context. Multimodal stays raw — embedding modality is
+ * orthogonal to summarization.
+ *
+ * Recommended when: documents and conversations have meaningful global
+ * context that improves retrieval recall.
+ */
+export declare const SUMMARIZED_TABLE: IngestRoutingTable;
+/**
+ * Preset: observational (Mastra-style for multi-session synthesis).
+ *
+ * Long conversational content (long-conversation) becomes a structured
+ * observation log via LLM extraction at ingest. Long articles get the
+ * cheaper summarized treatment. Short content, code, structured, and
+ * multimodal stay raw.
+ *
+ * Recommended when: workload is conversational and includes many
+ * multi-session synthesis questions ("what have we agreed to so far",
+ * "across our chats, what topics recur").
+ */
+export declare const OBSERVATIONAL_TABLE: IngestRoutingTable;
+/**
+ * Preset: hybrid (maximum-recall workloads).
+ *
+ * Applies multiple ingest strategies in parallel for long content. Every
+ * downstream retrieval architecture has its substrate (raw chunks for
+ * canonical hybrid, summary prefix for contextual retrieval, observation
+ * log for OM-style synthesis). Highest cost at ingest; highest flexibility
+ * at retrieval.
+ *
+ * Recommended when: cost-per-ingest is acceptable AND retrieval workload
+ * is heterogeneous enough that no single strategy dominates.
+ */
+export declare const HYBRID_TABLE: IngestRoutingTable;
+/**
+ * Preset registry keyed by name.
+ */
+export declare const PRESET_INGEST_TABLES: Readonly<Record<IngestRouterPreset, IngestRoutingTable>>;
+//# sourceMappingURL=routing-tables.d.ts.map

package/dist/ingest-router/routing-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.d.ts","sourceRoot":"","sources":["../../src/ingest-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,+GAOvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,QAAQ,GACR,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,QAAQ,CAAC;AAEb;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAC/B,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAC5C,CAAC;CACH;AAMD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,kBAUP,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,kBAUP,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,kBAUV,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,kBAUH,CAAC;AAEzB;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CACzC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAM9C,CAAC"}

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

@@ -0,0 +1,145 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link IngestRouter}.
+ *
+ * IngestRouter is the input-stage sibling of MemoryRouter. Where MemoryRouter
+ * picks the recall architecture for a query, IngestRouter picks the storage
+ * architecture for incoming content. The choice affects what's STORED, which
+ * downstream MemoryRouter then queries.
+ *
+ * Four shipping presets express different cost-vs-recall priorities:
+ *
+ * - {@link RAW_CHUNKS_TABLE}: stores everything as raw chunks. Cheapest at
+ *   ingest time. Pushes all complexity to retrieval. Default for cost-
+ *   sensitive workloads.
+ * - {@link SUMMARIZED_TABLE}: applies session/article summarization on long
+ *   content. Anthropic-style "contextual retrieval" — every chunk gets a
+ *   dense session-summary prefix before embedding.
+ * - {@link OBSERVATIONAL_TABLE}: extracts observation logs (Mastra-style)
+ *   from long conversational content. Most expensive at ingest, best for
+ *   multi-session synthesis recall.
+ * - {@link HYBRID_TABLE}: applies multiple ingest strategies in parallel
+ *   for long content (raw chunks + summary + observations). Highest cost,
+ *   highest recall flexibility — every retrieval strategy has its substrate.
+ *
+ * @module @framers/agentos/ingest-router/routing-tables
+ */
+// ============================================================================
+// Types
+// ============================================================================
+/**
+ * The six content kinds the LLM-as-judge ingest classifier can emit.
+ * Coarse taxonomy chosen to map cleanly onto distinct ingest strategies —
+ * extending the taxonomy means extending the routing tables consistently.
+ */
+export const INGEST_CONTENT_KINDS = [
+    'short-conversation',
+    'long-conversation',
+    'long-article',
+    'code',
+    'structured-data',
+    'multimodal',
+];
+// ============================================================================
+// Preset tables
+// ============================================================================
+/**
+ * Preset: raw-chunks (default for cost-sensitive workloads).
+ *
+ * Stores everything as raw chunks regardless of content kind. Zero LLM
+ * cost at ingest time. All complexity is pushed to retrieval where the
+ * MemoryRouter can compose hybrid retrieval over the raw chunks.
+ *
+ * Recommended when: ingest volume is high, retrieval-side compute is
+ * cheap, and you trust the retrieval stage to do the heavy lifting.
+ */
+export const RAW_CHUNKS_TABLE = Object.freeze({
+    preset: 'raw-chunks',
+    defaultMapping: Object.freeze({
+        'short-conversation': 'raw-chunks',
+        'long-conversation': 'raw-chunks',
+        'long-article': 'raw-chunks',
+        code: 'raw-chunks',
+        'structured-data': 'raw-chunks',
+        multimodal: 'raw-chunks',
+    }),
+});
+/**
+ * Preset: summarized (contextual retrieval for long content).
+ *
+ * Long content (long-conversation, long-article) gets a session/document
+ * summary prepended to every chunk before embedding. Short content stays
+ * as raw chunks. Code and structured data are summarized for the
+ * cross-file context. Multimodal stays raw — embedding modality is
+ * orthogonal to summarization.
+ *
+ * Recommended when: documents and conversations have meaningful global
+ * context that improves retrieval recall.
+ */
+export const SUMMARIZED_TABLE = Object.freeze({
+    preset: 'summarized',
+    defaultMapping: Object.freeze({
+        'short-conversation': 'raw-chunks',
+        'long-conversation': 'summarized',
+        'long-article': 'summarized',
+        code: 'summarized',
+        'structured-data': 'raw-chunks',
+        multimodal: 'raw-chunks',
+    }),
+});
+/**
+ * Preset: observational (Mastra-style for multi-session synthesis).
+ *
+ * Long conversational content (long-conversation) becomes a structured
+ * observation log via LLM extraction at ingest. Long articles get the
+ * cheaper summarized treatment. Short content, code, structured, and
+ * multimodal stay raw.
+ *
+ * Recommended when: workload is conversational and includes many
+ * multi-session synthesis questions ("what have we agreed to so far",
+ * "across our chats, what topics recur").
+ */
+export const OBSERVATIONAL_TABLE = Object.freeze({
+    preset: 'observational',
+    defaultMapping: Object.freeze({
+        'short-conversation': 'raw-chunks',
+        'long-conversation': 'observational',
+        'long-article': 'summarized',
+        code: 'raw-chunks',
+        'structured-data': 'raw-chunks',
+        multimodal: 'raw-chunks',
+    }),
+});
+/**
+ * Preset: hybrid (maximum-recall workloads).
+ *
+ * Applies multiple ingest strategies in parallel for long content. Every
+ * downstream retrieval architecture has its substrate (raw chunks for
+ * canonical hybrid, summary prefix for contextual retrieval, observation
+ * log for OM-style synthesis). Highest cost at ingest; highest flexibility
+ * at retrieval.
+ *
+ * Recommended when: cost-per-ingest is acceptable AND retrieval workload
+ * is heterogeneous enough that no single strategy dominates.
+ */
+export const HYBRID_TABLE = Object.freeze({
+    preset: 'hybrid',
+    defaultMapping: Object.freeze({
+        'short-conversation': 'raw-chunks',
+        'long-conversation': 'hybrid',
+        'long-article': 'hybrid',
+        code: 'summarized',
+        'structured-data': 'raw-chunks',
+        multimodal: 'raw-chunks',
+    }),
+});
+/**
+ * Preset registry keyed by name.
+ */
+export const PRESET_INGEST_TABLES = Object.freeze({
+    'raw-chunks': RAW_CHUNKS_TABLE,
+    summarized: SUMMARIZED_TABLE,
+    observational: OBSERVATIONAL_TABLE,
+    hybrid: HYBRID_TABLE,
+});
+//# sourceMappingURL=routing-tables.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.js","sourceRoot":"","sources":["../../src/ingest-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+EAA+E;AAC/E,QAAQ;AACR,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,oBAAoB;IACpB,mBAAmB;IACnB,cAAc;IACd,MAAM;IACN,iBAAiB;IACjB,YAAY;CACJ,CAAC;AAqDX,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuB,MAAM,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,YAAqB;IAC7B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,oBAAoB,EAAE,YAAY;QAClC,mBAAmB,EAAE,YAAY;QACjC,cAAc,EAAE,YAAY;QAC5B,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,YAAY;QAC/B,UAAU,EAAE,YAAY;KACzB,CAAC;CACH,CAAuB,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuB,MAAM,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,YAAqB;IAC7B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,oBAAoB,EAAE,YAAY;QAClC,mBAAmB,EAAE,YAAY;QACjC,cAAc,EAAE,YAAY;QAC5B,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,YAAY;QAC/B,UAAU,EAAE,YAAY;KACzB,CAAC;CACH,CAAuB,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAuB,MAAM,CAAC,MAAM,CAAC;IACnE,MAAM,EAAE,eAAwB;IAChC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,oBAAoB,EAAE,YAAY;QAClC,mBAAmB,EAAE,eAAe;QACpC,cAAc,EAAE,YAAY;QAC5B,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,YAAY;QAC/B,UAAU,EAAE,YAAY;KACzB,CAAC;CACH,CAAuB,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAuB,MAAM,CAAC,MAAM,CAAC;IAC5D,MAAM,EAAE,QAAiB;IACzB,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,oBAAoB,EAAE,YAAY;QAClC,mBAAmB,EAAE,QAAQ;QAC7B,cAAc,EAAE,QAAQ;QACxB,IAAI,EAAE,YAAY;QAClB,iBAAiB,EAAE,YAAY;QAC/B,UAAU,EAAE,YAAY;KACzB,CAAC;CACH,CAAuB,CAAC;AAEzB;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAE7B,MAAM,CAAC,MAAM,CAAC;IAChB,YAAY,EAAE,gBAAgB;IAC9B,UAAU,EAAE,gBAAgB;IAC5B,aAAa,EAAE,mBAAmB;IAClC,MAAM,EAAE,YAAY;CACrB,CAAC,CAAC"}

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

@@ -0,0 +1,67 @@
+/**
+ * @file select-strategy.ts
+ * @description Pure function that picks an ingest strategy from a
+ * predicted content kind + routing table + budget policy.
+ *
+ * Stateless. Deterministic. No I/O. Same shape as
+ * {@link selectBackend} in memory-router so the multi-stage guardrails
+ * orchestrator can compose them uniformly.
+ *
+ * @module @framers/agentos/ingest-router/select-strategy
+ */
+import type { IngestStrategyCostPoint } from './costs.js';
+import type { IngestContentKind, IngestRouterPreset, IngestRoutingTable, IngestStrategyId } from './routing-tables.js';
+/**
+ * Budget enforcement modes for ingest dispatch:
+ *   - `hard`: throw {@link IngestRouterBudgetExceededError} if the
+ *     routing-table pick exceeds the per-ingest USD ceiling.
+ *   - `soft`: keep the picked strategy when the ceiling is exceeded
+ *     (best-effort enforcement; flag exceeded in the decision).
+ *   - `cheapest-fallback`: silently downgrade to the cheapest strategy
+ *     that fits. If none fits, pick the absolute cheapest and flag.
+ */
+export type IngestBudgetMode = 'hard' | 'soft' | 'cheapest-fallback';
+/**
+ * Configuration object for {@link selectIngestStrategy}.
+ */
+export interface IngestRouterConfig {
+    readonly table: IngestRoutingTable;
+    readonly budgetPerIngestUsd: number | null;
+    readonly budgetMode: IngestBudgetMode;
+    readonly strategyCosts: Readonly<Record<IngestStrategyId, IngestStrategyCostPoint>>;
+}
+/**
+ * Output of {@link selectIngestStrategy}. Carries the chosen strategy
+ * plus full telemetry about how the decision was made.
+ */
+export interface IngestRoutingDecision {
+    readonly predictedKind: IngestContentKind;
+    /** Optional ground-truth kind (telemetry only; null in production). */
+    readonly groundTruthKind: IngestContentKind | null;
+    readonly chosenStrategy: IngestStrategyId;
+    readonly chosenStrategyReason: string;
+    readonly estimatedCostUsd: number;
+    readonly budgetCeiling: number | null;
+    readonly budgetExceeded: boolean;
+    readonly preset: IngestRouterPreset;
+}
+export declare class IngestRouterUnknownKindError extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+export declare class IngestRouterBudgetExceededError extends Error {
+    readonly strategy: IngestStrategyId;
+    readonly cost: number;
+    readonly budget: number;
+    constructor(strategy: IngestStrategyId, cost: number, budget: number);
+}
+/**
+ * Pure ingest-strategy selection. Mirrors selectBackend (memory-router)
+ * in structure for multi-stage composability.
+ */
+export declare function selectIngestStrategy(args: {
+    predictedKind: IngestContentKind;
+    groundTruthKind: IngestContentKind | null;
+    config: IngestRouterConfig;
+}): IngestRoutingDecision;
+//# sourceMappingURL=select-strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"select-strategy.d.ts","sourceRoot":"","sources":["../../src/ingest-router/select-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAC9B,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAClD,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC;IAC1C,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,kBAAkB,CAAC;CACrC;AAED,qBAAa,4BAA6B,SAAQ,KAAK;aACzB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAIzC;AAED,qBAAa,+BAAgC,SAAQ,KAAK;aAEtC,QAAQ,EAAE,gBAAgB;aAC1B,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAFd,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAQjC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,aAAa,EAAE,iBAAiB,CAAC;IACjC,eAAe,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,MAAM,EAAE,kBAAkB,CAAC;CAC5B,GAAG,qBAAqB,CAsFxB"}

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

@@ -0,0 +1,100 @@
+/**
+ * @file select-strategy.ts
+ * @description Pure function that picks an ingest strategy from a
+ * predicted content kind + routing table + budget policy.
+ *
+ * Stateless. Deterministic. No I/O. Same shape as
+ * {@link selectBackend} in memory-router so the multi-stage guardrails
+ * orchestrator can compose them uniformly.
+ *
+ * @module @framers/agentos/ingest-router/select-strategy
+ */
+export class IngestRouterUnknownKindError extends Error {
+    constructor(kind) {
+        super(`IngestRouter: kind '${kind}' not in routing table`);
+        this.kind = kind;
+        this.name = 'IngestRouterUnknownKindError';
+    }
+}
+export class IngestRouterBudgetExceededError extends Error {
+    constructor(strategy, cost, budget) {
+        super(`IngestRouter: strategy '${strategy}' cost $${cost.toFixed(4)} ` +
+            `exceeds hard budget $${budget.toFixed(4)}`);
+        this.strategy = strategy;
+        this.cost = cost;
+        this.budget = budget;
+        this.name = 'IngestRouterBudgetExceededError';
+    }
+}
+/**
+ * Pure ingest-strategy selection. Mirrors selectBackend (memory-router)
+ * in structure for multi-stage composability.
+ */
+export function selectIngestStrategy(args) {
+    const { predictedKind, groundTruthKind, config } = args;
+    const { table, budgetPerIngestUsd, budgetMode, strategyCosts } = config;
+    const picked = table.defaultMapping[predictedKind];
+    if (!picked) {
+        throw new IngestRouterUnknownKindError(predictedKind);
+    }
+    const pickedCost = strategyCosts[picked].avgCostPerIngest;
+    if (budgetPerIngestUsd === null || pickedCost <= budgetPerIngestUsd) {
+        return {
+            predictedKind,
+            groundTruthKind,
+            chosenStrategy: picked,
+            chosenStrategyReason: budgetPerIngestUsd === null
+                ? 'routing-table pick, no budget'
+                : 'routing-table pick fits budget',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerIngestUsd,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    if (budgetMode === 'hard') {
+        throw new IngestRouterBudgetExceededError(picked, pickedCost, budgetPerIngestUsd);
+    }
+    const candidates = Object.values(strategyCosts).map((c) => ({ strategy: c.strategy, cost: c.avgCostPerIngest }));
+    const fits = candidates.filter((c) => c.cost <= budgetPerIngestUsd);
+    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 {
+            predictedKind,
+            groundTruthKind,
+            chosenStrategy: globallyCheapest.strategy,
+            chosenStrategyReason: 'no strategy fits budget; picking absolute cheapest',
+            estimatedCostUsd: globallyCheapest.cost,
+            budgetCeiling: budgetPerIngestUsd,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    if (budgetMode === 'cheapest-fallback') {
+        return {
+            predictedKind,
+            groundTruthKind,
+            chosenStrategy: cheapestFits.strategy,
+            chosenStrategyReason: 'budget downgrade (cheapest-fallback mode)',
+            estimatedCostUsd: cheapestFits.cost,
+            budgetCeiling: budgetPerIngestUsd,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    // soft: keep the pick, flag exceeded.
+    return {
+        predictedKind,
+        groundTruthKind,
+        chosenStrategy: picked,
+        chosenStrategyReason: 'soft exceed: keeping picked despite budget breach',
+        estimatedCostUsd: pickedCost,
+        budgetCeiling: budgetPerIngestUsd,
+        budgetExceeded: true,
+        preset: table.preset,
+    };
+}
+//# sourceMappingURL=select-strategy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"select-strategy.js","sourceRoot":"","sources":["../../src/ingest-router/select-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiDH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrD,YAA4B,IAAY;QACtC,KAAK,CAAC,uBAAuB,IAAI,wBAAwB,CAAC,CAAC;QADjC,SAAI,GAAJ,IAAI,CAAQ;QAEtC,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IACxD,YACkB,QAA0B,EAC1B,IAAY,EACZ,MAAc;QAE9B,KAAK,CACH,2BAA2B,QAAQ,WAAW,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAC9D,wBAAwB,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAC9C,CAAC;QAPc,aAAQ,GAAR,QAAQ,CAAkB;QAC1B,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;QAM9B,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAIpC;IACC,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxD,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC;IAExE,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,aAAa,CAEpC,CAAC;IACd,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,4BAA4B,CAAC,aAAa,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,gBAAgB,CAAC;IAE1D,IAAI,kBAAkB,KAAK,IAAI,IAAI,UAAU,IAAI,kBAAkB,EAAE,CAAC;QACpE,OAAO;YACL,aAAa;YACb,eAAe;YACf,cAAc,EAAE,MAAM;YACtB,oBAAoB,EAClB,kBAAkB,KAAK,IAAI;gBACzB,CAAC,CAAC,+BAA+B;gBACjC,CAAC,CAAC,gCAAgC;YACtC,gBAAgB,EAAE,UAAU;YAC5B,aAAa,EAAE,kBAAkB;YACjC,cAAc,EAAE,KAAK;YACrB,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,UAAU,EACV,kBAAkB,CACnB,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GACd,MAAM,CAAC,MAAM,CAAC,aAAa,CAC5B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,kBAAkB,CAAC,CAAC;IACpE,MAAM,YAAY,GAChB,IAAI,CAAC,MAAM,GAAG,CAAC;QACb,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,CAAC,CAAC,IAAI,CAAC;IAEX,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAClD,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACzB,CAAC;QACF,OAAO;YACL,aAAa;YACb,eAAe;YACf,cAAc,EAAE,gBAAgB,CAAC,QAAQ;YACzC,oBAAoB,EAAE,oDAAoD;YAC1E,gBAAgB,EAAE,gBAAgB,CAAC,IAAI;YACvC,aAAa,EAAE,kBAAkB;YACjC,cAAc,EAAE,IAAI;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,mBAAmB,EAAE,CAAC;QACvC,OAAO;YACL,aAAa;YACb,eAAe;YACf,cAAc,EAAE,YAAY,CAAC,QAAQ;YACrC,oBAAoB,EAAE,2CAA2C;YACjE,gBAAgB,EAAE,YAAY,CAAC,IAAI;YACnC,aAAa,EAAE,kBAAkB;YACjC,cAAc,EAAE,KAAK;YACrB,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,OAAO;QACL,aAAa;QACb,eAAe;QACf,cAAc,EAAE,MAAM;QACtB,oBAAoB,EAAE,mDAAmD;QACzE,gBAAgB,EAAE,UAAU;QAC5B,aAAa,EAAE,kBAAkB;QACjC,cAAc,EAAE,IAAI;QACpB,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC"}