Separate L.assistant into L.assistantText and L.assistantStruct (#340)

harrysolovay · web-flow · commit df8861ac503c · 2025-07-28T20:14:06.000-04:00
diff --git a/.changeset/bitter-ears-sing.md b/.changeset/bitter-ears-sing.md
@@ -0,0 +1,5 @@
+---
+"liminal": minor
+---
+
+Separate L.assistant into L.assistantText and L.assistantStruct.
diff --git a/README.md b/README.md
@@ -27,24 +27,24 @@ import * as Strand from "liminal/Strand"
 await Effect.gen(function*() {
   yield* L
     .user`Decide on a subtopic for us to discuss within the domain of technological futurism.`
-  yield* L.assistant()
+  yield* L.assistantText
   yield* L
     .user`Great, please teach something interesting about this choice of subtopic.`
-  yield* L.assistant()
+  yield* L.assistantText
   let i = 0
   while (i < 3) {
     const reply = yield* Effect
       .gen(function*() {
         yield* L.user`Please reply to the last message on my behalf.`
-        return yield* L.assistant()
+        return yield* L.assistantText
       })
       .pipe(Effect.provide(Strand.layer()))
     yield* L.user(reply)
-    yield* L.assistant()
+    yield* L.assistantText
     i++
   }
   yield* L.user`Please summarize the key points from our conversation.`
-  return yield* L.assistant()
+  return yield* L.assistantText
 }).pipe(
   Effect.provide(Strand.layer({
     system: `
diff --git a/examples/activity_suggestions.ts b/examples/activity_suggestions.ts
@@ -17,7 +17,7 @@ await Effect.gen(function*() {
   let i = 0
   const activities: Array<typeof Activity.Type> = []
   while (i < 5) {
-    activities.push(yield* L.assistant(Activity))
+    activities.push(yield* L.assistantStruct(Activity))
     yield* L.user`Another please.`
     i++
   }
diff --git a/examples/chaining.ts b/examples/chaining.ts
@@ -6,7 +6,7 @@ import { common } from "./_common.ts"
 
 await Effect.gen(function*() {
   yield* L.user`Please generate the first draft.`
-  let copy = yield* L.assistant()
+  let copy = yield* L.assistantText
   yield* L.user`
     Now evaluate this marketing copy for:
 
@@ -16,7 +16,7 @@ await Effect.gen(function*() {
 
     Copy to evaluate: ${copy}
   `
-  const qualityMetrics = yield* L.assistant(Schema.Struct({
+  const qualityMetrics = yield* L.assistantStruct(Schema.Struct({
     hasCallToAction: Schema.Boolean,
     emotionalAppeal: Schema.Number,
     clarity: Schema.Number,
@@ -31,7 +31,7 @@ await Effect.gen(function*() {
 
       Original copy: ${copy}
     `
-    copy = yield* L.assistant()
+    copy = yield* L.assistantText
   }
   return { copy, qualityMetrics }
 }).pipe(
diff --git a/examples/compare_models.ts b/examples/compare_models.ts
@@ -7,15 +7,15 @@ import { common } from "./_common.ts"
 
 await Effect.gen(function*() {
   yield* L.user`Write a rap about type-level programming in TypeScript`
-  yield* L.assistant()
+  yield* L.assistantText
   yield* L.user`Rewrite it in whatever way you think best.`
   const variants = yield* Effect.all({
-    a: L.assistant().pipe(Effect.provide(Strand.layer())),
-    b: L.assistant().pipe(
+    a: L.assistantText.pipe(Effect.provide(Strand.layer())),
+    b: L.assistantText.pipe(
       Effect.provide(Strand.layer()),
       Effect.provide(OpenAiLanguageModel.model("gpt-4-turbo")),
     ),
-    c: L.assistant().pipe(
+    c: L.assistantText.pipe(
       Effect.provide(Strand.layer()),
       Effect.provide(OpenAiLanguageModel.model("gpt-3.5-turbo")),
     ),
@@ -26,7 +26,9 @@ await Effect.gen(function*() {
 
       ${JSON.stringify(variants)}
     `
-    return yield* L.assistant(Schema.Literal("a", "b", "c"))
+    return yield* L.assistantStruct(Schema.Struct({
+      inner: Schema.Literal("a", "b", "c"),
+    })).pipe(Effect.map(({ inner }) => inner))
   })
   return variants[key]
 }).pipe(
diff --git a/examples/optimizer.ts b/examples/optimizer.ts
@@ -9,7 +9,7 @@ const TEXT = "..."
 Effect.gen(function*() {
   yield* L.user`Target language: typescript`
   yield* L.user`Text:\n\n${TEXT}`
-  let currentTranslation = yield* L.assistant()
+  let currentTranslation = yield* L.assistantText
   let iterations = 0
   const MAX_ITERATIONS = 3
   while (iterations < MAX_ITERATIONS) {
@@ -25,7 +25,7 @@ Effect.gen(function*() {
       3. Preservation of nuance
       4. Cultural accuracy
     `
-    const evaluation = yield* L.assistant(Schema.Struct({
+    const evaluation = yield* L.assistantStruct(Schema.Struct({
       qualityScore: Schema.Int,
       preservesTone: Schema.Boolean,
       preservesNuance: Schema.Boolean,
@@ -50,7 +50,7 @@ Effect.gen(function*() {
       Original: ${TEXT}
       Current Translation: ${currentTranslation}
     `
-    currentTranslation = yield* L.assistant()
+    currentTranslation = yield* L.assistantText
     iterations += 1
   }
   return {
diff --git a/examples/parallel.ts b/examples/parallel.ts
@@ -8,7 +8,7 @@ import { common } from "./_common.ts"
 
 const Lmh = Schema.Literal("lower", "medium", "high")
 
-const security = L.assistant(Schema.Struct({
+const security = L.assistantStruct(Schema.Struct({
   type: Schema.Literal("security"),
   vulnerabilities: Schema.Array(Schema.String),
   riskLevel: Lmh,
@@ -19,7 +19,7 @@ const security = L.assistant(Schema.Struct({
   messages: undefined,
 })))
 
-const performance = L.assistant(Schema.Struct({
+const performance = L.assistantStruct(Schema.Struct({
   type: Schema.Literal("performance"),
   issues: Schema.Array(Schema.String),
   impact: Lmh,
@@ -30,7 +30,7 @@ const performance = L.assistant(Schema.Struct({
   messages: undefined,
 })))
 
-const maintainability = L.assistant(Schema.Struct({
+const maintainability = L.assistantStruct(Schema.Struct({
   type: Schema.Literal("maintainability"),
   concerns: Schema.Array(Schema.String),
   qualityScore: Schema.Int,
@@ -51,7 +51,7 @@ Effect.gen(function*() {
   })
   yield* L.user(JSON.stringify(Object.values(reviews), null, 2))
   yield* L.user`You are a technical lead summarizing multiple code reviews.`
-  const summary = yield* L.assistant()
+  const summary = yield* L.assistantText
   return { reviews, summary }
 }).pipe(
   Effect.provide(Strand.layer({
diff --git a/examples/routing.ts b/examples/routing.ts
@@ -16,7 +16,7 @@ const USE_CLASSIFICATION_PROMPTS = {
 await Effect.gen(function*() {
   const classification = yield* Effect.gen(function*() {
     yield* L.user`I'd like a refund please.`
-    return yield* L.assistant(Schema.Struct({
+    return yield* L.assistantStruct(Schema.Struct({
       reasoning: Schema.String,
       type: Schema.Literal("general", "refund", "technical"),
       complexity: Schema.Literal("simple", "complex"),
@@ -32,7 +32,7 @@ await Effect.gen(function*() {
       3. Brief reasoning for classification
     `,
   })))
-  const response = L.assistant().pipe(
+  const response = L.assistantText.pipe(
     Effect.provide(Strand.layer({
       system: USE_CLASSIFICATION_PROMPTS[classification.type],
     })),
diff --git a/examples/self_talk.ts b/examples/self_talk.ts
@@ -6,23 +6,23 @@ import { common } from "./_common.ts"
 await Effect
   .gen(function*() {
     yield* L.user`Decide on a subtopic for us to discuss within the domain of technological futurism.`
-    yield* L.assistant()
+    yield* L.assistantText
     yield* L.user`Great, please teach something interesting about this choice of subtopic.`
-    yield* L.assistant()
+    yield* L.assistantText
     let i = 0
     while (i < 3) {
       const reply = yield* Effect
         .gen(function*() {
           yield* L.user`Please reply to the last message on my behalf.`
-          return yield* L.assistant()
+          return yield* L.assistantText
         })
         .pipe(Effect.provide(Strand.layer()))
       yield* L.user(reply)
-      yield* L.assistant()
+      yield* L.assistantText
       i++
     }
     yield* L.user`Please summarize the key points from our conversation.`
-    return yield* L.assistant()
+    return yield* L.assistantText
   })
   .pipe(
     Effect.provide(Strand.layer({
diff --git a/examples/trip_planner.ts b/examples/trip_planner.ts
@@ -13,9 +13,11 @@ await Effect.gen(function*() {
     I want to plan a weekend trip leaving from ${DEPARTURE_LOCATION}. I don't know where to go.
     Suggest some follow-up questions that will help you narrow down the possible destination.
   `
-  const { questions } = yield* L.assistant(Schema.Struct({
-    questions: Schema.Array(Schema.String),
-  }))
+  const { questions } = yield* L.assistantStruct(
+    Schema.Struct({
+      questions: Schema.Array(Schema.String),
+    }),
+  )
   yield* L.user`Here are my answers to those questions:`
   const terminal = yield* Terminal.Terminal
   for (const question of questions) {
@@ -27,9 +29,9 @@ await Effect.gen(function*() {
     `
   }
   yield* L.user`Now that we've refined the destination criteria, please provide a single recommendation.`
-  yield* L.assistant()
+  yield* L.assistantText
   yield* L.user`Where can I stay there, what can I do there, how do I get there?`
-  return yield* L.assistant()
+  return yield* L.assistantText
 }).pipe(
   Effect.provide(Strand.layer({
     onMessage: Console.log,
diff --git a/examples/workers.ts b/examples/workers.ts
@@ -14,7 +14,7 @@ await Effect
   .gen(function*() {
     yield* L.user`Analyze this feature request and create an implementation plan:`
     yield* L.user`Alert administrators via text whenever site traffic exceeds a certain threshold.`
-    const implementationPlan = yield* L.assistant(Schema.Struct({
+    const implementationPlan = yield* L.assistantStruct(Schema.Struct({
       complexity: Schema.Literal("low", "medium", "high"),
       files: Schema.Array(Schema.Struct({
         changeType: Schema.Literal("create", "modify", "delete"),
@@ -27,7 +27,7 @@ await Effect
         Effect
           .gen(function*() {
             yield* L.user`Implement the changes for ${file.filePath} to support: ${file.purpose}`
-            const implementation = yield* L.assistant(Schema.Struct({
+            const implementation = yield* L.assistantStruct(Schema.Struct({
               explanation: Schema.String,
               code: Schema.String,
             }))
diff --git a/liminal.land/overview.md b/liminal.land/overview.md
@@ -25,7 +25,7 @@ const program = Effect
     yield* L.user`Where is the pot of gold?`
 
     // Infer and append a model reply.
-    const reply = yield* L.assistant()
+    const reply = yield* L.assistant
 
     // The conversation culminates in a string.
     return reply
@@ -85,7 +85,7 @@ export const refine = (content: string, i = 5) =>
   Effect.gen(function*() {
     while (i-- > 0) {
       yield* L.user`Improve the following text: ${content}`
-      content = yield* L.assistant()
+      content = yield* L.assistantText
     }
     return content
   })
@@ -104,9 +104,11 @@ const maybeRefine = (initial: string) =>
   Effect.gen(function*() {
     yield* L.user`Does the following text require refinement?: ${initial}`
 
-    const { needsRefinement } = yield* L.assistant(Schema.Struct({
-      needsRefinement: Schema.Boolean,
-    }))
+    const { needsRefinement } = yield* L.assistantStruct(
+      Schema.Struct({
+        needsRefinement: Schema.Boolean,
+      }),
+    )
     if (needsRefinement) {
       return yield* refine(initial)
     }
@@ -125,10 +127,12 @@ import { L } from "liminal"
 Effect.gen(function*() {
   yield* L.user`What day of the year is halloween?`
 
-  const result = yield* L.assistant(Schema.Struct({
-    month: L.integer,
-    day: L.integer,
-  }))
+  const result = yield* L.assistantStruct(
+    Schema.Struct({
+      month: L.integer,
+      day: L.integer,
+    }),
+  )
 
   result satisfies { month: integer; day: number }
 })
diff --git a/liminal.land/start.md b/liminal.land/start.md
@@ -48,7 +48,7 @@ const reply = Effect
     yield* L.user`<user-message-here>`
 
     // Trigger an assistant reply.
-    const modelReply = yield* L.assistant()
+    const modelReply = yield* L.assistantText
 
     return modelReply
   })
@@ -97,8 +97,10 @@ const validateEmail = (email: string) =>
       if (!EMAIL_REGEX.test(email)) {
         // 1. Ask a question.
         yield* L.user`Why is the following email is invalid?: "${email}".`
+
         // 2. Infer the answer.
-        const error = yield* L.assistant()
+        const error = yield* L.assistantText
+
         return { error }
       }
       return { valid: true }
diff --git a/liminal/L.ts b/liminal/L.ts
@@ -37,38 +37,45 @@ export const setMessages: (
   },
 )
 
-export const assistant: {
-  (): Effect.Effect<string, AiError.AiError, AiLanguageModel.AiLanguageModel | Strand.Strand>
-  <O, I>(
-    schema: Schema.Schema<O, I, never>,
-  ): Effect.Effect<O, AiError.AiError, AiLanguageModel.AiLanguageModel | Strand.Strand>
-} = Effect.fn(function*(schema?: Schema.Schema<any>) {
+export const assistantText: Effect.Effect<
+  string,
+  AiError.AiError,
+  AiLanguageModel.AiLanguageModel | Strand.Strand
+> = Effect.gen(function*() {
   const model = yield* AiLanguageModel.AiLanguageModel
-  const { system, messages, tools, onMessage } = yield* Strand.Strand
-  if (schema) {
-    const response = yield* model.generateObject({
-      system,
-      schema,
-      prompt: messages,
-    })
-    const { value, text } = response
-    yield* appendMessage(text)
-    return value
-  }
+  const { system, messages, tools } = yield* Strand.Strand
   const response = yield* model.generateText({
     system,
     prompt: messages,
     toolkit: AiToolkit.make(...tools ?? []) as never,
   })
   const { text } = response
-  yield* appendMessage(text)
+  yield* append(text)
   return text
+})
 
-  function* appendMessage(text: string) {
-    const message = new AiInput.AssistantMessage({
-      parts: [new AiInput.TextPart({ text })],
+export const assistantStruct: <O, I extends Record<string, unknown>>(
+  schema: Schema.Schema<O, I, never>,
+) => Effect.Effect<O, AiError.AiError, AiLanguageModel.AiLanguageModel | Strand.Strand> = Effect.fnUntraced(
+  function*(schema) {
+    const model = yield* AiLanguageModel.AiLanguageModel
+    const { system, messages } = yield* Strand.Strand
+    const response = yield* model.generateObject({
+      system,
+      schema,
+      prompt: messages,
     })
-    yield* onMessage(message)
-    messages.push(message)
-  }
+    const { value, text } = response
+    yield* append(text)
+    return value
+  },
+)
+
+const append = Effect.fnUntraced(function*(text: string) {
+  const { messages, onMessage } = yield* Strand.Strand
+  const message = new AiInput.AssistantMessage({
+    parts: [new AiInput.TextPart({ text })],
+  })
+  yield* onMessage(message)
+  messages.push(message)
 })
diff --git a/liminal/Strand.ts b/liminal/Strand.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"liminal": minor
 +---
++
 +Separate L.assistant into L.assistantText and L.assistantStruct.
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ await Effect.gen(function*() {`
`17`	`17`	`let i = 0`
`18`	`18`	`const activities: Array<typeof Activity.Type> = []`
`19`	`19`	`while (i < 5) {`
`20`		`- activities.push(yield* L.assistant(Activity))`
	`20`	`+ activities.push(yield* L.assistantStruct(Activity))`
`21`	`21`	yield* L.user`Another please.`
`22`	`22`	`i++`
`23`	`23`	`}`