refactor(ai): structured output via schema on generate, stream and loop (#60783)

This commit is contained in:
Aiden Cline
2026-10-30 23:35:18 -05:00
committed by GitHub
Unverified
parent 1908fcb8b7
commit e8238bae9b
10 changed files with 315 additions and 178 deletions
+8 -8
View File
@@ -104,17 +104,17 @@ history works with or without `freeform`.
### Structured output
`generateObject` forces a tool call and decodes its input against `schema`; pass `jsonSchema` instead for an
unvalidated `unknown` object:
Pass `schema` to `generate`, `stream` or `loop`. The model must answer through a hidden tool call, decoded into
`object` (typed from an Effect Schema, or an unvalidated `unknown` for a raw JSON Schema object):
```ts
const { object } = await ai.generateObject({
model,
prompt: "Pick a city.",
schema: Schema.Struct({ city: Schema.String }),
})
const res = await ai.generate({ model, prompt: "Pick a city.", schema: Schema.Struct({ city: Schema.String }) })
res.object.city
```
`stream` puts `object` on its `finish` event; `loop` runs tools first and puts it on the final step's `finish`. A
decode failure is an `AIError` whose `partial` holds the response.
### Raw provider events
Set `includeRaw: true` on a request to also receive every provider frame as `{ type: "raw", data }`, in order and
@@ -894,7 +894,7 @@ Everything below is exported from `@opencode/ai/effect` unless noted.
- **`Generation`** — provider-neutral handle for an in-flight media generation (`await`, `refresh`, `cancel`, `events`) used by queued media routes.
- **`ai.decision.request` / `ai.decision.generate`** — typed predicate, choice, and score questions over text, JSON, and media input; `DecisionClient` is its Effect service and layer.
- **`AIClient.layer` / `AIClient.layerWith(executor)`** — every modality client plus the request executor in one layer.
- **`@opencode/ai`** (Promise root) — a default `ai` with the text calls (`request`, `generate`, `stream`, `loop`, `generateObject`, `compact`, `canCompact`) at the top level plus `image` and `decision` (plus `experimental.video`, `experimental.speech`, and `experimental.transcription`) as Promise / `AsyncIterable` APIs, `run(effect)` for any package Effect, plus `file`, `write`, `bytes`, `base64`, and `materialize` for assets. `AI.make({ layer?, clients? })` builds a client over a custom executor or test layers. The same `ai` from `@opencode/ai/effect` returns `Effect` and `Stream`.
- **`@opencode/ai`** (Promise root) — a default `ai` with the text calls (`request`, `generate`, `stream`, `loop`, `compact`, `canCompact`) at the top level plus `image` and `decision` (plus `experimental.video`, `experimental.speech`, and `experimental.transcription`) as Promise / `AsyncIterable` APIs, `run(effect)` for any package Effect, plus `file`, `write`, `bytes`, `base64`, and `materialize` for assets. `AI.make({ layer?, clients? })` builds a client over a custom executor or test layers. The same `ai` from `@opencode/ai/effect` returns `Effect` and `Stream`.
- **`@opencode/ai/experimental`** — APIs that may change without compatibility guarantees: `Video`, `Speech`, `Transcription`, `Extraction`, and `Realtime`. See [Experimental](#experimental).
## Experimental
+6 -7
View File
@@ -123,9 +123,8 @@ const streamWithTools = Effect.gen(function* () {
}
})
// 6. `generateObject` is the structured-output helper. It forces a synthetic
// tool call internally, so the same call site works across providers instead of
// depending on provider-specific JSON mode flags.
// 6. `schema` asks for structured output. It forces a hidden tool call, so the
// same call site works across providers, and decodes its input into `object`.
const WeatherReport = Schema.Struct({
city: Schema.String,
forecast: Schema.String,
@@ -133,7 +132,7 @@ const WeatherReport = Schema.Struct({
})
const generateStructuredObject = Effect.gen(function* () {
const response = yield* ai.generateObject({
const response = yield* ai.generate({
model,
system: "Return only structured weather data.",
prompt: "Give me today's weather for San Francisco.",
@@ -141,16 +140,16 @@ const generateStructuredObject = Effect.gen(function* () {
generation: { maxTokens: 120, temperature: 0 },
})
console.log("\n== generateObject ==")
console.log("\n== structured output ==")
console.log(Formatter.formatJson(response.object, { space: 2 }))
})
// If the shape is only known at runtime, pass raw JSON Schema instead. The
// `.object` type is `unknown`; callers that need static types should validate it.
const generateDynamicObject = ai.generateObject({
const generateDynamicObject = ai.generate({
model,
prompt: "Extract the city and forecast from: San Francisco is sunny.",
jsonSchema: {
schema: {
type: "object",
properties: {
city: { type: "string" },
-1
View File
@@ -11,7 +11,6 @@ export const ai = {
generate: LLM.generate,
stream: LLM.stream,
loop: LLM.loop,
generateObject: LLM.generateObject,
compact: LLM.compact,
canCompact: LLM.canCompact,
image: Image,
+45 -28
View File
@@ -19,13 +19,18 @@ import {
LanguageModel,
type CompactionCheckpointResponse,
type CompactionResponse,
type LLMEvent,
type LLMRequest,
type LLMResponse,
} from "./schema/index.js"
import type {
GenerateObjectDynamicOptions,
GenerateObjectOptions,
GenerateObjectResponse,
LoopInput,
LoopObjectEvent,
ObjectEvent,
ObjectInput,
ObjectResponse,
OutputSchema,
OutputType,
RequestInput,
} from "./llm.js"
import { Speech, type SpeechModel, type SpeechRequest, type SpeechRequestInput } from "./speech.js"
@@ -115,19 +120,40 @@ export const make = <R = never>(options: Options<R> = {}) => {
),
)
function generateObject<const Model extends LanguageModel, S extends ToolSchema<any>>(
input: GenerateObjectOptions<S, Model>,
options?: RunOptions,
): Promise<GenerateObjectResponse<Schema.Schema.Type<S>>>
function generateObject<const Model extends LanguageModel>(
input: GenerateObjectDynamicOptions<Model>,
options?: RunOptions,
): Promise<GenerateObjectResponse<unknown>>
function generateObject(
input: GenerateObjectOptions<ToolSchema<any>> | GenerateObjectDynamicOptions,
options?: RunOptions,
) {
return run("schema" in input ? LLM.generateObject(input) : LLM.generateObject(input), options)
function generate<const Model extends LanguageModel, S extends OutputSchema>(
input: ObjectInput<S, Model>,
options?: StreamOptions & RunOptions,
): Promise<ObjectResponse<OutputType<S>>>
function generate<const Model extends LanguageModel>(
input: RequestInput<Model> | LLMRequest,
options?: StreamOptions & RunOptions,
): Promise<LLMResponse>
function generate(input: ObjectInput<OutputSchema> | RequestInput | LLMRequest, options?: StreamOptions & RunOptions) {
return run(LLM.generate(input, options), options)
}
function stream<const Model extends LanguageModel, S extends OutputSchema>(
input: ObjectInput<S, Model>,
options?: StreamOptions & RunOptions,
): AsyncIterable<ObjectEvent<OutputType<S>>>
function stream<const Model extends LanguageModel>(
input: RequestInput<Model> | LLMRequest,
options?: StreamOptions & RunOptions,
): AsyncIterable<LLMEvent>
function stream(input: ObjectInput<OutputSchema> | RequestInput | LLMRequest, options?: StreamOptions & RunOptions) {
return iterate(LLM.stream(input, options), options)
}
function loop<const Model extends LanguageModel, S extends OutputSchema>(
input: LoopInput<Model> & { readonly schema: S },
options?: StreamOptions & RunOptions,
): AsyncIterable<LoopObjectEvent<OutputType<S>>>
function loop<const Model extends LanguageModel>(
input: LoopInput<Model>,
options?: StreamOptions & RunOptions,
): AsyncIterable<LLMEvent>
function loop(input: LoopInput & { readonly schema?: OutputSchema }, options?: StreamOptions & RunOptions) {
return iterate(LLM.loop(input, options), options)
}
function compact(
@@ -196,19 +222,10 @@ export const make = <R = never>(options: Options<R> = {}) => {
)
},
request: LLM.request,
generate: <const Model extends LanguageModel>(
input: RequestInput<Model> | LLMRequest,
options?: StreamOptions & RunOptions,
) => run(LLM.generate(input, options), options),
stream: <const Model extends LanguageModel>(
input: RequestInput<Model> | LLMRequest,
options?: StreamOptions & RunOptions,
) => iterate(LLM.stream(input, options), options),
generate,
stream,
/** Stream model calls, running their tool calls, until the model stops calling tools or `until` is true. */
loop: <const Model extends LanguageModel>(input: LoopInput<Model>, options?: StreamOptions & RunOptions) =>
iterate(LLM.loop(input, options), options),
/** Decode the model's output against `schema` (or `jsonSchema`, unvalidated). */
generateObject,
loop,
/** Compact a Responses request: a replacement window, or a checkpoint with `mechanism: "trigger"`. */
compact,
canCompact: LLM.canCompact,
+137 -105
View File
@@ -12,6 +12,7 @@ import {
Message,
LanguageModel,
SystemPart,
type Finish,
ToolChoice,
ToolEntry,
type ContentPart,
@@ -38,20 +39,74 @@ export type RequestInput<SelectedLanguageModel extends LanguageModel = LanguageM
readonly http?: HttpOptions.Input
}
/** An Effect Schema decodes and types `object`; a raw JSON Schema leaves it `unknown`. */
export type OutputSchema = ToolSchema<any> | JsonSchema.JsonSchema
export type OutputType<S extends OutputSchema> = S extends Schema.Top ? Schema.Schema.Type<S> : unknown
export type ObjectInput<
S extends OutputSchema,
SelectedLanguageModel extends LanguageModel = LanguageModel,
> = RequestInput<SelectedLanguageModel> & { readonly schema: S }
export type ObjectResponse<T> = LLMResponse & { readonly object: T }
/** Stream events for a request with `schema`: the `finish` event carries the decoded `object`. */
export type ObjectEvent<T> = Exclude<LLMEvent, Finish> | (Finish & { readonly object: T })
/** Loop events for a request with `schema`: the final step's `finish` event carries the decoded `object`. */
export type LoopObjectEvent<T> = Exclude<LLMEvent, Finish> | (Finish & { readonly object?: T })
/** Run one model call. With `schema`, the model must answer through a forced tool call decoded into `object`. */
export function generate<const Model extends LanguageModel, S extends OutputSchema>(
input: ObjectInput<S, Model>,
options?: StreamOptions,
): Effect.Effect<ObjectResponse<OutputType<S>>, AIError, Service>
export function generate<const Model extends LanguageModel>(
input: RequestInput<Model> | LLMRequest,
options?: StreamOptions,
): Effect.Effect<LLMResponse, AIError, Service>
export function generate(input: RequestInput | LLMRequest, options?: StreamOptions) {
return requestEffect(input).pipe(Effect.flatMap((request) => LLMClient.generate(request, options)))
export function generate(input: Input, options?: StreamOptions) {
return prepare(input).pipe(
Effect.flatMap(({ request, output }) =>
LLMClient.generate(request, options).pipe(
Effect.flatMap((response) =>
output === undefined
? Effect.succeed(response)
: decodeObject(output, response).pipe(Effect.map((object) => Object.assign(response, { object }))),
),
),
),
)
}
/** Stream one model call. With `schema`, the `finish` event carries the decoded `object`. */
export function stream<const Model extends LanguageModel, S extends OutputSchema>(
input: ObjectInput<S, Model>,
options?: StreamOptions,
): Stream.Stream<ObjectEvent<OutputType<S>>, AIError, Service>
export function stream<const Model extends LanguageModel>(
input: RequestInput<Model> | LLMRequest,
options?: StreamOptions,
): Stream.Stream<LLMEvent, AIError, Service>
export function stream(input: RequestInput | LLMRequest, options?: StreamOptions) {
return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => LLMClient.stream(request, options))))
export function stream(input: Input, options?: StreamOptions) {
return Stream.unwrap(
prepare(input).pipe(
Effect.map(({ request, output }) =>
Stream.suspend(() => {
let state = LLMResponse.empty()
return LLMClient.stream(request, options).pipe(
Stream.mapEffect((event) => {
state = LLMResponse.reduce(state, event)
return output === undefined || event.type !== "finish"
? Effect.succeed(event)
: withObject(output, event, state)
}),
)
}),
),
),
)
}
export type LoopInput<SelectedLanguageModel extends LanguageModel = LanguageModel> = Omit<
@@ -66,27 +121,48 @@ export type LoopInput<SelectedLanguageModel extends LanguageModel = LanguageMode
/**
* Stream model calls, running the model's tool calls between them, until a step has no client-executed tool calls,
* reports a provider error, or `until` returns `true`. Each step's `step-start` and `step-finish` carry its step index.
* With `schema`, the model ends by calling the hidden answer tool, decoded into `object` on that step's `finish`.
*/
export function loop<const Model extends LanguageModel, S extends OutputSchema>(
input: LoopInput<Model> & { readonly schema: S },
options?: StreamOptions,
): Stream.Stream<LoopObjectEvent<OutputType<S>>, AIError, Service>
export function loop<const Model extends LanguageModel>(
input: LoopInput<Model>,
options?: StreamOptions,
): Stream.Stream<LLMEvent, AIError, Service>
export function loop(input: LoopInput, options?: StreamOptions) {
export function loop(input: LoopInput & { readonly schema?: OutputSchema }, options?: StreamOptions) {
const { tools, until, ...rest } = input
const step = (request: LLMRequest, steps: ReadonlyArray<LLMResponse>): Stream.Stream<LLMEvent, AIError, Service> =>
// A step that calls the answer tool is final, even if it also called other tools.
const clientCalls = (response: LLMResponse, output: Tool | undefined) =>
output && response.toolCalls.some((call) => call.name === OBJECT_TOOL)
? []
: response.toolCalls.filter((call) => call.providerExecuted !== true)
const step = (
request: LLMRequest,
steps: ReadonlyArray<LLMResponse>,
output: Tool | undefined,
): Stream.Stream<LLMEvent, AIError, Service> =>
Stream.suspend(() => {
let state = LLMResponse.empty()
return LLMClient.stream(request, options).pipe(
Stream.map((event) =>
event.type === "step-start" || event.type === "step-finish" ? { ...event, index: steps.length } : event,
),
Stream.tap((event) => Effect.sync(() => (state = LLMResponse.reduce(state, event)))),
Stream.mapEffect((event) => {
state = LLMResponse.reduce(state, event)
if (output === undefined || event.type !== "finish") return Effect.succeed(event)
const response = LLMResponse.complete(state)
return response && clientCalls(response, output).length > 0
? Effect.succeed(event)
: withObject(output, event, state)
}),
Stream.mapError((error) => withPartial(error, LLMResponse.partial(state))),
Stream.concat(
Stream.unwrap(
Effect.gen(function* () {
const response = LLMResponse.complete(state)
const calls = response?.toolCalls.filter((call) => call.providerExecuted !== true) ?? []
const calls = response ? clientCalls(response, output) : []
if (!response || calls.length === 0 || state.events.some(LLMEvent.is.providerError)) return Stream.empty
const done = [...steps, response]
if (until?.({ steps: done })) return Stream.empty
@@ -109,7 +185,7 @@ export function loop(input: LoopInput, options?: StreamOptions) {
],
})
return Stream.fromIterable(results.flatMap((result) => result.events)).pipe(
Stream.concat(step(next, done)),
Stream.concat(step(next, done, output)),
)
}),
),
@@ -117,12 +193,61 @@ export function loop(input: LoopInput, options?: StreamOptions) {
)
})
return Stream.unwrap(
requestEffect({ ...rest, tools: toDefinitions(tools) }).pipe(Effect.map((request) => step(request, []))),
prepare({ ...rest, tools: toDefinitions(tools) }).pipe(
Effect.map(({ request, output }) => step(request, [], output)),
),
)
}
const requestEffect = (input: RequestInput | LLMRequest) =>
input instanceof LLMRequest ? Effect.succeed(input) : tryRequest(() => request(input))
const OBJECT_TOOL = "generate_object"
type Input = (RequestInput & { readonly schema?: OutputSchema }) | LLMRequest
// `schema` adds a hidden tool whose input is the answer. With other tools the model only has to call some tool.
const prepare = (input: Input) => {
if (input instanceof LLMRequest) return Effect.succeed({ request: input, output: undefined })
const { schema, ...rest } = input
return tryRequest(() => {
const base = request(rest)
if (schema === undefined) return { request: base, output: undefined }
const description = "Return the structured result by calling this tool."
const output: Tool = Schema.isSchema(schema)
? tool({ description, parameters: schema })
: tool({ description, jsonSchema: schema })
const toolChoice = base.tools.length === 0 ? ToolChoice.named(OBJECT_TOOL) : new ToolChoice({ type: "required" })
return {
output,
request: LLMRequest.update(base, {
tools: [...base.tools, ...toDefinitions({ [OBJECT_TOOL]: output })],
toolChoice,
}),
}
})
}
const decodeObject = (output: Tool, response: LLMResponse) => {
const call = response.toolCalls.find((event) => event.name === OBJECT_TOOL)
const invalid = (message: string, cause?: unknown) =>
new AIError({ reason: new InvalidProviderOutputError({ message, cause }), partial: response })
if (call)
return output
._decode(call.input)
.pipe(Effect.mapError((error) => invalid(`schema decode failed: ${error.message}`, error)))
return Effect.fail(
invalid(
response.finishReason.normalized === "length"
? "output hit the token limit before the forced tool call completed"
: `model did not call the forced \`${OBJECT_TOOL}\` tool`,
),
)
}
const withObject = (output: Tool, event: Finish, state: LLMResponse.State): Effect.Effect<LLMEvent, AIError> => {
const response = LLMResponse.complete(state)
return response === undefined
? Effect.succeed(event)
: decodeObject(output, response).pipe(Effect.map((object) => ({ ...event, object })))
}
export const request = <const SelectedLanguageModel extends LanguageModel>(
input: RequestInput<SelectedLanguageModel>,
@@ -150,99 +275,6 @@ export const request = <const SelectedLanguageModel extends LanguageModel>(
})
}
const GENERATE_OBJECT_TOOL_NAME = "generate_object"
const GENERATE_OBJECT_TOOL_DESCRIPTION = "Return the structured result by calling this tool."
type GenerateObjectBase<SelectedLanguageModel extends LanguageModel = LanguageModel> = Omit<
RequestInput<SelectedLanguageModel>,
"tools" | "toolChoice"
>
export class GenerateObjectResponse<T> {
constructor(
readonly object: T,
readonly response: LLMResponse,
) {}
get events() {
return this.response.events
}
get usage() {
return this.response.usage
}
}
export interface GenerateObjectOptions<
S extends ToolSchema<any>,
SelectedLanguageModel extends LanguageModel = LanguageModel,
> extends GenerateObjectBase<SelectedLanguageModel> {
readonly schema: S
}
export interface GenerateObjectDynamicOptions<SelectedLanguageModel extends LanguageModel = LanguageModel>
extends GenerateObjectBase<SelectedLanguageModel> {
/** Raw JSON Schema object describing the expected output shape. */
readonly jsonSchema: JsonSchema.JsonSchema
}
const runGenerateObject = Effect.fn("LLM.generateObject")(function* (options: GenerateObjectBase, tool: Tool) {
const baseRequest = request(options)
const generateRequest = LLMRequest.update(baseRequest, {
tools: toDefinitions({ [GENERATE_OBJECT_TOOL_NAME]: tool }),
toolChoice: ToolChoice.named(GENERATE_OBJECT_TOOL_NAME),
})
const response = yield* LLMClient.generate(generateRequest)
const call = response.toolCalls.find((event) => event.name === GENERATE_OBJECT_TOOL_NAME)
const invalidOutput = (reason: InvalidProviderOutputError) => new AIError({ reason, partial: response })
if (!call) {
const message =
response.finishReason.normalized === "length"
? "generateObject: output hit the token limit before the forced tool call completed"
: `generateObject: model did not call the forced \`${GENERATE_OBJECT_TOOL_NAME}\` tool`
return yield* invalidOutput(new InvalidProviderOutputError({ message }))
}
const object = yield* tool._decode(call.input).pipe(
Effect.mapError((error) =>
invalidOutput(
new InvalidProviderOutputError({
message: `generateObject: tool input failed schema decode: ${error.message}`,
cause: error,
}),
),
),
)
return new GenerateObjectResponse(object, response)
})
/**
* Run a model and decode its output against `schema`. Works on every protocol
* because it forces a synthetic tool call internally — provider-native JSON
* modes are intentionally avoided so behaviour is uniform.
*
* Two input modes:
*
* 1. `schema: EffectSchema<T>` — `.object` is decoded and typed as `T`.
* Decode failures surface as `AIError`.
* 2. `jsonSchema: JsonSchema.JsonSchema` — `.object` is `unknown`. Use when
* the schema is only available at runtime (MCP, plugin manifests). Caller validates.
*/
export function generateObject<const SelectedLanguageModel extends LanguageModel, S extends ToolSchema<any>>(
options: GenerateObjectOptions<S, SelectedLanguageModel>,
): Effect.Effect<GenerateObjectResponse<Schema.Schema.Type<S>>, AIError, Service>
export function generateObject<const SelectedLanguageModel extends LanguageModel>(
options: GenerateObjectDynamicOptions<SelectedLanguageModel>,
): Effect.Effect<GenerateObjectResponse<unknown>, AIError, Service>
export function generateObject(options: GenerateObjectOptions<ToolSchema<any>> | GenerateObjectDynamicOptions) {
if ("schema" in options) {
const { schema, ...rest } = options
return runGenerateObject(rest, tool({ description: GENERATE_OBJECT_TOOL_DESCRIPTION, parameters: schema }))
}
const { jsonSchema, ...rest } = options
return runGenerateObject(rest, tool({ description: GENERATE_OBJECT_TOOL_DESCRIPTION, jsonSchema }))
}
export { canCompact, compact } from "./route/client.js"
export * as LLM from "./llm.js"
+1 -1
View File
@@ -164,7 +164,7 @@ export class AIError extends Schema.TaggedError<AIError>()("AI.Error", {
reason: AIErrorReason,
}) {
override readonly cause = this.reason
/** Output that arrived before `generate`, `generateObject` or a `loop` step failed. Not in the schema, so encoding omits it. */
/** Output that arrived before `generate` (including its `schema` decode) or a `loop` step failed. Not in the schema, so encoding omits it. */
readonly partial?: LLMResponse
constructor(props: Pick<AIError, "reason" | "partial">) {
+2 -2
View File
@@ -47,7 +47,7 @@ describe("AIError.partial", () => {
}),
)
it.effect("generateObject keeps the raw output when the token limit cuts off the forced tool call", () =>
it.effect("generate with schema keeps the raw output when the token limit cuts off the forced tool call", () =>
Effect.gen(function* () {
const client = yield* TestLLM.Test
yield* client.push(
@@ -59,7 +59,7 @@ describe("AIError.partial", () => {
)
const error = yield* ai
.generateObject({
.generate({
model,
prompt: "Answer",
schema: Schema.Struct({ answer: Schema.String }),
+80 -13
View File
@@ -1,10 +1,11 @@
import { describe, expect, test } from "bun:test"
import { Effect, Schema } from "effect"
import { ai } from "../src/effect.js"
import { Effect, Schema, Stream } from "effect"
import { ai, LLMEvent } from "../src/effect.js"
import * as OpenAIChat from "../src/protocols/openai-chat.js"
import { Auth } from "../src/route.js"
import { toDefinitions, tool } from "../src/tool.js"
import { it } from "./lib/effect.js"
import { TestLLM } from "../src/testing.js"
import { it, testEffect } from "./lib/effect.js"
import { dynamicResponse } from "./lib/http.js"
import { finishChunk, toolCallChunk } from "./lib/openai-chunks.js"
import { sseEvents } from "./lib/sse.js"
@@ -63,7 +64,7 @@ describe("tool (dynamic JSON Schema)", () => {
)
})
describe("ai.generateObject", () => {
describe("ai.generate with schema", () => {
it.effect("forces a synthetic tool call and decodes the input", () =>
Effect.gen(function* () {
const bodies: OpenAIChatBody[] = []
@@ -81,7 +82,7 @@ describe("ai.generateObject", () => {
)
const response = yield* ai
.generateObject({
.generate({
model,
prompt: "Return a structured weather report.",
schema: Schema.Struct({ city: Schema.String, temp: Schema.Number }),
@@ -89,7 +90,7 @@ describe("ai.generateObject", () => {
.pipe(Effect.provide(layer))
expect(response.object).toEqual({ city: "Paris", temp: 22 })
expect(response.response.toolCalls).toHaveLength(1)
expect(response.toolCalls).toHaveLength(1)
expect(bodies).toHaveLength(1)
expect(bodies[0].tool_choice).toEqual({ type: "function", function: { name: "generate_object" } })
const tool = bodies[0].tools?.[0]
@@ -124,10 +125,10 @@ describe("ai.generateObject", () => {
)
const response = yield* ai
.generateObject({
.generate({
model,
prompt: "Extract the user.",
jsonSchema: {
schema: {
type: "object",
properties: { name: { type: "string" }, age: { type: "number" } },
required: ["name", "age"],
@@ -155,7 +156,7 @@ describe("ai.generateObject", () => {
)
const exit = yield* ai
.generateObject({
.generate({
model,
prompt: "Return a structured value.",
schema: Schema.Struct({ value: Schema.Number }),
@@ -180,15 +181,81 @@ describe("ai.generateObject", () => {
),
)
const exit = yield* ai
.generateObject({
const error = yield* ai
.generate({
model,
prompt: "Return a structured value.",
schema: Schema.Struct({ value: Schema.Number }),
})
.pipe(Effect.provide(layer), Effect.exit)
.pipe(Effect.provide(layer), Effect.flip)
expect(exit._tag).toBe("Failure")
expect(error.message).toContain("schema decode failed")
expect(error.partial?.toolCalls[0]?.input).toEqual({ value: "not-a-number" })
}),
)
})
describe("schema on ai.stream and ai.loop", () => {
const City = Schema.Struct({ city: Schema.String })
const scripted = testEffect(TestLLM.testLayer())
const echo = tool({
description: "Echo a value.",
parameters: Schema.Struct({ value: Schema.String }),
execute: ({ value }) => Effect.succeed(value),
})
scripted.effect("stream puts the decoded object on finish", () =>
Effect.gen(function* () {
const client = yield* TestLLM.Test
yield* client.push(TestLLM.toolCall("call-1", "generate_object", { city: "Paris" }))
const events = Array.from(
yield* ai.stream({ model, prompt: "Pick a city.", schema: City }).pipe(Stream.runCollect),
)
const finish = events.at(-1)
expect(finish?.type === "finish" && finish.object).toEqual({ city: "Paris" })
}),
)
scripted.effect("loop runs tools, leaves the answer tool alone and decodes it on the final finish", () =>
Effect.gen(function* () {
const client = yield* TestLLM.Test
yield* client.push(TestLLM.toolCall("call-1", "echo", { value: "Paris" }))
yield* client.push(TestLLM.toolCall("call-2", "generate_object", { city: "Paris" }))
const events = Array.from(
yield* ai.loop({ model, prompt: "Pick a city.", tools: { echo }, schema: City }).pipe(Stream.runCollect),
)
expect(events.filter(LLMEvent.is.toolResult).map((event) => event.name)).toEqual(["echo"])
expect(events.filter((event) => event.type === "finish").map((event) => event.object)).toEqual([
undefined,
{ city: "Paris" },
])
expect((yield* client.requests())[0]?.toolChoice?.type).toBe("required")
}),
)
scripted.effect("loop ends at a step that calls the answer tool alongside another tool", () =>
Effect.gen(function* () {
const client = yield* TestLLM.Test
yield* client.push(
TestLLM.toolCalls(
LLMEvent.toolCall({ id: "call-1", name: "echo", input: { value: "Paris" } }),
LLMEvent.toolCall({ id: "call-2", name: "generate_object", input: { city: "Paris" } }),
),
)
const events = Array.from(
yield* ai.loop({ model, prompt: "Pick a city.", tools: { echo }, schema: City }).pipe(Stream.runCollect),
)
expect(events.some(LLMEvent.is.toolResult)).toBe(false)
expect(events.filter((event) => event.type === "finish").map((event) => event.object)).toEqual([
{ city: "Paris" },
])
expect(yield* client.requests()).toHaveLength(1)
}),
)
})
+35 -12
View File
@@ -1,6 +1,7 @@
import { Effect, Schema, Stream } from "effect"
import {
ai,
type Finish,
type LanguageModel,
type LanguageModelProviderOptions,
type LLMClientService,
@@ -21,6 +22,8 @@ const model = OpenAIChat.route
.model<ExampleProviderOptions>({ id: "example" })
type Requirements<T> = T extends Effect.Effect<infer _A, infer _E, infer R> ? R : never
type Success<T> = T extends Effect.Effect<infer A, infer _E, infer _R> ? A : never
type StreamEvent<T> = T extends Stream.Stream<infer A, infer _E, infer _R> ? A : never
type StreamRequirements<T> = T extends Stream.Stream<infer _A, infer _E, infer R> ? R : never
type Equal<A, B> = [A, B] extends [B, A] ? true : false
type Assert<T extends true> = T
@@ -49,28 +52,40 @@ ai.generate({ model, prompt: "Hello", providerOptions: { mode: "slow" } })
// @ts-expect-error Stream input keeps the selected model's provider option types.
ai.stream({ model, prompt: "Hello", providerOptions: { mode: "slow" } })
const generatedObject = ai.generateObject({
const generatedObject = ai.generate({
model,
prompt: "Hello",
schema: Schema.Struct({ answer: Schema.String }),
providerOptions: { mode: "thorough" },
})
type GenerateObjectRequirements = Assert<Equal<Requirements<typeof generatedObject>, LLMClientService>>
type StructuredOutputRequirements = Assert<Equal<Requirements<typeof generatedObject>, LLMClientService>>
type StructuredOutputValue = Assert<Equal<Success<typeof generatedObject>["object"], { readonly answer: string }>>
type StructuredOutputText = Assert<Equal<Success<typeof generatedObject>["text"], string>>
const generatedDynamicObject = ai.generateObject({
const generatedDynamicObject = ai.generate({
model,
prompt: "Hello",
jsonSchema: { type: "object" },
schema: { type: "object" },
})
type GenerateDynamicObjectRequirements = Assert<Equal<Requirements<typeof generatedDynamicObject>, LLMClientService>>
type GenerateDynamicObjectValue = Assert<Equal<Success<typeof generatedDynamicObject>["object"], unknown>>
ai.generateObject({
model,
prompt: "Hello",
jsonSchema: { type: "object" },
// @ts-expect-error Dynamic object generation uses the selected model's provider options.
providerOptions: { mode: false },
})
// @ts-expect-error Structured output keeps the selected model's provider options.
ai.generate({ model, prompt: "Hello", schema: { type: "object" }, providerOptions: { mode: false } })
// @ts-expect-error A plain request has no decoded object.
void ai.generate({ model, prompt: "Hello" }).pipe(Effect.map((response) => response.object))
type FinishObject<T> = Extract<T, { readonly type: "finish" }> extends { readonly object?: infer O } ? O : never
const streamedObject = ai.stream({ model, prompt: "Hello", schema: Schema.Struct({ answer: Schema.String }) })
type StreamObjectValue = Assert<Equal<FinishObject<StreamEvent<typeof streamedObject>>, { readonly answer: string }>>
const loopedObject = ai.loop({ model, prompt: "Hello", tools: {}, schema: Schema.Struct({ answer: Schema.String }) })
type LoopObjectValue = Assert<
Equal<
Extract<StreamEvent<typeof loopedObject>, { readonly type: "finish" }>,
Finish & { readonly object?: { readonly answer: string } }
>
>
declare const generic: LanguageModel
ai.request({ model: generic, prompt: "Hello", providerOptions: { arbitrary: { option: true } } })
@@ -81,9 +96,17 @@ void (true satisfies GenerateRequirements)
void (true satisfies StreamClientRequirements)
void (true satisfies InputGenerateRequirements)
void (true satisfies InputStreamRequirements)
void (true satisfies GenerateObjectRequirements)
void (true satisfies StructuredOutputRequirements)
void (true satisfies GenerateDynamicObjectRequirements)
void (true satisfies StructuredOutputValue)
void (true satisfies StructuredOutputText)
void (true satisfies GenerateDynamicObjectValue)
void (true satisfies StreamObjectValue)
void (true satisfies LoopObjectValue)
void AI.ai
.generate({ model, prompt: "Hello", schema: Schema.Struct({ answer: Schema.String }) })
.then((response) => response.object.answer satisfies string)
void AI.ai.generate({ model, prompt: "Hello", providerOptions: { mode: "fast" } })
void AI.ai.stream({ model, prompt: "Hello", providerOptions: { mode: "thorough" } })
void AI.ai.generate(AI.ai.request({ model, prompt: "Hello" }))
+1 -1
View File
@@ -493,7 +493,7 @@ describe("AI promise client", () => {
),
})
const response = await ai.generateObject({
const response = await ai.generate({
model: openai.chat("gpt-4o-mini"),
prompt: "Pick a city.",
schema: Schema.Struct({ city: Schema.String }),