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

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 models
+ */
+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,82 @@
 /**
- * @since 1.0.0
+ * The `OpenAiConfig` module carries request-time configuration for the
+ * `@effect/ai-openai` package through Effect's context. It currently exposes a
+ * scoped HTTP client transform used by OpenAI request helpers when they execute
+ * provider calls.
+ *
+ * **Mental model**
+ *
+ * Client constructors set the baseline HTTP client for an OpenAI service.
+ * `OpenAiConfig` is for narrower dynamic scopes: wrap an effect with
+ * {@link withClientTransform} and OpenAI requests evaluated inside that effect
+ * see the transformed `HttpClient`. Leaving the scope restores the previous
+ * configuration.
+ *
+ * **Common tasks**
+ *
+ * - Add request middleware, tracing, retry policy, proxy routing, or test
+ *   interception around a group of OpenAI calls.
+ * - Apply a temporary HTTP client transform without rebuilding the OpenAI
+ *   service layer.
+ * - Share one transform across all OpenAI helpers executed inside the same
+ *   Effect scope.
+ *
+ * **Gotchas**
+ *
+ * - Only one `transformClient` value is stored in the scoped config. Compose
+ *   transforms into a single `HttpClient => HttpClient` function when multiple
+ *   behaviors should apply.
+ * - The transform affects OpenAI requests that read this contextual config; it
+ *   does not mutate an already constructed HTTP client globally.
+ *
+ * @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 carrying scoped OpenAI configuration for 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 +84,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 a single effect or workflow needs temporary OpenAI HTTP client
+ * customization 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 a single effect or workflow needs temporary OpenAI HTTP client
+   * customization 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 a single effect or workflow needs temporary OpenAI HTTP client
+   * customization 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>,