@framers/agentos-ext-topicality 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @framers/agentos-ext-topicality
+
+## 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/TopicalityGuardrail.d.ts

@@ -1,196 +1,111 @@
 /**
- * @fileoverview IGuardrailService implementation for topicality enforcement.
+ * @file TopicalityGuardrail.ts
+ * @description Guardrail service that enforces on/off-topic boundaries for
+ * agent conversations using a three-tier evaluation strategy:
  *
- * `TopicalityGuardrail` evaluates user input (and optionally agent output)
- * against configured allowed and forbidden topic sets using semantic
- * embedding similarity.  It enforces three independent policy checks:
+ * 1. **Embedding similarity** (primary) — cosine similarity between input
+ *    and topic embeddings via `@huggingface/transformers`.
+ * 2. **LLM-as-judge** (fallback) — structured JSON classification prompt
+ *    sent to the configured LLM invoker.
+ * 3. **Keyword matching** (last resort) — simple substring search against
+ *    topic strings when neither embeddings nor LLM are available.
  *
- *  1. **Forbidden topics** — Messages that score above `forbiddenThreshold`
- *     against any forbidden topic are blocked (or flagged).
- *  2. **Off-topic detection** — Messages that score below `allowedThreshold`
- *     against *all* allowed topics are flagged (or blocked/redirected).
- *  3. **Session drift** — An EMA-based tracker flags sustained drift away
- *     from allowed topics across consecutive messages.
+ * The guardrail only evaluates input (user messages).  Output evaluation
+ * returns `null` (pass-through) because topic drift in agent responses is
+ * best handled at the input gate.
  *
- * ### Lazy initialisation
- * Embedding indices are built on the **first evaluation call**, not at
- * construction time.  This keeps instantiation cheap and defers the
- * potentially expensive batch embedding call until the agent actually
- * receives its first message.
+ * ### Guardrail pipeline phase
  *
- * ### Fail-open semantics
- * All evaluation methods wrap their logic in try/catch.  If the embedding
- * function throws, or any other unexpected error occurs, the guardrail
- * logs a warning and returns `null` (pass) to avoid blocking legitimate
- * traffic due to infrastructure failures.
+ * This guardrail sets `canSanitize: false` and `evaluateStreamingChunks: false`,
+ * placing it in Phase 2 (parallel) of the guardrail dispatcher.  It never
+ * modifies content — it only FLAGs or BLOCKs.
  *
- * @module topicality/TopicalityGuardrail
+ * @module agentos/extensions/packs/topicality/TopicalityGuardrail
  */
-import type { GuardrailConfig, GuardrailEvaluationResult, GuardrailInputPayload, GuardrailOutputPayload, IGuardrailService } from '@framers/agentos';
-import type { ISharedServiceRegistry } from '@framers/agentos';
-import type { TopicalityPackOptions } from './types';
+import type { IGuardrailService, GuardrailConfig, GuardrailInputPayload, GuardrailOutputPayload, GuardrailEvaluationResult } from '@framers/agentos';
+import type { TopicalityOptions } from './types';
 /**
- * Guardrail that enforces topicality constraints via semantic embeddings.
+ * Guardrail that enforces topic boundaries on user input.
  *
- * Implements {@link IGuardrailService} with Phase 2 (parallel) semantics:
- * `evaluateStreamingChunks: false` and `canSanitize: false`.  The guardrail
- * never modifies content — it only blocks or flags.
- *
- * @example
- * ```ts
- * const guardrail = new TopicalityGuardrail(registry, {
- *   allowedTopics: TOPIC_PRESETS.customerSupport,
- *   forbiddenTopics: TOPIC_PRESETS.commonUnsafe,
- *   forbiddenAction: 'block',
- *   offTopicAction: 'flag',
- * }, embeddingFn);
- *
- * const result = await guardrail.evaluateInput(payload);
- * if (result?.action === GuardrailAction.BLOCK) {
- *   // Reject the message
- * }
- * ```
+ * Implements {@link IGuardrailService} with input-only evaluation.
+ * Runs in Phase 2 (parallel, non-sanitizing) of the guardrail dispatcher.
  */
 export declare class TopicalityGuardrail implements IGuardrailService {
     /**
-     * Guardrail pipeline configuration.
-     *
-     * - `evaluateStreamingChunks: false` — topicality evaluation requires
-     *   complete text, not partial deltas.
-     * - `canSanitize: false` — this guardrail only blocks or flags; it never
-     *   modifies content, so it runs in Phase 2 (parallel) of the pipeline.
+     * Guardrail configuration — Phase 2 parallel (no sanitization, no streaming).
      */
     readonly config: GuardrailConfig;
-    /** Shared service registry provided by the extension manager. */
-    private readonly services;
-    /** Resolved pack options with caller overrides. */
-    private readonly options;
-    /** Caller-supplied or registry-backed embedding function. */
-    private readonly embeddingFn;
-    /**
-     * Embedding index for allowed topics.  Lazily built on the first
-     * evaluation call.  `null` until built or if no allowed topics are
-     * configured.
-     */
-    private allowedIndex;
-    /**
-     * Embedding index for forbidden topics.  Lazily built on the first
-     * evaluation call.  `null` until built or if no forbidden topics are
-     * configured.
-     */
-    private forbiddenIndex;
-    /**
-     * Session-level EMA drift tracker.  Only instantiated when
-     * `enableDriftDetection` is `true` (default).  `null` otherwise.
-     */
-    private driftTracker;
-    /**
-     * Which side of the conversation to evaluate.
-     * - `'input'`  — only user messages
-     * - `'output'` — only agent responses
-     * - `'both'`   — both directions
-     */
-    private readonly scope;
+    /** Resolved options with defaults applied. */
+    private readonly opts;
     /**
-     * Minimum similarity to any allowed topic for the message to be
-     * considered on-topic.
+     * @param options - Topicality configuration provided by the pack factory.
      */
-    private readonly allowedThreshold;
+    constructor(options: TopicalityOptions);
     /**
-     * Similarity above which a forbidden topic match triggers action.
-     */
-    private readonly forbiddenThreshold;
-    /**
-     * Whether the lazy initialisation of embedding indices has been
-     * performed.  Prevents redundant build calls.
-     */
-    private indicesBuilt;
-    /**
-     * Creates a new `TopicalityGuardrail`.
+     * Evaluate user input for topic relevance.
+     *
+     * Runs the three-tier evaluation strategy:
+     * 1. Embedding similarity (if `@huggingface/transformers` available)
+     * 2. LLM-as-judge (if `llmInvoker` configured)
+     * 3. Keyword matching (always available)
      *
-     * @param services    - Shared service registry for heavyweight resource sharing.
-     * @param options     - Pack-level configuration (topics, thresholds, actions).
-     * @param embeddingFn - Optional explicit embedding function.  When omitted,
-     *   the guardrail falls back to requesting an EmbeddingManager from the
-     *   shared service registry at evaluation time.
+     * @param payload - The input payload containing user text and context.
+     * @returns A guardrail result (FLAG/BLOCK) or `null` to allow.
      */
-    constructor(services: ISharedServiceRegistry, options: TopicalityPackOptions, embeddingFn?: (texts: string[]) => Promise<number[][]>);
+    evaluateInput(payload: GuardrailInputPayload): Promise<GuardrailEvaluationResult | null>;
     /**
-     * Clears any session-level drift-tracking state held by this guardrail.
+     * Output evaluation — returns `null` (pass-through).
      *
-     * Called by the topicality pack's `onDeactivate` hook so long-lived agents
-     * do not retain per-session EMA state after the pack is removed or the
-     * agent shuts down.
+     * Topic enforcement is applied at the input gate only.  Agent responses
+     * are not evaluated for topicality.
      */
-    clearSessionState(): void;
+    evaluateOutput(_payload: GuardrailOutputPayload): Promise<GuardrailEvaluationResult | null>;
     /**
-     * Evaluates a user input message against configured topic constraints.
+     * Evaluate input via cosine similarity between embeddings.
      *
-     * When `scope` is `'output'`, this method immediately returns `null`
-     * because input evaluation is disabled.
+     * Embeds the input text and each topic string, then compares similarities
+     * against the configured thresholds.
      *
-     * @param payload - The input payload containing the user message text and
-     *   session context.
-     * @returns A guardrail evaluation result (BLOCK or FLAG), or `null` if
-     *   the message passes all topic checks.  Returns `null` on any error
-     *   (fail-open).
+     * @param text - The user input text.
+     * @returns A {@link TopicMatchResult} or `null` if embeddings are unavailable.
      */
-    evaluateInput(payload: GuardrailInputPayload): Promise<GuardrailEvaluationResult | null>;
+    private evaluateViaEmbeddings;
     /**
-     * Evaluates an agent output chunk against configured topic constraints.
-     *
-     * When `scope` is `'input'`, this method immediately returns `null`
-     * because output evaluation is disabled.
+     * Evaluate input via LLM classification prompt.
      *
-     * For output evaluation, the guardrail extracts text from the response
-     * chunk's `finalResponseText` field (since `evaluateStreamingChunks` is
-     * `false`, only FINAL_RESPONSE chunks are seen).
+     * Sends a structured prompt to the configured LLM invoker asking it to
+     * classify the input as on-topic or off-topic and return JSON.
      *
-     * @param payload - The output payload containing the response chunk and
-     *   session context.
-     * @returns A guardrail evaluation result (BLOCK or FLAG), or `null` if
-     *   the output passes all topic checks.  Returns `null` on any error
-     *   (fail-open).
+     * @param text - The user input text.
+     * @returns A {@link TopicMatchResult} or `null` if no LLM invoker is configured.
      */
-    evaluateOutput(payload: GuardrailOutputPayload): Promise<GuardrailEvaluationResult | null>;
+    private evaluateViaLlm;
     /**
-     * Runs the three-stage topicality evaluation pipeline on a pre-computed
-     * embedding vector.
-     *
-     * Evaluation order:
-     *  1. Forbidden topic check (highest priority — immediate block/flag)
-     *  2. Off-topic check against allowed topics
-     *  3. Session drift check (only if drift detection is enabled and allowed
-     *     topics are configured)
+     * Evaluate input via simple case-insensitive substring matching against
+     * topic strings.
      *
-     * @param embedding - Pre-computed embedding vector for the text.
-     * @param sessionId - Session identifier for drift tracking.
-     * @returns A {@link GuardrailEvaluationResult} if any check triggers, or
-     *   `null` if all checks pass.
+     * This is the fallback of last resort when neither embeddings nor LLM
+     * are available.  It checks whether any topic string appears as a
+     * substring of the input (or vice versa).
      *
-     * @internal
+     * @param text - The user input text.
+     * @returns A {@link TopicMatchResult}.
      */
-    private evaluateEmbedding;
+    private evaluateViaKeywords;
     /**
-     * Ensures that the allowed and forbidden embedding indices have been built.
+     * Convert a {@link TopicMatchResult} into a {@link GuardrailEvaluationResult}.
      *
-     * Called once before the first evaluation.  Subsequent calls are no-ops
-     * (guarded by the `indicesBuilt` flag).
+     * - On-topic results return `null` (allow).
+     * - Blocked-topic matches return `BLOCK`.
+     * - Off-topic (below allowed threshold) returns `FLAG`.
      *
-     * @internal
+     * @param result - The topic match result to convert.
+     * @returns A guardrail evaluation result, or `null` to allow.
      */
-    private ensureIndicesBuilt;
+    private toGuardrailResult;
     /**
-     * Creates an embedding function that retrieves an EmbeddingManager from
-     * the shared service registry at call time.
-     *
-     * This fallback is used when no explicit `embeddingFn` is provided to
-     * the constructor.  It throws if the EmbeddingManager service is not
-     * available in the registry.
-     *
-     * @returns An async embedding function.
-     * @internal
+     * Clear cached embeddings.  Called during pack deactivation.
      */
-    private createRegistryEmbeddingFn;
+    clearCache(): void;
 }
 //# sourceMappingURL=TopicalityGuardrail.d.ts.map

package/dist/TopicalityGuardrail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TopicalityGuardrail.d.ts","sourceRoot":"","sources":["../src/TopicalityGuardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AA+BrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,mBAAoB,YAAW,iBAAiB;IAK3D;;;;;;;OAOG;IACH,SAAgB,MAAM,EAAE,eAAe,CAGrC;IAMF,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAElD,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAEhD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2C;IAEvE;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAAoC;IAExD;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAoC;IAE1D;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAkC;IAEtD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IAEpD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAE5C;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAS;IAM7B;;;;;;;;OAQG;gBAED,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,qBAAqB,EAC9B,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAsBxD;;;;;;OAMG;IACH,iBAAiB,IAAI,IAAI;IAQzB;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAoC5C;;;;;;;;;;;;;;;OAeG;IACG,cAAc,CAClB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAyC5C;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,iBAAiB;IAkHzB;;;;;;;OAOG;YACW,kBAAkB;IAwBhC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,yBAAyB;CAiBlC"}
+{"version":3,"file":"TopicalityGuardrail.d.ts","sourceRoot":"","sources":["../src/TopicalityGuardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,iBAAiB,EAAoB,MAAM,SAAS,CAAC;AA+DnE;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,iBAAiB;IAC3D;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAG9B;IAEF,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAMmB;IAExC;;OAEG;gBACS,OAAO,EAAE,iBAAiB;IActC;;;;;;;;;;OAUG;IACG,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAwB9F;;;;;OAKG;IACG,cAAc,CAClB,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAQ5C;;;;;;;;OAQG;YACW,qBAAqB;IA+CnC;;;;;;;;OAQG;YACW,cAAc;IA0C5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IA+B3B;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}