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

package/src/index.ts

@@ -1,81 +1,24 @@
 /**
- * @fileoverview Pack factory for the ML Classifier Guardrail Extension Pack.
+ * @file index.ts
+ * @description Pack factory for the ML Classifiers 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.
+ * Exports a `createExtensionPack()` 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
+ * @module ml-classifiers
  */
 
-import type { ISharedServiceRegistry } from '@framers/agentos';
-import { SharedServiceRegistry } from '@framers/agentos';
 import type { ExtensionPack, ExtensionPackContext } from '@framers/agentos';
-import type { ExtensionDescriptor, ExtensionLifecycleContext } from '@framers/agentos';
 import { EXTENSION_KIND_GUARDRAIL, EXTENSION_KIND_TOOL } from '@framers/agentos';
-import type { MLClassifierPackOptions } from './types';
-import { DEFAULT_THRESHOLDS } from './types';
+import type { MLClassifierOptions } from './types';
 import { MLClassifierGuardrail } from './MLClassifierGuardrail';
-import { ClassifierOrchestrator } from './ClassifierOrchestrator';
-import { SlidingWindowBuffer } from './SlidingWindowBuffer';
 import { ClassifyContentTool } from './tools/ClassifyContentTool';
-import { ToxicityClassifier } from './classifiers/ToxicityClassifier';
-import { InjectionClassifier } from './classifiers/InjectionClassifier';
-import { JailbreakClassifier } from './classifiers/JailbreakClassifier';
-import type { IContentClassifier } from './IContentClassifier';
 
 // ---------------------------------------------------------------------------
-// Re-exports — allow single-import for consumers
+// Re-exports
 // ---------------------------------------------------------------------------
 
-/**
- * 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';
 
 // ---------------------------------------------------------------------------
@@ -83,267 +26,34 @@ 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.
+ * Create an ExtensionPack that bundles the ML classifier guardrail with
+ * the `classify_content` tool.
  *
  * @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.
+ *                  sensible defaults; see {@link MLClassifierOptions}.
+ * @returns A fully-configured {@link ExtensionPack}.
  */
-export function createMLClassifierPack(options?: MLClassifierPackOptions): ExtensionPack {
-  /**
-   * Resolved options — default to empty object so every sub-check can
-   * safely use `opts.foo` without null-guarding the whole `options` reference.
-   */
-  const opts: MLClassifierPackOptions = options ?? {};
-
-  // -------------------------------------------------------------------------
-  // Mutable state — upgraded by onActivate with the extension manager's
-  // shared service registry.
-  // -------------------------------------------------------------------------
-
-  const state = {
-    /**
-     * Service registry — starts as a standalone instance so the pack can be
-     * used directly (without activation) in unit tests and scripts.
-     * Replaced with the shared registry when `onActivate` is called by the
-     * extension manager.
-     */
-    services: new SharedServiceRegistry() as ISharedServiceRegistry,
-  };
-
-  // -------------------------------------------------------------------------
-  // Component instances — rebuilt by buildComponents()
-  // -------------------------------------------------------------------------
-
-  /**
-   * The guardrail that evaluates user input and/or agent output streams
-   * against all active ML classifiers.
-   */
-  let guardrail: MLClassifierGuardrail;
-
-  /**
-   * The on-demand classification tool exposed to agents and workflows.
-   */
-  let tool: ClassifyContentTool;
-
-  /**
-   * The orchestrator that runs all active classifiers in parallel and folds
-   * their results into a single {@link ChunkEvaluation} via worst-wins
-   * aggregation.
-   */
-  let orchestrator: ClassifierOrchestrator;
-
-  /**
-   * The sliding-window buffer used internally by the guardrail to evaluate
-   * streamed output tokens incrementally.
-   */
-  let buffer: SlidingWindowBuffer;
-
-  // -------------------------------------------------------------------------
-  // buildComponents
-  // -------------------------------------------------------------------------
-
-  /**
-   * (Re)construct all pack components using the current `state.services`.
-   *
-   * Called once at pack creation for direct programmatic use, and again
-   * during `onActivate` to upgrade to the extension manager's shared
-   * service registry (so ONNX/WASM pipelines are shared across the agent).
-   *
-   * ### Classifier selection
-   * The active classifiers are determined by `opts.classifiers`:
-   *  - `undefined` or empty → all three built-in classifiers are created.
-   *  - Non-empty array      → only the named classifiers are created.
-   *
-   * Any `opts.customClassifiers` are always appended to the list.
-   */
-  function buildComponents(): void {
-    // ------------------------------------------------------------------
-    // 1. Determine which built-in classifiers to instantiate.
-    // ------------------------------------------------------------------
-
-    /**
-     * Determine whether a given built-in classifier name is enabled.
-     *
-     * When `opts.classifiers` is undefined or an empty array every built-in
-     * classifier is considered enabled (zero-config default).
-     *
-     * @param name - One of `'toxicity'`, `'injection'`, or `'jailbreak'`.
-     * @returns `true` when the classifier should be included.
-     */
-    function isBuiltInEnabled(name: 'toxicity' | 'injection' | 'jailbreak'): boolean {
-      // No explicit list — enable all built-in classifiers.
-      if (!opts.classifiers || opts.classifiers.length === 0) {
-        return true;
-      }
-      return opts.classifiers.includes(name);
-    }
-
-    /** Array that will be populated with every active IContentClassifier. */
-    const activeClassifiers: IContentClassifier[] = [];
-
-    // Toxicity classifier — detects hateful, abusive, and toxic language.
-    if (isBuiltInEnabled('toxicity')) {
-      activeClassifiers.push(new ToxicityClassifier(state.services));
-    }
-
-    // Injection classifier — detects prompt-injection payloads.
-    if (isBuiltInEnabled('injection')) {
-      activeClassifiers.push(new InjectionClassifier(state.services));
-    }
-
-    // Jailbreak classifier — detects system-prompt override attempts.
-    if (isBuiltInEnabled('jailbreak')) {
-      activeClassifiers.push(new JailbreakClassifier(state.services));
-    }
-
-    // Append any caller-supplied custom classifiers.
-    if (opts.customClassifiers && opts.customClassifiers.length > 0) {
-      activeClassifiers.push(...opts.customClassifiers);
-    }
-
-    // ------------------------------------------------------------------
-    // 2. Resolve pack-level thresholds (merge caller overrides on top of
-    //    the library defaults).
-    // ------------------------------------------------------------------
-
-    const thresholds = {
-      ...DEFAULT_THRESHOLDS,
-      ...opts.thresholds,
-    };
-
-    // ------------------------------------------------------------------
-    // 3. Build the orchestrator with the resolved classifier list and
-    //    thresholds.
-    // ------------------------------------------------------------------
-    orchestrator = new ClassifierOrchestrator(activeClassifiers, thresholds);
-
-    // ------------------------------------------------------------------
-    // 4. Build the sliding-window buffer for streaming evaluation.
-    // ------------------------------------------------------------------
-    buffer = new SlidingWindowBuffer({
-      chunkSize: opts.chunkSize,
-      contextSize: opts.contextSize,
-      maxEvaluations: opts.maxEvaluations,
-    });
-
-    // ------------------------------------------------------------------
-    // 5. Build the guardrail, passing the shared registry and options.
-    //    The guardrail creates its own orchestrator internally from the
-    //    `classifiers` option — we pass the pre-built classifier instances
-    //    via the third constructor argument.
-    // ------------------------------------------------------------------
-    guardrail = new MLClassifierGuardrail(state.services, opts, activeClassifiers);
-
-    // ------------------------------------------------------------------
-    // 6. Build the on-demand classification tool backed by the orchestrator.
-    // ------------------------------------------------------------------
-    tool = new ClassifyContentTool(orchestrator);
-  }
-
-  // Initial build — makes the pack usable immediately without activation.
-  buildComponents();
-
-  // -------------------------------------------------------------------------
-  // ExtensionPack shape
-  // -------------------------------------------------------------------------
+export function createMLClassifierGuardrail(options?: MLClassifierOptions): ExtensionPack {
+  const guardrail = new MLClassifierGuardrail(options);
+  const tool = new ClassifyContentTool(guardrail);
 
   return {
-    /** Canonical pack name used in manifests and logs. */
     name: 'ml-classifiers',
-
-    /** Semantic version of this pack implementation. */
     version: '1.0.0',
-
-    /**
-     * Descriptor getter — always returns the latest (possibly rebuilt)
-     * component instances.  Using a getter ensures that after `onActivate`
-     * rebuilds the components, the descriptors array reflects the new
-     * references rather than stale closures from the initial build.
-     */
-    get descriptors(): ExtensionDescriptor[] {
-      return [
-        {
-          /**
-           * Guardrail descriptor.
-           *
-           * Priority 5 places this guardrail after the PII redaction guardrail
-           * (priority 10) so PII is stripped before ML classification.
-           */
-          id: 'ml-classifier-guardrail',
-          kind: EXTENSION_KIND_GUARDRAIL,
-          priority: 5,
-          payload: guardrail,
-        },
-        {
-          /**
-           * On-demand classification tool descriptor.
-           *
-           * Priority 0 uses the default ordering — tools are typically
-           * ordered by name rather than priority.
-           */
-          id: 'classify_content',
-          kind: EXTENSION_KIND_TOOL,
-          priority: 0,
-          payload: tool,
-        },
-      ];
-    },
-
-    /**
-     * Lifecycle hook called by the extension manager when the pack is
-     * activated.
-     *
-     * Upgrades the internal service registry to the extension manager's
-     * shared instance (so ONNX/WASM model weights are shared across all
-     * extensions) then rebuilds all components to use the new registry.
-     *
-     * @param context - Activation context provided by the extension manager.
-     */
-    onActivate: (context: ExtensionLifecycleContext): void => {
-      // Upgrade to the shared registry when the manager provides one.
-      if (context.services) {
-        state.services = context.services;
-      }
-
-      // Rebuild all components with the upgraded registry.
-      buildComponents();
-    },
-
-    /**
-     * Lifecycle hook called when the pack is deactivated or the agent shuts
-     * down.
-     *
-     * Disposes the classifier orchestrator (which releases ONNX/WASM
-     * resources for every registered classifier) and clears the sliding
-     * window buffer to release per-stream state.
-     */
-    onDeactivate: async (): Promise<void> => {
-      // Dispose all classifiers managed by the orchestrator.
-      // orchestrator may be undefined if buildComponents() was never called
-      // successfully (defensive guard).
-      if (orchestrator) {
-        await orchestrator.dispose();
-      }
-
-      // Clear any in-progress stream buffers.
-      if (buffer) {
-        buffer.clear();
-      }
-    },
+    descriptors: [
+      {
+        id: 'ml-classifier-guardrail',
+        kind: EXTENSION_KIND_GUARDRAIL,
+        priority: 5,
+        payload: guardrail,
+      },
+      {
+        id: 'classify_content',
+        kind: EXTENSION_KIND_TOOL,
+        priority: 0,
+        payload: tool,
+      },
+    ],
   };
 }
 
@@ -356,28 +66,14 @@ export function createMLClassifierPack(options?: MLClassifierPackOptions): Exten
  *
  * 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}.
+ * and delegates to {@link createMLClassifierGuardrail}.
  *
- * @param context - Manifest context containing optional pack options, secret
- *                  resolver, and shared service registry.
+ * @param context - Manifest context containing optional pack options.
  * @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 function createExtensionPack(context: ExtensionPackContext): ExtensionPack {
-  return createMLClassifierPack(context.options as MLClassifierPackOptions);
+  return createMLClassifierGuardrail(context.options as MLClassifierOptions);
 }
+
+/** @deprecated Use createMLClassifierGuardrail instead */
+export const createMLClassifierPack = createMLClassifierGuardrail;

package/src/keyword-classifier.ts

@@ -0,0 +1,130 @@
+/**
+ * @file keyword-classifier.ts
+ * @description Lightweight keyword and regex-based safety classifier used as the
+ * last-resort fallback when neither ONNX models nor an LLM invoker are available.
+ *
+ * Returns normalised confidence scores per category based on keyword density and
+ * pattern matches.  This is intentionally conservative — it will produce false
+ * positives in edge cases, but ensures the guardrail is never completely blind.
+ *
+ * @module ml-classifiers/keyword-classifier
+ */
+
+import type { ClassifierCategory, CategoryScore } from './types';
+import { ALL_CATEGORIES } from './types';
+
+// ---------------------------------------------------------------------------
+// Pattern dictionaries
+// ---------------------------------------------------------------------------
+
+/**
+ * Toxic language patterns — slurs, hate speech, and abusive terms.
+ *
+ * Each regex uses word boundaries (`\b`) to reduce false positives from
+ * substrings appearing in innocent words.
+ */
+const TOXIC_PATTERNS: RegExp[] = [
+  /\b(fuck|shit|ass(?:hole)?|bitch|bastard|damn|crap)\b/i,
+  /\b(kill\s+(?:yourself|urself|you)|kys)\b/i,
+  /\b(retard(?:ed)?|idiot|moron|stupid\s+(?:bitch|ass))\b/i,
+  /\b(hate\s+(?:you|u)|die\s+(?:in|alone))\b/i,
+  /\b(racial|ethnic)\s+slur/i,
+  /\b(n[i1]gg|f[a4]g(?:got)?|tr[a4]nn)/i,
+];
+
+/**
+ * Prompt injection / jailbreak patterns — attempts to override system
+ * instructions, extract system prompts, or bypass safety guardrails.
+ */
+const INJECTION_PATTERNS: RegExp[] = [
+  /\bignore\s+(?:all\s+)?(?:previous|above|prior)\s+instructions?\b/i,
+  /\byou\s+are\s+now\s+(?:DAN|evil|unrestricted|jailbroken)\b/i,
+  /\bsystem\s*prompt\s*[:=]/i,
+  /\bdo\s+anything\s+now\b/i,
+  /\bdisregard\s+(?:your|all)\s+(?:rules|guidelines|instructions)\b/i,
+  /\bpretend\s+(?:you(?:'re|\s+are)\s+)?(?:not\s+an?\s+AI|unrestricted|evil)\b/i,
+  /\bact\s+as\s+(?:if|though)\s+(?:you\s+have\s+)?no\s+(?:restrictions|rules|limits)\b/i,
+  /\boverride\s+(?:safety|content)\s+(?:filters?|policies|guidelines)\b/i,
+  /\bjailbreak/i,
+  /\bprompt\s+(?:leak|injection|extract)/i,
+];
+
+/**
+ * NSFW patterns — sexually explicit content markers.
+ */
+const NSFW_PATTERNS: RegExp[] = [
+  /\b(porn(?:ography)?|hentai|xxx|nsfw)\b/i,
+  /\b(nude|naked|topless)\s+(?:photo|pic|image|video)\b/i,
+  /\bsexual(?:ly)?\s+explicit\b/i,
+  /\b(erotic|orgasm|masturbat)/i,
+  /\bsext(?:ing)?\b/i,
+];
+
+/**
+ * Threat patterns — direct threats of violence, self-harm instructions,
+ * or dangerous activity incitement.
+ */
+const THREAT_PATTERNS: RegExp[] = [
+  /\b(?:i(?:'ll|\s+will)\s+)?kill\s+(?:you|him|her|them)\b/i,
+  /\b(?:how\s+to\s+)?make\s+a?\s*(?:bomb|explosive|weapon)\b/i,
+  /\b(?:i(?:'ll|\s+will)\s+)?hurt\s+(?:you|myself|someone)\b/i,
+  /\bsuicid(?:e|al)\s+(?:method|instruction|guide|how)/i,
+  /\b(?:swat(?:ting)?|dox(?:x?ing)?)\s+(?:someone|him|her|you)\b/i,
+  /\bshoot\s+up\s+(?:a\s+)?(?:school|church|mosque|synagogue|building)\b/i,
+];
+
+/**
+ * Map category names to their pattern arrays for uniform iteration.
+ */
+const CATEGORY_PATTERNS: Record<ClassifierCategory, RegExp[]> = {
+  toxic: TOXIC_PATTERNS,
+  injection: INJECTION_PATTERNS,
+  nsfw: NSFW_PATTERNS,
+  threat: THREAT_PATTERNS,
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a text string using keyword and regex pattern matching.
+ *
+ * Confidence is computed as `min(1.0, matchCount * weight)` where `weight`
+ * scales the number of distinct pattern matches into the [0, 1] range.
+ * A single match yields a base confidence of 0.4; each additional match
+ * adds 0.15 up to a cap of 1.0.
+ *
+ * @param text       - The text to classify.
+ * @param categories - Which categories to evaluate.  Defaults to all four.
+ * @returns Per-category confidence scores.
+ */
+export function classifyByKeywords(
+  text: string,
+  categories: ClassifierCategory[] = ALL_CATEGORIES
+): CategoryScore[] {
+  const scores: CategoryScore[] = [];
+
+  for (const cat of categories) {
+    const patterns = CATEGORY_PATTERNS[cat];
+    if (!patterns) {
+      scores.push({ name: cat, confidence: 0 });
+      continue;
+    }
+
+    // Count how many distinct patterns match.
+    let matchCount = 0;
+    for (const re of patterns) {
+      if (re.test(text)) {
+        matchCount++;
+      }
+    }
+
+    // Scale: first match = 0.4, each additional += 0.15, capped at 1.0.
+    const confidence = matchCount === 0 ? 0 : Math.min(1.0, 0.4 + (matchCount - 1) * 0.15);
+
+    scores.push({ name: cat, confidence });
+  }
+
+  return scores;
+}