@framers/agentos-ext-topicality 0.1.0

package/src/index.ts

@@ -0,0 +1,302 @@
+/**
+ * @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 { ISharedServiceRegistry } from '@framers/agentos';
+import { SharedServiceRegistry } from '@framers/agentos';
+import type { ExtensionPack, ExtensionPackContext } from '@framers/agentos';
+import type { ExtensionDescriptor, ExtensionLifecycleContext } from '@framers/agentos';
+import { EXTENSION_KIND_GUARDRAIL, EXTENSION_KIND_TOOL } from '@framers/agentos';
+import type { TopicalityPackOptions } from './types';
+import { TopicalityGuardrail } from './TopicalityGuardrail';
+import { CheckTopicTool } from './tools/CheckTopicTool';
+
+// ---------------------------------------------------------------------------
+// Re-exports — allow single-import for consumers
+// ---------------------------------------------------------------------------
+
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// Pack factory
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 function createTopicalityPack(options?: TopicalityPackOptions): ExtensionPack {
+  /**
+   * Resolved options — default to empty object so every sub-check can
+   * safely use `opts.foo` without null-guarding the whole `options` reference.
+   */
+  const opts: TopicalityPackOptions = options ?? {};
+
+  // -------------------------------------------------------------------------
+  // Mutable state — upgraded by onActivate with the extension manager's
+  // shared service registry.
+  // -------------------------------------------------------------------------
+
+  const state = {
+    /**
+     * Service registry — starts as a standalone instance so the pack can be
+     * used directly (without activation) in unit tests and scripts.
+     * Replaced with the shared registry when `onActivate` is called by the
+     * extension manager.
+     */
+    services: new SharedServiceRegistry() as ISharedServiceRegistry,
+  };
+
+  // -------------------------------------------------------------------------
+  // Component instances — rebuilt by buildComponents()
+  // -------------------------------------------------------------------------
+
+  /**
+   * The guardrail that evaluates user input and/or agent output against
+   * configured allowed and forbidden topic sets.
+   */
+  let guardrail: TopicalityGuardrail;
+
+  /**
+   * The on-demand topic checking tool exposed to agents and workflows.
+   */
+  let tool: CheckTopicTool;
+
+  // -------------------------------------------------------------------------
+  // Embedding function resolution
+  // -------------------------------------------------------------------------
+
+  /**
+   * Resolves the embedding function to use for topic matching.
+   *
+   * Priority:
+   * 1. Explicit `opts.embeddingFn` provided by the caller.
+   * 2. Fallback to the shared service registry's EmbeddingManager.
+   *
+   * @returns An async embedding function.
+   */
+  function resolveEmbeddingFn(): (texts: string[]) => Promise<number[][]> {
+    if (opts.embeddingFn) {
+      return opts.embeddingFn;
+    }
+
+    // Fallback: request an EmbeddingManager from the shared service registry
+    // at call time (lazy resolution).
+    return async (texts: string[]): Promise<number[][]> => {
+      const em = await state.services.getOrCreate<{
+        generateEmbeddings: (texts: string[]) => Promise<number[][]>;
+      }>(
+        'agentos:topicality:embedding-manager',
+        async () => {
+          throw new Error(
+            'EmbeddingManager not available in shared service registry. ' +
+              'Provide an explicit embeddingFn in TopicalityPackOptions or ' +
+              'register an EmbeddingManager before activating the topicality pack.',
+          );
+        },
+      );
+      return em.generateEmbeddings(texts);
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // buildComponents
+  // -------------------------------------------------------------------------
+
+  /**
+   * (Re)construct all pack components using the current `state.services`.
+   *
+   * Called once at pack creation for direct programmatic use, and again
+   * during `onActivate` to upgrade to the extension manager's shared
+   * service registry.
+   */
+  function buildComponents(): void {
+    const embeddingFn = resolveEmbeddingFn();
+
+    // Resolve thresholds with defaults.
+    const allowedThreshold = opts.allowedThreshold ?? 0.35;
+    const forbiddenThreshold = opts.forbiddenThreshold ?? 0.65;
+
+    // ------------------------------------------------------------------
+    // 1. Build the guardrail.
+    // ------------------------------------------------------------------
+    guardrail = new TopicalityGuardrail(state.services, opts, embeddingFn);
+
+    // ------------------------------------------------------------------
+    // 2. Build the on-demand topic checking tool.
+    //    The tool starts with null indices — the guardrail builds them
+    //    lazily, and the tool shares the same embeddingFn so it can
+    //    operate independently.
+    // ------------------------------------------------------------------
+    tool = new CheckTopicTool(
+      null, // allowedIndex — will be null until lazy build
+      null, // forbiddenIndex — will be null until lazy build
+      embeddingFn,
+      allowedThreshold,
+      forbiddenThreshold,
+    );
+
+  }
+
+  // Initial build — makes the pack usable immediately without activation.
+  buildComponents();
+
+  // -------------------------------------------------------------------------
+  // ExtensionPack shape
+  // -------------------------------------------------------------------------
+
+  return {
+    /** Canonical pack name used in manifests and logs. */
+    name: 'topicality',
+
+    /** Semantic version of this pack implementation. */
+    version: '1.0.0',
+
+    /**
+     * Descriptor getter — always returns the latest (possibly rebuilt)
+     * component instances.  Using a getter ensures that after `onActivate`
+     * rebuilds the components, the descriptors array reflects the new
+     * references rather than stale closures from the initial build.
+     */
+    get descriptors(): ExtensionDescriptor[] {
+      return [
+        {
+          /**
+           * Guardrail descriptor.
+           *
+           * Priority 3 places this guardrail early in the pipeline so
+           * topic enforcement happens before most other guardrails.
+           */
+          id: 'topicality-guardrail',
+          kind: EXTENSION_KIND_GUARDRAIL,
+          priority: 3,
+          payload: guardrail,
+        },
+        {
+          /**
+           * On-demand topic checking tool descriptor.
+           *
+           * Priority 0 uses the default ordering — tools are typically
+           * ordered by name rather than priority.
+           */
+          id: 'check_topic',
+          kind: EXTENSION_KIND_TOOL,
+          priority: 0,
+          payload: tool,
+        },
+      ];
+    },
+
+    /**
+     * Lifecycle hook called by the extension manager when the pack is
+     * activated.
+     *
+     * Upgrades the internal service registry to the extension manager's
+     * shared instance (so embedding models are shared across all
+     * extensions) then rebuilds all components to use the new registry.
+     *
+     * @param context - Activation context provided by the extension manager.
+     */
+    onActivate: (context: ExtensionLifecycleContext): void => {
+      // Upgrade to the shared registry when the manager provides one.
+      if (context.services) {
+        state.services = context.services;
+      }
+
+      // Rebuild all components with the upgraded registry.
+      buildComponents();
+    },
+
+    /**
+     * Lifecycle hook called when the pack is deactivated or the agent shuts
+     * down.
+     *
+     * Clears drift tracker session state to release memory.
+     */
+    onDeactivate: async (): Promise<void> => {
+      guardrail.clearSessionState();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Manifest factory bridge
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 function createExtensionPack(context: ExtensionPackContext): ExtensionPack {
+  return createTopicalityPack(context.options as TopicalityPackOptions);
+}

package/src/tools/CheckTopicTool.ts

@@ -0,0 +1,296 @@
+/**
+ * @fileoverview On-demand topic checking tool for the topicality extension pack.
+ *
+ * `CheckTopicTool` implements {@link ITool} and exposes a `check_topic`
+ * function that agents and workflows can invoke to determine whether a
+ * piece of text aligns with the configured allowed topics, matches any
+ * forbidden topics, or both.
+ *
+ * Unlike the {@link TopicalityGuardrail} (which runs automatically on every
+ * message), this tool is invoked explicitly and returns structured data
+ * rather than triggering block/flag actions.  It is useful for:
+ *
+ *  - Agent self-awareness ("Am I still on-topic?")
+ *  - User-facing topic suggestions ("Your question is closest to: Billing")
+ *  - Workflow branching ("If off-topic, route to fallback handler")
+ *
+ * @module topicality/tools/CheckTopicTool
+ */
+
+import type {
+  ITool,
+  JSONSchemaObject,
+  ToolExecutionContext,
+  ToolExecutionResult,
+} from '@framers/agentos';
+import type { TopicEmbeddingIndex } from '../TopicEmbeddingIndex';
+import type { TopicMatch } from '../types';
+
+// ---------------------------------------------------------------------------
+// Input / output types
+// ---------------------------------------------------------------------------
+
+/**
+ * Input arguments accepted by the `check_topic` tool.
+ */
+interface CheckTopicInput {
+  /** The text string to evaluate against configured topics. */
+  text: string;
+}
+
+/**
+ * Structured output returned by the `check_topic` tool on success.
+ */
+interface CheckTopicOutput {
+  /**
+   * Whether the text is considered on-topic (i.e., above the allowed
+   * threshold against at least one allowed topic).  `null` if no
+   * allowed topics are configured.
+   */
+  onTopic: boolean | null;
+
+  /**
+   * The allowed topic with the highest similarity to the input text,
+   * or `null` if no allowed topics are configured.
+   */
+  nearestTopic: TopicMatch | null;
+
+  /**
+   * The forbidden topic with the highest similarity to the input text,
+   * or `null` if no forbidden topics are configured or none matched.
+   * Only includes matches above the forbidden threshold.
+   */
+  forbiddenMatch: TopicMatch | null;
+
+  /**
+   * Full list of similarity scores against all configured topics
+   * (both allowed and forbidden), sorted descending by similarity.
+   */
+  allScores: TopicMatch[];
+}
+
+// ---------------------------------------------------------------------------
+// CheckTopicTool
+// ---------------------------------------------------------------------------
+
+/**
+ * On-demand topic classification tool.
+ *
+ * Embeds the input text and checks it against both allowed and forbidden
+ * topic indices, returning structured similarity data.
+ *
+ * @example
+ * ```ts
+ * const result = await tool.execute(
+ *   { text: 'How do I cancel my subscription?' },
+ *   executionContext,
+ * );
+ * // result.output.onTopic → true
+ * // result.output.nearestTopic → { topicId: 'billing', ... }
+ * ```
+ */
+export class CheckTopicTool implements ITool<CheckTopicInput, CheckTopicOutput> {
+  // -------------------------------------------------------------------------
+  // ITool metadata
+  // -------------------------------------------------------------------------
+
+  /** @inheritdoc */
+  readonly id = 'check_topic';
+
+  /** @inheritdoc */
+  readonly name = 'check_topic';
+
+  /** @inheritdoc */
+  readonly displayName = 'Topic Checker';
+
+  /** @inheritdoc */
+  readonly description =
+    'Checks whether a piece of text aligns with configured allowed topics or ' +
+    'matches any forbidden topics. Returns similarity scores and the nearest ' +
+    'topic match. Useful for agent self-awareness and workflow branching.';
+
+  /** @inheritdoc */
+  readonly category = 'security';
+
+  /** @inheritdoc */
+  readonly version = '1.0.0';
+
+  /** @inheritdoc */
+  readonly hasSideEffects = false;
+
+  /** @inheritdoc */
+  readonly inputSchema: JSONSchemaObject = {
+    type: 'object',
+    properties: {
+      text: {
+        type: 'string',
+        description: 'The text to evaluate against configured topics.',
+      },
+    },
+    required: ['text'],
+    additionalProperties: false,
+  };
+
+  // -------------------------------------------------------------------------
+  // Private state
+  // -------------------------------------------------------------------------
+
+  /**
+   * Embedding index for allowed topics.  May be `null` if no allowed
+   * topics are configured.
+   */
+  private allowedIndex: TopicEmbeddingIndex | null;
+
+  /**
+   * Embedding index for forbidden topics.  May be `null` if no forbidden
+   * topics are configured.
+   */
+  private forbiddenIndex: TopicEmbeddingIndex | null;
+
+  /**
+   * Embedding function used to convert input text to a numeric vector.
+   */
+  private readonly embeddingFn: (texts: string[]) => Promise<number[][]>;
+
+  /**
+   * Minimum similarity score against an allowed topic for the text to
+   * be considered on-topic.
+   */
+  private readonly allowedThreshold: number;
+
+  /**
+   * Similarity score above which a forbidden topic match is reported.
+   */
+  private readonly forbiddenThreshold: number;
+
+  // -------------------------------------------------------------------------
+  // Constructor
+  // -------------------------------------------------------------------------
+
+  /**
+   * Creates a new `CheckTopicTool`.
+   *
+   * @param allowedIndex      - Pre-built index of allowed topics (or `null`).
+   * @param forbiddenIndex    - Pre-built index of forbidden topics (or `null`).
+   * @param embeddingFn       - Async function to embed text strings.
+   * @param allowedThreshold  - Minimum similarity for on-topic classification.
+   * @param forbiddenThreshold - Minimum similarity for forbidden topic flagging.
+   */
+  constructor(
+    allowedIndex: TopicEmbeddingIndex | null,
+    forbiddenIndex: TopicEmbeddingIndex | null,
+    embeddingFn: (texts: string[]) => Promise<number[][]>,
+    allowedThreshold: number,
+    forbiddenThreshold: number,
+  ) {
+    this.allowedIndex = allowedIndex;
+    this.forbiddenIndex = forbiddenIndex;
+    this.embeddingFn = embeddingFn;
+    this.allowedThreshold = allowedThreshold;
+    this.forbiddenThreshold = forbiddenThreshold;
+  }
+
+  // -------------------------------------------------------------------------
+  // Index setters (used by pack factory on rebuild)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Replaces the allowed topic index.  Called by the pack factory when
+   * components are rebuilt (e.g., after `onActivate`).
+   *
+   * @param index - The new allowed topic index (or `null` to clear).
+   */
+  setAllowedIndex(index: TopicEmbeddingIndex | null): void {
+    this.allowedIndex = index;
+  }
+
+  /**
+   * Replaces the forbidden topic index.  Called by the pack factory when
+   * components are rebuilt.
+   *
+   * @param index - The new forbidden topic index (or `null` to clear).
+   */
+  setForbiddenIndex(index: TopicEmbeddingIndex | null): void {
+    this.forbiddenIndex = index;
+  }
+
+  // -------------------------------------------------------------------------
+  // ITool — execute
+  // -------------------------------------------------------------------------
+
+  /**
+   * Embeds the input text and evaluates it against allowed and forbidden
+   * topic indices.
+   *
+   * @param args    - Input arguments containing the `text` field.
+   * @param context - Tool execution context (not used by this tool).
+   * @returns A {@link ToolExecutionResult} containing the structured
+   *   topic analysis or an error message.
+   */
+  async execute(
+    args: CheckTopicInput,
+    context: ToolExecutionContext,
+  ): Promise<ToolExecutionResult<CheckTopicOutput>> {
+    // Validate input.
+    if (!args.text || args.text.trim().length === 0) {
+      return {
+        success: false,
+        error: 'The "text" field is required and must be a non-empty string.',
+      };
+    }
+
+    try {
+      // Embed the input text once.
+      const [embedding] = await this.embeddingFn([args.text]);
+
+      // Collect all scores from both indices.
+      const allScores: TopicMatch[] = [];
+
+      // --- Allowed topics ---
+      let onTopic: boolean | null = null;
+      let nearestTopic: TopicMatch | null = null;
+
+      if (this.allowedIndex) {
+        const allowedMatches = this.allowedIndex.matchByVector(embedding);
+        allScores.push(...allowedMatches);
+
+        // Determine if on-topic using the threshold.
+        onTopic = this.allowedIndex.isOnTopicByVector(embedding, this.allowedThreshold);
+
+        // The nearest topic is the first match (highest similarity).
+        nearestTopic = allowedMatches.length > 0 ? allowedMatches[0] : null;
+      }
+
+      // --- Forbidden topics ---
+      let forbiddenMatch: TopicMatch | null = null;
+
+      if (this.forbiddenIndex) {
+        const forbiddenMatches = this.forbiddenIndex.matchByVector(embedding);
+        allScores.push(...forbiddenMatches);
+
+        // Report the highest-scoring forbidden match if above threshold.
+        if (forbiddenMatches.length > 0 && forbiddenMatches[0].similarity > this.forbiddenThreshold) {
+          forbiddenMatch = forbiddenMatches[0];
+        }
+      }
+
+      // Sort all scores descending by similarity.
+      allScores.sort((a, b) => b.similarity - a.similarity);
+
+      return {
+        success: true,
+        output: {
+          onTopic,
+          nearestTopic,
+          forbiddenMatch,
+          allScores,
+        },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: `Topic check failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+}