elsabro 2.3.0 → 3.8.0

package/references/multi-llm-providers.md

@@ -0,0 +1,2494 @@
+# Multi-LLM Providers System (v3.6)
+
+Sistema unificado de gestion de multiples proveedores de LLM con routing inteligente, fallback automatico y optimizacion de costos.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        MULTI-LLM PROVIDERS SYSTEM                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────┐     │
+│  │                         UNIFIED API                                 │     │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │     │
+│  │  │   complete() │  │   stream()   │  │   countTokens()          │  │     │
+│  │  │   chat()     │  │   embed()    │  │   estimateCost()         │  │     │
+│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │     │
+│  └────────────────────────────────────────────────────────────────────┘     │
+│                                    │                                         │
+│                                    ▼                                         │
+│  ┌────────────────────────────────────────────────────────────────────┐     │
+│  │                        MODEL ROUTER                                 │     │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │     │
+│  │  │ Task-Based  │  │    Cost     │  │    Load     │  │   Rate    │  │     │
+│  │  │   Routing   │  │ Optimization│  │  Balancing  │  │  Limiting │  │     │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘  └───────────┘  │     │
+│  └────────────────────────────────────────────────────────────────────┘     │
+│                                    │                                         │
+│                                    ▼                                         │
+│  ┌────────────────────────────────────────────────────────────────────┐     │
+│  │                      PROVIDER REGISTRY                              │     │
+│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  │     │
+│  │  │ Claude  │  │ OpenAI  │  │ Gemini  │  │  Local  │  │  Azure  │  │     │
+│  │  │(default)│  │  GPT-4  │  │  Flash  │  │ Ollama  │  │ OpenAI  │  │     │
+│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘  │     │
+│  └────────────────────────────────────────────────────────────────────┘     │
+│                                    │                                         │
+│                                    ▼                                         │
+│  ┌────────────────────────────────────────────────────────────────────┐     │
+│  │                      HEALTH & MONITORING                            │     │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │     │
+│  │  │   Health    │  │   Status    │  │  Automatic  │                 │     │
+│  │  │   Checks    │  │  Monitoring │  │  Fallback   │                 │     │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘                 │     │
+│  └────────────────────────────────────────────────────────────────────┘     │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ProviderRegistry
+
+### Interfaces Base
+
+```typescript
+interface LLMProvider<TConfig extends ProviderConfig = ProviderConfig> {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly config: TConfig;
+
+  // Core methods
+  complete(request: CompletionRequest): Promise<CompletionResponse>;
+  stream(request: CompletionRequest): AsyncIterable<StreamChunk>;
+
+  // Optional capabilities
+  embed?(texts: string[]): Promise<EmbeddingResponse>;
+  countTokens(text: string, model?: string): Promise<number>;
+
+  // Health & status
+  healthCheck(): Promise<HealthStatus>;
+  getStatus(): ProviderStatus;
+
+  // Lifecycle
+  initialize(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+interface ProviderConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+  retryDelay?: number;
+  rateLimit?: RateLimitConfig;
+  headers?: Record<string, string>;
+}
+
+interface RateLimitConfig {
+  requestsPerMinute: number;
+  tokensPerMinute: number;
+  tokensPerDay?: number;
+  concurrent?: number;
+}
+
+interface CompletionRequest {
+  model: string;
+  messages: Message[];
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  stopSequences?: string[];
+  tools?: ToolDefinition[];
+  toolChoice?: 'auto' | 'none' | 'required' | { name: string };
+  responseFormat?: 'text' | 'json' | { schema: JSONSchema };
+  metadata?: Record<string, unknown>;
+}
+
+interface Message {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | ContentBlock[];
+  name?: string;
+  toolCallId?: string;
+  toolCalls?: ToolCall[];
+}
+
+interface ContentBlock {
+  type: 'text' | 'image' | 'file';
+  text?: string;
+  imageUrl?: string;
+  imageBase64?: string;
+  mimeType?: string;
+  fileName?: string;
+}
+
+interface CompletionResponse {
+  id: string;
+  model: string;
+  content: string;
+  toolCalls?: ToolCall[];
+  usage: TokenUsage;
+  finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+  metadata?: {
+    provider: string;
+    latencyMs: number;
+    cached?: boolean;
+  };
+}
+
+interface StreamChunk {
+  type: 'content' | 'tool_call' | 'usage' | 'done';
+  content?: string;
+  toolCall?: Partial<ToolCall>;
+  usage?: Partial<TokenUsage>;
+  finishReason?: string;
+}
+
+interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+interface ToolCall {
+  id: string;
+  name: string;
+  arguments: string;
+}
+
+interface HealthStatus {
+  healthy: boolean;
+  latencyMs: number;
+  lastCheck: string;
+  error?: string;
+  details?: Record<string, unknown>;
+}
+
+interface ProviderStatus {
+  id: string;
+  name: string;
+  healthy: boolean;
+  enabled: boolean;
+  availableModels: string[];
+  rateLimitRemaining?: {
+    requests: number;
+    tokens: number;
+  };
+  lastError?: {
+    message: string;
+    timestamp: string;
+    code?: string;
+  };
+}
+```
+
+### ProviderRegistry Implementation
+
+```typescript
+interface RegisteredProvider {
+  provider: LLMProvider;
+  priority: number;
+  enabled: boolean;
+  healthStatus: HealthStatus;
+  metrics: ProviderMetrics;
+}
+
+interface ProviderMetrics {
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  totalTokens: number;
+  totalCost: number;
+  avgLatencyMs: number;
+  p95LatencyMs: number;
+  lastUsed?: string;
+}
+
+class ProviderRegistry {
+  private providers: Map<string, RegisteredProvider> = new Map();
+  private healthCheckInterval: NodeJS.Timer | null = null;
+  private config: ProviderRegistryConfig;
+
+  constructor(config: ProviderRegistryConfig) {
+    this.config = config;
+  }
+
+  // Register a provider
+  async register(
+    provider: LLMProvider,
+    options: { priority?: number; enabled?: boolean } = {}
+  ): Promise<void> {
+    const { priority = 100, enabled = true } = options;
+
+    // Initialize provider
+    await provider.initialize();
+
+    // Initial health check
+    const healthStatus = await provider.healthCheck();
+
+    this.providers.set(provider.id, {
+      provider,
+      priority,
+      enabled,
+      healthStatus,
+      metrics: {
+        totalRequests: 0,
+        successfulRequests: 0,
+        failedRequests: 0,
+        totalTokens: 0,
+        totalCost: 0,
+        avgLatencyMs: 0,
+        p95LatencyMs: 0
+      }
+    });
+
+    EventBus.publish('provider.registered', {
+      id: provider.id,
+      name: provider.name,
+      priority,
+      healthy: healthStatus.healthy
+    });
+  }
+
+  // Unregister a provider
+  async unregister(providerId: string): Promise<boolean> {
+    const registered = this.providers.get(providerId);
+    if (!registered) return false;
+
+    await registered.provider.shutdown();
+    this.providers.delete(providerId);
+
+    EventBus.publish('provider.unregistered', { id: providerId });
+    return true;
+  }
+
+  // Get provider by ID
+  get(providerId: string): LLMProvider | undefined {
+    return this.providers.get(providerId)?.provider;
+  }
+
+  // Get all healthy providers sorted by priority
+  getHealthyProviders(): LLMProvider[] {
+    return Array.from(this.providers.values())
+      .filter(p => p.enabled && p.healthStatus.healthy)
+      .sort((a, b) => a.priority - b.priority)
+      .map(p => p.provider);
+  }
+
+  // Get provider for specific model
+  getProviderForModel(model: string): LLMProvider | undefined {
+    for (const registered of this.providers.values()) {
+      if (!registered.enabled || !registered.healthStatus.healthy) continue;
+
+      const status = registered.provider.getStatus();
+      if (status.availableModels.includes(model)) {
+        return registered.provider;
+      }
+    }
+    return undefined;
+  }
+
+  // List all providers with status
+  list(): ProviderStatus[] {
+    return Array.from(this.providers.values()).map(r => ({
+      ...r.provider.getStatus(),
+      healthy: r.healthStatus.healthy,
+      enabled: r.enabled
+    }));
+  }
+
+  // Enable/disable provider
+  setEnabled(providerId: string, enabled: boolean): void {
+    const registered = this.providers.get(providerId);
+    if (registered) {
+      registered.enabled = enabled;
+      EventBus.publish('provider.status_changed', { id: providerId, enabled });
+    }
+  }
+
+  // Update metrics after request
+  recordMetrics(
+    providerId: string,
+    success: boolean,
+    latencyMs: number,
+    tokens: number,
+    cost: number
+  ): void {
+    const registered = this.providers.get(providerId);
+    if (!registered) return;
+
+    const m = registered.metrics;
+    m.totalRequests++;
+    if (success) {
+      m.successfulRequests++;
+    } else {
+      m.failedRequests++;
+    }
+    m.totalTokens += tokens;
+    m.totalCost += cost;
+    m.lastUsed = new Date().toISOString();
+
+    // Rolling average for latency
+    m.avgLatencyMs = (m.avgLatencyMs * (m.totalRequests - 1) + latencyMs) / m.totalRequests;
+  }
+
+  // Get provider metrics
+  getMetrics(providerId: string): ProviderMetrics | undefined {
+    return this.providers.get(providerId)?.metrics;
+  }
+
+  // Start health check loop
+  startHealthChecks(intervalMs: number = 30000): void {
+    this.healthCheckInterval = setInterval(async () => {
+      for (const [id, registered] of this.providers) {
+        try {
+          const status = await registered.provider.healthCheck();
+          const wasHealthy = registered.healthStatus.healthy;
+          registered.healthStatus = status;
+
+          if (wasHealthy !== status.healthy) {
+            EventBus.publish('provider.health_changed', {
+              id,
+              healthy: status.healthy,
+              error: status.error
+            });
+          }
+        } catch (error) {
+          registered.healthStatus = {
+            healthy: false,
+            latencyMs: 0,
+            lastCheck: new Date().toISOString(),
+            error: error instanceof Error ? error.message : 'Health check failed'
+          };
+        }
+      }
+    }, intervalMs);
+  }
+
+  // Stop health checks
+  stopHealthChecks(): void {
+    if (this.healthCheckInterval) {
+      clearInterval(this.healthCheckInterval);
+      this.healthCheckInterval = null;
+    }
+  }
+
+  // Shutdown all providers
+  async shutdown(): Promise<void> {
+    this.stopHealthChecks();
+    for (const registered of this.providers.values()) {
+      await registered.provider.shutdown();
+    }
+    this.providers.clear();
+  }
+}
+```
+
+---
+
+## Provider Implementations
+
+### ClaudeProvider (Default)
+
+```typescript
+interface ClaudeConfig extends ProviderConfig {
+  apiKey: string;
+  baseUrl?: string;
+  defaultModel?: string;
+  betaHeaders?: string[];
+}
+
+class ClaudeProvider implements LLMProvider<ClaudeConfig> {
+  readonly id = 'claude';
+  readonly name = 'Anthropic Claude';
+  readonly version = '1.0.0';
+  readonly config: ClaudeConfig;
+
+  private client: Anthropic;
+
+  static readonly MODELS = {
+    'claude-opus-4-5': {
+      id: 'claude-opus-4-5-20251101',
+      contextWindow: 200000,
+      maxOutput: 32000,
+      inputPrice: 15.0,    // per 1M tokens
+      outputPrice: 75.0,
+      capabilities: ['vision', 'tools', 'extended_thinking']
+    },
+    'claude-sonnet-4': {
+      id: 'claude-sonnet-4-20250514',
+      contextWindow: 200000,
+      maxOutput: 64000,
+      inputPrice: 3.0,
+      outputPrice: 15.0,
+      capabilities: ['vision', 'tools', 'computer_use']
+    },
+    'claude-3-5-haiku': {
+      id: 'claude-3-5-haiku-20241022',
+      contextWindow: 200000,
+      maxOutput: 8192,
+      inputPrice: 0.80,
+      outputPrice: 4.0,
+      capabilities: ['vision', 'tools']
+    }
+  };
+
+  constructor(config: ClaudeConfig) {
+    this.config = {
+      baseUrl: 'https://api.anthropic.com',
+      defaultModel: 'claude-sonnet-4',
+      timeout: 120000,
+      maxRetries: 3,
+      ...config
+    };
+  }
+
+  async initialize(): Promise<void> {
+    this.client = new Anthropic({
+      apiKey: this.config.apiKey,
+      baseURL: this.config.baseUrl,
+      timeout: this.config.timeout,
+      maxRetries: this.config.maxRetries
+    });
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const startTime = Date.now();
+    const modelId = this.resolveModel(request.model);
+
+    const response = await this.client.messages.create({
+      model: modelId,
+      max_tokens: request.maxTokens || 4096,
+      messages: this.convertMessages(request.messages),
+      system: this.extractSystemMessage(request.messages),
+      temperature: request.temperature,
+      top_p: request.topP,
+      stop_sequences: request.stopSequences,
+      tools: request.tools ? this.convertTools(request.tools) : undefined,
+      tool_choice: request.toolChoice ? this.convertToolChoice(request.toolChoice) : undefined
+    });
+
+    return {
+      id: response.id,
+      model: response.model,
+      content: this.extractContent(response),
+      toolCalls: this.extractToolCalls(response),
+      usage: {
+        promptTokens: response.usage.input_tokens,
+        completionTokens: response.usage.output_tokens,
+        totalTokens: response.usage.input_tokens + response.usage.output_tokens,
+        cacheReadTokens: response.usage.cache_read_input_tokens,
+        cacheWriteTokens: response.usage.cache_creation_input_tokens
+      },
+      finishReason: this.mapStopReason(response.stop_reason),
+      metadata: {
+        provider: this.id,
+        latencyMs: Date.now() - startTime
+      }
+    };
+  }
+
+  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
+    const modelId = this.resolveModel(request.model);
+
+    const stream = await this.client.messages.stream({
+      model: modelId,
+      max_tokens: request.maxTokens || 4096,
+      messages: this.convertMessages(request.messages),
+      system: this.extractSystemMessage(request.messages),
+      temperature: request.temperature
+    });
+
+    for await (const event of stream) {
+      if (event.type === 'content_block_delta') {
+        if (event.delta.type === 'text_delta') {
+          yield { type: 'content', content: event.delta.text };
+        } else if (event.delta.type === 'input_json_delta') {
+          yield { type: 'tool_call', toolCall: { arguments: event.delta.partial_json } };
+        }
+      } else if (event.type === 'message_delta') {
+        yield {
+          type: 'usage',
+          usage: { completionTokens: event.usage?.output_tokens },
+          finishReason: event.delta.stop_reason
+        };
+      }
+    }
+
+    yield { type: 'done' };
+  }
+
+  async countTokens(text: string, model?: string): Promise<number> {
+    const response = await this.client.messages.countTokens({
+      model: this.resolveModel(model || this.config.defaultModel!),
+      messages: [{ role: 'user', content: text }]
+    });
+    return response.input_tokens;
+  }
+
+  async healthCheck(): Promise<HealthStatus> {
+    const startTime = Date.now();
+    try {
+      await this.client.messages.create({
+        model: 'claude-3-5-haiku-20241022',
+        max_tokens: 10,
+        messages: [{ role: 'user', content: 'Hi' }]
+      });
+      return {
+        healthy: true,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString()
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString(),
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  getStatus(): ProviderStatus {
+    return {
+      id: this.id,
+      name: this.name,
+      healthy: true,
+      enabled: true,
+      availableModels: Object.keys(ClaudeProvider.MODELS)
+    };
+  }
+
+  async shutdown(): Promise<void> {
+    // Cleanup if needed
+  }
+
+  private resolveModel(model: string): string {
+    const modelInfo = ClaudeProvider.MODELS[model as keyof typeof ClaudeProvider.MODELS];
+    return modelInfo?.id || model;
+  }
+
+  private convertMessages(messages: Message[]): AnthropicMessage[] {
+    return messages
+      .filter(m => m.role !== 'system')
+      .map(m => ({
+        role: m.role === 'tool' ? 'user' : m.role,
+        content: this.convertContent(m)
+      }));
+  }
+
+  private extractSystemMessage(messages: Message[]): string | undefined {
+    const systemMsg = messages.find(m => m.role === 'system');
+    return typeof systemMsg?.content === 'string' ? systemMsg.content : undefined;
+  }
+
+  private convertContent(message: Message): string | AnthropicContentBlock[] {
+    if (typeof message.content === 'string') {
+      if (message.role === 'tool') {
+        return [{
+          type: 'tool_result',
+          tool_use_id: message.toolCallId!,
+          content: message.content
+        }];
+      }
+      return message.content;
+    }
+
+    return message.content.map(block => {
+      if (block.type === 'text') {
+        return { type: 'text', text: block.text! };
+      } else if (block.type === 'image') {
+        return {
+          type: 'image',
+          source: {
+            type: block.imageBase64 ? 'base64' : 'url',
+            media_type: block.mimeType || 'image/jpeg',
+            data: block.imageBase64,
+            url: block.imageUrl
+          }
+        };
+      }
+      return { type: 'text', text: '' };
+    });
+  }
+
+  private convertTools(tools: ToolDefinition[]): AnthropicTool[] {
+    return tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.parameters
+    }));
+  }
+
+  private convertToolChoice(choice: CompletionRequest['toolChoice']): AnthropicToolChoice {
+    if (choice === 'auto') return { type: 'auto' };
+    if (choice === 'none') return { type: 'none' };
+    if (choice === 'required') return { type: 'any' };
+    if (typeof choice === 'object') return { type: 'tool', name: choice.name };
+    return { type: 'auto' };
+  }
+
+  private extractContent(response: AnthropicResponse): string {
+    return response.content
+      .filter(b => b.type === 'text')
+      .map(b => b.text)
+      .join('');
+  }
+
+  private extractToolCalls(response: AnthropicResponse): ToolCall[] | undefined {
+    const toolUses = response.content.filter(b => b.type === 'tool_use');
+    if (toolUses.length === 0) return undefined;
+
+    return toolUses.map(t => ({
+      id: t.id,
+      name: t.name,
+      arguments: JSON.stringify(t.input)
+    }));
+  }
+
+  private mapStopReason(reason: string | null): CompletionResponse['finishReason'] {
+    switch (reason) {
+      case 'end_turn': return 'stop';
+      case 'max_tokens': return 'length';
+      case 'tool_use': return 'tool_calls';
+      default: return 'stop';
+    }
+  }
+}
+```
+
+### OpenAIProvider
+
+```typescript
+interface OpenAIConfig extends ProviderConfig {
+  apiKey: string;
+  organization?: string;
+  baseUrl?: string;
+  defaultModel?: string;
+}
+
+class OpenAIProvider implements LLMProvider<OpenAIConfig> {
+  readonly id = 'openai';
+  readonly name = 'OpenAI';
+  readonly version = '1.0.0';
+  readonly config: OpenAIConfig;
+
+  private client: OpenAI;
+
+  static readonly MODELS = {
+    'gpt-4o': {
+      id: 'gpt-4o',
+      contextWindow: 128000,
+      maxOutput: 16384,
+      inputPrice: 2.50,
+      outputPrice: 10.0,
+      capabilities: ['vision', 'tools', 'json_mode']
+    },
+    'gpt-4-turbo': {
+      id: 'gpt-4-turbo',
+      contextWindow: 128000,
+      maxOutput: 4096,
+      inputPrice: 10.0,
+      outputPrice: 30.0,
+      capabilities: ['vision', 'tools', 'json_mode']
+    },
+    'gpt-3.5-turbo': {
+      id: 'gpt-3.5-turbo',
+      contextWindow: 16385,
+      maxOutput: 4096,
+      inputPrice: 0.50,
+      outputPrice: 1.50,
+      capabilities: ['tools', 'json_mode']
+    },
+    'gpt-4o-mini': {
+      id: 'gpt-4o-mini',
+      contextWindow: 128000,
+      maxOutput: 16384,
+      inputPrice: 0.15,
+      outputPrice: 0.60,
+      capabilities: ['vision', 'tools', 'json_mode']
+    }
+  };
+
+  constructor(config: OpenAIConfig) {
+    this.config = {
+      baseUrl: 'https://api.openai.com/v1',
+      defaultModel: 'gpt-4o',
+      timeout: 120000,
+      maxRetries: 3,
+      ...config
+    };
+  }
+
+  async initialize(): Promise<void> {
+    this.client = new OpenAI({
+      apiKey: this.config.apiKey,
+      organization: this.config.organization,
+      baseURL: this.config.baseUrl,
+      timeout: this.config.timeout,
+      maxRetries: this.config.maxRetries
+    });
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const startTime = Date.now();
+
+    const response = await this.client.chat.completions.create({
+      model: request.model,
+      messages: this.convertMessages(request.messages),
+      temperature: request.temperature,
+      max_tokens: request.maxTokens,
+      top_p: request.topP,
+      stop: request.stopSequences,
+      tools: request.tools ? this.convertTools(request.tools) : undefined,
+      tool_choice: request.toolChoice as OpenAIToolChoice,
+      response_format: this.convertResponseFormat(request.responseFormat)
+    });
+
+    const choice = response.choices[0];
+
+    return {
+      id: response.id,
+      model: response.model,
+      content: choice.message.content || '',
+      toolCalls: choice.message.tool_calls?.map(tc => ({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: tc.function.arguments
+      })),
+      usage: {
+        promptTokens: response.usage?.prompt_tokens || 0,
+        completionTokens: response.usage?.completion_tokens || 0,
+        totalTokens: response.usage?.total_tokens || 0
+      },
+      finishReason: this.mapFinishReason(choice.finish_reason),
+      metadata: {
+        provider: this.id,
+        latencyMs: Date.now() - startTime
+      }
+    };
+  }
+
+  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
+    const stream = await this.client.chat.completions.create({
+      model: request.model,
+      messages: this.convertMessages(request.messages),
+      temperature: request.temperature,
+      max_tokens: request.maxTokens,
+      stream: true
+    });
+
+    for await (const chunk of stream) {
+      const choice = chunk.choices[0];
+      if (choice?.delta?.content) {
+        yield { type: 'content', content: choice.delta.content };
+      }
+      if (choice?.delta?.tool_calls) {
+        for (const tc of choice.delta.tool_calls) {
+          yield {
+            type: 'tool_call',
+            toolCall: {
+              id: tc.id,
+              name: tc.function?.name,
+              arguments: tc.function?.arguments
+            }
+          };
+        }
+      }
+      if (choice?.finish_reason) {
+        yield { type: 'done', finishReason: choice.finish_reason };
+      }
+    }
+  }
+
+  async embed(texts: string[]): Promise<EmbeddingResponse> {
+    const response = await this.client.embeddings.create({
+      model: 'text-embedding-3-small',
+      input: texts
+    });
+
+    return {
+      embeddings: response.data.map(d => d.embedding),
+      usage: {
+        totalTokens: response.usage.total_tokens
+      }
+    };
+  }
+
+  async countTokens(text: string, model?: string): Promise<number> {
+    // Use tiktoken for accurate counting
+    const encoding = getEncoding(model || 'gpt-4o');
+    return encoding.encode(text).length;
+  }
+
+  async healthCheck(): Promise<HealthStatus> {
+    const startTime = Date.now();
+    try {
+      await this.client.models.list();
+      return {
+        healthy: true,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString()
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString(),
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  getStatus(): ProviderStatus {
+    return {
+      id: this.id,
+      name: this.name,
+      healthy: true,
+      enabled: true,
+      availableModels: Object.keys(OpenAIProvider.MODELS)
+    };
+  }
+
+  async shutdown(): Promise<void> {}
+
+  private convertMessages(messages: Message[]): OpenAIChatMessage[] {
+    return messages.map(m => {
+      if (m.role === 'tool') {
+        return {
+          role: 'tool' as const,
+          content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+          tool_call_id: m.toolCallId!
+        };
+      }
+
+      const content = typeof m.content === 'string'
+        ? m.content
+        : m.content.map(b => {
+            if (b.type === 'text') return { type: 'text', text: b.text };
+            if (b.type === 'image') {
+              return {
+                type: 'image_url',
+                image_url: { url: b.imageUrl || `data:${b.mimeType};base64,${b.imageBase64}` }
+              };
+            }
+            return { type: 'text', text: '' };
+          });
+
+      return {
+        role: m.role,
+        content,
+        tool_calls: m.toolCalls?.map(tc => ({
+          id: tc.id,
+          type: 'function' as const,
+          function: { name: tc.name, arguments: tc.arguments }
+        }))
+      };
+    });
+  }
+
+  private convertTools(tools: ToolDefinition[]): OpenAITool[] {
+    return tools.map(t => ({
+      type: 'function' as const,
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters
+      }
+    }));
+  }
+
+  private convertResponseFormat(format?: CompletionRequest['responseFormat']) {
+    if (!format) return undefined;
+    if (format === 'json') return { type: 'json_object' as const };
+    if (typeof format === 'object') {
+      return { type: 'json_schema' as const, json_schema: format.schema };
+    }
+    return undefined;
+  }
+
+  private mapFinishReason(reason: string | null): CompletionResponse['finishReason'] {
+    switch (reason) {
+      case 'stop': return 'stop';
+      case 'length': return 'length';
+      case 'tool_calls': return 'tool_calls';
+      case 'content_filter': return 'content_filter';
+      default: return 'stop';
+    }
+  }
+}
+```
+
+### GeminiProvider
+
+```typescript
+interface GeminiConfig extends ProviderConfig {
+  apiKey: string;
+  baseUrl?: string;
+  defaultModel?: string;
+}
+
+class GeminiProvider implements LLMProvider<GeminiConfig> {
+  readonly id = 'gemini';
+  readonly name = 'Google Gemini';
+  readonly version = '1.0.0';
+  readonly config: GeminiConfig;
+
+  private client: GoogleGenerativeAI;
+
+  static readonly MODELS = {
+    'gemini-2.0-flash': {
+      id: 'gemini-2.0-flash',
+      contextWindow: 1000000,
+      maxOutput: 8192,
+      inputPrice: 0.075,
+      outputPrice: 0.30,
+      capabilities: ['vision', 'tools', 'grounding']
+    },
+    'gemini-1.5-pro': {
+      id: 'gemini-1.5-pro',
+      contextWindow: 2000000,
+      maxOutput: 8192,
+      inputPrice: 1.25,
+      outputPrice: 5.0,
+      capabilities: ['vision', 'tools', 'grounding', 'code_execution']
+    },
+    'gemini-1.5-flash': {
+      id: 'gemini-1.5-flash',
+      contextWindow: 1000000,
+      maxOutput: 8192,
+      inputPrice: 0.075,
+      outputPrice: 0.30,
+      capabilities: ['vision', 'tools']
+    }
+  };
+
+  constructor(config: GeminiConfig) {
+    this.config = {
+      defaultModel: 'gemini-2.0-flash',
+      timeout: 120000,
+      maxRetries: 3,
+      ...config
+    };
+  }
+
+  async initialize(): Promise<void> {
+    this.client = new GoogleGenerativeAI(this.config.apiKey);
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const startTime = Date.now();
+    const model = this.client.getGenerativeModel({ model: request.model });
+
+    const chat = model.startChat({
+      history: this.convertHistory(request.messages),
+      generationConfig: {
+        temperature: request.temperature,
+        maxOutputTokens: request.maxTokens,
+        topP: request.topP,
+        stopSequences: request.stopSequences
+      }
+    });
+
+    const lastMessage = request.messages[request.messages.length - 1];
+    const result = await chat.sendMessage(
+      typeof lastMessage.content === 'string'
+        ? lastMessage.content
+        : this.convertParts(lastMessage.content)
+    );
+
+    const response = result.response;
+    const usage = response.usageMetadata;
+
+    return {
+      id: `gemini-${Date.now()}`,
+      model: request.model,
+      content: response.text(),
+      toolCalls: this.extractToolCalls(response),
+      usage: {
+        promptTokens: usage?.promptTokenCount || 0,
+        completionTokens: usage?.candidatesTokenCount || 0,
+        totalTokens: usage?.totalTokenCount || 0
+      },
+      finishReason: this.mapFinishReason(response.candidates?.[0]?.finishReason),
+      metadata: {
+        provider: this.id,
+        latencyMs: Date.now() - startTime
+      }
+    };
+  }
+
+  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
+    const model = this.client.getGenerativeModel({ model: request.model });
+
+    const chat = model.startChat({
+      history: this.convertHistory(request.messages),
+      generationConfig: {
+        temperature: request.temperature,
+        maxOutputTokens: request.maxTokens
+      }
+    });
+
+    const lastMessage = request.messages[request.messages.length - 1];
+    const result = await chat.sendMessageStream(
+      typeof lastMessage.content === 'string' ? lastMessage.content : ''
+    );
+
+    for await (const chunk of result.stream) {
+      const text = chunk.text();
+      if (text) {
+        yield { type: 'content', content: text };
+      }
+    }
+
+    yield { type: 'done' };
+  }
+
+  async embed(texts: string[]): Promise<EmbeddingResponse> {
+    const model = this.client.getGenerativeModel({ model: 'text-embedding-004' });
+
+    const embeddings: number[][] = [];
+    for (const text of texts) {
+      const result = await model.embedContent(text);
+      embeddings.push(result.embedding.values);
+    }
+
+    return {
+      embeddings,
+      usage: { totalTokens: 0 } // Gemini doesn't report token usage for embeddings
+    };
+  }
+
+  async countTokens(text: string, model?: string): Promise<number> {
+    const genModel = this.client.getGenerativeModel({
+      model: model || this.config.defaultModel!
+    });
+    const result = await genModel.countTokens(text);
+    return result.totalTokens;
+  }
+
+  async healthCheck(): Promise<HealthStatus> {
+    const startTime = Date.now();
+    try {
+      const model = this.client.getGenerativeModel({ model: 'gemini-1.5-flash' });
+      await model.countTokens('test');
+      return {
+        healthy: true,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString()
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString(),
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  getStatus(): ProviderStatus {
+    return {
+      id: this.id,
+      name: this.name,
+      healthy: true,
+      enabled: true,
+      availableModels: Object.keys(GeminiProvider.MODELS)
+    };
+  }
+
+  async shutdown(): Promise<void> {}
+
+  private convertHistory(messages: Message[]): GeminiContent[] {
+    return messages.slice(0, -1).map(m => ({
+      role: m.role === 'assistant' ? 'model' : 'user',
+      parts: typeof m.content === 'string'
+        ? [{ text: m.content }]
+        : this.convertParts(m.content)
+    }));
+  }
+
+  private convertParts(content: ContentBlock[]): GeminiPart[] {
+    return content.map(b => {
+      if (b.type === 'text') return { text: b.text! };
+      if (b.type === 'image') {
+        return {
+          inlineData: {
+            mimeType: b.mimeType || 'image/jpeg',
+            data: b.imageBase64!
+          }
+        };
+      }
+      return { text: '' };
+    });
+  }
+
+  private extractToolCalls(response: GeminiResponse): ToolCall[] | undefined {
+    const functionCalls = response.functionCalls();
+    if (!functionCalls || functionCalls.length === 0) return undefined;
+
+    return functionCalls.map((fc, i) => ({
+      id: `call-${i}`,
+      name: fc.name,
+      arguments: JSON.stringify(fc.args)
+    }));
+  }
+
+  private mapFinishReason(reason?: string): CompletionResponse['finishReason'] {
+    switch (reason) {
+      case 'STOP': return 'stop';
+      case 'MAX_TOKENS': return 'length';
+      case 'SAFETY': return 'content_filter';
+      default: return 'stop';
+    }
+  }
+}
+```
+
+### LocalProvider (Ollama)
+
+```typescript
+interface LocalConfig extends ProviderConfig {
+  baseUrl?: string;
+  defaultModel?: string;
+}
+
+class LocalProvider implements LLMProvider<LocalConfig> {
+  readonly id = 'local';
+  readonly name = 'Ollama Local';
+  readonly version = '1.0.0';
+  readonly config: LocalConfig;
+
+  static readonly MODELS = {
+    'llama3': {
+      id: 'llama3:latest',
+      contextWindow: 8192,
+      maxOutput: 4096,
+      inputPrice: 0,
+      outputPrice: 0,
+      capabilities: ['tools']
+    },
+    'llama3.2': {
+      id: 'llama3.2:latest',
+      contextWindow: 128000,
+      maxOutput: 4096,
+      inputPrice: 0,
+      outputPrice: 0,
+      capabilities: ['tools', 'vision']
+    },
+    'mistral': {
+      id: 'mistral:latest',
+      contextWindow: 32768,
+      maxOutput: 4096,
+      inputPrice: 0,
+      outputPrice: 0,
+      capabilities: ['tools']
+    },
+    'codellama': {
+      id: 'codellama:latest',
+      contextWindow: 16384,
+      maxOutput: 4096,
+      inputPrice: 0,
+      outputPrice: 0,
+      capabilities: ['code']
+    },
+    'deepseek-coder': {
+      id: 'deepseek-coder:latest',
+      contextWindow: 16384,
+      maxOutput: 4096,
+      inputPrice: 0,
+      outputPrice: 0,
+      capabilities: ['code']
+    }
+  };
+
+  constructor(config: LocalConfig = {}) {
+    this.config = {
+      baseUrl: 'http://localhost:11434',
+      defaultModel: 'llama3',
+      timeout: 300000,
+      maxRetries: 1,
+      ...config
+    };
+  }
+
+  async initialize(): Promise<void> {
+    // Verify Ollama is running
+    await this.healthCheck();
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const startTime = Date.now();
+
+    const response = await fetch(`${this.config.baseUrl}/api/chat`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: this.resolveModel(request.model),
+        messages: this.convertMessages(request.messages),
+        options: {
+          temperature: request.temperature,
+          num_predict: request.maxTokens,
+          top_p: request.topP,
+          stop: request.stopSequences
+        },
+        stream: false
+      })
+    });
+
+    if (!response.ok) {
+      throw new Error(`Ollama error: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+
+    return {
+      id: `ollama-${Date.now()}`,
+      model: request.model,
+      content: data.message.content,
+      usage: {
+        promptTokens: data.prompt_eval_count || 0,
+        completionTokens: data.eval_count || 0,
+        totalTokens: (data.prompt_eval_count || 0) + (data.eval_count || 0)
+      },
+      finishReason: 'stop',
+      metadata: {
+        provider: this.id,
+        latencyMs: Date.now() - startTime
+      }
+    };
+  }
+
+  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
+    const response = await fetch(`${this.config.baseUrl}/api/chat`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: this.resolveModel(request.model),
+        messages: this.convertMessages(request.messages),
+        options: {
+          temperature: request.temperature,
+          num_predict: request.maxTokens
+        },
+        stream: true
+      })
+    });
+
+    const reader = response.body!.getReader();
+    const decoder = new TextDecoder();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const lines = decoder.decode(value).split('\n').filter(l => l.trim());
+      for (const line of lines) {
+        const data = JSON.parse(line);
+        if (data.message?.content) {
+          yield { type: 'content', content: data.message.content };
+        }
+        if (data.done) {
+          yield {
+            type: 'usage',
+            usage: {
+              promptTokens: data.prompt_eval_count,
+              completionTokens: data.eval_count
+            }
+          };
+          yield { type: 'done' };
+        }
+      }
+    }
+  }
+
+  async embed(texts: string[]): Promise<EmbeddingResponse> {
+    const embeddings: number[][] = [];
+
+    for (const text of texts) {
+      const response = await fetch(`${this.config.baseUrl}/api/embeddings`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          model: 'nomic-embed-text',
+          prompt: text
+        })
+      });
+
+      const data = await response.json();
+      embeddings.push(data.embedding);
+    }
+
+    return { embeddings, usage: { totalTokens: 0 } };
+  }
+
+  async countTokens(text: string): Promise<number> {
+    // Approximate token count for local models
+    return Math.ceil(text.length / 4);
+  }
+
+  async healthCheck(): Promise<HealthStatus> {
+    const startTime = Date.now();
+    try {
+      const response = await fetch(`${this.config.baseUrl}/api/tags`);
+      if (!response.ok) throw new Error('Ollama not responding');
+
+      return {
+        healthy: true,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString()
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString(),
+        error: error instanceof Error ? error.message : 'Ollama not available'
+      };
+    }
+  }
+
+  getStatus(): ProviderStatus {
+    return {
+      id: this.id,
+      name: this.name,
+      healthy: true,
+      enabled: true,
+      availableModels: Object.keys(LocalProvider.MODELS)
+    };
+  }
+
+  async shutdown(): Promise<void> {}
+
+  private resolveModel(model: string): string {
+    const modelInfo = LocalProvider.MODELS[model as keyof typeof LocalProvider.MODELS];
+    return modelInfo?.id || model;
+  }
+
+  private convertMessages(messages: Message[]): OllamaMessage[] {
+    return messages.map(m => ({
+      role: m.role === 'tool' ? 'assistant' : m.role,
+      content: typeof m.content === 'string' ? m.content : m.content.map(b => b.text).join('')
+    }));
+  }
+}
+```
+
+### AzureProvider
+
+```typescript
+interface AzureConfig extends ProviderConfig {
+  apiKey: string;
+  endpoint: string;
+  apiVersion?: string;
+  deployments: Record<string, string>; // model -> deployment name
+}
+
+class AzureProvider implements LLMProvider<AzureConfig> {
+  readonly id = 'azure';
+  readonly name = 'Azure OpenAI';
+  readonly version = '1.0.0';
+  readonly config: AzureConfig;
+
+  private client: AzureOpenAI;
+
+  constructor(config: AzureConfig) {
+    this.config = {
+      apiVersion: '2024-02-01',
+      timeout: 120000,
+      maxRetries: 3,
+      ...config
+    };
+  }
+
+  async initialize(): Promise<void> {
+    this.client = new AzureOpenAI({
+      apiKey: this.config.apiKey,
+      endpoint: this.config.endpoint,
+      apiVersion: this.config.apiVersion
+    });
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const startTime = Date.now();
+    const deployment = this.getDeployment(request.model);
+
+    const response = await this.client.chat.completions.create({
+      model: deployment,
+      messages: this.convertMessages(request.messages),
+      temperature: request.temperature,
+      max_tokens: request.maxTokens,
+      top_p: request.topP,
+      stop: request.stopSequences
+    });
+
+    const choice = response.choices[0];
+
+    return {
+      id: response.id,
+      model: request.model,
+      content: choice.message.content || '',
+      toolCalls: choice.message.tool_calls?.map(tc => ({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: tc.function.arguments
+      })),
+      usage: {
+        promptTokens: response.usage?.prompt_tokens || 0,
+        completionTokens: response.usage?.completion_tokens || 0,
+        totalTokens: response.usage?.total_tokens || 0
+      },
+      finishReason: this.mapFinishReason(choice.finish_reason),
+      metadata: {
+        provider: this.id,
+        latencyMs: Date.now() - startTime
+      }
+    };
+  }
+
+  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
+    const deployment = this.getDeployment(request.model);
+
+    const stream = await this.client.chat.completions.create({
+      model: deployment,
+      messages: this.convertMessages(request.messages),
+      temperature: request.temperature,
+      max_tokens: request.maxTokens,
+      stream: true
+    });
+
+    for await (const chunk of stream) {
+      const choice = chunk.choices[0];
+      if (choice?.delta?.content) {
+        yield { type: 'content', content: choice.delta.content };
+      }
+      if (choice?.finish_reason) {
+        yield { type: 'done', finishReason: choice.finish_reason };
+      }
+    }
+  }
+
+  async countTokens(text: string, model?: string): Promise<number> {
+    const encoding = getEncoding('cl100k_base');
+    return encoding.encode(text).length;
+  }
+
+  async healthCheck(): Promise<HealthStatus> {
+    const startTime = Date.now();
+    try {
+      await this.client.chat.completions.create({
+        model: Object.values(this.config.deployments)[0],
+        messages: [{ role: 'user', content: 'Hi' }],
+        max_tokens: 5
+      });
+      return {
+        healthy: true,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString()
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - startTime,
+        lastCheck: new Date().toISOString(),
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  getStatus(): ProviderStatus {
+    return {
+      id: this.id,
+      name: this.name,
+      healthy: true,
+      enabled: true,
+      availableModels: Object.keys(this.config.deployments)
+    };
+  }
+
+  async shutdown(): Promise<void> {}
+
+  private getDeployment(model: string): string {
+    const deployment = this.config.deployments[model];
+    if (!deployment) {
+      throw new Error(`No Azure deployment configured for model: ${model}`);
+    }
+    return deployment;
+  }
+
+  private convertMessages(messages: Message[]): AzureMessage[] {
+    return messages.map(m => ({
+      role: m.role,
+      content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content)
+    }));
+  }
+
+  private mapFinishReason(reason: string | null): CompletionResponse['finishReason'] {
+    switch (reason) {
+      case 'stop': return 'stop';
+      case 'length': return 'length';
+      case 'tool_calls': return 'tool_calls';
+      case 'content_filter': return 'content_filter';
+      default: return 'stop';
+    }
+  }
+}
+```
+
+---
+
+## ModelRouter
+
+### Routing Inteligente
+
+```typescript
+interface RoutingRule {
+  id: string;
+  name: string;
+  conditions: RoutingCondition[];
+  target: RoutingTarget;
+  priority: number;
+  enabled: boolean;
+}
+
+interface RoutingCondition {
+  type: 'task_type' | 'token_count' | 'cost_limit' | 'capability' | 'time_of_day' | 'custom';
+  operator: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'matches';
+  value: unknown;
+  field?: string;
+}
+
+interface RoutingTarget {
+  type: 'model' | 'provider' | 'alias' | 'fallback_chain';
+  value: string | string[];
+}
+
+interface TaskContext {
+  taskType: TaskType;
+  estimatedTokens: number;
+  maxCost?: number;
+  requiredCapabilities?: string[];
+  priority?: 'low' | 'normal' | 'high' | 'critical';
+  metadata?: Record<string, unknown>;
+}
+
+type TaskType =
+  | 'code_generation'
+  | 'code_review'
+  | 'documentation'
+  | 'analysis'
+  | 'conversation'
+  | 'summarization'
+  | 'translation'
+  | 'creative'
+  | 'reasoning'
+  | 'quick_task';
+
+class ModelRouter {
+  private registry: ProviderRegistry;
+  private rules: RoutingRule[] = [];
+  private aliases: Map<string, string> = new Map();
+  private rateLimiters: Map<string, RateLimiter> = new Map();
+  private config: RouterConfig;
+
+  constructor(registry: ProviderRegistry, config: RouterConfig) {
+    this.registry = registry;
+    this.config = config;
+    this.loadDefaultRules();
+    this.loadAliases();
+  }
+
+  // Route request to best model/provider
+  async route(
+    request: CompletionRequest,
+    context: TaskContext
+  ): Promise<{ provider: LLMProvider; model: string }> {
+
+    // Resolve alias if present
+    const resolvedModel = this.resolveAlias(request.model);
+
+    // Find matching rules
+    const matchingRules = this.rules
+      .filter(r => r.enabled && this.evaluateConditions(r.conditions, context, request))
+      .sort((a, b) => b.priority - a.priority);
+
+    if (matchingRules.length > 0) {
+      const rule = matchingRules[0];
+      return this.resolveTarget(rule.target, context);
+    }
+
+    // Default routing: find provider for model
+    const provider = this.registry.getProviderForModel(resolvedModel);
+    if (!provider) {
+      // Try fallback chain
+      return this.tryFallbackChain(resolvedModel, context);
+    }
+
+    // Check rate limits
+    await this.checkRateLimit(provider.id, resolvedModel);
+
+    return { provider, model: resolvedModel };
+  }
+
+  // Cost-optimized routing
+  async routeOptimized(
+    request: CompletionRequest,
+    context: TaskContext
+  ): Promise<{ provider: LLMProvider; model: string }> {
+
+    const candidates = this.getCandidateModels(context);
+
+    // Sort by cost (ascending)
+    const sortedCandidates = candidates.sort((a, b) => {
+      const costA = this.estimateCost(a.model, context.estimatedTokens);
+      const costB = this.estimateCost(b.model, context.estimatedTokens);
+      return costA - costB;
+    });
+
+    // Find cheapest that meets requirements
+    for (const candidate of sortedCandidates) {
+      if (this.meetsRequirements(candidate.model, context)) {
+        const provider = this.registry.getProviderForModel(candidate.model);
+        if (provider) {
+          await this.checkRateLimit(provider.id, candidate.model);
+          return { provider, model: candidate.model };
+        }
+      }
+    }
+
+    // Fallback to default
+    return this.route(request, context);
+  }
+
+  // Load balancing across providers
+  async routeBalanced(
+    request: CompletionRequest,
+    context: TaskContext
+  ): Promise<{ provider: LLMProvider; model: string }> {
+
+    const resolvedModel = this.resolveAlias(request.model);
+    const compatibleProviders = this.getProvidersForModel(resolvedModel);
+
+    if (compatibleProviders.length === 0) {
+      return this.tryFallbackChain(resolvedModel, context);
+    }
+
+    // Round-robin with health awareness
+    const healthyProviders = compatibleProviders.filter(p => {
+      const status = this.registry.get(p.id)?.getStatus();
+      return status?.healthy;
+    });
+
+    if (healthyProviders.length === 0) {
+      throw new Error(`No healthy providers available for model: ${resolvedModel}`);
+    }
+
+    // Select based on current load
+    const selected = this.selectLeastLoaded(healthyProviders);
+    await this.checkRateLimit(selected.id, resolvedModel);
+
+    return { provider: selected, model: resolvedModel };
+  }
+
+  // Add routing rule
+  addRule(rule: RoutingRule): void {
+    this.rules.push(rule);
+    this.rules.sort((a, b) => b.priority - a.priority);
+  }
+
+  // Remove routing rule
+  removeRule(ruleId: string): boolean {
+    const index = this.rules.findIndex(r => r.id === ruleId);
+    if (index >= 0) {
+      this.rules.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+
+  // Set model alias
+  setAlias(alias: string, model: string): void {
+    this.aliases.set(alias, model);
+  }
+
+  // Get model alias
+  resolveAlias(modelOrAlias: string): string {
+    return this.aliases.get(modelOrAlias) || modelOrAlias;
+  }
+
+  // Estimate cost for request
+  estimateCost(model: string, tokens: number): number {
+    const modelInfo = this.getModelInfo(model);
+    if (!modelInfo) return 0;
+
+    const inputTokens = Math.ceil(tokens * 0.7);
+    const outputTokens = Math.ceil(tokens * 0.3);
+
+    return (
+      (inputTokens / 1_000_000) * modelInfo.inputPrice +
+      (outputTokens / 1_000_000) * modelInfo.outputPrice
+    );
+  }
+
+  private loadDefaultRules(): void {
+    this.rules = [
+      {
+        id: 'quick-tasks',
+        name: 'Route quick tasks to fast models',
+        conditions: [
+          { type: 'task_type', operator: 'eq', value: 'quick_task' }
+        ],
+        target: { type: 'alias', value: 'fast' },
+        priority: 100,
+        enabled: true
+      },
+      {
+        id: 'code-generation',
+        name: 'Route code generation to capable models',
+        conditions: [
+          { type: 'task_type', operator: 'eq', value: 'code_generation' },
+          { type: 'token_count', operator: 'gt', value: 1000 }
+        ],
+        target: { type: 'alias', value: 'smart' },
+        priority: 90,
+        enabled: true
+      },
+      {
+        id: 'reasoning',
+        name: 'Route complex reasoning to best models',
+        conditions: [
+          { type: 'task_type', operator: 'eq', value: 'reasoning' }
+        ],
+        target: { type: 'model', value: 'claude-opus-4-5' },
+        priority: 95,
+        enabled: true
+      },
+      {
+        id: 'cost-sensitive',
+        name: 'Route cost-sensitive requests to cheap models',
+        conditions: [
+          { type: 'cost_limit', operator: 'lt', value: 0.01 }
+        ],
+        target: { type: 'alias', value: 'cheap' },
+        priority: 80,
+        enabled: true
+      }
+    ];
+  }
+
+  private loadAliases(): void {
+    // Model aliases for convenience
+    this.aliases.set('fast', 'claude-3-5-haiku');
+    this.aliases.set('smart', 'claude-sonnet-4');
+    this.aliases.set('best', 'claude-opus-4-5');
+    this.aliases.set('cheap', 'gpt-4o-mini');
+    this.aliases.set('local', 'llama3');
+    this.aliases.set('code', 'claude-sonnet-4');
+    this.aliases.set('vision', 'gpt-4o');
+  }
+
+  private evaluateConditions(
+    conditions: RoutingCondition[],
+    context: TaskContext,
+    request: CompletionRequest
+  ): boolean {
+    return conditions.every(c => this.evaluateCondition(c, context, request));
+  }
+
+  private evaluateCondition(
+    condition: RoutingCondition,
+    context: TaskContext,
+    request: CompletionRequest
+  ): boolean {
+    let value: unknown;
+
+    switch (condition.type) {
+      case 'task_type':
+        value = context.taskType;
+        break;
+      case 'token_count':
+        value = context.estimatedTokens;
+        break;
+      case 'cost_limit':
+        value = context.maxCost;
+        break;
+      case 'capability':
+        value = context.requiredCapabilities;
+        break;
+      case 'custom':
+        value = condition.field ? context.metadata?.[condition.field] : undefined;
+        break;
+      default:
+        return false;
+    }
+
+    return this.compareValues(value, condition.operator, condition.value);
+  }
+
+  private compareValues(actual: unknown, operator: string, expected: unknown): boolean {
+    switch (operator) {
+      case 'eq': return actual === expected;
+      case 'ne': return actual !== expected;
+      case 'gt': return Number(actual) > Number(expected);
+      case 'lt': return Number(actual) < Number(expected);
+      case 'gte': return Number(actual) >= Number(expected);
+      case 'lte': return Number(actual) <= Number(expected);
+      case 'contains':
+        return Array.isArray(actual) && actual.includes(expected);
+      case 'matches':
+        return typeof actual === 'string' && new RegExp(String(expected)).test(actual);
+      default:
+        return false;
+    }
+  }
+
+  private async resolveTarget(
+    target: RoutingTarget,
+    context: TaskContext
+  ): Promise<{ provider: LLMProvider; model: string }> {
+    switch (target.type) {
+      case 'model': {
+        const model = target.value as string;
+        const provider = this.registry.getProviderForModel(model);
+        if (!provider) throw new Error(`No provider for model: ${model}`);
+        return { provider, model };
+      }
+      case 'alias': {
+        const model = this.resolveAlias(target.value as string);
+        const provider = this.registry.getProviderForModel(model);
+        if (!provider) throw new Error(`No provider for alias: ${target.value}`);
+        return { provider, model };
+      }
+      case 'fallback_chain': {
+        const models = target.value as string[];
+        return this.tryFallbackChainFromList(models, context);
+      }
+      default:
+        throw new Error(`Unknown target type: ${target.type}`);
+    }
+  }
+
+  private async tryFallbackChain(
+    model: string,
+    context: TaskContext
+  ): Promise<{ provider: LLMProvider; model: string }> {
+    const fallbackChain = this.config.fallbackChains[model] || this.config.defaultFallbackChain;
+    return this.tryFallbackChainFromList(fallbackChain, context);
+  }
+
+  private async tryFallbackChainFromList(
+    models: string[],
+    context: TaskContext
+  ): Promise<{ provider: LLMProvider; model: string }> {
+    for (const model of models) {
+      const provider = this.registry.getProviderForModel(model);
+      if (provider) {
+        const status = provider.getStatus();
+        if (status.healthy) {
+          return { provider, model };
+        }
+      }
+    }
+    throw new Error('All providers in fallback chain unavailable');
+  }
+
+  private getCandidateModels(context: TaskContext): { model: string; provider: string }[] {
+    const candidates: { model: string; provider: string }[] = [];
+
+    for (const status of this.registry.list()) {
+      if (!status.healthy || !status.enabled) continue;
+
+      for (const model of status.availableModels) {
+        if (this.meetsCapabilities(model, context.requiredCapabilities)) {
+          candidates.push({ model, provider: status.id });
+        }
+      }
+    }
+
+    return candidates;
+  }
+
+  private meetsCapabilities(model: string, required?: string[]): boolean {
+    if (!required || required.length === 0) return true;
+
+    const modelInfo = this.getModelInfo(model);
+    if (!modelInfo) return false;
+
+    return required.every(cap => modelInfo.capabilities.includes(cap));
+  }
+
+  private meetsRequirements(model: string, context: TaskContext): boolean {
+    const modelInfo = this.getModelInfo(model);
+    if (!modelInfo) return false;
+
+    // Check context window
+    if (context.estimatedTokens > modelInfo.contextWindow) return false;
+
+    // Check cost limit
+    if (context.maxCost) {
+      const estimatedCost = this.estimateCost(model, context.estimatedTokens);
+      if (estimatedCost > context.maxCost) return false;
+    }
+
+    // Check capabilities
+    if (!this.meetsCapabilities(model, context.requiredCapabilities)) return false;
+
+    return true;
+  }
+
+  private getModelInfo(model: string): ModelInfo | undefined {
+    // Check all providers for model info
+    const allModels = {
+      ...ClaudeProvider.MODELS,
+      ...OpenAIProvider.MODELS,
+      ...GeminiProvider.MODELS,
+      ...LocalProvider.MODELS
+    };
+
+    return allModels[model as keyof typeof allModels];
+  }
+
+  private getProvidersForModel(model: string): LLMProvider[] {
+    return this.registry.list()
+      .filter(s => s.availableModels.includes(model) && s.healthy && s.enabled)
+      .map(s => this.registry.get(s.id)!)
+      .filter(Boolean);
+  }
+
+  private selectLeastLoaded(providers: LLMProvider[]): LLMProvider {
+    let minLoad = Infinity;
+    let selected = providers[0];
+
+    for (const provider of providers) {
+      const metrics = this.registry.getMetrics(provider.id);
+      const load = metrics?.totalRequests || 0;
+      if (load < minLoad) {
+        minLoad = load;
+        selected = provider;
+      }
+    }
+
+    return selected;
+  }
+
+  private async checkRateLimit(providerId: string, model: string): Promise<void> {
+    const key = `${providerId}:${model}`;
+    let limiter = this.rateLimiters.get(key);
+
+    if (!limiter) {
+      const modelInfo = this.getModelInfo(model);
+      limiter = new RateLimiter({
+        requestsPerMinute: modelInfo?.rateLimit?.requestsPerMinute || 60,
+        tokensPerMinute: modelInfo?.rateLimit?.tokensPerMinute || 100000
+      });
+      this.rateLimiters.set(key, limiter);
+    }
+
+    await limiter.acquire();
+  }
+}
+```
+
+---
+
+## UnifiedAPI
+
+### API Consistente
+
+```typescript
+class UnifiedLLMAPI {
+  private registry: ProviderRegistry;
+  private router: ModelRouter;
+  private config: UnifiedAPIConfig;
+
+  constructor(config: UnifiedAPIConfig) {
+    this.config = config;
+    this.registry = new ProviderRegistry(config.registry);
+    this.router = new ModelRouter(this.registry, config.router);
+  }
+
+  // Initialize all providers
+  async initialize(): Promise<void> {
+    // Register configured providers
+    if (this.config.providers.claude?.enabled) {
+      await this.registry.register(
+        new ClaudeProvider(this.config.providers.claude),
+        { priority: 1 }
+      );
+    }
+
+    if (this.config.providers.openai?.enabled) {
+      await this.registry.register(
+        new OpenAIProvider(this.config.providers.openai),
+        { priority: 2 }
+      );
+    }
+
+    if (this.config.providers.gemini?.enabled) {
+      await this.registry.register(
+        new GeminiProvider(this.config.providers.gemini),
+        { priority: 3 }
+      );
+    }
+
+    if (this.config.providers.local?.enabled) {
+      await this.registry.register(
+        new LocalProvider(this.config.providers.local),
+        { priority: 10 }
+      );
+    }
+
+    if (this.config.providers.azure?.enabled) {
+      await this.registry.register(
+        new AzureProvider(this.config.providers.azure),
+        { priority: 2 }
+      );
+    }
+
+    // Start health checks
+    this.registry.startHealthChecks(this.config.healthCheckInterval);
+  }
+
+  // Main completion method
+  async complete(
+    request: CompletionRequest,
+    options: CompletionOptions = {}
+  ): Promise<CompletionResponse> {
+    const context = this.buildContext(request, options);
+
+    // Route to best provider/model
+    const { provider, model } = options.costOptimized
+      ? await this.router.routeOptimized(request, context)
+      : await this.router.route(request, context);
+
+    const startTime = Date.now();
+
+    try {
+      // Execute with retry and fallback
+      const response = await this.executeWithFallback(
+        provider,
+        { ...request, model },
+        context
+      );
+
+      // Record metrics
+      const latencyMs = Date.now() - startTime;
+      const cost = this.calculateCost(model, response.usage);
+
+      this.registry.recordMetrics(
+        provider.id,
+        true,
+        latencyMs,
+        response.usage.totalTokens,
+        cost
+      );
+
+      // Emit event
+      EventBus.publish('llm.completion', {
+        provider: provider.id,
+        model,
+        tokens: response.usage.totalTokens,
+        latencyMs,
+        cost
+      });
+
+      return response;
+
+    } catch (error) {
+      this.registry.recordMetrics(provider.id, false, Date.now() - startTime, 0, 0);
+      throw error;
+    }
+  }
+
+  // Streaming completion
+  async *stream(
+    request: CompletionRequest,
+    options: CompletionOptions = {}
+  ): AsyncIterable<StreamChunk> {
+    const context = this.buildContext(request, options);
+    const { provider, model } = await this.router.route(request, context);
+
+    yield* provider.stream({ ...request, model });
+  }
+
+  // Chat convenience method
+  async chat(
+    messages: Message[],
+    options: ChatOptions = {}
+  ): Promise<CompletionResponse> {
+    return this.complete({
+      model: options.model || this.config.defaultModel,
+      messages,
+      temperature: options.temperature,
+      maxTokens: options.maxTokens,
+      tools: options.tools,
+      toolChoice: options.toolChoice
+    }, options);
+  }
+
+  // Embed texts
+  async embed(
+    texts: string[],
+    options: EmbedOptions = {}
+  ): Promise<EmbeddingResponse> {
+    const providerId = options.provider || 'openai';
+    const provider = this.registry.get(providerId);
+
+    if (!provider?.embed) {
+      throw new Error(`Provider ${providerId} does not support embeddings`);
+    }
+
+    return provider.embed(texts);
+  }
+
+  // Count tokens
+  async countTokens(
+    text: string,
+    model?: string
+  ): Promise<number> {
+    const targetModel = model || this.config.defaultModel;
+    const provider = this.registry.getProviderForModel(targetModel);
+
+    if (!provider) {
+      // Fallback to approximate count
+      return Math.ceil(text.length / 4);
+    }
+
+    return provider.countTokens(text, targetModel);
+  }
+
+  // Estimate cost
+  estimateCost(
+    model: string,
+    inputTokens: number,
+    outputTokens: number
+  ): number {
+    return this.router.estimateCost(model, inputTokens + outputTokens);
+  }
+
+  // Get provider status
+  getProviderStatus(): ProviderStatus[] {
+    return this.registry.list();
+  }
+
+  // Get available models
+  getAvailableModels(): ModelInfo[] {
+    const models: ModelInfo[] = [];
+
+    for (const status of this.registry.list()) {
+      if (!status.enabled) continue;
+
+      for (const model of status.availableModels) {
+        models.push({
+          id: model,
+          provider: status.id,
+          ...this.getModelDetails(model)
+        });
+      }
+    }
+
+    return models;
+  }
+
+  // Shutdown
+  async shutdown(): Promise<void> {
+    await this.registry.shutdown();
+  }
+
+  private buildContext(
+    request: CompletionRequest,
+    options: CompletionOptions
+  ): TaskContext {
+    return {
+      taskType: options.taskType || 'conversation',
+      estimatedTokens: options.estimatedTokens || this.estimateTokens(request),
+      maxCost: options.maxCost,
+      requiredCapabilities: options.requiredCapabilities,
+      priority: options.priority,
+      metadata: options.metadata
+    };
+  }
+
+  private estimateTokens(request: CompletionRequest): number {
+    let total = 0;
+    for (const msg of request.messages) {
+      const content = typeof msg.content === 'string'
+        ? msg.content
+        : msg.content.map(b => b.text || '').join('');
+      total += Math.ceil(content.length / 4);
+    }
+    return total + (request.maxTokens || 1000);
+  }
+
+  private async executeWithFallback(
+    provider: LLMProvider,
+    request: CompletionRequest,
+    context: TaskContext,
+    attempt: number = 1
+  ): Promise<CompletionResponse> {
+    try {
+      return await provider.complete(request);
+    } catch (error) {
+      if (attempt >= this.config.maxRetries) {
+        // Try fallback provider
+        if (this.config.enableFallback) {
+          const fallbackResult = await this.router.routeBalanced(request, context);
+          if (fallbackResult.provider.id !== provider.id) {
+            return fallbackResult.provider.complete({
+              ...request,
+              model: fallbackResult.model
+            });
+          }
+        }
+        throw error;
+      }
+
+      // Retry with exponential backoff
+      await this.sleep(Math.pow(2, attempt) * 1000);
+      return this.executeWithFallback(provider, request, context, attempt + 1);
+    }
+  }
+
+  private calculateCost(model: string, usage: TokenUsage): number {
+    const modelInfo = this.getModelDetails(model);
+    if (!modelInfo) return 0;
+
+    return (
+      (usage.promptTokens / 1_000_000) * modelInfo.inputPrice +
+      (usage.completionTokens / 1_000_000) * modelInfo.outputPrice
+    );
+  }
+
+  private getModelDetails(model: string): ModelDetails | undefined {
+    const allModels = {
+      ...ClaudeProvider.MODELS,
+      ...OpenAIProvider.MODELS,
+      ...GeminiProvider.MODELS,
+      ...LocalProvider.MODELS
+    };
+    return allModels[model as keyof typeof allModels];
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+---
+
+## Matriz de Capacidades
+
+| Modelo | Provider | Context | Output | Vision | Tools | Streaming | Input $/1M | Output $/1M |
+|--------|----------|---------|--------|--------|-------|-----------|------------|-------------|
+| claude-opus-4-5 | Claude | 200K | 32K | Yes | Yes | Yes | $15.00 | $75.00 |
+| claude-sonnet-4 | Claude | 200K | 64K | Yes | Yes | Yes | $3.00 | $15.00 |
+| claude-3-5-haiku | Claude | 200K | 8K | Yes | Yes | Yes | $0.80 | $4.00 |
+| gpt-4o | OpenAI | 128K | 16K | Yes | Yes | Yes | $2.50 | $10.00 |
+| gpt-4-turbo | OpenAI | 128K | 4K | Yes | Yes | Yes | $10.00 | $30.00 |
+| gpt-4o-mini | OpenAI | 128K | 16K | Yes | Yes | Yes | $0.15 | $0.60 |
+| gpt-3.5-turbo | OpenAI | 16K | 4K | No | Yes | Yes | $0.50 | $1.50 |
+| gemini-2.0-flash | Gemini | 1M | 8K | Yes | Yes | Yes | $0.075 | $0.30 |
+| gemini-1.5-pro | Gemini | 2M | 8K | Yes | Yes | Yes | $1.25 | $5.00 |
+| llama3 | Local | 8K | 4K | No | Yes | Yes | $0.00 | $0.00 |
+| llama3.2 | Local | 128K | 4K | Yes | Yes | Yes | $0.00 | $0.00 |
+| mistral | Local | 32K | 4K | No | Yes | Yes | $0.00 | $0.00 |
+| codellama | Local | 16K | 4K | No | No | Yes | $0.00 | $0.00 |
+
+---
+
+## Ejemplos de Uso
+
+### Inicializacion Basica
+
+```typescript
+import { UnifiedLLMAPI } from '@elsabro/llm-providers';
+
+const llm = new UnifiedLLMAPI({
+  defaultModel: 'claude-sonnet-4',
+  providers: {
+    claude: {
+      enabled: true,
+      apiKey: process.env.ANTHROPIC_API_KEY
+    },
+    openai: {
+      enabled: true,
+      apiKey: process.env.OPENAI_API_KEY
+    },
+    local: {
+      enabled: true,
+      baseUrl: 'http://localhost:11434'
+    }
+  },
+  router: {
+    defaultFallbackChain: ['claude-sonnet-4', 'gpt-4o', 'llama3']
+  }
+});
+
+await llm.initialize();
+```
+
+### Completion Simple
+
+```typescript
+const response = await llm.complete({
+  model: 'claude-sonnet-4',
+  messages: [
+    { role: 'user', content: 'Explain quantum computing in simple terms' }
+  ],
+  maxTokens: 500
+});
+
+console.log(response.content);
+console.log(`Tokens: ${response.usage.totalTokens}`);
+```
+
+### Routing por Tipo de Tarea
+
+```typescript
+// Code generation - routes to smart model
+const codeResponse = await llm.complete({
+  model: 'auto',
+  messages: [
+    { role: 'user', content: 'Write a binary search function in TypeScript' }
+  ]
+}, {
+  taskType: 'code_generation',
+  estimatedTokens: 500
+});
+
+// Quick task - routes to fast model
+const quickResponse = await llm.complete({
+  model: 'auto',
+  messages: [
+    { role: 'user', content: 'What is 2+2?' }
+  ]
+}, {
+  taskType: 'quick_task'
+});
+```
+
+### Cost Optimization
+
+```typescript
+const response = await llm.complete({
+  model: 'auto',
+  messages: [
+    { role: 'user', content: 'Summarize this document...' }
+  ]
+}, {
+  costOptimized: true,
+  maxCost: 0.01, // Max $0.01 per request
+  taskType: 'summarization'
+});
+```
+
+### Streaming
+
+```typescript
+const stream = llm.stream({
+  model: 'claude-sonnet-4',
+  messages: [
+    { role: 'user', content: 'Write a short story about a robot' }
+  ]
+});
+
+for await (const chunk of stream) {
+  if (chunk.type === 'content') {
+    process.stdout.write(chunk.content || '');
+  }
+}
+```
+
+### Using Model Aliases
+
+```typescript
+// Use predefined aliases
+const fastResponse = await llm.chat([
+  { role: 'user', content: 'Quick question: capital of France?' }
+], { model: 'fast' }); // Routes to claude-3-5-haiku
+
+const smartResponse = await llm.chat([
+  { role: 'user', content: 'Complex reasoning task...' }
+], { model: 'smart' }); // Routes to claude-sonnet-4
+
+const bestResponse = await llm.chat([
+  { role: 'user', content: 'Very complex task...' }
+], { model: 'best' }); // Routes to claude-opus-4-5
+```
+
+### Provider Health Check
+
+```typescript
+const status = llm.getProviderStatus();
+
+for (const provider of status) {
+  console.log(`${provider.name}: ${provider.healthy ? 'OK' : 'DOWN'}`);
+  console.log(`  Models: ${provider.availableModels.join(', ')}`);
+}
+```
+
+### Tool Use
+
+```typescript
+const response = await llm.complete({
+  model: 'claude-sonnet-4',
+  messages: [
+    { role: 'user', content: 'What is the weather in Paris?' }
+  ],
+  tools: [{
+    name: 'get_weather',
+    description: 'Get current weather for a location',
+    parameters: {
+      type: 'object',
+      properties: {
+        location: { type: 'string', description: 'City name' }
+      },
+      required: ['location']
+    }
+  }],
+  toolChoice: 'auto'
+});
+
+if (response.toolCalls) {
+  for (const call of response.toolCalls) {
+    console.log(`Tool: ${call.name}`);
+    console.log(`Args: ${call.arguments}`);
+  }
+}
+```
+
+---
+
+## Comandos
+
+```bash
+/elsabro:llm status              # Ver estado de providers
+/elsabro:llm models              # Listar modelos disponibles
+/elsabro:llm test <provider>     # Probar provider
+/elsabro:llm route <model>       # Ver routing para modelo
+/elsabro:llm cost <model> <tokens>  # Estimar costo
+/elsabro:llm alias set <name> <model>  # Crear alias
+/elsabro:llm config              # Ver configuracion actual
+```
+
+---
+
+## Configuracion
+
+Ver `templates/multi-llm-config.json` para configuracion completa.
+
+---
+
+## Changelog
+
+- **v3.6.0**: Initial Multi-LLM Providers System
+  - ProviderRegistry with health checks
+  - 5 provider implementations (Claude, OpenAI, Gemini, Local, Azure)
+  - ModelRouter with intelligent routing
+  - UnifiedAPI with consistent interface
+  - Cost optimization and load balancing
+  - Streaming support cross-provider