@effect/ai-openai 4.0.0-beta.8 → 4.0.0-beta.81

package/src/OpenAiClientGenerated.ts

@@ -0,0 +1,202 @@
+/**
+ * @since 4.0.0
+ */
+import * as Array from "effect/Array"
+import type * as Config from "effect/Config"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import { identity } from "effect/Function"
+import * as Function from "effect/Function"
+import * as Layer from "effect/Layer"
+import * as Predicate from "effect/Predicate"
+import * as Redacted from "effect/Redacted"
+import * as Headers from "effect/unstable/http/Headers"
+import * as HttpClient from "effect/unstable/http/HttpClient"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import * as Generated from "./Generated.ts"
+import { OpenAiConfig } from "./OpenAiConfig.ts"
+
+// =============================================================================
+// Service Identifier
+// =============================================================================
+
+/**
+ * Service identifier for the generated OpenAI client.
+ *
+ * @since 4.0.0
+ * @category service
+ */
+export class OpenAiClientGenerated extends Context.Service<OpenAiClientGenerated, Generated.OpenAiClient>()(
+  "@effect/ai-openai/OpenAiClientGenerated"
+) {}
+
+// =============================================================================
+// Options
+// =============================================================================
+
+/**
+ * Options for configuring the generated OpenAI client.
+ *
+ * @since 4.0.0
+ * @category options
+ */
+export type Options = {
+  /**
+   * The OpenAI API key.
+   */
+  readonly apiKey?: Redacted.Redacted<string> | undefined
+
+  /**
+   * The base URL for the OpenAI API.
+   *
+   * @default "https://api.openai.com/v1"
+   */
+  readonly apiUrl?: string | undefined
+
+  /**
+   * Optional organization ID for multi-org accounts.
+   */
+  readonly organizationId?: Redacted.Redacted<string> | undefined
+
+  /**
+   * Optional project ID for project-scoped requests.
+   */
+  readonly projectId?: Redacted.Redacted<string> | undefined
+
+  /**
+   * Optional transformer for the HTTP client.
+   */
+  readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
+}
+
+const RedactedOpenAiHeaders = {
+  OpenAiOrganization: "OpenAI-Organization",
+  OpenAiProject: "OpenAI-Project"
+}
+
+// =============================================================================
+// Constructor
+// =============================================================================
+
+/**
+ * Creates a generated OpenAI client service with the given options.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export const make = Effect.fnUntraced(
+  function*(options: Options): Effect.fn.Return<Generated.OpenAiClient, never, HttpClient.HttpClient> {
+    const baseClient = yield* HttpClient.HttpClient
+    const apiUrl = options.apiUrl ?? "https://api.openai.com/v1"
+
+    const httpClient = baseClient.pipe(
+      HttpClient.mapRequest(Function.flow(
+        HttpClientRequest.prependUrl(apiUrl),
+        options.apiKey
+          ? HttpClientRequest.bearerToken(Redacted.value(options.apiKey))
+          : identity,
+        options.organizationId
+          ? HttpClientRequest.setHeader(
+            RedactedOpenAiHeaders.OpenAiOrganization,
+            Redacted.value(options.organizationId)
+          )
+          : identity,
+        options.projectId
+          ? HttpClientRequest.setHeader(
+            RedactedOpenAiHeaders.OpenAiProject,
+            Redacted.value(options.projectId)
+          )
+          : identity,
+        HttpClientRequest.acceptJson
+      )),
+      options.transformClient
+        ? options.transformClient
+        : identity
+    )
+
+    return Generated.make(httpClient, {
+      transformClient: Effect.fnUntraced(function*(client) {
+        const config = yield* OpenAiConfig.getOrUndefined
+        if (Predicate.isNotUndefined(config?.transformClient)) {
+          return config.transformClient(client)
+        }
+        return client
+      })
+    })
+  },
+  Effect.updateService(
+    Headers.CurrentRedactedNames,
+    Array.appendAll(Object.values(RedactedOpenAiHeaders))
+  )
+)
+
+// =============================================================================
+// Layers
+// =============================================================================
+
+/**
+ * Creates a layer for the generated OpenAI client with the given options.
+ *
+ * @since 4.0.0
+ * @category layers
+ */
+export const layer = (options: Options): Layer.Layer<OpenAiClientGenerated, never, HttpClient.HttpClient> =>
+  Layer.effect(OpenAiClientGenerated, make(options))
+
+/**
+ * Creates a layer for the generated OpenAI client, loading the requisite
+ * configuration via Effect's `Config` module.
+ *
+ * @since 4.0.0
+ * @category layers
+ */
+export const layerConfig = (options?: {
+  /**
+   * The config value to load for the API key.
+   */
+  readonly apiKey?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
+
+  /**
+   * The config value to load for the API URL.
+   */
+  readonly apiUrl?: Config.Config<string> | undefined
+
+  /**
+   * The config value to load for the organization ID.
+   */
+  readonly organizationId?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
+
+  /**
+   * The config value to load for the project ID.
+   */
+  readonly projectId?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
+
+  /**
+   * Optional transformer for the HTTP client.
+   */
+  readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
+}): Layer.Layer<OpenAiClientGenerated, Config.ConfigError, HttpClient.HttpClient> =>
+  Layer.effect(
+    OpenAiClientGenerated,
+    Effect.gen(function*() {
+      const apiKey = Predicate.isNotUndefined(options?.apiKey)
+        ? yield* options.apiKey :
+        undefined
+      const apiUrl = Predicate.isNotUndefined(options?.apiUrl)
+        ? yield* options.apiUrl :
+        undefined
+      const organizationId = Predicate.isNotUndefined(options?.organizationId)
+        ? yield* options.organizationId
+        : undefined
+      const projectId = Predicate.isNotUndefined(options?.projectId)
+        ? yield* options.projectId :
+        undefined
+      return yield* make({
+        apiKey,
+        apiUrl,
+        organizationId,
+        projectId,
+        transformClient: options?.transformClient
+      })
+    })
+  )

package/src/OpenAiConfig.ts

@@ -1,35 +1,56 @@
 /**
- * @since 1.0.0
+ * The `OpenAiConfig` module lets a workflow temporarily customize the HTTP
+ * client used by `@effect/ai-openai` request helpers. OpenAI client, language
+ * model, and embedding code read this scoped transform when they execute
+ * provider calls.
+ *
+ * @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 for scoped OpenAI configuration used by provider operations.
+ *
+ * **When to use**
+ *
+ * Use to provide scoped OpenAI client configuration, such as an HTTP client
+ * transform, to OpenAI provider operations without passing it through each call.
+ *
+ * @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/OpenAiConfig") {
   /**
-   * @since 1.0.0
+   * Gets the configured OpenAI 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 used by the `OpenAiConfig` context service.
+ *
+ * @since 4.0.0
  */
 export declare namespace OpenAiConfig {
   /**
-   * @since 1.0.
+   * Configuration values read by OpenAI provider operations when executing
+   * requests.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined
@@ -37,18 +58,75 @@ export declare namespace OpenAiConfig {
 }
 
 /**
- * @since 1.0.0
+ * Provides a scoped transform for the OpenAI HTTP client used by provider
+ * operations.
+ *
+ * **When to use**
+ *
+ * Use when you need temporary OpenAI HTTP client customization for a single
+ * effect or workflow without rebuilding the client layer.
+ *
+ * **Details**
+ *
+ * Supports both data-first and data-last forms. The transform is stored in the
+ * scoped `OpenAiConfig` service and read by OpenAI provider operations while
+ * running the supplied effect.
+ *
+ * **Gotchas**
+ *
+ * If a transform is already present in the scoped config, this helper replaces
+ * it. Compose transforms manually when both should apply.
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withClientTransform: {
   /**
-   * @since 1.0.0
+   * Provides a scoped transform for the OpenAI HTTP client used by provider
+   * operations.
+   *
+   * **When to use**
+   *
+   * Use when you need temporary OpenAI HTTP client customization for a single
+   * effect or workflow without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenAiConfig` service and read by OpenAI provider operations while
+   * running the supplied effect.
+   *
+   * **Gotchas**
+   *
+   * If a transform is already present in the scoped config, this helper replaces
+   * it. Compose transforms manually when both should apply.
+   *
    * @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 a scoped transform for the OpenAI HTTP client used by provider
+   * operations.
+   *
+   * **When to use**
+   *
+   * Use when you need temporary OpenAI HTTP client customization for a single
+   * effect or workflow without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenAiConfig` service and read by OpenAI provider operations while
+   * running the supplied effect.
+   *
+   * **Gotchas**
+   *
+   * If a transform is already present in the scoped config, this helper replaces
+   * it. Compose transforms manually when both should apply.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,

package/src/OpenAiEmbeddingModel.ts

@@ -0,0 +1,332 @@
+/**
+ * The `OpenAiEmbeddingModel` module provides the OpenAI implementation of
+ * Effect AI's `EmbeddingModel` service. It sends embedding requests through
+ * `OpenAiClient`, exposes constructors for layers and `AiModel` values,
+ * supports scoped request configuration overrides, and checks that OpenAI
+ * returns one numeric vector for each requested input.
+ *
+ * @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"
+
+/**
+ * Context service for OpenAI embedding model configuration.
+ *
+ * **When to use**
+ *
+ * Use when you need scoped OpenAI request defaults or overrides for embedding
+ * requests 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.
+ *
+ * **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 you need scoped OpenAI embedding request defaults for a single
+ * effect or workflow 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 you need scoped OpenAI embedding request defaults for a single
+   * effect or workflow 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 you need scoped OpenAI embedding request defaults for a single
+   * effect or workflow 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 you need scoped OpenAI embedding request defaults for a single
+   * effect or workflow 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 you need scoped OpenAI embedding request defaults for a single
+   * effect or workflow 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 })
+  })