@popcomputer/structured-chat 0.1.0 → 0.2.0-rc.0

package/examples/answer-modes.ts

@@ -9,84 +9,95 @@ import {
 
 const SearchCatalog = defineTool({
   name: "search_catalog",
-  description: "Search the catalog for relevant agency matches.",
-  input: Schema.Struct({ query: Schema.NonEmptyTrimmedString }),
+  description: "Search the catalog for relevant resources.",
+  input: Schema.Struct({
+    query: Schema.Trimmed.check(Schema.isNonEmpty()),
+  }),
   execute: ({ query }) => Effect.succeed({ query }),
 })
 
 const Search = Stage.tools({
   name: "search",
-  instructions: ["Search the catalog using the completed project brief."],
+  instructions: ["Search the catalog using the completed request details."],
   tools: [SearchCatalog],
 })
 
-const ProjectBrief = Stage.collect({
-  name: "project_brief",
+const RequestDetails = Stage.collect({
+  name: "request_details",
   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?",
-        },
-      ),
-    }),
+    goal: Answer.confirmed(
+      Schema.Trimmed.check(Schema.isNonEmpty()),
+      {
+        description: "The outcome the user wants to achieve.",
+        ask: Question.adaptiveChoice(
+          "What would you like help accomplishing?",
+          {
+            minimumOptions: 2,
+            maximumOptions: 3,
+            fallbackOptions: [
+              "Understand a topic",
+              "Compare available options",
+              "Plan the next steps",
+            ],
+          },
+        ),
+      },
+    ),
+    audience: Answer.confirmed(
+      Schema.Trimmed.check(Schema.isNonEmpty()),
+      {
+        description: "Who the requested result is for.",
+        ask: Question.adaptive(
+          "Ask who will use the result and what they already know.",
+          {
+            fallback: "Who is this for, and what do they already know?",
+          },
+        ),
+      },
+    ),
   },
 })
 
 /** A required ask-then-answer workflow before catalog search. */
-export const Matchmaker = defineChat({
-  name: "matchmaker",
+export const GuidedResourceFinder = defineChat({
+  name: "guided_resource_finder",
   version: 1,
-  stages: [ProjectBrief, Search],
+  stages: [RequestDetails, Search],
 })
 
-const ProjectUnderstanding = Stage.collect({
-  name: "project_understanding",
+const RequestUnderstanding = Stage.collect({
+  name: "request_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?",
-        },
-      ),
-    }),
+    intent: Answer.semantic(
+      Schema.Trimmed.check(Schema.isNonEmpty()),
+      {
+        description:
+          "The user's searchable goal, subject, constraints, or desired outcome.",
+        ask: Question.adaptive(
+          "Ask one useful follow-up only when the request is not searchable yet.",
+          {
+            fallback: "What subject or outcome should I search for?",
+          },
+        ),
+      },
+    ),
   },
 })
 
 /** A chat that can infer a searchable intent from the opening request. */
-export const FreeformMatchmaker = defineChat({
-  name: "freeform_matchmaker",
+export const FreeformResourceFinder = defineChat({
+  name: "freeform_resource_finder",
   version: 1,
-  stages: [ProjectUnderstanding, Search],
+  stages: [RequestUnderstanding, Search],
 })
 
 /** A chat whose catalog search tool is available on the opening turn. */
-export const OpenSearchChat = defineChat({
-  name: "open_search_chat",
+export const OpenResourceSearch = defineChat({
+  name: "open_resource_search",
   version: 1,
   stages: [Search],
 })

package/examples/prompt-injection-policy.ts

@@ -21,9 +21,7 @@ export class UnsafeConversation extends Schema.TaggedError<UnsafeConversation>()
  * Application-owned classifier; production may use any local or remote
  * policy.
  */
-export class ConversationSafety extends Context.Tag(
-  "ConversationSafety",
-)<
+export class ConversationSafety extends Context.Service<
   ConversationSafety,
   {
     readonly checkConversation: (
@@ -33,34 +31,36 @@ export class ConversationSafety extends Context.Tag(
       context: ModelGuardCallContext,
     ) => Effect.Effect<void, UnsafeConversation>
   }
->() {}
+>()("ConversationSafety") {}
 
 /** 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),
-      ),
-    ),
+    Effect.gen(function* () {
+      const safety = yield* ConversationSafety
+      return yield* safety.checkConversation(context)
+    }),
   checkCall: (context) =>
-    ConversationSafety.pipe(
-      Effect.flatMap((safety) => safety.checkCall(context)),
-    ),
+    Effect.gen(function* () {
+      const safety = yield* ConversationSafety
+      return yield* safety.checkCall(context)
+    }),
 })
 
-const SearchAgencies = defineTool({
-  name: "search_agencies",
-  description: "Find agencies relevant to the project brief.",
-  input: Schema.Struct({ query: Schema.NonEmptyTrimmedString }),
+const FindResources = defineTool({
+  name: "find_resources",
+  description: "Find resources relevant to the request.",
+  input: Schema.Struct({
+    query: Schema.Trimmed.check(Schema.isNonEmpty()),
+  }),
   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],
+export const Lookup = Stage.tools({
+  name: "lookup",
+  instructions: ["Route the completed request to one resource lookup."],
+  tools: [FindResources],
   guards: [PromptInjectionPolicy],
 })

package/examples/resource-search.ts

@@ -0,0 +1,104 @@
+import {
+  Context,
+  Effect,
+  Layer,
+  Schema,
+} from "effect"
+import {
+  defineTool,
+  defineView,
+  Message,
+  Stage,
+  Tool,
+} from "@popcomputer/structured-chat"
+
+interface ResourceMatch {
+  readonly id: string
+  readonly title: string
+  readonly summary: string
+  readonly internalScore: number
+  readonly retrievedText: string
+}
+
+class ResourceCatalog extends Context.Service<
+  ResourceCatalog,
+  {
+    readonly search: (
+      query: string,
+    ) => Effect.Effect<ReadonlyArray<ResourceMatch>>
+  }
+>()("ResourceCatalog") {}
+
+const ResultCards = defineView({
+  name: "result_cards",
+  version: 1,
+  schema: Schema.Struct({
+    results: Schema.Array(
+      Schema.Struct({
+        id: Schema.String,
+        title: Schema.String,
+        summary: Schema.String,
+      }),
+    ),
+  }),
+})
+
+const ResourceEvidence = Schema.Struct({
+  matches: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      summary: Schema.String,
+    }),
+  ),
+})
+
+export const FindResources = defineTool({
+  name: "find_resources",
+  description: "Find resources relevant to the request.",
+  input: Schema.Struct({
+    query: Schema.Trimmed.check(Schema.isNonEmpty()),
+  }),
+  execute: ({ query }) =>
+    Effect.gen(function* () {
+      const catalog = yield* ResourceCatalog
+      return yield* catalog.search(query)
+    }),
+}).pipe(
+  Tool.modelResult(ResourceEvidence, (matches) => ({
+    matches: matches.map(({ id, summary }) => ({ id, summary })),
+  })),
+  Tool.present(ResultCards, (matches) => ({
+    results: matches.map(({ id, title, summary }) => ({
+      id,
+      title,
+      summary,
+    })),
+  })),
+)
+
+export const Lookup = Stage.tools({
+  name: "lookup",
+  instructions: ["Route the completed request to one resource lookup."],
+  tools: [FindResources],
+})
+
+const ResourceCatalogLive = Layer.succeed(ResourceCatalog, {
+  search: () =>
+    Effect.succeed([
+      {
+        id: "resource:1",
+        title: "Onboarding checklist",
+        summary: "A concise sequence of practical onboarding steps.",
+        internalScore: 0.93,
+        retrievedText: "Untrusted source text remains server-side.",
+      },
+    ]),
+})
+
+export const example = FindResources.execute({
+  query: "A practical onboarding guide",
+}).pipe(Effect.provide(ResourceCatalogLive))
+
+export const stageExample = Lookup.run([
+  Message.user("We need a practical onboarding guide."),
+])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcomputer/structured-chat",
-  "version": "0.1.0",
+  "version": "0.2.0-rc.0",
   "description": "Schema-defined structured chats with typed tools, stages, and UI views",
   "type": "module",
   "packageManager": "bun@1.3.1",
@@ -57,13 +57,21 @@
   ],
   "author": "Patrick Ogilvie",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PatrickOgilvie/popcomputer-structured-chat.git"
+  },
+  "homepage": "https://github.com/PatrickOgilvie/popcomputer-structured-chat#readme",
+  "bugs": {
+    "url": "https://github.com/PatrickOgilvie/popcomputer-structured-chat/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
     "@assistant-ui/core": "^0.3.1",
     "react": "^18.0.0 || ^19.0.0",
-    "effect": "^3.21.2"
+    "effect": "^4.0.0-rc.109"
   },
   "peerDependenciesMeta": {
     "@assistant-ui/core": {
@@ -80,7 +88,7 @@
     "@types/bun": "^1.3.14",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "effect": "3.21.2",
+    "effect": "4.0.0-rc.109",
     "oxlint": "1.78.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

package/examples/agency-search.ts

@@ -1,101 +0,0 @@
-import {
-  Context,
-  Effect,
-  Layer,
-  Schema,
-} from "effect"
-import {
-  defineTool,
-  defineView,
-  Message,
-  Stage,
-  Tool,
-} from "@popcomputer/structured-chat"
-
-interface AgencyMatch {
-  readonly id: string
-  readonly name: string
-  readonly reason: string
-  readonly internalScore: number
-  readonly retrievedText: string
-}
-
-class AgencyCatalog extends Context.Tag("AgencyCatalog")<
-  AgencyCatalog,
-  {
-    readonly search: (
-      query: string,
-    ) => Effect.Effect<ReadonlyArray<AgencyMatch>>
-  }
->() {}
-
-const AgencyCards = defineView({
-  name: "agency_cards",
-  version: 1,
-  schema: Schema.Struct({
-    agencies: Schema.Array(
-      Schema.Struct({
-        id: Schema.String,
-        name: Schema.String,
-        reason: Schema.String,
-      }),
-    ),
-  }),
-})
-
-const AgencyEvidence = Schema.Struct({
-  matches: Schema.Array(
-    Schema.Struct({
-      id: Schema.String,
-      reason: Schema.String,
-    }),
-  ),
-})
-
-export const SearchAgencies = defineTool({
-  name: "search_agencies",
-  description: "Find agencies relevant to the project.",
-  input: Schema.Struct({ query: Schema.NonEmptyTrimmedString }),
-  execute: ({ query }) =>
-    AgencyCatalog.pipe(
-      Effect.flatMap((catalog) => catalog.search(query)),
-    ),
-}).pipe(
-  Tool.modelResult(AgencyEvidence, (matches) => ({
-    matches: matches.map(({ id, reason }) => ({ id, reason })),
-  })),
-  Tool.present(AgencyCards, (matches) => ({
-    agencies: matches.map(({ id, name, reason }) => ({
-      id,
-      name,
-      reason,
-    })),
-  })),
-)
-
-export const Matching = Stage.tools({
-  name: "matching",
-  instructions: ["Route the project brief to one agency search."],
-  tools: [SearchAgencies],
-})
-
-const AgencyCatalogLive = Layer.succeed(AgencyCatalog, {
-  search: () =>
-    Effect.succeed([
-      {
-        id: "agency:1",
-        name: "Northbank",
-        reason: "Relevant public-sector transformation work.",
-        internalScore: 0.93,
-        retrievedText: "Untrusted source text remains server-side.",
-      },
-    ]),
-})
-
-export const example = SearchAgencies.execute({
-  query: "A public-sector digital service",
-}).pipe(Effect.provide(AgencyCatalogLive))
-
-export const stageExample = Matching.run([
-  Message.user("We need a public-sector digital service."),
-])