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

package/src/OpenAiEmbeddingModel.ts

@@ -0,0 +1,208 @@
+/**
+ * OpenAI Embedding Model implementation.
+ *
+ * Provides an EmbeddingModel implementation for OpenAI-compatible embeddings APIs.
+ *
+ * @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.
+ *
+ * @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 OpenAI-compatible embedding model that can be used with
+ * `AiModel.provide`.
+ *
+ * @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 embedding model service.
+ *
+ * @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 the OpenAI embedding model.
+ *
+ * @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 config overrides for OpenAI embedding model operations.
+ *
+ * @category configuration
+ * @since 4.0.0
+ */
+export const withConfigOverride: {
+  /**
+   * Provides config overrides for OpenAI embedding model operations.
+   *
+   * @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.
+   *
+   * @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.
+   *
+   * @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.
+   *
+   * @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
   }
 }