@sparkleideas/integration 3.0.1

package/src/provider-adapter.ts

@@ -0,0 +1,1168 @@
+/**
+ * ProviderAdapter - Multi-Provider Support for AI Models
+ *
+ * Provides a unified interface for working with multiple AI providers
+ * (Anthropic, OpenAI, local models, etc.) with automatic selection,
+ * failover, and load balancing.
+ *
+ * Features:
+ * - Provider registration and management
+ * - Requirement-based provider selection
+ * - Automatic failover on provider errors
+ * - Rate limiting and quota management
+ * - Cost tracking and optimization
+ * - Provider health monitoring
+ *
+ * Compatible with @sparkleideas/agentic-flow's provider manager patterns.
+ *
+ * @module v3/integration/provider-adapter
+ * @version 3.0.0-alpha.1
+ */
+
+import { EventEmitter } from 'events';
+import type { Task } from './agentic-flow-agent.js';
+
+/**
+ * Provider interface for AI model providers
+ */
+export interface Provider {
+  /** Unique provider identifier */
+  id: string;
+  /** Provider name */
+  name: string;
+  /** Provider type */
+  type: ProviderType;
+  /** Available models */
+  models: ModelInfo[];
+  /** Provider capabilities */
+  capabilities: ProviderCapability[];
+  /** Provider status */
+  status: ProviderStatus;
+  /** Rate limits */
+  rateLimits: RateLimits;
+  /** Cost per token (input/output) */
+  costPerToken: CostInfo;
+  /** Provider-specific configuration */
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Provider types
+ */
+export type ProviderType =
+  | 'anthropic'
+  | 'openai'
+  | 'google'
+  | 'azure'
+  | 'aws'
+  | 'ollama'
+  | 'huggingface'
+  | 'custom';
+
+/**
+ * Provider capabilities
+ */
+export type ProviderCapability =
+  | 'text-completion'
+  | 'chat'
+  | 'embeddings'
+  | 'vision'
+  | 'code-generation'
+  | 'function-calling'
+  | 'streaming'
+  | 'fine-tuning'
+  | 'batch-processing'
+  | 'long-context';
+
+/**
+ * Provider status
+ */
+export type ProviderStatus =
+  | 'available'
+  | 'degraded'
+  | 'unavailable'
+  | 'rate-limited'
+  | 'maintenance';
+
+/**
+ * Model information
+ */
+export interface ModelInfo {
+  /** Model identifier */
+  id: string;
+  /** Model display name */
+  name: string;
+  /** Maximum context length */
+  maxContextLength: number;
+  /** Maximum output tokens */
+  maxOutputTokens: number;
+  /** Supported capabilities */
+  capabilities: ProviderCapability[];
+  /** Model-specific configuration */
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Rate limit configuration
+ */
+export interface RateLimits {
+  /** Requests per minute */
+  requestsPerMinute: number;
+  /** Tokens per minute */
+  tokensPerMinute: number;
+  /** Current request count */
+  currentRequests: number;
+  /** Current token count */
+  currentTokens: number;
+  /** Reset timestamp */
+  resetAt: number;
+}
+
+/**
+ * Cost information
+ */
+export interface CostInfo {
+  /** Cost per 1K input tokens in USD */
+  inputPer1K: number;
+  /** Cost per 1K output tokens in USD */
+  outputPer1K: number;
+  /** Currency */
+  currency: string;
+}
+
+/**
+ * Provider requirements for selection
+ */
+export interface ProviderRequirements {
+  /** Required capabilities */
+  capabilities?: ProviderCapability[];
+  /** Minimum context length */
+  minContextLength?: number;
+  /** Maximum cost per 1K tokens */
+  maxCostPer1K?: number;
+  /** Preferred provider types */
+  preferredTypes?: ProviderType[];
+  /** Excluded provider IDs */
+  excludeProviders?: string[];
+  /** Required model ID */
+  modelId?: string;
+  /** Require streaming support */
+  streaming?: boolean;
+  /** Require vision support */
+  vision?: boolean;
+  /** Custom filters */
+  customFilters?: ((provider: Provider) => boolean)[];
+}
+
+/**
+ * Provider selection result
+ */
+export interface ProviderSelectionResult {
+  /** Selected provider */
+  provider: Provider;
+  /** Selected model */
+  model: ModelInfo;
+  /** Selection score */
+  score: number;
+  /** Selection reasoning */
+  reasons: string[];
+  /** Alternative providers */
+  alternatives: Array<{
+    provider: Provider;
+    model: ModelInfo;
+    score: number;
+  }>;
+}
+
+/**
+ * Execution options
+ */
+export interface ExecutionOptions {
+  /** Model to use (overrides automatic selection) */
+  modelId?: string;
+  /** Temperature for generation */
+  temperature?: number;
+  /** Maximum tokens to generate */
+  maxTokens?: number;
+  /** Enable streaming */
+  stream?: boolean;
+  /** Stop sequences */
+  stopSequences?: string[];
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Retry configuration */
+  retry?: {
+    maxAttempts: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+  };
+  /** Metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Execution result
+ */
+export interface ExecutionResult {
+  /** Success indicator */
+  success: boolean;
+  /** Output content */
+  content: string;
+  /** Provider used */
+  providerId: string;
+  /** Model used */
+  modelId: string;
+  /** Token usage */
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+  };
+  /** Cost in USD */
+  cost: number;
+  /** Execution latency in milliseconds */
+  latencyMs: number;
+  /** Error if failed */
+  error?: Error;
+  /** Metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Provider metrics
+ */
+export interface ProviderMetrics {
+  /** Total requests */
+  totalRequests: number;
+  /** Successful requests */
+  successfulRequests: number;
+  /** Failed requests */
+  failedRequests: number;
+  /** Average latency in milliseconds */
+  avgLatencyMs: number;
+  /** Total tokens used */
+  totalTokens: number;
+  /** Total cost in USD */
+  totalCost: number;
+  /** Last request timestamp */
+  lastRequest: number;
+  /** Uptime percentage */
+  uptimePercent: number;
+}
+
+/**
+ * Provider adapter configuration
+ */
+export interface ProviderAdapterConfig {
+  /** Default provider ID */
+  defaultProviderId?: string;
+  /** Default model ID */
+  defaultModelId?: string;
+  /** Enable automatic failover */
+  enableFailover?: boolean;
+  /** Maximum failover attempts */
+  maxFailoverAttempts?: number;
+  /** Enable cost tracking */
+  enableCostTracking?: boolean;
+  /** Cost limit per hour in USD */
+  costLimitPerHour?: number;
+  /** Enable provider health checks */
+  enableHealthChecks?: boolean;
+  /** Health check interval in milliseconds */
+  healthCheckInterval?: number;
+  /** Enable request caching */
+  enableCaching?: boolean;
+  /** Cache TTL in milliseconds */
+  cacheTTL?: number;
+}
+
+/**
+ * ProviderAdapter - Multi-provider AI model management
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new ProviderAdapter({
+ *   enableFailover: true,
+ *   enableCostTracking: true,
+ * });
+ *
+ * // Register providers
+ * adapter.registerProvider({
+ *   id: 'anthropic',
+ *   name: 'Anthropic',
+ *   type: 'anthropic',
+ *   models: [...],
+ *   capabilities: ['chat', 'code-generation'],
+ *   status: 'available',
+ *   rateLimits: { ... },
+ *   costPerToken: { ... },
+ * });
+ *
+ * // Select provider based on requirements
+ * const result = adapter.selectProvider({
+ *   capabilities: ['code-generation'],
+ *   maxCostPer1K: 0.01,
+ * });
+ *
+ * // Execute task
+ * const output = await adapter.executeWithProvider(task, result.provider);
+ * ```
+ */
+export class ProviderAdapter extends EventEmitter {
+  /** Registered providers */
+  providers: Map<string, Provider>;
+
+  /** Provider metrics */
+  private metrics: Map<string, ProviderMetrics>;
+
+  /** Adapter configuration */
+  private config: ProviderAdapterConfig;
+
+  /** Health check timer */
+  private healthCheckTimer: NodeJS.Timeout | null = null;
+
+  /** Request cache */
+  private cache: Map<string, { result: ExecutionResult; timestamp: number }>;
+
+  /** Hourly cost tracking */
+  private hourlyCost: { amount: number; resetAt: number };
+
+  /**
+   * Create a new ProviderAdapter instance
+   *
+   * @param config - Adapter configuration
+   */
+  constructor(config: ProviderAdapterConfig = {}) {
+    super();
+
+    this.providers = new Map();
+    this.metrics = new Map();
+    this.cache = new Map();
+
+    this.config = {
+      enableFailover: config.enableFailover ?? true,
+      maxFailoverAttempts: config.maxFailoverAttempts ?? 3,
+      enableCostTracking: config.enableCostTracking ?? true,
+      costLimitPerHour: config.costLimitPerHour ?? 10,
+      enableHealthChecks: config.enableHealthChecks ?? true,
+      healthCheckInterval: config.healthCheckInterval ?? 60000,
+      enableCaching: config.enableCaching ?? false,
+      cacheTTL: config.cacheTTL ?? 300000,
+      ...config,
+    };
+
+    this.hourlyCost = { amount: 0, resetAt: Date.now() + 3600000 };
+
+    this.emit('adapter-created', { config: this.config });
+  }
+
+  /**
+   * Initialize the adapter
+   */
+  async initialize(): Promise<void> {
+    // Start health checks if enabled
+    if (this.config.enableHealthChecks) {
+      this.startHealthChecks();
+    }
+
+    this.emit('adapter-initialized');
+  }
+
+  /**
+   * Shutdown the adapter
+   */
+  async shutdown(): Promise<void> {
+    this.stopHealthChecks();
+    this.providers.clear();
+    this.metrics.clear();
+    this.cache.clear();
+
+    this.emit('adapter-shutdown');
+  }
+
+  /**
+   * Register a provider
+   *
+   * @param provider - Provider to register
+   */
+  registerProvider(provider: Provider): void {
+    this.providers.set(provider.id, provider);
+
+    // Initialize metrics
+    this.metrics.set(provider.id, {
+      totalRequests: 0,
+      successfulRequests: 0,
+      failedRequests: 0,
+      avgLatencyMs: 0,
+      totalTokens: 0,
+      totalCost: 0,
+      lastRequest: 0,
+      uptimePercent: 100,
+    });
+
+    this.emit('provider-registered', { providerId: provider.id });
+  }
+
+  /**
+   * Unregister a provider
+   *
+   * @param providerId - Provider ID to remove
+   */
+  unregisterProvider(providerId: string): boolean {
+    const removed = this.providers.delete(providerId);
+    this.metrics.delete(providerId);
+
+    if (removed) {
+      this.emit('provider-unregistered', { providerId });
+    }
+
+    return removed;
+  }
+
+  /**
+   * Get a provider by ID
+   *
+   * @param providerId - Provider ID
+   * @returns Provider or undefined
+   */
+  getProvider(providerId: string): Provider | undefined {
+    return this.providers.get(providerId);
+  }
+
+  /**
+   * Get all registered providers
+   */
+  getAllProviders(): Provider[] {
+    return Array.from(this.providers.values());
+  }
+
+  /**
+   * Get available providers (not unavailable or rate-limited)
+   */
+  getAvailableProviders(): Provider[] {
+    return Array.from(this.providers.values()).filter(
+      (p) => p.status === 'available' || p.status === 'degraded'
+    );
+  }
+
+  /**
+   * Select the best provider based on requirements
+   *
+   * @param requirements - Selection requirements
+   * @returns Selection result with provider and model
+   */
+  selectProvider(requirements: ProviderRequirements = {}): ProviderSelectionResult {
+    const candidates: Array<{
+      provider: Provider;
+      model: ModelInfo;
+      score: number;
+      reasons: string[];
+    }> = [];
+
+    for (const provider of this.getAvailableProviders()) {
+      // Check exclusions
+      if (requirements.excludeProviders?.includes(provider.id)) {
+        continue;
+      }
+
+      // Check capabilities
+      if (requirements.capabilities) {
+        const hasAllCapabilities = requirements.capabilities.every((cap) =>
+          provider.capabilities.includes(cap)
+        );
+        if (!hasAllCapabilities) {
+          continue;
+        }
+      }
+
+      // Check preferred types
+      if (
+        requirements.preferredTypes &&
+        !requirements.preferredTypes.includes(provider.type)
+      ) {
+        continue;
+      }
+
+      // Check custom filters
+      if (requirements.customFilters) {
+        const passesFilters = requirements.customFilters.every((filter) =>
+          filter(provider)
+        );
+        if (!passesFilters) {
+          continue;
+        }
+      }
+
+      // Find suitable model
+      for (const model of provider.models) {
+        // Check context length
+        if (
+          requirements.minContextLength &&
+          model.maxContextLength < requirements.minContextLength
+        ) {
+          continue;
+        }
+
+        // Check model ID
+        if (requirements.modelId && model.id !== requirements.modelId) {
+          continue;
+        }
+
+        // Check streaming
+        if (requirements.streaming && !model.capabilities.includes('streaming')) {
+          continue;
+        }
+
+        // Check vision
+        if (requirements.vision && !model.capabilities.includes('vision')) {
+          continue;
+        }
+
+        // Check cost
+        const avgCost =
+          (provider.costPerToken.inputPer1K + provider.costPerToken.outputPer1K) / 2;
+        if (requirements.maxCostPer1K && avgCost > requirements.maxCostPer1K) {
+          continue;
+        }
+
+        // Calculate score
+        const { score, reasons } = this.calculateProviderScore(
+          provider,
+          model,
+          requirements
+        );
+
+        candidates.push({ provider, model, score, reasons });
+      }
+    }
+
+    if (candidates.length === 0) {
+      throw new Error('No providers match the requirements');
+    }
+
+    // Sort by score
+    candidates.sort((a, b) => b.score - a.score);
+
+    const best = candidates[0];
+    const alternatives = candidates.slice(1, 4).map(({ provider, model, score }) => ({
+      provider,
+      model,
+      score,
+    }));
+
+    this.emit('provider-selected', {
+      providerId: best.provider.id,
+      modelId: best.model.id,
+      score: best.score,
+    });
+
+    return {
+      provider: best.provider,
+      model: best.model,
+      score: best.score,
+      reasons: best.reasons,
+      alternatives,
+    };
+  }
+
+  /**
+   * Execute a task with a specific provider
+   *
+   * @param task - Task to execute
+   * @param provider - Provider to use
+   * @param options - Execution options
+   * @returns Execution result
+   */
+  async executeWithProvider(
+    task: Task,
+    provider: Provider,
+    options: ExecutionOptions = {}
+  ): Promise<ExecutionResult> {
+    // Check cache
+    if (this.config.enableCaching) {
+      const cached = this.getCachedResult(task, provider.id);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    // Check cost limits
+    if (this.config.enableCostTracking) {
+      this.checkCostLimits();
+    }
+
+    // Check rate limits
+    this.checkRateLimits(provider);
+
+    const startTime = Date.now();
+    let result: ExecutionResult;
+    let attempt = 0;
+    const maxAttempts = options.retry?.maxAttempts ?? 1;
+
+    while (attempt < maxAttempts) {
+      try {
+        result = await this.executeRequest(task, provider, options);
+
+        // Update metrics on success
+        this.updateMetrics(provider.id, result);
+
+        // Update rate limits
+        this.updateRateLimits(provider, result.usage.totalTokens);
+
+        // Cache result
+        if (this.config.enableCaching) {
+          this.cacheResult(task, provider.id, result);
+        }
+
+        return result;
+      } catch (error) {
+        attempt++;
+
+        this.emit('execution-error', {
+          providerId: provider.id,
+          attempt,
+          error: error as Error,
+        });
+
+        if (attempt >= maxAttempts) {
+          // Try failover if enabled
+          if (this.config.enableFailover) {
+            const failoverResult = await this.tryFailover(task, provider, options);
+            if (failoverResult) {
+              return failoverResult;
+            }
+          }
+
+          // Update failure metrics
+          const metrics = this.metrics.get(provider.id);
+          if (metrics) {
+            metrics.failedRequests++;
+          }
+
+          return {
+            success: false,
+            content: '',
+            providerId: provider.id,
+            modelId: options.modelId || provider.models[0]?.id || 'unknown',
+            usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+            cost: 0,
+            latencyMs: Date.now() - startTime,
+            error: error as Error,
+          };
+        }
+
+        // Wait before retry
+        const delay =
+          (options.retry?.backoffMs ?? 1000) *
+          Math.pow(options.retry?.backoffMultiplier ?? 2, attempt - 1);
+        await this.delay(delay);
+      }
+    }
+
+    throw new Error('Execution failed after all attempts');
+  }
+
+  /**
+   * Get provider metrics
+   *
+   * @param providerId - Provider ID
+   * @returns Provider metrics or undefined
+   */
+  getProviderMetrics(providerId: string): ProviderMetrics | undefined {
+    return this.metrics.get(providerId);
+  }
+
+  /**
+   * Get all provider metrics
+   */
+  getAllMetrics(): Map<string, ProviderMetrics> {
+    return new Map(this.metrics);
+  }
+
+  /**
+   * Update provider status
+   *
+   * @param providerId - Provider ID
+   * @param status - New status
+   */
+  updateProviderStatus(providerId: string, status: ProviderStatus): void {
+    const provider = this.providers.get(providerId);
+    if (provider) {
+      provider.status = status;
+
+      this.emit('provider-status-changed', { providerId, status });
+    }
+  }
+
+  // ===== Private Methods =====
+
+  /**
+   * Calculate provider score for selection
+   */
+  private calculateProviderScore(
+    provider: Provider,
+    model: ModelInfo,
+    requirements: ProviderRequirements
+  ): { score: number; reasons: string[] } {
+    let score = 100;
+    const reasons: string[] = [];
+
+    // Base availability score
+    if (provider.status === 'available') {
+      score += 20;
+      reasons.push('Provider is fully available');
+    } else if (provider.status === 'degraded') {
+      score -= 10;
+      reasons.push('Provider is degraded');
+    }
+
+    // Cost efficiency
+    const avgCost =
+      (provider.costPerToken.inputPer1K + provider.costPerToken.outputPer1K) / 2;
+    if (avgCost < 0.01) {
+      score += 15;
+      reasons.push('Low cost provider');
+    } else if (avgCost > 0.05) {
+      score -= 10;
+    }
+
+    // Rate limit headroom
+    const rateHeadroom = 1 - provider.rateLimits.currentRequests / provider.rateLimits.requestsPerMinute;
+    score += rateHeadroom * 10;
+    if (rateHeadroom > 0.5) {
+      reasons.push('Good rate limit headroom');
+    }
+
+    // Historical performance
+    const metrics = this.metrics.get(provider.id);
+    if (metrics) {
+      const successRate =
+        metrics.totalRequests > 0
+          ? metrics.successfulRequests / metrics.totalRequests
+          : 1;
+      score += successRate * 20;
+
+      if (successRate > 0.95) {
+        reasons.push('High success rate');
+      }
+
+      // Latency penalty
+      if (metrics.avgLatencyMs > 5000) {
+        score -= 15;
+        reasons.push('High latency');
+      }
+    }
+
+    // Preferred provider bonus
+    if (requirements.preferredTypes?.includes(provider.type)) {
+      score += 10;
+      reasons.push('Preferred provider type');
+    }
+
+    // Context length bonus
+    if (model.maxContextLength > 100000) {
+      score += 5;
+      reasons.push('Long context support');
+    }
+
+    return { score, reasons };
+  }
+
+  /**
+   * Execute a request to the provider
+   */
+  private async executeRequest(
+    task: Task,
+    provider: Provider,
+    options: ExecutionOptions
+  ): Promise<ExecutionResult> {
+    const startTime = Date.now();
+
+    // Execute with provider-like latency (actual API calls via external integrations)
+    await this.delay(100);
+
+    const model = options.modelId
+      ? provider.models.find((m) => m.id === options.modelId) || provider.models[0]
+      : provider.models[0];
+
+    const inputTokens = Math.ceil(task.description.length / 4);
+    const outputTokens = Math.ceil(inputTokens * 1.5);
+
+    const cost =
+      (inputTokens / 1000) * provider.costPerToken.inputPer1K +
+      (outputTokens / 1000) * provider.costPerToken.outputPer1K;
+
+    return {
+      success: true,
+      content: `Executed task ${task.id} with ${provider.name}`,
+      providerId: provider.id,
+      modelId: model?.id || 'default',
+      usage: {
+        inputTokens,
+        outputTokens,
+        totalTokens: inputTokens + outputTokens,
+      },
+      cost,
+      latencyMs: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Try failover to alternative providers
+   */
+  private async tryFailover(
+    task: Task,
+    failedProvider: Provider,
+    options: ExecutionOptions
+  ): Promise<ExecutionResult | null> {
+    for (let attempt = 0; attempt < this.config.maxFailoverAttempts!; attempt++) {
+      try {
+        const selection = this.selectProvider({
+          excludeProviders: [failedProvider.id],
+          capabilities: failedProvider.capabilities,
+        });
+
+        this.emit('failover-attempt', {
+          fromProvider: failedProvider.id,
+          toProvider: selection.provider.id,
+          attempt: attempt + 1,
+        });
+
+        const result = await this.executeRequest(
+          task,
+          selection.provider,
+          options
+        );
+
+        this.updateMetrics(selection.provider.id, result);
+
+        this.emit('failover-success', {
+          fromProvider: failedProvider.id,
+          toProvider: selection.provider.id,
+        });
+
+        return result;
+      } catch (error) {
+        this.emit('failover-error', {
+          attempt: attempt + 1,
+          error: error as Error,
+        });
+      }
+    }
+
+    this.emit('failover-exhausted', { originalProvider: failedProvider.id });
+    return null;
+  }
+
+  /**
+   * Update provider metrics
+   */
+  private updateMetrics(providerId: string, result: ExecutionResult): void {
+    const metrics = this.metrics.get(providerId);
+    if (!metrics) return;
+
+    metrics.totalRequests++;
+    metrics.lastRequest = Date.now();
+
+    if (result.success) {
+      metrics.successfulRequests++;
+    } else {
+      metrics.failedRequests++;
+    }
+
+    // Update average latency
+    const totalLatency = metrics.avgLatencyMs * (metrics.totalRequests - 1) + result.latencyMs;
+    metrics.avgLatencyMs = totalLatency / metrics.totalRequests;
+
+    // Update token and cost totals
+    metrics.totalTokens += result.usage.totalTokens;
+    metrics.totalCost += result.cost;
+
+    // Update hourly cost
+    if (this.config.enableCostTracking) {
+      this.hourlyCost.amount += result.cost;
+    }
+  }
+
+  /**
+   * Update rate limits after request
+   */
+  private updateRateLimits(provider: Provider, tokensUsed: number): void {
+    provider.rateLimits.currentRequests++;
+    provider.rateLimits.currentTokens += tokensUsed;
+
+    // Check if rate limited
+    if (
+      provider.rateLimits.currentRequests >= provider.rateLimits.requestsPerMinute ||
+      provider.rateLimits.currentTokens >= provider.rateLimits.tokensPerMinute
+    ) {
+      provider.status = 'rate-limited';
+
+      // Schedule reset
+      setTimeout(() => {
+        provider.rateLimits.currentRequests = 0;
+        provider.rateLimits.currentTokens = 0;
+        provider.status = 'available';
+      }, 60000);
+    }
+  }
+
+  /**
+   * Check rate limits before request
+   */
+  private checkRateLimits(provider: Provider): void {
+    // Reset rate limits if needed
+    const now = Date.now();
+    if (now >= provider.rateLimits.resetAt) {
+      provider.rateLimits.currentRequests = 0;
+      provider.rateLimits.currentTokens = 0;
+      provider.rateLimits.resetAt = now + 60000;
+      if (provider.status === 'rate-limited') {
+        provider.status = 'available';
+      }
+    }
+
+    if (provider.status === 'rate-limited') {
+      throw new Error(`Provider ${provider.id} is rate limited`);
+    }
+  }
+
+  /**
+   * Check cost limits
+   */
+  private checkCostLimits(): void {
+    const now = Date.now();
+
+    // Reset hourly cost if needed
+    if (now >= this.hourlyCost.resetAt) {
+      this.hourlyCost.amount = 0;
+      this.hourlyCost.resetAt = now + 3600000;
+    }
+
+    if (this.hourlyCost.amount >= this.config.costLimitPerHour!) {
+      throw new Error(
+        `Hourly cost limit exceeded: $${this.hourlyCost.amount.toFixed(2)} / $${this.config.costLimitPerHour}`
+      );
+    }
+  }
+
+  /**
+   * Get cached result
+   */
+  private getCachedResult(
+    task: Task,
+    providerId: string
+  ): ExecutionResult | null {
+    const cacheKey = `${providerId}:${task.id}:${task.description}`;
+    const cached = this.cache.get(cacheKey);
+
+    if (cached && Date.now() - cached.timestamp < this.config.cacheTTL!) {
+      this.emit('cache-hit', { taskId: task.id, providerId });
+      return cached.result;
+    }
+
+    return null;
+  }
+
+  /**
+   * Cache result
+   */
+  private cacheResult(
+    task: Task,
+    providerId: string,
+    result: ExecutionResult
+  ): void {
+    const cacheKey = `${providerId}:${task.id}:${task.description}`;
+    this.cache.set(cacheKey, { result, timestamp: Date.now() });
+  }
+
+  /**
+   * Start health check timer
+   */
+  private startHealthChecks(): void {
+    this.healthCheckTimer = setInterval(() => {
+      this.performHealthChecks();
+    }, this.config.healthCheckInterval!);
+  }
+
+  /**
+   * Stop health check timer
+   */
+  private stopHealthChecks(): void {
+    if (this.healthCheckTimer) {
+      clearInterval(this.healthCheckTimer);
+      this.healthCheckTimer = null;
+    }
+  }
+
+  /**
+   * Perform health checks on all providers
+   */
+  private performHealthChecks(): void {
+    for (const provider of Array.from(this.providers.values())) {
+      const metrics = this.metrics.get(provider.id);
+      if (!metrics) continue;
+
+      // Calculate uptime based on recent success rate
+      const successRate =
+        metrics.totalRequests > 0
+          ? metrics.successfulRequests / metrics.totalRequests
+          : 1;
+      metrics.uptimePercent = successRate * 100;
+
+      // Update provider status based on metrics
+      if (successRate < 0.5 && metrics.totalRequests > 10) {
+        provider.status = 'unavailable';
+      } else if (successRate < 0.8 && metrics.totalRequests > 5) {
+        provider.status = 'degraded';
+      } else if (provider.status !== 'rate-limited') {
+        provider.status = 'available';
+      }
+
+      this.emit('provider-health-check', {
+        providerId: provider.id,
+        status: provider.status,
+        uptimePercent: metrics.uptimePercent,
+      });
+    }
+  }
+
+  /**
+   * Utility delay function
+   */
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+/**
+ * Create a provider adapter with the given configuration
+ *
+ * @param config - Adapter configuration
+ * @returns Configured ProviderAdapter
+ */
+export function createProviderAdapter(
+  config: ProviderAdapterConfig = {}
+): ProviderAdapter {
+  return new ProviderAdapter(config);
+}
+
+/**
+ * Create default provider configurations for common providers
+ */
+export function createDefaultProviders(): Provider[] {
+  return [
+    {
+      id: 'anthropic-claude',
+      name: 'Anthropic Claude',
+      type: 'anthropic',
+      models: [
+        {
+          id: 'claude-3-opus-20240229',
+          name: 'Claude 3 Opus',
+          maxContextLength: 200000,
+          maxOutputTokens: 4096,
+          capabilities: ['chat', 'code-generation', 'vision', 'long-context'],
+        },
+        {
+          id: 'claude-3-sonnet-20240229',
+          name: 'Claude 3 Sonnet',
+          maxContextLength: 200000,
+          maxOutputTokens: 4096,
+          capabilities: ['chat', 'code-generation', 'vision', 'long-context'],
+        },
+        {
+          id: 'claude-3-5-sonnet-20241022',
+          name: 'Claude 3.5 Sonnet',
+          maxContextLength: 200000,
+          maxOutputTokens: 8192,
+          capabilities: ['chat', 'code-generation', 'vision', 'long-context', 'streaming'],
+        },
+      ],
+      capabilities: ['chat', 'code-generation', 'vision', 'streaming', 'long-context'],
+      status: 'available',
+      rateLimits: {
+        requestsPerMinute: 60,
+        tokensPerMinute: 100000,
+        currentRequests: 0,
+        currentTokens: 0,
+        resetAt: Date.now() + 60000,
+      },
+      costPerToken: {
+        inputPer1K: 0.015,
+        outputPer1K: 0.075,
+        currency: 'USD',
+      },
+    },
+    {
+      id: 'openai-gpt4',
+      name: 'OpenAI GPT-4',
+      type: 'openai',
+      models: [
+        {
+          id: 'gpt-4-turbo',
+          name: 'GPT-4 Turbo',
+          maxContextLength: 128000,
+          maxOutputTokens: 4096,
+          capabilities: ['chat', 'code-generation', 'vision', 'function-calling'],
+        },
+        {
+          id: 'gpt-4o',
+          name: 'GPT-4o',
+          maxContextLength: 128000,
+          maxOutputTokens: 4096,
+          capabilities: ['chat', 'code-generation', 'vision', 'function-calling', 'streaming'],
+        },
+      ],
+      capabilities: ['chat', 'code-generation', 'vision', 'function-calling', 'streaming'],
+      status: 'available',
+      rateLimits: {
+        requestsPerMinute: 500,
+        tokensPerMinute: 150000,
+        currentRequests: 0,
+        currentTokens: 0,
+        resetAt: Date.now() + 60000,
+      },
+      costPerToken: {
+        inputPer1K: 0.01,
+        outputPer1K: 0.03,
+        currency: 'USD',
+      },
+    },
+    {
+      id: 'ollama-local',
+      name: 'Ollama Local',
+      type: 'ollama',
+      models: [
+        {
+          id: 'llama3',
+          name: 'Llama 3',
+          maxContextLength: 8192,
+          maxOutputTokens: 2048,
+          capabilities: ['chat', 'code-generation'],
+        },
+        {
+          id: 'codellama',
+          name: 'Code Llama',
+          maxContextLength: 16384,
+          maxOutputTokens: 2048,
+          capabilities: ['chat', 'code-generation'],
+        },
+      ],
+      capabilities: ['chat', 'code-generation'],
+      status: 'available',
+      rateLimits: {
+        requestsPerMinute: 1000,
+        tokensPerMinute: 1000000,
+        currentRequests: 0,
+        currentTokens: 0,
+        resetAt: Date.now() + 60000,
+      },
+      costPerToken: {
+        inputPer1K: 0,
+        outputPer1K: 0,
+        currency: 'USD',
+      },
+    },
+  ];
+}