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

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @framers/agentos-ext-ml-classifiers
+
+## 0.2.1
+
+### Patch Changes
+
+- [`15065c9`](https://github.com/framersai/agentos-extensions/commit/15065c949ea5d25f4408ffab2079ad3e600ddded) Thanks [@jddunn](https://github.com/jddunn)! - Fix npm publish: add missing repository.url field for sigstore provenance verification
+
+## 0.2.0
+
+### Minor Changes
+
+- [`c35afe8`](https://github.com/framersai/agentos-extensions/commit/c35afe8c16fdf51df6ce2d0bb83de6cd702e3a8b) Thanks [@jddunn](https://github.com/jddunn)! - Implement all 5 guardrail extension packs with full detection logic:
+  - PII Redaction: 4-tier detection (regex + keyword + NER + LLM)
+  - Code Safety: OWASP regex patterns for SQL injection, XSS, command injection
+  - ML Classifiers: toxicity/injection/NSFW via ONNX or LLM fallback
+  - Topicality: embedding-based topic enforcement with LLM fallback
+  - Grounding Guard: NLI-based hallucination detection against RAG sources

package/dist/MLClassifierGuardrail.d.ts

@@ -1,163 +1,134 @@
 /**
- * @fileoverview IGuardrailService implementation backed by ML classifiers.
+ * @file MLClassifierGuardrail.ts
+ * @description IGuardrailService implementation that classifies text for toxicity,
+ * prompt injection, NSFW content, and threats using a three-tier strategy:
  *
- * `MLClassifierGuardrail` bridges the AgentOS guardrail pipeline to the ML
- * classifier subsystem.  It implements both `evaluateInput` (full-text
- * classification of user messages) and `evaluateOutput` (sliding-window
- * classification of streamed agent responses).
+ * 1. **ONNX inference** — attempts to load `@huggingface/transformers` at runtime
+ *    and run a lightweight ONNX classification model.
+ * 2. **LLM-as-judge** — falls back to an LLM invoker callback that prompts a
+ *    language model for structured JSON safety classification.
+ * 3. **Keyword matching** — last-resort regex/keyword-based detection when neither
+ *    ONNX nor LLM are available.
  *
- * Three streaming evaluation modes are supported:
+ * The guardrail is configured as Phase 2 (parallel, non-sanitizing) so it runs
+ * alongside other read-only guardrails without blocking the streaming pipeline.
  *
- * | Mode          | Behaviour                                                      |
- * |---------------|----------------------------------------------------------------|
- * | `blocking`    | Every chunk that fills the sliding window is classified         |
- * |               | **synchronously** — the stream waits for the result.           |
- * | `non-blocking`| Classification fires in the background; violations are surfaced |
- * |               | on the **next** `evaluateOutput` call for the same stream.     |
- * | `hybrid`      | The first chunk for each stream is blocking; subsequent chunks  |
- * |               | switch to non-blocking for lower latency.                      |
+ * ### Action thresholds
  *
- * The default mode is `blocking` when `streamingMode` is enabled.
+ * - **FLAG** when any category confidence exceeds `flagThreshold` (default 0.5).
+ * - **BLOCK** when any category confidence exceeds `blockThreshold` (default 0.8).
  *
- * @module agentos/extensions/packs/ml-classifiers/MLClassifierGuardrail
+ * @module ml-classifiers/MLClassifierGuardrail
  */
-import type { GuardrailConfig, GuardrailEvaluationResult, GuardrailInputPayload, GuardrailOutputPayload, IGuardrailService } from '@framers/agentos';
-import type { ISharedServiceRegistry } from '@framers/agentos';
-import type { MLClassifierPackOptions } from './types';
-import type { IContentClassifier } from './IContentClassifier';
+import type { IGuardrailService, GuardrailConfig, GuardrailInputPayload, GuardrailOutputPayload, GuardrailEvaluationResult } from '@framers/agentos';
+import type { MLClassifierOptions, ClassifierResult } from './types';
 /**
- * Guardrail implementation that runs ML classifiers against both user input
- * and streamed agent output.
+ * AgentOS guardrail that classifies text for safety using ML models, LLM
+ * inference, or keyword fallback.
  *
  * @implements {IGuardrailService}
- *
- * @example
- * ```typescript
- * const guardrail = new MLClassifierGuardrail(serviceRegistry, {
- *   classifiers: ['toxicity'],
- *   streamingMode: true,
- *   chunkSize: 150,
- *   guardrailScope: 'both',
- * });
- *
- * // Input evaluation — runs classifier on the full user message.
- * const inputResult = await guardrail.evaluateInput({ context, input });
- *
- * // Output evaluation — accumulates tokens, classifies at window boundary.
- * const outputResult = await guardrail.evaluateOutput({ context, chunk });
- * ```
  */
 export declare class MLClassifierGuardrail implements IGuardrailService {
     /**
-     * Guardrail configuration exposed to the AgentOS pipeline.
+     * Guardrail configuration.
      *
-     * `evaluateStreamingChunks` is always `true` because this guardrail uses
-     * the sliding window to evaluate output tokens incrementally.
+     * - `canSanitize: false` — this guardrail does not modify content; it only
+     *   BLOCKs or FLAGs.  This places it in Phase 2 (parallel) of the guardrail
+     *   dispatcher for better performance.
+     * - `evaluateStreamingChunks: false` — only evaluates complete messages, not
+     *   individual streaming deltas.  ML classification on partial text produces
+     *   unreliable results.
      */
     readonly config: GuardrailConfig;
-    /** The classifier orchestrator that runs all classifiers in parallel. */
-    private readonly orchestrator;
-    /** Sliding window buffer for accumulating streaming tokens. */
-    private readonly buffer;
-    /** Guardrail scope — which direction(s) this guardrail evaluates. */
-    private readonly scope;
-    /** Streaming evaluation strategy for output chunks. */
-    private readonly streamingMode;
+    /** Categories to evaluate. */
+    private readonly categories;
+    /** Per-category flag thresholds. */
+    private readonly flagThresholds;
+    /** Per-category block thresholds. */
+    private readonly blockThresholds;
+    /** Optional LLM invoker callback for tier-2 classification. */
+    private readonly llmInvoker;
     /**
-     * Map of stream IDs to pending (background) classification promises.
-     * Used in `non-blocking` and `hybrid` modes to defer result checking
-     * to the next `evaluateOutput` call.
+     * Cached reference to the `@huggingface/transformers` pipeline function.
+     * `null` means we already tried and failed to load the module.
+     * `undefined` means we have not tried yet.
      */
-    private readonly pendingResults;
+    private onnxPipeline;
     /**
-     * Tracks whether the first chunk for a given stream has been processed.
-     * Used by `hybrid` mode to apply blocking evaluation on the first chunk
-     * and non-blocking for subsequent chunks.
+     * Create a new MLClassifierGuardrail.
+     *
+     * @param options - Pack-level configuration.  All properties have sensible
+     *                  defaults for zero-config operation.
      */
-    private readonly isFirstChunk;
+    constructor(options?: MLClassifierOptions);
     /**
-     * Create a new ML classifier guardrail.
+     * Evaluate user input for safety before orchestration begins.
      *
-     * @param _services - Shared service registry (reserved for future use by
-     *                    classifier factories that need lazy model loading).
-     * @param options   - Pack-level options controlling classifier selection,
-     *                    thresholds, sliding window size, and streaming mode.
-     * @param classifiers - Pre-built classifier instances.  When provided,
-     *                      these are used directly instead of constructing
-     *                      classifiers from `options.classifiers`.
+     * @param payload - Input evaluation payload containing the user's message.
+     * @returns Guardrail result or `null` if no action is required.
      */
-    constructor(_services: ISharedServiceRegistry, options: MLClassifierPackOptions, classifiers?: IContentClassifier[]);
+    evaluateInput(payload: GuardrailInputPayload): Promise<GuardrailEvaluationResult | null>;
     /**
-     * Evaluate a user's input message before it enters the orchestration pipeline.
-     *
-     * Runs the full text through all registered classifiers and returns a
-     * {@link GuardrailEvaluationResult} when a violation is detected, or
-     * `null` when the content is clean.
+     * Evaluate agent output for safety.  Only processes FINAL_RESPONSE chunks
+     * since `evaluateStreamingChunks` is disabled.
      *
-     * Skipped entirely when `scope === 'output'`.
+     * @param payload - Output evaluation payload from the AgentOS dispatcher.
+     * @returns Guardrail result or `null` if no action is required.
+     */
+    evaluateOutput(payload: GuardrailOutputPayload): Promise<GuardrailEvaluationResult | null>;
+    /**
+     * Classify a text string using the three-tier strategy: ONNX -> LLM -> keyword.
      *
-     * @param payload - The input payload containing user text and context.
-     * @returns Evaluation result or `null` if no action is needed.
+     * @param text - The text to classify.
+     * @returns Classification result with per-category scores.
      */
-    evaluateInput(payload: GuardrailInputPayload): Promise<GuardrailEvaluationResult | null>;
+    classify(text: string): Promise<ClassifierResult>;
     /**
-     * Evaluate a streamed output chunk from the agent before it is delivered
-     * to the client.
+     * Attempt to load `@huggingface/transformers` and run ONNX-based text
+     * classification.  Returns `null` if the module is unavailable or inference
+     * fails.
      *
-     * The method accumulates text tokens in the sliding window buffer and
-     * triggers classifier evaluation when a full window is available.  The
-     * evaluation strategy depends on the configured streaming mode.
+     * The module load is attempted only once; subsequent calls use the cached
+     * result (either a working pipeline or `null`).
      *
-     * Skipped entirely when `scope === 'input'`.
+     * @param text - Text to classify.
+     * @returns Classification result or `null`.
      *
-     * @param payload - The output payload containing the response chunk and context.
-     * @returns Evaluation result or `null` if no action is needed yet.
+     * @internal
      */
-    evaluateOutput(payload: GuardrailOutputPayload): Promise<GuardrailEvaluationResult | null>;
+    private tryOnnxClassification;
     /**
-     * **Blocking mode**: push text into the buffer and, when a full window is
-     * ready, await the classifier result before returning.
+     * Map raw ONNX text-classification output labels to our standard categories.
      *
-     * @param streamId  - Identifier of the active stream.
-     * @param textDelta - New text fragment from the current chunk.
-     * @returns Evaluation result (possibly BLOCK/FLAG) or `null`.
-     */
-    private handleBlocking;
-    /**
-     * **Non-blocking mode**: push text into the buffer.  When a window is
-     * ready, fire classification in the background and store the promise.
-     * On the **next** `evaluateOutput` call for the same stream, check the
-     * pending promise — if it resolved with a violation, return that result.
+     * ONNX models (e.g. toxic-bert) produce labels like `"toxic"`, `"obscene"`,
+     * `"threat"`, `"insult"`, `"identity_hate"`, etc.  We map these to our four
+     * categories, taking the max score when multiple ONNX labels map to the same
+     * category.
+     *
+     * @param raw - Raw ONNX pipeline output.
+     * @returns Per-category scores.
      *
-     * @param streamId  - Identifier of the active stream.
-     * @param textDelta - New text fragment from the current chunk.
-     * @returns A previously resolved violation result, or `null`.
+     * @internal
      */
-    private handleNonBlocking;
+    private mapOnnxScores;
     /**
-     * **Hybrid mode**: the first chunk for each stream is evaluated in
-     * blocking mode; subsequent chunks use non-blocking.
+     * Classify text using the LLM-as-judge fallback.
      *
-     * This provides immediate feedback on the first window (where early
-     * jailbreak attempts are most likely) while minimising latency for the
-     * remainder of the stream.
+     * @param text - Text to classify.
+     * @returns Classification result or `null` if the LLM call fails.
      *
-     * @param streamId  - Identifier of the active stream.
-     * @param textDelta - New text fragment from the current chunk.
-     * @returns Evaluation result or `null`.
+     * @internal
      */
-    private handleHybrid;
+    private tryLlmClassification;
     /**
-     * Convert a {@link ChunkEvaluation} into a {@link GuardrailEvaluationResult}
-     * suitable for the AgentOS guardrail pipeline.
+     * Convert a {@link ClassifierResult} into a {@link GuardrailEvaluationResult},
+     * or return `null` when no thresholds are exceeded.
      *
-     * Returns `null` when the recommended action is ALLOW (no intervention
-     * needed).  For all other actions, the evaluation details are attached as
-     * metadata for audit/logging.
+     * @param result - Classification result from any tier.
+     * @returns Guardrail evaluation result or `null`.
      *
-     * @param evaluation - Aggregated classifier evaluation.
-     * @returns A guardrail result or `null` for clean content.
+     * @internal
      */
-    private evaluationToResult;
+    private buildResult;
 }
 //# sourceMappingURL=MLClassifierGuardrail.d.ts.map

package/dist/MLClassifierGuardrail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MLClassifierGuardrail.d.ts","sourceRoot":"","sources":["../src/MLClassifierGuardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAmB,MAAM,SAAS,CAAC;AAIxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAmB/D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IAK7D;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAMjC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IAEtD,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAE7C,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IAEpD,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAE9C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoD;IAEnF;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmC;IAMhE;;;;;;;;;;OAUG;gBAED,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,uBAAuB,EAChC,WAAW,GAAE,kBAAkB,EAAO;IAsCxC;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAuB9F;;;;;;;;;;;;OAYG;IACG,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IA0DhG;;;;;;;OAOG;YACW,cAAc;IAc5B;;;;;;;;;OASG;YACW,iBAAiB;IAoC/B;;;;;;;;;;;OAWG;YACW,YAAY;IAqB1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;CAsB3B"}
+{"version":3,"file":"MLClassifierGuardrail.d.ts","sourceRoot":"","sources":["../src/MLClassifierGuardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EACV,mBAAmB,EAEnB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AASjB;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IAK7D;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAG9B;IAMF,8BAA8B;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAElD,oCAAoC;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqC;IAEpE,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IAErE,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAE/D;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAAqC;IAMzD;;;;;OAKG;gBACS,OAAO,CAAC,EAAE,mBAAmB;IAuBzC;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAY9F;;;;;;OAMG;IACG,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAmBhG;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwBvD;;;;;;;;;;;;OAYG;YACW,qBAAqB;IAqCnC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,aAAa;IAsCrB;;;;;;;OAOG;YACW,oBAAoB;IAuBlC;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;CAsCpB"}