@popcomputer/structured-chat 0.1.0

package/examples/answer-modes.ts

@@ -0,0 +1,92 @@
+import { Effect, Schema } from "effect"
+import {
+  Answer,
+  defineChat,
+  defineTool,
+  Question,
+  Stage,
+} from "@popcomputer/structured-chat"
+
+const SearchCatalog = defineTool({
+  name: "search_catalog",
+  description: "Search the catalog for relevant agency matches.",
+  input: Schema.Struct({ query: Schema.NonEmptyTrimmedString }),
+  execute: ({ query }) => Effect.succeed({ query }),
+})
+
+const Search = Stage.tools({
+  name: "search",
+  instructions: ["Search the catalog using the completed project brief."],
+  tools: [SearchCatalog],
+})
+
+const ProjectBrief = Stage.collect({
+  name: "project_brief",
+  questions: {
+    guidance: "Ask one concise, conversational question at a time.",
+    escape: "Not sure yet",
+  },
+  fields: {
+    priority: Answer.confirmed(Schema.NonEmptyTrimmedString, {
+      description: "Where the client most needs outside help.",
+      ask: Question.adaptiveChoice(
+        "Where could an agency make the biggest difference?",
+        {
+          minimumOptions: 2,
+          maximumOptions: 3,
+          fallbackOptions: [
+            "Launch or grow a product",
+            "Build the brand long term",
+            "Fix a performance problem",
+          ],
+        },
+      ),
+    }),
+    location: Answer.confirmed(Schema.NonEmptyTrimmedString, {
+      description: "Where the client is based.",
+      ask: Question.adaptive(
+        "Ask where the client is based and whether location matters.",
+        {
+          fallback: "Where are you based, and does location matter?",
+        },
+      ),
+    }),
+  },
+})
+
+/** A required ask-then-answer workflow before catalog search. */
+export const Matchmaker = defineChat({
+  name: "matchmaker",
+  version: 1,
+  stages: [ProjectBrief, Search],
+})
+
+const ProjectUnderstanding = Stage.collect({
+  name: "project_understanding",
+  fields: {
+    intent: Answer.semantic(Schema.NonEmptyTrimmedString, {
+      description:
+        "The client's searchable need, desired outcome, sector, or relevant experience.",
+      ask: Question.adaptive(
+        "Ask one useful follow-up only when the request is not searchable yet.",
+        {
+          fallback: "What outcome or experience should I search for?",
+        },
+      ),
+    }),
+  },
+})
+
+/** A chat that can infer a searchable intent from the opening request. */
+export const FreeformMatchmaker = defineChat({
+  name: "freeform_matchmaker",
+  version: 1,
+  stages: [ProjectUnderstanding, Search],
+})
+
+/** A chat whose catalog search tool is available on the opening turn. */
+export const OpenSearchChat = defineChat({
+  name: "open_search_chat",
+  version: 1,
+  stages: [Search],
+})

package/examples/prompt-injection-policy.ts

@@ -0,0 +1,66 @@
+import {
+  Context,
+  Effect,
+  Schema,
+} from "effect"
+import {
+  defineModelGuard,
+  defineTool,
+  Stage,
+  type ModelGuardCallContext,
+  type ModelGuardContext,
+} from "@popcomputer/structured-chat"
+
+/** Application policy rejection retained in the Effect error channel. */
+export class UnsafeConversation extends Schema.TaggedError<UnsafeConversation>()(
+  "UnsafeConversation",
+  { reason: Schema.Literal("prompt_injection") },
+) {}
+
+/**
+ * Application-owned classifier; production may use any local or remote
+ * policy.
+ */
+export class ConversationSafety extends Context.Tag(
+  "ConversationSafety",
+)<
+  ConversationSafety,
+  {
+    readonly checkConversation: (
+      context: ModelGuardContext,
+    ) => Effect.Effect<void, UnsafeConversation>
+    readonly checkCall: (
+      context: ModelGuardCallContext,
+    ) => Effect.Effect<void, UnsafeConversation>
+  }
+>() {}
+
+/** Effect-native guard composed into any model-backed stage. */
+export const PromptInjectionPolicy = defineModelGuard({
+  name: "prompt_injection_policy",
+  check: (context) =>
+    ConversationSafety.pipe(
+      Effect.flatMap((safety) =>
+        safety.checkConversation(context),
+      ),
+    ),
+  checkCall: (context) =>
+    ConversationSafety.pipe(
+      Effect.flatMap((safety) => safety.checkCall(context)),
+    ),
+})
+
+const SearchAgencies = defineTool({
+  name: "search_agencies",
+  description: "Find agencies relevant to the project brief.",
+  input: Schema.Struct({ query: Schema.NonEmptyTrimmedString }),
+  execute: ({ query }) => Effect.succeed({ query }),
+})
+
+/** Closed search stage protected by the application policy. */
+export const Matching = Stage.tools({
+  name: "matching",
+  instructions: ["Route the completed brief to one search."],
+  tools: [SearchAgencies],
+  guards: [PromptInjectionPolicy],
+})

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@popcomputer/structured-chat",
+  "version": "0.1.0",
+  "description": "Schema-defined structured chats with typed tools, stages, and UI views",
+  "type": "module",
+  "packageManager": "bun@1.3.1",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./assistant-ui": {
+      "types": "./dist/integrations/assistant-ui.d.ts",
+      "import": "./dist/integrations/assistant-ui.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node --input-type=module --eval \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\"",
+    "build": "bun run clean && tsc",
+    "check": "tsc --noEmit && tsc -p tsconfig.type-tests.json && tsc -p tsconfig.examples.json",
+    "lint": "oxlint .",
+    "test": "bun test",
+    "test:node": "bun run build && node tests/node-esm-smoke.mjs",
+    "test:package:types": "tsc -p tsconfig.package-tests.json",
+    "test:package": "bun run build && bun run test:package:types && node tests/node-esm-smoke.mjs && npm pack --dry-run --ignore-scripts --offline --cache node_modules/.cache/npm",
+    "test:types": "tsc -p tsconfig.type-tests.json",
+    "verify": "bun run lint && bun run check && bun test && bun run test:package",
+    "prepack": "bun run build",
+    "prepublishOnly": "bun run verify"
+  },
+  "keywords": [
+    "chat",
+    "assistant-ui",
+    "effect",
+    "effect-ts",
+    "popcomputer",
+    "structured-output",
+    "tool-calling",
+    "workflow"
+  ],
+  "author": "Patrick Ogilvie",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@assistant-ui/core": "^0.3.1",
+    "react": "^18.0.0 || ^19.0.0",
+    "effect": "^3.21.2"
+  },
+  "peerDependenciesMeta": {
+    "@assistant-ui/core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@assistant-ui/core": "0.3.13",
+    "@assistant-ui/react": "^0.15.1",
+    "@oxlint/plugins": "1.78.0",
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "effect": "3.21.2",
+    "oxlint": "1.78.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.9.3"
+  }
+}