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

package/dist/OpenRouterLanguageModel.js

@@ -1,17 +1,38 @@
 /**
- * @since 1.0.0
+ * 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
  */
 /** @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 * as SchemaAST from "effect/SchemaAST";
-import * as ServiceMap from "effect/ServiceMap";
 import * as Stream from "effect/Stream";
 import * as AiError from "effect/unstable/ai/AiError";
 import { toCodecAnthropic } from "effect/unstable/ai/AnthropicStructuredOutput";
@@ -29,26 +50,28 @@ import { OpenRouterClient } from "./OpenRouterClient.js";
 /**
  * Service definition for OpenRouter language model configuration.
  *
- * @since 1.0.0
  * @category services
+ * @since 4.0.0
  */
-export class Config extends /*#__PURE__*/ServiceMap.Service()("@effect/ai-openrouter/OpenRouterLanguageModel/Config") {}
+export class Config extends /*#__PURE__*/Context.Service()("@effect/ai-openrouter/OpenRouterLanguageModel/Config") {}
 // =============================================================================
 // Language Model
 // =============================================================================
 /**
- * @since 1.0.0
+ * Creates an AI model descriptor for an OpenRouter language model.
+ *
  * @category constructors
+ * @since 4.0.0
  */
-export const model = (model, config) => AiModel.make("openai", layer({
+export const model = (model, config) => AiModel.make("openai", model, layer({
   model,
   config
 }));
 /**
  * Creates an OpenRouter language model service.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = /*#__PURE__*/Effect.fnUntraced(function* ({
   model,
@@ -57,7 +80,7 @@ export const make = /*#__PURE__*/Effect.fnUntraced(function* ({
   const client = yield* OpenRouterClient;
   const codecTransformer = getCodecTransformer(model);
   const makeConfig = Effect.gen(function* () {
-    const services = yield* Effect.services();
+    const services = yield* Effect.context();
     return {
       model,
       ...providerConfig,
@@ -99,6 +122,7 @@ export const make = /*#__PURE__*/Effect.fnUntraced(function* ({
     return request;
   });
   return yield* LanguageModel.make({
+    codecTransformer: toCodecOpenAI,
     generateText: Effect.fnUntraced(function* (options) {
       const config = yield* makeConfig;
       const request = yield* makeRequest({
@@ -129,20 +153,20 @@ export const make = /*#__PURE__*/Effect.fnUntraced(function* ({
       annotateStreamResponse(options.span, response);
       return response;
     })))
-  }).pipe(Effect.provideService(LanguageModel.CurrentCodecTransformer, codecTransformer));
+  });
 });
 /**
  * Creates a layer for the OpenRouter language model.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = options => Layer.effect(LanguageModel.LanguageModel, make(options));
 /**
  * Provides config overrides for OpenRouter language model operations.
  *
- * @since 1.0.0
  * @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 : {}),
@@ -344,7 +368,7 @@ const buildHttpRequestDetails = request => ({
   method: request.method,
   url: request.url,
   urlParams: Array.from(request.urlParams),
-  hash: request.hash,
+  hash: Option.getOrUndefined(request.hash),
   headers: Redactable.redact(request.headers)
 });
 const buildHttpResponseDetails = response => ({
@@ -636,267 +660,260 @@ const makeStreamResponse = /*#__PURE__*/Effect.fnUntraced(function* ({
       usage.outputTokens = computed.outputTokens;
     }
     const choice = event.choices[0];
-    if (Predicate.isUndefined(choice)) {
-      return yield* AiError.make({
-        module: "OpenRouterLanguageModel",
-        method: "makeStreamResponse",
-        reason: new AiError.InvalidOutputError({
-          description: "Received response with empty choices"
-        })
-      });
-    }
-    if (Predicate.isNotNull(choice.finish_reason)) {
-      finishReason = resolveFinishReason(choice.finish_reason);
-    }
-    const delta = choice.delta;
-    if (Predicate.isNullish(delta)) {
-      return parts;
-    }
-    const emitReasoning = Effect.fnUntraced(function* (delta, metadata) {
-      if (!reasoningStarted) {
-        activeReasoningId = openRouterResponseId ?? (yield* idGenerator.generateId());
+    if (Predicate.isNotUndefined(choice)) {
+      if (Predicate.isNotNullish(choice.finish_reason)) {
+        finishReason = resolveFinishReason(choice.finish_reason);
+      }
+      const delta = choice.delta;
+      if (Predicate.isNullish(delta)) {
+        return parts;
+      }
+      const emitReasoning = Effect.fnUntraced(function* (delta, metadata) {
+        if (!reasoningStarted) {
+          activeReasoningId = openRouterResponseId ?? (yield* idGenerator.generateId());
+          parts.push({
+            type: "reasoning-start",
+            id: activeReasoningId,
+            metadata
+          });
+          reasoningStarted = true;
+        }
         parts.push({
-          type: "reasoning-start",
+          type: "reasoning-delta",
           id: activeReasoningId,
+          delta,
           metadata
         });
-        reasoningStarted = true;
-      }
-      parts.push({
-        type: "reasoning-delta",
-        id: activeReasoningId,
-        delta,
-        metadata
       });
-    });
-    const reasoningDetails = delta.reasoning_details;
-    if (Predicate.isNotUndefined(reasoningDetails) && reasoningDetails.length > 0) {
-      // Accumulate reasoning_details to preserve for multi-turn conversations
-      // Merge consecutive reasoning.text items into a single entry
-      for (const detail of reasoningDetails) {
-        if (detail.type === "reasoning.text") {
-          const lastDetail = accumulatedReasoningDetails[accumulatedReasoningDetails.length - 1];
-          if (Predicate.isNotUndefined(lastDetail) && lastDetail.type === "reasoning.text") {
-            // Merge with the previous text detail
-            lastDetail.text = (lastDetail.text ?? "") + (detail.text ?? "");
-            lastDetail.signature = lastDetail.signature ?? detail.signature ?? null;
-            lastDetail.format = lastDetail.format ?? detail.format ?? null;
+      const reasoningDetails = delta.reasoning_details;
+      if (Predicate.isNotUndefined(reasoningDetails) && reasoningDetails.length > 0) {
+        // Accumulate reasoning_details to preserve for multi-turn conversations
+        // Merge consecutive reasoning.text items into a single entry
+        for (const detail of reasoningDetails) {
+          if (detail.type === "reasoning.text") {
+            const lastDetail = accumulatedReasoningDetails[accumulatedReasoningDetails.length - 1];
+            if (Predicate.isNotUndefined(lastDetail) && lastDetail.type === "reasoning.text") {
+              // Merge with the previous text detail
+              lastDetail.text = (lastDetail.text ?? "") + (detail.text ?? "");
+              lastDetail.signature = lastDetail.signature ?? detail.signature ?? null;
+              lastDetail.format = lastDetail.format ?? detail.format ?? null;
+            } else {
+              // Start a new text detail
+              accumulatedReasoningDetails.push({
+                ...detail
+              });
+            }
           } else {
-            // Start a new text detail
-            accumulatedReasoningDetails.push({
-              ...detail
-            });
+            // Non-text details (encrypted, summary) are pushed as-is
+            accumulatedReasoningDetails.push(detail);
           }
-        } else {
-          // Non-text details (encrypted, summary) are pushed as-is
-          accumulatedReasoningDetails.push(detail);
         }
-      }
-      // Emit reasoning_details in providerMetadata for each delta chunk
-      // so users can accumulate them on their end before sending back
-      const metadata = {
-        openrouter: {
-          reasoningDetails
-        }
-      };
-      for (const detail of reasoningDetails) {
-        switch (detail.type) {
-          case "reasoning.text":
-            {
-              if (Predicate.isNotNullish(detail.text)) {
-                yield* emitReasoning(detail.text, metadata);
+        // Emit reasoning_details in providerMetadata for each delta chunk
+        // so users can accumulate them on their end before sending back
+        const metadata = {
+          openrouter: {
+            reasoningDetails
+          }
+        };
+        for (const detail of reasoningDetails) {
+          switch (detail.type) {
+            case "reasoning.text":
+              {
+                if (Predicate.isNotNullish(detail.text)) {
+                  yield* emitReasoning(detail.text, metadata);
+                }
+                break;
               }
-              break;
-            }
-          case "reasoning.summary":
-            {
-              if (Predicate.isNotNullish(detail.summary)) {
-                yield* emitReasoning(detail.summary, metadata);
+            case "reasoning.summary":
+              {
+                if (Predicate.isNotNullish(detail.summary)) {
+                  yield* emitReasoning(detail.summary, metadata);
+                }
+                break;
               }
-              break;
-            }
-          case "reasoning.encrypted":
-            {
-              if (Predicate.isNotNullish(detail.data)) {
-                yield* emitReasoning("[REDACTED]", metadata);
+            case "reasoning.encrypted":
+              {
+                if (Predicate.isNotNullish(detail.data)) {
+                  yield* emitReasoning("[REDACTED]", metadata);
+                }
+                break;
               }
-              break;
-            }
+          }
         }
+      } else if (Predicate.isNotNullish(delta.reasoning)) {
+        yield* emitReasoning(delta.reasoning);
       }
-    } else if (Predicate.isNotNullish(delta.reasoning)) {
-      yield* emitReasoning(delta.reasoning);
-    }
-    const content = delta.content;
-    if (Predicate.isNotNullish(content)) {
-      // If reasoning was previously active and now we're starting text content,
-      // we should end the reasoning first to maintain proper order
-      if (reasoningStarted && !textStarted) {
-        parts.push({
-          type: "reasoning-end",
-          id: activeReasoningId,
-          // Include accumulated reasoning_details so the we can update the
-          // reasoning part's provider metadata with the correct signature.
-          // The signature typically arrives in the last reasoning delta,
-          // but reasoning-start only carries the first delta's metadata.
-          metadata: accumulatedReasoningDetails.length > 0 ? {
-            openRouter: {
-              reasoningDetails: accumulatedReasoningDetails
-            }
-          } : undefined
-        });
-        reasoningStarted = false;
-      }
-      if (!textStarted) {
-        activeTextId = openRouterResponseId ?? (yield* idGenerator.generateId());
-        parts.push({
-          type: "text-start",
-          id: activeTextId
-        });
-        textStarted = true;
-      }
-      parts.push({
-        type: "text-delta",
-        id: activeTextId,
-        delta: content
-      });
-    }
-    const annotations = delta.annotations;
-    if (Predicate.isNotNullish(annotations)) {
-      for (const annotation of annotations) {
-        if (annotation.type === "url_citation") {
+      const content = delta.content;
+      if (Predicate.isNotNullish(content)) {
+        // If reasoning was previously active and now we're starting text content,
+        // we should end the reasoning first to maintain proper order
+        if (reasoningStarted && !textStarted) {
           parts.push({
-            type: "source",
-            sourceType: "url",
-            id: annotation.url_citation.url,
-            url: annotation.url_citation.url,
-            title: annotation.url_citation.title ?? "",
-            metadata: {
-              openrouter: {
-                ...(Predicate.isNotUndefined(annotation.url_citation.content) ? {
-                  content: annotation.url_citation.content
-                } : undefined),
-                ...(Predicate.isNotUndefined(annotation.url_citation.start_index) ? {
-                  startIndex: annotation.url_citation.start_index
-                } : undefined),
-                ...(Predicate.isNotUndefined(annotation.url_citation.end_index) ? {
-                  startIndex: annotation.url_citation.end_index
-                } : undefined)
+            type: "reasoning-end",
+            id: activeReasoningId,
+            // Include accumulated reasoning_details so the we can update the
+            // reasoning part's provider metadata with the correct signature.
+            // The signature typically arrives in the last reasoning delta,
+            // but reasoning-start only carries the first delta's metadata.
+            metadata: accumulatedReasoningDetails.length > 0 ? {
+              openRouter: {
+                reasoningDetails: accumulatedReasoningDetails
               }
-            }
+            } : undefined
           });
-        } else if (annotation.type === "file") {
-          accumulatedFileAnnotations.push(annotation);
+          reasoningStarted = false;
         }
+        if (!textStarted) {
+          activeTextId = openRouterResponseId ?? (yield* idGenerator.generateId());
+          parts.push({
+            type: "text-start",
+            id: activeTextId
+          });
+          textStarted = true;
+        }
+        parts.push({
+          type: "text-delta",
+          id: activeTextId,
+          delta: content
+        });
       }
-    }
-    const toolCalls = delta.tool_calls;
-    if (Predicate.isNotNullish(toolCalls)) {
-      for (const toolCall of toolCalls) {
-        const index = toolCall.index ?? toolCalls.length - 1;
-        let activeToolCall = activeToolCalls[index];
-        // Tool call start - OpenRouter returns all information except the
-        // tool call parameters in the first chunk
-        if (Predicate.isUndefined(activeToolCall)) {
-          if (toolCall.type !== "function") {
-            return yield* AiError.make({
-              module: "OpenRouterLanguageModel",
-              method: "makeStreamResponse",
-              reason: new AiError.InvalidOutputError({
-                description: "Received tool call delta that was not of type: 'function'"
-              })
-            });
-          }
-          if (Predicate.isUndefined(toolCall.id)) {
-            return yield* AiError.make({
-              module: "OpenRouterLanguageModel",
-              method: "makeStreamResponse",
-              reason: new AiError.InvalidOutputError({
-                description: "Received tool call delta without a tool call identifier"
-              })
+      const annotations = delta.annotations;
+      if (Predicate.isNotNullish(annotations)) {
+        for (const annotation of annotations) {
+          if (annotation.type === "url_citation") {
+            parts.push({
+              type: "source",
+              sourceType: "url",
+              id: annotation.url_citation.url,
+              url: annotation.url_citation.url,
+              title: annotation.url_citation.title ?? "",
+              metadata: {
+                openrouter: {
+                  ...(Predicate.isNotUndefined(annotation.url_citation.content) ? {
+                    content: annotation.url_citation.content
+                  } : undefined),
+                  ...(Predicate.isNotUndefined(annotation.url_citation.start_index) ? {
+                    startIndex: annotation.url_citation.start_index
+                  } : undefined),
+                  ...(Predicate.isNotUndefined(annotation.url_citation.end_index) ? {
+                    startIndex: annotation.url_citation.end_index
+                  } : undefined)
+                }
+              }
             });
+          } else if (annotation.type === "file") {
+            accumulatedFileAnnotations.push(annotation);
           }
-          if (Predicate.isUndefined(toolCall.function?.name)) {
-            return yield* AiError.make({
-              module: "OpenRouterLanguageModel",
-              method: "makeStreamResponse",
-              reason: new AiError.InvalidOutputError({
-                description: "Received tool call delta without a tool call name"
-              })
+        }
+      }
+      const toolCalls = delta.tool_calls;
+      if (Predicate.isNotNullish(toolCalls)) {
+        for (const toolCall of toolCalls) {
+          const index = toolCall.index ?? toolCalls.length - 1;
+          let activeToolCall = activeToolCalls[index];
+          // Tool call start - OpenRouter returns all information except the
+          // tool call parameters in the first chunk
+          if (Predicate.isUndefined(activeToolCall)) {
+            if (toolCall.type !== "function") {
+              return yield* AiError.make({
+                module: "OpenRouterLanguageModel",
+                method: "makeStreamResponse",
+                reason: new AiError.InvalidOutputError({
+                  description: "Received tool call delta that was not of type: 'function'"
+                })
+              });
+            }
+            if (Predicate.isNullish(toolCall.id)) {
+              return yield* AiError.make({
+                module: "OpenRouterLanguageModel",
+                method: "makeStreamResponse",
+                reason: new AiError.InvalidOutputError({
+                  description: "Received tool call delta without a tool call identifier"
+                })
+              });
+            }
+            if (Predicate.isNullish(toolCall.function?.name)) {
+              return yield* AiError.make({
+                module: "OpenRouterLanguageModel",
+                method: "makeStreamResponse",
+                reason: new AiError.InvalidOutputError({
+                  description: "Received tool call delta without a tool call name"
+                })
+              });
+            }
+            activeToolCall = {
+              id: toolCall.id,
+              type: "function",
+              name: toolCall.function.name,
+              params: toolCall.function.arguments ?? ""
+            };
+            activeToolCalls[index] = activeToolCall;
+            parts.push({
+              type: "tool-params-start",
+              id: activeToolCall.id,
+              name: activeToolCall.name
             });
-          }
-          activeToolCall = {
-            id: toolCall.id,
-            type: "function",
-            name: toolCall.function.name,
-            params: toolCall.function.arguments ?? ""
-          };
-          activeToolCalls[index] = activeToolCall;
-          parts.push({
-            type: "tool-params-start",
-            id: activeToolCall.id,
-            name: activeToolCall.name
-          });
-          // Emit a tool call delta part if parameters were also sent
-          if (activeToolCall.params.length > 0) {
+            // Emit a tool call delta part if parameters were also sent
+            if (activeToolCall.params.length > 0) {
+              parts.push({
+                type: "tool-params-delta",
+                id: activeToolCall.id,
+                delta: activeToolCall.params
+              });
+            }
+          } else {
+            // If an active tool call was found, update and emit the delta for
+            // the tool call's parameters
+            activeToolCall.params += toolCall.function?.arguments ?? "";
             parts.push({
               type: "tool-params-delta",
               id: activeToolCall.id,
               delta: activeToolCall.params
             });
           }
-        } else {
-          // If an active tool call was found, update and emit the delta for
-          // the tool call's parameters
-          activeToolCall.params += toolCall.function?.arguments ?? "";
-          parts.push({
-            type: "tool-params-delta",
-            id: activeToolCall.id,
-            delta: activeToolCall.params
-          });
+          // Check if the tool call is complete
+          // @effect-diagnostics-next-line tryCatchInEffectGen:off
+          try {
+            const params = Tool.unsafeSecureJsonParse(activeToolCall.params);
+            parts.push({
+              type: "tool-params-end",
+              id: activeToolCall.id
+            });
+            parts.push({
+              type: "tool-call",
+              id: activeToolCall.id,
+              name: activeToolCall.name,
+              params,
+              // Only attach reasoning_details to the first tool call to avoid
+              // duplicating thinking blocks for parallel tool calls (Claude)
+              metadata: reasoningDetailsAttachedToToolCall ? undefined : {
+                openrouter: {
+                  reasoningDetails: accumulatedReasoningDetails
+                }
+              }
+            });
+            reasoningDetailsAttachedToToolCall = true;
+            // Increment the total tool calls emitted by the stream and
+            // remove the active tool call
+            totalToolCalls += 1;
+            delete activeToolCalls[toolCall.index];
+          } catch {
+            // Tool call incomplete, continue parsing
+            continue;
+          }
         }
-        // Check if the tool call is complete
-        // @effect-diagnostics-next-line tryCatchInEffectGen:off
-        try {
-          const params = Tool.unsafeSecureJsonParse(activeToolCall.params);
-          parts.push({
-            type: "tool-params-end",
-            id: activeToolCall.id
-          });
+      }
+      const images = delta.images;
+      if (Predicate.isNotNullish(images)) {
+        for (const image of images) {
           parts.push({
-            type: "tool-call",
-            id: activeToolCall.id,
-            name: activeToolCall.name,
-            params,
-            // Only attach reasoning_details to the first tool call to avoid
-            // duplicating thinking blocks for parallel tool calls (Claude)
-            metadata: reasoningDetailsAttachedToToolCall ? undefined : {
-              openrouter: {
-                reasoningDetails: accumulatedReasoningDetails
-              }
-            }
+            type: "file",
+            mediaType: getMediaType(image.image_url.url, "image/jpeg"),
+            data: getBase64FromDataUrl(image.image_url.url)
           });
-          reasoningDetailsAttachedToToolCall = true;
-          // Increment the total tool calls emitted by the stream and
-          // remove the active tool call
-          totalToolCalls += 1;
-          delete activeToolCalls[toolCall.index];
-        } catch {
-          // Tool call incomplete, continue parsing
-          continue;
         }
       }
     }
-    const images = delta.images;
-    if (Predicate.isNotNullish(images)) {
-      for (const image of images) {
-        parts.push({
-          type: "file",
-          mediaType: getMediaType(image.image_url.url, "image/jpeg"),
-          data: getBase64FromDataUrl(image.image_url.url)
-        });
-      }
-    }
     // Usage is only emitted by the last part of the stream, so we need to
     // handle flushing any remaining text / reasoning / tool calls
     if (Predicate.isNotUndefined(event.usage)) {