@framers/agentos-ext-topicality 0.1.0

package/dist/TopicalityGuardrail.js

@@ -0,0 +1,426 @@
+/**
+ * @fileoverview IGuardrailService implementation for topicality enforcement.
+ *
+ * `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. **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.
+ *
+ * ### 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.
+ *
+ * ### 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.
+ *
+ * @module topicality/TopicalityGuardrail
+ */
+import { GuardrailAction } from '@framers/agentos';
+import { DEFAULT_DRIFT_CONFIG } from './types';
+import { TopicEmbeddingIndex } from './TopicEmbeddingIndex';
+import { TopicDriftTracker } from './TopicDriftTracker';
+// ---------------------------------------------------------------------------
+// Reason codes emitted by this guardrail
+// ---------------------------------------------------------------------------
+/**
+ * Machine-readable reason code for messages matching a forbidden topic.
+ * @internal
+ */
+const REASON_FORBIDDEN = 'TOPICALITY_FORBIDDEN';
+/**
+ * Machine-readable reason code for messages that do not match any allowed topic.
+ * @internal
+ */
+const REASON_OFF_TOPIC = 'TOPICALITY_OFF_TOPIC';
+/**
+ * Machine-readable reason code for sustained session-level topic drift.
+ * @internal
+ */
+const REASON_DRIFT = 'TOPICALITY_DRIFT';
+// ---------------------------------------------------------------------------
+// TopicalityGuardrail
+// ---------------------------------------------------------------------------
+/**
+ * Guardrail that enforces topicality constraints via semantic embeddings.
+ *
+ * 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
+ * }
+ * ```
+ */
+export class TopicalityGuardrail {
+    // -------------------------------------------------------------------------
+    // IGuardrailService config
+    // -------------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    config = {
+        evaluateStreamingChunks: false,
+        canSanitize: false,
+    };
+    // -------------------------------------------------------------------------
+    // Private state
+    // -------------------------------------------------------------------------
+    /** Shared service registry provided by the extension manager. */
+    services;
+    /** Resolved pack options with caller overrides. */
+    options;
+    /** Caller-supplied or registry-backed embedding function. */
+    embeddingFn;
+    /**
+     * Embedding index for allowed topics.  Lazily built on the first
+     * evaluation call.  `null` until built or if no allowed topics are
+     * configured.
+     */
+    allowedIndex = null;
+    /**
+     * Embedding index for forbidden topics.  Lazily built on the first
+     * evaluation call.  `null` until built or if no forbidden topics are
+     * configured.
+     */
+    forbiddenIndex = null;
+    /**
+     * Session-level EMA drift tracker.  Only instantiated when
+     * `enableDriftDetection` is `true` (default).  `null` otherwise.
+     */
+    driftTracker = null;
+    /**
+     * Which side of the conversation to evaluate.
+     * - `'input'`  — only user messages
+     * - `'output'` — only agent responses
+     * - `'both'`   — both directions
+     */
+    scope;
+    /**
+     * Minimum similarity to any allowed topic for the message to be
+     * considered on-topic.
+     */
+    allowedThreshold;
+    /**
+     * Similarity above which a forbidden topic match triggers action.
+     */
+    forbiddenThreshold;
+    /**
+     * Whether the lazy initialisation of embedding indices has been
+     * performed.  Prevents redundant build calls.
+     */
+    indicesBuilt = false;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * Creates a new `TopicalityGuardrail`.
+     *
+     * @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.
+     */
+    constructor(services, options, embeddingFn) {
+        this.services = services;
+        this.options = options;
+        // Resolve embedding function: prefer explicit argument, then fall back
+        // to the shared service registry.
+        this.embeddingFn = embeddingFn ?? this.createRegistryEmbeddingFn();
+        // Resolve scope and thresholds from options with sensible defaults.
+        this.scope = options.guardrailScope ?? 'input';
+        this.allowedThreshold = options.allowedThreshold ?? 0.35;
+        this.forbiddenThreshold = options.forbiddenThreshold ?? 0.65;
+        // Instantiate drift tracker if enabled (default: true).
+        const driftEnabled = options.enableDriftDetection !== false;
+        if (driftEnabled) {
+            const driftConfig = { ...DEFAULT_DRIFT_CONFIG, ...(options.drift ?? {}) };
+            this.driftTracker = new TopicDriftTracker(driftConfig);
+        }
+    }
+    /**
+     * Clears any session-level drift-tracking state held by this guardrail.
+     *
+     * 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.
+     */
+    clearSessionState() {
+        this.driftTracker?.clear();
+    }
+    // -------------------------------------------------------------------------
+    // IGuardrailService — evaluateInput
+    // -------------------------------------------------------------------------
+    /**
+     * Evaluates a user input message against configured topic constraints.
+     *
+     * When `scope` is `'output'`, this method immediately returns `null`
+     * because input evaluation is disabled.
+     *
+     * @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).
+     */
+    async evaluateInput(payload) {
+        // If scope is output-only, skip input evaluation entirely.
+        if (this.scope === 'output') {
+            return null;
+        }
+        try {
+            // Extract the text content from the input payload.
+            const text = payload.input.textInput;
+            if (!text || text.trim().length === 0) {
+                // No text to evaluate — pass through.
+                return null;
+            }
+            // Lazy-build embedding indices on the first call.
+            await this.ensureIndicesBuilt();
+            // Embed the user's text once — reuse the vector for all checks.
+            const [embedding] = await this.embeddingFn([text]);
+            // Run the core evaluation pipeline on the embedded vector.
+            return this.evaluateEmbedding(embedding, payload.context.sessionId);
+        }
+        catch (error) {
+            // Fail-open: log the error but let the message through.
+            console.warn('[TopicalityGuardrail] evaluateInput failed (fail-open):', error instanceof Error ? error.message : error);
+            return null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // IGuardrailService — evaluateOutput
+    // -------------------------------------------------------------------------
+    /**
+     * Evaluates an agent output chunk against configured topic constraints.
+     *
+     * When `scope` is `'input'`, this method immediately returns `null`
+     * because output evaluation is disabled.
+     *
+     * For output evaluation, the guardrail extracts text from the response
+     * chunk's `finalResponseText` field (since `evaluateStreamingChunks` is
+     * `false`, only FINAL_RESPONSE chunks are seen).
+     *
+     * @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).
+     */
+    async evaluateOutput(payload) {
+        // If scope is input-only, skip output evaluation entirely.
+        if (this.scope === 'input') {
+            return null;
+        }
+        try {
+            // Extract text from the chunk.  Since evaluateStreamingChunks is false,
+            // we receive FINAL_RESPONSE chunks with finalResponseText.
+            const chunk = payload.chunk;
+            const text = chunk.textDelta ??
+                chunk.finalResponseText ??
+                '';
+            if (!text || text.trim().length === 0) {
+                return null;
+            }
+            // Lazy-build embedding indices on the first call.
+            await this.ensureIndicesBuilt();
+            // Embed the output text once.
+            const [embedding] = await this.embeddingFn([text]);
+            // Run the core evaluation pipeline.
+            return this.evaluateEmbedding(embedding, payload.context.sessionId);
+        }
+        catch (error) {
+            // Fail-open: log and pass through.
+            console.warn('[TopicalityGuardrail] evaluateOutput failed (fail-open):', error instanceof Error ? error.message : error);
+            return null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Core evaluation pipeline
+    // -------------------------------------------------------------------------
+    /**
+     * 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)
+     *
+     * @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.
+     *
+     * @internal
+     */
+    evaluateEmbedding(embedding, sessionId) {
+        // ------------------------------------------------------------------
+        // Step 1: Check forbidden topics
+        // ------------------------------------------------------------------
+        if (this.forbiddenIndex) {
+            const forbiddenMatches = this.forbiddenIndex.matchByVector(embedding);
+            // Check if any forbidden topic exceeds the threshold.
+            for (const match of forbiddenMatches) {
+                if (match.similarity > this.forbiddenThreshold) {
+                    // Determine action: 'block' (default) or 'flag'.
+                    const action = this.options.forbiddenAction === 'flag'
+                        ? GuardrailAction.FLAG
+                        : GuardrailAction.BLOCK;
+                    return {
+                        action,
+                        reason: `Message matches forbidden topic: ${match.topicName}`,
+                        reasonCode: REASON_FORBIDDEN,
+                        metadata: {
+                            matchedTopic: match.topicId,
+                            matchedTopicName: match.topicName,
+                            similarity: match.similarity,
+                        },
+                    };
+                }
+            }
+        }
+        // ------------------------------------------------------------------
+        // Step 2: Check allowed topics (off-topic detection)
+        // ------------------------------------------------------------------
+        if (this.allowedIndex) {
+            const isOnTopic = this.allowedIndex.isOnTopicByVector(embedding, this.allowedThreshold);
+            if (!isOnTopic) {
+                // Get the nearest topic for metadata, even though it's below threshold.
+                const allMatches = this.allowedIndex.matchByVector(embedding);
+                const nearestTopic = allMatches.length > 0 ? allMatches[0] : null;
+                // Determine action based on offTopicAction option.
+                let action;
+                switch (this.options.offTopicAction) {
+                    case 'block':
+                        action = GuardrailAction.BLOCK;
+                        break;
+                    case 'redirect':
+                        // Redirect maps to FLAG with metadata indicating redirection intent.
+                        action = GuardrailAction.FLAG;
+                        break;
+                    default:
+                        // Default: 'flag'
+                        action = GuardrailAction.FLAG;
+                        break;
+                }
+                return {
+                    action,
+                    reason: nearestTopic
+                        ? `Message is off-topic. Nearest topic: ${nearestTopic.topicName} (similarity: ${nearestTopic.similarity.toFixed(3)})`
+                        : 'Message is off-topic. No matching topics found.',
+                    reasonCode: REASON_OFF_TOPIC,
+                    metadata: {
+                        nearestTopic: nearestTopic?.topicId ?? null,
+                        nearestTopicName: nearestTopic?.topicName ?? null,
+                        nearestSimilarity: nearestTopic?.similarity ?? 0,
+                    },
+                };
+            }
+        }
+        // ------------------------------------------------------------------
+        // Step 3: Check session drift (only when drift detection is enabled
+        //         and we have allowed topics to compare against)
+        // ------------------------------------------------------------------
+        if (this.driftTracker && this.allowedIndex) {
+            const driftResult = this.driftTracker.update(sessionId, embedding, this.allowedIndex);
+            if (driftResult.driftLimitExceeded) {
+                return {
+                    // Drift is always a FLAG — it represents a gradual trend, not
+                    // an immediate policy violation.
+                    action: GuardrailAction.FLAG,
+                    reason: `Session has drifted off-topic for ${driftResult.driftStreak} consecutive messages.`,
+                    reasonCode: REASON_DRIFT,
+                    metadata: {
+                        driftStreak: driftResult.driftStreak,
+                        currentSimilarity: driftResult.currentSimilarity,
+                        nearestTopic: driftResult.nearestTopic?.topicId ?? null,
+                        nearestTopicName: driftResult.nearestTopic?.topicName ?? null,
+                    },
+                };
+            }
+        }
+        // All checks passed — no action needed.
+        return null;
+    }
+    // -------------------------------------------------------------------------
+    // Lazy index building
+    // -------------------------------------------------------------------------
+    /**
+     * Ensures that the allowed and forbidden embedding indices have been built.
+     *
+     * Called once before the first evaluation.  Subsequent calls are no-ops
+     * (guarded by the `indicesBuilt` flag).
+     *
+     * @internal
+     */
+    async ensureIndicesBuilt() {
+        if (this.indicesBuilt) {
+            return;
+        }
+        // Build the forbidden-topic index if any forbidden topics are configured.
+        if (this.options.forbiddenTopics && this.options.forbiddenTopics.length > 0) {
+            this.forbiddenIndex = new TopicEmbeddingIndex(this.embeddingFn);
+            await this.forbiddenIndex.build(this.options.forbiddenTopics);
+        }
+        // Build the allowed-topic index if any allowed topics are configured.
+        if (this.options.allowedTopics && this.options.allowedTopics.length > 0) {
+            this.allowedIndex = new TopicEmbeddingIndex(this.embeddingFn);
+            await this.allowedIndex.build(this.options.allowedTopics);
+        }
+        this.indicesBuilt = true;
+    }
+    // -------------------------------------------------------------------------
+    // Registry-based embedding fallback
+    // -------------------------------------------------------------------------
+    /**
+     * 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
+     */
+    createRegistryEmbeddingFn() {
+        return async (texts) => {
+            // Attempt to retrieve the EmbeddingManager from the shared registry.
+            const em = await this.services.getOrCreate('agentos:topicality:embedding-manager', async () => {
+                throw new Error('EmbeddingManager not available in shared service registry. ' +
+                    'Provide an explicit embeddingFn or register an EmbeddingManager.');
+            });
+            return em.generateEmbeddings(texts);
+        };
+    }
+}
+//# sourceMappingURL=TopicalityGuardrail.js.map

package/dist/TopicalityGuardrail.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Pack factory for the Topicality Guardrail Extension Pack.
+ *
+ * Exports the main `createTopicalityPack()` factory that assembles the
+ * {@link TopicalityGuardrail} and the {@link CheckTopicTool} 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
+ * `createTopicalityPack()` with options extracted from the
+ * {@link ExtensionPackContext}.
+ *
+ * ### Default behaviour (zero-config)
+ * When called without arguments, no topics are configured so the guardrail
+ * and tool are effectively no-ops.  Callers should provide at least
+ * `allowedTopics` or `forbiddenTopics` for meaningful enforcement.
+ *
+ * ### 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 (embedding models) are shared across the agent.
+ *
+ * @example
+ * ```typescript
+ * import { createTopicalityPack, TOPIC_PRESETS } from './topicality';
+ *
+ * const pack = createTopicalityPack({
+ *   allowedTopics: TOPIC_PRESETS.customerSupport,
+ *   forbiddenTopics: TOPIC_PRESETS.commonUnsafe,
+ * });
+ * ```
+ *
+ * @module agentos/extensions/packs/topicality
+ */
+import type { ExtensionPack, ExtensionPackContext } from '@framers/agentos';
+import type { TopicalityPackOptions } from './types';
+/**
+ * Re-export all types from the topicality type definitions so consumers
+ * can import everything from a single entry point:
+ * ```ts
+ * import { createTopicalityPack, TOPIC_PRESETS } from './topicality';
+ * ```
+ */
+export * from './types';
+/**
+ * Create an {@link ExtensionPack} that bundles:
+ *  - The {@link TopicalityGuardrail} guardrail (evaluates input & output
+ *    against allowed/forbidden topics and drift detection).
+ *  - The {@link CheckTopicTool} `check_topic` tool (on-demand topic analysis).
+ *
+ * @param options - Optional pack-level configuration.  All properties have
+ *                  sensible defaults; see {@link TopicalityPackOptions}.
+ * @returns A fully-configured {@link ExtensionPack} with one guardrail
+ *          descriptor and one tool descriptor.
+ */
+export declare function createTopicalityPack(options?: TopicalityPackOptions): ExtensionPack;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Conforms to the convention expected by the extension loader when resolving
+ * packs from manifests.  Extracts `options` from the {@link ExtensionPackContext}
+ * and delegates to {@link createTopicalityPack}.
+ *
+ * @param context - Manifest context containing optional pack options, secret
+ *                  resolver, and shared service registry.
+ * @returns A fully-configured {@link ExtensionPack}.
+ *
+ * @example Manifest entry:
+ * ```json
+ * {
+ *   "packs": [
+ *     {
+ *       "module": "./topicality",
+ *       "options": {
+ *         "allowedTopics": [...],
+ *         "forbiddenTopics": [...],
+ *         "allowedThreshold": 0.4
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAQrD;;;;;;GAMG;AACH,cAAc,SAAS,CAAC;AAMxB;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAgMnF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAEhF"}