@x12i/ai-providers-router 4.6.0

package/dist/openrouter-catalog.js

@@ -0,0 +1,222 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getDirname } from './utils/esm-compat.js';
+// Get __dirname equivalent for ESM
+const __dirname = getDirname(import.meta.url);
+/**
+ * OpenRouter Catalog Loader
+ * Loads and caches the OpenRouter catalog data from JSON file
+ */
+export class OpenRouterCatalogLoader {
+    constructor() {
+        this.catalog = null;
+        // Default path relative to this file
+        this.catalogPath = path.join(__dirname, '..', '.metadata', 'openrouter_catalog_with_vendor_mapping.json');
+    }
+    static getInstance() {
+        if (!OpenRouterCatalogLoader.instance) {
+            OpenRouterCatalogLoader.instance = new OpenRouterCatalogLoader();
+        }
+        return OpenRouterCatalogLoader.instance;
+    }
+    /**
+     * Load the catalog from the JSON file
+     */
+    async load() {
+        if (this.catalog) {
+            return this.catalog;
+        }
+        try {
+            const data = fs.readFileSync(this.catalogPath, 'utf8');
+            this.catalog = JSON.parse(data);
+            return this.catalog;
+        }
+        catch (error) {
+            throw new Error(`Failed to load OpenRouter catalog from ${this.catalogPath}: ${error}`);
+        }
+    }
+    /**
+     * Get the loaded catalog (throws if not loaded)
+     */
+    getCatalog() {
+        if (!this.catalog) {
+            throw new Error('OpenRouter catalog not loaded. Call load() first.');
+        }
+        return this.catalog;
+    }
+    /**
+     * Get all providers
+     */
+    async getProviders() {
+        const catalog = await this.load();
+        return catalog.providers;
+    }
+    /**
+     * Get all models
+     */
+    async getModels() {
+        const catalog = await this.load();
+        return catalog.models;
+    }
+    /**
+     * Find a model by OpenRouter ID
+     */
+    async findModelById(openrouterId) {
+        const models = await this.getModels();
+        return models.find(m => m.openrouterId === openrouterId) || null;
+    }
+    /**
+     * Find models by canonical slug
+     */
+    async findModelByCanonicalSlug(canonicalSlug) {
+        const models = await this.getModels();
+        return models.find(m => m.canonicalSlug === canonicalSlug) || null;
+    }
+    /**
+     * Find models by aliases (returns all matches)
+     */
+    async findModelsByAlias(alias) {
+        const models = await this.getModels();
+        return models.filter(m => m.aliases.includes(alias));
+    }
+    /**
+     * Find provider by slug
+     */
+    async findProviderBySlug(slug) {
+        const providers = await this.getProviders();
+        return providers.find(p => p.slug === slug) || null;
+    }
+    /**
+     * Get all provider slugs
+     */
+    async getProviderSlugs() {
+        const providers = await this.getProviders();
+        return providers.map(p => p.slug);
+    }
+    /**
+     * Find provider by vendor ID (from model.vendor.direct.vendorId)
+     * This maps vendor IDs to provider slugs for alias support
+     */
+    async findProviderByVendorId(vendorId) {
+        const providers = await this.getProviders();
+        // Direct match with slug
+        const directMatch = providers.find(p => p.slug === vendorId);
+        if (directMatch) {
+            return directMatch;
+        }
+        // Some vendor IDs might be different from slugs, check common mappings
+        const vendorMappings = {
+            'xai': 'grok', // xAI is Grok's vendor
+            'meta': 'meta-llama', // Meta vendor maps to meta-llama provider
+            // Add more mappings as needed based on catalog data
+        };
+        const mappedSlug = vendorMappings[vendorId];
+        if (mappedSlug) {
+            return providers.find(p => p.slug === mappedSlug) || null;
+        }
+        return null;
+    }
+    /**
+     * Get all vendor IDs that map to providers
+     */
+    async getAllVendorIds() {
+        const models = await this.getModels();
+        const vendorIds = new Set();
+        for (const model of models) {
+            vendorIds.add(model.vendor.direct.vendorId);
+        }
+        return Array.from(vendorIds);
+    }
+    /**
+     * Check if a model is available
+     */
+    async isModelAvailable(modelId) {
+        const model = await this.findModelById(modelId);
+        return model !== null;
+    }
+    /**
+     * Get model capabilities
+     */
+    async getModelCapabilities(modelId) {
+        const model = await this.findModelById(modelId);
+        return model?.capabilities || null;
+    }
+    /**
+     * Validate model supports a specific parameter
+     */
+    async modelSupportsParameter(modelId, parameter) {
+        const capabilities = await this.getModelCapabilities(modelId);
+        return capabilities?.supportedParameters?.includes(parameter) || false;
+    }
+    /**
+     * Infer provider from model name using catalog data
+     */
+    async inferProviderFromModel(modelName) {
+        const models = await this.getModels();
+        // First try exact match with openrouterId
+        const exactMatch = models.find(m => m.openrouterId === modelName);
+        if (exactMatch) {
+            return exactMatch.vendor.author;
+        }
+        // Try alias match
+        const aliasMatch = models.find(m => m.aliases.includes(modelName));
+        if (aliasMatch) {
+            return aliasMatch.vendor.author;
+        }
+        // Try prefix match (e.g., "openai/gpt-4o" -> "openai")
+        if (modelName.includes('/')) {
+            const [prefix] = modelName.split('/');
+            const provider = await this.findProviderBySlug(prefix);
+            if (provider) {
+                return provider.slug;
+            }
+            // Also try vendor ID mapping for the prefix
+            const vendorProvider = await this.findProviderByVendorId(prefix);
+            if (vendorProvider) {
+                return vendorProvider.slug;
+            }
+        }
+        return null;
+    }
+    /**
+     * Normalize model name to OpenRouter format
+     * Returns the canonical OpenRouter ID for the model
+     */
+    async normalizeModelName(modelName, providerHint) {
+        const models = await this.getModels();
+        // If already in OpenRouter format (contains '/'), validate it
+        if (modelName.includes('/')) {
+            const model = models.find(m => m.openrouterId === modelName);
+            if (model) {
+                return model.openrouterId;
+            }
+            // If not found but contains '/', it might be an alias, continue to check
+        }
+        // Try to find by exact alias match
+        const aliasMatch = models.find(m => m.aliases.includes(modelName));
+        if (aliasMatch) {
+            return aliasMatch.openrouterId;
+        }
+        // If provider hint provided, try to construct OpenRouter ID
+        if (providerHint) {
+            const candidateId = `${providerHint}/${modelName}`;
+            const model = models.find(m => m.openrouterId === candidateId);
+            if (model) {
+                return model.openrouterId;
+            }
+        }
+        // Fallback: try to infer provider and construct ID
+        const inferredProvider = await this.inferProviderFromModel(modelName);
+        if (inferredProvider) {
+            const candidateId = `${inferredProvider}/${modelName}`;
+            const model = models.find(m => m.openrouterId === candidateId);
+            if (model) {
+                return model.openrouterId;
+            }
+        }
+        // Last resort: return as-is (might be a direct model name)
+        return modelName;
+    }
+}
+// Export singleton instance
+export const openRouterCatalog = OpenRouterCatalogLoader.getInstance();

package/dist/providers/OpenRouterProvider.d.ts

@@ -0,0 +1,16 @@
+/**
+ * OpenRouter ProviderModule wrapper using @openrouter/sdk directly
+ * This properly implements the ProviderModule interface for OpenRouter
+ */
+import type { ProviderModule } from '@x12i/ai-provider-interface';
+export interface OpenRouterProviderConfig {
+    apiKey: string;
+    baseURL?: string;
+    timeoutMs?: number;
+    httpReferer?: string;
+    xTitle?: string;
+}
+/**
+ * Create OpenRouter ProviderModule using @openrouter/sdk directly
+ */
+export declare function createOpenRouterProvider(config: OpenRouterProviderConfig): ProviderModule;

package/dist/providers/OpenRouterProvider.js

@@ -0,0 +1,171 @@
+/**
+ * OpenRouter ProviderModule wrapper using @openrouter/sdk directly
+ * This properly implements the ProviderModule interface for OpenRouter
+ */
+import { OpenRouter } from '@openrouter/sdk';
+/**
+ * Create OpenRouter ProviderModule using @openrouter/sdk directly
+ */
+export function createOpenRouterProvider(config) {
+    const client = new OpenRouter({
+        apiKey: config.apiKey,
+        serverURL: config.baseURL || 'https://openrouter.ai/api/v1',
+        httpReferer: config.httpReferer,
+        xTitle: config.xTitle,
+        timeoutMs: config.timeoutMs,
+    });
+    return {
+        name: 'openrouter',
+        capabilities: {
+            modes: {
+                sync: true,
+                stream: true,
+                batch: false,
+            },
+            operations: [
+                'openai.chat.completions.create',
+                'openai.chat.completions.stream',
+                'openai.responses.create',
+                'openai.responses.stream',
+            ],
+        },
+        async execute(spec) {
+            const { operation, args, exec } = spec;
+            // Create AbortController for timeout
+            const controller = new AbortController();
+            let timeoutId = null;
+            if (exec?.timeoutMs) {
+                timeoutId = setTimeout(() => {
+                    controller.abort();
+                }, exec.timeoutMs);
+            }
+            // Use exec.signal if provided, otherwise use our timeout controller
+            const signal = exec?.signal || controller.signal;
+            try {
+                let rawResponse;
+                if (operation === 'openai.responses.create' || operation === 'openai.chat.completions.create') {
+                    // Convert args to OpenRouter SDK format
+                    // OpenRouter SDK only supports Chat Completions format (messages array)
+                    // If adapter passed 'input' (Responses API format), convert it to messages
+                    const openRouterArgs = { ...args };
+                    // If args has 'input' field (Responses API), convert to messages format
+                    if (openRouterArgs.input && !openRouterArgs.messages) {
+                        if (typeof openRouterArgs.input === 'string') {
+                            openRouterArgs.messages = [{ role: 'user', content: openRouterArgs.input }];
+                        }
+                        else if (openRouterArgs.input.input_text) {
+                            openRouterArgs.messages = [{ role: 'user', content: openRouterArgs.input.input_text }];
+                        }
+                        else {
+                            openRouterArgs.messages = [{ role: 'user', content: JSON.stringify(openRouterArgs.input) }];
+                        }
+                        // Remove input field as OpenRouter doesn't support it
+                        delete openRouterArgs.input;
+                    }
+                    // Ensure messages array exists
+                    if (!openRouterArgs.messages || !Array.isArray(openRouterArgs.messages)) {
+                        throw new Error('OpenRouter SDK requires messages array');
+                    }
+                    // Convert max_output_tokens to max_tokens if present (Responses API -> Chat Completions)
+                    if (openRouterArgs.max_output_tokens !== undefined && openRouterArgs.max_tokens === undefined) {
+                        openRouterArgs.max_tokens = openRouterArgs.max_output_tokens;
+                        delete openRouterArgs.max_output_tokens;
+                    }
+                    // Use OpenRouter's chat API (OpenRouter uses OpenAI-compatible API)
+                    const chatResponse = await client.chat.send({
+                        ...openRouterArgs,
+                        stream: false,
+                    }, {
+                        signal,
+                    });
+                    rawResponse = chatResponse;
+                }
+                else {
+                    throw new Error(`Unsupported operation: ${operation}`);
+                }
+                return {
+                    rawResponse,
+                    rawMeta: {
+                        operation,
+                        provider: 'openrouter',
+                    },
+                };
+            }
+            catch (error) {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                throw error;
+            }
+        },
+        async *stream(spec) {
+            const { operation, args, exec } = spec;
+            // Create AbortController for timeout
+            const controller = new AbortController();
+            let timeoutId = null;
+            if (exec?.timeoutMs) {
+                timeoutId = setTimeout(() => {
+                    controller.abort();
+                }, exec.timeoutMs);
+            }
+            // Use exec.signal if provided, otherwise use our timeout controller
+            const signal = exec?.signal || controller.signal;
+            try {
+                if (operation === 'openai.responses.stream' || operation === 'openai.chat.completions.stream') {
+                    // Convert args to OpenRouter SDK format
+                    // OpenRouter SDK only supports Chat Completions format (messages array)
+                    // If adapter passed 'input' (Responses API format), convert it to messages
+                    const openRouterArgs = { ...args };
+                    // If args has 'input' field (Responses API), convert to messages format
+                    if (openRouterArgs.input && !openRouterArgs.messages) {
+                        if (typeof openRouterArgs.input === 'string') {
+                            openRouterArgs.messages = [{ role: 'user', content: openRouterArgs.input }];
+                        }
+                        else if (openRouterArgs.input.input_text) {
+                            openRouterArgs.messages = [{ role: 'user', content: openRouterArgs.input.input_text }];
+                        }
+                        else {
+                            openRouterArgs.messages = [{ role: 'user', content: JSON.stringify(openRouterArgs.input) }];
+                        }
+                        // Remove input field as OpenRouter doesn't support it
+                        delete openRouterArgs.input;
+                    }
+                    // Ensure messages array exists
+                    if (!openRouterArgs.messages || !Array.isArray(openRouterArgs.messages)) {
+                        throw new Error('OpenRouter SDK requires messages array');
+                    }
+                    // Convert max_output_tokens to max_tokens if present (Responses API -> Chat Completions)
+                    if (openRouterArgs.max_output_tokens !== undefined && openRouterArgs.max_tokens === undefined) {
+                        openRouterArgs.max_tokens = openRouterArgs.max_output_tokens;
+                        delete openRouterArgs.max_output_tokens;
+                    }
+                    // Use OpenRouter's streaming chat API
+                    const stream = await client.chat.send({
+                        ...openRouterArgs,
+                        stream: true,
+                    }, {
+                        signal,
+                    });
+                    for await (const chunk of stream) {
+                        yield {
+                            raw: chunk,
+                            rawMeta: {
+                                operation,
+                                provider: 'openrouter',
+                            },
+                        };
+                    }
+                }
+                else {
+                    throw new Error(`Unsupported streaming operation: ${operation}`);
+                }
+            }
+            catch (error) {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                throw error;
+            }
+        },
+    };
+}

package/dist/registry/AdapterRegistry.d.ts

@@ -0,0 +1,86 @@
+import type { ProviderSDKCallSpec, ProviderSDKExecResult, ProviderSDKStreamChunk, ProviderBatchResults } from '@x12i/ai-provider-interface';
+import type { AIResponse, AIStreamEvent } from '../router/RouterTypes.js';
+/**
+ * Router-side adapter interface
+ * Adapters convert router requests to ProviderSDKCallSpec and parse raw responses
+ */
+export interface RouterAdapter {
+    provider: string;
+    /**
+     * Build ProviderSDKCallSpec from router request
+     */
+    buildCallSpec(input: {
+        requestId: string;
+        mode: 'sync' | 'stream';
+        request: any;
+        exec?: {
+            timeoutMs?: number;
+            retries?: number;
+            idempotencyKey?: string;
+            signal?: AbortSignal;
+        };
+    }): ProviderSDKCallSpec | Promise<ProviderSDKCallSpec>;
+    /**
+     * Parse ProviderSDKExecResult to AIResponse
+     */
+    parseResponse(input: {
+        requestId: string;
+        request: any;
+        execResult: ProviderSDKExecResult;
+    }): AIResponse;
+    /**
+     * Parse stream chunk to router events (optional)
+     */
+    parseStreamChunk?(input: {
+        requestId: string;
+        request: any;
+        chunk: ProviderSDKStreamChunk;
+    }): AIStreamEvent[];
+    /**
+     * Finalize stream and return final response (optional)
+     */
+    finalizeStream?(input: {
+        requestId: string;
+        request: any;
+        collected: {
+            rawEvents: unknown[];
+            outputText?: string;
+        };
+        finalRaw?: unknown;
+    }): AIResponse;
+    /**
+     * Parse batch item result (optional)
+     */
+    parseBatchItem?(input: {
+        requestId: string;
+        request: any;
+        item: ProviderBatchResults['items'][number];
+    }): {
+        requestId: string;
+        rawResponse?: unknown;
+        outputText?: string;
+        error?: any;
+    };
+}
+/**
+ * Registry for router-side adapters
+ */
+export declare class AdapterRegistry {
+    private map;
+    /**
+     * Register an adapter
+     */
+    register(adapter: RouterAdapter): void;
+    /**
+     * Get adapter for a provider
+     */
+    get(provider: string): RouterAdapter;
+    /**
+     * Check if adapter exists for provider
+     */
+    has(provider: string): boolean;
+    /**
+     * List all registered adapter provider names
+     */
+    list(): string[];
+}

package/dist/registry/AdapterRegistry.js

@@ -0,0 +1,36 @@
+/**
+ * Registry for router-side adapters
+ */
+export class AdapterRegistry {
+    constructor() {
+        this.map = new Map();
+    }
+    /**
+     * Register an adapter
+     */
+    register(adapter) {
+        this.map.set(adapter.provider, adapter);
+    }
+    /**
+     * Get adapter for a provider
+     */
+    get(provider) {
+        const a = this.map.get(provider);
+        if (!a) {
+            throw new Error(`Adapter not registered for provider: ${provider}. Available: ${Array.from(this.map.keys()).join(', ')}`);
+        }
+        return a;
+    }
+    /**
+     * Check if adapter exists for provider
+     */
+    has(provider) {
+        return this.map.has(provider);
+    }
+    /**
+     * List all registered adapter provider names
+     */
+    list() {
+        return [...this.map.keys()];
+    }
+}

package/dist/registry/ProviderRegistry.d.ts

@@ -0,0 +1,24 @@
+import type { ProviderModule } from '@x12i/ai-provider-interface';
+/**
+ * Registry for provider modules
+ * Loads and manages ProviderModule instances
+ */
+export declare class ProviderRegistry {
+    private map;
+    /**
+     * Register a provider module
+     */
+    register(provider: ProviderModule): void;
+    /**
+     * Get a provider module by name
+     */
+    get(name: string): ProviderModule;
+    /**
+     * List all registered provider names
+     */
+    list(): string[];
+    /**
+     * Check if a provider is registered
+     */
+    has(name: string): boolean;
+}

package/dist/registry/ProviderRegistry.js

@@ -0,0 +1,46 @@
+/**
+ * Registry for provider modules
+ * Loads and manages ProviderModule instances
+ */
+export class ProviderRegistry {
+    constructor() {
+        this.map = new Map();
+    }
+    /**
+     * Register a provider module
+     */
+    register(provider) {
+        if (!provider.name) {
+            throw new Error('Provider module must have a name');
+        }
+        if (!provider.capabilities) {
+            throw new Error(`Provider '${provider.name}' must declare capabilities`);
+        }
+        if (!provider.execute) {
+            throw new Error(`Provider '${provider.name}' must implement execute()`);
+        }
+        this.map.set(provider.name, provider);
+    }
+    /**
+     * Get a provider module by name
+     */
+    get(name) {
+        const p = this.map.get(name);
+        if (!p) {
+            throw new Error(`Provider not registered: ${name}. Available: ${Array.from(this.map.keys()).join(', ')}`);
+        }
+        return p;
+    }
+    /**
+     * List all registered provider names
+     */
+    list() {
+        return [...this.map.keys()];
+    }
+    /**
+     * Check if a provider is registered
+     */
+    has(name) {
+        return this.map.has(name);
+    }
+}

package/dist/router/Router.d.ts

@@ -0,0 +1,33 @@
+import type { ProviderRegistry } from '../registry/ProviderRegistry.js';
+import type { AdapterRegistry } from '../registry/AdapterRegistry.js';
+import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem } from './RouterTypes.js';
+/**
+ * Main router class
+ * Orchestrates provider execution using ProviderModules and router-side adapters
+ */
+export declare class AIRouter {
+    private providers;
+    private adapters;
+    constructor(providers: ProviderRegistry, adapters: AdapterRegistry);
+    /**
+     * Resolve provider name from request, checking OpenRouter mode first
+     */
+    private resolveProviderName;
+    /**
+     * Execute a sync request
+     */
+    runSync(input: AIRouterRequest): Promise<AIResponse>;
+    /**
+     * Execute a streaming request
+     */
+    runStream(input: AIRouterRequest): AsyncIterable<AIStreamEvent>;
+    /**
+     * Execute a batch request
+     */
+    runBatch(providerName: string, items: AIBatchRequestItem[], exec?: {
+        timeoutMs?: number;
+        retries?: number;
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<AIBatchResponse>;
+}