@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 1,309 lines 37.4 KB
Raw
1 /**
2 * The `OpenAiClient` module provides an Effect service for OpenAI-compatible
3 * chat completions and embeddings APIs. It builds on the Effect HTTP client,
4 * adds authentication and OpenAI organization or project headers, and exposes
5 * typed helpers for non-streaming chat completions, streaming chat completions,
6 * and embedding requests.
7 *
8 * @stability unstable
9 * @since 4.0.0
10 */
11 import type * as AiError from "effect/ai/AiError"
12 import * as Array from "effect/Array"
13 import type * as Config from "effect/Config"
14 import * as Context from "effect/Context"
15 import * as Effect from "effect/Effect"
16 import * as Sse from "effect/encoding/Sse"
17 import { identity } from "effect/Function"
18 import * as Headers from "effect/http/Headers"
19 import * as HttpClient from "effect/http/HttpClient"
20 import * as HttpClientRequest from "effect/http/HttpClientRequest"
21 import * as HttpClientResponse from "effect/http/HttpClientResponse"
22 import * as Layer from "effect/Layer"
23 import * as Redacted from "effect/Redacted"
24 import * as Result from "effect/Result"
25 import * as Schema from "effect/Schema"
26 import * as Stream from "effect/Stream"
27 import * as Errors from "./internal/errors.ts"
28 import { OpenAiConfig } from "./OpenAiConfig.ts"
29
30 /**
31 * Effect service interface for OpenAI-compatible chat completions and embeddings.
32 *
33 * **Details**
34 *
35 * Exposes the configured HTTP client plus helpers for non-streaming chat
36 * completions, streaming chat completions, and embeddings. Transport and
37 * schema decoding failures are mapped to `AiError`.
38 *
39 * @stability unstable
40 * @category services
41 * @since 4.0.0
42 */
43 export interface Service {
44 readonly client: HttpClient.HttpClient
45 readonly createResponse: (
46 options: CreateResponseRequestJson
47 ) => Effect.Effect<
48 [body: CreateResponse200, response: HttpClientResponse.HttpClientResponse],
49 AiError.AiError
50 >
51 readonly createResponseStream: (
52 options: Omit<CreateResponseRequestJson, "stream" | "stream_options">
53 ) => Effect.Effect<
54 [
55 response: HttpClientResponse.HttpClientResponse,
56 stream: Stream.Stream<CreateResponse200Sse, AiError.AiError>
57 ],
58 AiError.AiError
59 >
60 readonly createEmbedding: (
61 options: CreateEmbeddingRequestJson
62 ) => Effect.Effect<CreateEmbedding200, AiError.AiError>
63 }
64
65 /**
66 * Service tag for the OpenAI-compatible chat completions and embeddings client.
67 *
68 * **When to use**
69 *
70 * Use when building effects that depend on the low-level OpenAI-compatible
71 * client through context rather than receiving the client as a value.
72 *
73 * **Details**
74 *
75 * The tagged service is the `Service` interface produced by `make` and provided
76 * by `layer` or `layerConfig`.
77 *
78 * @see {@link Service} for the operations provided by the service
79 * @see {@link make} for constructing the service from explicit options
80 * @see {@link layer} for providing the service from explicit options
81 * @see {@link layerConfig} for loading client settings from `Config`
82 *
83 * @stability unstable
84 * @category services
85 * @since 4.0.0
86 */
87 export class OpenAiClient extends Context.Service<OpenAiClient, Service>()(
88 "@effect/ai-openai-compat/OpenAiClient"
89 ) {}
90
91 /**
92 * Configuration options used to construct an OpenAI-compatible client.
93 *
94 * @stability unstable
95 * @category options
96 * @since 4.0.0
97 */
98 export type Options = {
99 readonly apiKey?: Redacted.Redacted<string> | undefined
100 readonly apiUrl?: string | undefined
101 readonly organizationId?: Redacted.Redacted<string> | undefined
102 readonly projectId?: Redacted.Redacted<string> | undefined
103 readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
104 }
105
106 const RedactedOpenAiHeaders = {
107 OpenAiOrganization: "openai-organization",
108 OpenAiProject: "openai-project"
109 }
110
111 const withRedactedHeaders = Effect.updateService(
112 Headers.CurrentRedactedNames,
113 Array.appendAll(Object.values(RedactedOpenAiHeaders))
114 )
115
116 /**
117 * Constructs an OpenAI-compatible client service from explicit options.
118 *
119 * **When to use**
120 *
121 * Use when you need the OpenAI-compatible client service value inside an effect.
122 *
123 * **Details**
124 *
125 * The returned service uses the current `HttpClient`, prepends `apiUrl` or
126 * `https://api.openai.com/v1`, adds authentication and OpenAI
127 * organization/project headers, accepts JSON responses, and applies
128 * `transformClient` when provided.
129 *
130 * **Gotchas**
131 *
132 * A scoped `OpenAiConfig.withClientTransform` is applied when request helpers
133 * run, after the `transformClient` option supplied to `make`.
134 *
135 * @see {@link layer} for providing this client from explicit options
136 * @see {@link layerConfig} for loading client settings from `Config`
137 *
138 * @stability unstable
139 * @category constructors
140 * @since 4.0.0
141 */
142 export const make = Effect.fnUntraced(
143 function*(options: Options): Effect.fn.Return<Service, never, HttpClient.HttpClient> {
144 const baseClient = yield* HttpClient.HttpClient
145
146 const httpClient = baseClient.pipe(
147 HttpClient.mapRequest((request) =>
148 request.pipe(
149 HttpClientRequest.prependUrl(options.apiUrl ?? "https://api.openai.com/v1"),
150 options.apiKey !== undefined
151 ? HttpClientRequest.bearerToken(Redacted.value(options.apiKey))
152 : identity,
153 options.organizationId !== undefined
154 ? HttpClientRequest.setHeader(
155 RedactedOpenAiHeaders.OpenAiOrganization,
156 Redacted.value(options.organizationId)
157 )
158 : identity,
159 options.projectId !== undefined
160 ? HttpClientRequest.setHeader(
161 RedactedOpenAiHeaders.OpenAiProject,
162 Redacted.value(options.projectId)
163 )
164 : identity,
165 HttpClientRequest.acceptJson
166 )
167 ),
168 options.transformClient !== undefined
169 ? options.transformClient
170 : identity
171 )
172
173 const resolveHttpClient = Effect.map(
174 OpenAiConfig.getOrUndefined,
175 (config) =>
176 config?.transformClient !== undefined
177 ? config.transformClient(httpClient)
178 : httpClient
179 )
180
181 const decodeResponse = HttpClientResponse.schemaBodyJson(ChatCompletionResponse)
182
183 const createResponse = (
184 payload: CreateResponseRequestJson
185 ): Effect.Effect<
186 [body: CreateResponse200, response: HttpClientResponse.HttpClientResponse],
187 AiError.AiError
188 > =>
189 resolveHttpClient.pipe(
190 Effect.flatMap((client) =>
191 HttpClientRequest.post("/chat/completions").pipe(
192 HttpClientRequest.bodyJsonUnsafe(payload),
193 HttpClient.filterStatusOk(client).execute,
194 Effect.flatMap((response) =>
195 Effect.map(decodeResponse(response), (
196 body
197 ): [CreateResponse200, HttpClientResponse.HttpClientResponse] => [
198 body,
199 response
200 ])
201 ),
202 Effect.catchTags({
203 HttpClientError: (error) => Errors.mapHttpClientError(error, "createResponse"),
204 SchemaError: (error) => Effect.fail(Errors.mapSchemaError(error, "createResponse"))
205 })
206 )
207 ),
208 withRedactedHeaders
209 )
210
211 const buildResponseStream = (
212 response: HttpClientResponse.HttpClientResponse
213 ): [
214 HttpClientResponse.HttpClientResponse,
215 Stream.Stream<CreateResponse200Sse, AiError.AiError>
216 ] => {
217 const stream = response.stream.pipe(
218 Stream.decodeText(),
219 Stream.pipeThroughChannel(Sse.decode()),
220 Stream.filterMap((event) => {
221 const data = decodeChatCompletionSseData(event.data)
222 return data !== undefined ? Result.succeed(data) : Result.failVoid
223 }),
224 Stream.takeUntil((event) => event === "[DONE]"),
225 Stream.catchTags({
226 Retry: (error) => Stream.die(error),
227 SseError: (error) => Stream.fail(Errors.mapSseError(error, "createResponseStream")),
228 HttpClientError: (error) => Stream.fromEffect(Errors.mapHttpClientError(error, "createResponseStream"))
229 })
230 ) as any
231 return [response, stream]
232 }
233
234 const createResponseStream: Service["createResponseStream"] = (payload) =>
235 resolveHttpClient.pipe(
236 Effect.flatMap((client) =>
237 HttpClientRequest.post("/chat/completions").pipe(
238 HttpClientRequest.bodyJsonUnsafe({
239 ...payload,
240 stream: true,
241 stream_options: {
242 include_usage: true
243 }
244 }),
245 HttpClient.filterStatusOk(client).execute,
246 Effect.map(buildResponseStream),
247 Effect.catchTag(
248 "HttpClientError",
249 (error) => Errors.mapHttpClientError(error, "createResponseStream")
250 )
251 )
252 ),
253 withRedactedHeaders
254 )
255
256 const decodeEmbedding = HttpClientResponse.schemaBodyJson(CreateEmbeddingResponseSchema)
257
258 const createEmbedding = (
259 payload: CreateEmbeddingRequestJson
260 ): Effect.Effect<CreateEmbedding200, AiError.AiError> =>
261 resolveHttpClient.pipe(
262 Effect.flatMap((client) =>
263 HttpClientRequest.post("/embeddings").pipe(
264 HttpClientRequest.bodyJsonUnsafe(payload),
265 HttpClient.filterStatusOk(client).execute,
266 Effect.flatMap(decodeEmbedding),
267 Effect.catchTags({
268 HttpClientError: (error) => Errors.mapHttpClientError(error, "createEmbedding"),
269 SchemaError: (error) => Effect.fail(Errors.mapSchemaError(error, "createEmbedding"))
270 })
271 )
272 ),
273 withRedactedHeaders
274 )
275
276 return OpenAiClient.of({
277 client: httpClient,
278 createResponse,
279 createResponseStream,
280 createEmbedding
281 })
282 },
283 withRedactedHeaders
284 )
285
286 /**
287 * Creates a layer that provides an OpenAI-compatible client from explicit options.
288 *
289 * **When to use**
290 *
291 * Use to install `OpenAiClient` in an application layer when the client options
292 * are already available as values rather than loaded from `Config`.
293 *
294 * @see {@link make} for constructing the client service effectfully
295 * @see {@link layerConfig} for loading client settings from `Config`
296 *
297 * @stability unstable
298 * @category layers
299 * @since 4.0.0
300 */
301 export const layer = (options: Options): Layer.Layer<OpenAiClient, never, HttpClient.HttpClient> =>
302 Layer.effect(OpenAiClient, make(options))
303
304 /**
305 * Creates a layer that loads OpenAI-compatible client settings from `Config`
306 * values before constructing the service.
307 *
308 * **When to use**
309 *
310 * Use when you need client settings for OpenAI-compatible APIs to be read from
311 * Effect `Config` values while providing `OpenAiClient` as a layer.
312 *
313 * **Details**
314 *
315 * Only config values supplied in `options` are loaded. Omitted fields are
316 * passed to `make` as `undefined`, and `transformClient` is forwarded as a
317 * plain option.
318 *
319 * @see {@link make} for constructing the client service effectfully
320 * @see {@link layer} for providing the client from already-resolved options
321 *
322 * @stability unstable
323 * @category layers
324 * @since 4.0.0
325 */
326 export const layerConfig = (options?: {
327 readonly apiKey?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
328 readonly apiUrl?: Config.Config<string> | undefined
329 readonly organizationId?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
330 readonly projectId?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
331 readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
332 }): Layer.Layer<OpenAiClient, Config.ConfigError, HttpClient.HttpClient> =>
333 Layer.effect(
334 OpenAiClient,
335 Effect.gen(function*() {
336 const apiKey = options?.apiKey !== undefined
337 ? yield* options.apiKey :
338 undefined
339 const apiUrl = options?.apiUrl !== undefined
340 ? yield* options.apiUrl :
341 undefined
342 const organizationId = options?.organizationId !== undefined
343 ? yield* options.organizationId
344 : undefined
345 const projectId = options?.projectId !== undefined
346 ? yield* options.projectId :
347 undefined
348 return yield* make({
349 apiKey,
350 apiUrl,
351 organizationId,
352 projectId,
353 transformClient: options?.transformClient
354 })
355 })
356 )
357
358 type JsonObject = { readonly [x: string]: Schema.Json }
359
360 /**
361 * Optional response fields that can be requested with the `include` parameter.
362 *
363 * @stability unstable
364 * @category models
365 * @since 4.0.0
366 */
367 export type IncludeEnum =
368 | "message.input_image.image_url"
369 | "reasoning.encrypted_content"
370 | "message.output_text.logprobs"
371
372 /**
373 * Lifecycle status shared by message, reasoning, and tool-call items.
374 *
375 * @stability unstable
376 * @category models
377 * @since 4.0.0
378 */
379 export type MessageStatus = "in_progress" | "completed" | "incomplete"
380
381 type InputTextContent = {
382 readonly type: "input_text"
383 readonly text: string
384 }
385
386 type InputImageContent = {
387 readonly type: "input_image"
388 readonly image_url?: string | null | undefined
389 readonly file_id?: string | null | undefined
390 readonly detail?: "low" | "high" | "auto" | null | undefined
391 }
392
393 type InputFileContent = {
394 readonly type: "input_file"
395 readonly file_id?: string | null | undefined
396 readonly filename?: string | undefined
397 readonly file_url?: string | undefined
398 readonly file_data?: string | undefined
399 }
400
401 /**
402 * Content blocks accepted in input messages.
403 *
404 * @stability unstable
405 * @category models
406 * @since 4.0.0
407 */
408 export type InputContent = InputTextContent | InputImageContent | InputFileContent
409
410 /**
411 * Text content block used for model-provided reasoning summaries.
412 *
413 * @stability unstable
414 * @category models
415 * @since 4.0.0
416 */
417 export type SummaryTextContent = {
418 readonly type: "summary_text"
419 readonly text: string
420 }
421
422 type ReasoningTextContent = {
423 readonly type: "reasoning_text"
424 readonly text: string
425 }
426
427 type RefusalContent = {
428 readonly type: "refusal"
429 readonly refusal: string
430 }
431
432 type TextContent = {
433 readonly type: "text"
434 readonly text: string
435 }
436
437 type ComputerScreenshotContent = {
438 readonly type: "computer_screenshot"
439 readonly image_url: string | null
440 readonly file_id: string | null
441 }
442
443 type FileCitationAnnotation = {
444 readonly type: "file_citation"
445 readonly file_id: string
446 readonly index: number
447 readonly filename: string
448 }
449
450 type UrlCitationAnnotation = {
451 readonly type: "url_citation"
452 readonly url: string
453 readonly start_index: number
454 readonly end_index: number
455 readonly title: string
456 }
457
458 type ContainerFileCitationAnnotation = {
459 readonly type: "container_file_citation"
460 readonly container_id: string
461 readonly file_id: string
462 readonly start_index: number
463 readonly end_index: number
464 readonly filename: string
465 }
466
467 type FilePathAnnotation = {
468 readonly type: "file_path"
469 readonly file_id: string
470 readonly index: number
471 }
472
473 /**
474 * Citation and file-path annotations attached to output text content.
475 *
476 * @stability unstable
477 * @category models
478 * @since 4.0.0
479 */
480 export type Annotation =
481 | FileCitationAnnotation
482 | UrlCitationAnnotation
483 | ContainerFileCitationAnnotation
484 | FilePathAnnotation
485
486 type OutputTextContent = {
487 readonly type: "output_text"
488 readonly text: string
489 readonly annotations?: ReadonlyArray<Annotation> | undefined
490 readonly logprobs?: ReadonlyArray<unknown> | undefined
491 }
492
493 type OutputMessageContent =
494 | InputTextContent
495 | OutputTextContent
496 | TextContent
497 | SummaryTextContent
498 | ReasoningTextContent
499 | RefusalContent
500 | InputImageContent
501 | ComputerScreenshotContent
502 | InputFileContent
503
504 type OutputMessage = {
505 readonly id: string
506 readonly type: "message"
507 readonly role: "assistant"
508 readonly content: ReadonlyArray<OutputMessageContent>
509 readonly status: MessageStatus
510 }
511
512 /**
513 * Reasoning output item containing encrypted reasoning content, summaries, and
514 * optional reasoning text.
515 *
516 * @stability unstable
517 * @category models
518 * @since 4.0.0
519 */
520 export type ReasoningItem = {
521 readonly type: "reasoning"
522 readonly id: string
523 readonly encrypted_content?: string | null | undefined
524 readonly summary: ReadonlyArray<SummaryTextContent>
525 readonly content?: ReadonlyArray<ReasoningTextContent> | undefined
526 readonly status?: MessageStatus | undefined
527 }
528
529 type FunctionCall = {
530 readonly id?: string | undefined
531 readonly type: "function_call"
532 readonly call_id: string
533 readonly name: string
534 readonly arguments: string
535 readonly extra_content?: JsonObject | undefined
536 readonly status?: MessageStatus | undefined
537 }
538
539 type FunctionCallOutput = {
540 readonly id?: string | null | undefined
541 readonly call_id: string
542 readonly type: "function_call_output"
543 readonly output: string | ReadonlyArray<InputTextContent | InputImageContent | InputFileContent>
544 readonly status?: MessageStatus | null | undefined
545 }
546
547 type CustomToolCall = {
548 readonly type: "custom_tool_call"
549 readonly id?: string | undefined
550 readonly call_id: string
551 readonly name: string
552 readonly input: string
553 }
554
555 type CustomToolCallOutput = {
556 readonly type: "custom_tool_call_output"
557 readonly id?: string | undefined
558 readonly call_id: string
559 readonly output: string | ReadonlyArray<InputTextContent | InputImageContent | InputFileContent>
560 }
561
562 type ItemReference = {
563 readonly type?: "item_reference" | null | undefined
564 readonly id: string
565 }
566
567 /**
568 * Item shapes accepted by a Responses-style `input` field.
569 *
570 * **Details**
571 *
572 * Supports input messages, output messages, tool calls, tool outputs, reasoning
573 * items, custom tool interactions, and item references.
574 *
575 * @stability unstable
576 * @category models
577 * @since 4.0.0
578 */
579 export type InputItem =
580 | {
581 readonly role: "user" | "assistant" | "system" | "developer"
582 readonly content: string | ReadonlyArray<InputContent>
583 readonly type?: "message" | undefined
584 }
585 | {
586 readonly type?: "message" | undefined
587 readonly role: "user" | "system" | "developer"
588 readonly status?: MessageStatus | undefined
589 readonly content: ReadonlyArray<InputContent>
590 }
591 | OutputMessage
592 | FunctionCall
593 | FunctionCallOutput
594 | ReasoningItem
595 | CustomToolCallOutput
596 | CustomToolCall
597 | ItemReference
598
599 type FunctionTool = {
600 readonly type: "function"
601 readonly name: string
602 readonly description?: string | null | undefined
603 readonly parameters?: JsonObject | null | undefined
604 readonly strict?: boolean | null | undefined
605 }
606
607 type CustomToolParam = {
608 readonly type: "custom"
609 readonly name: string
610 readonly description?: string | undefined
611 readonly format?: unknown
612 }
613
614 /**
615 * Tool definitions that can be supplied to a Responses-style request.
616 *
617 * @stability unstable
618 * @category models
619 * @since 4.0.0
620 */
621 export type Tool =
622 | FunctionTool
623 | CustomToolParam
624
625 type ToolChoice =
626 | "none"
627 | "auto"
628 | "required"
629 | {
630 readonly type: "allowed_tools"
631 readonly mode: "auto" | "required"
632 readonly tools: ReadonlyArray<JsonObject>
633 }
634 | {
635 readonly type: "function"
636 readonly name: string
637 }
638 | {
639 readonly type: "custom"
640 readonly name: string
641 }
642
643 /**
644 * Text output format configuration for plain text, JSON object, or JSON Schema
645 * responses.
646 *
647 * @stability unstable
648 * @category configuration
649 * @since 4.0.0
650 */
651 export type TextResponseFormatConfiguration =
652 | {
653 readonly type: "text"
654 }
655 | {
656 readonly type: "json_schema"
657 readonly description?: string | undefined
658 readonly name: string
659 readonly schema: JsonObject
660 readonly strict?: boolean | null | undefined
661 }
662 | {
663 readonly type: "json_object"
664 }
665
666 /**
667 * Request options for creating a Responses-style response with an
668 * OpenAI-compatible provider.
669 *
670 * @stability unstable
671 * @category models
672 * @since 4.0.0
673 */
674 export type CreateResponse = {
675 readonly metadata?: Readonly<Record<string, string>> | null | undefined
676 readonly top_logprobs?: number | undefined
677 readonly temperature?: number | null | undefined
678 readonly top_p?: number | null | undefined
679 readonly user?: string | null | undefined
680 readonly safety_identifier?: string | null | undefined
681 readonly prompt_cache_key?: string | null | undefined
682 readonly service_tier?: string | undefined
683 readonly prompt_cache_retention?: "in-memory" | "24h" | null | undefined
684 readonly previous_response_id?: string | null | undefined
685 readonly model?: string | undefined
686 readonly reasoning?: unknown
687 readonly background?: boolean | null | undefined
688 readonly max_output_tokens?: number | null | undefined
689 readonly max_tool_calls?: number | null | undefined
690 readonly text?: {
691 readonly format?: TextResponseFormatConfiguration | undefined
692 readonly verbosity?: "low" | "medium" | "high" | null | undefined
693 } | undefined
694 readonly tools?: ReadonlyArray<Tool> | undefined
695 readonly tool_choice?: ToolChoice | undefined
696 readonly truncation?: "auto" | "disabled" | null | undefined
697 readonly input?: string | ReadonlyArray<InputItem> | undefined
698 readonly include?: ReadonlyArray<IncludeEnum> | null | undefined
699 readonly parallel_tool_calls?: boolean | null | undefined
700 readonly store?: boolean | null | undefined
701 readonly instructions?: string | null | undefined
702 readonly stream?: boolean | null | undefined
703 readonly conversation?: string | null | undefined
704 readonly modalities?: ReadonlyArray<"text" | "audio"> | undefined
705 readonly seed?: number | undefined
706 }
707
708 /**
709 * Token accounting reported on Responses-style response objects.
710 *
711 * @stability unstable
712 * @category models
713 * @since 4.0.0
714 */
715 export type ResponseUsage = {
716 readonly input_tokens: number
717 readonly output_tokens: number
718 readonly total_tokens: number
719 readonly input_tokens_details?: unknown
720 readonly output_tokens_details?: unknown
721 }
722
723 type OutputItem =
724 | OutputMessage
725 | FunctionCall
726 | ReasoningItem
727 | CustomToolCall
728
729 /**
730 * Responses-style response object returned by compatible providers or embedded
731 * in response stream lifecycle events.
732 *
733 * @stability unstable
734 * @category models
735 * @since 4.0.0
736 */
737 export type Response = {
738 readonly id: string
739 readonly object?: "response" | undefined
740 readonly model: string
741 readonly status?: "completed" | "failed" | "in_progress" | "cancelled" | "queued" | "incomplete" | undefined
742 readonly created_at: number
743 readonly output: ReadonlyArray<OutputItem>
744 readonly usage?: ResponseUsage | null | undefined
745 readonly incomplete_details?:
746 | {
747 readonly reason?: "max_output_tokens" | "content_filter" | undefined
748 }
749 | null
750 | undefined
751 readonly service_tier?: string | undefined
752 }
753
754 type ResponseCreatedEvent = {
755 readonly type: "response.created"
756 readonly response: Response
757 readonly sequence_number: number
758 }
759
760 type ResponseCompletedEvent = {
761 readonly type: "response.completed"
762 readonly response: Response
763 readonly sequence_number: number
764 }
765
766 type ResponseIncompleteEvent = {
767 readonly type: "response.incomplete"
768 readonly response: Response
769 readonly sequence_number: number
770 }
771
772 type ResponseFailedEvent = {
773 readonly type: "response.failed"
774 readonly response: Response
775 readonly sequence_number: number
776 }
777
778 type ResponseOutputItemAddedEvent = {
779 readonly type: "response.output_item.added"
780 readonly output_index: number
781 readonly sequence_number: number
782 readonly item: OutputItem
783 }
784
785 type ResponseOutputItemDoneEvent = {
786 readonly type: "response.output_item.done"
787 readonly output_index: number
788 readonly sequence_number: number
789 readonly item: OutputItem
790 }
791
792 type ResponseTextDeltaEvent = {
793 readonly type: "response.output_text.delta"
794 readonly item_id: string
795 readonly output_index: number
796 readonly content_index: number
797 readonly delta: string
798 readonly sequence_number: number
799 readonly logprobs?: ReadonlyArray<unknown> | undefined
800 }
801
802 type ResponseOutputTextAnnotationAddedEvent = {
803 readonly type: "response.output_text.annotation.added"
804 readonly item_id: string
805 readonly output_index: number
806 readonly content_index: number
807 readonly annotation_index: number
808 readonly sequence_number: number
809 readonly annotation: Annotation
810 }
811
812 type ResponseFunctionCallArgumentsDeltaEvent = {
813 readonly type: "response.function_call_arguments.delta"
814 readonly item_id: string
815 readonly output_index: number
816 readonly sequence_number: number
817 readonly delta: string
818 }
819
820 type ResponseReasoningSummaryPartAddedEvent = {
821 readonly type: "response.reasoning_summary_part.added"
822 readonly item_id: string
823 readonly output_index: number
824 readonly summary_index: number
825 readonly sequence_number: number
826 readonly part: SummaryTextContent
827 }
828
829 type ResponseReasoningSummaryPartDoneEvent = {
830 readonly type: "response.reasoning_summary_part.done"
831 readonly item_id: string
832 readonly output_index: number
833 readonly summary_index: number
834 readonly sequence_number: number
835 readonly part: SummaryTextContent
836 }
837
838 type ResponseReasoningSummaryTextDeltaEvent = {
839 readonly type: "response.reasoning_summary_text.delta"
840 readonly item_id: string
841 readonly output_index: number
842 readonly summary_index: number
843 readonly delta: string
844 readonly sequence_number: number
845 }
846
847 type ResponseErrorEvent = {
848 readonly type: "error"
849 readonly code: string | null
850 readonly message: string
851 readonly param: string | null
852 readonly sequence_number: number
853 }
854
855 type UnknownResponseStreamEvent = {
856 readonly type: string
857 readonly [key: string]: unknown
858 }
859
860 /**
861 * Server-sent event shapes emitted by Responses-style response streams.
862 *
863 * @stability unstable
864 * @category streaming
865 * @since 4.0.0
866 */
867 export type ResponseStreamEvent =
868 | ResponseCreatedEvent
869 | ResponseCompletedEvent
870 | ResponseIncompleteEvent
871 | ResponseFailedEvent
872 | ResponseOutputItemAddedEvent
873 | ResponseOutputItemDoneEvent
874 | ResponseTextDeltaEvent
875 | ResponseOutputTextAnnotationAddedEvent
876 | ResponseFunctionCallArgumentsDeltaEvent
877 | ResponseReasoningSummaryPartAddedEvent
878 | ResponseReasoningSummaryPartDoneEvent
879 | ResponseReasoningSummaryTextDeltaEvent
880 | ResponseErrorEvent
881 | UnknownResponseStreamEvent
882
883 /**
884 * Represents one embedding item returned by an OpenAI-compatible embeddings API.
885 *
886 * **Details**
887 *
888 * The embedding can be returned either as a numeric vector or as a base64-encoded
889 * string. The `index` field identifies the input item that produced this
890 * embedding.
891 *
892 * @stability unstable
893 * @category models
894 * @since 4.0.0
895 */
896 export type Embedding = {
897 readonly embedding: ReadonlyArray<number> | string
898 readonly index: number
899 readonly object?: string | undefined
900 }
901
902 /**
903 * Request payload for the embeddings endpoint.
904 *
905 * @stability unstable
906 * @category models
907 * @since 4.0.0
908 */
909 export type CreateEmbeddingRequest = {
910 readonly input: string | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<ReadonlyArray<number>>
911 readonly model: string
912 readonly encoding_format?: "float" | "base64" | undefined
913 readonly dimensions?: number | undefined
914 readonly user?: string | undefined
915 }
916
917 /**
918 * Successful response payload returned by the embeddings endpoint.
919 *
920 * @stability unstable
921 * @category models
922 * @since 4.0.0
923 */
924 export type CreateEmbeddingResponse = {
925 readonly data: ReadonlyArray<Embedding>
926 readonly model: string
927 readonly object?: "list" | undefined
928 readonly usage?: {
929 readonly prompt_tokens: number
930 readonly total_tokens: number
931 } | undefined
932 }
933
934 /**
935 * JSON request body accepted by the embeddings endpoint.
936 *
937 * @stability unstable
938 * @category models
939 * @since 4.0.0
940 */
941 export type CreateEmbeddingRequestJson = CreateEmbeddingRequest
942 /**
943 * Decoded successful embeddings response body.
944 *
945 * @stability unstable
946 * @category models
947 * @since 4.0.0
948 */
949 export type CreateEmbedding200 = CreateEmbeddingResponse
950 /**
951 * Structured content parts accepted in chat completion messages.
952 *
953 * @stability unstable
954 * @category models
955 * @since 4.0.0
956 */
957 export type ChatCompletionContentPart =
958 | {
959 readonly type: "text"
960 readonly text: string
961 }
962 | {
963 readonly type: "image_url"
964 readonly image_url: {
965 readonly url: string
966 readonly detail?: "low" | "high" | "auto" | undefined
967 }
968 }
969 /**
970 * Tool call data attached to an assistant chat completion message.
971 *
972 * @stability unstable
973 * @category models
974 * @since 4.0.0
975 */
976 export type ChatCompletionRequestToolCall = {
977 readonly id: string
978 readonly type: "function"
979 readonly function: {
980 readonly name: string
981 readonly arguments: string
982 }
983 readonly extra_content?: JsonObject | undefined
984 }
985 /**
986 * Message shapes accepted by the chat completions endpoint.
987 *
988 * @stability unstable
989 * @category models
990 * @since 4.0.0
991 */
992 export type ChatCompletionRequestMessage =
993 | {
994 readonly role: "system" | "developer" | "user" | "assistant"
995 readonly content: string | ReadonlyArray<ChatCompletionContentPart> | null
996 readonly tool_calls?: ReadonlyArray<ChatCompletionRequestToolCall> | undefined
997 /**
998 * Assistant reasoning replayed for providers that read it from
999 * `reasoning_content`.
1000 */
1001 readonly reasoning_content?: string | undefined
1002 /**
1003 * Assistant reasoning replayed for providers that read it from `reasoning`.
1004 */
1005 readonly reasoning?: string | undefined
1006 }
1007 | {
1008 readonly role: "tool"
1009 readonly tool_call_id: string
1010 readonly content: string
1011 }
1012 /**
1013 * Function tool definition accepted by the chat completions endpoint.
1014 *
1015 * @stability unstable
1016 * @category models
1017 * @since 4.0.0
1018 */
1019 export type ChatCompletionTool = {
1020 readonly type: "function"
1021 readonly function: {
1022 readonly name: string
1023 readonly description?: string | null | undefined
1024 readonly parameters?: JsonObject | undefined
1025 readonly strict?: boolean | undefined
1026 }
1027 }
1028 /**
1029 * Controls whether the model may call tools and can force a specific function.
1030 *
1031 * @stability unstable
1032 * @category configuration
1033 * @since 4.0.0
1034 */
1035 export type ChatCompletionToolChoice =
1036 | "none"
1037 | "auto"
1038 | "required"
1039 | {
1040 readonly type: "function"
1041 readonly function: {
1042 readonly name: string
1043 }
1044 }
1045 /**
1046 * JSON response format configuration for chat completion requests.
1047 *
1048 * @stability unstable
1049 * @category configuration
1050 * @since 4.0.0
1051 */
1052 export type ChatCompletionResponseFormat =
1053 | {
1054 readonly type: "json_object"
1055 }
1056 | {
1057 readonly type: "json_schema"
1058 readonly json_schema: {
1059 readonly name: string
1060 readonly schema: JsonObject
1061 readonly description?: string | undefined
1062 readonly strict?: boolean | undefined
1063 }
1064 }
1065 /**
1066 * Request payload for the OpenAI-compatible chat completions endpoint.
1067 *
1068 * @stability unstable
1069 * @category models
1070 * @since 4.0.0
1071 */
1072 export type ChatCompletionRequest = {
1073 readonly model: string
1074 readonly messages: ReadonlyArray<ChatCompletionRequestMessage>
1075 readonly temperature?: number | null | undefined
1076 readonly top_p?: number | null | undefined
1077 readonly max_tokens?: number | null | undefined
1078 readonly user?: string | null | undefined
1079 readonly seed?: number | undefined
1080 readonly parallel_tool_calls?: boolean | null | undefined
1081 readonly response_format?: ChatCompletionResponseFormat | undefined
1082 readonly tools?: ReadonlyArray<ChatCompletionTool> | undefined
1083 readonly tool_choice?: ChatCompletionToolChoice | undefined
1084 readonly service_tier?: string | undefined
1085 readonly reasoning?: unknown
1086 readonly stream?: boolean | undefined
1087 readonly stream_options?: {
1088 readonly include_usage?: boolean | undefined
1089 } | undefined
1090 readonly [x: string]: unknown
1091 }
1092 /**
1093 * JSON request body used by this client when creating a chat completion response.
1094 *
1095 * @stability unstable
1096 * @category models
1097 * @since 4.0.0
1098 */
1099 export type CreateResponseRequestJson = ChatCompletionRequest
1100 /**
1101 * Decoded successful chat completion response body returned by `createResponse`.
1102 *
1103 * @stability unstable
1104 * @category models
1105 * @since 4.0.0
1106 */
1107 export type CreateResponse200 = ChatCompletionResponse
1108 /**
1109 * Decoded server-sent event payload emitted by `createResponseStream`.
1110 *
1111 * @stability unstable
1112 * @category streaming
1113 * @since 4.0.0
1114 */
1115 export type CreateResponse200Sse = ChatCompletionStreamEvent
1116
1117 const EmbeddingSchema = Schema.Struct({
1118 embedding: Schema.Union([Schema.Array(Schema.Finite), Schema.String]),
1119 index: Schema.Int,
1120 object: Schema.optionalKey(Schema.String)
1121 })
1122
1123 const CreateEmbeddingResponseSchema = Schema.Struct({
1124 data: Schema.Array(EmbeddingSchema),
1125 model: Schema.String,
1126 object: Schema.optionalKey(Schema.Literal("list")),
1127 usage: Schema.optionalKey(Schema.Struct({
1128 prompt_tokens: Schema.Int,
1129 total_tokens: Schema.Int
1130 }))
1131 })
1132
1133 const ChatCompletionToolFunction = Schema.Struct({
1134 name: Schema.String,
1135 arguments: Schema.optionalKey(Schema.String)
1136 })
1137
1138 const ChatCompletionToolFunctionDelta = Schema.Struct({
1139 // Some OpenAI-compatible providers (e.g. Fireworks) send `name: null` on
1140 // streamed tool-call continuation fragments. `name` must be nullable, else
1141 // the whole chunk fails validation and its argument delta is dropped.
1142 name: Schema.optionalKey(Schema.NullOr(Schema.String)),
1143 arguments: Schema.optionalKey(Schema.String)
1144 })
1145
1146 const ChatCompletionToolCall = Schema.Struct({
1147 id: Schema.optionalKey(Schema.String),
1148 index: Schema.optionalKey(Schema.Int),
1149 type: Schema.optionalKey(Schema.String),
1150 extra_content: Schema.optionalKey(Schema.NullOr(Schema.JsonObject)),
1151 function: Schema.optionalKey(ChatCompletionToolFunction)
1152 })
1153
1154 const ChatCompletionToolCallDelta = Schema.Struct({
1155 // Some providers send `id: null` on tool-call continuation fragments.
1156 id: Schema.optionalKey(Schema.NullOr(Schema.String)),
1157 index: Schema.optionalKey(Schema.Int),
1158 type: Schema.optionalKey(Schema.String),
1159 extra_content: Schema.optionalKey(Schema.NullOr(Schema.JsonObject)),
1160 function: Schema.optionalKey(ChatCompletionToolFunctionDelta)
1161 })
1162
1163 const ChatCompletionMessage = Schema.Struct({
1164 role: Schema.optionalKey(Schema.String),
1165 content: Schema.optionalKey(Schema.NullOr(Schema.String)),
1166 reasoning: Schema.optionalKey(Schema.NullOr(Schema.String)),
1167 reasoning_content: Schema.optionalKey(Schema.NullOr(Schema.String)),
1168 tool_calls: Schema.optionalKey(Schema.Array(ChatCompletionToolCall))
1169 })
1170
1171 const ChatCompletionDelta = Schema.Struct({
1172 // Some providers send `role: null` on streamed text deltas.
1173 role: Schema.optionalKey(Schema.NullOr(Schema.String)),
1174 content: Schema.optionalKey(Schema.NullOr(Schema.String)),
1175 reasoning: Schema.optionalKey(Schema.NullOr(Schema.String)),
1176 reasoning_content: Schema.optionalKey(Schema.NullOr(Schema.String)),
1177 // Some OpenAI-compatible providers send `tool_calls: null` when a streamed
1178 // chunk contains only text. Accepting null keeps the text-bearing chunk from
1179 // being classified as an unknown event.
1180 tool_calls: Schema.optionalKey(Schema.NullOr(Schema.Array(ChatCompletionToolCallDelta)))
1181 })
1182
1183 const ChatCompletionChoice = Schema.Struct({
1184 index: Schema.Int,
1185 finish_reason: Schema.optionalKey(Schema.NullOr(Schema.String)),
1186 message: Schema.optionalKey(ChatCompletionMessage),
1187 delta: Schema.optionalKey(ChatCompletionDelta)
1188 })
1189
1190 const ChatCompletionUsage = Schema.Struct({
1191 prompt_tokens: Schema.Int,
1192 completion_tokens: Schema.Int,
1193 total_tokens: Schema.Int,
1194 prompt_tokens_details: Schema.optionalKey(Schema.Any),
1195 completion_tokens_details: Schema.optionalKey(Schema.Any)
1196 })
1197
1198 const ChatCompletionResponse = Schema.Struct({
1199 id: Schema.String,
1200 model: Schema.String,
1201 created: Schema.Int,
1202 choices: Schema.Array(ChatCompletionChoice),
1203 usage: Schema.optionalKey(Schema.NullOr(ChatCompletionUsage)),
1204 service_tier: Schema.optionalKey(Schema.String)
1205 })
1206
1207 const ChatCompletionChunk = Schema.Struct({
1208 id: Schema.String,
1209 model: Schema.String,
1210 created: Schema.Int,
1211 choices: Schema.Array(ChatCompletionChoice),
1212 usage: Schema.optionalKey(Schema.NullOr(ChatCompletionUsage)),
1213 service_tier: Schema.optionalKey(Schema.String)
1214 })
1215
1216 /**
1217 * Decoded tool-call object from a chat completion response or streaming chunk.
1218 *
1219 * @stability unstable
1220 * @category models
1221 * @since 4.0.0
1222 */
1223 export type ChatCompletionToolCall = typeof ChatCompletionToolCall.Type
1224 /**
1225 * Decoded message object from a non-streaming chat completion choice.
1226 *
1227 * @stability unstable
1228 * @category models
1229 * @since 4.0.0
1230 */
1231 export type ChatCompletionMessage = typeof ChatCompletionMessage.Type
1232 /**
1233 * Decoded choice object returned by chat completion responses and chunks.
1234 *
1235 * @stability unstable
1236 * @category models
1237 * @since 4.0.0
1238 */
1239 export type ChatCompletionChoice = typeof ChatCompletionChoice.Type
1240 /**
1241 * Decoded token usage summary returned by chat completions.
1242 *
1243 * @stability unstable
1244 * @category models
1245 * @since 4.0.0
1246 */
1247 export type ChatCompletionUsage = typeof ChatCompletionUsage.Type
1248 /**
1249 * Decoded successful response from the chat completions endpoint.
1250 *
1251 * @stability unstable
1252 * @category models
1253 * @since 4.0.0
1254 */
1255 export type ChatCompletionResponse = typeof ChatCompletionResponse.Type
1256 /**
1257 * Decoded streaming chunk emitted by the chat completions endpoint.
1258 *
1259 * @stability unstable
1260 * @category streaming
1261 * @since 4.0.0
1262 */
1263 export type ChatCompletionChunk = typeof ChatCompletionChunk.Type
1264 /**
1265 * A parsed chat completion event that does not match the expected chunk schema.
1266 *
1267 * @stability unstable
1268 * @category streaming
1269 * @since 4.0.0
1270 */
1271 export interface UnknownChatCompletionEvent {
1272 readonly _tag: "UnknownChatCompletionEvent"
1273 readonly data: unknown
1274 }
1275 /**
1276 * Streaming chat completion event, including decoded chunks, unknown parsed
1277 * events, and the `[DONE]` sentinel.
1278 *
1279 * @stability unstable
1280 * @category streaming
1281 * @since 4.0.0
1282 */
1283 export type ChatCompletionStreamEvent = ChatCompletionChunk | UnknownChatCompletionEvent | "[DONE]"
1284
1285 const parseJson = (value: string): unknown => {
1286 try {
1287 return JSON.parse(value)
1288 } catch {
1289 return undefined
1290 }
1291 }
1292
1293 const isChatCompletionChunk = Schema.is(ChatCompletionChunk)
1294
1295 const decodeChatCompletionSseData = (
1296 data: string
1297 ): ChatCompletionStreamEvent | undefined => {
1298 if (data === "[DONE]") {
1299 return data
1300 }
1301 const parsed = parseJson(data)
1302 if (parsed === undefined) {
1303 return undefined
1304 }
1305 return isChatCompletionChunk(parsed) ? parsed : {
1306 _tag: "UnknownChatCompletionEvent",
1307 data: parsed
1308 }
1309 }