@framers/agentos-ext-ml-classifiers 0.1.0

package/dist/SlidingWindowBuffer.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Sliding-window text buffer for streaming ML classifier evaluation.
+ *
+ * When an LLM streams its response token-by-token, we cannot wait for the
+ * complete response before running safety classifiers — that would be too late
+ * to block or sanitise harmful content.  At the same time, classifiers are
+ * expensive: running one on every individual token is wasteful and introduces
+ * unacceptable latency.
+ *
+ * `SlidingWindowBuffer` solves this by accumulating tokens from one or more
+ * concurrent streams and emitting a {@link ChunkReady} event only when enough
+ * tokens have accumulated to fill a `chunkSize`-token window.  Each window
+ * also includes a `contextSize`-token "ring" from the previous chunk, so the
+ * classifier can reason about content that spans window boundaries.
+ *
+ * Architecture
+ * ------------
+ * - **Per-stream state**: Stored in a `Map<streamId, WindowState>`.  Each
+ *   stream is fully independent and can be used across multiple concurrent
+ *   responses.
+ * - **Token estimation**: Uses the 4-chars-per-token heuristic for speed;
+ *   callers that need exact counts should pre-tokenise text before pushing.
+ * - **Evaluation budget**: Once a stream reaches `maxEvaluations` chunks,
+ *   `push()` returns `null` for all subsequent pushes, preventing unbounded
+ *   classifier invocations on very long responses.
+ * - **Stale-stream pruning**: Streams that have not received data within
+ *   `streamTimeoutMs` milliseconds are lazily evicted from the map to prevent
+ *   memory leaks in long-running servers.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/SlidingWindowBuffer
+ */
+/**
+ * Configuration for a {@link SlidingWindowBuffer} instance.
+ *
+ * All fields are optional; unset fields fall back to the defaults shown below.
+ */
+export interface SlidingWindowConfig {
+    /**
+     * Target window size in *estimated* tokens.  When the accumulated buffer
+     * reaches or exceeds this many tokens, a {@link ChunkReady} is emitted and
+     * the buffer is slid forward.
+     *
+     * @default 200
+     */
+    chunkSize: number;
+    /**
+     * Number of tokens from the tail of the previous window to carry into the
+     * `text` field of the next {@link ChunkReady}.  This overlap prevents
+     * boundary effects where a phrase split across two windows is misclassified.
+     *
+     * @default 50
+     */
+    contextSize: number;
+    /**
+     * Maximum number of {@link ChunkReady} events to emit per stream.  After
+     * this budget is exhausted, `push()` returns `null` for the remainder of the
+     * stream.  Use `flush()` to retrieve any buffered text that has not been
+     * emitted yet.
+     *
+     * @default 100
+     */
+    maxEvaluations: number;
+    /**
+     * Milliseconds of inactivity after which a stream is considered stale and
+     * eligible for eviction by {@link SlidingWindowBuffer.pruneStale}.
+     *
+     * @default 30000
+     */
+    streamTimeoutMs: number;
+}
+/**
+ * Emitted by {@link SlidingWindowBuffer.push} when sufficient tokens have
+ * accumulated to fill one evaluation window.
+ */
+export interface ChunkReady {
+    /**
+     * The full text to classify.  Equals `contextRing + newBuffer`, where
+     * `contextRing` is the carried-forward tail from the previous window.
+     * Always non-empty.
+     */
+    text: string;
+    /**
+     * Only the *new* text pushed since the last chunk was emitted (i.e. without
+     * the context prefix).  Useful for determining which part of the response
+     * was newly evaluated.
+     */
+    newText: string;
+    /**
+     * 1-indexed sequence number for this chunk within the stream.
+     * The first chunk emitted for a stream has `evaluationNumber === 1`.
+     */
+    evaluationNumber: number;
+}
+/**
+ * A stateful, multi-stream text accumulator that emits fixed-size windows
+ * for ML classifier evaluation with configurable context carry-forward.
+ *
+ * @example
+ * ```typescript
+ * const buf = new SlidingWindowBuffer({ chunkSize: 200, contextSize: 50 });
+ *
+ * // Simulate streaming tokens
+ * for (const token of streamedTokens) {
+ *   const chunk = buf.push('stream-1', token);
+ *   if (chunk) {
+ *     const result = await toxicityClassifier.classify(chunk.text);
+ *     if (result.confidence > 0.9) terminateStream();
+ *   }
+ * }
+ *
+ * // Evaluate remaining tokens
+ * const finalChunk = buf.flush('stream-1');
+ * if (finalChunk) {
+ *   await toxicityClassifier.classify(finalChunk.text);
+ * }
+ * ```
+ */
+export declare class SlidingWindowBuffer {
+    /** Resolved configuration (defaults applied). */
+    private readonly config;
+    /**
+     * Per-stream state map.  Keyed by the `streamId` passed to `push()`.
+     * Entries are created lazily on first push and removed on flush or prune.
+     */
+    private readonly streams;
+    /**
+     * Construct a new buffer with the supplied configuration.
+     *
+     * @param config - Partial configuration; unset fields fall back to defaults:
+     *   `chunkSize=200`, `contextSize=50`, `maxEvaluations=100`,
+     *   `streamTimeoutMs=30000`.
+     */
+    constructor(config?: Partial<SlidingWindowConfig>);
+    /**
+     * Push new text into the buffer for the specified stream.
+     *
+     * Internally the text is appended to the stream's accumulation buffer.
+     * If the buffer's estimated token count reaches `chunkSize`, a
+     * {@link ChunkReady} is assembled and returned; the buffer is then reset
+     * (with the tail preserved as the context ring for the next window).
+     *
+     * Returns `null` when:
+     * - The buffer has not yet accumulated `chunkSize` tokens.
+     * - The stream has already emitted `maxEvaluations` chunks.
+     *
+     * When the map contains more than 10 streams, stale streams are pruned
+     * lazily after the push is processed.
+     *
+     * @param streamId - Opaque identifier for the stream (e.g. a request UUID).
+     * @param text     - The new text fragment to accumulate.
+     * @returns A {@link ChunkReady} when an evaluation window is complete, or
+     *   `null` if more data is needed (or the budget is exhausted).
+     */
+    push(streamId: string, text: string): ChunkReady | null;
+    /**
+     * Flush any remaining buffered text for the stream as a final chunk.
+     *
+     * Call this after the stream ends (e.g. when the LLM emits its final
+     * token) to ensure the classifier evaluates the tail of the response.
+     *
+     * The stream's state entry is removed from the map after flushing.
+     *
+     * @param streamId - Identifier of the stream to flush.
+     * @returns A {@link ChunkReady} for the remaining buffer, or `null` if the
+     *   buffer is empty or the stream does not exist.
+     */
+    flush(streamId: string): ChunkReady | null;
+    /**
+     * Remove streams that have not received data within `streamTimeoutMs`.
+     *
+     * Called lazily by `push()` when the stream map grows beyond 10 entries.
+     * May also be called proactively by a maintenance timer.
+     */
+    pruneStale(): void;
+    /**
+     * Remove all stream state from the buffer.
+     *
+     * Useful for graceful shutdown or unit-test teardown to ensure no cross-test
+     * state leaks.
+     */
+    clear(): void;
+    /**
+     * The number of streams currently tracked (including stale ones not yet
+     * pruned).
+     *
+     * Exposed primarily for testing and diagnostics.
+     */
+    get size(): number;
+    /**
+     * Assemble a {@link ChunkReady} from the current stream state.
+     *
+     * The `text` field is the concatenation of `contextRing` and the current
+     * `buffer`, giving the classifier cross-boundary context.  The `newText`
+     * field is just the raw `buffer` so callers can distinguish old from new.
+     *
+     * @param state - The mutable state for the stream being assembled.
+     * @returns A fully-populated {@link ChunkReady}.
+     */
+    private assembleChunk;
+    /**
+     * Estimate the number of LLM tokens in a string using the 4-chars-per-token
+     * heuristic.
+     *
+     * This deliberately mirrors {@link estimateTokens} from `core/utils/text-utils`
+     * without importing it, keeping this module self-contained and safe to load
+     * in Web Worker contexts where module resolution may differ.
+     *
+     * @param text - The string to estimate.
+     * @returns Non-negative integer token count estimate.
+     */
+    private estimateTokens;
+}
+//# sourceMappingURL=SlidingWindowBuffer.d.ts.map

package/dist/SlidingWindowBuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlidingWindowBuffer.d.ts","sourceRoot":"","sources":["../src/SlidingWindowBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAgDD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAmB;IAC9B,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAE7C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAE/D;;;;;;OAMG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC;IAajD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAwDvD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAe1C;;;;;OAKG;IACH,UAAU,IAAI,IAAI;IASlB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAMD;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAWrB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;CAIvB"}

package/dist/SlidingWindowBuffer.js

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview Sliding-window text buffer for streaming ML classifier evaluation.
+ *
+ * When an LLM streams its response token-by-token, we cannot wait for the
+ * complete response before running safety classifiers — that would be too late
+ * to block or sanitise harmful content.  At the same time, classifiers are
+ * expensive: running one on every individual token is wasteful and introduces
+ * unacceptable latency.
+ *
+ * `SlidingWindowBuffer` solves this by accumulating tokens from one or more
+ * concurrent streams and emitting a {@link ChunkReady} event only when enough
+ * tokens have accumulated to fill a `chunkSize`-token window.  Each window
+ * also includes a `contextSize`-token "ring" from the previous chunk, so the
+ * classifier can reason about content that spans window boundaries.
+ *
+ * Architecture
+ * ------------
+ * - **Per-stream state**: Stored in a `Map<streamId, WindowState>`.  Each
+ *   stream is fully independent and can be used across multiple concurrent
+ *   responses.
+ * - **Token estimation**: Uses the 4-chars-per-token heuristic for speed;
+ *   callers that need exact counts should pre-tokenise text before pushing.
+ * - **Evaluation budget**: Once a stream reaches `maxEvaluations` chunks,
+ *   `push()` returns `null` for all subsequent pushes, preventing unbounded
+ *   classifier invocations on very long responses.
+ * - **Stale-stream pruning**: Streams that have not received data within
+ *   `streamTimeoutMs` milliseconds are lazily evicted from the map to prevent
+ *   memory leaks in long-running servers.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/SlidingWindowBuffer
+ */
+// ---------------------------------------------------------------------------
+// SlidingWindowBuffer implementation
+// ---------------------------------------------------------------------------
+/**
+ * A stateful, multi-stream text accumulator that emits fixed-size windows
+ * for ML classifier evaluation with configurable context carry-forward.
+ *
+ * @example
+ * ```typescript
+ * const buf = new SlidingWindowBuffer({ chunkSize: 200, contextSize: 50 });
+ *
+ * // Simulate streaming tokens
+ * for (const token of streamedTokens) {
+ *   const chunk = buf.push('stream-1', token);
+ *   if (chunk) {
+ *     const result = await toxicityClassifier.classify(chunk.text);
+ *     if (result.confidence > 0.9) terminateStream();
+ *   }
+ * }
+ *
+ * // Evaluate remaining tokens
+ * const finalChunk = buf.flush('stream-1');
+ * if (finalChunk) {
+ *   await toxicityClassifier.classify(finalChunk.text);
+ * }
+ * ```
+ */
+export class SlidingWindowBuffer {
+    /** Resolved configuration (defaults applied). */
+    config;
+    /**
+     * Per-stream state map.  Keyed by the `streamId` passed to `push()`.
+     * Entries are created lazily on first push and removed on flush or prune.
+     */
+    streams = new Map();
+    /**
+     * Construct a new buffer with the supplied configuration.
+     *
+     * @param config - Partial configuration; unset fields fall back to defaults:
+     *   `chunkSize=200`, `contextSize=50`, `maxEvaluations=100`,
+     *   `streamTimeoutMs=30000`.
+     */
+    constructor(config) {
+        this.config = {
+            chunkSize: config?.chunkSize ?? 200,
+            contextSize: config?.contextSize ?? 50,
+            maxEvaluations: config?.maxEvaluations ?? 100,
+            streamTimeoutMs: config?.streamTimeoutMs ?? 30_000,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Push new text into the buffer for the specified stream.
+     *
+     * Internally the text is appended to the stream's accumulation buffer.
+     * If the buffer's estimated token count reaches `chunkSize`, a
+     * {@link ChunkReady} is assembled and returned; the buffer is then reset
+     * (with the tail preserved as the context ring for the next window).
+     *
+     * Returns `null` when:
+     * - The buffer has not yet accumulated `chunkSize` tokens.
+     * - The stream has already emitted `maxEvaluations` chunks.
+     *
+     * When the map contains more than 10 streams, stale streams are pruned
+     * lazily after the push is processed.
+     *
+     * @param streamId - Opaque identifier for the stream (e.g. a request UUID).
+     * @param text     - The new text fragment to accumulate.
+     * @returns A {@link ChunkReady} when an evaluation window is complete, or
+     *   `null` if more data is needed (or the budget is exhausted).
+     */
+    push(streamId, text) {
+        if (!text) {
+            return null;
+        }
+        // Initialise state for a new stream.
+        if (!this.streams.has(streamId)) {
+            this.streams.set(streamId, {
+                buffer: '',
+                tokenCount: 0,
+                contextRing: '',
+                evaluationCount: 0,
+                lastSeenAt: Date.now(),
+            });
+        }
+        const state = this.streams.get(streamId);
+        state.lastSeenAt = Date.now();
+        // Respect the evaluation budget — stop emitting chunks once exhausted.
+        if (state.evaluationCount >= this.config.maxEvaluations) {
+            return null;
+        }
+        // Accumulate incoming text.
+        state.buffer += text;
+        state.tokenCount = this.estimateTokens(state.buffer);
+        // Lazy pruning: clean up stale streams whenever the map grows large.
+        // Done unconditionally (not just on chunk emit) so stale entries are
+        // reclaimed even when streams are slow to accumulate a full window.
+        if (this.streams.size > 10) {
+            this.pruneStale();
+        }
+        // Not enough tokens yet — wait for more.
+        if (state.tokenCount < this.config.chunkSize) {
+            return null;
+        }
+        // We have a full window.  Assemble the chunk.
+        const chunk = this.assembleChunk(state);
+        // Slide the context ring forward: keep the last `contextSize` tokens'
+        // worth of characters from the buffer that was just emitted.
+        const contextCharBudget = this.config.contextSize * 4;
+        state.contextRing = state.buffer.slice(-contextCharBudget);
+        // Reset the buffer and token count for the next window.
+        state.buffer = '';
+        state.tokenCount = 0;
+        state.evaluationCount += 1;
+        return chunk;
+    }
+    /**
+     * Flush any remaining buffered text for the stream as a final chunk.
+     *
+     * Call this after the stream ends (e.g. when the LLM emits its final
+     * token) to ensure the classifier evaluates the tail of the response.
+     *
+     * The stream's state entry is removed from the map after flushing.
+     *
+     * @param streamId - Identifier of the stream to flush.
+     * @returns A {@link ChunkReady} for the remaining buffer, or `null` if the
+     *   buffer is empty or the stream does not exist.
+     */
+    flush(streamId) {
+        const state = this.streams.get(streamId);
+        // Nothing to flush if the stream is unknown or the buffer is empty.
+        if (!state || state.buffer.length === 0) {
+            // Always clean up the map entry, even for empty buffers.
+            this.streams.delete(streamId);
+            return null;
+        }
+        const chunk = this.assembleChunk(state);
+        this.streams.delete(streamId);
+        return chunk;
+    }
+    /**
+     * Remove streams that have not received data within `streamTimeoutMs`.
+     *
+     * Called lazily by `push()` when the stream map grows beyond 10 entries.
+     * May also be called proactively by a maintenance timer.
+     */
+    pruneStale() {
+        const now = Date.now();
+        for (const [id, state] of this.streams) {
+            if (now - state.lastSeenAt > this.config.streamTimeoutMs) {
+                this.streams.delete(id);
+            }
+        }
+    }
+    /**
+     * Remove all stream state from the buffer.
+     *
+     * Useful for graceful shutdown or unit-test teardown to ensure no cross-test
+     * state leaks.
+     */
+    clear() {
+        this.streams.clear();
+    }
+    /**
+     * The number of streams currently tracked (including stale ones not yet
+     * pruned).
+     *
+     * Exposed primarily for testing and diagnostics.
+     */
+    get size() {
+        return this.streams.size;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Assemble a {@link ChunkReady} from the current stream state.
+     *
+     * The `text` field is the concatenation of `contextRing` and the current
+     * `buffer`, giving the classifier cross-boundary context.  The `newText`
+     * field is just the raw `buffer` so callers can distinguish old from new.
+     *
+     * @param state - The mutable state for the stream being assembled.
+     * @returns A fully-populated {@link ChunkReady}.
+     */
+    assembleChunk(state) {
+        const newText = state.buffer;
+        const text = state.contextRing + newText;
+        return {
+            text,
+            newText,
+            // evaluationCount is 0-indexed before increment, so +1 gives 1-indexed number.
+            evaluationNumber: state.evaluationCount + 1,
+        };
+    }
+    /**
+     * Estimate the number of LLM tokens in a string using the 4-chars-per-token
+     * heuristic.
+     *
+     * This deliberately mirrors {@link estimateTokens} from `core/utils/text-utils`
+     * without importing it, keeping this module self-contained and safe to load
+     * in Web Worker contexts where module resolution may differ.
+     *
+     * @param text - The string to estimate.
+     * @returns Non-negative integer token count estimate.
+     */
+    estimateTokens(text) {
+        if (!text)
+            return 0;
+        return Math.ceil(text.length / 4);
+    }
+}
+//# sourceMappingURL=SlidingWindowBuffer.js.map

package/dist/SlidingWindowBuffer.js.map

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

package/dist/classifiers/InjectionClassifier.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Prompt-injection content classifier using the
+ * `protectai/deberta-v3-small-prompt-injection-v2` model.
+ *
+ * Prompt injection is the attack pattern where adversarial instructions are
+ * embedded inside user-supplied text to override or hijack the agent's system
+ * prompt.  This classifier provides a dedicated binary signal (INJECTION /
+ * SAFE) that the guardrail orchestrator can act on independently of the
+ * toxicity or jailbreak classifiers.
+ *
+ * Model details
+ * -------------
+ * `protectai/deberta-v3-small-prompt-injection-v2` is a fine-tuned DeBERTa
+ * model from ProtectAI, specifically trained to distinguish benign user
+ * messages from prompt-injection payloads.  It outputs two labels:
+ *  - `INJECTION` — high-confidence injection attempt
+ *  - `SAFE`      — normal user input
+ *
+ * Graceful degradation
+ * --------------------
+ * If the model fails to load the classifier sets `unavailable = true` and
+ * returns a pass result `{ bestClass: 'benign', confidence: 0, allScores: [] }`
+ * on every subsequent call.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/classifiers/InjectionClassifier
+ */
+import type { ClassificationResult } from '@framers/agentos';
+import type { ISharedServiceRegistry } from '@framers/agentos';
+import type { IContentClassifier } from '../IContentClassifier';
+import type { ClassifierConfig } from '../types';
+/**
+ * Binary prompt-injection classifier backed by
+ * `protectai/deberta-v3-small-prompt-injection-v2`.
+ *
+ * Returns one of two labels:
+ *  - `INJECTION` — the text contains an injection attempt
+ *  - `SAFE`      — the text is clean
+ *
+ * The label with the higher confidence becomes `bestClass` / `confidence`.
+ * Both labels are present in `allScores` so callers can read the SAFE score
+ * as well.
+ *
+ * @implements {IContentClassifier}
+ *
+ * @example
+ * ```typescript
+ * const classifier = new InjectionClassifier(serviceRegistry);
+ * const result = await classifier.classify('Ignore previous instructions and …');
+ * // result.bestClass === 'INJECTION', result.confidence ≈ 0.97
+ * ```
+ */
+export declare class InjectionClassifier implements IContentClassifier {
+    private readonly services;
+    private readonly config?;
+    /** Unique service identifier for this classifier. */
+    readonly id = "prompt-injection";
+    /** Human-readable name for dashboards and log output. */
+    readonly displayName = "Prompt Injection Classifier";
+    /** Short description of what this classifier detects. */
+    readonly description: string;
+    /**
+     * Default Hugging Face model ID.
+     * Overridable via {@link ClassifierConfig.modelId}.
+     */
+    readonly modelId = "protectai/deberta-v3-small-prompt-injection-v2";
+    /**
+     * Whether the model weights are fully loaded and the classifier is ready
+     * to accept `classify()` calls.
+     */
+    private _isLoaded;
+    /**
+     * Set to `true` when the model fails to load.  Once `unavailable`, every
+     * subsequent `classify()` call immediately returns the pass result rather
+     * than retrying the expensive model load.
+     */
+    private unavailable;
+    /**
+     * @param services - Shared service registry used to lazily create and cache
+     *   the underlying HuggingFace pipeline instance.
+     * @param config - Optional per-classifier configuration.  When
+     *   `config.modelId` is provided it overrides the default `modelId` when
+     *   loading the model.
+     */
+    constructor(services: ISharedServiceRegistry, config?: ClassifierConfig | undefined);
+    /**
+     * Whether the underlying model pipeline has been successfully initialised.
+     * The flag is set to `true` after the first successful `classify()` call.
+     */
+    get isLoaded(): boolean;
+    /**
+     * Run prompt-injection inference on `text`.
+     *
+     * Lazily loads the pipeline on the first call via the shared service
+     * registry, then calls it with `{ topk: null }` to retrieve scores for both
+     * labels.
+     *
+     * @param text - The text to evaluate.
+     * @returns A promise that resolves with the classification result.  If the
+     *   model is unavailable the pass result is returned instead of throwing.
+     */
+    classify(text: string): Promise<ClassificationResult>;
+    /**
+     * Release the pipeline instance from the shared service registry.
+     *
+     * Idempotent — safe to call multiple times.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Returns a "pass" result used when the model is unavailable.
+     *
+     * A pass result reports `bestClass: 'benign'` with zero confidence so the
+     * guardrail orchestrator will always choose {@link GuardrailAction.ALLOW}.
+     */
+    private passResult;
+    /**
+     * Map the raw pipeline output to a {@link ClassificationResult}.
+     *
+     * For binary classification the label with the higher confidence score
+     * becomes `bestClass` / `confidence`.  Both labels are included in
+     * `allScores`.
+     *
+     * @param raw - Array returned by the pipeline when called with `topk: null`.
+     */
+    private mapResult;
+}
+//# sourceMappingURL=InjectionClassifier.d.ts.map

package/dist/classifiers/InjectionClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InjectionClassifier.d.ts","sourceRoot":"","sources":["../../src/classifiers/InjectionClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAsBjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAmD1D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IA/C1B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,sBAAsB;IAEjC,yDAAyD;IACzD,QAAQ,CAAC,WAAW,iCAAiC;IAErD,yDAAyD;IACzD,QAAQ,CAAC,WAAW,SAEsD;IAE1E;;;OAGG;IACH,QAAQ,CAAC,OAAO,oDAAoD;IAMpE;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAAS;IAM5B;;;;;;OAMG;gBAEgB,QAAQ,EAAE,sBAAsB,EAChC,MAAM,CAAC,EAAE,gBAAgB,YAAA;IAO5C;;;OAGG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAMD;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkD3D;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAIlB;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;CAsBlB"}