@framers/agentos-ext-topicality 0.1.0

package/dist/TopicEmbeddingIndex.js

@@ -0,0 +1,291 @@
+/**
+ * @fileoverview TopicEmbeddingIndex — semantic similarity lookup for topic guardrails.
+ *
+ * This module implements a lightweight in-memory embedding index that:
+ *
+ * 1. **Builds** per-topic centroid embeddings from descriptions + examples.
+ * 2. **Matches** an arbitrary embedding or text string against all topic centroids
+ *    using cosine similarity.
+ * 3. **Answers** boolean on-topic queries at a configurable similarity threshold.
+ *
+ * ### How centroids are built
+ * For each {@link TopicDescriptor} the index concatenates:
+ * ```
+ * texts = [descriptor.description, ...descriptor.examples]
+ * ```
+ * All topics are embedded in a single batch call to `embeddingFn` to minimise
+ * round-trips.  The centroid for a topic is the component-wise average (mean)
+ * of all its embedding vectors.
+ *
+ * ### Similarity scoring
+ * Raw cosine similarity can be negative when vectors point in opposite directions.
+ * `matchByVector` clamps scores to `Math.max(0, similarity)` so that all
+ * {@link TopicMatch} values represent non-negative relevance scores.
+ *
+ * @module topicality/TopicEmbeddingIndex
+ */
+import { cosineSimilarity } from '@framers/agentos/core/utils/text-utils';
+// ---------------------------------------------------------------------------
+// TopicEmbeddingIndex
+// ---------------------------------------------------------------------------
+/**
+ * Semantic embedding index for topicality guardrail matching.
+ *
+ * The index is intentionally **lazy** — it holds no embeddings until
+ * {@link build} is called.  This makes instantiation cheap and lets the
+ * caller defer the (potentially expensive) batch embedding call until the
+ * agent's first message.
+ *
+ * @example
+ * ```ts
+ * const index = new TopicEmbeddingIndex(async (texts) => {
+ *   const res = await openai.embeddings.create({ model: 'text-embedding-3-small', input: texts });
+ *   return res.data.map(d => d.embedding);
+ * });
+ *
+ * await index.build(TOPIC_PRESETS.customerSupport);
+ *
+ * const matches = await index.match('How do I cancel my subscription?');
+ * // → [{ topicId: 'billing', topicName: 'Billing & Payments', similarity: 0.82 }, ...]
+ *
+ * const onTopic = await index.isOnTopic('Tell me a joke', 0.35);
+ * // → false (a joke doesn't match any customer-support topic)
+ * ```
+ */
+export class TopicEmbeddingIndex {
+    /**
+     * Caller-supplied batch embedding function.
+     * Invoked once during {@link build} with all topic texts concatenated.
+     */
+    embeddingFn;
+    /**
+     * Internal store mapping `topicId → TopicEntry`.
+     * Populated by {@link build}; empty until then.
+     */
+    entries = new Map();
+    /** Whether {@link build} has been called and completed successfully. */
+    built = false;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * Creates a new `TopicEmbeddingIndex`.
+     *
+     * @param embeddingFn - Async function that converts an array of text strings
+     *   into corresponding numeric embedding vectors.  All returned vectors must
+     *   share the same dimensionality.  The function is called exactly **once**
+     *   per {@link build} invocation with all texts for all topics batched
+     *   together.
+     */
+    constructor(embeddingFn) {
+        this.embeddingFn = embeddingFn;
+    }
+    // -------------------------------------------------------------------------
+    // Public API — build
+    // -------------------------------------------------------------------------
+    /**
+     * Embeds all topic descriptions and examples, computes per-topic centroid
+     * embeddings, and stores them in the internal index.
+     *
+     * Calling `build()` a second time replaces the existing index entirely,
+     * allowing hot-reloading of topic configurations without recreating the
+     * instance.
+     *
+     * ### Centroid computation
+     * For each topic we collect `[description, ...examples]` as a list of
+     * strings, embed them all in one batch, then average the resulting vectors
+     * component-wise to produce a single representative centroid.
+     *
+     * All topics are embedded in a **single batch call** to minimise latency.
+     *
+     * @param topics - Array of {@link TopicDescriptor} objects to index.
+     *   An empty array is valid — the index will simply return no matches.
+     * @returns A promise that resolves once all embeddings are computed and
+     *   stored.  Rejects if `embeddingFn` throws or returns vectors of
+     *   mismatched length.
+     */
+    async build(topics) {
+        // Reset state before (re)building so a failed build leaves the index empty
+        // rather than in a partial state.
+        this.entries.clear();
+        this.built = false;
+        if (topics.length === 0) {
+            // Nothing to embed — mark as built so isBuilt returns true.
+            this.built = true;
+            return;
+        }
+        // Collect, per topic, the list of texts to embed and the range of
+        // indices they will occupy in the flat batch array.
+        //
+        // Layout: [topic0_desc, topic0_ex0, topic0_ex1, …, topic1_desc, …]
+        const allTexts = [];
+        const topicRanges = [];
+        for (const topic of topics) {
+            const start = allTexts.length;
+            // Always include the description as the first text for this topic.
+            allTexts.push(topic.description);
+            // Then all examples (may be empty — the centroid will just be the description).
+            for (const example of topic.examples) {
+                allTexts.push(example);
+            }
+            const end = allTexts.length; // exclusive
+            topicRanges.push({ topic, start, end });
+        }
+        // Single batch embedding call — one round-trip regardless of how many
+        // topics or examples are configured.
+        const allEmbeddings = await this.embeddingFn(allTexts);
+        // Validate that the embedding function returned the right number of vectors.
+        if (allEmbeddings.length !== allTexts.length) {
+            throw new Error(`TopicEmbeddingIndex.build: embeddingFn returned ${allEmbeddings.length} vectors ` +
+                `but ${allTexts.length} texts were provided.`);
+        }
+        // Compute centroid for each topic from its slice of the batch result.
+        for (const { topic, start, end } of topicRanges) {
+            const slice = allEmbeddings.slice(start, end);
+            const centroid = computeCentroid(slice);
+            this.entries.set(topic.id, { descriptor: topic, centroid });
+        }
+        this.built = true;
+    }
+    // -------------------------------------------------------------------------
+    // Public API — matchByVector
+    // -------------------------------------------------------------------------
+    /**
+     * Computes similarity between a pre-computed embedding vector and all topic
+     * centroids **without** making any additional embedding calls.
+     *
+     * This is the hot path invoked by {@link TopicDriftTracker}, which maintains
+     * its own running embedding and never needs to re-embed.
+     *
+     * Results are clamped to `[0, 1]` (negative cosine → 0) and sorted
+     * descending by similarity.
+     *
+     * @param embedding - A numeric vector with the same dimensionality as the
+     *   centroids produced during {@link build}.
+     * @returns Array of {@link TopicMatch} objects sorted by similarity
+     *   descending.  Returns an empty array if the index was not yet built or
+     *   contains no topics.
+     */
+    matchByVector(embedding) {
+        if (!this.built || this.entries.size === 0) {
+            // Return empty rather than throwing — callers can treat no match as off-topic.
+            return [];
+        }
+        const matches = [];
+        for (const [topicId, entry] of this.entries) {
+            const raw = cosineSimilarity(embedding, entry.centroid);
+            // Clamp to [0, 1] — negative similarity means "opposite direction" which
+            // is no more useful than "unrelated" for topic matching.
+            const similarity = Math.max(0, raw);
+            matches.push({
+                topicId,
+                topicName: entry.descriptor.name,
+                similarity,
+            });
+        }
+        // Sort descending so the best match is first.
+        matches.sort((a, b) => b.similarity - a.similarity);
+        return matches;
+    }
+    // -------------------------------------------------------------------------
+    // Public API — match
+    // -------------------------------------------------------------------------
+    /**
+     * Embeds `text` and returns similarity scores against all topic centroids.
+     *
+     * This is a convenience wrapper that handles the embedding step.  If you
+     * already have an embedding (e.g. from the drift tracker's running vector)
+     * prefer {@link matchByVector} to avoid a redundant embedding call.
+     *
+     * @param text - The user message or assistant output to evaluate.
+     * @returns A promise resolving to {@link TopicMatch}[] sorted descending.
+     */
+    async match(text) {
+        // Embed the single query text.
+        const [embedding] = await this.embeddingFn([text]);
+        return this.matchByVector(embedding);
+    }
+    // -------------------------------------------------------------------------
+    // Public API — isOnTopicByVector
+    // -------------------------------------------------------------------------
+    /**
+     * Returns `true` if the given embedding vector scores above `threshold`
+     * against **at least one** topic in the index.
+     *
+     * Uses {@link matchByVector} internally so no additional embedding call is
+     * made.
+     *
+     * @param embedding - Pre-computed numeric vector.
+     * @param threshold - Minimum similarity (in `[0, 1]`) for a topic to count
+     *   as a match.
+     * @returns `true` if any topic centroid has similarity > threshold; otherwise `false`.
+     */
+    isOnTopicByVector(embedding, threshold) {
+        const matches = this.matchByVector(embedding);
+        // The list is sorted descending, so we only need to check the first entry.
+        return matches.length > 0 && matches[0].similarity > threshold;
+    }
+    // -------------------------------------------------------------------------
+    // Public API — isOnTopic
+    // -------------------------------------------------------------------------
+    /**
+     * Embeds `text` and returns `true` if it scores above `threshold` against
+     * at least one allowed topic.
+     *
+     * @param text      - The text to evaluate.
+     * @param threshold - Minimum cosine similarity for the text to be considered on-topic.
+     * @returns A promise resolving to `true` if on-topic, `false` otherwise.
+     */
+    async isOnTopic(text, threshold) {
+        const [embedding] = await this.embeddingFn([text]);
+        return this.isOnTopicByVector(embedding, threshold);
+    }
+    // -------------------------------------------------------------------------
+    // Getter
+    // -------------------------------------------------------------------------
+    /**
+     * Whether {@link build} has been called and completed successfully.
+     *
+     * Use this to guard against calling {@link match} or {@link matchByVector}
+     * before the index is ready.
+     *
+     * @example
+     * ```ts
+     * if (!index.isBuilt) await index.build(topics);
+     * ```
+     */
+    get isBuilt() {
+        return this.built;
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Computes the component-wise average (centroid) of an array of embedding
+ * vectors.
+ *
+ * All input vectors are assumed to have the same dimensionality.  If the
+ * input array is empty an empty array is returned (safe no-op).
+ *
+ * @param vectors - One or more numeric vectors of equal length.
+ * @returns A single vector whose i-th element is the mean of i-th elements
+ *   across all input vectors.
+ *
+ * @internal
+ */
+function computeCentroid(vectors) {
+    if (vectors.length === 0)
+        return [];
+    const dim = vectors[0].length;
+    // Initialise accumulator to all zeros.
+    const sum = new Array(dim).fill(0);
+    for (const vec of vectors) {
+        for (let i = 0; i < dim; i++) {
+            sum[i] += vec[i];
+        }
+    }
+    // Divide each component by the number of vectors to get the mean.
+    return sum.map((v) => v / vectors.length);
+}
+//# sourceMappingURL=TopicEmbeddingIndex.js.map

package/dist/TopicEmbeddingIndex.js.map

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

package/dist/TopicalityGuardrail.d.ts

@@ -0,0 +1,196 @@
+/**
+ * @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 type { GuardrailConfig, GuardrailEvaluationResult, GuardrailInputPayload, GuardrailOutputPayload, IGuardrailService } from '@framers/agentos';
+import type { ISharedServiceRegistry } from '@framers/agentos';
+import type { TopicalityPackOptions } from './types';
+/**
+ * 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 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.
+     */
+    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;
+    /**
+     * Minimum similarity to any allowed topic for the message to be
+     * considered on-topic.
+     */
+    private readonly allowedThreshold;
+    /**
+     * 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`.
+     *
+     * @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: ISharedServiceRegistry, options: TopicalityPackOptions, embeddingFn?: (texts: string[]) => Promise<number[][]>);
+    /**
+     * 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(): void;
+    /**
+     * 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).
+     */
+    evaluateInput(payload: GuardrailInputPayload): Promise<GuardrailEvaluationResult | null>;
+    /**
+     * 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).
+     */
+    evaluateOutput(payload: GuardrailOutputPayload): Promise<GuardrailEvaluationResult | null>;
+    /**
+     * 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
+     */
+    private evaluateEmbedding;
+    /**
+     * 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
+     */
+    private ensureIndicesBuilt;
+    /**
+     * 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
+     */
+    private createRegistryEmbeddingFn;
+}
+//# sourceMappingURL=TopicalityGuardrail.d.ts.map

package/dist/TopicalityGuardrail.d.ts.map

@@ -0,0 +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"}