@framers/agentos-ext-topicality 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Framers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/dist/TopicDriftTracker.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview TopicDriftTracker — session-level EMA drift detection for topicality guardrails.
+ *
+ * This module tracks whether a conversation session is gradually drifting away
+ * from its allowed topics by maintaining a per-session **running embedding**
+ * that is updated with each new message using an Exponential Moving Average
+ * (EMA).
+ *
+ * ### Why EMA?
+ * A simple "last-message" check is too noisy: a single off-topic message in an
+ * otherwise on-topic conversation should not trigger a hard block.  EMA
+ * smooths the signal so that sustained drift is detected while brief tangents
+ * are tolerated.
+ *
+ * The update formula is:
+ * ```
+ * running[i] = alpha * message[i] + (1 - alpha) * running[i]
+ * ```
+ * A smaller `alpha` means the running vector changes slowly (long memory);
+ * a larger `alpha` means it reacts quickly to each new message.
+ *
+ * ### Drift decision
+ * After each EMA update the tracker checks whether the running embedding is
+ * "on-topic" by calling {@link TopicEmbeddingIndex.isOnTopicByVector}.  If the
+ * check fails the `driftStreak` counter is incremented; if it passes the
+ * streak resets to zero.  When `driftStreak >= driftStreakLimit` the result
+ * `driftLimitExceeded` is set to `true`.
+ *
+ * ### Session management
+ * Sessions are stored in an in-memory `Map<sessionId, TopicState>`.  To
+ * prevent unbounded memory growth:
+ * - Stale sessions (inactive for > `sessionTimeoutMs`) are pruned lazily
+ *   whenever `map.size > maxSessions` at the start of an `update()` call.
+ * - Callers can force a full clear via {@link clear}.
+ *
+ * @module topicality/TopicDriftTracker
+ */
+import type { TopicEmbeddingIndex } from './TopicEmbeddingIndex';
+import { type DriftConfig, type DriftResult, type TopicState } from './types';
+/**
+ * Tracks per-session topic drift using EMA-blended running embeddings.
+ *
+ * Instantiate once per agent process (not per conversation) since the tracker
+ * manages many concurrent sessions internally.
+ *
+ * @example
+ * ```ts
+ * const tracker = new TopicDriftTracker({ alpha: 0.4, driftStreakLimit: 2 });
+ *
+ * // In your message handler:
+ * const embedding = await embed(userMessage);
+ * const result = tracker.update('session-abc', embedding, allowedIndex);
+ *
+ * if (result.driftLimitExceeded) {
+ *   // Take configured action: redirect, warn, or block.
+ * }
+ * ```
+ */
+export declare class TopicDriftTracker {
+    /** Fully resolved drift configuration (defaults merged with caller overrides). */
+    private readonly config;
+    /**
+     * In-memory session store.
+     * Key: caller-supplied session ID (e.g. conversation UUID).
+     * Value: mutable {@link TopicState} for that session.
+     */
+    private readonly sessions;
+    /**
+     * Creates a new `TopicDriftTracker`.
+     *
+     * @param config - Optional partial override of {@link DEFAULT_DRIFT_CONFIG}.
+     *   Any fields not provided fall back to their default values.  Pass an
+     *   empty object `{}` or omit entirely to use all defaults.
+     *
+     * @example
+     * ```ts
+     * // Use defaults
+     * const tracker = new TopicDriftTracker();
+     *
+     * // Override only alpha and streakLimit
+     * const strictTracker = new TopicDriftTracker({ alpha: 0.5, driftStreakLimit: 2 });
+     * ```
+     */
+    constructor(config?: Partial<DriftConfig>);
+    /**
+     * Processes a new message embedding for the given session and returns the
+     * current drift assessment.
+     *
+     * ### Steps performed
+     * 1. **Retrieve or create** the session state.  On the very first message
+     *    the running embedding is initialised to a shallow copy of
+     *    `messageEmbedding` (no EMA applied yet).
+     * 2. **Apply EMA** (from the second message onwards):
+     *    `running[i] = alpha * message[i] + (1 - alpha) * running[i]`
+     * 3. **Check topic alignment** using
+     *    `allowedIndex.isOnTopicByVector(running, driftThreshold)`.
+     * 4. **Update streak** — increment `driftStreak` on off-topic, reset to 0
+     *    on on-topic.
+     * 5. **Lazy-prune** stale sessions when `map.size > maxSessions` before
+     *    creating a new session (never during updates of existing sessions to
+     *    avoid deleting the session we are currently updating).
+     * 6. **Persist** the updated state and return a {@link DriftResult}.
+     *
+     * @param sessionId        - Unique identifier for the conversation session.
+     *   Typically a UUID or user ID. Must be consistent across messages in the
+     *   same conversation.
+     * @param messageEmbedding - Pre-computed numeric embedding of the current
+     *   message.  Must have the same dimensionality as the topic centroids used
+     *   by `allowedIndex`.
+     * @param allowedIndex     - Built {@link TopicEmbeddingIndex} containing the
+     *   allowed topics to check against.  The tracker calls only
+     *   `isOnTopicByVector` (no async operations, no extra embedding calls).
+     * @returns A {@link DriftResult} describing whether the session is currently
+     *   drifting and by how much.
+     */
+    update(sessionId: string, messageEmbedding: number[], allowedIndex: TopicEmbeddingIndex): DriftResult;
+    /**
+     * Removes sessions that have been inactive for longer than `sessionTimeoutMs`.
+     *
+     * This is called lazily inside {@link update} when the session map exceeds
+     * `maxSessions`, but callers may invoke it directly to trigger an immediate
+     * cleanup (e.g. in a scheduled maintenance job).
+     *
+     * Pruning is O(n) in the number of active sessions.
+     */
+    pruneStale(): void;
+    /**
+     * Removes all sessions from the tracker unconditionally.
+     *
+     * Useful for graceful shutdown, testing teardown, or resetting the agent
+     * context between evaluation runs.
+     */
+    clear(): void;
+    /**
+     * Returns the current number of active sessions in the internal map.
+     * Useful for observability and testing.
+     *
+     * @internal
+     */
+    get sessionCount(): number;
+    /**
+     * Returns a copy of the {@link TopicState} for the given session, or
+     * `undefined` if the session does not exist.
+     *
+     * Exposed for unit-testing state inspection.  The returned object is a
+     * shallow copy — mutating it does not affect the tracker's internal state.
+     *
+     * @internal
+     */
+    getState(sessionId: string): TopicState | undefined;
+}
+//# sourceMappingURL=TopicDriftTracker.d.ts.map

package/dist/TopicDriftTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopicDriftTracker.d.ts","sourceRoot":"","sources":["../src/TopicDriftTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,WAAW,EAEhB,KAAK,UAAU,EAChB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAC5B,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAM/D;;;;;;;;;;;;;;;OAeG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAUzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EAAE,EAC1B,YAAY,EAAE,mBAAmB,GAChC,WAAW;IAiGd;;;;;;;;OAQG;IACH,UAAU,IAAI,IAAI;IAelB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAQb;;;;;OAKG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;CAMpD"}

package/dist/TopicDriftTracker.js

@@ -0,0 +1,265 @@
+/**
+ * @fileoverview TopicDriftTracker — session-level EMA drift detection for topicality guardrails.
+ *
+ * This module tracks whether a conversation session is gradually drifting away
+ * from its allowed topics by maintaining a per-session **running embedding**
+ * that is updated with each new message using an Exponential Moving Average
+ * (EMA).
+ *
+ * ### Why EMA?
+ * A simple "last-message" check is too noisy: a single off-topic message in an
+ * otherwise on-topic conversation should not trigger a hard block.  EMA
+ * smooths the signal so that sustained drift is detected while brief tangents
+ * are tolerated.
+ *
+ * The update formula is:
+ * ```
+ * running[i] = alpha * message[i] + (1 - alpha) * running[i]
+ * ```
+ * A smaller `alpha` means the running vector changes slowly (long memory);
+ * a larger `alpha` means it reacts quickly to each new message.
+ *
+ * ### Drift decision
+ * After each EMA update the tracker checks whether the running embedding is
+ * "on-topic" by calling {@link TopicEmbeddingIndex.isOnTopicByVector}.  If the
+ * check fails the `driftStreak` counter is incremented; if it passes the
+ * streak resets to zero.  When `driftStreak >= driftStreakLimit` the result
+ * `driftLimitExceeded` is set to `true`.
+ *
+ * ### Session management
+ * Sessions are stored in an in-memory `Map<sessionId, TopicState>`.  To
+ * prevent unbounded memory growth:
+ * - Stale sessions (inactive for > `sessionTimeoutMs`) are pruned lazily
+ *   whenever `map.size > maxSessions` at the start of an `update()` call.
+ * - Callers can force a full clear via {@link clear}.
+ *
+ * @module topicality/TopicDriftTracker
+ */
+import { DEFAULT_DRIFT_CONFIG, } from './types';
+// ---------------------------------------------------------------------------
+// TopicDriftTracker
+// ---------------------------------------------------------------------------
+/**
+ * Tracks per-session topic drift using EMA-blended running embeddings.
+ *
+ * Instantiate once per agent process (not per conversation) since the tracker
+ * manages many concurrent sessions internally.
+ *
+ * @example
+ * ```ts
+ * const tracker = new TopicDriftTracker({ alpha: 0.4, driftStreakLimit: 2 });
+ *
+ * // In your message handler:
+ * const embedding = await embed(userMessage);
+ * const result = tracker.update('session-abc', embedding, allowedIndex);
+ *
+ * if (result.driftLimitExceeded) {
+ *   // Take configured action: redirect, warn, or block.
+ * }
+ * ```
+ */
+export class TopicDriftTracker {
+    /** Fully resolved drift configuration (defaults merged with caller overrides). */
+    config;
+    /**
+     * In-memory session store.
+     * Key: caller-supplied session ID (e.g. conversation UUID).
+     * Value: mutable {@link TopicState} for that session.
+     */
+    sessions = new Map();
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * Creates a new `TopicDriftTracker`.
+     *
+     * @param config - Optional partial override of {@link DEFAULT_DRIFT_CONFIG}.
+     *   Any fields not provided fall back to their default values.  Pass an
+     *   empty object `{}` or omit entirely to use all defaults.
+     *
+     * @example
+     * ```ts
+     * // Use defaults
+     * const tracker = new TopicDriftTracker();
+     *
+     * // Override only alpha and streakLimit
+     * const strictTracker = new TopicDriftTracker({ alpha: 0.5, driftStreakLimit: 2 });
+     * ```
+     */
+    constructor(config) {
+        // Merge caller overrides with defaults — undefined fields are taken from
+        // DEFAULT_DRIFT_CONFIG, preserving all caller-supplied values exactly.
+        this.config = { ...DEFAULT_DRIFT_CONFIG, ...(config ?? {}) };
+    }
+    // -------------------------------------------------------------------------
+    // Public API — update
+    // -------------------------------------------------------------------------
+    /**
+     * Processes a new message embedding for the given session and returns the
+     * current drift assessment.
+     *
+     * ### Steps performed
+     * 1. **Retrieve or create** the session state.  On the very first message
+     *    the running embedding is initialised to a shallow copy of
+     *    `messageEmbedding` (no EMA applied yet).
+     * 2. **Apply EMA** (from the second message onwards):
+     *    `running[i] = alpha * message[i] + (1 - alpha) * running[i]`
+     * 3. **Check topic alignment** using
+     *    `allowedIndex.isOnTopicByVector(running, driftThreshold)`.
+     * 4. **Update streak** — increment `driftStreak` on off-topic, reset to 0
+     *    on on-topic.
+     * 5. **Lazy-prune** stale sessions when `map.size > maxSessions` before
+     *    creating a new session (never during updates of existing sessions to
+     *    avoid deleting the session we are currently updating).
+     * 6. **Persist** the updated state and return a {@link DriftResult}.
+     *
+     * @param sessionId        - Unique identifier for the conversation session.
+     *   Typically a UUID or user ID. Must be consistent across messages in the
+     *   same conversation.
+     * @param messageEmbedding - Pre-computed numeric embedding of the current
+     *   message.  Must have the same dimensionality as the topic centroids used
+     *   by `allowedIndex`.
+     * @param allowedIndex     - Built {@link TopicEmbeddingIndex} containing the
+     *   allowed topics to check against.  The tracker calls only
+     *   `isOnTopicByVector` (no async operations, no extra embedding calls).
+     * @returns A {@link DriftResult} describing whether the session is currently
+     *   drifting and by how much.
+     */
+    update(sessionId, messageEmbedding, allowedIndex) {
+        const now = Date.now();
+        const isNewSession = !this.sessions.has(sessionId);
+        // Lazy prune: only trigger when a NEW session would push us over the limit.
+        // We do not prune during updates of existing sessions to avoid accidentally
+        // deleting a session that is currently being processed.
+        if (isNewSession && this.sessions.size >= this.config.maxSessions) {
+            this.pruneStale();
+        }
+        let state;
+        if (isNewSession) {
+            // First message in this session — initialise running embedding to a copy
+            // of the current message embedding.  A copy prevents external mutation
+            // of the array from silently corrupting the tracker state.
+            state = {
+                runningEmbedding: [...messageEmbedding],
+                messageCount: 0, // will be incremented below
+                lastTopicScore: 0,
+                driftStreak: 0,
+                lastSeenAt: now,
+            };
+        }
+        else {
+            // Retrieve existing state — guaranteed non-null by the `has()` check above.
+            state = this.sessions.get(sessionId);
+            // Apply the EMA update in-place.
+            // running[i] = alpha * message[i] + (1 - alpha) * running[i]
+            const alpha = this.config.alpha;
+            const oneMinusAlpha = 1 - alpha;
+            for (let i = 0; i < state.runningEmbedding.length; i++) {
+                state.runningEmbedding[i] =
+                    alpha * messageEmbedding[i] + oneMinusAlpha * state.runningEmbedding[i];
+            }
+        }
+        // Increment message counter and timestamp.
+        state.messageCount += 1;
+        state.lastSeenAt = now;
+        // -----------------------------------------------------------------------
+        // Topic alignment check
+        // -----------------------------------------------------------------------
+        // Check whether the (now-updated) running embedding is on-topic.
+        const onTopic = allowedIndex.isOnTopicByVector(state.runningEmbedding, this.config.driftThreshold);
+        // Retrieve the best-match details from the index for the result payload.
+        // matchByVector is synchronous and does not re-embed anything.
+        const topMatches = allowedIndex.matchByVector(state.runningEmbedding);
+        const nearestTopic = topMatches.length > 0 ? topMatches[0] : null;
+        const currentSimilarity = nearestTopic?.similarity ?? 0;
+        // Store the latest similarity score for observability.
+        state.lastTopicScore = currentSimilarity;
+        // -----------------------------------------------------------------------
+        // Drift streak management
+        // -----------------------------------------------------------------------
+        if (onTopic) {
+            // Good message — reset the drift counter.
+            state.driftStreak = 0;
+        }
+        else {
+            // Off-topic message — accumulate the streak.
+            state.driftStreak += 1;
+        }
+        const driftLimitExceeded = state.driftStreak >= this.config.driftStreakLimit;
+        // -----------------------------------------------------------------------
+        // Persist state and return result
+        // -----------------------------------------------------------------------
+        // Always write back (even for existing sessions, since we mutated in-place
+        // for the EMA; for new sessions we need to insert).
+        this.sessions.set(sessionId, state);
+        return {
+            onTopic,
+            currentSimilarity,
+            nearestTopic,
+            driftStreak: state.driftStreak,
+            driftLimitExceeded,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Public API — pruneStale
+    // -------------------------------------------------------------------------
+    /**
+     * Removes sessions that have been inactive for longer than `sessionTimeoutMs`.
+     *
+     * This is called lazily inside {@link update} when the session map exceeds
+     * `maxSessions`, but callers may invoke it directly to trigger an immediate
+     * cleanup (e.g. in a scheduled maintenance job).
+     *
+     * Pruning is O(n) in the number of active sessions.
+     */
+    pruneStale() {
+        const now = Date.now();
+        const timeoutMs = this.config.sessionTimeoutMs;
+        for (const [id, state] of this.sessions) {
+            if (now - state.lastSeenAt > timeoutMs) {
+                this.sessions.delete(id);
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Public API — clear
+    // -------------------------------------------------------------------------
+    /**
+     * Removes all sessions from the tracker unconditionally.
+     *
+     * Useful for graceful shutdown, testing teardown, or resetting the agent
+     * context between evaluation runs.
+     */
+    clear() {
+        this.sessions.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Internal helpers (exposed for testing via package-private pattern)
+    // -------------------------------------------------------------------------
+    /**
+     * Returns the current number of active sessions in the internal map.
+     * Useful for observability and testing.
+     *
+     * @internal
+     */
+    get sessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Returns a copy of the {@link TopicState} for the given session, or
+     * `undefined` if the session does not exist.
+     *
+     * Exposed for unit-testing state inspection.  The returned object is a
+     * shallow copy — mutating it does not affect the tracker's internal state.
+     *
+     * @internal
+     */
+    getState(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return undefined;
+        // Shallow copy to prevent callers from accidentally mutating tracker state.
+        return { ...state, runningEmbedding: [...state.runningEmbedding] };
+    }
+}
+//# sourceMappingURL=TopicDriftTracker.js.map

package/dist/TopicDriftTracker.js.map

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

package/dist/TopicEmbeddingIndex.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @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 type { TopicDescriptor, TopicMatch } from './types';
+/**
+ * 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 declare class TopicEmbeddingIndex {
+    /**
+     * Caller-supplied batch embedding function.
+     * Invoked once during {@link build} with all topic texts concatenated.
+     */
+    private readonly embeddingFn;
+    /**
+     * Internal store mapping `topicId → TopicEntry`.
+     * Populated by {@link build}; empty until then.
+     */
+    private readonly entries;
+    /** Whether {@link build} has been called and completed successfully. */
+    private built;
+    /**
+     * 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: (texts: string[]) => Promise<number[][]>);
+    /**
+     * 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.
+     */
+    build(topics: TopicDescriptor[]): Promise<void>;
+    /**
+     * 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: number[]): TopicMatch[];
+    /**
+     * 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.
+     */
+    match(text: string): Promise<TopicMatch[]>;
+    /**
+     * 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: number[], threshold: number): boolean;
+    /**
+     * 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.
+     */
+    isOnTopic(text: string, threshold: number): Promise<boolean>;
+    /**
+     * 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(): boolean;
+}
+//# sourceMappingURL=TopicEmbeddingIndex.d.ts.map

package/dist/TopicEmbeddingIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopicEmbeddingIndex.d.ts","sourceRoot":"","sources":["../src/TopicEmbeddingIndex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAyB3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAmB;IAC9B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2C;IAEvE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAE9D,wEAAwE;IACxE,OAAO,CAAC,KAAK,CAAkB;IAM/B;;;;;;;;OAQG;gBACS,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAQjE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,KAAK,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyDrD;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE;IA8BhD;;;;;;;;;OASG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAUhD;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAUlE;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASlE;;;;;;;;;;OAUG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;CACF"}