@standardagents/openrouter 0.10.0-dev.ffffff

package/LICENSE.txt

@@ -0,0 +1,48 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2025 FormKit Inc. All Rights Reserved.
+
+UNLICENSED - DO NOT USE
+
+This software and associated documentation files (the "Software") are the sole
+and exclusive property of FormKit Inc. ("FormKit").
+
+USE RESTRICTIONS
+
+The Software is UNLICENSED and proprietary. NO PERMISSION is granted to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, or to permit persons to whom the Software is furnished to do so,
+under any circumstances, without prior written authorization from FormKit Inc.
+
+UNAUTHORIZED USE PROHIBITED
+
+Any use of this Software without a valid, written license agreement signed by
+authorized officers of FormKit Inc. is strictly prohibited and constitutes
+unauthorized use and infringement of FormKit's intellectual property rights.
+
+LICENSING INQUIRIES
+
+Organizations interested in licensing this Software should contact:
+enterprise@formkit.com
+
+A written license agreement must be executed before any use of this Software
+is authorized.
+
+NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+FORMKIT INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+GOVERNING LAW
+
+This license shall be governed by and construed in accordance with the laws
+of the jurisdiction in which FormKit Inc. is incorporated, without regard to
+its conflict of law provisions.
+
+FormKit Inc.
+https://formkit.com
+enterprise@formkit.com

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+import { LLMProviderInterface, ProviderFactoryConfig, ModelCapabilities, ProviderModelInfo, ProviderRequest, ProviderResponse, ProviderStreamChunk, ResponseSummary, InspectedRequest, ProviderFactoryWithOptions } from '@standardagents/spec';
+import { z } from 'zod';
+
+/**
+ * OpenRouter provider options schema.
+ *
+ * Defines typed providerOptions for OpenRouter models, providing
+ * TypeScript autocompletion and runtime validation.
+ *
+ * @see https://openrouter.ai/docs/guides/routing/provider-selection
+ * @module
+ */
+
+/**
+ * OpenRouter provider options schema.
+ *
+ * Routing options are nested under the `provider` key to match
+ * OpenRouter's API structure.
+ *
+ * @example
+ * ```typescript
+ * providerOptions: {
+ *   provider: {
+ *     zdr: true,
+ *     max_price: { prompt: 1, completion: 5 },
+ *     order: ['anthropic', 'openai'],
+ *   },
+ * }
+ * ```
+ */
+declare const openrouterProviderOptions: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodObject<{
+        order: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allow_fallbacks: z.ZodOptional<z.ZodBoolean>;
+        require_parameters: z.ZodOptional<z.ZodBoolean>;
+        data_collection: z.ZodOptional<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>>;
+        zdr: z.ZodOptional<z.ZodBoolean>;
+        only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sort: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            price: "price";
+            throughput: "throughput";
+            latency: "latency";
+        }>, z.ZodObject<{
+            by: z.ZodEnum<{
+                price: "price";
+                throughput: "throughput";
+                latency: "latency";
+            }>;
+            partition: z.ZodOptional<z.ZodEnum<{
+                model: "model";
+                none: "none";
+            }>>;
+        }, z.core.$strip>]>>;
+        max_price: z.ZodOptional<z.ZodObject<{
+            prompt: z.ZodOptional<z.ZodNumber>;
+            completion: z.ZodOptional<z.ZodNumber>;
+            request: z.ZodOptional<z.ZodNumber>;
+            image: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        quantizations: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            unknown: "unknown";
+            int4: "int4";
+            int8: "int8";
+            fp4: "fp4";
+            fp6: "fp6";
+            fp8: "fp8";
+            fp16: "fp16";
+            bf16: "bf16";
+            fp32: "fp32";
+        }>>>;
+        preferred_min_throughput: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            p50: z.ZodOptional<z.ZodNumber>;
+            p75: z.ZodOptional<z.ZodNumber>;
+            p90: z.ZodOptional<z.ZodNumber>;
+            p99: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
+        preferred_max_latency: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            p50: z.ZodOptional<z.ZodNumber>;
+            p75: z.ZodOptional<z.ZodNumber>;
+            p90: z.ZodOptional<z.ZodNumber>;
+            p99: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
+        enforce_distillable_text: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/**
+ * TypeScript type for OpenRouter provider options.
+ * Inferred from the Zod schema for type-safe usage.
+ */
+type OpenRouterProviderOptions = z.infer<typeof openrouterProviderOptions>;
+
+/**
+ * Extended provider config for OpenRouter
+ */
+interface OpenRouterConfig extends ProviderFactoryConfig {
+    /** List of providers to route to (e.g., ['openai', 'anthropic']) */
+    providers?: string[];
+}
+/**
+ * OpenRouter provider implementation for Standard Agents
+ *
+ * Uses the official @openrouter/sdk Responses API for API calls.
+ * OpenRouter is a multi-provider gateway that routes requests to various LLM providers.
+ */
+declare class OpenRouterProvider implements LLMProviderInterface {
+    readonly name = "openrouter";
+    readonly specificationVersion: "1";
+    private client;
+    private config;
+    constructor(config: OpenRouterConfig);
+    private getClient;
+    supportsModel(_modelId: string): boolean;
+    /**
+     * Get the icon for a model as a data URI.
+     * Extracts the AI lab/organization from the model ID prefix and returns
+     * the corresponding SVG icon as a data URI.
+     * For example, 'anthropic/claude-3-opus' returns the Anthropic icon.
+     * Falls back to the OpenRouter icon for unknown labs.
+     */
+    getIcon(modelId?: string): string;
+    /** Cache for model capabilities to avoid repeated API calls */
+    private static modelsCache;
+    private static modelsCacheTime;
+    private static readonly CACHE_TTL;
+    /**
+     * Get capabilities for a specific model.
+     * Fetches from OpenRouter's models API which provides rich metadata.
+     */
+    getModelCapabilities(modelId: string): Promise<ModelCapabilities | null>;
+    private fetchModelsWithCache;
+    private mapOpenRouterCapabilities;
+    /**
+     * Get list of available models from OpenRouter.
+     * Fetches from OpenRouter's public models API with caching.
+     *
+     * @param filter - Optional search string to filter models by name/id
+     */
+    getModels(filter?: string): Promise<ProviderModelInfo[]>;
+    private mapToProviderModelInfo;
+    generate(request: ProviderRequest): Promise<ProviderResponse>;
+    stream(request: ProviderRequest): Promise<AsyncIterable<ProviderStreamChunk>>;
+    /**
+     * Fetch additional metadata about a completed response.
+     * Called asynchronously after the response is received.
+     *
+     * Uses OpenRouter's /generation endpoint to fetch accurate provider info,
+     * token counts, and cost data.
+     */
+    getResponseMetadata(summary: ResponseSummary, signal?: AbortSignal): Promise<Record<string, unknown> | null>;
+    private toProviderError;
+    /**
+     * Transform a ProviderRequest to OpenRouter Responses API format for inspection.
+     * Returns the exact request body that would be sent to OpenRouter, with base64 data truncated.
+     */
+    inspectRequest(request: ProviderRequest): Promise<InspectedRequest>;
+}
+
+/**
+ * Generation metadata returned by OpenRouter's /api/v1/generation endpoint.
+ * Contains accurate usage, cost, and provider information.
+ */
+interface GenerationMetadata {
+    /** Unique generation ID */
+    id: string;
+    /** Total cost in USD */
+    totalCost: number;
+    /** Input/prompt tokens */
+    promptTokens: number;
+    /** Output/completion tokens */
+    completionTokens: number;
+    /** Native input tokens (provider-specific) */
+    nativePromptTokens?: number;
+    /** Native output tokens (provider-specific) */
+    nativeCompletionTokens?: number;
+    /** Actual provider that served the request */
+    providerName: string;
+    /** Request latency in milliseconds */
+    latency?: number;
+    /** Model used */
+    model?: string;
+    /** Finish reason */
+    finishReason?: string;
+    /** Created timestamp */
+    createdAt?: string;
+}
+/**
+ * Fetch generation metadata from OpenRouter after a stream completes.
+ *
+ * This is the recommended way to get accurate token usage, cost, and provider
+ * information. Should be called with the responseId from the finish chunk.
+ *
+ * @param apiKey - OpenRouter API key
+ * @param generationId - The response/generation ID from the stream finish chunk
+ * @param baseUrl - Optional base URL (defaults to https://openrouter.ai/api/v1)
+ * @param signal - Optional abort signal for cancellation
+ * @returns Generation metadata or null if not available
+ */
+declare function fetchGenerationMetadata(apiKey: string, generationId: string, baseUrl?: string, signal?: AbortSignal): Promise<GenerationMetadata | null>;
+
+/**
+ * OpenRouter provider factory for Standard Agents
+ *
+ * OpenRouter is a multi-provider gateway that routes requests to various LLM providers.
+ * Includes typed providerOptions for routing configuration.
+ *
+ * @example
+ * ```typescript
+ * import { defineModel } from '@standardagents/builder';
+ * import { openrouter } from '@standardagents/openrouter';
+ *
+ * export default defineModel({
+ *   name: 'claude-3-opus',
+ *   provider: openrouter,
+ *   model: 'anthropic/claude-3-opus',
+ *   inputPrice: 15,
+ *   outputPrice: 75,
+ *   capabilities: {
+ *     supportsImages: true,
+ *     supportsToolCalls: true,
+ *     maxContextTokens: 200000,
+ *   },
+ *   providerOptions: {
+ *     provider: {
+ *       zdr: true,
+ *       only: ['anthropic'],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare const openrouter: ProviderFactoryWithOptions<typeof openrouterProviderOptions>;
+
+export { type GenerationMetadata, type OpenRouterConfig, OpenRouterProvider, type OpenRouterProviderOptions, fetchGenerationMetadata, openrouter, openrouterProviderOptions };