@framers/agentos-ext-ml-classifiers 0.1.0

package/dist/classifiers/WorkerClassifierProxy.js

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview WorkerClassifierProxy — wraps an IContentClassifier to run
+ * inference inside a Web Worker, with automatic main-thread fallback.
+ *
+ * ## Why a proxy?
+ * ML inference (even quantized ONNX / WASM pipelines) can block the main
+ * thread for 50–500 ms per classification.  Moving classification into a
+ * Web Worker keeps the UI responsive.  This proxy makes the switch
+ * transparent to callers: they still call `classify(text)` and receive a
+ * `ClassificationResult`; the underlying transport (Worker vs. direct call)
+ * is an implementation detail.
+ *
+ * ## Fallback policy
+ * The proxy falls back to direct (main-thread) delegation whenever:
+ *  - The global `Worker` constructor is undefined (Node.js, older browsers).
+ *  - `browserConfig.useWebWorker` is explicitly `false`.
+ *  - Worker creation throws (e.g. strict CSP that blocks `blob:` URLs).
+ *
+ * Once a fallback has been triggered by a Worker creation error the proxy
+ * sets `workerFailed = true` and remains in fallback mode for all subsequent
+ * calls.
+ *
+ * ## IContentClassifier contract
+ * The proxy forwards all identity fields (`id`, `displayName`, `description`,
+ * `modelId`) and the `isLoaded` state directly from the wrapped classifier so
+ * it is completely transparent to the orchestrator.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/classifiers/WorkerClassifierProxy
+ */
+// ---------------------------------------------------------------------------
+// WorkerClassifierProxy
+// ---------------------------------------------------------------------------
+/**
+ * Transparent proxy around an {@link IContentClassifier} that offloads
+ * `classify()` calls to a Web Worker when the browser environment supports it.
+ *
+ * In all other environments (Node.js, strict CSP, explicit opt-out) the proxy
+ * delegates calls directly to the wrapped classifier on the main thread.
+ *
+ * @implements {IContentClassifier}
+ *
+ * @example Browser context — Web Worker path
+ * ```typescript
+ * const toxicity = new ToxicityClassifier(serviceRegistry);
+ * const proxy = new WorkerClassifierProxy(toxicity, { useWebWorker: true });
+ * const result = await proxy.classify('some text');
+ * ```
+ *
+ * @example Node.js / forced fallback path
+ * ```typescript
+ * const proxy = new WorkerClassifierProxy(toxicity, { useWebWorker: false });
+ * // Delegates directly to toxicity.classify() on the same thread.
+ * ```
+ */
+export class WorkerClassifierProxy {
+    wrapped;
+    browserConfig;
+    // -------------------------------------------------------------------------
+    // IContentClassifier identity — delegated from wrapped classifier
+    // -------------------------------------------------------------------------
+    /**
+     * {@inheritDoc IContentClassifier.id}
+     * Delegated from the wrapped classifier so this proxy is transparent in
+     * the orchestrator's service-ID lookups.
+     */
+    get id() {
+        return this.wrapped.id;
+    }
+    /**
+     * {@inheritDoc IContentClassifier.displayName}
+     * Returns the wrapped classifier's display name with a `(Worker)` suffix
+     * when the Web Worker path is active, so logs clearly indicate the mode.
+     */
+    get displayName() {
+        return this.wrapped.displayName;
+    }
+    /**
+     * {@inheritDoc IContentClassifier.description}
+     * Delegated directly from the wrapped classifier.
+     */
+    get description() {
+        return this.wrapped.description;
+    }
+    /**
+     * {@inheritDoc IContentClassifier.modelId}
+     * Delegated directly from the wrapped classifier.
+     */
+    get modelId() {
+        return this.wrapped.modelId;
+    }
+    /**
+     * {@inheritDoc IContentClassifier.isLoaded}
+     *
+     * Reflects the wrapped classifier's `isLoaded` state.  The wrapped
+     * instance is the authoritative source because it owns the model weights
+     * (whether they live in the Worker or on the main thread).
+     */
+    get isLoaded() {
+        return this.wrapped.isLoaded;
+    }
+    /**
+     * IContentClassifier requires `isLoaded` to be settable via the interface
+     * contract (`isLoaded: boolean`).  We store the value through the wrapped
+     * classifier so the authoritative state lives in one place.
+     */
+    set isLoaded(value) {
+        this.wrapped.isLoaded = value;
+    }
+    // -------------------------------------------------------------------------
+    // Internal state
+    // -------------------------------------------------------------------------
+    /**
+     * Set to `true` after a Worker creation failure.  Once set, all subsequent
+     * `classify()` calls are routed directly to the wrapped classifier without
+     * attempting to re-create the Worker.
+     */
+    workerFailed = false;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * Create a WorkerClassifierProxy.
+     *
+     * @param wrapped       - The real classifier to delegate to.  In Worker
+     *                        mode this classifier is still responsible for
+     *                        model loading and inference; the proxy just
+     *                        changes the thread on which it executes.
+     * @param browserConfig - Optional browser-side configuration.  Controls
+     *                        whether Worker mode is attempted
+     *                        (`useWebWorker`, default `true`).
+     */
+    constructor(wrapped, browserConfig) {
+        this.wrapped = wrapped;
+        this.browserConfig = browserConfig;
+    }
+    // -------------------------------------------------------------------------
+    // classify
+    // -------------------------------------------------------------------------
+    /**
+     * Classify the provided text, routing to a Web Worker when available.
+     *
+     * ### Routing decision (evaluated once per call)
+     * 1. `typeof Worker === 'undefined'` → fallback (Node.js / no Worker API).
+     * 2. `browserConfig.useWebWorker === false` → fallback (explicit opt-out).
+     * 3. `workerFailed === true` → fallback (previous Worker creation error).
+     * 4. Otherwise → attempt to run in a Web Worker.
+     *
+     * If the Worker is created but fails to post a result within the
+     * classification request, the error is propagated as a rejected promise
+     * (not silently swallowed) so the orchestrator can log and fall back at
+     * a higher level.
+     *
+     * @param text - The text to classify.  Must not be empty.
+     * @returns A promise that resolves with the classification result.
+     */
+    async classify(text) {
+        // Determine whether to use a Web Worker.
+        const shouldUseWorker = this.shouldUseWebWorker();
+        if (!shouldUseWorker) {
+            // Fallback: delegate directly to the wrapped classifier on this thread.
+            return this.wrapped.classify(text);
+        }
+        // Attempt to classify in a Worker.
+        return this.classifyInWorker(text);
+    }
+    // -------------------------------------------------------------------------
+    // dispose (optional IContentClassifier lifecycle hook)
+    // -------------------------------------------------------------------------
+    /**
+     * Release resources held by the wrapped classifier.
+     *
+     * Delegates to `wrapped.dispose()` if it exists.  Idempotent.
+     */
+    async dispose() {
+        if (this.wrapped.dispose) {
+            await this.wrapped.dispose();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Determine whether the current environment and configuration support
+     * running inference in a Web Worker.
+     *
+     * @returns `true` when Web Worker mode should be attempted.
+     */
+    shouldUseWebWorker() {
+        // Worker API is not available (Node.js, JSDOM without worker support, etc.)
+        if (typeof Worker === 'undefined') {
+            return false;
+        }
+        // Caller explicitly opted out of Web Worker mode.
+        if (this.browserConfig?.useWebWorker === false) {
+            return false;
+        }
+        // A previous Worker creation attempt failed — stay on main thread.
+        if (this.workerFailed) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Run `classify(text)` inside a transient Web Worker.
+     *
+     * Each call creates a new Worker, sends a single `classify` message,
+     * awaits the `result` or `error` response, then terminates the Worker.
+     *
+     * If Worker creation itself throws (e.g. CSP violation), `workerFailed`
+     * is set to `true` and the call falls back to the wrapped classifier on
+     * the main thread.
+     *
+     * @param text - The text to classify inside the Worker.
+     * @returns A promise resolving with the {@link ClassificationResult}.
+     */
+    async classifyInWorker(text) {
+        let worker;
+        try {
+            // Resolve the Worker script URL.  We use the sibling classifier-worker
+            // module.  In a bundled environment this will be a blob URL or a
+            // `new URL(...)` import; here we use a relative path that bundlers
+            // understand via the standard Worker constructor pattern.
+            worker = new Worker(new URL('../worker/classifier-worker.ts', import.meta.url), {
+                type: 'module',
+            });
+        }
+        catch (err) {
+            // Worker could not be created (CSP, missing support, etc.).
+            // Mark as failed and fall back to the main thread.
+            this.workerFailed = true;
+            console.warn(`[WorkerClassifierProxy] Worker creation failed for "${this.wrapped.id}"; ` +
+                `falling back to main-thread classification. Reason: ${err}`);
+            return this.wrapped.classify(text);
+        }
+        // Build the request message.
+        const request = {
+            type: 'classify',
+            text,
+            modelId: this.wrapped.modelId,
+            // Default to non-quantized; the wrapped classifier's config owns this,
+            // but the Worker needs it to load the right model variant.
+            quantized: false,
+            taskType: 'text-classification',
+        };
+        return new Promise((resolve, reject) => {
+            // Handle the single response message from the Worker.
+            worker.onmessage = (event) => {
+                const message = event.data;
+                if (message.type === 'result') {
+                    resolve(message.result);
+                }
+                else {
+                    reject(new Error(`Worker classification error: ${message.error}`));
+                }
+                // Terminate the Worker after receiving its response to free resources.
+                worker.terminate();
+            };
+            // Handle any uncaught errors thrown inside the Worker.
+            worker.onerror = (errorEvent) => {
+                reject(new Error(`Worker runtime error in "${this.wrapped.id}": ${errorEvent.message}`));
+                worker.terminate();
+            };
+            // Send the classify request to the Worker.
+            worker.postMessage(request);
+        });
+    }
+}
+//# sourceMappingURL=WorkerClassifierProxy.js.map

package/dist/classifiers/WorkerClassifierProxy.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Pack factory for the ML Classifier Guardrail Extension Pack.
+ *
+ * Exports the main `createMLClassifierPack()` factory that assembles the
+ * ML classifier guardrail and the `classify_content` tool into a single
+ * {@link ExtensionPack} ready for registration with the AgentOS extension
+ * manager.
+ *
+ * Also exports a `createExtensionPack()` bridge function that conforms to
+ * the AgentOS manifest factory convention, delegating to
+ * `createMLClassifierPack()` with options extracted from the
+ * {@link ExtensionPackContext}.
+ *
+ * ### Default behaviour (zero-config)
+ * When called without arguments, all three built-in classifiers (toxicity,
+ * prompt-injection, jailbreak) are active using their default model IDs and
+ * the default threshold set:
+ *  - block at 0.90 confidence
+ *  - flag at 0.70 confidence
+ *  - warn (sanitize) at 0.40 confidence
+ *
+ * ### Activation lifecycle
+ * Components are built eagerly at pack creation time for direct programmatic
+ * use.  When the extension manager activates the pack, `onActivate` rebuilds
+ * all components with the manager's shared service registry so heavyweight
+ * resources (ONNX/WASM model pipelines) are shared across the agent.
+ *
+ * ### Disabling classifiers
+ * Individual classifiers can be disabled by omitting them from the
+ * `options.classifiers` array.  An empty array or `undefined` activates all
+ * three built-in classifiers.
+ *
+ * @example
+ * ```typescript
+ * import { createMLClassifierPack } from './ml-classifiers';
+ *
+ * // All built-in classifiers at default thresholds:
+ * const pack = createMLClassifierPack();
+ *
+ * // Toxicity only with custom block threshold:
+ * const strictPack = createMLClassifierPack({
+ *   classifiers: ['toxicity'],
+ *   thresholds: { blockThreshold: 0.85 },
+ *   streamingMode: true,
+ *   guardrailScope: 'both',
+ * });
+ * ```
+ *
+ * @module agentos/extensions/packs/ml-classifiers
+ */
+import type { ExtensionPack, ExtensionPackContext } from '@framers/agentos';
+import type { MLClassifierPackOptions } from './types';
+/**
+ * Re-export all types from the ML classifier type definitions so consumers
+ * can import everything from a single entry point:
+ * ```ts
+ * import { createMLClassifierPack, DEFAULT_THRESHOLDS } from './ml-classifiers';
+ * ```
+ */
+export * from './types';
+/**
+ * Create an {@link ExtensionPack} that bundles:
+ *  - The {@link MLClassifierGuardrail} guardrail (evaluates input & output).
+ *  - The {@link ClassifyContentTool} `classify_content` tool (on-demand analysis).
+ *
+ * The built-in classifiers that are instantiated depend on `options.classifiers`:
+ *  - `'toxicity'`  → {@link ToxicityClassifier}   (`unitary/toxic-bert`)
+ *  - `'injection'` → {@link InjectionClassifier}  (`protectai/deberta-v3-small-prompt-injection-v2`)
+ *  - `'jailbreak'` → {@link JailbreakClassifier}  (`meta-llama/PromptGuard-86M`)
+ *
+ * When `options.classifiers` is `undefined` or empty, **all three** are active.
+ *
+ * Additional classifiers supplied via `options.customClassifiers` are appended
+ * to the active list and run in parallel alongside the built-in ones.
+ *
+ * @param options - Optional pack-level configuration.  All properties have
+ *                  sensible defaults; see {@link MLClassifierPackOptions}.
+ * @returns A fully-configured {@link ExtensionPack} with one guardrail
+ *          descriptor and one tool descriptor.
+ */
+export declare function createMLClassifierPack(options?: MLClassifierPackOptions): ExtensionPack;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Conforms to the convention expected by the extension loader when resolving
+ * packs from manifests.  Extracts `options` from the {@link ExtensionPackContext}
+ * and delegates to {@link createMLClassifierPack}.
+ *
+ * @param context - Manifest context containing optional pack options, secret
+ *                  resolver, and shared service registry.
+ * @returns A fully-configured {@link ExtensionPack}.
+ *
+ * @example Manifest entry:
+ * ```json
+ * {
+ *   "packs": [
+ *     {
+ *       "module": "./ml-classifiers",
+ *       "options": {
+ *         "classifiers": ["toxicity", "jailbreak"],
+ *         "thresholds": { "blockThreshold": 0.95 },
+ *         "streamingMode": true
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAevD;;;;;;GAMG;AACH,cAAc,SAAS,CAAC;AAMxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,aAAa,CAmPvF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAEhF"}