@effect/ai-openrouter 4.0.0-beta.9 → 4.0.0-beta.91

package/src/OpenRouterLanguageModel.ts

@@ -1,18 +1,26 @@
 /**
- * @since 1.0.0
+ * 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 provider options into OpenRouter chat completion
+ * requests, records GenAI telemetry around those calls, and converts normal or
+ * streaming results back into Effect AI response content and metadata.
+ *
+ * @since 4.0.0
  */
 /** @effect-diagnostics preferSchemaOverJson:skip-file */
 import * as Arr from "effect/Array"
+import * as Context from "effect/Context"
 import * as DateTime from "effect/DateTime"
 import * as Effect from "effect/Effect"
 import * as Encoding from "effect/Encoding"
 import { dual } from "effect/Function"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
 import * as Redactable from "effect/Redactable"
 import type * as Schema from "effect/Schema"
 import * as SchemaAST from "effect/SchemaAST"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import type { Span } from "effect/Tracer"
 import type { DeepMutable, Mutable, Simplify } from "effect/Types"
@@ -37,12 +45,19 @@ 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
  *
- * @since 1.0.0
  * @category services
+ * @since 4.0.0
  */
-export class Config extends ServiceMap.Service<
+export class Config extends Context.Service<
   Config,
   Simplify<
     & Partial<
@@ -68,14 +83,20 @@ export class Config extends ServiceMap.Service<
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * OpenRouter assistant reasoning detail blocks preserved for multi-turn
+ * conversations.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ReasoningDetails = Exclude<typeof Generated.AssistantMessage.Encoded["reasoning_details"], undefined>
 
 /**
- * @since 1.0.0
+ * File annotations emitted on OpenRouter assistant messages and exposed in
+ * finish metadata.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type FileAnnotation = Extract<
   NonNullable<typeof Generated.AssistantMessage.fields.annotations.Type>[number],
@@ -83,7 +104,21 @@ export type FileAnnotation = Extract<
 >
 
 declare module "effect/unstable/ai/Prompt" {
+  /**
+   * OpenRouter-specific options for system messages.
+   *
+   * **Details**
+   *
+   * These options are used when translating system instructions into
+   * OpenRouter chat messages.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface SystemMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the system message.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -92,7 +127,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for user messages.
+   *
+   * **Details**
+   *
+   * These options are used when translating user content into OpenRouter chat
+   * messages.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface UserMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the user message.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -101,7 +150,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for assistant messages.
+   *
+   * **Details**
+   *
+   * Preserves reasoning metadata when assistant messages are replayed in later
+   * OpenRouter requests.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface AssistantMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the assistant message.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -114,7 +177,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for tool messages.
+   *
+   * **Details**
+   *
+   * These options are used when converting tool results into OpenRouter chat
+   * messages.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the tool message.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -123,7 +200,20 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for text prompt parts.
+   *
+   * **When to use**
+   *
+   * Use when you use these options to control how text content is sent to OpenRouter.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface TextPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the text part.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -132,7 +222,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for reasoning prompt parts.
+   *
+   * **Details**
+   *
+   * Preserves provider reasoning blocks so reasoning-aware conversations can
+   * continue across OpenRouter requests.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ReasoningPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the reasoning part.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -145,7 +249,20 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for file prompt parts.
+   *
+   * **Details**
+   *
+   * Controls file naming and prompt caching for files sent to OpenRouter.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface FilePartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the file part.
+     */
     readonly openrouter?: {
       /**
        * The name to give to the file. Will be prioritized over the file name
@@ -159,7 +276,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for tool call prompt parts.
+   *
+   * **Details**
+   *
+   * Preserves reasoning details associated with tool calls when a conversation
+   * is sent back to OpenRouter.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolCallPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the tool call part.
+     */
     readonly openrouter?: {
       /**
        * Reasoning details associated with the tool call part.
@@ -168,7 +299,20 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for tool result prompt parts.
+   *
+   * **Details**
+   *
+   * Controls prompt caching for tool results sent to OpenRouter.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolResultPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the tool result part.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -179,43 +323,157 @@ declare module "effect/unstable/ai/Prompt" {
 }
 
 declare module "effect/unstable/ai/Response" {
+  /**
+   * OpenRouter metadata attached to completed reasoning response parts.
+   *
+   * **Details**
+   *
+   * Preserves provider reasoning details that can be sent back in later turns.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the reasoning part.
+     */
     readonly openrouter?: {
+      /**
+       * Reasoning details emitted by the underlying provider for this part.
+       */
       readonly reasoningDetails?: ReasoningDetails | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata emitted when a streamed reasoning part starts.
+   *
+   * **Details**
+   *
+   * Carries the first reasoning detail chunk when OpenRouter exposes one.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning start.
+     */
     readonly openrouter?: {
+      /**
+       * Reasoning details emitted by the underlying provider for this part.
+       */
       readonly reasoningDetails?: ReasoningDetails | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata emitted for streamed reasoning deltas.
+   *
+   * **Details**
+   *
+   * Carries provider reasoning detail chunks as they arrive from OpenRouter.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning delta.
+     */
     readonly openrouter?: {
+      /**
+       * Reasoning details emitted by the underlying provider for this delta.
+       */
       readonly reasoningDetails?: ReasoningDetails | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata attached to tool-call response parts.
+   *
+   * **Details**
+   *
+   * Associates tool calls with provider reasoning details when the model emits
+   * reasoning and tool calls together.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ToolCallPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the tool call.
+     */
     readonly openrouter?: {
+      /**
+       * Reasoning details associated with this tool call.
+       */
       readonly reasoningDetails?: ReasoningDetails | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata attached to URL source citations.
+   *
+   * **Details**
+   *
+   * Includes citation text and offsets returned by providers that support URL
+   * annotations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface UrlSourcePartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific citation metadata returned for the URL source.
+     */
     readonly openrouter?: {
+      /**
+       * The cited source content returned by the provider.
+       */
       readonly content?: string | null
+      /**
+       * The zero-based start index of the citation in the generated text.
+       */
       readonly startIndex?: number | null
+      /**
+       * The zero-based end index of the citation in the generated text.
+       */
       readonly endIndex?: number | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata attached to finish response parts.
+   *
+   * **Details**
+   *
+   * Exposes provider response details that are not represented by the common
+   * Effect AI finish part fields.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface FinishPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned when the OpenRouter response finishes.
+     */
     readonly openrouter?: {
+      /**
+       * Provider fingerprint for the backend configuration that served the request.
+       */
       readonly systemFingerprint?: string | null
+      /**
+       * Raw token usage reported by OpenRouter.
+       */
       readonly usage?: typeof Generated.ChatGenerationTokenUsage.Encoded | null
+      /**
+       * File annotations returned by the provider.
+       */
       readonly annotations?: ReadonlyArray<FileAnnotation> | null
+      /**
+       * The OpenRouter provider that served the request, when reported.
+       */
       readonly provider?: string | null
     } | null
   }
@@ -226,20 +484,59 @@ declare module "effect/unstable/ai/Response" {
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * 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
  */
 export const model = (
   model: string,
   config?: Omit<typeof Config.Service, "model">
 ): AiModel.Model<"openai", LanguageModel.LanguageModel, OpenRouterClient> =>
-  AiModel.make("openai", layer({ model, config }))
+  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 you need to construct a `LanguageModel.Service` value backed by
+ * `OpenRouterClient` inside an Effect.
+ *
+ * **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
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: string
@@ -249,7 +546,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   const codecTransformer = getCodecTransformer(model)
 
   const makeConfig = Effect.gen(function*() {
-    const services = yield* Effect.services<never>()
+    const services = yield* Effect.context<never>()
     return { model, ...providerConfig, ...services.mapUnsafe.get(Config.key) }
   })
 
@@ -273,6 +570,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   )
 
   return yield* LanguageModel.make({
+    codecTransformer: toCodecOpenAI,
     generateText: Effect.fnUntraced(
       function*(options) {
         const config = yield* makeConfig
@@ -300,17 +598,23 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
           })
         )
     )
-  }).pipe(Effect.provideService(
-    LanguageModel.CurrentCodecTransformer,
-    codecTransformer
-  ))
+  })
 })
 
 /**
  * Creates a layer for the OpenRouter language model.
  *
- * @since 1.0.0
+ * **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
  */
 export const layer = (options: {
   readonly model: string
@@ -321,37 +625,107 @@ export const layer = (options: {
 /**
  * Provides config overrides for OpenRouter language model operations.
  *
- * @since 1.0.0
+ * **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
  */
 export const withConfigOverride: {
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
-   * @since 1.0.0
+   * **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
    */
   (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
-   * @since 1.0.0
+   * **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
    */
   <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 OpenRouter language model operations.
    *
-   * @since 1.0.0
+   * **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
    */
   (overrides: typeof Config.Service) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
-   * @since 1.0.0
+   * **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
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
 >(2, (self, overrides) =>
@@ -460,6 +834,45 @@ const prepareMessages = Effect.fnUntraced(
                   break
                 }
 
+                if (part.mediaType.startsWith("audio/")) {
+                  const format = audioFormats[part.mediaType.toLowerCase()]
+
+                  if (Predicate.isUndefined(format)) {
+                    return yield* AiError.make({
+                      module: "OpenRouterLanguageModel",
+                      method: "prepareMessages",
+                      reason: new AiError.InvalidUserInputError({
+                        description: `Detected unsupported media type for audio file: '${part.mediaType}' ` +
+                          `- OpenRouter supports ${supportedAudioFormats} audio`
+                      })
+                    })
+                  }
+
+                  if (part.data instanceof URL) {
+                    return yield* AiError.make({
+                      module: "OpenRouterLanguageModel",
+                      method: "prepareMessages",
+                      reason: new AiError.InvalidUserInputError({
+                        description: "Detected URL data for audio file - OpenRouter requires " +
+                          "audio to be provided as base64-encoded data"
+                      })
+                    })
+                  }
+
+                  content.push({
+                    type: "input_audio",
+                    input_audio: {
+                      data: part.data instanceof Uint8Array
+                        ? Encoding.encodeBase64(part.data)
+                        : getBase64FromDataUrl(part.data),
+                      format
+                    },
+                    ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
+                  })
+
+                  break
+                }
+
                 const options = part.options.openrouter
                 const fileName = options?.fileName ?? part.fileName ?? ""
 
@@ -588,7 +1001,7 @@ const buildHttpRequestDetails = (
   method: request.method,
   url: request.url,
   urlParams: Array.from(request.urlParams),
-  hash: request.hash,
+  hash: Option.getOrUndefined(request.hash),
   headers: Redactable.redact(request.headers) as Record<string, string>
 })
 
@@ -1431,7 +1844,7 @@ const unsupportedSchemaError = (error: unknown, method: string): AiError.AiError
     })
   })
 
-const tryJsonSchema = <S extends Schema.Top>(
+const tryJsonSchema = <S extends Schema.Constraint>(
   schema: S,
   method: string,
   transformer: LanguageModel.CodecTransformer
@@ -1462,6 +1875,32 @@ const getResponseFormat = Effect.fnUntraced(function*({ config, options, transfo
   return undefined
 })
 
+/**
+ * Maps audio media types to the formats supported by OpenRouter.
+ *
+ * @see https://openrouter.ai/docs/guides/overview/multimodal/audio
+ */
+const audioFormats: Record<string, string> = {
+  "audio/aac": "aac",
+  "audio/aiff": "aiff",
+  "audio/x-aiff": "aiff",
+  "audio/flac": "flac",
+  "audio/x-flac": "flac",
+  "audio/l16": "pcm16",
+  "audio/l24": "pcm24",
+  "audio/m4a": "m4a",
+  "audio/x-m4a": "m4a",
+  "audio/mp4": "m4a",
+  "audio/mp3": "mp3",
+  "audio/mpeg": "mp3",
+  "audio/ogg": "ogg",
+  "audio/wav": "wav",
+  "audio/wave": "wav",
+  "audio/x-wav": "wav"
+}
+
+const supportedAudioFormats = Array.from(new Set(Object.values(audioFormats))).join(", ")
+
 const getMediaType = (dataUrl: string, defaultMediaType: string): string => {
   const match = dataUrl.match(/^data:([^;]+)/)
   return match ? (match[1] ?? defaultMediaType) : defaultMediaType