@framers/agentos-ext-ml-classifiers 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,319 @@
+/**
+ * @fileoverview Core type definitions for the ML Classifier Guardrail Extension Pack.
+ *
+ * This file defines all configuration shapes, runtime result types, and
+ * service-identifier constants used by the ML classifier pipeline. All
+ * classifiers in this pack evaluate text content against learned models
+ * (toxicity, prompt-injection, jailbreak) and emit structured results that
+ * feed into the AgentOS guardrail decision tree.
+ *
+ * Import hierarchy
+ * ----------------
+ * ```
+ * IUtilityAI  ──── ClassificationResult, ClassificationScore
+ * IGuardrailService ── GuardrailAction
+ *                   │
+ *                   ▼
+ *              types.ts  (this file)
+ *                   │
+ *                   ▼
+ *           IContentClassifier.ts  /  SlidingWindowBuffer.ts  /  …
+ * ```
+ *
+ * @module agentos/extensions/packs/ml-classifiers/types
+ */
+import type { ClassificationResult, ClassificationScore } from '@framers/agentos';
+import type { GuardrailAction } from '@framers/agentos';
+export type { ClassificationResult, ClassificationScore };
+/**
+ * Numeric thresholds that map raw classifier confidence scores (0–1) to
+ * guardrail actions.
+ *
+ * The thresholds are applied in descending priority:
+ *  1. `score >= blockThreshold` → {@link GuardrailAction.BLOCK}
+ *  2. `score >= flagThreshold`  → {@link GuardrailAction.FLAG}
+ *  3. `score >= warnThreshold`  → {@link GuardrailAction.SANITIZE}
+ *  4. otherwise                 → {@link GuardrailAction.ALLOW}
+ */
+export interface ClassifierThresholds {
+    /**
+     * Minimum score at which content is **blocked** (interaction terminated).
+     * Must be in the range [0, 1].  Typical default: `0.9`.
+     */
+    blockThreshold: number;
+    /**
+     * Minimum score at which content is **flagged** for review while still
+     * being allowed through.  Must be in the range [0, 1].  Typical default: `0.7`.
+     */
+    flagThreshold: number;
+    /**
+     * Minimum score at which a **warn** action is taken (e.g. the chunk is
+     * sanitised or a warning is appended to the response).  Must be in the range
+     * [0, 1].  Typical default: `0.4`.
+     */
+    warnThreshold: number;
+}
+/**
+ * Sensible defaults for {@link ClassifierThresholds}.
+ *
+ * These values reflect a conservative-but-pragmatic policy:
+ * - block at 90 % confidence → very high bar, minimises false positives
+ * - flag at 70 % → surfaced for human review, not blocked
+ * - warn at 40 % → low-confidence signal, handled with a light touch
+ */
+export declare const DEFAULT_THRESHOLDS: ClassifierThresholds;
+/**
+ * Configuration for a single ML classifier pipeline.
+ *
+ * Allows individual classifiers to override the pack-level defaults for the
+ * model variant and decision thresholds, and to customise which guardrail
+ * action is taken for each classification label.
+ */
+export interface ClassifierConfig {
+    /**
+     * Hugging Face model identifier (e.g. `"Xenova/toxic-bert"`) or a local
+     * model path to load instead of the pack default.
+     * @optional Falls back to the pack-level `MLClassifierPackOptions.modelCacheDir` default.
+     */
+    modelId?: string;
+    /**
+     * Per-classifier threshold overrides.
+     * @optional Falls back to {@link DEFAULT_THRESHOLDS}.
+     */
+    thresholds?: Partial<ClassifierThresholds>;
+    /**
+     * Maps classification labels to the guardrail action that should be taken
+     * when that label is the winning class.
+     *
+     * @example
+     * ```typescript
+     * // Always block on TOXIC label regardless of threshold.
+     * labelActions: { TOXIC: GuardrailAction.BLOCK }
+     * ```
+     */
+    labelActions?: Record<string, GuardrailAction>;
+}
+/**
+ * Configuration for browser-side model execution.
+ *
+ * When the ML classifier pack is loaded in a browser context (e.g. a chat
+ * widget), models run inside a Web Worker to avoid blocking the main thread.
+ * This interface controls worker lifecycle and cache management.
+ */
+export interface BrowserConfig {
+    /**
+     * Run model inference in a Web Worker.
+     * @default true
+     */
+    useWebWorker?: boolean;
+    /**
+     * Caching strategy for downloaded model weights.
+     * - `'memory'`  — keep weights in memory only (lost on page unload)
+     * - `'indexeddb'` — persist weights to IndexedDB (survives reloads)
+     * - `'none'` — no caching; re-download on every page load
+     * @default 'indexeddb'
+     */
+    cacheStrategy?: 'memory' | 'indexeddb' | 'none';
+    /**
+     * Maximum number of model shards to keep in the in-memory cache when
+     * `cacheStrategy === 'memory'`.  Oldest entries are evicted LRU-style.
+     * @default 3
+     */
+    maxCacheSize?: number;
+    /**
+     * Callback invoked with download progress as model weights are fetched.
+     * Useful for showing a progress bar in the UI.
+     *
+     * @param progress - Current progress state.
+     */
+    onProgress?: (progress: ModelDownloadProgress) => void;
+}
+/**
+ * Progress report emitted during model weight downloads.
+ *
+ * @example
+ * ```typescript
+ * onProgress({ modelId: 'Xenova/toxic-bert', loaded: 50_000, total: 200_000, percent: 25 })
+ * ```
+ */
+export interface ModelDownloadProgress {
+    /** Identifier of the model being downloaded (Hugging Face ID or path). */
+    modelId: string;
+    /** Number of bytes downloaded so far. */
+    loaded: number;
+    /** Total number of bytes to download (`0` if unknown). */
+    total: number;
+    /** Download progress as a percentage in the range [0, 100]. */
+    percent: number;
+}
+/**
+ * Top-level configuration for the ML Classifier Extension Pack.
+ *
+ * Passed to `createMLClassifierPack()` (or the NestJS module factory) to
+ * control which classifiers are active, how models are loaded, and how the
+ * sliding-window streaming evaluation behaves.
+ *
+ * @example
+ * ```typescript
+ * const packOptions: MLClassifierPackOptions = {
+ *   classifiers: ['toxicity', 'jailbreak'],
+ *   quantized: true,
+ *   runtime: 'node',
+ *   thresholds: { blockThreshold: 0.95, flagThreshold: 0.75, warnThreshold: 0.5 },
+ *   streamingMode: true,
+ *   chunkSize: 150,
+ *   contextSize: 50,
+ * };
+ * ```
+ */
+export interface MLClassifierPackOptions {
+    /**
+     * Subset of built-in classifiers to activate.
+     * Omit or pass an empty array to activate all built-in classifiers.
+     *
+     * @example `['toxicity', 'injection']`
+     */
+    classifiers?: Array<'toxicity' | 'injection' | 'jailbreak'>;
+    /**
+     * Fully-qualified `IContentClassifier` instances to add alongside the
+     * built-in classifiers (e.g. domain-specific harm classifiers).
+     */
+    customClassifiers?: import('./IContentClassifier').IContentClassifier[];
+    /**
+     * Local filesystem path where downloaded model weights are cached.
+     * Defaults to `~/.cache/agentos/ml-classifiers`.
+     */
+    modelCacheDir?: string;
+    /**
+     * Use 8-bit quantised model variants when available.
+     * Reduces VRAM/RAM footprint and increases inference speed at a small
+     * accuracy cost.
+     * @default false
+     */
+    quantized?: boolean;
+    /**
+     * Execution runtime for model inference.
+     * - `'node'`    — Runs via `@xenova/transformers` in the Node.js process.
+     * - `'browser'` — Runs via `@xenova/transformers` in a Web Worker.
+     * - `'wasm'`    — Explicit WebAssembly fallback (Node.js or browser).
+     * @default 'node'
+     */
+    runtime?: 'node' | 'browser' | 'wasm';
+    /**
+     * Browser-specific options.  Only applicable when `runtime === 'browser'`.
+     */
+    browser?: BrowserConfig;
+    /**
+     * Number of tokens per evaluation window when streaming mode is enabled.
+     * Smaller values detect issues earlier but increase evaluation frequency.
+     * @default 200
+     */
+    chunkSize?: number;
+    /**
+     * Number of tokens from the previous chunk to carry forward as context into
+     * the next window, preventing boundary effects.
+     * @default 50
+     */
+    contextSize?: number;
+    /**
+     * Maximum number of classifier evaluations per stream.  The sliding window
+     * stops advancing after this many evaluations, allowing the stream to
+     * complete without further overhead.
+     * @default 100
+     */
+    maxEvaluations?: number;
+    /**
+     * Enable sliding-window evaluation for streamed (token-by-token) output.
+     * When `false`, classifiers only run on the completed final response.
+     * @default false
+     */
+    streamingMode?: boolean;
+    /**
+     * Pack-level threshold defaults applied to every classifier unless
+     * overridden by a per-classifier {@link ClassifierConfig}.
+     */
+    thresholds?: Partial<ClassifierThresholds>;
+    /**
+     * Scope of guardrail enforcement.
+     * - `'input'`  — Evaluate user messages before orchestration.
+     * - `'output'` — Evaluate agent responses before delivery.
+     * - `'both'`   — Evaluate at both stages.
+     * @default 'both'
+     */
+    guardrailScope?: 'input' | 'output' | 'both';
+}
+/**
+ * Well-known service identifier strings for the three built-in ML classifier
+ * pipelines.
+ *
+ * These IDs follow the `agentos:<domain>:<name>` naming convention used
+ * throughout the AgentOS extension ecosystem.  Use them to retrieve specific
+ * classifier services from the shared service registry.
+ *
+ * @example
+ * ```typescript
+ * const toxicity = serviceRegistry.get(ML_CLASSIFIER_SERVICE_IDS.TOXICITY_PIPELINE);
+ * ```
+ */
+export declare const ML_CLASSIFIER_SERVICE_IDS: {
+    /** Classifier that detects toxic, hateful, or abusive language. */
+    readonly TOXICITY_PIPELINE: "agentos:ml-classifiers:toxicity-pipeline";
+    /** Classifier that detects prompt-injection attempts. */
+    readonly INJECTION_PIPELINE: "agentos:ml-classifiers:injection-pipeline";
+    /** Classifier that detects jailbreak / system-override attempts. */
+    readonly JAILBREAK_PIPELINE: "agentos:ml-classifiers:jailbreak-pipeline";
+};
+/** Union type of all ML classifier service ID strings. */
+export type MLClassifierServiceId = (typeof ML_CLASSIFIER_SERVICE_IDS)[keyof typeof ML_CLASSIFIER_SERVICE_IDS];
+/**
+ * A {@link ClassificationResult} augmented with provenance metadata.
+ *
+ * Produced when a classifier evaluates a chunk of text.  Carries the
+ * classifier's identity and the wall-clock latency so callers can build
+ * audit trails and SLO dashboards.
+ */
+export interface AnnotatedClassificationResult extends ClassificationResult {
+    /**
+     * The {@link IContentClassifier.id} of the classifier that produced this
+     * result (e.g. `ML_CLASSIFIER_SERVICE_IDS.TOXICITY_PIPELINE`).
+     */
+    classifierId: string;
+    /**
+     * Wall-clock time in milliseconds from when `classify()` was called to when
+     * it resolved.
+     */
+    latencyMs: number;
+}
+/**
+ * Aggregated evaluation outcome for a single sliding-window chunk.
+ *
+ * Produced by running all active classifiers against one text window and
+ * collating their results into a single action recommendation.
+ *
+ * The `recommendedAction` is the most restrictive action across all
+ * classifiers (BLOCK > FLAG > SANITIZE > ALLOW).
+ */
+export interface ChunkEvaluation {
+    /**
+     * Individual results from every classifier that evaluated this chunk,
+     * in the order the classifiers were invoked.
+     */
+    results: AnnotatedClassificationResult[];
+    /**
+     * The most restrictive guardrail action recommended across all results.
+     * The pipeline should act on this value rather than iterating `results`
+     * manually.
+     */
+    recommendedAction: GuardrailAction;
+    /**
+     * ID of the classifier that triggered the `recommendedAction`, or `null`
+     * if the action is {@link GuardrailAction.ALLOW} (no classifier triggered).
+     */
+    triggeredBy: string | null;
+    /**
+     * Sum of all classifier `latencyMs` values — useful for profiling the
+     * total evaluation overhead per chunk.
+     */
+    totalLatencyMs: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Core type definitions for the ML Classifier Guardrail Extension Pack.
+ *
+ * This file defines all configuration shapes, runtime result types, and
+ * service-identifier constants used by the ML classifier pipeline. All
+ * classifiers in this pack evaluate text content against learned models
+ * (toxicity, prompt-injection, jailbreak) and emit structured results that
+ * feed into the AgentOS guardrail decision tree.
+ *
+ * Import hierarchy
+ * ----------------
+ * ```
+ * IUtilityAI  ──── ClassificationResult, ClassificationScore
+ * IGuardrailService ── GuardrailAction
+ *                   │
+ *                   ▼
+ *              types.ts  (this file)
+ *                   │
+ *                   ▼
+ *           IContentClassifier.ts  /  SlidingWindowBuffer.ts  /  …
+ * ```
+ *
+ * @module agentos/extensions/packs/ml-classifiers/types
+ */
+/**
+ * Sensible defaults for {@link ClassifierThresholds}.
+ *
+ * These values reflect a conservative-but-pragmatic policy:
+ * - block at 90 % confidence → very high bar, minimises false positives
+ * - flag at 70 % → surfaced for human review, not blocked
+ * - warn at 40 % → low-confidence signal, handled with a light touch
+ */
+export const DEFAULT_THRESHOLDS = {
+    blockThreshold: 0.9,
+    flagThreshold: 0.7,
+    warnThreshold: 0.4,
+};
+// ---------------------------------------------------------------------------
+// Service identifiers
+// ---------------------------------------------------------------------------
+/**
+ * Well-known service identifier strings for the three built-in ML classifier
+ * pipelines.
+ *
+ * These IDs follow the `agentos:<domain>:<name>` naming convention used
+ * throughout the AgentOS extension ecosystem.  Use them to retrieve specific
+ * classifier services from the shared service registry.
+ *
+ * @example
+ * ```typescript
+ * const toxicity = serviceRegistry.get(ML_CLASSIFIER_SERVICE_IDS.TOXICITY_PIPELINE);
+ * ```
+ */
+export const ML_CLASSIFIER_SERVICE_IDS = {
+    /** Classifier that detects toxic, hateful, or abusive language. */
+    TOXICITY_PIPELINE: 'agentos:ml-classifiers:toxicity-pipeline',
+    /** Classifier that detects prompt-injection attempts. */
+    INJECTION_PIPELINE: 'agentos:ml-classifiers:injection-pipeline',
+    /** Classifier that detects jailbreak / system-override attempts. */
+    JAILBREAK_PIPELINE: 'agentos:ml-classifiers:jailbreak-pipeline',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA2CH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAyB;IACtD,cAAc,EAAE,GAAG;IACnB,aAAa,EAAE,GAAG;IAClB,aAAa,EAAE,GAAG;CACV,CAAC;AA6NX,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,mEAAmE;IACnE,iBAAiB,EAAE,0CAA0C;IAE7D,yDAAyD;IACzD,kBAAkB,EAAE,2CAA2C;IAE/D,oEAAoE;IACpE,kBAAkB,EAAE,2CAA2C;CACvD,CAAC"}

package/dist/worker/classifier-worker.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Web Worker entry point for ML content classification.
+ *
+ * This script is loaded by {@link WorkerClassifierProxy} as a dedicated Web
+ * Worker.  It listens for `classify` messages from the main thread, lazily
+ * loads the requested model pipeline via `@huggingface/transformers`, runs
+ * inference, then posts the result (or an error) back.
+ *
+ * ## Message protocol
+ *
+ * **Incoming** (main thread → worker):
+ * ```json
+ * {
+ *   "type": "classify",
+ *   "text":      "<string>",
+ *   "modelId":   "<HuggingFace model ID or local path>",
+ *   "quantized": true | false,
+ *   "taskType":  "<transformers.js task string>"
+ * }
+ * ```
+ *
+ * **Outgoing** (worker → main thread) on success:
+ * ```json
+ * { "type": "result", "result": { "bestClass": "...", "confidence": 0.92, "allScores": [...] } }
+ * ```
+ *
+ * **Outgoing** (worker → main thread) on error:
+ * ```json
+ * { "type": "error", "error": "<error message>" }
+ * ```
+ *
+ * ## Pipeline caching
+ * The pipeline is loaded once per `(modelId, taskType)` key and cached in
+ * a module-level `Map`.  Subsequent `classify` messages for the same model
+ * reuse the cached instance, avoiding repeated expensive model downloads and
+ * WASM initialisation.
+ *
+ * ## Raw label normalisation
+ * The worker normalises the raw `@huggingface/transformers` output (an array
+ * of `{ label, score }` objects when called with `topk: null`) into the
+ * AgentOS {@link ClassificationResult} shape:
+ *  - `bestClass`  — label with the highest score
+ *  - `confidence` — score of the winning label
+ *  - `allScores`  — all labels mapped to `{ classLabel, score }` pairs
+ *
+ * @module agentos/extensions/packs/ml-classifiers/worker/classifier-worker
+ */
+export {};
+//# sourceMappingURL=classifier-worker.d.ts.map

package/dist/worker/classifier-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier-worker.d.ts","sourceRoot":"","sources":["../../src/worker/classifier-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG"}

package/dist/worker/classifier-worker.js

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview Web Worker entry point for ML content classification.
+ *
+ * This script is loaded by {@link WorkerClassifierProxy} as a dedicated Web
+ * Worker.  It listens for `classify` messages from the main thread, lazily
+ * loads the requested model pipeline via `@huggingface/transformers`, runs
+ * inference, then posts the result (or an error) back.
+ *
+ * ## Message protocol
+ *
+ * **Incoming** (main thread → worker):
+ * ```json
+ * {
+ *   "type": "classify",
+ *   "text":      "<string>",
+ *   "modelId":   "<HuggingFace model ID or local path>",
+ *   "quantized": true | false,
+ *   "taskType":  "<transformers.js task string>"
+ * }
+ * ```
+ *
+ * **Outgoing** (worker → main thread) on success:
+ * ```json
+ * { "type": "result", "result": { "bestClass": "...", "confidence": 0.92, "allScores": [...] } }
+ * ```
+ *
+ * **Outgoing** (worker → main thread) on error:
+ * ```json
+ * { "type": "error", "error": "<error message>" }
+ * ```
+ *
+ * ## Pipeline caching
+ * The pipeline is loaded once per `(modelId, taskType)` key and cached in
+ * a module-level `Map`.  Subsequent `classify` messages for the same model
+ * reuse the cached instance, avoiding repeated expensive model downloads and
+ * WASM initialisation.
+ *
+ * ## Raw label normalisation
+ * The worker normalises the raw `@huggingface/transformers` output (an array
+ * of `{ label, score }` objects when called with `topk: null`) into the
+ * AgentOS {@link ClassificationResult} shape:
+ *  - `bestClass`  — label with the highest score
+ *  - `confidence` — score of the winning label
+ *  - `allScores`  — all labels mapped to `{ classLabel, score }` pairs
+ *
+ * @module agentos/extensions/packs/ml-classifiers/worker/classifier-worker
+ */
+// ---------------------------------------------------------------------------
+// Pipeline cache
+// ---------------------------------------------------------------------------
+/**
+ * Cache key composed of `modelId` and `taskType` so different task types
+ * for the same model ID are kept separate.
+ *
+ * @param modelId  - Hugging Face model ID or local path.
+ * @param taskType - transformers.js task string.
+ * @returns Cache key string.
+ */
+function cacheKey(modelId, taskType) {
+    return `${taskType}::${modelId}`;
+}
+/**
+ * Module-level pipeline cache.
+ *
+ * Maps cache keys (see {@link cacheKey}) to loaded pipeline functions.
+ * Populated lazily on the first `classify` message for each unique
+ * `(modelId, taskType)` combination.
+ */
+const pipelineCache = new Map();
+// ---------------------------------------------------------------------------
+// Classification logic
+// ---------------------------------------------------------------------------
+/**
+ * Load (or retrieve from cache) the text-classification pipeline for the
+ * given model and run inference on `text`.
+ *
+ * @param request - The incoming classify request.
+ * @returns A promise resolving with the raw label array from the pipeline.
+ * @throws If the pipeline fails to load or inference throws.
+ */
+async function runPipeline(request) {
+    const key = cacheKey(request.modelId, request.taskType);
+    // Check the cache first to avoid re-loading on every message.
+    let pipe = pipelineCache.get(key);
+    if (!pipe) {
+        // Lazy-load the @huggingface/transformers package.
+        // Dynamic import is used so this module can be evaluated in environments
+        // where the package is optional (the Worker is only instantiated when
+        // browser runtime is active and the package is present).
+        const { pipeline: createPipeline } = await import('@huggingface/transformers');
+        // Create the pipeline with quantisation option from the request.
+        const newPipe = await createPipeline(request.taskType, request.modelId, {
+            quantized: request.quantized,
+        });
+        // Store in cache and narrow the type.
+        pipe = newPipe;
+        pipelineCache.set(key, pipe);
+    }
+    // Run inference — request all label scores (topk: null).
+    return pipe(request.text, { topk: null });
+}
+/**
+ * Normalise raw pipeline output into an AgentOS {@link ClassificationResult}.
+ *
+ * @param raw - Array of `{ label, score }` objects from the pipeline.
+ * @returns A fully-populated `ClassificationResult`.
+ */
+function normaliseResult(raw) {
+    if (!raw || raw.length === 0) {
+        // No output — return a benign pass result so the orchestrator treats this
+        // as ALLOW rather than an error.
+        return { bestClass: 'benign', confidence: 0, allScores: [] };
+    }
+    // Find the label with the highest confidence score.
+    let best = raw[0];
+    for (const item of raw) {
+        if (item.score > best.score) {
+            best = item;
+        }
+    }
+    // Map every label to the AgentOS ClassificationScore shape.
+    const allScores = raw.map((item) => ({
+        classLabel: item.label,
+        score: item.score,
+    }));
+    return {
+        bestClass: best.label,
+        confidence: best.score,
+        allScores,
+    };
+}
+// ---------------------------------------------------------------------------
+// Message handler
+// ---------------------------------------------------------------------------
+/**
+ * Handle a `classify` message from the main thread.
+ *
+ * Runs the pipeline and posts either a {@link ResultMessage} or an
+ * {@link ErrorMessage} back to the main thread.
+ *
+ * @param request - The incoming classify request.
+ */
+async function handleClassify(request) {
+    try {
+        const raw = await runPipeline(request);
+        const result = normaliseResult(raw);
+        const response = { type: 'result', result };
+        self.postMessage(response);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const response = { type: 'error', error: message };
+        self.postMessage(response);
+    }
+}
+// ---------------------------------------------------------------------------
+// Worker bootstrap — listen for messages from the main thread
+// ---------------------------------------------------------------------------
+/**
+ * The primary message listener for this Worker.
+ *
+ * Dispatches incoming messages to {@link handleClassify} when the message
+ * type is `'classify'`.  All other message types are ignored with a warning
+ * logged to the Worker console (useful for debugging unexpected messages
+ * during development).
+ */
+self.onmessage = (event) => {
+    const data = event.data;
+    if (data?.type === 'classify') {
+        // Kick off async classification.  Errors are caught inside handleClassify
+        // and posted back as ErrorMessage, so we do not need a top-level catch here.
+        void handleClassify(data);
+    }
+    else {
+        // Unknown message type — log and ignore.
+        console.warn('[classifier-worker] Received unexpected message type:', data?.type ?? data);
+    }
+};
+export {};
+//# sourceMappingURL=classifier-worker.js.map

package/dist/worker/classifier-worker.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@framers/agentos-ext-ml-classifiers",
+  "version": "0.1.0",
+  "description": "ML-based content classification guardrail (toxicity, injection, jailbreak) for AgentOS",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "SKILL.md",
+    "manifest.json"
+  ],
+  "peerDependencies": {
+    "@framers/agentos": "^0.1.0"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^3.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0",
+    "@framers/agentos": "0.1.47"
+  },
+  "license": "MIT",
+  "author": "Frame.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/framersai/agentos-extensions.git",
+    "directory": "registry/curated/safety/ml-classifiers"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}