diff --git a/packages/ai/README.md b/packages/ai/README.md index 1299a0925d1..c0fe51c7808 100644 --- a/packages/ai/README.md +++ b/packages/ai/README.md @@ -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 diff --git a/packages/ai/example/tutorial.ts b/packages/ai/example/tutorial.ts index 6da24e57cd2..3dcb380475e 100644 --- a/packages/ai/example/tutorial.ts +++ b/packages/ai/example/tutorial.ts @@ -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" }, diff --git a/packages/ai/src/effect.ts b/packages/ai/src/effect.ts index 35ffa524b0e..7bde72a2c3f 100644 --- a/packages/ai/src/effect.ts +++ b/packages/ai/src/effect.ts @@ -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, diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts index 9770a5a9f3e..44aaed981fa 100644 --- a/packages/ai/src/index.ts +++ b/packages/ai/src/index.ts @@ -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 = (options: Options = {}) => { ), ) - function generateObject>( - input: GenerateObjectOptions, - options?: RunOptions, - ): Promise>> - function generateObject( - input: GenerateObjectDynamicOptions, - options?: RunOptions, - ): Promise> - function generateObject( - input: GenerateObjectOptions> | GenerateObjectDynamicOptions, - options?: RunOptions, - ) { - return run("schema" in input ? LLM.generateObject(input) : LLM.generateObject(input), options) + function generate( + input: ObjectInput, + options?: StreamOptions & RunOptions, + ): Promise>> + function generate( + input: RequestInput | LLMRequest, + options?: StreamOptions & RunOptions, + ): Promise + function generate(input: ObjectInput | RequestInput | LLMRequest, options?: StreamOptions & RunOptions) { + return run(LLM.generate(input, options), options) + } + + function stream( + input: ObjectInput, + options?: StreamOptions & RunOptions, + ): AsyncIterable>> + function stream( + input: RequestInput | LLMRequest, + options?: StreamOptions & RunOptions, + ): AsyncIterable + function stream(input: ObjectInput | RequestInput | LLMRequest, options?: StreamOptions & RunOptions) { + return iterate(LLM.stream(input, options), options) + } + + function loop( + input: LoopInput & { readonly schema: S }, + options?: StreamOptions & RunOptions, + ): AsyncIterable>> + function loop( + input: LoopInput, + options?: StreamOptions & RunOptions, + ): AsyncIterable + 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 = (options: Options = {}) => { ) }, request: LLM.request, - generate: ( - input: RequestInput | LLMRequest, - options?: StreamOptions & RunOptions, - ) => run(LLM.generate(input, options), options), - stream: ( - input: RequestInput | 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: (input: LoopInput, 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, diff --git a/packages/ai/src/llm.ts b/packages/ai/src/llm.ts index 46580ae7d12..23cf247aa16 100644 --- a/packages/ai/src/llm.ts +++ b/packages/ai/src/llm.ts @@ -12,6 +12,7 @@ import { Message, LanguageModel, SystemPart, + type Finish, ToolChoice, ToolEntry, type ContentPart, @@ -38,20 +39,74 @@ export type RequestInput | JsonSchema.JsonSchema + +export type OutputType = S extends Schema.Top ? Schema.Schema.Type : unknown + +export type ObjectInput< + S extends OutputSchema, + SelectedLanguageModel extends LanguageModel = LanguageModel, +> = RequestInput & { readonly schema: S } + +export type ObjectResponse = LLMResponse & { readonly object: T } + +/** Stream events for a request with `schema`: the `finish` event carries the decoded `object`. */ +export type ObjectEvent = Exclude | (Finish & { readonly object: T }) + +/** Loop events for a request with `schema`: the final step's `finish` event carries the decoded `object`. */ +export type LoopObjectEvent = Exclude | (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( + input: ObjectInput, + options?: StreamOptions, +): Effect.Effect>, AIError, Service> export function generate( input: RequestInput | LLMRequest, options?: StreamOptions, ): Effect.Effect -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( + input: ObjectInput, + options?: StreamOptions, +): Stream.Stream>, AIError, Service> export function stream( input: RequestInput | LLMRequest, options?: StreamOptions, ): Stream.Stream -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 = Omit< @@ -66,27 +121,48 @@ export type LoopInput