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

package/src/OpenAiEmbeddingModel.ts

@@ -0,0 +1,357 @@
+/**
+ * The `OpenAiEmbeddingModel` module provides the OpenAI implementation of
+ * Effect AI's `EmbeddingModel` service. It adapts the OpenAI embeddings
+ * endpoint into Effect AI's batch embedding interface, preserving input order
+ * and returning numeric vectors for each requested input.
+ *
+ * **Mental model**
+ *
+ * `OpenAiClient` owns transport, authentication, and provider request
+ * execution. This module owns embedding-specific configuration, response
+ * validation, and the `EmbeddingModel.EmbeddingModel` layer. Use {@link model}
+ * when you want an `AiModel` descriptor that also provides the configured
+ * embedding dimensions, or {@link layer} / {@link make} when the dimensions are
+ * managed separately.
+ *
+ * **Common tasks**
+ *
+ * - Provide an OpenAI-backed `EmbeddingModel.EmbeddingModel` from an existing
+ *   `OpenAiClient`
+ * - Configure the OpenAI embedding model id, dimensions, encoding format, and
+ *   other create-embedding request fields
+ * - Scope per-request defaults with {@link Config} and
+ *   {@link withConfigOverride}
+ *
+ * **Gotchas**
+ *
+ * - The service expects OpenAI to return floating-point embedding arrays.
+ *   Requesting base64 embeddings causes an `InvalidOutputError`.
+ * - Provider results are checked for missing, duplicate, or out-of-range
+ *   indexes before they are exposed as Effect AI embedding results.
+ *
+ * @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 { OpenAiClient } from "./OpenAiClient.ts"
+import type * as OpenAiSchema from "./OpenAiSchema.ts"
+
+/**
+ * Model identifiers supported by OpenAI's embeddings API.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type Model = "text-embedding-ada-002" | "text-embedding-3-small" | "text-embedding-3-large"
+
+/**
+ * Service definition for OpenAI embedding model configuration.
+ *
+ * **When to use**
+ *
+ * Use when embedding requests need scoped OpenAI request defaults or overrides
+ * from Effect context.
+ *
+ * **Details**
+ *
+ * The service stores the OpenAI create-embedding request payload without
+ * `input`, carrying options such as `model`, `dimensions`, `encoding_format`,
+ * and `user`.
+ *
+ * @see {@link withConfigOverride} for scoping embedding request overrides
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export class Config extends Context.Service<
+  Config,
+  Simplify<
+    & Partial<
+      Omit<
+        typeof OpenAiSchema.CreateEmbeddingRequest.Encoded,
+        "input"
+      >
+    >
+    & {
+      readonly [x: string]: unknown
+    }
+  >
+>()("@effect/ai-openai/OpenAiEmbeddingModel/Config") {}
+
+/**
+ * Creates an `AiModel` for an OpenAI embedding model with its configured vector dimensions.
+ *
+ * **When to use**
+ *
+ * Use to provide an OpenAI `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 & {}) | Model,
+  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 embedding model service.
+ *
+ * **When to use**
+ *
+ * Use to construct the `EmbeddingModel.Service` effectfully when
+ * `OpenAiClient` is already available in the environment or when the service
+ * value is needed directly.
+ *
+ * **Details**
+ *
+ * The `model` option is sent with each embedding request. Constructor `config`
+ * supplies create-embedding request fields other than `model` and `input`, and
+ * scoped overrides from `withConfigOverride` are merged last for each request.
+ *
+ * **Gotchas**
+ *
+ * The service expects numeric embedding vectors. It fails with
+ * `InvalidOutputError` when the provider returns base64 embeddings,
+ * out-of-range indexes, duplicate indexes, or an unexpected number of
+ * embeddings.
+ *
+ * @see {@link layer} for providing the embedding model service as a layer
+ * @see {@link model} for creating an `AiModel` that also provides dimensions
+ * @see {@link withConfigOverride} for scoped request configuration overrides
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
+  readonly model: (string & {}) | Model
+  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 the OpenAI embedding model.
+ *
+ * **When to use**
+ *
+ * Use when composing application layers and you want OpenAI to satisfy
+ * `EmbeddingModel.EmbeddingModel` while supplying `OpenAiClient` from another
+ * layer.
+ *
+ * **Gotchas**
+ *
+ * Use the default floating-point embedding format. The service expects numeric
+ * vectors and fails with `InvalidOutputError` if OpenAI returns base64
+ * embeddings.
+ *
+ * @see {@link make} for constructing the embedding model service effectfully
+ * @see {@link model} for creating an `AiModel` that also provides embedding dimensions
+ *
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer = (options: {
+  readonly model: (string & {}) | Model
+  readonly config?: Omit<typeof Config.Service, "model"> | undefined
+}): Layer.Layer<EmbeddingModel.EmbeddingModel, never, OpenAiClient> =>
+  Layer.effect(EmbeddingModel.EmbeddingModel, make(options))
+
+/**
+ * Provides config overrides for OpenAI embedding model operations.
+ *
+ * **When to use**
+ *
+ * Use when a single effect or workflow needs scoped OpenAI embedding request
+ * defaults without rebuilding the embedding model service.
+ *
+ * **Details**
+ *
+ * Supports both data-first and data-last forms. Existing scoped config is read
+ * first, then the provided overrides are applied so override fields take
+ * precedence.
+ *
+ * @see {@link Config} for the scoped embedding request configuration service
+ *
+ * @category configuration
+ * @since 4.0.0
+ */
+export const withConfigOverride: {
+  /**
+   * Provides config overrides for OpenAI embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs scoped OpenAI embedding request
+   * defaults without rebuilding the embedding model service.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. Existing scoped config is read
+   * first, then the provided overrides are applied so override fields take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped embedding request configuration service
+   *
+   * @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 config overrides for OpenAI embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs scoped OpenAI embedding request
+   * defaults without rebuilding the embedding model service.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. Existing scoped config is read
+   * first, then the provided overrides are applied so override fields take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped embedding request configuration service
+   *
+   * @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 config overrides for OpenAI embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs scoped OpenAI embedding request
+   * defaults without rebuilding the embedding model service.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. Existing scoped config is read
+   * first, then the provided overrides are applied so override fields take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped embedding request configuration service
+   *
+   * @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 config overrides for OpenAI embedding model operations.
+   *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs scoped OpenAI embedding request
+   * defaults without rebuilding the embedding model service.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. Existing scoped config is read
+   * first, then the provided overrides are applied so override fields take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped embedding request configuration service
+   *
+   * @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: typeof OpenAiSchema.CreateEmbeddingResponse.Type
+): 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

@@ -4,14 +4,14 @@
  * Provides OpenAI-specific metadata fields for AI error types through module
  * augmentation, enabling typed access to OpenAI error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
  * OpenAI-specific error metadata fields.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiErrorMetadata = {
   /**
@@ -31,11 +31,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 & {
   /**
@@ -57,51 +59,184 @@ export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
-  export interface RateLimitError {
-    readonly metadata: {
-      readonly openai?: OpenAiRateLimitMetadata | null
-    }
+  /**
+   * OpenAI metadata attached to `RateLimitError` values.
+   *
+   * **Details**
+   *
+   * Captures OpenAI error details together with rate limit header information
+   * from responses where the provider rejected the request because a limit was
+   * reached.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface RateLimitErrorMetadata {
+    /**
+     * OpenAI-specific details for the rate limit response.
+     */
+    readonly openai?: OpenAiRateLimitMetadata | null
   }
 
-  export interface QuotaExhaustedError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * OpenAI metadata attached to `QuotaExhaustedError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for failures caused by exhausted account,
+   * billing, or usage quota.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface QuotaExhaustedErrorMetadata {
+    /**
+     * OpenAI-specific details for the quota exhaustion response.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface AuthenticationError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * OpenAI metadata attached to `AuthenticationError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for failed API key, authorization, or
+   * permission checks.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface AuthenticationErrorMetadata {
+    /**
+     * OpenAI-specific details for the authentication failure.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface ContentPolicyError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * OpenAI metadata attached to `ContentPolicyError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details when OpenAI rejects input or output because
+   * it violates a content policy.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface ContentPolicyErrorMetadata {
+    /**
+     * OpenAI-specific details for the content policy response.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface InvalidRequestError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * OpenAI metadata attached to `InvalidRequestError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for malformed requests, unsupported
+   * parameters, or other request validation failures reported by OpenAI.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InvalidRequestErrorMetadata {
+    /**
+     * OpenAI-specific details for the invalid request response.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface InternalProviderError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * OpenAI metadata attached to `InternalProviderError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for OpenAI-side failures such as transient
+   * server errors.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InternalProviderErrorMetadata {
+    /**
+     * OpenAI-specific details for the internal provider response.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface InvalidOutputError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * OpenAI metadata attached to `InvalidOutputError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details when an OpenAI response cannot be parsed or
+   * validated as the expected output.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InvalidOutputErrorMetadata {
+    /**
+     * OpenAI-specific details for the invalid output response.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
+  }
+
+  /**
+   * OpenAI metadata attached to `StructuredOutputError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details when OpenAI returns content that does not
+   * satisfy the requested structured output schema.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface StructuredOutputErrorMetadata {
+    /**
+     * OpenAI-specific details for the structured output failure.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
   }
 
-  export interface UnknownError {
-    readonly metadata: {
-      readonly openai?: OpenAiErrorMetadata | null
-    }
+  /**
+   * OpenAI metadata attached to `UnsupportedSchemaError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details when an unsupported schema failure is
+   * associated with an OpenAI response.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface UnsupportedSchemaErrorMetadata {
+    /**
+     * OpenAI-specific details for the unsupported schema failure.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
+  }
+
+  /**
+   * OpenAI metadata attached to `UnknownError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for OpenAI failures that do not map cleanly
+   * to a more specific AI error category.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface UnknownErrorMetadata {
+    /**
+     * OpenAI-specific details for the unclassified provider failure.
+     */
+    readonly openai?: OpenAiErrorMetadata | null
   }
 }