@effect/ai-openrouter 4.0.0-beta.70 → 4.0.0-beta.72

package/src/OpenRouterClient.ts

@@ -96,7 +96,16 @@ export type ChatStreamingResponseChunkData = typeof Generated.ChatStreamingRespo
 // =============================================================================
 
 /**
- * Service identifier for the OpenRouter client.
+ * Service tag for the OpenRouter client.
+ *
+ * **When to use**
+ *
+ * Use when accessing or providing the OpenRouter client service through
+ * Effect's context.
+ *
+ * @see {@link make} for constructing an OpenRouter client effectfully
+ * @see {@link layer} for providing a client from explicit options
+ * @see {@link layerConfig} for providing a client from `Config`
  *
  * @category services
  * @since 4.0.0
@@ -111,7 +120,7 @@ export class OpenRouterClient extends Context.Service<
 // =============================================================================
 
 /**
- * Configuration options for creating an OpenRouter client.
+ * Configuration for creating an OpenRouter client.
  *
  * @category models
  * @since 4.0.0
@@ -136,7 +145,7 @@ export type Options = {
    *
    * **When to use**
    *
-   * Use this to add middleware, logging, or custom request/response handling.
+   * Use to add middleware, logging, or custom request/response handling.
    */
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
 }
@@ -146,7 +155,28 @@ export type Options = {
 // =============================================================================
 
 /**
- * Creates an OpenRouter client service with the given options.
+ * Creates an OpenRouter client service from explicit options.
+ *
+ * **When to use**
+ *
+ * Use to construct the OpenRouter client service inside an effect when you need
+ * the service value directly.
+ *
+ * **Details**
+ *
+ * The returned service uses the current `HttpClient`, prepends `apiUrl` or
+ * `https://openrouter.ai/api/v1`, adds the bearer token and optional
+ * `HTTP-Referer` and `X-Title` headers, accepts JSON responses, and applies
+ * `transformClient` when provided.
+ *
+ * **Gotchas**
+ *
+ * Scoped `OpenRouterConfig.withClientTransform` applies to generated client
+ * request methods. Streaming chat completion requests are sent directly by this
+ * module and do not read that scoped transform.
+ *
+ * @see {@link layer} for providing this client from explicit options
+ * @see {@link layerConfig} for loading client settings from `Config`
  *
  * @category constructors
  * @since 4.0.0
@@ -245,6 +275,14 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the OpenRouter client with the given options.
  *
+ * **When to use**
+ *
+ * Use when you already have the OpenRouter client options in code and want to
+ * provide `OpenRouterClient` as a layer.
+ *
+ * @see {@link make} for constructing the client service effectfully
+ * @see {@link layerConfig} for loading client settings from `Config`
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -252,8 +290,21 @@ export const layer = (options: Options): Layer.Layer<OpenRouterClient, never, Ht
   Layer.effect(OpenRouterClient, make(options))
 
 /**
- * Creates a layer for the OpenRouter client, loading the requisite
- * configuration via Effect's `Config` module.
+ * Creates a layer for the OpenRouter client from provided `Config` values.
+ *
+ * **When to use**
+ *
+ * Use when OpenRouter client settings should be read from Effect `Config`
+ * values while providing `OpenRouterClient` as a layer.
+ *
+ * **Details**
+ *
+ * Only config values supplied in `options` are loaded. Omitted fields are
+ * passed to `make` as `undefined`, and `transformClient` is forwarded as a
+ * plain option.
+ *
+ * @see {@link make} for constructing the client service effectfully
+ * @see {@link layer} for providing the client from already-resolved options
  *
  * @category layers
  * @since 4.0.0

package/src/OpenRouterConfig.ts

@@ -1,21 +1,34 @@
 /**
- * The `OpenRouterConfig` module provides contextual configuration for the
- * OpenRouter provider integration. It is used to customize the HTTP client that
- * backs OpenRouter requests without rebuilding the provider layer itself.
+ * The `OpenRouterConfig` module provides scoped contextual configuration for
+ * OpenRouter request execution. It lets a workflow customize the HTTP client
+ * used by generated OpenRouter request methods without rebuilding the
+ * `OpenRouterClient` layer.
  *
- * Use {@link withClientTransform} when a single effect, workflow, or scoped
- * portion of an application needs to add cross-cutting HTTP client behavior
- * such as request logging, retries, proxy routing, additional headers, or test
- * doubles. The configuration is read from the current Effect context, so the
- * transform only applies where the returned effect is run with that context.
+ * **Mental model**
+ *
+ * - {@link OpenRouterConfig} is a context service carrying optional
+ *   OpenRouter-specific request configuration
+ * - {@link withClientTransform} provides that service around one effect
+ * - Generated request methods read the current context and apply the transform
+ *   to their `HttpClient`
+ * - The scoped configuration only applies while the returned effect is run
+ *
+ * **Common tasks**
+ *
+ * - Add request logging, retries, proxy routing, headers, or test doubles with
+ *   {@link withClientTransform}
+ * - Scope OpenRouter client customization to one workflow without changing the
+ *   shared client layer
  *
  * **Gotchas**
  *
- * - Each call to {@link withClientTransform} replaces the current client
- *   transform for the provided effect; compose transforms manually when both
- *   behaviors should apply.
+ * - Each {@link withClientTransform} call replaces the current scoped
+ *   transform for the supplied effect; compose transforms manually when both
+ *   behaviors should apply
  * - The transform receives and returns an `HttpClient`, so it should preserve
- *   the OpenRouter client contract while adding behavior around it.
+ *   the OpenRouter request contract while adding behavior around it
+ * - Streaming chat completion requests are sent directly by `OpenRouterClient`
+ *   and do not read this scoped transform
  *
  * @since 4.0.0
  */
@@ -25,9 +38,16 @@ import { dual } from "effect/Function"
 import type { HttpClient } from "effect/unstable/http/HttpClient"
 
 /**
- * Context service carrying scoped OpenRouter provider configuration for client
+ * Context service for scoped OpenRouter provider configuration used by client
  * operations.
  *
+ * **When to use**
+ *
+ * Use as the context service tag when manually providing or reading scoped
+ * OpenRouter provider configuration in an Effect context.
+ *
+ * @see {@link withClientTransform} for scoping an HTTP client transformation
+ *
  * @category services
  * @since 4.0.0
  */
@@ -68,6 +88,24 @@ export declare namespace OpenRouterConfig {
  * Provides a scoped transform for the OpenRouter HTTP client used by provider
  * operations.
  *
+ * **When to use**
+ *
+ * Use when a single effect or workflow needs temporary OpenRouter HTTP client
+ * customization without rebuilding the client layer.
+ *
+ * **Details**
+ *
+ * Supports both data-first and data-last forms. The transform is stored in the
+ * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+ * 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. Streaming chat
+ * completion requests are sent directly by `OpenRouterClient.make` and do not
+ * read this scoped transform.
+ *
  * @category configuration
  * @since 4.0.0
  */
@@ -76,6 +114,24 @@ export const withClientTransform: {
    * Provides a scoped transform for the OpenRouter HTTP client used by provider
    * operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs temporary OpenRouter HTTP client
+   * customization without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+   * 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. Streaming chat
+   * completion requests are sent directly by `OpenRouterClient.make` and do not
+   * read this scoped transform.
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -84,6 +140,24 @@ export const withClientTransform: {
    * Provides a scoped transform for the OpenRouter HTTP client used by provider
    * operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs temporary OpenRouter HTTP client
+   * customization without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+   * 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. Streaming chat
+   * completion requests are sent directly by `OpenRouterClient.make` and do not
+   * read this scoped transform.
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -96,6 +170,24 @@ export const withClientTransform: {
    * Provides a scoped transform for the OpenRouter HTTP client used by provider
    * operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs temporary OpenRouter HTTP client
+   * customization without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+   * 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. Streaming chat
+   * completion requests are sent directly by `OpenRouterClient.make` and do not
+   * read this scoped transform.
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -104,6 +196,24 @@ export const withClientTransform: {
    * Provides a scoped transform for the OpenRouter HTTP client used by provider
    * operations.
    *
+   * **When to use**
+   *
+   * Use when a single effect or workflow needs temporary OpenRouter HTTP client
+   * customization without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+   * 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. Streaming chat
+   * completion requests are sent directly by `OpenRouterClient.make` and do not
+   * read this scoped transform.
+   *
    * @category configuration
    * @since 4.0.0
    */

package/src/OpenRouterLanguageModel.ts

@@ -1,23 +1,42 @@
 /**
- * The `OpenRouterLanguageModel` module provides constructors for using
- * OpenRouter chat completion models through the Effect AI `LanguageModel`
- * interface. It adapts Effect prompts, tools, structured output schemas, file
- * parts, reasoning details, cache-control hints, and telemetry annotations into
- * the OpenRouter request and response formats.
+ * The `OpenRouterLanguageModel` module provides the OpenRouter implementation
+ * of Effect AI's `LanguageModel` service. It translates provider-neutral
+ * prompts, tools, files, structured output requests, reasoning metadata,
+ * cache-control hints, and telemetry annotations into OpenRouter chat
+ * completion requests, then converts responses and streams back into Effect AI
+ * response parts.
  *
- * Use this module when an application wants to select an OpenRouter model by
- * name while keeping the rest of its AI workflow provider-agnostic. The
- * exported layer and model constructors install a `LanguageModel` service backed
- * by `OpenRouterClient`, and `withConfigOverride` can scope per-request
- * OpenRouter options such as sampling, routing, tool use, or JSON schema
- * behavior.
+ * **Mental model**
  *
- * OpenRouter routes requests to many underlying providers, so model support for
- * images, files, tools, structured outputs, caching, and reasoning metadata can
- * vary. Provider-specific prompt and response metadata is preserved under the
- * `openrouter` option namespace so multi-turn conversations can round-trip
- * details such as reasoning blocks and file annotations when the selected model
- * supports them.
+ * `OpenRouterClient` owns HTTP transport and authentication. This module owns
+ * protocol translation: message assembly, tool conversion, structured output
+ * codec selection, streaming chunk handling, OpenRouter metadata round-trips,
+ * and GenAI telemetry annotations. {@link model}, {@link layer}, and
+ * {@link make} all build the same OpenRouter-backed
+ * `LanguageModel.LanguageModel` service from a model id and optional request
+ * defaults.
+ *
+ * **Common tasks**
+ *
+ * - Create an OpenRouter model descriptor for `Effect.provide`: {@link model}
+ * - Provide `LanguageModel.LanguageModel` as a `Layer`: {@link layer}
+ * - Construct the service effectfully from an existing `OpenRouterClient`:
+ *   {@link make}
+ * - Supply or scope OpenRouter request defaults: {@link Config},
+ *   {@link withConfigOverride}
+ * - Preserve OpenRouter reasoning and file metadata across turns:
+ *   {@link ReasoningDetails}, {@link FileAnnotation}
+ *
+ * **Gotchas**
+ *
+ * - OpenRouter routes to many underlying providers, so support for images,
+ *   files, tools, structured outputs, caching, and reasoning metadata depends
+ *   on the selected model and route.
+ * - Provider-specific prompt and response metadata lives under the `openrouter`
+ *   option namespace so later requests can replay reasoning details and file
+ *   annotations when the model supports them.
+ * - Provider-defined tools are not supported by this integration; requests that
+ *   include them fail before reaching OpenRouter.
  *
  * @since 4.0.0
  */
@@ -58,7 +77,14 @@ import { type ChatStreamingResponseChunkData, OpenRouterClient } from "./OpenRou
 // =============================================================================
 
 /**
- * Service definition for OpenRouter language model configuration.
+ * Context service for OpenRouter language model configuration.
+ *
+ * **When to use**
+ *
+ * Use to provide scoped OpenRouter chat completion defaults or per-operation
+ * overrides for an OpenRouter language model service.
+ *
+ * @see {@link withConfigOverride} for scoping language model request overrides
  *
  * @category services
  * @since 4.0.0
@@ -211,7 +237,7 @@ declare module "effect/unstable/ai/Prompt" {
    *
    * **When to use**
    *
-   * Use these options to control how text content is sent to OpenRouter.
+   * Use when you use these options to control how text content is sent to OpenRouter.
    *
    * @category request
    * @since 4.0.0
@@ -490,7 +516,22 @@ declare module "effect/unstable/ai/Response" {
 // =============================================================================
 
 /**
- * Creates an AI model descriptor for an OpenRouter language model.
+ * Creates an OpenRouter model descriptor that can be provided with
+ * `Effect.provide`.
+ *
+ * **When to use**
+ *
+ * Use when you want an OpenRouter language model value that carries provider
+ * and model metadata and can be supplied directly to an Effect program.
+ *
+ * **Details**
+ *
+ * The returned model requires `OpenRouterClient` and provides
+ * `LanguageModel.LanguageModel`.
+ *
+ * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
+ * @see {@link make} for constructing the language model service effectfully
+ * @see {@link withConfigOverride} for scoping OpenRouter request overrides
  *
  * @category constructors
  * @since 4.0.0
@@ -502,7 +543,29 @@ export const model = (
   AiModel.make("openai", model, layer({ model, config }))
 
 /**
- * Creates an OpenRouter language model service.
+ * Creates an OpenRouter `LanguageModel` service from a model identifier and
+ * optional request defaults.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to construct a `LanguageModel.Service` value backed
+ * by `OpenRouterClient`.
+ *
+ * **Details**
+ *
+ * The returned effect requires `OpenRouterClient`. Request defaults from the
+ * `config` option are merged with any `Config` service in the context, with
+ * context values taking precedence. The service supports both `generateText`
+ * and `streamText`.
+ *
+ * **Gotchas**
+ *
+ * Provider-defined tools are not supported by this provider integration;
+ * requests that include them fail with an `InvalidUserInputError`.
+ *
+ * @see {@link layer} for providing the service as a `Layer`
+ * @see {@link model} for creating a model descriptor for `Effect.provide`
+ * @see {@link withConfigOverride} for scoping request defaults around operations
  *
  * @category constructors
  * @since 4.0.0
@@ -573,6 +636,15 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 /**
  * Creates a layer for the OpenRouter language model.
  *
+ * **When to use**
+ *
+ * Use when composing application layers and you want OpenRouter to satisfy
+ * `LanguageModel.LanguageModel` while supplying `OpenRouterClient` from another
+ * layer.
+ *
+ * @see {@link make} for constructing the language model service effectfully
+ * @see {@link model} for creating a model descriptor for `Effect.provide`
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -585,6 +657,20 @@ export const layer = (options: {
 /**
  * Provides config overrides for OpenRouter language model operations.
  *
+ * **When to use**
+ *
+ * Use to apply OpenRouter request configuration 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 pipe form and
+ * `withConfigOverride(effect, overrides)`.
+ *
+ * @see {@link Config} for available OpenRouter request configuration fields
+ *
  * @category configuration
  * @since 4.0.0
  */
@@ -592,6 +678,20 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
+   * **When to use**
+   *
+   * Use to apply OpenRouter request configuration 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 pipe form and
+   * `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenRouter request configuration fields
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -599,6 +699,20 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
+   * **When to use**
+   *
+   * Use to apply OpenRouter request configuration 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 pipe form and
+   * `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenRouter request configuration fields
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -607,6 +721,20 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
+   * **When to use**
+   *
+   * Use to apply OpenRouter request configuration 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 pipe form and
+   * `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenRouter request configuration fields
+   *
    * @category configuration
    * @since 4.0.0
    */
@@ -614,6 +742,20 @@ export const withConfigOverride: {
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
+   * **When to use**
+   *
+   * Use to apply OpenRouter request configuration 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 pipe form and
+   * `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenRouter request configuration fields
+   *
    * @category configuration
    * @since 4.0.0
    */

package/src/index.ts

@@ -10,86 +10,21 @@
 export * as Generated from "./Generated.ts"
 
 /**
- * The `OpenRouterClient` module provides an Effect service for calling
- * OpenRouter's chat completions API. It wraps the generated OpenRouter HTTP
- * client with Effect-native constructors, layers, typed errors, and streaming
- * support.
- *
- * **Common tasks**
- *
- * - Build a client from explicit options with {@link make}
- * - Provide the client to an application with {@link layer} or {@link layerConfig}
- * - Create non-streaming chat completions with {@link Service.createChatCompletion}
- * - Create server-sent event chat completion streams with
- *   {@link Service.createChatCompletionStream}
- * - Customize authentication, base URL, OpenRouter ranking headers, or the
- *   underlying HTTP client through {@link Options}
- *
- * **Gotchas**
- *
- * - Streaming requests are sent directly to `/chat/completions` with `stream`
- *   and `stream_options.include_usage` enabled by this module.
- * - OpenRouter API failures, HTTP client failures, and schema decoding failures
- *   are mapped into `AiError` values for the exported service methods.
- *
  * @since 4.0.0
  */
 export * as OpenRouterClient from "./OpenRouterClient.ts"
 
 /**
- * The `OpenRouterConfig` module provides contextual configuration for the
- * OpenRouter provider integration. It is used to customize the HTTP client that
- * backs OpenRouter requests without rebuilding the provider layer itself.
- *
- * Use {@link withClientTransform} when a single effect, workflow, or scoped
- * portion of an application needs to add cross-cutting HTTP client behavior
- * such as request logging, retries, proxy routing, additional headers, or test
- * doubles. The configuration is read from the current Effect context, so the
- * transform only applies where the returned effect is run with that context.
- *
- * **Gotchas**
- *
- * - Each call to {@link withClientTransform} replaces the current client
- *   transform for the provided effect; compose transforms manually when both
- *   behaviors should apply.
- * - The transform receives and returns an `HttpClient`, so it should preserve
- *   the OpenRouter client contract while adding behavior around it.
- *
  * @since 4.0.0
  */
 export * as OpenRouterConfig from "./OpenRouterConfig.ts"
 
 /**
- * OpenRouter error metadata augmentation.
- *
- * Provides OpenRouter-specific metadata fields for AI error types through
- * module augmentation, enabling typed access to OpenRouter error details.
- *
  * @since 4.0.0
  */
 export * as OpenRouterError from "./OpenRouterError.ts"
 
 /**
- * The `OpenRouterLanguageModel` module provides constructors for using
- * OpenRouter chat completion models through the Effect AI `LanguageModel`
- * interface. It adapts Effect prompts, tools, structured output schemas, file
- * parts, reasoning details, cache-control hints, and telemetry annotations into
- * the OpenRouter request and response formats.
- *
- * Use this module when an application wants to select an OpenRouter model by
- * name while keeping the rest of its AI workflow provider-agnostic. The
- * exported layer and model constructors install a `LanguageModel` service backed
- * by `OpenRouterClient`, and `withConfigOverride` can scope per-request
- * OpenRouter options such as sampling, routing, tool use, or JSON schema
- * behavior.
- *
- * OpenRouter routes requests to many underlying providers, so model support for
- * images, files, tools, structured outputs, caching, and reasoning metadata can
- * vary. Provider-specific prompt and response metadata is preserved under the
- * `openrouter` option namespace so multi-turn conversations can round-trip
- * details such as reasoning blocks and file annotations when the selected model
- * supports them.
- *
  * @since 4.0.0
  */
 export * as OpenRouterLanguageModel from "./OpenRouterLanguageModel.ts"