@directive-run/knowledge 0.2.0

package/examples/topic-guard.ts

@@ -0,0 +1,306 @@
+// Example: topic-guard
+// Source: examples/topic-guard/src/topic-guard.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Topic Guard — Directive Module
+ *
+ * Demonstrates input guardrails for AI agents. Messages are checked against
+ * configurable guardrails before reaching the mock agent. Blocked messages
+ * are rejected with an explanation; allowed messages get a mock response.
+ */
+
+import { type ModuleSchema, createModule, t } from "@directive-run/core";
+import {
+  type GuardrailResult,
+  checkKeywordGuardrail,
+  checkTopicClassifier,
+  getMockAgentResponse,
+} from "./mock-guardrails.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ChatMessage {
+  role: "user" | "agent" | "system";
+  text: string;
+  blocked: boolean;
+  guardrail?: string;
+}
+
+export interface GuardrailLogEntry {
+  timestamp: number;
+  input: string;
+  result: GuardrailResult;
+}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const topicGuardSchema = {
+  facts: {
+    input: t.string(),
+    messages: t.object<ChatMessage[]>(),
+    isProcessing: t.boolean(),
+    lastGuardrailResult: t.object<GuardrailResult | null>(),
+    guardrailLog: t.object<GuardrailLogEntry[]>(),
+    allowedTopics: t.object<string[]>(),
+  },
+  derivations: {
+    messageCount: t.number(),
+    blockedCount: t.number(),
+    allowedCount: t.number(),
+    blockRate: t.string(),
+    canSend: t.boolean(),
+    lastMessageBlocked: t.boolean(),
+  },
+  events: {
+    send: {},
+    clear: {},
+    setInput: { value: t.string() },
+    toggleTopic: { topic: t.string() },
+  },
+  requirements: {
+    BLOCK_MESSAGE: {
+      reason: t.string(),
+      guardrailName: t.string(),
+    },
+    ALLOW_MESSAGE: {},
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export const topicGuardModule = createModule("topic-guard", {
+  schema: topicGuardSchema,
+
+  init: (facts) => {
+    facts.input = "";
+    facts.messages = [];
+    facts.isProcessing = false;
+    facts.lastGuardrailResult = null;
+    facts.guardrailLog = [];
+    facts.allowedTopics = ["product", "billing", "support", "technical"];
+  },
+
+  // ============================================================================
+  // Derivations
+  // ============================================================================
+
+  derive: {
+    messageCount: (facts) => {
+      return (facts.messages as ChatMessage[]).filter((m) => m.role === "user")
+        .length;
+    },
+
+    blockedCount: (facts) => {
+      return (facts.messages as ChatMessage[]).filter(
+        (m) => m.role === "user" && m.blocked,
+      ).length;
+    },
+
+    allowedCount: (facts) => {
+      return (facts.messages as ChatMessage[]).filter(
+        (m) => m.role === "user" && !m.blocked,
+      ).length;
+    },
+
+    blockRate: (facts, derive) => {
+      const total = derive.messageCount as number;
+      if (total === 0) {
+        return "0%";
+      }
+      const blocked = derive.blockedCount as number;
+      const rate = Math.round((blocked / total) * 100);
+
+      return `${rate}%`;
+    },
+
+    canSend: (facts) => {
+      return (
+        (facts.input as string).trim().length > 0 &&
+        !(facts.isProcessing as boolean)
+      );
+    },
+
+    lastMessageBlocked: (facts) => {
+      const msgs = facts.messages as ChatMessage[];
+      if (msgs.length === 0) {
+        return false;
+      }
+
+      return msgs[msgs.length - 1].blocked;
+    },
+  },
+
+  // ============================================================================
+  // Events
+  // ============================================================================
+
+  events: {
+    send: (facts) => {
+      const text = (facts.input as string).trim();
+      if (text.length === 0 || facts.isProcessing) {
+        return;
+      }
+
+      // Add user message
+      const messages = [...(facts.messages as ChatMessage[])];
+      messages.push({ role: "user", text, blocked: false });
+      facts.messages = messages;
+
+      // Run guardrails
+      const keywordResult = checkKeywordGuardrail(text);
+      if (keywordResult.blocked) {
+        facts.lastGuardrailResult = keywordResult;
+        facts.isProcessing = true;
+        facts.input = "";
+
+        return;
+      }
+
+      const classifierResult = checkTopicClassifier(
+        text,
+        facts.allowedTopics as string[],
+      );
+      facts.lastGuardrailResult = classifierResult;
+      facts.isProcessing = true;
+      facts.input = "";
+    },
+
+    clear: (facts) => {
+      facts.messages = [];
+      facts.guardrailLog = [];
+      facts.lastGuardrailResult = null;
+      facts.isProcessing = false;
+    },
+
+    setInput: (facts, { value }) => {
+      facts.input = value;
+    },
+
+    toggleTopic: (facts, { topic }) => {
+      const topics = [...(facts.allowedTopics as string[])];
+      const idx = topics.indexOf(topic);
+      if (idx >= 0) {
+        topics.splice(idx, 1);
+      } else {
+        topics.push(topic);
+      }
+      facts.allowedTopics = topics;
+    },
+  },
+
+  // ============================================================================
+  // Constraints
+  // ============================================================================
+
+  constraints: {
+    offTopicDetected: {
+      priority: 100,
+      when: (facts) => {
+        const result = facts.lastGuardrailResult as GuardrailResult | null;
+
+        return result?.blocked === true && (facts.isProcessing as boolean);
+      },
+      require: (facts) => {
+        const result = facts.lastGuardrailResult as GuardrailResult;
+
+        return {
+          type: "BLOCK_MESSAGE",
+          reason: result.reason,
+          guardrailName: result.guardrailName,
+        };
+      },
+    },
+
+    onTopicConfirmed: {
+      priority: 90,
+      when: (facts) => {
+        const result = facts.lastGuardrailResult as GuardrailResult | null;
+
+        return result?.blocked === false && (facts.isProcessing as boolean);
+      },
+      require: () => ({
+        type: "ALLOW_MESSAGE",
+      }),
+    },
+  },
+
+  // ============================================================================
+  // Resolvers
+  // ============================================================================
+
+  resolvers: {
+    blockMessage: {
+      requirement: "BLOCK_MESSAGE",
+      resolve: async (req, context) => {
+        const messages = [...(context.facts.messages as ChatMessage[])];
+        // Mark the last user message as blocked
+        const lastUserIdx = messages.length - 1;
+        if (lastUserIdx >= 0) {
+          messages[lastUserIdx] = {
+            ...messages[lastUserIdx],
+            blocked: true,
+            guardrail: req.guardrailName,
+          };
+        }
+        // Add system rejection message
+        messages.push({
+          role: "system",
+          text: "I can only help with product-related questions.",
+          blocked: true,
+          guardrail: req.guardrailName,
+        });
+        context.facts.messages = messages;
+        context.facts.isProcessing = false;
+      },
+    },
+
+    allowMessage: {
+      requirement: "ALLOW_MESSAGE",
+      resolve: async (_req, context) => {
+        const messages = [...(context.facts.messages as ChatMessage[])];
+        const lastUserMsg = messages.filter((m) => m.role === "user").pop();
+        const responseText = getMockAgentResponse(lastUserMsg?.text ?? "");
+        messages.push({
+          role: "agent",
+          text: responseText,
+          blocked: false,
+        });
+        context.facts.messages = messages;
+        context.facts.isProcessing = false;
+      },
+    },
+  },
+
+  // ============================================================================
+  // Effects
+  // ============================================================================
+
+  effects: {
+    logGuardrailResult: {
+      deps: ["lastGuardrailResult"],
+      run: (facts) => {
+        const result = facts.lastGuardrailResult as GuardrailResult | null;
+        if (!result) {
+          return;
+        }
+
+        const msgs = facts.messages as ChatMessage[];
+        const lastUserMsg = [...msgs].reverse().find((m) => m.role === "user");
+        const log = [...(facts.guardrailLog as GuardrailLogEntry[])];
+        log.push({
+          timestamp: Date.now(),
+          input: lastUserMsg?.text ?? "",
+          result,
+        });
+        facts.guardrailLog = log;
+      },
+    },
+  },
+});

package/examples/url-sync.ts

@@ -0,0 +1,333 @@
+// Example: url-sync
+// Source: examples/url-sync/src/url-sync.ts
+// Pure module file — no DOM wiring
+
+/**
+ * URL Sync — Directive Modules
+ *
+ * Two modules that synchronize URL query parameters with product filtering:
+ * - **url module**: Reads/writes URL params, dispatches filter changes
+ * - **products module**: Fetches filtered products via cross-module constraints
+ *
+ * Demonstrates bidirectional URL sync (popstate ↔ replaceState), cross-module
+ * constraints, and resolver-driven data fetching with mock delay.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+import { type Product, allProducts, filterProducts } from "./mock-products.js";
+
+// ============================================================================
+// URL Module — Schema
+// ============================================================================
+
+export const urlSchema = {
+  facts: {
+    search: t.string(),
+    category: t.string(),
+    sortBy: t.string<"newest" | "price-asc" | "price-desc">(),
+    page: t.number(),
+    syncingFromUrl: t.boolean(),
+  },
+  derivations: {},
+  events: {
+    setSearch: { value: t.string() },
+    setCategory: { value: t.string() },
+    setSortBy: { value: t.string() },
+    setPage: { value: t.number() },
+    syncFromUrl: {
+      search: t.string(),
+      category: t.string(),
+      sortBy: t.string(),
+      page: t.number(),
+    },
+    syncComplete: {},
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+// ============================================================================
+// URL Module — Helpers
+// ============================================================================
+
+function readUrlParams(): {
+  search: string;
+  category: string;
+  sortBy: string;
+  page: number;
+} {
+  const params = new URLSearchParams(window.location.search);
+
+  return {
+    search: params.get("q") ?? "",
+    category: params.get("cat") ?? "",
+    sortBy: params.get("sort") ?? "newest",
+    page: Math.max(1, Number.parseInt(params.get("page") ?? "1", 10) || 1),
+  };
+}
+
+// ============================================================================
+// URL Module
+// ============================================================================
+
+export const urlModule = createModule("url", {
+  schema: urlSchema,
+
+  init: (facts) => {
+    const params = readUrlParams();
+    facts.search = params.search;
+    facts.category = params.category;
+    facts.sortBy = params.sortBy;
+    facts.page = params.page;
+    facts.syncingFromUrl = false;
+  },
+
+  // ============================================================================
+  // Events
+  // ============================================================================
+
+  events: {
+    setSearch: (facts, { value }) => {
+      facts.search = value;
+      facts.page = 1;
+    },
+
+    setCategory: (facts, { value }) => {
+      facts.category = value;
+      facts.page = 1;
+    },
+
+    setSortBy: (facts, { value }) => {
+      facts.sortBy = value;
+      facts.page = 1;
+    },
+
+    setPage: (facts, { value }) => {
+      facts.page = value;
+    },
+
+    syncFromUrl: (facts, { search, category, sortBy, page }) => {
+      facts.syncingFromUrl = true;
+      facts.search = search;
+      facts.category = category;
+      facts.sortBy = sortBy;
+      facts.page = page;
+    },
+
+    syncComplete: (facts) => {
+      facts.syncingFromUrl = false;
+    },
+  },
+
+  // ============================================================================
+  // Effects
+  // ============================================================================
+
+  effects: {
+    urlToState: {
+      run: () => {
+        const handler = () => {
+          const params = readUrlParams();
+          system.events.url.syncFromUrl({
+            search: params.search,
+            category: params.category,
+            sortBy: params.sortBy,
+            page: params.page,
+          });
+          system.events.url.syncComplete();
+        };
+
+        window.addEventListener("popstate", handler);
+
+        return () => {
+          window.removeEventListener("popstate", handler);
+        };
+      },
+    },
+
+    stateToUrl: {
+      deps: ["search", "category", "sortBy", "page"],
+      run: (facts) => {
+        if (facts.syncingFromUrl) {
+          return;
+        }
+
+        const params = new URLSearchParams();
+
+        if (facts.search !== "") {
+          params.set("q", facts.search as string);
+        }
+        if (facts.category !== "" && facts.category !== "all") {
+          params.set("cat", facts.category as string);
+        }
+        if (facts.sortBy !== "newest") {
+          params.set("sort", facts.sortBy as string);
+        }
+        if ((facts.page as number) > 1) {
+          params.set("page", String(facts.page));
+        }
+
+        const search = params.toString();
+        const newUrl = search
+          ? `${window.location.pathname}?${search}`
+          : window.location.pathname;
+
+        if (newUrl !== `${window.location.pathname}${window.location.search}`) {
+          history.replaceState(null, "", newUrl);
+        }
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Products Module — Schema
+// ============================================================================
+
+export const productsSchema = {
+  facts: {
+    items: t.object<Product[]>(),
+    totalItems: t.number(),
+    isLoading: t.boolean(),
+    itemsPerPage: t.number(),
+  },
+  derivations: {
+    totalPages: t.number(),
+    currentPageDisplay: t.string(),
+  },
+  events: {
+    setItemsPerPage: { value: t.number() },
+  },
+  requirements: {
+    FETCH_PRODUCTS: {
+      search: t.string(),
+      category: t.string(),
+      sortBy: t.string(),
+      page: t.number(),
+      itemsPerPage: t.number(),
+    },
+  },
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Products Module
+// ============================================================================
+
+export const productsModule = createModule("products", {
+  schema: productsSchema,
+
+  crossModuleDeps: { url: urlSchema },
+
+  init: (facts) => {
+    facts.items = [];
+    facts.totalItems = 0;
+    facts.isLoading = false;
+    facts.itemsPerPage = 10;
+  },
+
+  // ============================================================================
+  // Derivations
+  // ============================================================================
+
+  derive: {
+    totalPages: (facts) => {
+      if (facts.self.totalItems === 0) {
+        return 0;
+      }
+
+      return Math.ceil(facts.self.totalItems / facts.self.itemsPerPage);
+    },
+
+    currentPageDisplay: (facts) => {
+      const total = facts.self.totalItems;
+      if (total === 0) {
+        return "No results";
+      }
+
+      const page = facts.url.page;
+      const perPage = facts.self.itemsPerPage;
+      const start = (page - 1) * perPage + 1;
+      const end = Math.min(page * perPage, total);
+
+      return `${start}\u2013${end} of ${total}`;
+    },
+  },
+
+  // ============================================================================
+  // Events
+  // ============================================================================
+
+  events: {
+    setItemsPerPage: (facts, { value }) => {
+      facts.itemsPerPage = value;
+    },
+  },
+
+  // ============================================================================
+  // Constraints
+  // ============================================================================
+
+  constraints: {
+    fetchProducts: {
+      priority: 100,
+      when: () => true,
+      require: (facts) => ({
+        type: "FETCH_PRODUCTS",
+        search: facts.url.search,
+        category: facts.url.category,
+        sortBy: facts.url.sortBy,
+        page: facts.url.page,
+        itemsPerPage: facts.self.itemsPerPage,
+      }),
+    },
+  },
+
+  // ============================================================================
+  // Resolvers
+  // ============================================================================
+
+  resolvers: {
+    fetchProducts: {
+      requirement: "FETCH_PRODUCTS",
+      key: (req) =>
+        `fetch-${req.search}-${req.category}-${req.sortBy}-${req.page}-${req.itemsPerPage}`,
+      timeout: 10000,
+      resolve: async (req, context) => {
+        context.facts.isLoading = true;
+
+        // Simulate network delay
+        await new Promise((resolve) => setTimeout(resolve, 300));
+
+        const result = filterProducts(allProducts, {
+          search: req.search,
+          category: req.category,
+          sortBy: req.sortBy,
+          page: req.page,
+          itemsPerPage: req.itemsPerPage,
+        });
+
+        context.facts.items = result.items;
+        context.facts.totalItems = result.totalItems;
+        context.facts.isLoading = false;
+      },
+    },
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+export const system = createSystem({
+  modules: {
+    url: urlModule,
+    products: productsModule,
+  },
+  debug: { runHistory: true },
+  plugins: [devtoolsPlugin({ name: "url-sync" })],
+});