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

package/dist/OpenAiEmbeddingModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAiEmbeddingModel.d.ts","sourceRoot":"","sources":["../src/OpenAiEmbeddingModel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAGrC,OAAO,KAAK,cAAc,MAAM,mCAAmC,CAAA;AACnE,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAA;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAA;;;;;;;;AAE1B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,MAAO,SAAQ,WAa+B;CAAG;AAE9D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,GAChB,OAAO,MAAM,EACb,SAAS;IACP,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC,CAAA;CACtE,KACA,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,cAAc,CAAC,cAAc,GAAG,cAAc,CAAC,UAAU,EAAE,YAAY,CAc/F,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,IAAI;oBACC,MAAM;sBACJ,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS;gEAgBlE,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CACnE,KAAG,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,EAAE,KAAK,EAAE,YAAY,CACN,CAAA;AAE5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,EAAE;IAC/B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,CAAC,SAAS,EAAE,OAAO,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;IACtH;;;;;;;;;;;;;;;;;;;OAmBG;IACH,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;CAoDhH,CAAA"}

package/dist/OpenAiEmbeddingModel.js

@@ -0,0 +1,218 @@
+/**
+ * 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 * 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.js";
+/**
+ * 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 /*#__PURE__*/Context.Service()("@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, options) => 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 = /*#__PURE__*/Effect.fnUntraced(function* ({
+  model,
+  config: providerConfig
+}) {
+  const client = yield* OpenAiClient;
+  const makeConfig = Effect.gen(function* () {
+    const services = yield* Effect.context();
+    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 => 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 = /*#__PURE__*/dual(2, (self, overrides) => Effect.flatMap(Effect.serviceOption(Config), config => Effect.provideService(self, Config, {
+  ...(config._tag === "Some" ? config.value : {}),
+  ...overrides
+})));
+const mapProviderResponse = (inputLength, response) => {
+  if (response.data.length !== inputLength) {
+    return Effect.fail(invalidOutput(`Provider returned ${response.data.length} embeddings but expected ${inputLength}`));
+  }
+  const results = new Array(inputLength);
+  const seen = new Set();
+  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 => AiError.make({
+  module: "OpenAiEmbeddingModel",
+  method: "embedMany",
+  reason: new AiError.InvalidOutputError({
+    description
+  })
+});
+//# sourceMappingURL=OpenAiEmbeddingModel.js.map

package/dist/OpenAiEmbeddingModel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAiEmbeddingModel.js","names":["Context","Effect","dual","Layer","AiError","EmbeddingModel","AiModel","OpenAiClient","Config","Service","model","options","make","merge","layer","config","dimensions","succeed","Dimensions","fnUntraced","providerConfig","client","makeConfig","gen","services","context","mapUnsafe","get","key","embedMany","inputs","response","createEmbedding","input","mapProviderResponse","length","effect","withConfigOverride","self","overrides","flatMap","serviceOption","provideService","_tag","value","inputLength","data","fail","invalidOutput","results","Array","seen","Set","entry","Number","isInteger","index","has","isArray","embedding","add","size","usage","inputTokens","prompt_tokens","description","module","method","reason","InvalidOutputError"],"sources":["../src/OpenAiEmbeddingModel.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/OpenAiError.d.ts

@@ -1,11 +1,24 @@
 /**
- * @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 = {
     /**
@@ -24,11 +37,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 & {
     /**
@@ -49,45 +64,104 @@ export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
     readonly resetTokens: string | null;
 };
 declare module "effect/unstable/ai/AiError" {
-    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
+     */
+    interface RateLimitErrorMetadata {
+        readonly openai?: OpenAiRateLimitMetadata | null;
     }
-    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
+     */
+    interface QuotaExhaustedErrorMetadata {
+        readonly openai?: OpenAiErrorMetadata | null;
     }
-    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
+     */
+    interface AuthenticationErrorMetadata {
+        readonly openai?: OpenAiErrorMetadata | null;
     }
-    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
+     */
+    interface ContentPolicyErrorMetadata {
+        readonly openai?: OpenAiErrorMetadata | null;
     }
-    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
+     */
+    interface InvalidRequestErrorMetadata {
+        readonly openai?: OpenAiErrorMetadata | null;
     }
-    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
+     */
+    interface InternalProviderErrorMetadata {
+        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
+     */
+    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
+     */
+    interface StructuredOutputErrorMetadata {
+        readonly openai?: OpenAiErrorMetadata | null;
     }
-    interface InvalidOutputError {
-        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
+     */
+    interface UnsupportedSchemaErrorMetadata {
+        readonly openai?: OpenAiErrorMetadata | null;
     }
-    interface UnknownError {
-        readonly metadata: {
-            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
+     */
+    interface UnknownErrorMetadata {
+        readonly openai?: OpenAiErrorMetadata | null;
     }
 }
 //# sourceMappingURL=OpenAiError.d.ts.map

package/dist/OpenAiError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAiError.d.ts","sourceRoot":"","sources":["../src/OpenAiError.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG,mBAAmB,GAAG;IAC1D;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC,CAAA;AAED,OAAO,QAAQ,4BAA4B,CAAC;IAC1C,UAAiB,cAAc;QAC7B,QAAQ,CAAC,QAAQ,EAAE;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAA;SACjD,CAAA;KACF;IAED,UAAiB,mBAAmB;QAClC,QAAQ,CAAC,QAAQ,EAAE;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;SAC7C,CAAA;KACF;IAED,UAAiB,mBAAmB;QAClC,QAAQ,CAAC,QAAQ,EAAE;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;SAC7C,CAAA;KACF;IAED,UAAiB,kBAAkB;QACjC,QAAQ,CAAC,QAAQ,EAAE;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;SAC7C,CAAA;KACF;IAED,UAAiB,mBAAmB;QAClC,QAAQ,CAAC,QAAQ,EAAE;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;SAC7C,CAAA;KACF;IAED,UAAiB,qBAAqB;QACpC,QAAQ,CAAC,QAAQ,EAAE;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;SAC7C,CAAA;KACF;IAED,UAAiB,kBAAkB;QACjC,QAAQ,CAAC,QAAQ,EAAE;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;SAC7C,CAAA;KACF;IAED,UAAiB,YAAY;QAC3B,QAAQ,CAAC,QAAQ,EAAE;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;SAC7C,CAAA;KACF;CACF"}
+{"version":3,"file":"OpenAiError.d.ts","sourceRoot":"","sources":["../src/OpenAiError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG,mBAAmB,GAAG;IAC1D;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC,CAAA;AAED,OAAO,QAAQ,4BAA4B,CAAC;IAC1C;;;;;OAKG;IACH,UAAiB,sBAAsB;QACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAA;KACjD;IAED;;;;;;OAMG;IACH,UAAiB,2BAA2B;QAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;IAED;;;;;;OAMG;IACH,UAAiB,2BAA2B;QAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;IAED;;;;;;OAMG;IACH,UAAiB,0BAA0B;QACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;IAED;;;;;;OAMG;IACH,UAAiB,2BAA2B;QAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;IAED;;;;;;OAMG;IACH,UAAiB,6BAA6B;QAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;IAED;;;;;;OAMG;IACH,UAAiB,0BAA0B;QACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;IAED;;;;;;OAMG;IACH,UAAiB,6BAA6B;QAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;IAED;;;;;;OAMG;IACH,UAAiB,8BAA8B;QAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;IAED;;;;;;OAMG;IACH,UAAiB,oBAAoB;QACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAC7C;CACF"}

package/dist/OpenAiError.js

@@ -1,5 +1,18 @@
 /**
- * @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
  */
 export {};
 //# sourceMappingURL=OpenAiError.js.map