@effect/ai-openai 4.0.0-beta.67 → 4.0.0-beta.68

package/src/OpenAiLanguageModel.ts

@@ -112,6 +112,9 @@ export class Config extends Context.Service<
 declare module "effect/unstable/ai/Prompt" {
   /**
    * OpenAI-specific options for file prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface FilePartOptions extends ProviderOptions {
     /**
@@ -127,6 +130,9 @@ declare module "effect/unstable/ai/Prompt" {
 
   /**
    * OpenAI-specific options for reasoning prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface ReasoningPartOptions extends ProviderOptions {
     /**
@@ -148,6 +154,9 @@ declare module "effect/unstable/ai/Prompt" {
 
   /**
    * OpenAI-specific options for assistant tool-call prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface ToolCallPartOptions extends ProviderOptions {
     /**
@@ -171,6 +180,9 @@ declare module "effect/unstable/ai/Prompt" {
 
   /**
    * OpenAI-specific options for tool-result prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface ToolResultPartOptions extends ProviderOptions {
     /**
@@ -194,6 +206,9 @@ declare module "effect/unstable/ai/Prompt" {
 
   /**
    * OpenAI-specific options for text prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
    */
   export interface TextPartOptions extends ProviderOptions {
     /**
@@ -219,6 +234,9 @@ declare module "effect/unstable/ai/Prompt" {
 declare module "effect/unstable/ai/Response" {
   /**
    * OpenAI metadata attached to a complete text response part.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface TextPartMetadata extends ProviderMetadata {
     /**
@@ -248,6 +266,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata emitted when a streamed text part starts.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface TextStartPartMetadata extends ProviderMetadata {
     /**
@@ -263,6 +284,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata emitted when a streamed text part ends.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface TextEndPartMetadata extends ProviderMetadata {
     /**
@@ -282,6 +306,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata attached to a complete reasoning response part.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ReasoningPartMetadata extends ProviderMetadata {
     /**
@@ -301,6 +328,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata emitted when a streamed reasoning part starts.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
     /**
@@ -320,6 +350,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata emitted for a streamed reasoning delta.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
     /**
@@ -335,6 +368,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata emitted when a streamed reasoning part ends.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ReasoningEndPartMetadata extends ProviderMetadata {
     /**
@@ -354,6 +390,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata attached to tool-call response parts.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface ToolCallPartMetadata extends ProviderMetadata {
     /**
@@ -369,6 +408,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata attached to document source citations.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface DocumentSourcePartMetadata extends ProviderMetadata {
     /**
@@ -422,6 +464,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata attached to URL source citations.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface UrlSourcePartMetadata extends ProviderMetadata {
     /**
@@ -445,6 +490,9 @@ declare module "effect/unstable/ai/Response" {
 
   /**
    * OpenAI metadata attached to finish response parts.
+   *
+   * @category response
+   * @since 4.0.0
    */
   export interface FinishPartMetadata extends ProviderMetadata {
     /**

package/src/OpenAiSchema.ts

@@ -20,6 +20,7 @@ const ImageDetail = Schema.Literals(["low", "high", "auto"])
  * **Details**
  * These values request additional response fields such as image URLs, encrypted reasoning content, output logprobs, code interpreter outputs, or web search sources.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const IncludeEnum = Schema.Literals([
@@ -33,6 +34,7 @@ export const IncludeEnum = Schema.Literals([
 /**
  * Type of optional `include` values accepted by OpenAI Responses requests.
  *
+ * @category models
  * @since 4.0.0
  */
 export type IncludeEnum = typeof IncludeEnum.Type
@@ -40,6 +42,7 @@ export type IncludeEnum = typeof IncludeEnum.Type
 /**
  * Schema for lifecycle statuses shared by messages, reasoning items, and tool calls.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const MessageStatus = Schema.Literals(["in_progress", "completed", "incomplete"])
@@ -47,6 +50,7 @@ export const MessageStatus = Schema.Literals(["in_progress", "completed", "incom
 /**
  * Lifecycle status shared by messages, reasoning items, and tool calls.
  *
+ * @category models
  * @since 4.0.0
  */
 export type MessageStatus = typeof MessageStatus.Type
@@ -74,6 +78,7 @@ const InputFileContent = Schema.Struct({
 /**
  * Schema for content blocks accepted in OpenAI Responses input messages.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const InputContent = Schema.Union([
@@ -85,6 +90,7 @@ export const InputContent = Schema.Union([
 /**
  * Content block accepted in OpenAI Responses input messages.
  *
+ * @category models
  * @since 4.0.0
  */
 export type InputContent = typeof InputContent.Type
@@ -92,6 +98,7 @@ export type InputContent = typeof InputContent.Type
 /**
  * Schema for a text block containing a model-provided reasoning summary.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const SummaryTextContent = Schema.Struct({
@@ -102,6 +109,7 @@ export const SummaryTextContent = Schema.Struct({
 /**
  * Text content block used for model-provided reasoning summaries.
  *
+ * @category models
  * @since 4.0.0
  */
 export type SummaryTextContent = typeof SummaryTextContent.Type
@@ -160,6 +168,7 @@ const FilePathAnnotation = Schema.Struct({
 /**
  * Schema for citation and file-path annotations attached to output text content.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const Annotation = Schema.Union([
@@ -172,6 +181,7 @@ export const Annotation = Schema.Union([
 /**
  * Citation or file-path annotation attached to output text content.
  *
+ * @category models
  * @since 4.0.0
  */
 export type Annotation = typeof Annotation.Type
@@ -206,6 +216,7 @@ const OutputMessage = Schema.Struct({
 /**
  * Schema for a reasoning output item containing encrypted content, summaries, and optional reasoning text.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const ReasoningItem = Schema.Struct({
@@ -220,6 +231,7 @@ export const ReasoningItem = Schema.Struct({
 /**
  * Reasoning output item containing encrypted content, summaries, and optional reasoning text.
  *
+ * @category models
  * @since 4.0.0
  */
 export type ReasoningItem = typeof ReasoningItem.Type
@@ -308,6 +320,7 @@ const RequestMessageItem = Schema.Struct({
 /**
  * Schema for item shapes accepted by an OpenAI Responses request `input` field.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const InputItem = Schema.Union([
@@ -328,6 +341,7 @@ export const InputItem = Schema.Union([
 /**
  * Item shape accepted by an OpenAI Responses request `input` field.
  *
+ * @category models
  * @since 4.0.0
  */
 export type InputItem = typeof InputItem.Type
@@ -367,6 +381,7 @@ const ProviderDefinedTool = Schema.StructWithRest(
 /**
  * Schema for tool definitions that can be supplied to an OpenAI Responses request.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const Tool = Schema.Union([
@@ -378,6 +393,7 @@ export const Tool = Schema.Union([
 /**
  * Tool definition that can be supplied to an OpenAI Responses request.
  *
+ * @category models
  * @since 4.0.0
  */
 export type Tool = typeof Tool.Type
@@ -385,6 +401,7 @@ export type Tool = typeof Tool.Type
 /**
  * Schema for selecting whether and which tools the model may call in a Responses request.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const ToolChoice = Schema.Union([
@@ -423,6 +440,7 @@ export const ToolChoice = Schema.Union([
 /**
  * Tool selection mode or named tool choice for a Responses request.
  *
+ * @category models
  * @since 4.0.0
  */
 export type ToolChoice = typeof ToolChoice.Type
@@ -430,6 +448,7 @@ export type ToolChoice = typeof ToolChoice.Type
 /**
  * Schema for text output format configuration, including plain text, JSON object, and JSON Schema responses.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const TextResponseFormatConfiguration = Schema.Union([
@@ -447,6 +466,7 @@ export const TextResponseFormatConfiguration = Schema.Union([
 /**
  * Text output format configuration for plain text, JSON object, or JSON Schema responses.
  *
+ * @category models
  * @since 4.0.0
  */
 export type TextResponseFormatConfiguration = typeof TextResponseFormatConfiguration.Type
@@ -454,6 +474,7 @@ export type TextResponseFormatConfiguration = typeof TextResponseFormatConfigura
 /**
  * Schema for request options used to create an OpenAI Responses API response.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const CreateResponse = Schema.Struct({
@@ -501,6 +522,7 @@ export const CreateResponse = Schema.Struct({
 /**
  * Request options used to create an OpenAI Responses API response.
  *
+ * @category models
  * @since 4.0.0
  */
 export type CreateResponse = typeof CreateResponse.Type
@@ -508,6 +530,7 @@ export type CreateResponse = typeof CreateResponse.Type
 /**
  * Schema for token accounting reported on OpenAI Responses API response objects.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const ResponseUsage = Schema.StructWithRest(
@@ -524,6 +547,7 @@ export const ResponseUsage = Schema.StructWithRest(
 /**
  * Token accounting reported on OpenAI Responses API response objects.
  *
+ * @category models
  * @since 4.0.0
  */
 export type ResponseUsage = typeof ResponseUsage.Type
@@ -623,6 +647,7 @@ const OutputItem = Schema.Union([
 /**
  * Schema for an OpenAI Responses API response object.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const Response = Schema.Struct({
@@ -645,6 +670,7 @@ export const Response = Schema.Struct({
 /**
  * OpenAI Responses API response object.
  *
+ * @category models
  * @since 4.0.0
  */
 export type Response = typeof Response.Type
@@ -824,6 +850,7 @@ const knownResponseStreamEventTypes = new Set([
 /**
  * Fallback event shape for future or provider-specific response stream events.
  *
+ * @category models
  * @since 4.0.0
  */
 export type UnknownResponseStreamEvent = {
@@ -845,6 +872,7 @@ const UnknownResponseStreamEvent = Schema.declare<UnknownResponseStreamEvent>(
 /**
  * Schema for server-sent event shapes emitted by OpenAI Responses API streams.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const ResponseStreamEvent = Schema.Union([
@@ -873,6 +901,7 @@ export const ResponseStreamEvent = Schema.Union([
 /**
  * Server-sent event shape emitted by OpenAI Responses API streams.
  *
+ * @category models
  * @since 4.0.0
  */
 export type ResponseStreamEvent = typeof ResponseStreamEvent.Type
@@ -880,6 +909,7 @@ export type ResponseStreamEvent = typeof ResponseStreamEvent.Type
 /**
  * Schema for one embedding item returned by the OpenAI embeddings API.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const Embedding = Schema.Struct({
@@ -894,6 +924,7 @@ export const Embedding = Schema.Struct({
 /**
  * One embedding item returned by the OpenAI embeddings API.
  *
+ * @category models
  * @since 4.0.0
  */
 export type Embedding = typeof Embedding.Type
@@ -901,6 +932,7 @@ export type Embedding = typeof Embedding.Type
 /**
  * Schema for the request payload sent to the OpenAI embeddings endpoint.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const CreateEmbeddingRequest = Schema.Struct({
@@ -919,6 +951,7 @@ export const CreateEmbeddingRequest = Schema.Struct({
 /**
  * Request payload sent to the OpenAI embeddings endpoint.
  *
+ * @category models
  * @since 4.0.0
  */
 export type CreateEmbeddingRequest = typeof CreateEmbeddingRequest.Type
@@ -926,6 +959,7 @@ export type CreateEmbeddingRequest = typeof CreateEmbeddingRequest.Type
 /**
  * Schema for a successful response payload returned by the OpenAI embeddings endpoint.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const CreateEmbeddingResponse = Schema.Struct({
@@ -943,6 +977,7 @@ export const CreateEmbeddingResponse = Schema.Struct({
 /**
  * Successful response payload returned by the OpenAI embeddings endpoint.
  *
+ * @category models
  * @since 4.0.0
  */
 export type CreateEmbeddingResponse = typeof CreateEmbeddingResponse.Type

package/src/OpenAiTelemetry.ts

@@ -102,8 +102,8 @@ export type WellKnownServiceTier = "auto" | "default"
  * Options accepted by `addGenAIAnnotations`, combining standard GenAI
  * telemetry attributes with optional OpenAI request and response attributes.
  *
+ * @category models
  * @since 4.0.0
- * @since models
  */
 export type OpenAiTelemetryAttributeOptions = Telemetry.GenAITelemetryAttributeOptions & {
   openai?: {
@@ -125,8 +125,8 @@ const addOpenAiResponseAttributes = Telemetry.addSpanAttributes("gen_ai.openai.r
  *
  * **NOTE**: This method will mutate the `Span` **in-place**.
  *
+ * @category tracing
  * @since 4.0.0
- * @since utilities
  */
 export const addGenAIAnnotations: {
   /**
@@ -135,8 +135,8 @@ export const addGenAIAnnotations: {
    *
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
+   * @category tracing
    * @since 4.0.0
-   * @since utilities
    */
   (options: OpenAiTelemetryAttributeOptions): (span: Span) => void
   /**
@@ -145,8 +145,8 @@ export const addGenAIAnnotations: {
    *
    * **NOTE**: This method will mutate the `Span` **in-place**.
    *
+   * @category tracing
    * @since 4.0.0
-   * @since utilities
    */
   (span: Span, options: OpenAiTelemetryAttributeOptions): void
 } = dual(2, (span: Span, options: OpenAiTelemetryAttributeOptions) => {

package/src/index.ts

@@ -25,6 +25,22 @@ export * as OpenAiClient from "./OpenAiClient.ts"
 export * as OpenAiClientGenerated from "./OpenAiClientGenerated.ts"
 
 /**
+ * The `OpenAiConfig` module provides contextual configuration for the
+ * `@effect/ai-openai` integration. It is used to customize how OpenAI clients
+ * are built and interpreted without threading configuration through every API
+ * call manually.
+ *
+ * The primary use case is installing an HTTP client transform with
+ * {@link withClientTransform}. This lets applications adapt the underlying
+ * OpenAI HTTP client for cross-cutting concerns such as custom middleware,
+ * instrumentation, proxying, or request policy changes while keeping the
+ * OpenAI service APIs unchanged.
+ *
+ * Configuration is scoped through Effect's context, so transforms only apply to
+ * the effect they are provided to and anything evaluated inside that scope.
+ * When multiple transforms are needed, compose them into a single
+ * `HttpClient => HttpClient` function before providing the configuration.
+ *
  * @since 4.0.0
  */
 export * as OpenAiConfig from "./OpenAiConfig.ts"