@x12i/ai-providers-router 4.6.0

package/dist/adapters/openrouter/reasoning-capabilities.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reasoning capabilities loader from JSON registry
+ * Provides cross-vendor reasoning support detection
+ */
+type ReasoningMode = 'none' | 'effort' | 'max_tokens' | 'both';
+export interface ReasoningVisibilitySupport {
+    summary: boolean;
+    text: boolean;
+    encrypted: boolean;
+}
+export interface ReasoningCapabilities {
+    supportsReasoningDetails: boolean;
+    mode: ReasoningMode;
+    visibility: ReasoningVisibilitySupport;
+    supportedEfforts?: string[];
+    vendorId?: string;
+}
+/**
+ * Load reasoning capabilities from JSON registry based on model ID
+ */
+export declare function getReasoningCapabilitiesFromRegistry(modelId: string): ReasoningCapabilities | null;
+/**
+ * Check if model has reasoning parameter in catalog
+ */
+export declare function hasReasoningParamInCatalog(model: any): boolean;
+export {};

package/dist/adapters/openrouter/reasoning-capabilities.js

@@ -0,0 +1,79 @@
+/**
+ * Reasoning capabilities loader from JSON registry
+ * Provides cross-vendor reasoning support detection
+ */
+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);
+// Load reasoning support registry from JSON file
+// Using same pattern as openrouter-catalog.ts
+let reasoningSupportRegistry;
+try {
+    // __dirname in compiled JS will be dist/adapters/openrouter, so go up to root
+    // In TS source, __dirname will be src/adapters/openrouter
+    const registryPath = path.join(__dirname, '..', '..', '..', '.metadata', 'reasoning-support.json');
+    const registryContent = fs.readFileSync(registryPath, 'utf-8');
+    reasoningSupportRegistry = JSON.parse(registryContent);
+}
+catch (error) {
+    console.warn('[reasoning-capabilities] Failed to load reasoning-support.json, using empty registry:', error);
+    reasoningSupportRegistry = { vendors: [] };
+}
+/**
+ * Load reasoning capabilities from JSON registry based on model ID
+ */
+export function getReasoningCapabilitiesFromRegistry(modelId) {
+    const canonicalSlug = modelId.toLowerCase();
+    // Iterate through vendors in registry
+    for (const vendor of reasoningSupportRegistry.vendors) {
+        if (!vendor.supportsReasoningDetails) {
+            continue;
+        }
+        // Check each model match rule
+        for (const rule of vendor.modelMatchRules) {
+            let matches = false;
+            if (rule.matchType === 'prefix') {
+                matches = canonicalSlug.startsWith(rule.pattern.toLowerCase());
+            }
+            else if (rule.matchType === 'regex') {
+                const regex = new RegExp(rule.pattern, 'i');
+                matches = regex.test(canonicalSlug);
+            }
+            else if (rule.matchType === 'exact') {
+                matches = canonicalSlug === rule.pattern.toLowerCase();
+            }
+            if (matches) {
+                // Determine mode from requestModes
+                let mode = 'none';
+                if (vendor.requestModes.includes('effort') && vendor.requestModes.includes('max_tokens')) {
+                    mode = 'both';
+                }
+                else if (vendor.requestModes.includes('effort')) {
+                    mode = 'effort';
+                }
+                else if (vendor.requestModes.includes('max_tokens')) {
+                    mode = 'max_tokens';
+                }
+                return {
+                    supportsReasoningDetails: true,
+                    mode,
+                    visibility: vendor.visibilitySupport,
+                    supportedEfforts: mode === 'effort' || mode === 'both'
+                        ? ['low', 'medium', 'high'] // xhigh normalized to high
+                        : undefined,
+                    vendorId: vendor.vendorId,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Check if model has reasoning parameter in catalog
+ */
+export function hasReasoningParamInCatalog(model) {
+    return model?.capabilities?.supportedParameters?.includes('reasoning') ||
+        model?.capabilities?.supportedParameters?.includes('include_reasoning');
+}

package/dist/discovery.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Auto-discover installed provider packages
+ * This is a simplified implementation - in practice, you'd scan node_modules
+ * for packages matching the pattern @x12i/llm-provider-*
+ */
+export {};

package/dist/discovery.js

@@ -0,0 +1,114 @@
+/**
+ * Auto-discover installed provider packages
+ * This is a simplified implementation - in practice, you'd scan node_modules
+ * for packages matching the pattern @x12i/llm-provider-*
+ */
+/*
+ async function discoverProviders(
+  providerConfigs?: Record<string, any>
+): Promise<any[]> {
+  const providers: any[] = [];
+
+  // Common provider package patterns
+  const providerPackages = [
+    '@x12i/ai-provider-openai',
+    '@x12i/ai-provider-grok',
+  ];
+
+
+  // Also check for @x12i/x-models which may export a provider
+  try {
+    const xModelsModule = await import('@x12i/x-models').catch(() => null);
+    if (xModelsModule) {
+      // Look for provider class - check common export patterns
+      const XModelsProvider = (xModelsModule as any).XModelsAdapterProvider ||
+        (xModelsModule as any).default ||
+        (xModelsModule as any).Provider ||
+        (xModelsModule as any).LLMProvider;
+      if (XModelsProvider && typeof XModelsProvider === 'function') {
+        const config = providerConfigs?.['x-models'] || {};
+        try {
+          const providerInstance = new XModelsProvider(config);
+          if (typeof providerInstance.invoke === 'function') {
+            providers.push(providerInstance);
+          }
+        } catch (error) {
+          // Provider instantiation failed, skip it
+        }
+      }
+    }
+  } catch (error) {
+    // Package not available, skip it
+  }
+    
+  for (const packageName of providerPackages) {
+    try {
+      // Try to dynamically import the provider
+      const providerModule = await import(packageName).catch(() => null);
+      if (!providerModule) continue;
+
+      // Look for default export or named exports
+      const exported =
+        providerModule.default || providerModule.provider || providerModule[getProviderClassName(packageName)];
+
+      if (!exported) continue;
+
+      const providerName = extractProviderName(packageName);
+      const config = providerConfigs?.[providerName] || {};
+      let providerInstance: any;
+
+      if (typeof exported === 'function') {
+        // Handle class constructor
+        try {
+          providerInstance = new (exported as any)(config);
+        } catch (e) {
+          // If 'new' fails, try calling as a factory
+          try {
+            providerInstance = (exported as any)(config);
+          } catch (e2) {
+            // Both failed
+          }
+        }
+      } else if (typeof exported === 'object' && exported !== null) {
+        // Handle direct object export (ProviderModule) or factory-like object
+        if (typeof (exported as any).initializeClient === 'function') {
+          providerInstance = (exported as any).initializeClient(config);
+        } else if (exported.name && exported.execute) {
+          providerInstance = exported;
+        }
+      }
+
+      if (providerInstance) {
+        // Check for both invoke (LLMProviderInterface) and aiCall (AIProviderInterface)
+        if (typeof providerInstance.invoke === 'function' || typeof providerInstance.aiCall === 'function') {
+          providers.push(providerInstance);
+        }
+      } else {
+        console.warn(`Failed to instantiate provider ${packageName}: No valid constructor or factory found`);
+      }
+    } catch (error) {
+      // Package not installed or not available, skip it
+      continue;
+    }
+  }
+
+  return providers;
+}v
+*/
+function getProviderClassName(packageName) {
+    const parts = packageName.split('/');
+    const name = parts[parts.length - 1];
+    // Handle both ai-provider-* and llm-provider-* patterns
+    const cleanName = name.replace('ai-provider-', '').replace('llm-provider-', '');
+    const className = cleanName
+        .split('-')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('') + 'Provider';
+    return className;
+}
+function extractProviderName(packageName) {
+    const parts = packageName.split('/');
+    const name = parts[parts.length - 1];
+    return name.replace('ai-provider-', '').replace('llm-provider-', '');
+}
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+import type { ProviderId } from './types.js';
+/**
+ * Error thrown when a requested provider is not registered
+ */
+export declare class ProviderNotFoundError extends Error {
+    constructor(providerName: ProviderId | string);
+}
+/**
+ * Error thrown when all providers in the fallback chain have failed
+ */
+export declare class FallbackExhaustedError extends Error {
+    attempts: Array<{
+        provider: ProviderId;
+        error: Error;
+    }>;
+    constructor(attempts: Array<{
+        provider: ProviderId;
+        error: Error;
+    }>);
+}
+/**
+ * Error thrown when a provider package is not installed
+ */
+export declare class ProviderNotInstalledError extends Error {
+    packageName: string;
+    constructor(providerName: ProviderId | string, packageName: string);
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Error thrown when a requested provider is not registered
+ */
+export class ProviderNotFoundError extends Error {
+    constructor(providerName) {
+        super(`Provider '${providerName}' not registered`);
+        this.name = 'ProviderNotFoundError';
+        Object.setPrototypeOf(this, ProviderNotFoundError.prototype);
+    }
+}
+/**
+ * Error thrown when all providers in the fallback chain have failed
+ */
+export class FallbackExhaustedError extends Error {
+    constructor(attempts) {
+        super('All providers in fallback chain failed');
+        this.attempts = attempts;
+        this.name = 'FallbackExhaustedError';
+        Object.setPrototypeOf(this, FallbackExhaustedError.prototype);
+    }
+}
+/**
+ * Error thrown when a provider package is not installed
+ */
+export class ProviderNotInstalledError extends Error {
+    constructor(providerName, packageName) {
+        super(`Provider '${providerName}' is not installed. ` +
+            `Install it with: npm install ${packageName} or yarn add ${packageName}`);
+        this.packageName = packageName;
+        this.name = 'ProviderNotInstalledError';
+        Object.setPrototypeOf(this, ProviderNotInstalledError.prototype);
+    }
+}

package/dist/factory.d.ts

@@ -0,0 +1,15 @@
+import { LLMProviderRouter } from './router/RouterWrapper.js';
+import type { RouterConfig } from './router/RouterTypes.js';
+export interface CreateRouterConfig extends RouterConfig {
+    providerConfigs?: Record<string, any>;
+}
+/**
+ * Factory function to create a router with automatic provider discovery and configuration
+ * ERC-compliant: Supports zero-config initialization from environment variables
+ */
+export declare function createRouter(config?: CreateRouterConfig): Promise<LLMProviderRouter>;
+/**
+ * Create router from configuration file (legacy support)
+ * Note: For ERC compliance, prefer createRouter() with environment variables
+ */
+export declare function createRouterFromConfig(configPath: string): Promise<LLMProviderRouter>;

package/dist/factory.js

@@ -0,0 +1,206 @@
+import { LLMProviderRouter } from './router/RouterWrapper.js';
+import dns from 'node:dns';
+import dotenv from 'dotenv';
+// Fix IPv6-first DNS resolution issue on Windows (forces IPv4-first to avoid connect timeouts)
+// This prevents undici from trying IPv6 first on networks that silently drop IPv6 traffic
+// Must be set before any network calls are made
+dns.setDefaultResultOrder('ipv4first');
+// Set undici global dispatcher connectTimeout to prevent hard 10s connect timeout
+// This must be done before any provider initializes to ensure all fetch calls use the correct timeout
+// Dynamic import for optional dependency (undici might not be available)
+(async () => {
+    try {
+        const { Agent, setGlobalDispatcher } = await import('undici');
+        // Set a reasonable default connect timeout (60s) - providers can override via their config
+        // This prevents undici's hard-coded 10s connect timeout from causing premature failures
+        const defaultConnectTimeout = 60000; // 60 seconds
+        setGlobalDispatcher(new Agent({
+            connectTimeout: defaultConnectTimeout,
+        }));
+    }
+    catch (e) {
+        // undici not available or already set - continue without it
+        // This is a best-effort fix; providers should also set their own dispatchers
+    }
+})();
+// Load environment variables from .env file if available
+// This ensures nx-config2 can resolve ENV. placeholders
+// dotenv.config() is idempotent and won't overwrite existing process.env values
+dotenv.config();
+/**
+ * Resolve ENV. placeholders to actual environment variable values
+ * Replaces nx-config2 functionality to avoid ESM/CommonJS compatibility issues
+ */
+function resolveEnvPlaceholders(config) {
+    if (typeof config === 'string') {
+        // Handle ENV.VAR_NAME||default pattern
+        if (config.startsWith('ENV.')) {
+            const match = config.match(/^ENV\.([^|]+)(?:\|\|(.+))?$/);
+            if (match) {
+                const envVar = match[1];
+                const defaultValue = match[2] !== undefined ? match[2] : undefined;
+                const value = process.env[envVar];
+                return value !== undefined ? value : (defaultValue !== undefined ? defaultValue : config);
+            }
+        }
+        return config;
+    }
+    if (Array.isArray(config)) {
+        return config.map(item => resolveEnvPlaceholders(item));
+    }
+    if (config && typeof config === 'object') {
+        const resolved = {};
+        for (const [key, value] of Object.entries(config)) {
+            resolved[key] = resolveEnvPlaceholders(value);
+        }
+        return resolved;
+    }
+    return config;
+}
+/**
+ * Legacy provider inference function (fallback when catalog is unavailable)
+ */
+function inferProviderFromModelLegacy(model) {
+    if (model.startsWith('gpt-') || model.startsWith('o1-') || model.startsWith('openai/')) {
+        return 'openai';
+    }
+    else if (model.startsWith('claude-') || model.startsWith('anthropic/')) {
+        return 'anthropic';
+    }
+    else if (model.startsWith('grok-') || model.startsWith('xai/')) {
+        return 'grok';
+    }
+    else if (model.startsWith('gemini-') || model.startsWith('google/')) {
+        return 'google';
+    }
+    else if (model.startsWith('llama-') || model.startsWith('meta-llama/')) {
+        return 'meta';
+    }
+    return undefined;
+}
+/**
+ * Factory function to create a router with automatic provider discovery and configuration
+ * ERC-compliant: Supports zero-config initialization from environment variables
+ */
+export async function createRouter(config) {
+    // ERC Configuration: Define router and provider requirements
+    // Use our own resolver instead of nx-config2 to avoid ESM/CommonJS compatibility issues
+    const ercConfig = {
+        // Router-specific configuration
+        router: {
+            logLevel: 'ENV.AI_PROVIDER_ROUTER_LOG_LEVEL||info',
+            verbose: 'ENV.AI_PROVIDER_ROUTER_VERBOSE||false',
+            timeoutMs: 'ENV.AI_PROVIDER_ROUTER_TIMEOUT_MS||60000',
+        },
+        // Provider SDK client configurations (auto-detected from environment)
+        providers: {
+            openai: {
+                apiKey: 'ENV.OPENAI_API_KEY',
+                baseURL: 'ENV.OPENAI_API_BASE',
+                organization: 'ENV.OPENAI_ORGANIZATION',
+            },
+            xai: {
+                apiKey: 'ENV.GROK_API_KEY',
+                baseURL: 'ENV.XAI_API_BASE',
+            },
+            groq: {
+                apiKey: 'ENV.GROQ_API_KEY',
+            },
+            anthropic: {
+                apiKey: 'ENV.ANTHROPIC_API_KEY',
+                baseURL: 'ENV.ANTHROPIC_API_BASE',
+            },
+            google: {
+                apiKey: 'ENV.GOOGLE_API_KEY',
+            },
+            openrouter: {
+                apiKey: 'ENV.OPEN_ROUTER_KEY',
+                httpReferer: 'ENV.OPEN_ROUTER_HTTP_REFERER',
+                xTitle: 'ENV.OPEN_ROUTER_X_TITLE',
+                useOpenRouter: 'ENV.USE_OPENROUTER',
+            },
+        },
+    };
+    // Resolve ENV. placeholders
+    const ercResult = {
+        config: resolveEnvPlaceholders(ercConfig)
+    };
+    // Use explicit config if provided (Advanced Mode), otherwise use ERC auto-discovered config (Zero-Config Mode)
+    const finalConfig = Object.keys(config || {}).length > 0 ? config : {
+        logLevel: ercResult.config.router.logLevel,
+        verbose: ercResult.config.router.verbose === 'true' || ercResult.config.router.verbose === true,
+        timeoutMs: ercResult.config.router.timeoutMs ? parseInt(String(ercResult.config.router.timeoutMs), 10) : undefined,
+        defaultTimeoutMs: ercResult.config.router.timeoutMs ? parseInt(String(ercResult.config.router.timeoutMs), 10) : undefined,
+    };
+    const router = new LLMProviderRouter(finalConfig);
+    // Configure providers from ERC auto-detected config OR explicit config
+    const providerConfigs = config?.providerConfigs || ercResult.config.providers;
+    // Check if OpenRouter mode should be enabled
+    // Default: true if OPEN_ROUTER_KEY is present, else false
+    // Can be explicitly disabled with USE_OPENROUTER=false
+    const openRouterKey = providerConfigs.openrouter?.apiKey;
+    const useOpenRouterEnv = providerConfigs.openrouter?.useOpenRouter;
+    // Check if API key is valid (not placeholder, not empty)
+    const hasValidKey = openRouterKey &&
+        openRouterKey !== 'ENV.OPEN_ROUTER_KEY' &&
+        typeof openRouterKey === 'string' &&
+        openRouterKey.trim() !== '';
+    // Determine if OpenRouter should be enabled
+    // Default to true if key is present, unless explicitly disabled
+    let useOpenRouter = false;
+    if (hasValidKey) {
+        if (useOpenRouterEnv === undefined || useOpenRouterEnv === '' || useOpenRouterEnv === 'true' || useOpenRouterEnv === true) {
+            useOpenRouter = true;
+        }
+        else if (useOpenRouterEnv === 'false' || useOpenRouterEnv === false) {
+            useOpenRouter = false;
+        }
+        else {
+            // Default to true if key is present
+            useOpenRouter = true;
+        }
+    }
+    // NOTE: We don't need to manually register providers here anymore if they are 
+    // in environment variables, as LLMProviderRouter will auto-register them 
+    // on first invoke/stream/createBatch call.
+    // We only register them here if they were provided in the explicit config.
+    if (config?.providerConfigs) {
+        // Manual registration from explicit config
+        for (const [name, pConfig] of Object.entries(config.providerConfigs)) {
+            if (pConfig && pConfig.apiKey && !pConfig.apiKey.startsWith('ENV.')) {
+                router.configureProvider(name, pConfig);
+                try {
+                    if (name === 'openai') {
+                        const mod = await import('@x12i/ai-provider-openai');
+                        router.registerProvider(mod, 'initializeClient');
+                    }
+                    else if (name === 'grok' || name === 'xai') {
+                        const mod = await import('@x12i/ai-provider-grok');
+                        router.registerProvider(mod);
+                    }
+                }
+                catch (e) {
+                    // Skip if provider package not installed
+                }
+            }
+        }
+    }
+    return router;
+}
+/**
+ * Create router from configuration file (legacy support)
+ * Note: For ERC compliance, prefer createRouter() with environment variables
+ */
+export async function createRouterFromConfig(configPath) {
+    // Load config file
+    const fs = await import('fs/promises');
+    const configContent = await fs.readFile(configPath, 'utf-8');
+    const fileConfig = JSON.parse(configContent);
+    // Convert file config to router config format
+    const routerConfig = {
+        providerConfigs: fileConfig.providers,
+        logLevel: fileConfig.logLevel,
+        verbose: fileConfig.verbose,
+    };
+    return createRouter(routerConfig);
+}

package/dist/gateway.d.ts

@@ -0,0 +1,22 @@
+import { LLMProviderRouter } from './router/RouterWrapper.js';
+import type { AIResponse } from './router/RouterTypes.js';
+export interface EnhancedLLMResponse extends AIResponse {
+    content?: {
+        providerMetadata?: {
+            provider?: string;
+            model?: string;
+            [key: string]: any;
+        };
+        [key: string]: any;
+    };
+    metadata?: any;
+}
+export declare class AIGateway {
+    private router;
+    constructor(router?: LLMProviderRouter);
+    invoke(request: any): Promise<EnhancedLLMResponse>;
+    private invokeInternal;
+    private validateRequest;
+    private extractOutboundPrompt;
+    private looksLikeConfigJSON;
+}