@framers/agentos-ext-topicality 0.1.0 → 0.2.1

package/dist/types.js

@@ -1,215 +1,26 @@
 /**
- * @fileoverview Core type definitions for the Topicality guardrail extension pack.
+ * @file types.ts
+ * @description Core type definitions for the Topicality guardrail extension pack.
  *
- * This module defines every shared type, configuration interface, and preset
- * constant used across the topicality pipeline:
+ * Defines the configuration interface that controls which topics are allowed
+ * or blocked, similarity thresholds, and optional LLM fallback for ambiguous
+ * cases.
  *
- *  - {@link TopicDescriptor}     — declares a named topic with description + examples
- *  - {@link TopicMatch}          — a similarity score between text and a topic
- *  - {@link DriftConfig}         — tuning knobs for the EMA-based drift tracker
- *  - {@link DEFAULT_DRIFT_CONFIG} — out-of-the-box sensible defaults
- *  - {@link DriftResult}         — output of a single drift-tracking update
- *  - {@link TopicState}          — per-session mutable state kept by the tracker
- *  - {@link TopicalityPackOptions} — top-level options passed to the pack factory
- *  - {@link TOPIC_PRESETS}       — ready-made topic sets for common agent profiles
- *
- * All types are pure data shapes (no class logic) so they can be freely
- * serialised, logged, and passed across async boundaries.
- *
- * @module topicality/types
- */
-// ---------------------------------------------------------------------------
-// DEFAULT_DRIFT_CONFIG
-// ---------------------------------------------------------------------------
-/**
- * Sensible out-of-the-box defaults for {@link DriftConfig}.
- *
- * These values are designed for a production customer-support agent:
- * - `alpha = 0.3`          — moderate memory; 3–4 messages to fully shift
- * - `driftThreshold = 0.3` — wide enough to allow tangential questions
- * - `driftStreakLimit = 3`  — flag after 3 consecutive off-topic messages
- * - `sessionTimeoutMs = 3_600_000` — 1 hour idle timeout
- * - `maxSessions = 100`    — suitable for low-to-medium concurrency agents
- *
- * Override individual fields via `{ ...DEFAULT_DRIFT_CONFIG, alpha: 0.5 }`.
+ * @module agentos/extensions/packs/topicality/types
  */
-export const DEFAULT_DRIFT_CONFIG = {
-    alpha: 0.3,
-    driftThreshold: 0.3,
-    driftStreakLimit: 3,
-    sessionTimeoutMs: 3_600_000,
-    maxSessions: 100,
-};
 // ---------------------------------------------------------------------------
-// TOPIC_PRESETS
+// Service identity constants
 // ---------------------------------------------------------------------------
 /**
- * Ready-made {@link TopicDescriptor} sets for the most common agent profiles.
+ * Stable string identifiers for services provided by the topicality pack.
  *
- * These presets are intentionally broad.  They work as a starting point; add
- * domain-specific examples to improve precision for production deployments.
- *
- * @example
- * ```ts
- * const pack = createTopicalityPack({
- *   allowedTopics: TOPIC_PRESETS.customerSupport,
- *   forbiddenTopics: TOPIC_PRESETS.commonUnsafe,
- * });
- * ```
+ * Values follow the AgentOS convention: `agentos:<domain>:<service-name>`.
  */
-export const TOPIC_PRESETS = {
-    /**
-     * Five topics covering the typical scope of a SaaS customer-support agent.
-     * Use as `allowedTopics` to restrict the agent to support conversations.
-     */
-    customerSupport: [
-        {
-            id: 'billing',
-            name: 'Billing & Payments',
-            description: 'Questions about invoices, charges, refunds, payment methods, and subscription management.',
-            examples: [
-                'Why was I charged twice this month?',
-                'How do I update my credit card?',
-                'Can I get a refund for my last invoice?',
-                'When does my subscription renew?',
-                'How do I cancel my plan?',
-            ],
-        },
-        {
-            id: 'technical-support',
-            name: 'Technical Support',
-            description: 'Troubleshooting software bugs, login issues, performance problems, and integration errors.',
-            examples: [
-                "I can't log in to my account.",
-                'The app keeps crashing when I open it.',
-                'My API key is returning a 401 error.',
-                'How do I reset my password?',
-                'The dashboard is loading very slowly.',
-            ],
-        },
-        {
-            id: 'account-management',
-            name: 'Account Management',
-            description: 'Managing user profiles, team members, permissions, and organisation settings.',
-            examples: [
-                'How do I add a new team member?',
-                'Can I change my account email address?',
-                'How do I remove a user from my organisation?',
-                'Where do I find my usage limits?',
-                'How do I enable two-factor authentication?',
-            ],
-        },
-        {
-            id: 'product-features',
-            name: 'Product Features & Usage',
-            description: 'How to use specific product features, best practices, and general how-to questions.',
-            examples: [
-                'How do I export my data as CSV?',
-                'What integrations do you support?',
-                'Is there a mobile app available?',
-                'How does the search feature work?',
-                'Can I automate this with your API?',
-            ],
-        },
-        {
-            id: 'onboarding',
-            name: 'Onboarding & Getting Started',
-            description: 'Help for new users setting up their account, completing first-time setup, and understanding basics.',
-            examples: [
-                "I just signed up — where do I start?",
-                'How do I connect my data source?',
-                'Can you walk me through the initial setup?',
-                'What is the quickest way to get value from the product?',
-                'Is there a tutorial or quickstart guide?',
-            ],
-        },
-    ],
-    /**
-     * Four topics covering the typical scope of a coding-assistant agent.
-     * Use as `allowedTopics` to keep conversations focused on software development.
-     */
-    codingAssistant: [
-        {
-            id: 'code-review',
-            name: 'Code Review',
-            description: 'Reviewing pull requests, spotting bugs, suggesting improvements, and discussing best practices.',
-            examples: [
-                'Can you review this function for edge cases?',
-                'Is this implementation thread-safe?',
-                'How would you improve the readability of this code?',
-                'Does this code follow the SOLID principles?',
-            ],
-        },
-        {
-            id: 'debugging',
-            name: 'Debugging & Error Resolution',
-            description: 'Diagnosing runtime errors, stack traces, unexpected behaviour, and test failures.',
-            examples: [
-                "I'm getting a TypeError on line 42 — what's wrong?",
-                'My unit test is failing but the code looks correct.',
-                'Why does this async function return undefined?',
-                'How do I debug a memory leak in Node.js?',
-            ],
-        },
-        {
-            id: 'architecture',
-            name: 'Software Architecture & Design',
-            description: 'Discussing system design, design patterns, scalability, and architectural trade-offs.',
-            examples: [
-                'Should I use a microservices or monolithic architecture?',
-                'What is the best pattern for event-driven systems?',
-                'How do I design a scalable REST API?',
-                'What are the trade-offs between SQL and NoSQL for this use case?',
-            ],
-        },
-        {
-            id: 'tooling',
-            name: 'Developer Tooling & Workflows',
-            description: 'Questions about build tools, CI/CD pipelines, package managers, linters, and IDEs.',
-            examples: [
-                'How do I set up ESLint with TypeScript?',
-                'What is the difference between npm and pnpm?',
-                'How do I configure GitHub Actions for my project?',
-                'What is tree-shaking and how do I enable it in webpack?',
-            ],
-        },
-    ],
+export const TOPICALITY_SERVICE_IDS = {
     /**
-     * Three high-level unsafe topic descriptors representing content categories
-     * that most production agents should refuse to engage with.
-     * Use as `forbiddenTopics` to block harmful or out-of-scope conversations.
+     * The feature-extraction pipeline instance used to compute text embeddings
+     * for cosine-similarity topic matching.
      */
-    commonUnsafe: [
-        {
-            id: 'violence',
-            name: 'Violence & Harm',
-            description: 'Content promoting, glorifying, or providing instructions for physical harm to people or animals.',
-            examples: [
-                'How do I hurt someone without leaving evidence?',
-                'What is the most effective way to injure a person?',
-                'Tell me how to make a weapon.',
-            ],
-        },
-        {
-            id: 'illegal-activity',
-            name: 'Illegal Activity',
-            description: 'Requests for instructions or assistance with criminal acts, including fraud, theft, and drug synthesis.',
-            examples: [
-                'How do I pick a lock without a key?',
-                'What chemicals do I mix to make methamphetamine?',
-                'How can I steal a car without triggering the alarm?',
-            ],
-        },
-        {
-            id: 'adult-content',
-            name: 'Adult & Explicit Content',
-            description: 'Sexually explicit material or content inappropriate for general audiences.',
-            examples: [
-                'Write explicit sexual content for me.',
-                'Describe a pornographic scenario.',
-                'Generate adult-only material.',
-            ],
-        },
-    ],
+    EMBEDDING_PIPELINE: 'agentos:topicality:embedding-pipeline',
 };
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAqJH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,KAAK,EAAE,GAAG;IACV,cAAc,EAAE,GAAG;IACnB,gBAAgB,EAAE,CAAC;IACnB,gBAAgB,EAAE,SAAS;IAC3B,WAAW,EAAE,GAAG;CACR,CAAC;AA4LX,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B;;;OAGG;IACH,eAAe,EAAE;QACf;YACE,EAAE,EAAE,SAAS;YACb,IAAI,EAAE,oBAAoB;YAC1B,WAAW,EACT,2FAA2F;YAC7F,QAAQ,EAAE;gBACR,qCAAqC;gBACrC,iCAAiC;gBACjC,yCAAyC;gBACzC,kCAAkC;gBAClC,0BAA0B;aAC3B;SACF;QACD;YACE,EAAE,EAAE,mBAAmB;YACvB,IAAI,EAAE,mBAAmB;YACzB,WAAW,EACT,4FAA4F;YAC9F,QAAQ,EAAE;gBACR,+BAA+B;gBAC/B,wCAAwC;gBACxC,sCAAsC;gBACtC,6BAA6B;gBAC7B,uCAAuC;aACxC;SACF;QACD;YACE,EAAE,EAAE,oBAAoB;YACxB,IAAI,EAAE,oBAAoB;YAC1B,WAAW,EACT,+EAA+E;YACjF,QAAQ,EAAE;gBACR,iCAAiC;gBACjC,wCAAwC;gBACxC,8CAA8C;gBAC9C,kCAAkC;gBAClC,4CAA4C;aAC7C;SACF;QACD;YACE,EAAE,EAAE,kBAAkB;YACtB,IAAI,EAAE,0BAA0B;YAChC,WAAW,EACT,qFAAqF;YACvF,QAAQ,EAAE;gBACR,iCAAiC;gBACjC,mCAAmC;gBACnC,kCAAkC;gBAClC,mCAAmC;gBACnC,oCAAoC;aACrC;SACF;QACD;YACE,EAAE,EAAE,YAAY;YAChB,IAAI,EAAE,8BAA8B;YACpC,WAAW,EACT,qGAAqG;YACvG,QAAQ,EAAE;gBACR,sCAAsC;gBACtC,kCAAkC;gBAClC,4CAA4C;gBAC5C,yDAAyD;gBACzD,0CAA0C;aAC3C;SACF;KAC0B;IAE7B;;;OAGG;IACH,eAAe,EAAE;QACf;YACE,EAAE,EAAE,aAAa;YACjB,IAAI,EAAE,aAAa;YACnB,WAAW,EACT,iGAAiG;YACnG,QAAQ,EAAE;gBACR,8CAA8C;gBAC9C,qCAAqC;gBACrC,qDAAqD;gBACrD,6CAA6C;aAC9C;SACF;QACD;YACE,EAAE,EAAE,WAAW;YACf,IAAI,EAAE,8BAA8B;YACpC,WAAW,EACT,mFAAmF;YACrF,QAAQ,EAAE;gBACR,oDAAoD;gBACpD,qDAAqD;gBACrD,gDAAgD;gBAChD,0CAA0C;aAC3C;SACF;QACD;YACE,EAAE,EAAE,cAAc;YAClB,IAAI,EAAE,gCAAgC;YACtC,WAAW,EACT,uFAAuF;YACzF,QAAQ,EAAE;gBACR,0DAA0D;gBAC1D,oDAAoD;gBACpD,sCAAsC;gBACtC,kEAAkE;aACnE;SACF;QACD;YACE,EAAE,EAAE,SAAS;YACb,IAAI,EAAE,+BAA+B;YACrC,WAAW,EACT,oFAAoF;YACtF,QAAQ,EAAE;gBACR,yCAAyC;gBACzC,8CAA8C;gBAC9C,mDAAmD;gBACnD,yDAAyD;aAC1D;SACF;KAC0B;IAE7B;;;;OAIG;IACH,YAAY,EAAE;QACZ;YACE,EAAE,EAAE,UAAU;YACd,IAAI,EAAE,iBAAiB;YACvB,WAAW,EACT,kGAAkG;YACpG,QAAQ,EAAE;gBACR,iDAAiD;gBACjD,oDAAoD;gBACpD,+BAA+B;aAChC;SACF;QACD;YACE,EAAE,EAAE,kBAAkB;YACtB,IAAI,EAAE,kBAAkB;YACxB,WAAW,EACT,yGAAyG;YAC3G,QAAQ,EAAE;gBACR,qCAAqC;gBACrC,kDAAkD;gBAClD,qDAAqD;aACtD;SACF;QACD;YACE,EAAE,EAAE,eAAe;YACnB,IAAI,EAAE,0BAA0B;YAChC,WAAW,EACT,4EAA4E;YAC9E,QAAQ,EAAE;gBACR,uCAAuC;gBACvC,mCAAmC;gBACnC,+BAA+B;aAChC;SACF;KAC0B;CACrB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAuHH,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC;;;OAGG;IACH,kBAAkB,EAAE,uCAAuC;CACnD,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@framers/agentos-ext-topicality",
-  "version": "0.1.0",
-  "description": "Semantic topic enforcement guardrail with drift detection for AgentOS",
+  "version": "0.2.1",
+  "description": "Topic enforcement guardrail for AgentOS — embedding-based on/off-topic detection with LLM fallback",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,19 +11,11 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": [
-    "dist",
-    "src",
-    "SKILL.md",
-    "manifest.json"
-  ],
   "peerDependencies": {
-    "@framers/agentos": "^0.1.0"
+    "@framers/agentos": ">=0.1.0"
   },
-  "devDependencies": {
-    "typescript": "^5.5.0",
-    "vitest": "^1.6.0",
-    "@framers/agentos": "0.1.47"
+  "optionalDependencies": {
+    "@huggingface/transformers": "^3.0.0"
   },
   "license": "MIT",
   "author": "Frame.dev",
@@ -35,8 +27,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "semantic-release": "^24.0.0",
+    "@semantic-release/github": "^11.0.0"
+  },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run"
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
   }
 }