@providerprotocol/ai 0.0.11 → 0.0.13

package/dist/openrouter/index.d.ts

@@ -1,8 +1,22 @@
-import { b as Provider, M as ModelReference, a as LLMHandler } from '../provider-CUJWjgNl.js';
+import { b as Provider, M as ModelReference, a as LLMHandler } from '../provider-mKkz7Q9U.js';
 
 /**
- * OpenRouter Chat Completions API parameters
- * These are passed through to the /api/v1/chat/completions endpoint
+ * OpenRouter-specific types for the Unified Provider Protocol.
+ *
+ * This module defines types for both the Chat Completions API and the
+ * Responses API (beta), including request/response formats, streaming
+ * events, and OpenRouter-specific features like model routing.
+ *
+ * @module types
+ */
+/**
+ * Parameters for OpenRouter's Chat Completions API.
+ *
+ * These parameters are passed through to the `/api/v1/chat/completions` endpoint.
+ * Includes standard OpenAI-compatible parameters plus OpenRouter-specific features
+ * like model routing and provider preferences.
+ *
+ * @see {@link https://openrouter.ai/docs/api-reference/chat-completions | OpenRouter Chat Completions API}
  */
 interface OpenRouterCompletionsParams {
     /** Maximum number of tokens to generate */
@@ -74,8 +88,13 @@ interface OpenRouterCompletionsParams {
     };
 }
 /**
- * OpenRouter Responses API parameters (Beta)
- * These are passed through to the /api/v1/responses endpoint
+ * Parameters for OpenRouter's Responses API (beta).
+ *
+ * These parameters are passed through to the `/api/v1/responses` endpoint.
+ * The Responses API uses a different structure than Chat Completions and
+ * supports features like reasoning configuration.
+ *
+ * @see {@link https://openrouter.ai/docs/api-reference/responses | OpenRouter Responses API}
  */
 interface OpenRouterResponsesParams {
     /** Maximum output tokens */
@@ -94,49 +113,58 @@ interface OpenRouterResponsesParams {
     };
 }
 /**
- * API mode for OpenRouter provider
+ * API mode selection for OpenRouter provider.
+ *
+ * - `'completions'`: Chat Completions API (stable, recommended)
+ * - `'responses'`: Responses API (beta)
  */
 type OpenRouterAPIMode = 'completions' | 'responses';
 /**
- * Model options when creating a model reference
+ * Options for creating an OpenRouter model reference.
  */
 interface OpenRouterModelOptions {
-    /** Which API to use */
+    /** Which API to use for this model. */
     api?: OpenRouterAPIMode;
 }
 /**
- * Model reference with OpenRouter-specific options
+ * Model reference with OpenRouter-specific options.
  */
 interface OpenRouterModelReference {
+    /** The model identifier in `provider/model` format. */
     modelId: string;
+    /** Optional API selection. */
     options?: OpenRouterModelOptions;
 }
 /**
- * OpenRouter provider configuration
+ * Configuration for the OpenRouter provider.
  */
 interface OpenRouterConfig {
-    /** Which API to use: 'completions' (default) or 'responses' (beta) */
+    /** Which API to use: 'completions' (default) or 'responses' (beta). */
     api?: 'completions' | 'responses';
 }
 /**
- * Provider routing preferences
+ * Provider routing preferences for OpenRouter.
+ *
+ * Controls how OpenRouter selects and routes requests to upstream providers.
+ *
+ * @see {@link https://openrouter.ai/docs/guides/routing/provider-selection | Provider Selection}
  */
 interface OpenRouterProviderPreferences {
-    /** Allow fallback to other providers */
+    /** Allow fallback to other providers if the primary is unavailable. */
     allow_fallbacks?: boolean;
-    /** Require specific parameters to be supported */
+    /** Require that the provider supports all specified parameters. */
     require_parameters?: boolean;
-    /** Data collection policy */
+    /** Data collection policy: 'allow' or 'deny'. */
     data_collection?: 'allow' | 'deny';
-    /** Order of provider preference */
+    /** Ordered list of preferred provider slugs. */
     order?: string[];
-    /** Ignore specific providers */
+    /** List of provider slugs to exclude from routing. */
     ignore?: string[];
-    /** Quantization preferences */
+    /** Preferred quantization levels (e.g., 'fp16', 'int8'). */
     quantizations?: string[];
 }
 /**
- * Response format
+ * Response format configuration for structured output.
  */
 type OpenRouterResponseFormat = {
     type: 'text';
@@ -145,103 +173,131 @@ type OpenRouterResponseFormat = {
 } | {
     type: 'json_schema';
     json_schema: {
+        /** Schema name for identification. */
         name: string;
+        /** Optional schema description. */
         description?: string;
+        /** JSON Schema definition. */
         schema: Record<string, unknown>;
+        /** Enable strict schema validation. */
         strict?: boolean;
     };
 };
 
-/** Union type for modalities interface */
+/**
+ * Union type for both Completions and Responses API parameter types.
+ * Used internally to type the modalities handler.
+ */
 type OpenRouterLLMParamsUnion = OpenRouterCompletionsParams | OpenRouterResponsesParams;
 /**
- * OpenRouter provider options
+ * Configuration options for creating an OpenRouter model reference.
+ *
+ * OpenRouter supports two distinct APIs:
+ * - Chat Completions API: Stable, production-ready, supports most models
+ * - Responses API: Beta, supports advanced features like reasoning
  */
 interface OpenRouterProviderOptions {
     /**
-     * Which API to use:
-     * - 'completions': Chat Completions API (default, recommended)
-     * - 'responses': Responses API (beta)
+     * Which OpenRouter API to use.
+     *
+     * - `'completions'`: Chat Completions API (default, recommended for production)
+     * - `'responses'`: Responses API (beta, supports reasoning models)
      */
     api?: 'completions' | 'responses';
 }
 /**
- * OpenRouter provider with configurable API mode
+ * OpenRouter provider interface with configurable API mode.
+ *
+ * OpenRouter is a unified API that provides access to hundreds of AI models
+ * through a single endpoint, including models from OpenAI, Anthropic, Google,
+ * Meta, Mistral, and many others.
  *
- * @example
- * // Using the Chat Completions API (default)
+ * @example Using the Chat Completions API (default)
+ * ```typescript
  * const model = openrouter('openai/gpt-4o');
+ * ```
  *
- * @example
- * // Using the Responses API (beta)
+ * @example Using the Responses API (beta)
+ * ```typescript
  * const model = openrouter('openai/gpt-4o', { api: 'responses' });
+ * ```
  *
- * @example
- * // Explicit Completions API
+ * @example Using Anthropic models
+ * ```typescript
  * const model = openrouter('anthropic/claude-3.5-sonnet', { api: 'completions' });
+ * ```
  */
 interface OpenRouterProvider extends Provider<OpenRouterProviderOptions> {
     /**
-     * Create a model reference
-     * @param modelId - The model identifier (e.g., 'openai/gpt-4o', 'anthropic/claude-3.5-sonnet', 'meta-llama/llama-3.1-70b-instruct')
-     * @param options - Provider options including API selection
+     * Creates a model reference for the specified model ID.
+     *
+     * @param modelId - The OpenRouter model identifier in `provider/model` format
+     *                  (e.g., 'openai/gpt-4o', 'anthropic/claude-3.5-sonnet',
+     *                  'meta-llama/llama-3.1-70b-instruct')
+     * @param options - Optional configuration including API selection
+     * @returns A model reference that can be passed to llm()
      */
     (modelId: string, options?: OpenRouterProviderOptions): ModelReference<OpenRouterProviderOptions>;
-    /** Provider name */
+    /** Provider identifier. Always 'openrouter'. */
     readonly name: 'openrouter';
-    /** Provider version */
+    /** Semantic version of this provider implementation. */
     readonly version: string;
-    /** Supported modalities */
+    /**
+     * Supported modalities for this provider.
+     * OpenRouter currently only supports LLM (text generation).
+     */
     readonly modalities: {
         llm: LLMHandler<OpenRouterLLMParamsUnion>;
     };
 }
 /**
- * OpenRouter provider
- *
- * Supports both the Chat Completions API (default) and Responses API (beta).
+ * OpenRouter provider singleton.
  *
  * OpenRouter is a unified API that provides access to hundreds of AI models
  * through a single endpoint, including models from OpenAI, Anthropic, Google,
  * Meta, Mistral, and many others.
  *
- * @example
- * ```ts
+ * Supports both the Chat Completions API (default) and Responses API (beta).
+ *
+ * @example Basic usage with Chat Completions API
+ * ```typescript
  * import { openrouter } from './providers/openrouter';
  * import { llm } from './core/llm';
  *
- * // Using Chat Completions API (default, recommended)
  * const model = llm({
  *   model: openrouter('openai/gpt-4o'),
  *   params: { max_tokens: 1000 }
  * });
  *
- * // Using Responses API (beta)
+ * const turn = await model.generate('Hello!');
+ * console.log(turn.response.text);
+ * ```
+ *
+ * @example Using the Responses API (beta)
+ * ```typescript
  * const betaModel = llm({
  *   model: openrouter('openai/gpt-4o', { api: 'responses' }),
  *   params: { max_output_tokens: 1000 }
  * });
+ * ```
  *
- * // Using OpenRouter-specific features
+ * @example Model routing and fallback configuration
+ * ```typescript
  * const routedModel = llm({
  *   model: openrouter('openai/gpt-4o'),
  *   params: {
  *     max_tokens: 1000,
- *     // Fallback routing
  *     models: ['openai/gpt-4o', 'anthropic/claude-3.5-sonnet'],
  *     route: 'fallback',
- *     // Provider preferences
  *     provider: {
  *       allow_fallbacks: true,
  *       require_parameters: true,
  *     },
  *   }
  * });
- *
- * // Generate
- * const turn = await model.generate('Hello!');
- * console.log(turn.response.text);
  * ```
+ *
+ * @see {@link https://openrouter.ai/docs | OpenRouter Documentation}
  */
 declare const openrouter: OpenRouterProvider;
 

package/dist/openrouter/index.js

@@ -3,17 +3,17 @@ import {
   isAssistantMessage,
   isToolResultMessage,
   isUserMessage
-} from "../chunk-W4BB4BG2.js";
+} from "../chunk-SVYROCLD.js";
 import {
   parseSSEStream
-} from "../chunk-X5G4EHL7.js";
+} from "../chunk-Z7RBRCRN.js";
 import {
   UPPError,
   doFetch,
   doStreamFetch,
   normalizeHttpError,
   resolveApiKey
-} from "../chunk-SUNYWHTH.js";
+} from "../chunk-MOU4U3PO.js";
 
 // src/providers/openrouter/transform.completions.ts
 function transformRequest(request, modelId) {
@@ -72,9 +72,25 @@ function transformMessages(messages, system) {
 function filterValidContent(content) {
   return content.filter((c) => c && typeof c.type === "string");
 }
+function extractCacheControl(message) {
+  const openrouterMeta = message.metadata?.openrouter;
+  return openrouterMeta?.cache_control;
+}
 function transformMessage(message) {
   if (isUserMessage(message)) {
     const validContent = filterValidContent(message.content);
+    const cacheControl = extractCacheControl(message);
+    if (cacheControl) {
+      const content = validContent.map(transformContentBlock);
+      for (let i = content.length - 1; i >= 0; i--) {
+        const block = content[i];
+        if (block?.type === "text") {
+          content[i] = { type: "text", text: block.text, cache_control: cacheControl };
+          break;
+        }
+      }
+      return { role: "user", content };
+    }
     if (validContent.length === 1 && validContent[0]?.type === "text") {
       return {
         role: "user",
@@ -215,7 +231,9 @@ function transformResponse(data) {
   const usage = {
     inputTokens: data.usage.prompt_tokens,
     outputTokens: data.usage.completion_tokens,
-    totalTokens: data.usage.total_tokens
+    totalTokens: data.usage.total_tokens,
+    cacheReadTokens: data.usage.prompt_tokens_details?.cached_tokens ?? 0,
+    cacheWriteTokens: 0
   };
   let stopReason = "end_turn";
   switch (choice.finish_reason) {
@@ -247,7 +265,8 @@ function createStreamState() {
     toolCalls: /* @__PURE__ */ new Map(),
     finishReason: null,
     inputTokens: 0,
-    outputTokens: 0
+    outputTokens: 0,
+    cacheReadTokens: 0
   };
 }
 function transformStreamEvent(chunk, state) {
@@ -305,6 +324,7 @@ function transformStreamEvent(chunk, state) {
   if (chunk.usage) {
     state.inputTokens = chunk.usage.prompt_tokens;
     state.outputTokens = chunk.usage.completion_tokens;
+    state.cacheReadTokens = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
   }
   return events;
 }
@@ -349,7 +369,9 @@ function buildResponseFromState(state) {
   const usage = {
     inputTokens: state.inputTokens,
     outputTokens: state.outputTokens,
-    totalTokens: state.inputTokens + state.outputTokens
+    totalTokens: state.inputTokens + state.outputTokens,
+    cacheReadTokens: state.cacheReadTokens,
+    cacheWriteTokens: 0
   };
   let stopReason = "end_turn";
   switch (state.finishReason) {
@@ -765,7 +787,9 @@ function transformResponse2(data) {
   const usage = {
     inputTokens: data.usage.input_tokens,
     outputTokens: data.usage.output_tokens,
-    totalTokens: data.usage.total_tokens
+    totalTokens: data.usage.total_tokens,
+    cacheReadTokens: data.usage.input_tokens_details?.cached_tokens ?? 0,
+    cacheWriteTokens: 0
   };
   let stopReason = "end_turn";
   if (data.status === "completed") {
@@ -794,6 +818,7 @@ function createStreamState2() {
     status: "in_progress",
     inputTokens: 0,
     outputTokens: 0,
+    cacheReadTokens: 0,
     hadRefusal: false
   };
 }
@@ -814,6 +839,7 @@ function transformStreamEvent2(event, state) {
       if (event.response?.usage) {
         state.inputTokens = event.response.usage.input_tokens;
         state.outputTokens = event.response.usage.output_tokens;
+        state.cacheReadTokens = event.response.usage.input_tokens_details?.cached_tokens ?? 0;
       }
       if (event.response?.output) {
         for (let i = 0; i < event.response.output.length; i++) {
@@ -1039,7 +1065,9 @@ function buildResponseFromState2(state) {
   const usage = {
     inputTokens: state.inputTokens,
     outputTokens: state.outputTokens,
-    totalTokens: state.inputTokens + state.outputTokens
+    totalTokens: state.inputTokens + state.outputTokens,
+    cacheReadTokens: state.cacheReadTokens,
+    cacheWriteTokens: 0
   };
   let stopReason = "end_turn";
   if (state.status === "completed") {