Something went wrong. Try again.
opencode v2 mirror
Something went wrong. Try again.
TypeScript
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263import { Config, Effect, Formatter, Layer, Schema, Stream } from "effect"import { NodeFileSystem } from "@effect/platform-node"import { Image, ImageClient, LLM, LLMClient, LLMRequest, Media, Message, ProviderID, Tool, ToolRuntime,} from "@opencode/ai"import { Route, Auth, Endpoint, Framing, Protocol, RequestExecutor } from "@opencode/ai/route"import { OpenAI } from "@opencode/ai/providers"
/** * A runnable walkthrough of the LLM package use-site API. * * Run from `packages/ai` with an OpenAI key in the environment: * * OPENAI_API_KEY=... bun example/tutorial.ts * * The file is intentionally written as a normal TypeScript program. You can * hover imports and local values to see how the public API is typed. */
const apiKey = Config.redacted("OPENAI_API_KEY")
// 1. Configure a provider. The configured facade records provider identity,// deployment options, authentication, and defaults. Per-modality selectors pick// the API: `.responses(...)` / `.chat(...)` for LLM calls and `.image(...)` for// image generation.const openai = OpenAI.configure({ apiKey, generation: { maxTokens: 160 }, providerOptions: { store: false, },})const model = openai.responses("gpt-4o-mini")
// 2. Build a provider-neutral request. This is useful when reusing one request// across generate and stream examples.//// Options can live on both the configured route/provider facade and the request://// - `generation`: common controls such as max tokens, temperature, topP/topK,// penalties, seed, and stop sequences.// - `promptCacheKey`: stable cache affinity for protocols that support it.// - `providerOptions`: model-typed provider-native behavior. For example,// OpenAI store behavior, Anthropic thinking, Gemini thinking config, or// OpenRouter routing/reasoning.// - `http`: last-resort serializable overlays for final request body, headers,// and query params. Prefer typed `providerOptions` when a field is stable.//// Route/provider options are defaults. Request options override them for this call.const request = LLM.request({ model, system: "You are concise and practical.", prompt: "Tell me a joke", generation: { maxTokens: 80, temperature: 0.7 }, promptCacheKey: "tutorial-joke",})
// 3. `generate` sends the request and collects the event stream into one// response object. `response.text` is the collected text output.const generateOnce = Effect.gen(function* () { const response = yield* LLM.generate(request)
console.log("\n== generate ==") console.log("generated text:", response.text) console.log("usage", Formatter.formatJson(response.usage, { space: 2 }))})
// 4. `stream` exposes provider output as common `LLMEvent`s for UIs that want// incremental text, reasoning, tool input, usage, or finish events.const streamText = LLM.stream(request).pipe( Stream.tap((event) => Effect.sync(() => { if (event.type === "text-delta") process.stdout.write(`\ntext: ${event.text}`) if (event.type === "finish") process.stdout.write( `\nfinish: ${event.reason.normalized}${event.reason.raw ? ` (${event.reason.raw})` : ""}\n`, ) }), ), Stream.runDrain,)
// 5. Tools are typed with Effect Schema. Provider turns remain explicit:// advertise definitions on the request, stream one turn, dispatch local calls,// then persist/build follow-up history in the enclosing product flow.const tools = { get_weather: Tool.make({ description: "Get current weather for a city.", parameters: Schema.Struct({ city: Schema.String }), success: Schema.Struct({ forecast: Schema.String }), execute: (input) => Effect.succeed({ forecast: `${input.city}: sunny, 72F` }), }),}
const streamWithTools = Effect.gen(function* () { const request = LLM.request({ model, prompt: "Use get_weather for San Francisco, then answer in one sentence.", generation: { maxTokens: 80, temperature: 0 }, tools: Tool.toDefinitions(tools), }) const events = Array.from(yield* LLM.stream(request).pipe(Stream.runCollect)) for (const event of events) { if (event.type === "tool-call") console.log("tool call", event.name, event.input) if (event.type === "text-delta") process.stdout.write(event.text) if (event.type !== "tool-call" || event.providerExecuted) continue const dispatched = yield* ToolRuntime.dispatch(tools, event) console.log("tool result", event.name, dispatched.result)
// A durable agent would persist these messages before starting another // raw model turn. This tutorial keeps the boundary visible instead. const followUp = LLMRequest.update(request, { messages: [ ...request.messages, Message.assistant([event]), Message.tool({ ...event, result: dispatched.result }), ], }) console.log("follow-up history messages:", followUp.messages.length) }})
// 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.const WeatherReport = Schema.Struct({ city: Schema.String, forecast: Schema.String, highFahrenheit: Schema.Number,})
const generateStructuredObject = Effect.gen(function* () { const response = yield* LLM.generateObject({ model, system: "Return only structured weather data.", prompt: "Give me today's weather for San Francisco.", schema: WeatherReport, generation: { maxTokens: 120, temperature: 0 }, })
console.log("\n== generateObject ==") 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 = LLM.generateObject({ model, prompt: "Extract the city and forecast from: San Francisco is sunny.", jsonSchema: { type: "object", properties: { city: { type: "string" }, forecast: { type: "string" }, }, required: ["city", "forecast"], },})
// -----------------------------------------------------------------------------// Part 2: provider composition with a fake provider// -----------------------------------------------------------------------------
// A protocol is the provider-native API shape: common request -> body, response// frames -> common events. This fake one turns text prompts into a JSON body// and treats every SSE frame as output text.const FakeBody = Schema.Struct({ model: Schema.String, input: Schema.String,})type FakeBody = Schema.Schema.Type<typeof FakeBody>
const FakeProtocol = Protocol.make<FakeBody, string, string, void>({ // Protocol ids are open strings, so external packages can define their own // protocols without changing this package. id: "fake-echo", body: { schema: FakeBody, from: (request) => Effect.succeed({ model: request.model.id, input: request.messages .flatMap((message) => message.content) .filter((part) => part.type === "text") .map((part) => part.text) .join("\n"), }), }, stream: { event: Schema.String, initial: () => undefined, step: (_, frame) => Effect.succeed([undefined, [{ type: "text-delta", id: "text-0", text: frame }]] as const), onHalt: () => [{ type: "finish", reason: { normalized: "stop" } }], },})
// A route is the runnable binding for that protocol. It adds the deployment// axes that the protocol deliberately does not know: URL, auth, and framing.const FakeAdapter = Route.make({ id: "fake-echo", provider: "fake-echo", protocol: FakeProtocol, endpoint: Endpoint.path("/v1/echo", { baseURL: "https://fake.local" }), auth: Auth.passthrough, framing: Framing.sse,})
// A provider module exports a configured facade. Configuration happens before// model selection; model selectors accept ids only.const FakeEcho = { id: ProviderID.make("fake-echo"), configure: () => ({ id: ProviderID.make("fake-echo"), model: (id: string) => FakeAdapter.model({ id }), }),}
// 8. Image generation uses the same facade and the same request/generate shape.// `response.image` is a `Media.Asset`: bytes decode lazily and are cached, and// `Media.write` persists them through the Effect `FileSystem`.const generateImage = Effect.gen(function* () { const response = yield* Image.generate({ model: openai.image("gpt-image-1-mini"), prompt: "A flat black circle centered on a plain white background.", size: "1024x1024", format: "jpeg", providerOptions: { quality: "low" }, })
console.log("\n== image ==") console.log("media type:", response.image.mediaType) console.log("bytes:", (yield* response.image.bytes()).byteLength) console.log("usage", Formatter.formatJson(response.usage, { space: 2 })) yield* Media.write(response.image, "tutorial-image.jpg").pipe(Effect.provide(NodeFileSystem.layer))})
// Provide the LLM runtime and the HTTP request executor once. Keep one path// enabled at a time so the tutorial can demonstrate generate, stream, or// tool-loop behavior without spending tokens on every example.const requestExecutorLayer = RequestExecutor.fetchLayerconst llmClientLayer = LLMClient.layer.pipe(Layer.provide(requestExecutorLayer))const imageClientLayer = ImageClient.layer.pipe(Layer.provide(requestExecutorLayer))
const program = Effect.gen(function* () { // yield* generateOnce // yield* streamText // yield* generateStructuredObject // yield* generateDynamicObject.pipe(Effect.andThen((response) => Effect.sync(() => console.log(response.object)))) // yield* generateImage yield* streamWithTools}).pipe(Effect.provide(Layer.mergeAll(requestExecutorLayer, llmClientLayer, imageClientLayer)))
Effect.runPromise(program)