@framers/agentos-ext-ml-classifiers 0.1.0 → 0.3.1

package/src/classifiers/WorkerClassifierProxy.ts

@@ -1,366 +0,0 @@
-/**
- * @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
- */
-
-import type { ClassificationResult } from '@framers/agentos';
-import type { IContentClassifier } from '../IContentClassifier';
-import type { BrowserConfig } from '../types';
-
-// ---------------------------------------------------------------------------
-// Internal message shapes
-// ---------------------------------------------------------------------------
-
-/**
- * Message sent from the main thread to the Worker to request classification.
- *
- * @internal
- */
-interface WorkerClassifyRequest {
-  /** Discriminant tag that identifies this message type. */
-  type: 'classify';
-
-  /** The text to classify.  Passed directly to the pipeline. */
-  text: string;
-
-  /** Hugging Face model ID (or local path) to load if not yet cached. */
-  modelId: string;
-
-  /**
-   * Whether to request a quantized model variant.
-   * Passed through to the `@huggingface/transformers` pipeline factory.
-   */
-  quantized: boolean;
-
-  /**
-   * HuggingFace pipeline task string, e.g. `'text-classification'`.
-   * Sent so the Worker can use the correct pipeline type when loading the
-   * model for the first time.
-   */
-  taskType: string;
-}
-
-/**
- * Success response posted back from the Worker.
- *
- * @internal
- */
-interface WorkerResultMessage {
-  /** Discriminant tag. */
-  type: 'result';
-
-  /** The resolved classification result. */
-  result: ClassificationResult;
-}
-
-/**
- * Error response posted back from the Worker.
- *
- * @internal
- */
-interface WorkerErrorMessage {
-  /** Discriminant tag. */
-  type: 'error';
-
-  /** Human-readable error message. */
-  error: string;
-}
-
-/** Union of all possible messages coming back from the Worker. */
-type WorkerResponse = WorkerResultMessage | WorkerErrorMessage;
-
-// ---------------------------------------------------------------------------
-// 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 implements IContentClassifier {
-  // -------------------------------------------------------------------------
-  // 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(): string {
-    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(): string {
-    return this.wrapped.displayName;
-  }
-
-  /**
-   * {@inheritDoc IContentClassifier.description}
-   * Delegated directly from the wrapped classifier.
-   */
-  get description(): string {
-    return this.wrapped.description;
-  }
-
-  /**
-   * {@inheritDoc IContentClassifier.modelId}
-   * Delegated directly from the wrapped classifier.
-   */
-  get modelId(): string {
-    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(): boolean {
-    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: boolean) {
-    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.
-   */
-  private 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(
-    private readonly wrapped: IContentClassifier,
-    private readonly 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: string): Promise<ClassificationResult> {
-    // 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(): Promise<void> {
-    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.
-   */
-  private shouldUseWebWorker(): boolean {
-    // 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}.
-   */
-  private async classifyInWorker(text: string): Promise<ClassificationResult> {
-    let worker: 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: WorkerClassifyRequest = {
-      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<ClassificationResult>((resolve, reject) => {
-      // Handle the single response message from the Worker.
-      worker.onmessage = (event: MessageEvent<WorkerResponse>) => {
-        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: 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);
-    });
-  }
-}

package/src/worker/classifier-worker.ts

@@ -1,267 +0,0 @@
-/**
- * @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
- */
-
-import type { ClassificationResult, ClassificationScore } from '@framers/agentos';
-
-// ---------------------------------------------------------------------------
-// Internal message shapes (mirrored from WorkerClassifierProxy for clarity)
-// ---------------------------------------------------------------------------
-
-/**
- * A classification request message received from the main thread.
- *
- * @internal
- */
-interface ClassifyRequest {
-  /** Must be `'classify'` — other message types are silently ignored. */
-  type: 'classify';
-
-  /** The text to pass to the pipeline. */
-  text: string;
-
-  /** Hugging Face model ID (e.g. `'Xenova/toxic-bert'`) or local path. */
-  modelId: string;
-
-  /**
-   * Whether to request a quantized (8-bit) model variant.
-   * Passed to the pipeline constructor's `{ quantized }` option.
-   */
-  quantized: boolean;
-
-  /**
-   * The `@huggingface/transformers` task identifier.
-   * Most classifiers use `'text-classification'`.
-   */
-  taskType: string;
-}
-
-/**
- * A single label/score pair as returned by the transformers.js
- * text-classification pipeline when called with `{ topk: null }`.
- *
- * @internal
- */
-interface RawLabel {
-  /** Classification label name, e.g. `'toxic'`. */
-  label: string;
-
-  /** Confidence score in the range [0, 1]. */
-  score: number;
-}
-
-/**
- * Success response posted to the main thread.
- *
- * @internal
- */
-interface ResultMessage {
-  type: 'result';
-  result: ClassificationResult;
-}
-
-/**
- * Error response posted to the main thread.
- *
- * @internal
- */
-interface ErrorMessage {
-  type: 'error';
-  error: string;
-}
-
-// ---------------------------------------------------------------------------
-// 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: string, taskType: string): string {
-  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<string, (text: string, opts: { topk: null }) => Promise<RawLabel[]>>();
-
-// ---------------------------------------------------------------------------
-// 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: ClassifyRequest): Promise<RawLabel[]> {
-  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 as (text: string, opts: { topk: null }) => Promise<RawLabel[]>;
-    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: RawLabel[]): ClassificationResult {
-  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: ClassificationScore[] = 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: ClassifyRequest): Promise<void> {
-  try {
-    const raw = await runPipeline(request);
-    const result = normaliseResult(raw);
-
-    const response: ResultMessage = { type: 'result', result };
-    self.postMessage(response);
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err);
-    const response: ErrorMessage = { 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: MessageEvent) => {
-  const data = event.data as ClassifyRequest;
-
-  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,
-    );
-  }
-};