mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-21 04:12:08 +03:00
refactor(ai): structured output via schema on generate, stream and loop (#60783)
This commit is contained in:
committed by
GitHub
Unverified
parent
1908fcb8b7
commit
e8238bae9b
@@ -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
|
||||
|
||||
@@ -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" },
|
||||
|
||||
@@ -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
@@ -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
@@ -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"
|
||||
|
||||
@@ -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">) {
|
||||
|
||||
@@ -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 }),
|
||||
|
||||
@@ -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)
|
||||
}),
|
||||
)
|
||||
})
|
||||
|
||||
@@ -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" }))
|
||||
|
||||
@@ -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 }),
|
||||
|
||||
Reference in New Issue
Block a user