@framers/agentos-ext-ml-classifiers 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Framers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/dist/ClassifierOrchestrator.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Orchestrator for parallel ML classifier execution with worst-wins aggregation.
+ *
+ * The `ClassifierOrchestrator` runs all registered {@link IContentClassifier}
+ * instances in parallel against a single text input and aggregates their
+ * results into a single {@link ChunkEvaluation}.  The aggregation policy is
+ * **worst-wins**: if any classifier recommends BLOCK the overall result is
+ * BLOCK, even if every other classifier returned ALLOW.
+ *
+ * Priority order (descending):
+ * ```
+ * BLOCK > FLAG > SANITIZE > ALLOW
+ * ```
+ *
+ * Each classifier may have its own threshold overrides (via
+ * `perClassifierThresholds`), and individual labels can be mapped to
+ * hard-coded actions via `ClassifierConfig.labelActions`.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/ClassifierOrchestrator
+ */
+import type { IContentClassifier } from './IContentClassifier';
+import type { ChunkEvaluation, ClassifierThresholds } from './types';
+/**
+ * Drives all registered ML classifiers in parallel and folds their results
+ * into a single {@link ChunkEvaluation} using worst-wins aggregation.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = new ClassifierOrchestrator(
+ *   [toxicityClassifier, injectionClassifier],
+ *   DEFAULT_THRESHOLDS,
+ * );
+ *
+ * const evaluation = await orchestrator.classifyAll('some user message');
+ * if (evaluation.recommendedAction === GuardrailAction.BLOCK) {
+ *   // Terminate the interaction.
+ * }
+ * ```
+ */
+export declare class ClassifierOrchestrator {
+    /** Immutable list of classifiers to run on every `classifyAll()` call. */
+    private readonly classifiers;
+    /** Merged default thresholds (pack-level defaults + caller overrides). */
+    private readonly defaultThresholds;
+    /**
+     * Optional per-classifier threshold overrides, keyed by classifier ID.
+     * When a classifier's ID appears here, the partial thresholds are merged
+     * on top of {@link defaultThresholds} for that classifier only.
+     */
+    private readonly perClassifierThresholds;
+    /**
+     * Create a new orchestrator.
+     *
+     * @param classifiers            - Array of classifier instances to run in parallel.
+     * @param defaultThresholds      - Pack-level threshold defaults applied to every classifier
+     *                                 unless overridden by `perClassifierThresholds`.
+     * @param perClassifierThresholds - Optional map from classifier ID to partial threshold
+     *                                  overrides.  Missing fields fall back to `defaultThresholds`.
+     */
+    constructor(classifiers: IContentClassifier[], defaultThresholds?: ClassifierThresholds, perClassifierThresholds?: Record<string, Partial<ClassifierThresholds>>);
+    /**
+     * Classify `text` against every registered classifier in parallel and
+     * return the aggregated {@link ChunkEvaluation}.
+     *
+     * Execution details:
+     * 1. All classifiers run concurrently via `Promise.allSettled`.
+     * 2. Fulfilled results are wrapped as {@link AnnotatedClassificationResult}
+     *    with provenance metadata (`classifierId`, `latencyMs`).
+     * 3. Rejected promises log a warning and contribute an implicit ALLOW so
+     *    a single broken classifier does not block all content.
+     * 4. Each result is mapped to a {@link GuardrailAction} using
+     *    per-classifier thresholds (if configured) or the pack defaults.
+     * 5. The final `recommendedAction` is the most restrictive action across
+     *    all classifiers (worst-wins).
+     *
+     * @param text - The text to evaluate.  Must not be empty.
+     * @returns A promise resolving to the aggregated evaluation result.
+     */
+    classifyAll(text: string): Promise<ChunkEvaluation>;
+    /**
+     * Dispose every registered classifier, releasing model weights and any
+     * other resources they hold.
+     *
+     * Calls each classifier's `dispose()` method (if present) and swallows
+     * errors so a single failing classifier does not prevent cleanup of the
+     * others.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Invoke a single classifier with wall-clock latency tracking.
+     *
+     * Wraps `classifier.classify(text)` and returns the raw
+     * {@link ClassificationResult} augmented with `classifierId` and
+     * `latencyMs` fields.
+     *
+     * @param classifier - The classifier to invoke.
+     * @param text       - The text to classify.
+     * @returns An annotated result with provenance metadata.
+     */
+    private timedClassify;
+    /**
+     * Map a classifier's confidence score to a {@link GuardrailAction}.
+     *
+     * The mapping checks `labelActions` first (from per-classifier config in
+     * thresholds), then falls back to numeric threshold comparison:
+     *
+     * 1. `confidence >= blockThreshold` -> BLOCK
+     * 2. `confidence >= flagThreshold`  -> FLAG
+     * 3. `confidence >= warnThreshold`  -> SANITIZE
+     * 4. otherwise                      -> ALLOW
+     *
+     * @param result     - The annotated classification result.
+     * @param thresholds - Resolved thresholds for this classifier.
+     * @returns The appropriate guardrail action.
+     */
+    private scoreToAction;
+    /**
+     * Resolve the effective thresholds for a given classifier by merging
+     * per-classifier overrides on top of the pack-level defaults.
+     *
+     * @param classifierId - ID of the classifier to resolve thresholds for.
+     * @returns Fully-resolved thresholds with no undefined fields.
+     */
+    private resolveThresholds;
+}
+//# sourceMappingURL=ClassifierOrchestrator.d.ts.map

package/dist/ClassifierOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClassifierOrchestrator.d.ts","sourceRoot":"","sources":["../src/ClassifierOrchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAEV,eAAe,EACf,oBAAoB,EAErB,MAAM,SAAS,CAAC;AAwBjB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAsB;IAKjC,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;IAEnD,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuB;IAEzD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAgD;IAMxF;;;;;;;;OAQG;gBAED,WAAW,EAAE,kBAAkB,EAAE,EACjC,iBAAiB,GAAE,oBAAyC,EAC5D,uBAAuB,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAM;IAW7E;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAoDzD;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAc9B;;;;;;;;;;OAUG;YACW,aAAa;IAe3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,aAAa;IAwBrB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;CAY1B"}

package/dist/ClassifierOrchestrator.js

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Orchestrator for parallel ML classifier execution with worst-wins aggregation.
+ *
+ * The `ClassifierOrchestrator` runs all registered {@link IContentClassifier}
+ * instances in parallel against a single text input and aggregates their
+ * results into a single {@link ChunkEvaluation}.  The aggregation policy is
+ * **worst-wins**: if any classifier recommends BLOCK the overall result is
+ * BLOCK, even if every other classifier returned ALLOW.
+ *
+ * Priority order (descending):
+ * ```
+ * BLOCK > FLAG > SANITIZE > ALLOW
+ * ```
+ *
+ * Each classifier may have its own threshold overrides (via
+ * `perClassifierThresholds`), and individual labels can be mapped to
+ * hard-coded actions via `ClassifierConfig.labelActions`.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/ClassifierOrchestrator
+ */
+import { DEFAULT_THRESHOLDS } from './types';
+import { GuardrailAction } from '@framers/agentos';
+// ---------------------------------------------------------------------------
+// Action severity ranking — used by worst-wins aggregation
+// ---------------------------------------------------------------------------
+/**
+ * Numeric severity for each {@link GuardrailAction}, where higher values
+ * represent more restrictive actions.  Used to implement the worst-wins
+ * comparison without brittle string ordering.
+ */
+const ACTION_SEVERITY = {
+    [GuardrailAction.ALLOW]: 0,
+    [GuardrailAction.SANITIZE]: 1,
+    [GuardrailAction.FLAG]: 2,
+    [GuardrailAction.BLOCK]: 3,
+};
+// ---------------------------------------------------------------------------
+// ClassifierOrchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Drives all registered ML classifiers in parallel and folds their results
+ * into a single {@link ChunkEvaluation} using worst-wins aggregation.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = new ClassifierOrchestrator(
+ *   [toxicityClassifier, injectionClassifier],
+ *   DEFAULT_THRESHOLDS,
+ * );
+ *
+ * const evaluation = await orchestrator.classifyAll('some user message');
+ * if (evaluation.recommendedAction === GuardrailAction.BLOCK) {
+ *   // Terminate the interaction.
+ * }
+ * ```
+ */
+export class ClassifierOrchestrator {
+    // -------------------------------------------------------------------------
+    // Private state
+    // -------------------------------------------------------------------------
+    /** Immutable list of classifiers to run on every `classifyAll()` call. */
+    classifiers;
+    /** Merged default thresholds (pack-level defaults + caller overrides). */
+    defaultThresholds;
+    /**
+     * Optional per-classifier threshold overrides, keyed by classifier ID.
+     * When a classifier's ID appears here, the partial thresholds are merged
+     * on top of {@link defaultThresholds} for that classifier only.
+     */
+    perClassifierThresholds;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * Create a new orchestrator.
+     *
+     * @param classifiers            - Array of classifier instances to run in parallel.
+     * @param defaultThresholds      - Pack-level threshold defaults applied to every classifier
+     *                                 unless overridden by `perClassifierThresholds`.
+     * @param perClassifierThresholds - Optional map from classifier ID to partial threshold
+     *                                  overrides.  Missing fields fall back to `defaultThresholds`.
+     */
+    constructor(classifiers, defaultThresholds = DEFAULT_THRESHOLDS, perClassifierThresholds = {}) {
+        this.classifiers = classifiers;
+        this.defaultThresholds = defaultThresholds;
+        this.perClassifierThresholds = perClassifierThresholds;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Classify `text` against every registered classifier in parallel and
+     * return the aggregated {@link ChunkEvaluation}.
+     *
+     * Execution details:
+     * 1. All classifiers run concurrently via `Promise.allSettled`.
+     * 2. Fulfilled results are wrapped as {@link AnnotatedClassificationResult}
+     *    with provenance metadata (`classifierId`, `latencyMs`).
+     * 3. Rejected promises log a warning and contribute an implicit ALLOW so
+     *    a single broken classifier does not block all content.
+     * 4. Each result is mapped to a {@link GuardrailAction} using
+     *    per-classifier thresholds (if configured) or the pack defaults.
+     * 5. The final `recommendedAction` is the most restrictive action across
+     *    all classifiers (worst-wins).
+     *
+     * @param text - The text to evaluate.  Must not be empty.
+     * @returns A promise resolving to the aggregated evaluation result.
+     */
+    async classifyAll(text) {
+        // Record wall-clock start time so `totalLatencyMs` reflects the
+        // real-world time spent, not the sum of sequential latencies.
+        const wallStart = performance.now();
+        // Fire all classifiers in parallel and wait for every one to settle.
+        const settled = await Promise.allSettled(this.classifiers.map((c) => this.timedClassify(c, text)));
+        // Accumulate annotated results and track the worst action seen.
+        const results = [];
+        let worstAction = GuardrailAction.ALLOW;
+        let triggeredBy = null;
+        for (let i = 0; i < settled.length; i++) {
+            const outcome = settled[i];
+            const classifier = this.classifiers[i];
+            if (outcome.status === 'fulfilled') {
+                const annotated = outcome.value;
+                results.push(annotated);
+                // Resolve the thresholds for this specific classifier.
+                const thresholds = this.resolveThresholds(classifier.id);
+                // Map the raw confidence score to a guardrail action.
+                const action = this.scoreToAction(annotated, thresholds);
+                // Worst-wins: keep the most restrictive action.
+                if (ACTION_SEVERITY[action] > ACTION_SEVERITY[worstAction]) {
+                    worstAction = action;
+                    triggeredBy = classifier.id;
+                }
+            }
+            else {
+                // Classifier failed — log and contribute an implicit ALLOW.
+                console.warn(`[ClassifierOrchestrator] Classifier "${classifier.id}" failed: ${outcome.reason}`);
+            }
+        }
+        const wallEnd = performance.now();
+        return {
+            results,
+            recommendedAction: worstAction,
+            triggeredBy,
+            totalLatencyMs: Math.round(wallEnd - wallStart),
+        };
+    }
+    /**
+     * Dispose every registered classifier, releasing model weights and any
+     * other resources they hold.
+     *
+     * Calls each classifier's `dispose()` method (if present) and swallows
+     * errors so a single failing classifier does not prevent cleanup of the
+     * others.
+     */
+    async dispose() {
+        await Promise.allSettled(this.classifiers.map(async (c) => {
+            if (c.dispose) {
+                await c.dispose();
+            }
+        }));
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Invoke a single classifier with wall-clock latency tracking.
+     *
+     * Wraps `classifier.classify(text)` and returns the raw
+     * {@link ClassificationResult} augmented with `classifierId` and
+     * `latencyMs` fields.
+     *
+     * @param classifier - The classifier to invoke.
+     * @param text       - The text to classify.
+     * @returns An annotated result with provenance metadata.
+     */
+    async timedClassify(classifier, text) {
+        const start = performance.now();
+        const result = await classifier.classify(text);
+        const latencyMs = Math.round(performance.now() - start);
+        return {
+            ...result,
+            classifierId: classifier.id,
+            latencyMs,
+        };
+    }
+    /**
+     * Map a classifier's confidence score to a {@link GuardrailAction}.
+     *
+     * The mapping checks `labelActions` first (from per-classifier config in
+     * thresholds), then falls back to numeric threshold comparison:
+     *
+     * 1. `confidence >= blockThreshold` -> BLOCK
+     * 2. `confidence >= flagThreshold`  -> FLAG
+     * 3. `confidence >= warnThreshold`  -> SANITIZE
+     * 4. otherwise                      -> ALLOW
+     *
+     * @param result     - The annotated classification result.
+     * @param thresholds - Resolved thresholds for this classifier.
+     * @returns The appropriate guardrail action.
+     */
+    scoreToAction(result, thresholds) {
+        // Extract the confidence as a single number.
+        // ClassificationResult.confidence may be number | number[]; normalise.
+        const confidence = Array.isArray(result.confidence)
+            ? result.confidence[0] ?? 0
+            : result.confidence;
+        // Threshold comparison — checked in descending severity order.
+        if (confidence >= thresholds.blockThreshold) {
+            return GuardrailAction.BLOCK;
+        }
+        if (confidence >= thresholds.flagThreshold) {
+            return GuardrailAction.FLAG;
+        }
+        if (confidence >= thresholds.warnThreshold) {
+            return GuardrailAction.SANITIZE;
+        }
+        return GuardrailAction.ALLOW;
+    }
+    /**
+     * Resolve the effective thresholds for a given classifier by merging
+     * per-classifier overrides on top of the pack-level defaults.
+     *
+     * @param classifierId - ID of the classifier to resolve thresholds for.
+     * @returns Fully-resolved thresholds with no undefined fields.
+     */
+    resolveThresholds(classifierId) {
+        const overrides = this.perClassifierThresholds[classifierId];
+        if (!overrides) {
+            return this.defaultThresholds;
+        }
+        return {
+            blockThreshold: overrides.blockThreshold ?? this.defaultThresholds.blockThreshold,
+            flagThreshold: overrides.flagThreshold ?? this.defaultThresholds.flagThreshold,
+            warnThreshold: overrides.warnThreshold ?? this.defaultThresholds.warnThreshold,
+        };
+    }
+}
+//# sourceMappingURL=ClassifierOrchestrator.js.map

package/dist/ClassifierOrchestrator.js.map

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

package/dist/IContentClassifier.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Interface contract for ML-backed content classifiers.
+ *
+ * An `IContentClassifier` represents a single model pipeline that accepts
+ * arbitrary text and returns a {@link ClassificationResult} containing the
+ * winning label and confidence scores for all candidate classes.
+ *
+ * Built-in implementations (toxicity, injection, jailbreak) each implement
+ * this interface.  Third-party classifiers may be registered via the
+ * `customClassifiers` option of {@link MLClassifierPackOptions}.
+ *
+ * Lifecycle
+ * ---------
+ * 1. The pack initialises each classifier (model loading, warm-up).
+ * 2. The guardrail pipeline calls `classify()` for every text chunk.
+ * 3. On pack teardown, `dispose()` is called (if present) to release GPU/
+ *    WASM memory.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/IContentClassifier
+ */
+import type { ClassificationResult } from '@framers/agentos';
+/**
+ * Contract for a single ML content classifier.
+ *
+ * Implementations back one model pipeline and expose a narrow classify/dispose
+ * API so the guardrail orchestrator can drive them uniformly regardless of the
+ * underlying runtime (Node.js ONNX, browser WASM, remote inference endpoint).
+ *
+ * @example Minimal custom classifier
+ * ```typescript
+ * class SarcasmClassifier implements IContentClassifier {
+ *   readonly id = 'custom:sarcasm-detector';
+ *   readonly displayName = 'Sarcasm Detector';
+ *   readonly description = 'Detects sarcastic or ironic statements.';
+ *   readonly modelId = 'my-org/sarcasm-bert';
+ *   isLoaded = false;
+ *
+ *   async classify(text: string): Promise<ClassificationResult> {
+ *     // … run inference …
+ *     return { bestClass: 'NOT_SARCASTIC', confidence: 0.8, allScores: [] };
+ *   }
+ *
+ *   async dispose(): Promise<void> {
+ *     // Free resources.
+ *   }
+ * }
+ * ```
+ */
+export interface IContentClassifier {
+    /**
+     * Unique service identifier for this classifier.
+     *
+     * Must follow the `agentos:<domain>:<name>` convention so it can be
+     * registered with the AgentOS shared service registry.
+     *
+     * @example `'agentos:ml-classifiers:toxicity-pipeline'`
+     */
+    readonly id: string;
+    /**
+     * Human-readable name displayed in logs and dashboards.
+     *
+     * @example `'Toxicity Pipeline'`
+     */
+    readonly displayName: string;
+    /**
+     * Short prose description of what this classifier detects.
+     *
+     * @example `'Detects toxic, hateful, or abusive language in text.'`
+     */
+    readonly description: string;
+    /**
+     * Identifier of the underlying model being used, typically a Hugging Face
+     * model ID or a local filesystem path.
+     *
+     * @example `'Xenova/toxic-bert'`
+     */
+    readonly modelId: string;
+    /**
+     * Whether the model weights have been fully loaded into memory and the
+     * classifier is ready to accept `classify()` calls.
+     *
+     * The pack initialiser sets this to `true` after the warm-up inference
+     * succeeds.  Callers can check this flag before calling `classify()` to
+     * avoid queueing calls during a slow model download.
+     */
+    isLoaded: boolean;
+    /**
+     * Classify the provided text and return confidence scores for all candidate
+     * labels.
+     *
+     * The classifier is responsible for mapping raw model output to the
+     * {@link ClassificationResult} shape.  It should NOT apply thresholds or
+     * guardrail actions — that is the responsibility of the pack orchestrator.
+     *
+     * @param text - The text to classify.  May be a short chunk from a streaming
+     *   response or a complete message.  Must not be empty.
+     * @returns A promise that resolves with the classification result, including
+     *   the winning label (`bestClass`), its `confidence`, and `allScores` for
+     *   every label the model evaluated.
+     * @throws {Error} If the model is not loaded (`isLoaded === false`) or if
+     *   inference fails for an unrecoverable reason.
+     */
+    classify(text: string): Promise<ClassificationResult>;
+    /**
+     * Release all resources held by this classifier (model weights, WASM
+     * module, GPU buffers, worker threads, etc.).
+     *
+     * Called by the pack orchestrator during AgentOS shutdown or when the pack
+     * is unloaded.  Implementations should be idempotent — calling `dispose()`
+     * multiple times must not throw.
+     *
+     * @optional Classifiers that hold no persistent resources may omit this
+     *   method.
+     */
+    dispose?(): Promise<void>;
+}
+//# sourceMappingURL=IContentClassifier.d.ts.map

package/dist/IContentClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IContentClassifier.d.ts","sourceRoot":"","sources":["../src/IContentClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;;OAOG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEtD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/IContentClassifier.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Interface contract for ML-backed content classifiers.
+ *
+ * An `IContentClassifier` represents a single model pipeline that accepts
+ * arbitrary text and returns a {@link ClassificationResult} containing the
+ * winning label and confidence scores for all candidate classes.
+ *
+ * Built-in implementations (toxicity, injection, jailbreak) each implement
+ * this interface.  Third-party classifiers may be registered via the
+ * `customClassifiers` option of {@link MLClassifierPackOptions}.
+ *
+ * Lifecycle
+ * ---------
+ * 1. The pack initialises each classifier (model loading, warm-up).
+ * 2. The guardrail pipeline calls `classify()` for every text chunk.
+ * 3. On pack teardown, `dispose()` is called (if present) to release GPU/
+ *    WASM memory.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/IContentClassifier
+ */
+export {};
+//# sourceMappingURL=IContentClassifier.js.map

package/dist/IContentClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IContentClassifier.js","sourceRoot":"","sources":["../src/IContentClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}