@flare-ai-sdk/server 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1196 @@
+import EventEmitter from 'eventemitter3';
+
+/**
+ * Circuit breaker configuration
+ */
+interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold?: number;
+    /** Time to wait before attempting reset (ms) */
+    resetTimeout?: number;
+    /** Half-open state request limit */
+    halfOpenRequests?: number;
+}
+/**
+ * Health check status
+ */
+interface HealthStatus {
+    /** Overall health status */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Timestamp */
+    timestamp: number;
+    /** Service uptime in ms */
+    uptime: number;
+    /** Circuit breaker state */
+    circuitBreaker?: 'closed' | 'open' | 'half-open';
+    /** Active connections */
+    activeConnections?: number;
+    /** Queue size */
+    queueSize?: number;
+    /** Metrics */
+    metrics?: MetricsData;
+}
+/**
+ * Performance metrics
+ */
+interface MetricsData {
+    /** Total requests */
+    totalRequests: number;
+    /** Successful requests */
+    successfulRequests: number;
+    /** Failed requests */
+    failedRequests: number;
+    /** Average latency in ms */
+    avgLatency: number;
+    /** P95 latency in ms */
+    p95Latency: number;
+    /** P99 latency in ms */
+    p99Latency: number;
+    /** Requests per second */
+    rps: number;
+}
+/**
+ * Authentication context
+ */
+interface AuthContext {
+    /** API key or token */
+    apiKey?: string;
+    /** User identifier */
+    userId?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Validate function */
+    validate?: (req: any) => Promise<boolean>;
+}
+/**
+ * Content filter configuration
+ */
+interface ContentFilter {
+    /** Input filter function */
+    filterInput?: (content: string) => Promise<string | null>;
+    /** Output filter function */
+    filterOutput?: (content: string) => Promise<string | null>;
+    /** Blocked patterns */
+    blockedPatterns?: RegExp[];
+}
+
+/**
+ * Rate limiting configuration
+ */
+interface RateLimitConfig {
+    /** Maximum requests per window */
+    maxRequests?: number;
+    /** Time window in milliseconds */
+    windowMs?: number;
+    /** Client identifier for per-client limiting */
+    clientId?: string;
+}
+
+/**
+ * Retry configuration with exponential backoff
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Initial delay in milliseconds */
+    initialDelay?: number;
+    /** Maximum delay in milliseconds */
+    maxDelay?: number;
+    /** Backoff multiplier */
+    backoffMultiplier?: number;
+    /** Jitter to add randomness */
+    jitter?: boolean;
+}
+/**
+ * Request timeout configuration
+ */
+interface TimeoutConfig {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Connection timeout in milliseconds */
+    connectionTimeout?: number;
+}
+
+/**
+ * Core type definitions for paprflare-kit
+ * @module types
+ */
+
+/**
+ * Supported AI providers
+ */
+type AIProvider = 'openai' | 'anthropic' | 'google' | 'sarvam' | 'custom';
+/**
+ * Configuration for AI model requests
+ */
+interface ModelConfig {
+    /** Provider name */
+    provider: AIProvider;
+    /** Model identifier (e.g., 'gpt-4', 'claude-3-opus') */
+    model: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Base URL for custom providers */
+    baseUrl?: string;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Temperature for randomness (0-2) */
+    temperature?: number;
+    /** Top P sampling parameter */
+    topP?: number;
+    /** Frequency penalty (-2 to 2) */
+    frequencyPenalty?: number;
+    /** Presence penalty (-2 to 2) */
+    presencePenalty?: number;
+    /** Stop sequences */
+    stop?: string[];
+}
+/**
+ * Complete SDK configuration
+ */
+interface FlareConfig extends ModelConfig {
+    retry?: RetryConfig;
+    timeout?: TimeoutConfig;
+    rateLimit?: RateLimitConfig;
+    circuitBreaker?: CircuitBreakerConfig;
+    /** Enable request queuing */
+    enableQueueing?: boolean;
+    /** Queue priority (higher = processed first) */
+    queuePriority?: number;
+    /** Enable connection pooling */
+    enablePooling?: boolean;
+    /** Pool size for connections */
+    poolSize?: number;
+    /** Enable request deduplication */
+    enableDeduplication?: boolean;
+    /** Enable metrics collection */
+    enableMetrics?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Message in a conversation
+ */
+interface Message {
+    /** Message role */
+    role: 'system' | 'user' | 'assistant';
+    /** Message content */
+    content: string;
+    /** Optional message name */
+    name?: string;
+    /** Optional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Request for text generation
+ */
+interface GenerateTextRequest {
+    /** Conversation messages */
+    messages: Message[];
+    /** Optional system prompt */
+    systemPrompt?: string;
+    /** Model configuration overrides */
+    config?: Partial<FlareConfig>;
+}
+/**
+ * Response from text generation
+ */
+interface GenerateTextResponse {
+    /** Generated text content */
+    text: string;
+    /** Token usage information */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Finish reason */
+    finishReason: 'stop' | 'length' | 'content_filter' | 'tool_calls';
+    /** Response metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Streaming chunk from text generation
+ */
+interface TextStreamChunk {
+    /** Chunk type */
+    type: 'content' | 'metadata' | 'error' | 'done';
+    /** Text content (for content chunks) */
+    content?: string;
+    /** Metadata (for metadata chunks) */
+    metadata?: Record<string, any>;
+    /** Error information (for error chunks) */
+    error?: Error;
+    /** Completion data (for done chunks) */
+    done?: {
+        finishReason: string;
+        usage: GenerateTextResponse['usage'];
+    };
+}
+/**
+ * Schema for structured object generation
+ */
+interface ObjectSchema<T> {
+    /** Schema type */
+    type: 'object' | 'array' | 'string' | 'number' | 'boolean';
+    /** Property definitions (for object type) */
+    properties?: Record<string, ObjectSchema<T>>;
+    /** Required properties */
+    required?: string[];
+    /** Items schema (for array type) */
+    items?: ObjectSchema<T>;
+    /** Description */
+    description?: string;
+    /** Enum values */
+    enum?: any[];
+}
+/**
+ * Request for object generation
+ */
+interface GenerateObjectRequest<T> {
+    /** Conversation messages */
+    messages: Message[];
+    /** JSON schema describing T */
+    schema: ObjectSchema<T>;
+    /** Optional system prompt */
+    systemPrompt?: string;
+    /** Model configuration overrides */
+    config?: Partial<FlareConfig>;
+}
+/**
+ * Response from object generation
+ */
+interface GenerateObjectResponse<T = any> {
+    /** Parsed object */
+    object: T;
+    /** Raw text response */
+    text: string;
+    /** Token usage */
+    usage: GenerateTextResponse['usage'];
+    /** Validation errors (if any) */
+    validationErrors?: string[];
+}
+/**
+ * Streaming chunk from object generation
+ */
+interface ObjectStreamChunk<T = any> {
+    /** Chunk type */
+    type: 'partial' | 'complete' | 'error';
+    /** Partial object (incrementally parsed) */
+    partial?: Partial<T>;
+    /** Complete object (when done) */
+    object?: T;
+    /** Error information */
+    error?: Error;
+    /** Raw text accumulated so far */
+    text?: string;
+}
+/**
+ * Stream reader interface
+ */
+interface StreamReader<T> {
+    /** Read next chunk */
+    read(): Promise<{
+        value: T;
+        done: boolean;
+    }>;
+    /** Cancel the stream */
+    cancel(): void;
+    /** Get async iterator */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+/**
+ * Event types for streaming
+ */
+interface StreamEvents {
+    'chunk': (chunk: any) => void;
+    'error': (error: Error) => void;
+    'done': (result: any) => void;
+    'start': () => void;
+    'abort': () => void;
+}
+
+/**
+ * Custom error classes for paprflare-kit
+ * @module errors
+ */
+/**
+ * Base error class for all paprflare-kit errors
+ */
+declare class FlareError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly retryable: boolean;
+    readonly details?: Record<string, any>;
+    constructor(message: string, code: string, statusCode?: number, retryable?: boolean, details?: Record<string, any>);
+}
+/**
+ * Network-related errors
+ */
+declare class NetworkError extends FlareError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Timeout errors
+ */
+declare class TimeoutError extends FlareError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Rate limit exceeded errors
+ */
+declare class RateLimitError extends FlareError {
+    readonly retryAfter?: number;
+    constructor(message: string, retryAfter?: number, details?: Record<string, any>);
+}
+/**
+ * Authentication/authorization errors
+ */
+declare class AuthenticationError extends FlareError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Invalid request errors
+ */
+declare class ValidationError extends FlareError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Circuit breaker open errors
+ */
+declare class CircuitBreakerError extends FlareError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Provider-specific errors
+ */
+declare class ProviderError extends FlareError {
+    readonly provider: string;
+    constructor(provider: string, message: string, statusCode?: number, details?: Record<string, any>);
+}
+/**
+ * Streaming errors
+ */
+declare class StreamError extends FlareError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Parse/validation errors for structured output
+ */
+declare class ParseError extends FlareError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Content filter errors
+ */
+declare class ContentFilterError extends FlareError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Check if an error is retryable
+ */
+declare function isRetryableError(error: Error): boolean;
+/**
+ * Extract status code from error
+ */
+declare function getErrorStatusCode(error: Error): number | undefined;
+
+/**
+ * Metrics collection and reporting
+ * @module metrics
+ */
+
+/**
+ * Metrics collector for monitoring SDK performance
+ *
+ * @example
+ * ```typescript
+ * const metrics = new MetricsCollector();
+ *
+ * const start = Date.now();
+ * try {
+ *   await doRequest();
+ *   metrics.recordSuccess(Date.now() - start);
+ * } catch (error) {
+ *   metrics.recordFailure(Date.now() - start);
+ * }
+ *
+ * console.log(metrics.getMetrics());
+ * ```
+ */
+declare class MetricsCollector {
+    private totalRequests;
+    private successfulRequests;
+    private failedRequests;
+    private latencyHistogram;
+    private startTime;
+    private windowStart;
+    private windowRequests;
+    private windowDuration;
+    /**
+     * Record successful request
+     * @param latency - Request latency in milliseconds
+     */
+    recordSuccess(latency: number): void;
+    /**
+     * Record failed request
+     * @param latency - Request latency in milliseconds
+     */
+    recordFailure(latency: number): void;
+    /**
+     * Update rolling window for RPS calculation
+     */
+    private updateWindow;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): MetricsData;
+    /**
+     * Get success rate as percentage
+     */
+    getSuccessRate(): number;
+    /**
+     * Get uptime in milliseconds
+     */
+    getUptime(): number;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Get detailed statistics
+     */
+    getDetailedStats(): {
+        successRate: number;
+        uptime: number;
+        timestamp: number;
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        avgLatency: number;
+        p95Latency: number;
+        p99Latency: number;
+        rps: number;
+    };
+}
+/**
+ * Get or create global metrics collector
+ */
+declare function getGlobalMetrics(): MetricsCollector;
+/**
+ * Create a new metrics collector
+ */
+declare function createMetricsCollector(): MetricsCollector;
+/**
+ * Measure function execution time and record metrics
+ * @param fn - Function to measure
+ * @param collector - Metrics collector (defaults to global)
+ * @returns Function result
+ */
+declare function measureLatency<T>(fn: () => Promise<T>, collector?: MetricsCollector): Promise<T>;
+
+/**
+ * Rate limiter implementation
+ * @module rateLimiter
+ */
+
+/**
+ * Token bucket rate limiter
+ * Implements sliding window algorithm for smooth rate limiting
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({ maxRequests: 10, windowMs: 1000 });
+ *
+ * try {
+ *   await limiter.acquire('user-123');
+ *   // Request allowed
+ * } catch (error) {
+ *   // Rate limit exceeded
+ * }
+ * ```
+ */
+declare class RateLimiter {
+    private buckets;
+    private config;
+    private cleanupInterval?;
+    constructor(config?: Partial<RateLimitConfig>);
+    /**
+     * Acquire a token for rate limiting
+     * @param clientId - Client identifier
+     * @throws RateLimitError if rate limit exceeded
+     */
+    acquire(clientId?: string): Promise<void>;
+    /**
+     * Check if request would be allowed without consuming token
+     * @param clientId - Client identifier
+     * @returns true if request would be allowed
+     */
+    check(clientId?: string): boolean;
+    /**
+     * Get remaining tokens for client
+     * @param clientId - Client identifier
+     * @returns Number of remaining requests
+     */
+    getRemaining(clientId?: string): number;
+    /**
+     * Reset rate limit for client
+     * @param clientId - Client identifier
+     */
+    reset(clientId?: string): void;
+    /**
+     * Get or create bucket for client
+     */
+    private getBucket;
+    /**
+     * Refill tokens based on elapsed time
+     */
+    private refillBucket;
+    /**
+     * Calculate retry-after time in milliseconds
+     */
+    private calculateRetryAfter;
+    /**
+     * Start periodic cleanup of old buckets
+     */
+    private startCleanup;
+    /**
+     * Get statistics for monitoring
+     */
+    getStats(): {
+        totalClients: number;
+        config: Required<RateLimitConfig>;
+    };
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+/**
+ * Create a rate limiter instance
+ * @param config - Rate limit configuration
+ * @returns RateLimiter instance
+ */
+declare function createRateLimiter(config?: Partial<RateLimitConfig>): RateLimiter;
+
+/**
+ * Request queue with priority handling
+ * @module requestQueue
+ */
+
+/**
+ * Queue configuration
+ */
+interface QueueConfig {
+    /** Maximum concurrent requests */
+    concurrency?: number;
+    /** Maximum queue size */
+    maxQueueSize?: number;
+    /** Request timeout in ms */
+    timeout?: number;
+}
+/**
+ * Priority queue for managing concurrent requests
+ * Higher priority items are processed first
+ *
+ * @example
+ * ```typescript
+ * const queue = new RequestQueue({ concurrency: 5 });
+ *
+ * queue.on('drain', () => console.log('Queue empty'));
+ *
+ * const result = await queue.add(
+ *   async () => fetchData(),
+ *   { priority: 10 }
+ * );
+ * ```
+ */
+declare class RequestQueue extends EventEmitter {
+    private queue;
+    private running;
+    private config;
+    private requestCounter;
+    constructor(config?: Partial<QueueConfig>);
+    /**
+     * Add request to queue
+     * @param fn - Async function to execute
+     * @param priority - Request priority (higher = processed first)
+     * @returns Promise resolving to function result
+     */
+    add<T>(fn: () => Promise<T>, priority?: number): Promise<T>;
+    /**
+     * Process queue items
+     */
+    private process;
+    /**
+     * Execute queue item with timeout
+     */
+    private executeItem;
+    /**
+     * Get queue size
+     */
+    size(): number;
+    /**
+     * Get number of running requests
+     */
+    getRunning(): number;
+    /**
+     * Check if queue is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Clear all pending requests
+     */
+    clear(): void;
+    /**
+     * Wait for queue to drain
+     */
+    drain(): Promise<void>;
+    /**
+     * Get queue statistics
+     */
+    getStats(): {
+        queueSize: number;
+        running: number;
+        concurrency: number;
+        maxQueueSize: number;
+    };
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<QueueConfig>): void;
+}
+/**
+ * Create a request queue instance
+ * @param config - Queue configuration
+ * @returns RequestQueue instance
+ */
+declare function createRequestQueue(config?: Partial<QueueConfig>): RequestQueue;
+
+/**
+ * Retry logic with exponential backoff
+ * @module retry
+ */
+
+/**
+ * Retry a function with exponential backoff
+ * @param fn - Async function to retry
+ * @param config - Retry configuration
+ * @param onRetry - Optional callback on retry attempt
+ * @returns Promise resolving to function result
+ * @throws Error after all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => fetchData(),
+ *   { maxRetries: 3, initialDelay: 1000 },
+ *   (attempt, error) => console.log(`Retry ${attempt}: ${error.message}`)
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>, onRetry?: (attempt: number, error: Error, delay: number) => void): Promise<T>;
+/**
+ * Retry class with configurable behavior
+ */
+declare class RetryHandler {
+    private config;
+    constructor(config?: Partial<RetryConfig>);
+    /**
+     * Execute function with retry logic
+     */
+    execute<T>(fn: () => Promise<T>, onRetry?: (attempt: number, error: Error, delay: number) => void): Promise<T>;
+    /**
+     * Update retry configuration
+     */
+    updateConfig(config: Partial<RetryConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<RetryConfig>;
+}
+/**
+ * Create a retry handler with custom configuration
+ * @param config - Retry configuration
+ * @returns RetryHandler instance
+ *
+ * @example
+ * ```typescript
+ * const retry = createRetryHandler({ maxRetries: 5, initialDelay: 500 });
+ * const result = await retry.execute(() => apiCall());
+ * ```
+ */
+declare function createRetryHandler(config?: Partial<RetryConfig>): RetryHandler;
+
+/**
+ * Circuit breaker pattern implementation
+ * @module circuitBreaker
+ */
+
+/**
+ * Circuit breaker states
+ */
+declare enum CircuitState {
+    CLOSED = "closed",
+    OPEN = "open",
+    HALF_OPEN = "half-open"
+}
+/**
+ * Circuit breaker implementation for fault tolerance
+ * Prevents cascading failures by stopping requests to failing services
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Service failing, requests blocked
+ * - HALF_OPEN: Testing if service recovered, limited requests allowed
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({ failureThreshold: 3 });
+ *
+ * breaker.on('open', () => console.log('Circuit opened'));
+ * breaker.on('close', () => console.log('Circuit closed'));
+ *
+ * const result = await breaker.execute(async () => {
+ *   return await fetchData();
+ * });
+ * ```
+ */
+declare class CircuitBreaker extends EventEmitter {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime?;
+    private resetTimer?;
+    private config;
+    constructor(config?: Partial<CircuitBreakerConfig>);
+    /**
+     * Execute a function with circuit breaker protection
+     * @param fn - Async function to execute
+     * @returns Promise resolving to function result
+     * @throws CircuitBreakerError if circuit is open
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Handle successful execution
+     */
+    private onSuccess;
+    /**
+     * Handle failed execution
+     */
+    private onFailure;
+    /**
+     * Open the circuit (block requests)
+     */
+    private open;
+    /**
+     * Enter half-open state (test if service recovered)
+     */
+    private halfOpen;
+    /**
+     * Close the circuit (allow requests)
+     */
+    private close;
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit statistics
+     */
+    getStats(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        lastFailureTime: number | undefined;
+    };
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+/**
+ * Create a circuit breaker instance
+ * @param config - Circuit breaker configuration
+ * @returns CircuitBreaker instance
+ */
+declare function createCircuitBreaker(config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+
+/**
+ * Base provider interface and implementations
+ * @module providers
+ */
+
+/**
+ * Base AI provider interface
+ */
+interface AIProviderInterface {
+    generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    streamText(request: GenerateTextRequest): AsyncIterable<any>;
+    generateObject<T>(request: GenerateObjectRequest<T>): Promise<GenerateObjectResponse<T>>;
+    streamObject<T>(request: GenerateObjectRequest<T>): AsyncIterable<any>;
+}
+/**
+ * Base provider class with common functionality
+ */
+declare abstract class BaseProvider implements AIProviderInterface {
+    protected config: ModelConfig;
+    constructor(config: ModelConfig);
+    protected makeRequest(url: string, options: RequestInit, stream?: boolean): Promise<Response>;
+    protected formatMessages(request: GenerateTextRequest): Message[];
+    protected getEndpoint(path: string): string;
+    protected abstract getDefaultBaseUrl(): string;
+    abstract generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    abstract streamText(request: GenerateTextRequest): AsyncIterable<any>;
+    abstract generateObject<T>(request: GenerateObjectRequest<T>): Promise<GenerateObjectResponse<T>>;
+    abstract streamObject<T>(request: GenerateObjectRequest<T>): AsyncIterable<any>;
+}
+
+/**
+ * Create provider instance based on configuration
+ */
+declare function createProvider(config: ModelConfig): AIProviderInterface;
+
+/**
+ * Anthropic provider implementation
+ */
+declare class AnthropicProvider extends BaseProvider {
+    protected getDefaultBaseUrl(): string;
+    generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    streamText(request: GenerateTextRequest): AsyncIterable<any>;
+    generateObject<T>(request: GenerateObjectRequest<T>): Promise<GenerateObjectResponse<T>>;
+    streamObject<T>(request: GenerateObjectRequest<T>): AsyncIterable<any>;
+}
+
+/**
+ * OpenAI provider implementation
+ */
+declare class OpenAIProvider extends BaseProvider {
+    protected getDefaultBaseUrl(): string;
+    generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    streamText(request: GenerateTextRequest): AsyncIterable<any>;
+    generateObject<T>(request: GenerateObjectRequest<T>): Promise<GenerateObjectResponse<T>>;
+    streamObject<T>(request: GenerateObjectRequest<T>): AsyncIterable<any>;
+}
+
+/**
+ * Google AI (Gemini) provider implementation
+ * Supports Google's Gemini models via their API
+ *
+ * @example
+ * ```typescript
+ * const provider = new GoogleProvider({
+ *   provider: 'google',
+ *   model: 'gemini-pro',
+ *   apiKey: process.env.GOOGLE_API_KEY,
+ * });
+ * ```
+ */
+declare class GoogleProvider extends BaseProvider {
+    protected getDefaultBaseUrl(): string;
+    /**
+     * Format messages for Google's API format
+     */
+    private formatGoogleMessages;
+    generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    streamText(request: GenerateTextRequest): AsyncIterable<any>;
+    generateObject<T>(request: GenerateObjectRequest<T>): Promise<GenerateObjectResponse<T>>;
+    streamObject<T>(request: GenerateObjectRequest<T>): AsyncIterable<any>;
+    /**
+     * Map Google's finish reason to standard format
+     */
+    private mapGoogleFinishReason;
+}
+
+/**
+ * Sarvam AI provider implementation
+ * Supports Sarvam's Indian language models
+ *
+ * @example
+ * ```typescript
+ * const provider = new SarvamProvider({
+ *   provider: 'sarvam',
+ *   model: 'sarvam-2b',
+ *   apiKey: process.env.SARVAM_API_KEY,
+ * });
+ * ```
+ */
+declare class SarvamProvider extends BaseProvider {
+    protected getDefaultBaseUrl(): string;
+    generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    streamText(request: GenerateTextRequest): AsyncIterable<any>;
+    generateObject<T>(request: GenerateObjectRequest<T>): Promise<GenerateObjectResponse<T>>;
+    streamObject<T>(request: GenerateObjectRequest<T>): AsyncIterable<any>;
+    /**
+     * Map Sarvam's finish reason to standard format
+     */
+    private mapSarvamFinishReason;
+}
+
+/**
+ * Custom provider implementation
+ * Allows integration with any OpenAI-compatible API
+ *
+ * @example
+ * ```typescript
+ * const provider = new CustomProvider({
+ *   provider: 'custom',
+ *   model: 'llama-3-70b',
+ *   baseUrl: 'https://your-api.com/v1',
+ *   apiKey: process.env.CUSTOM_API_KEY,
+ * });
+ * ```
+ */
+declare class CustomProvider extends BaseProvider {
+    protected getDefaultBaseUrl(): string;
+    /**
+     * Request format for custom provider
+     */
+    private requestFormat;
+    /**
+     * Set request format for custom provider
+     */
+    setRequestFormat(format: 'openai' | 'anthropic' | 'custom'): void;
+    generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    streamText(request: GenerateTextRequest): AsyncIterable<any>;
+    generateObject<T>(request: GenerateObjectRequest<T>): Promise<GenerateObjectResponse<T>>;
+    streamObject<T>(request: GenerateObjectRequest<T>): AsyncIterable<any>;
+    /**
+     * Format request body based on provider format
+     */
+    private formatRequestBody;
+    /**
+     * Parse text response based on provider format
+     */
+    private parseTextResponse;
+    /**
+     * Parse streaming response
+     */
+    private parseStreamResponse;
+}
+
+/**
+ * Streaming utilities for real-time data processing
+ * @module stream
+ */
+
+/**
+ * Transform stream for processing chunks
+ */
+declare class TransformStream<TInput, TOutput> {
+    private transformer;
+    constructor(transformer: (chunk: TInput) => TOutput | Promise<TOutput>);
+    transform(source: AsyncIterable<TInput>): AsyncIterable<TOutput>;
+}
+/**
+ * Stream reader implementation
+ */
+declare class FlareStreamReader<T> implements StreamReader<T> {
+    private source;
+    private done;
+    constructor(source: AsyncIterable<T>);
+    read(): Promise<{
+        value: T;
+        done: boolean;
+    }>;
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+/**
+ * Create a data stream writer for Server-Sent Events
+ * @returns Writer object with methods to push data
+ *
+ * @example
+ * ```typescript
+ * const writer = createDataStreamWriter();
+ *
+ * writer.writeData({ type: 'message', content: 'Hello' });
+ * writer.writeError(new Error('Something went wrong'));
+ * writer.close();
+ *
+ * return new Response(writer.readable);
+ * ```
+ */
+declare function createDataStreamWriter(): {
+    readable: ReadableStream<Uint8Array<ArrayBufferLike>>;
+    /**
+     * Write data event
+     */
+    writeData(data: any): void;
+    /**
+     * Write error event
+     */
+    writeError(error: Error): void;
+    /**
+     * Write custom event
+     */
+    writeEvent(event: string, data: any): void;
+    /**
+     * Close the stream
+     */
+    close(): void;
+};
+/**
+ * Convert async iterable to UI stream response
+ * Transforms server stream into format suitable for client consumption
+ *
+ * @param stream - Async iterable of chunks
+ * @returns Response object with streaming body
+ *
+ * @example
+ * ```typescript
+ * const stream = streamText({ messages, config });
+ * return toUiStreamResponse(stream);
+ * ```
+ */
+declare function toUiStreamResponse<T>(stream: AsyncIterable<T>, headers?: Record<string, string>): Response;
+/**
+ * Parse Server-Sent Events stream
+ * @param response - Fetch Response with SSE stream
+ * @returns Async iterable of parsed events
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/api/stream');
+ * for await (const event of parseSSEStream(response)) {
+ *   console.log(event);
+ * }
+ * ```
+ */
+declare function parseSSEStream(response: Response): AsyncIterable<any>;
+/**
+ * Merge multiple streams into one
+ * @param streams - Array of async iterables
+ * @returns Merged async iterable
+ */
+declare function mergeStreams<T>(...streams: AsyncIterable<T>[]): AsyncIterable<T>;
+/**
+ * Buffer stream chunks for batch processing
+ * @param stream - Source stream
+ * @param size - Buffer size
+ * @returns Buffered stream
+ */
+declare function bufferStream<T>(stream: AsyncIterable<T>, size: number): AsyncIterable<T[]>;
+/**
+ * Throttle stream to limit rate
+ * @param stream - Source stream
+ * @param delayMs - Delay between chunks in milliseconds
+ * @returns Throttled stream
+ */
+declare function throttleStream<T>(stream: AsyncIterable<T>, delayMs: number): AsyncIterable<T>;
+
+/**
+ * Main FlareClient for AI interactions
+ * @module client
+ */
+
+/**
+ * Main FlareClient for AI interactions
+ * Provides text generation, streaming, and structured output
+ * with built-in retry, circuit breaker, and rate limiting
+ *
+ * @example
+ * ```typescript
+ * const client = new FlareClient({
+ *   provider: 'openai',
+ *   model: 'gpt-4',
+ *   apiKey: process.env.OPENAI_API_KEY,
+ * });
+ *
+ * // Generate text
+ * const response = await client.generateText({
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ *
+ * // Stream text
+ * const stream = client.streamText({
+ *   messages: [{ role: 'user', content: 'Tell me a story' }],
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   console.log(chunk.content);
+ * }
+ * ```
+ */
+declare class FlareClient extends EventEmitter {
+    private config;
+    private provider;
+    private retryHandler;
+    private circuitBreaker;
+    private rateLimiter;
+    private requestQueue?;
+    private metrics;
+    private startTime;
+    constructor(config: FlareConfig);
+    /**
+     * Setup event listeners for monitoring
+     */
+    private setupEventListeners;
+    /**
+     * Generate text synchronously
+     * @param request - Text generation request
+     * @returns Generated text response
+     */
+    generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    /**
+     * Stream text generation
+     * @param request - Text generation request
+     * @returns Async iterable of text chunks
+     */
+    streamText(request: GenerateTextRequest): AsyncIterable<any>;
+    /**
+     * Generate structured object
+     * @param request - Object generation request
+     * @returns Generated object response
+     */
+    generateObject<T = any>(request: GenerateObjectRequest<T>): Promise<GenerateObjectResponse<T>>;
+    /**
+     * Stream object generation
+     * @param request - Object generation request
+     * @returns Async iterable of object chunks
+     */
+    streamObject<T = any>(request: GenerateObjectRequest<T>): AsyncIterable<any>;
+    /**
+     * Get health status
+     */
+    getHealth(): HealthStatus;
+    /**
+     * Get performance metrics
+     */
+    getMetrics(): {
+        successRate: number;
+        uptime: number;
+        timestamp: number;
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        avgLatency: number;
+        p95Latency: number;
+        p99Latency: number;
+        rps: number;
+    };
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<FlareConfig>): void;
+    /**
+     * Reset circuit breaker
+     */
+    resetCircuitBreaker(): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+/**
+ * Create FlareClient instance
+ * @param config - Client configuration
+ * @returns FlareClient instance
+ */
+declare function createFlareClient(config: FlareConfig): FlareClient;
+
+export { type AIProvider, type AIProviderInterface, AnthropicProvider, type AuthContext, AuthenticationError, BaseProvider, CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerError, CircuitState, type ContentFilter, ContentFilterError, CustomProvider, FlareClient, type FlareConfig, FlareError, FlareStreamReader, type GenerateObjectRequest, type GenerateObjectResponse, type GenerateTextRequest, type GenerateTextResponse, GoogleProvider, type HealthStatus, type Message, MetricsCollector, type MetricsData, type ModelConfig, NetworkError, type ObjectSchema, type ObjectStreamChunk, OpenAIProvider, ParseError, ProviderError, type QueueConfig, type RateLimitConfig, RateLimitError, RateLimiter, RequestQueue, type RetryConfig, RetryHandler, SarvamProvider, StreamError, type StreamEvents, type StreamReader, type TextStreamChunk, type TimeoutConfig, TimeoutError, TransformStream, ValidationError, bufferStream, createCircuitBreaker, createDataStreamWriter, createFlareClient, createMetricsCollector, createProvider, createRateLimiter, createRequestQueue, createRetryHandler, getErrorStatusCode, getGlobalMetrics, isRetryableError, measureLatency, mergeStreams, parseSSEStream, throttleStream, toUiStreamResponse, withRetry };