@effect/ai-openai-compat 4.0.0-beta.7 → 4.0.0-beta.71

package/src/OpenAiConfig.ts

@@ -1,35 +1,72 @@
 /**
- * @since 1.0.0
+ * The `OpenAiConfig` module provides shared configuration for clients that
+ * talk to OpenAI-compatible APIs. It is used to customize the HTTP client
+ * wiring around a provider without changing the higher-level model,
+ * embeddings, or tool-calling APIs that consume the client.
+ *
+ * **Common tasks**
+ *
+ * - Install a client transform with {@link withClientTransform}
+ * - Add provider-specific HTTP behavior, such as headers, retries, proxies, or
+ *   instrumentation
+ * - Read the active configuration from the Effect context when implementing
+ *   OpenAI-compatible integrations
+ *
+ * **Gotchas**
+ *
+ * - The transform receives and returns an `HttpClient`, so it should preserve
+ *   the existing client behavior unless it intentionally replaces it
+ * - Configuration is provided through Effect context and is scoped to the
+ *   effect that receives the service
+ *
+ * @since 4.0.0
  */
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import { dual } from "effect/Function"
-import * as ServiceMap from "effect/ServiceMap"
 import type { HttpClient } from "effect/unstable/http/HttpClient"
 
 /**
- * @since 1.0.0
+ * Context service used to carry OpenAI-compatible client configuration for the
+ * current Effect scope.
+ *
+ * **When to use**
+ *
+ * Use as the context service for OpenAI-compatible client configuration when you
+ * need to provide or read scoped HTTP client transforms through Effect context.
+ *
+ * @see {@link withClientTransform} for scoping an HTTP client transformation
+ *
  * @category services
+ * @since 4.0.0
  */
-export class OpenAiConfig extends ServiceMap.Service<
+export class OpenAiConfig extends Context.Service<
   OpenAiConfig,
   OpenAiConfig.Service
 >()("@effect/ai-openai-compat/OpenAiConfig") {
   /**
-   * @since 1.0.0
+   * Gets the configured OpenAI-compatible service from the current context when present.
+   *
+   * @since 4.0.0
    */
   static readonly getOrUndefined: Effect.Effect<typeof OpenAiConfig.Service | undefined> = Effect.map(
-    Effect.services<never>(),
+    Effect.context<never>(),
     (context) => context.mapUnsafe.get(OpenAiConfig.key)
   )
 }
 
 /**
- * @since 1.0.0
+ * Types associated with the `OpenAiConfig` context service.
+ *
+ * @since 4.0.0
  */
 export declare namespace OpenAiConfig {
   /**
-   * @since 1.0.
+   * Configuration consumed by OpenAI-compatible clients when they build or
+   * resolve the underlying HTTP client.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined
@@ -37,18 +74,54 @@ export declare namespace OpenAiConfig {
 }
 
 /**
- * @since 1.0.0
+ * Provides an HTTP client transform for the supplied effect.
+ *
+ * **When to use**
+ *
+ * Use to add provider-specific OpenAI-compatible HTTP behavior, such as
+ * headers, retries, instrumentation, or proxy routing.
+ *
+ * **Details**
+ *
+ * OpenAI-compatible provider services read the transform from the
+ * `OpenAiConfig` context.
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withClientTransform: {
   /**
-   * @since 1.0.0
+   * Provides an HTTP client transform for the supplied effect.
+   *
+   * **When to use**
+   *
+   * Use to add provider-specific OpenAI-compatible HTTP behavior, such as
+   * headers, retries, instrumentation, or proxy routing.
+   *
+   * **Details**
+   *
+   * OpenAI-compatible provider services read the transform from the
+   * `OpenAiConfig` context.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (transform: (client: HttpClient) => HttpClient): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * @since 1.0.0
+   * Provides an HTTP client transform for the supplied effect.
+   *
+   * **When to use**
+   *
+   * Use to add provider-specific OpenAI-compatible HTTP behavior, such as
+   * headers, retries, instrumentation, or proxy routing.
+   *
+   * **Details**
+   *
+   * OpenAI-compatible provider services read the transform from the
+   * `OpenAiConfig` context.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,

package/src/OpenAiEmbeddingModel.ts

@@ -0,0 +1,360 @@
+/**
+ * The `OpenAiEmbeddingModel` module adapts OpenAI-compatible embeddings
+ * endpoints to Effect's embedding model service. It sends embedding requests
+ * through {@link OpenAiClient}, exposes constructors for layers and `AiModel`
+ * values, and supports scoped request configuration overrides.
+ *
+ * **Mental model**
+ *
+ * - {@link make} builds the `EmbeddingModel` service when an
+ *   {@link OpenAiClient} is already available.
+ * - {@link layer} provides that service as a `Layer`.
+ * - {@link model} creates an `AiModel` and also provides the configured vector
+ *   dimensions service expected by embedding consumers.
+ * - {@link Config} and {@link withConfigOverride} merge default request options
+ *   with scoped overrides for individual operations.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link model} when application code wants a named `AiModel` with known
+ *   dimensions.
+ * - Use {@link layer} when composing services around an existing
+ *   {@link OpenAiClient} layer.
+ * - Use {@link withConfigOverride} to set per-operation options such as `user`,
+ *   `dimensions`, or provider-specific request fields.
+ *
+ * **Gotchas**
+ *
+ * - {@link Model} is `string` because OpenAI-compatible providers use their
+ *   own embedding model identifiers.
+ * - {@link model} requires explicit dimensions because compatible providers do
+ *   not expose a shared way to infer vector width.
+ * - Provider responses must contain one numeric vector per input with unique,
+ *   in-range indexes; base64 embeddings or malformed indexes fail with
+ *   `InvalidOutputError`.
+ *
+ * @since 4.0.0
+ */
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import { dual } from "effect/Function"
+import * as Layer from "effect/Layer"
+import type { Simplify } from "effect/Types"
+import * as AiError from "effect/unstable/ai/AiError"
+import * as EmbeddingModel from "effect/unstable/ai/EmbeddingModel"
+import * as AiModel from "effect/unstable/ai/Model"
+import type { CreateEmbedding200, CreateEmbeddingRequestJson } from "./OpenAiClient.ts"
+import { OpenAiClient } from "./OpenAiClient.ts"
+
+/**
+ * A model identifier accepted by an OpenAI-compatible embeddings endpoint.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type Model = string
+
+/**
+ * Service definition for OpenAI embedding model configuration.
+ *
+ * **When to use**
+ *
+ * Use when you need to provide shared default request options for
+ * OpenAI-compatible embedding operations through the Effect context, such as
+ * `dimensions`, `encoding_format`, or `user`.
+ *
+ * **Details**
+ *
+ * The service stores the embedding request payload without `input`. Requests
+ * combine the selected model, layer or constructor config, and scoped context
+ * config, with scoped context config taking precedence.
+ *
+ * @see {@link withConfigOverride} for scoping embedding request overrides
+ *
+ * @category context
+ * @since 4.0.0
+ */
+export class Config extends Context.Service<
+  Config,
+  Simplify<
+    & Partial<
+      Omit<
+        CreateEmbeddingRequestJson,
+        "input"
+      >
+    >
+    & {
+      readonly [x: string]: unknown
+    }
+  >
+>()("@effect/ai-openai-compat/OpenAiEmbeddingModel/Config") {}
+
+/**
+ * Creates an `AiModel` for an OpenAI-compatible embedding model with its configured vector dimensions.
+ *
+ * **When to use**
+ *
+ * Use to provide an OpenAI-compatible `EmbeddingModel` and its `Dimensions`
+ * service to an Effect program.
+ *
+ * @see {@link layer} for providing only the embedding model service
+ * @see {@link withConfigOverride} for scoped request configuration overrides
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const model = (
+  model: string,
+  options: {
+    readonly dimensions: number
+    readonly config?: Omit<typeof Config.Service, "model" | "dimensions">
+  }
+): AiModel.Model<"openai", EmbeddingModel.EmbeddingModel | EmbeddingModel.Dimensions, OpenAiClient> =>
+  AiModel.make(
+    "openai",
+    model,
+    Layer.merge(
+      layer({
+        model,
+        config: {
+          ...options.config,
+          dimensions: options.dimensions
+        }
+      }),
+      Layer.succeed(EmbeddingModel.Dimensions, options.dimensions)
+    )
+  )
+
+/**
+ * Creates an OpenAI-compatible embedding model service backed by `OpenAiClient`.
+ *
+ * **When to use**
+ *
+ * Use when you need to build or provide an `EmbeddingModel` service directly
+ * from an existing `OpenAiClient`.
+ *
+ * **Details**
+ *
+ * The service sends embedding requests through `OpenAiClient.createEmbedding`.
+ * Request config is merged as the selected model, constructor config, then
+ * scoped `Config`, so scoped overrides take precedence. Provider usage
+ * `prompt_tokens` is exposed as `usage.inputTokens`.
+ *
+ * **Gotchas**
+ *
+ * Provider responses must contain one numeric vector for every requested input
+ * with unique, in-range `index` values; otherwise embedding operations fail with
+ * `AiError.InvalidOutputError`.
+ *
+ * @see {@link model} for the higher-level `AiModel` descriptor that also provides `EmbeddingModel.Dimensions`
+ * @see {@link layer} for providing the service as a `Layer`
+ * @see {@link withConfigOverride} for scoping embedding request overrides
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
+  readonly model: string
+  readonly config?: Omit<typeof Config.Service, "model"> | undefined
+}): Effect.fn.Return<EmbeddingModel.Service, never, OpenAiClient> {
+  const client = yield* OpenAiClient
+
+  const makeConfig = Effect.gen(function*() {
+    const services = yield* Effect.context<never>()
+    return { model, ...providerConfig, ...services.mapUnsafe.get(Config.key) }
+  })
+
+  return yield* EmbeddingModel.make({
+    embedMany: Effect.fnUntraced(function*({ inputs }) {
+      const config = yield* makeConfig
+      const response = yield* client.createEmbedding({ ...config, input: inputs })
+      return yield* mapProviderResponse(inputs.length, response)
+    })
+  })
+})
+
+/**
+ * Creates a layer for an OpenAI-compatible embedding model service.
+ *
+ * **When to use**
+ *
+ * Use when composing application layers and you want an OpenAI-compatible
+ * embeddings endpoint to satisfy `EmbeddingModel.EmbeddingModel` while
+ * supplying `OpenAiClient` from another layer.
+ *
+ * @see {@link make} for constructing the embedding model service effectfully
+ * @see {@link model} for creating an `AiModel` with configured dimensions
+ *
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer = (options: {
+  readonly model: string
+  readonly config?: Omit<typeof Config.Service, "model"> | undefined
+}): Layer.Layer<EmbeddingModel.EmbeddingModel, never, OpenAiClient> =>
+  Layer.effect(EmbeddingModel.EmbeddingModel, make(options))
+
+/**
+ * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+ *
+ * **When to use**
+ *
+ * Use to apply embedding request options to one effect without changing the
+ * model's default configuration.
+ *
+ * **Details**
+ *
+ * The overrides are merged with any existing `Config` service for the duration
+ * of the supplied effect. Fields in `overrides` take precedence over existing
+ * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+ * and `withConfigOverride(effect, overrides)`.
+ *
+ * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
+ *
+ * @category configuration
+ * @since 4.0.0
+ */
+export const withConfigOverride: {
+  /**
+   * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply embedding request options to one effect without changing the
+   * model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
+  /**
+   * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply embedding request options to one effect without changing the
+   * model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
+} = dual<
+  /**
+   * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply embedding request options to one effect without changing the
+   * model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  (overrides: typeof Config.Service) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
+  /**
+   * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply embedding request options to one effect without changing the
+   * model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
+   * and `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
+>(2, (self, overrides) =>
+  Effect.flatMap(
+    Effect.serviceOption(Config),
+    (config) =>
+      Effect.provideService(self, Config, {
+        ...(config._tag === "Some" ? config.value : {}),
+        ...overrides
+      })
+  ))
+
+const mapProviderResponse = (
+  inputLength: number,
+  response: CreateEmbedding200
+): Effect.Effect<EmbeddingModel.ProviderResponse, AiError.AiError> => {
+  if (response.data.length !== inputLength) {
+    return Effect.fail(
+      invalidOutput(`Provider returned ${response.data.length} embeddings but expected ${inputLength}`)
+    )
+  }
+
+  const results = new Array<Array<number>>(inputLength)
+  const seen = new Set<number>()
+
+  for (const entry of response.data) {
+    if (!Number.isInteger(entry.index) || entry.index < 0 || entry.index >= inputLength) {
+      return Effect.fail(invalidOutput(`Provider returned invalid embedding index: ${entry.index}`))
+    }
+    if (seen.has(entry.index)) {
+      return Effect.fail(invalidOutput(`Provider returned duplicate embedding index: ${entry.index}`))
+    }
+    if (!Array.isArray(entry.embedding)) {
+      return Effect.fail(invalidOutput(`Provider returned non-vector embedding at index ${entry.index}`))
+    }
+
+    seen.add(entry.index)
+    results[entry.index] = [...entry.embedding]
+  }
+
+  if (seen.size !== inputLength) {
+    return Effect.fail(
+      invalidOutput(`Provider returned embeddings for ${seen.size} inputs but expected ${inputLength}`)
+    )
+  }
+
+  return Effect.succeed({
+    results,
+    usage: {
+      inputTokens: response.usage?.prompt_tokens
+    }
+  })
+}
+
+const invalidOutput = (description: string): AiError.AiError =>
+  AiError.make({
+    module: "OpenAiEmbeddingModel",
+    method: "embedMany",
+    reason: new AiError.InvalidOutputError({ description })
+  })

package/src/OpenAiError.ts

@@ -1,12 +1,25 @@
 /**
- * @since 1.0.0
+ * The `OpenAiError` module defines OpenAI-specific metadata that can be
+ * attached to the shared `AiError` error types used by the AI packages. It is
+ * primarily used by OpenAI-compatible clients to preserve provider details
+ * such as error codes, error types, request IDs, and rate limit headers while
+ * still exposing errors through the provider-neutral Effect AI error model.
+ *
+ * Use this module when mapping OpenAI API failures into `AiError` values and
+ * when consumers need enough structured metadata to debug failed requests,
+ * inspect quota or rate limit responses, or correlate an error with OpenAI
+ * support. The exported types are metadata shapes only; the module augmentation
+ * makes those shapes available on the corresponding shared AI error metadata
+ * interfaces without defining new runtime error classes.
+ *
+ * @since 4.0.0
  */
 
 /**
  * OpenAI-specific error metadata fields.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiErrorMetadata = {
   /**
@@ -26,11 +39,13 @@ export type OpenAiErrorMetadata = {
 /**
  * OpenAI-specific rate limit metadata fields.
  *
+ * **Details**
+ *
  * Extends base error metadata with rate limit specific information from
  * OpenAI's rate limit headers.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
   /**
@@ -52,51 +67,112 @@ export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
-  export interface RateLimitError {
-    readonly metadata: {
-      readonly openai?: OpenAiRateLimitMetadata | null
-    }
+  /**
+   * Metadata attached to rate limit errors returned by OpenAI-compatible APIs.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface RateLimitErrorMetadata {
+    readonly openai?: OpenAiRateLimitMetadata | null
   }
 
-  export interface QuotaExhaustedError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * Metadata attached when an OpenAI-compatible provider reports that quota or
+   * billing limits have been exhausted.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface QuotaExhaustedErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface AuthenticationError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * Metadata attached to authentication failures from OpenAI-compatible APIs,
+   * such as invalid, missing, or unauthorized API credentials.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface AuthenticationErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface ContentPolicyError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * Metadata attached when an OpenAI-compatible provider rejects content because
+   * it violates a safety or usage policy.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface ContentPolicyErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface InvalidRequestError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * Metadata attached to malformed or unsupported requests rejected by an
+   * OpenAI-compatible API before model execution.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface InvalidRequestErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface InternalProviderError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * Metadata attached to unexpected server-side failures reported by an
+   * OpenAI-compatible provider.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface InternalProviderErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface InvalidOutputError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * Metadata attached when an OpenAI-compatible response cannot be converted
+   * into the expected AI package output shape.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface InvalidOutputErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
+  }
+
+  /**
+   * Metadata attached when an OpenAI-compatible structured output response does
+   * not satisfy the requested schema or parsing constraints.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface StructuredOutputErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface UnknownError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * Metadata attached when an OpenAI-compatible provider cannot support the
+   * schema supplied for structured output or tool definitions.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface UnsupportedSchemaErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
+  }
+
+  /**
+   * Metadata attached when an OpenAI-compatible error response cannot be mapped
+   * to a more specific shared AI error category.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface UnknownErrorMetadata {
+    readonly openai?: OpenAiErrorMetadata | null
   }
 }