@sparkleideas/providers 3.0.0-alpha.22 → 3.0.0-alpha.49

package/dist/base-provider.d.ts

@@ -0,0 +1,174 @@
+/**
+ * V3 Abstract Base Provider
+ *
+ * Provides common functionality for all LLM providers:
+ * - Circuit breaker protection
+ * - Health monitoring
+ * - Cost tracking
+ * - Request metrics
+ *
+ * @module @sparkleideas/providers/base-provider
+ */
+import { EventEmitter } from 'events';
+import { ILLMProvider, LLMProvider, LLMProviderConfig, LLMRequest, LLMResponse, LLMStreamEvent, LLMModel, ModelInfo, ProviderCapabilities, HealthCheckResult, ProviderStatus, CostEstimate, UsageStats, UsagePeriod, LLMProviderError } from './types.js';
+/**
+ * Simple circuit breaker implementation
+ */
+declare class CircuitBreaker {
+    private readonly name;
+    private readonly threshold;
+    private readonly resetTimeout;
+    private failures;
+    private lastFailure;
+    private state;
+    constructor(name: string, threshold?: number, resetTimeout?: number);
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    getState(): string;
+}
+/**
+ * Logger interface
+ */
+export interface ILogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, error?: unknown): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Console logger implementation
+ */
+export declare const consoleLogger: ILogger;
+/**
+ * Base provider options
+ */
+export interface BaseProviderOptions {
+    logger?: ILogger;
+    config: LLMProviderConfig;
+    cacheTTL?: number;
+    circuitBreakerOptions?: {
+        threshold?: number;
+        resetTimeout?: number;
+    };
+}
+/**
+ * Abstract base class for LLM providers
+ */
+export declare abstract class BaseProvider extends EventEmitter implements ILLMProvider {
+    abstract readonly name: LLMProvider;
+    abstract readonly capabilities: ProviderCapabilities;
+    protected logger: ILogger;
+    protected circuitBreaker: CircuitBreaker;
+    protected healthCheckInterval?: ReturnType<typeof setInterval>;
+    protected lastHealthCheck?: HealthCheckResult;
+    protected requestCount: number;
+    protected errorCount: number;
+    protected totalTokens: number;
+    protected totalCost: number;
+    protected requestMetrics: Map<string, {
+        timestamp: Date;
+        model: string;
+        tokens: number;
+        cost?: number;
+        latency: number;
+    }>;
+    config: LLMProviderConfig;
+    constructor(options: BaseProviderOptions);
+    /**
+     * Initialize the provider
+     */
+    initialize(): Promise<void>;
+    /**
+     * Provider-specific initialization (override in subclass)
+     */
+    protected abstract doInitialize(): Promise<void>;
+    /**
+     * Validate provider configuration
+     */
+    protected validateConfig(): void;
+    /**
+     * Complete a request
+     */
+    complete(request: LLMRequest): Promise<LLMResponse>;
+    /**
+     * Provider-specific completion (override in subclass)
+     */
+    protected abstract doComplete(request: LLMRequest): Promise<LLMResponse>;
+    /**
+     * Stream complete a request
+     */
+    streamComplete(request: LLMRequest): AsyncIterable<LLMStreamEvent>;
+    /**
+     * Provider-specific stream completion (override in subclass)
+     */
+    protected abstract doStreamComplete(request: LLMRequest): AsyncIterable<LLMStreamEvent>;
+    /**
+     * List available models
+     */
+    abstract listModels(): Promise<LLMModel[]>;
+    /**
+     * Get model information
+     */
+    abstract getModelInfo(model: LLMModel): Promise<ModelInfo>;
+    /**
+     * Validate if a model is supported
+     */
+    validateModel(model: LLMModel): boolean;
+    /**
+     * Perform health check
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Provider-specific health check (override in subclass)
+     */
+    protected abstract doHealthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Get provider status
+     */
+    getStatus(): ProviderStatus;
+    /**
+     * Get remaining rate limit (override in provider)
+     */
+    protected getRateLimitRemaining(): number | undefined;
+    /**
+     * Get rate limit reset time (override in provider)
+     */
+    protected getRateLimitReset(): Date | undefined;
+    /**
+     * Estimate cost for a request
+     */
+    estimateCost(request: LLMRequest): Promise<CostEstimate>;
+    /**
+     * Simple token estimation (4 chars ≈ 1 token)
+     */
+    protected estimateTokens(text: string): number;
+    /**
+     * Get usage statistics
+     */
+    getUsage(period?: UsagePeriod): Promise<UsageStats>;
+    private getStartDate;
+    private calculateAverageLatency;
+    /**
+     * Track successful request
+     */
+    protected trackRequest(request: LLMRequest, response: LLMResponse, latency: number): void;
+    /**
+     * Track streaming request
+     */
+    protected trackStreamRequest(request: LLMRequest, totalTokens: number, totalCost: number, latency: number): void;
+    /**
+     * Transform errors to provider errors
+     */
+    protected transformError(error: unknown): LLMProviderError;
+    /**
+     * Start periodic health checks
+     */
+    protected startHealthChecks(): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=base-provider.d.ts.map

package/dist/base-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-provider.d.ts","sourceRoot":"","sources":["../src/base-provider.ts"],"names":[],"mappings":"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"}