@framers/agentos 0.2.7 → 0.2.9

package/dist/cognitive-pipeline/index.d.ts

@@ -0,0 +1,197 @@
+/**
+ * AgentOS CognitivePipeline Module
+ *
+ * Smart per-message orchestration. Composes 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.
+ *
+ * **What this is NOT:** safety guardrails. CognitivePipeline picks
+ * strategies (which architecture per ingest, which retrieval per recall,
+ * which reader per read). It does NOT block, refuse, or validate output —
+ * those concerns live in `core/guardrails` and the
+ * `agentos-ext-grounding-guard` / `agentos-ext-topicality` /
+ * `agentos-ext-pii-redaction` extensions.
+ *
+ * **The three orchestrator stages:**
+ *
+ * ```
+ *   Content                 Query                    Query
+ *      │                      │                       │
+ *      ▼                      ▼                       ▼
+ *  ┌─────────┐          ┌─────────────┐         ┌─────────────┐
+ *  │ Ingest  │          │   Recall    │         │    Read     │
+ *  │ Stage   │          │   Stage     │         │   Stage     │
+ *  │ (input) │          │  (memory)   │         │  (reader)   │
+ *  └─────────┘          └─────────────┘         └─────────────┘
+ *      │                      │                       │
+ *      ▼                      ▼                       ▼
+ *  Memory state          Retrieved traces         Final answer
+ * ```
+ *
+ * Output guardrails (a separate, existing concern) sit downstream of the
+ * Read stage's answer to enforce safety and policy.
+ *
+ * **Why a composition primitive:** each individual router is independently
+ * useful and ships with its own classifier + dispatcher + table machinery.
+ * CognitivePipeline 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 stage 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 `ingestRouterAsStage` / `memoryRouterAsStage` / `readRouterAsStage`).
+ * - Custom implementations (rule-based, ML-driven, mock for tests) can
+ *   satisfy the same interfaces and slot in.
+ *
+ * @module @framers/agentos/cognitive-pipeline
+ */
+/**
+ * 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 `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 `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 `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 CognitivePipelineOptions<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 { CognitivePipeline } from '../cognitive-pipeline';
+ * import { ingestRouterAsStage } from '../cognitive-pipeline';
+ *
+ * const pipeline = new CognitivePipeline({
+ *   ingest: ingestRouterAsStage(myIngestRouter),
+ *   recall: memoryRouterAsStage(myMemoryRouter),
+ *   read: readRouterAsStage(myReadRouter),
+ * });
+ *
+ * await pipeline.ingest(newContent);
+ * const { outcome } = await pipeline.recallAndRead("what's my latest job?");
+ * ```
+ */
+export declare class CognitivePipeline<TTrace, TOutcome> {
+    private readonly ingestStage;
+    private readonly recallStage;
+    private readonly readStage;
+    constructor(options: CognitivePipelineOptions<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 `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 `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 `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/cognitive-pipeline/index.d.ts.map

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

package/dist/cognitive-pipeline/index.js

@@ -0,0 +1,193 @@
+/**
+ * AgentOS CognitivePipeline Module
+ *
+ * Smart per-message orchestration. Composes 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.
+ *
+ * **What this is NOT:** safety guardrails. CognitivePipeline picks
+ * strategies (which architecture per ingest, which retrieval per recall,
+ * which reader per read). It does NOT block, refuse, or validate output —
+ * those concerns live in `core/guardrails` and the
+ * `agentos-ext-grounding-guard` / `agentos-ext-topicality` /
+ * `agentos-ext-pii-redaction` extensions.
+ *
+ * **The three orchestrator stages:**
+ *
+ * ```
+ *   Content                 Query                    Query
+ *      │                      │                       │
+ *      ▼                      ▼                       ▼
+ *  ┌─────────┐          ┌─────────────┐         ┌─────────────┐
+ *  │ Ingest  │          │   Recall    │         │    Read     │
+ *  │ Stage   │          │   Stage     │         │   Stage     │
+ *  │ (input) │          │  (memory)   │         │  (reader)   │
+ *  └─────────┘          └─────────────┘         └─────────────┘
+ *      │                      │                       │
+ *      ▼                      ▼                       ▼
+ *  Memory state          Retrieved traces         Final answer
+ * ```
+ *
+ * Output guardrails (a separate, existing concern) sit downstream of the
+ * Read stage's answer to enforce safety and policy.
+ *
+ * **Why a composition primitive:** each individual router is independently
+ * useful and ships with its own classifier + dispatcher + table machinery.
+ * CognitivePipeline 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 stage 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 `ingestRouterAsStage` / `memoryRouterAsStage` / `readRouterAsStage`).
+ * - Custom implementations (rule-based, ML-driven, mock for tests) can
+ *   satisfy the same interfaces and slot in.
+ *
+ * @module @framers/agentos/cognitive-pipeline
+ */
+// ============================================================================
+// Errors
+// ============================================================================
+export class MissingStageError extends Error {
+    constructor(stage) {
+        super(`CognitivePipeline: ${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 { CognitivePipeline } from '../cognitive-pipeline/index.js';
+ * import { ingestRouterAsStage } from '../cognitive-pipeline';
+ *
+ * const pipeline = new CognitivePipeline({
+ *   ingest: ingestRouterAsStage(myIngestRouter),
+ *   recall: memoryRouterAsStage(myMemoryRouter),
+ *   read: readRouterAsStage(myReadRouter),
+ * });
+ *
+ * await pipeline.ingest(newContent);
+ * const { outcome } = await pipeline.recallAndRead("what's my latest job?");
+ * ```
+ */
+export class CognitivePipeline {
+    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 `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 `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 `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/cognitive-pipeline/index.js.map

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

package/dist/ingest-router/IngestRouter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file IngestRouter.ts
+ * @description Top-level input-stage orchestrator that composes the
+ * ingest classifier and the pure {@link selectIngestStrategy} into a
+ * single per-content routing call.
+ *
+ * Same shape as MemoryRouter (recall-stage) so the multi-stage guardrails
+ * orchestrator can compose them uniformly. Decide-only and decide+dispatch
+ * flows are both supported.
+ *
+ * @module @framers/agentos/ingest-router/IngestRouter
+ */
+import type { IIngestClassifier, IngestClassifierResult } from './classifier.js';
+import { type IngestStrategyCostPoint } from './costs.js';
+import { type IngestContentKind, type IngestRouterPreset, type IngestRoutingTable, type IngestStrategyId } from './routing-tables.js';
+import { type IngestBudgetMode, type IngestRoutingDecision } from './select-strategy.js';
+import type { IIngestDispatcher } from './dispatcher.js';
+export interface IngestBudgetPolicy {
+    readonly perIngestUsd?: number;
+    readonly mode?: IngestBudgetMode;
+}
+export interface IngestRouterOptions {
+    readonly classifier: IIngestClassifier;
+    readonly preset?: IngestRouterPreset;
+    readonly routingTable?: IngestRoutingTable;
+    readonly mapping?: Partial<Record<IngestContentKind, IngestStrategyId>>;
+    readonly budget?: IngestBudgetPolicy;
+    readonly strategyCosts?: Readonly<Record<IngestStrategyId, IngestStrategyCostPoint>>;
+    readonly useFewShotPrompt?: boolean;
+    readonly dispatcher?: IIngestDispatcher<unknown, unknown>;
+}
+export interface IngestRouterDecideOptions {
+    /**
+     * Optional manual override of the classifier. When set, the classifier
+     * is NOT invoked and the routing table is consulted with this kind
+     * directly. Useful when the caller already knows the content kind
+     * (e.g., file extension determines code vs structured-data).
+     */
+    readonly manualKind?: IngestContentKind;
+    readonly groundTruthKind?: IngestContentKind | null;
+    readonly useFewShotPrompt?: boolean;
+}
+export interface IngestRouterDecision {
+    readonly classifier: IngestClassifierResult;
+    readonly routing: IngestRoutingDecision;
+}
+export interface IngestRouterDispatchedResult<TOutcome> {
+    readonly decision: IngestRouterDecision;
+    readonly outcome: TOutcome;
+    readonly strategy: IngestStrategyId;
+}
+export declare class IngestRouterDispatcherMissingError extends Error {
+    constructor();
+}
+/**
+ * Public input-stage orchestrator. One instance per ingest endpoint;
+ * reuse across content events.
+ */
+export declare class IngestRouter {
+    private readonly classifier;
+    private readonly preset;
+    private readonly routingTable;
+    private readonly budgetPerIngestUsd;
+    private readonly budgetMode;
+    private readonly strategyCosts;
+    private readonly defaultUseFewShotPrompt;
+    private readonly dispatcher;
+    constructor(options: IngestRouterOptions);
+    decide(content: string, options?: IngestRouterDecideOptions): Promise<IngestRouterDecision>;
+    decideAndDispatch<TOutcome, TPayload = undefined>(content: string, dispatchPayload?: TPayload, options?: IngestRouterDecideOptions): Promise<IngestRouterDispatchedResult<TOutcome>>;
+}
+//# sourceMappingURL=IngestRouter.d.ts.map

package/dist/ingest-router/IngestRouter.d.ts.map

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

package/dist/ingest-router/IngestRouter.js

@@ -0,0 +1,98 @@
+/**
+ * @file IngestRouter.ts
+ * @description Top-level input-stage orchestrator that composes the
+ * ingest classifier and the pure {@link selectIngestStrategy} into a
+ * single per-content routing call.
+ *
+ * Same shape as MemoryRouter (recall-stage) so the multi-stage guardrails
+ * orchestrator can compose them uniformly. Decide-only and decide+dispatch
+ * flows are both supported.
+ *
+ * @module @framers/agentos/ingest-router/IngestRouter
+ */
+import { DEFAULT_INGEST_COSTS, } from './costs.js';
+import { PRESET_INGEST_TABLES, } from './routing-tables.js';
+import { selectIngestStrategy, } from './select-strategy.js';
+export class IngestRouterDispatcherMissingError extends Error {
+    constructor() {
+        super('IngestRouter.decideAndDispatch requires a dispatcher. ' +
+            'Either pass a dispatcher in options or call `decide` and dispatch yourself.');
+        this.name = 'IngestRouterDispatcherMissingError';
+    }
+}
+/**
+ * Public input-stage orchestrator. One instance per ingest endpoint;
+ * reuse across content events.
+ */
+export class IngestRouter {
+    constructor(options) {
+        this.classifier = options.classifier;
+        this.preset = options.preset ?? 'raw-chunks';
+        this.dispatcher = options.dispatcher ?? null;
+        const baseTable = options.routingTable ?? PRESET_INGEST_TABLES[this.preset];
+        if (options.mapping) {
+            const patched = {
+                ...baseTable.defaultMapping,
+            };
+            for (const key of Object.keys(options.mapping)) {
+                const ov = options.mapping[key];
+                if (ov)
+                    patched[key] = ov;
+            }
+            this.routingTable = Object.freeze({
+                preset: baseTable.preset,
+                defaultMapping: Object.freeze(patched),
+            });
+        }
+        else {
+            this.routingTable = baseTable;
+        }
+        this.budgetPerIngestUsd = options.budget?.perIngestUsd ?? null;
+        this.budgetMode = options.budget?.mode ?? 'cheapest-fallback';
+        this.strategyCosts = options.strategyCosts ?? DEFAULT_INGEST_COSTS;
+        this.defaultUseFewShotPrompt = options.useFewShotPrompt ?? false;
+    }
+    async decide(content, options) {
+        let classifier;
+        if (options?.manualKind) {
+            classifier = {
+                kind: options.manualKind,
+                tokensIn: 0,
+                tokensOut: 0,
+                model: 'manual',
+            };
+        }
+        else {
+            const useFewShot = options?.useFewShotPrompt ?? this.defaultUseFewShotPrompt;
+            classifier = await this.classifier.classify(content, useFewShot ? { useFewShotPrompt: true } : undefined);
+        }
+        const routing = selectIngestStrategy({
+            predictedKind: classifier.kind,
+            groundTruthKind: options?.groundTruthKind ?? null,
+            config: {
+                table: this.routingTable,
+                budgetPerIngestUsd: this.budgetPerIngestUsd,
+                budgetMode: this.budgetMode,
+                strategyCosts: this.strategyCosts,
+            },
+        });
+        return { classifier, routing };
+    }
+    async decideAndDispatch(content, dispatchPayload, options) {
+        if (!this.dispatcher) {
+            throw new IngestRouterDispatcherMissingError();
+        }
+        const decision = await this.decide(content, options);
+        const dispatched = (await this.dispatcher.dispatch({
+            strategy: decision.routing.chosenStrategy,
+            content,
+            payload: dispatchPayload,
+        }));
+        return {
+            decision,
+            outcome: dispatched.outcome,
+            strategy: dispatched.strategy,
+        };
+    }
+}
+//# sourceMappingURL=IngestRouter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IngestRouter.js","sourceRoot":"","sources":["../../src/ingest-router/IngestRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EACL,oBAAoB,GAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,GAKrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,GAGrB,MAAM,sBAAsB,CAAC;AA+C9B,MAAM,OAAO,kCAAmC,SAAQ,KAAK;IAC3D;QACE,KAAK,CACH,wDAAwD;YACtD,6EAA6E,CAChF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oCAAoC,CAAC;IACnD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,YAAY;IAYvB,YAAY,OAA4B;QACtC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC;QAC7C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;QAE7C,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,IAAI,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5E,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,OAAO,GAAgD;gBAC3D,GAAG,SAAS,CAAC,cAAc;aAC5B,CAAC;YACF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAwB,EAAE,CAAC;gBACtE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAChC,IAAI,EAAE;oBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;YAC5B,CAAC;YACD,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;gBAChC,MAAM,EAAE,SAAS,CAAC,MAAM;gBACxB,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;aACvC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAChC,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,YAAY,IAAI,IAAI,CAAC;QAC/D,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,IAAI,mBAAmB,CAAC;QAC9D,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,oBAAoB,CAAC;QACnE,IAAI,CAAC,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,IAAI,KAAK,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,MAAM,CACV,OAAe,EACf,OAAmC;QAEnC,IAAI,UAAkC,CAAC;QACvC,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC;YACxB,UAAU,GAAG;gBACX,IAAI,EAAE,OAAO,CAAC,UAAU;gBACxB,QAAQ,EAAE,CAAC;gBACX,SAAS,EAAE,CAAC;gBACZ,KAAK,EAAE,QAAQ;aAChB,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,UAAU,GACd,OAAO,EAAE,gBAAgB,IAAI,IAAI,CAAC,uBAAuB,CAAC;YAC5D,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,CACzC,OAAO,EACP,UAAU,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CACpD,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,oBAAoB,CAAC;YACnC,aAAa,EAAE,UAAU,CAAC,IAAI;YAC9B,eAAe,EAAE,OAAO,EAAE,eAAe,IAAI,IAAI;YACjD,MAAM,EAAE;gBACN,KAAK,EAAE,IAAI,CAAC,YAAY;gBACxB,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;gBAC3C,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;aAClC;SACF,CAAC,CAAC;QAEH,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,iBAAiB,CACrB,OAAe,EACf,eAA0B,EAC1B,OAAmC;QAEnC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,MAAM,IAAI,kCAAkC,EAAE,CAAC;QACjD,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACrD,MAAM,UAAU,GAAG,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YACjD,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,cAAc;YACzC,OAAO;YACP,OAAO,EAAE,eAA0B;SACpC,CAAC,CAAmC,CAAC;QAEtC,OAAO;YACL,QAAQ;YACR,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,QAAQ,EAAE,UAAU,CAAC,QAAQ;SAC9B,CAAC;IACJ,CAAC;CACF"}

package/dist/ingest-router/classifier.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file classifier.ts
+ * @description LLM-as-judge classifier that maps a piece of content to
+ * one of the six {@link IngestContentKind} values.
+ *
+ * Same shape as the memory-router classifier — deliberately so the
+ * multi-stage guardrails orchestrator can compose them with one mental
+ * model.
+ *
+ * @module @framers/agentos/ingest-router/classifier
+ */
+import { type IngestContentKind } from './routing-tables.js';
+export interface IngestClassifierLLMRequest {
+    readonly system: string;
+    readonly user: string;
+    readonly maxTokens: number;
+    readonly temperature: number;
+}
+export interface IngestClassifierLLMResponse {
+    readonly text: string;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly model: string;
+}
+export interface IIngestClassifierLLM {
+    invoke(request: IngestClassifierLLMRequest): Promise<IngestClassifierLLMResponse>;
+}
+export interface IngestClassifierClassifyOptions {
+    /** Use the few-shot prompt variant (more accurate on ambiguous content). */
+    readonly useFewShotPrompt?: boolean;
+}
+export interface IngestClassifierResult {
+    readonly kind: IngestContentKind;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly model: string;
+}
+export interface IIngestClassifier {
+    classify(content: string, options?: IngestClassifierClassifyOptions): Promise<IngestClassifierResult>;
+}
+export declare const INGEST_CLASSIFIER_SYSTEM_PROMPT = "You are classifying a piece of content into one of six ingest kinds for memory storage.\n\nReturn ONLY the kind token (no explanation, no quotes, no punctuation).\n\nKinds:\n- short-conversation: 1-3 turns of chat dialog. Examples: a one-message Q&A, a brief support exchange.\n- long-conversation: extended chat sessions across many turns. Examples: a 50-turn coding conversation, a 30-turn customer support thread.\n- long-article: prose document over ~500 words. Examples: a blog post, a research paper section, a long email.\n- code: source code, configuration files, schemas. Examples: a TypeScript module, a SQL migration, a JSON schema.\n- structured-data: tabular or JSON-style records. Examples: a CSV, a JSON list of records, a database export.\n- multimodal: content that includes images, video frames, or audio. Examples: a PDF with figures, a presentation slide.";
+export declare const INGEST_CLASSIFIER_SYSTEM_PROMPT_FEWSHOT = "You are classifying a piece of content into one of six ingest kinds for memory storage.\n\nReturn ONLY the kind token (no explanation, no quotes, no punctuation).\n\nKinds:\n- short-conversation: 1-3 turns of chat dialog.\n- long-conversation: extended chat sessions across many turns.\n- long-article: prose document over ~500 words.\n- code: source code, configuration files, schemas.\n- structured-data: tabular or JSON-style records.\n- multimodal: content that includes images, video frames, or audio.\n\nExamples:\n\nContent: \"user: hi\\nassistant: hi! how can I help?\"\nKind: short-conversation\n\nContent: \"[3000 words of a research paper introduction]\"\nKind: long-article\n\nContent: \"export function fibonacci(n: number): number { return n < 2 ? n : fibonacci(n-1) + fibonacci(n-2); }\"\nKind: code\n\nContent: \"[CSV with 50 rows of user records]\"\nKind: structured-data\n\nContent: \"[40 turns of a customer-support thread]\"\nKind: long-conversation\n\nContent: \"[image bytes + caption text]\"\nKind: multimodal";
+export declare const SAFE_INGEST_FALLBACK_KIND: IngestContentKind;
+export declare function normalizeIngestClassifierOutput(raw: string): string;
+export declare function parseIngestClassifierOutput(raw: string): IngestContentKind;
+export interface LLMIngestClassifierOptions {
+    readonly llm: IIngestClassifierLLM;
+    readonly maxTokens?: number;
+    /**
+     * Maximum content characters to forward to the classifier. Most ingest
+     * decisions can be made from the first ~1k chars (kind detection
+     * doesn't require the full body). Default 1000.
+     */
+    readonly maxContentChars?: number;
+}
+export declare class LLMIngestClassifier implements IIngestClassifier {
+    private readonly llm;
+    private readonly maxTokens;
+    private readonly maxContentChars;
+    constructor(options: LLMIngestClassifierOptions);
+    classify(content: string, options?: IngestClassifierClassifyOptions): Promise<IngestClassifierResult>;
+}
+//# sourceMappingURL=classifier.d.ts.map

package/dist/ingest-router/classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../src/ingest-router/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAM7B,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CACJ,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACzC;AAMD,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACpC;AAMD,eAAO,MAAM,+BAA+B,g3BAU4E,CAAC;AAEzH,eAAO,MAAM,uCAAuC,6gCA8BnC,CAAC;AAElB,eAAO,MAAM,yBAAyB,EAAE,iBAAwC,CAAC;AAEjF,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAcnE;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAY1E;AAMD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,oBAAoB,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,qBAAa,mBAAoB,YAAW,iBAAiB;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,OAAO,EAAE,0BAA0B;IAMzC,QAAQ,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,sBAAsB,CAAC;CAqBnC"}