@catalystlabs/tryai/dist/index.d.mts

Dead simple AI library. One line setup. Zero config. Just works.

import { z } from 'zod';
import { EventEmitter } from 'events';

/**
 * Embeddings API - Separate from main AI clients
 *
 * Usage:
 * - ai.embeddings.openai(text)
 * - ai.embeddings.google(text)
 * - ai.embeddings.lmstudio(text)
 */
declare class EmbeddingsAPI {
    private configLoader;
    constructor();
    /**
     * Create embeddings using OpenAI
     * Uses text-embedding-3-small by default
     */
    openai(input: string | string[], options?: {
        model?: string;
        apiKey?: string;
    }): Promise<any>;
    /**
     * Create embeddings using Google
     * Uses text-embedding-004 by default
     */
    google(input: string | string[], options?: {
        model?: string;
        apiKey?: string;
    }): Promise<any>;
    /**
     * Create embeddings using LM Studio
     * Uses whatever embedding model is loaded
     */
    lmstudio(input: string | string[], options?: {
        baseURL?: string;
    }): Promise<any>;
    /**
     * Helper to get embedding dimensions for each provider/model
     */
    getDimensions(provider: 'openai' | 'google' | 'lmstudio', model?: string): number;
}
declare const embeddings: EmbeddingsAPI;

/**
 * Rate limiting types
 */
interface RateLimitConfig {
    enabled?: boolean;
    requestsPerMinute?: number;
    tokensPerMinute?: number;
    requestsPerHour?: number;
    tokensPerHour?: number;
}
interface RateLimits {
    rpm: number;
    tpm: number;
    rph?: number;
    tph?: number;
    rpd?: number;
}
interface RateLimitState {
    requests: number;
    tokens: number;
    windowStart: number;
    queue: Array<{
        resolve: (value: any) => void;
        reject: (error: any) => void;
        execute: () => Promise<any>;
    }>;
}

interface QueuedRequest {
    id: string;
    provider: ProviderType;
    model: string;
    execute: () => Promise<any>;
    resolve: (value: any) => void;
    reject: (error: any) => void;
    timestamp: number;
    estimatedTokens?: number;
    retryCount: number;
}

/**
 * Base types for the unified AI system
 */

type ProviderType = 'openai' | 'anthropic' | 'google' | 'llama' | 'lmstudio' | 'router';
interface BaseConfig {
    temperature?: number;
    maxTokens?: number;
    topP?: number;
    topK?: number;
    frequencyPenalty?: number;
    presencePenalty?: number;
    stopSequences?: string[];
    systemPrompt?: string;
    retry?: RetryConfig;
    metadata?: MetadataConfig$1;
    rateLimit?: RateLimitConfig;
    cache?: CacheConfig;
    conversation?: ConversationConfig;
    tools?: string[] | boolean;
    toolChoice?: string | any;
    priority?: 'quality_first' | 'balanced' | 'aggressive_cost';
}
interface RetryConfig {
    enabled?: boolean;
    maxAttempts?: number;
    initialDelay?: number;
    maxDelay?: number;
    backoffMultiplier?: number;
    retryableErrors?: string[];
}
interface MetadataConfig$1 {
    enabled?: boolean;
    trackCosts?: boolean;
    trackLatency?: boolean;
    trackTokens?: boolean;
    includeTimestamp?: boolean;
}
interface CacheConfig {
    enabled?: boolean;
    ttl?: number;
    maxSize?: number;
    strategy?: 'memory' | 'disk' | 'redis';
}
interface ConversationConfig {
    maxHistory?: number;
    summarizeAfter?: number;
    persistHistory?: boolean;
}

/**
 * Database Recorder - Optional database tracking for TryAI
 *
 * Provides optional database recording capabilities for completions, conversations,
 * and messages. Designed to never break the main flow - all operations are async
 * and use silent failure mode by default.
 */
interface DatabaseConfig {
    enabled?: boolean;
    type: 'postgres' | 'mysql';
    connection?: string;
    silentFail?: boolean;
    capture?: {
        completions?: boolean;
        conversations?: boolean;
        messages?: boolean;
        toolCalls?: boolean;
    };
    userTracking?: {
        enabled?: boolean;
        userIdSource?: 'env' | 'function';
        envVar?: string;
    };
}
interface CompletionRecord {
    id: string;
    external_id?: string;
    user_id?: string;
    template_id?: number;
    prompt_text: string;
    completion_text?: string;
    system_prompt?: string;
    provider: string;
    model: string;
    temperature?: number;
    max_tokens?: number;
    tokens_input?: number;
    tokens_output?: number;
    tokens_total?: number;
    cost_input?: number;
    cost_output?: number;
    cost_total?: number;
    response_time_ms?: number;
    success: boolean;
    error_message?: string;
    metadata?: any;
    created_at?: Date;
}
interface ConversationRecord {
    id: string;
    external_id?: string;
    user_id?: string;
    ai_client_name?: string;
    current_provider: string;
    current_model: string;
    name?: string;
    message_count?: number;
    total_tokens_input?: number;
    total_tokens_output?: number;
    total_tokens?: number;
    total_cost_input?: number;
    total_cost_output?: number;
    total_cost?: number;
    context_window_size?: number;
    context_tokens_used?: number;
    average_latency?: number;
    started_at?: Date;
    last_message_at?: Date;
    metadata?: any;
}
interface MessageRecord {
    id: string;
    conversation_id: string;
    completion_id?: string;
    user_id?: string;
    ai_client_name?: string;
    role: 'user' | 'assistant' | 'system' | 'tool';
    content: string;
    message_index: number;
    in_context?: boolean;
    tokens_estimate?: number;
    created_at?: Date;
}
interface ToolCallRecord {
    id: string;
    completion_id: string;
    user_id?: string;
    tool_name: string;
    arguments: any;
    result?: any;
    execution_time_ms?: number;
    success: boolean;
    error_message?: string;
    created_at?: Date;
}
interface ConversationStats {
    messageCount: number;
    totalTokensInput: number;
    totalTokensOutput: number;
    totalTokens: number;
    totalCostInput: number;
    totalCostOutput: number;
    totalCost: number;
    averageLatency: number;
    lastMessageAt: Date;
}
declare class DatabaseRecorder {
    private db;
    private config;
    private isHealthy;
    private lastError;
    constructor(config: DatabaseConfig);
    /**
     * Initialize database connection using the CLI's database utilities
     */
    private initializeDatabase;
    /**
     * Get database connection string with proper hierarchy
     */
    private getConnectionString;
    /**
     * Get current user ID for tracking
     */
    private getCurrentUserId;
    /**
     * Record a completion (AI request/response)
     */
    recordCompletion(data: Partial<CompletionRecord>): Promise<void>;
    /**
     * Record a conversation
     */
    recordConversation(data: Partial<ConversationRecord>): Promise<void>;
    /**
     * Record a message
     */
    recordMessage(data: Partial<MessageRecord>): Promise<void>;
    /**
     * Record a tool call
     */
    recordToolCall(data: Partial<ToolCallRecord>): Promise<void>;
    /**
     * Update conversation statistics
     */
    updateConversationStats(conversationId: string, stats: ConversationStats): Promise<void>;
    /**
     * Check if we should capture this type of data
     */
    private shouldCapture;
    /**
     * Execute database operation with error handling
     */
    private executeWithErrorHandling;
    /**
     * Handle database errors with silent failure
     */
    private handleError;
    /**
     * Check database health and attempt to reconnect
     */
    private checkHealth;
    /**
     * Get recorder health status
     */
    getHealth(): {
        healthy: boolean;
        lastError?: string;
    };
    /**
     * Close database connection
     */
    close(): Promise<void>;
    /**
     * Fire-and-forget recording - never blocks main flow
     */
    recordAsync<T>(operation: () => Promise<T>): void;
}

/**
 * Client and configuration types
 */

interface GlobalConfig extends BaseConfig {
    apiKeys?: {
        openai?: string;
        anthropic?: string;
        google?: string;
        llama?: string;
        lmstudio?: string;
        router?: string;
    };
    router?: {
        baseURL?: string;
        apiKey?: string;
        priority?: 'quality_first' | 'balanced' | 'aggressive_cost';
    };
    defaultProvider?: ProviderType;
    features?: {
        autoModelSelection?: boolean;
        costOptimization?: boolean;
        latencyOptimization?: boolean;
    };
}
interface ClientConfig extends BaseConfig {
    provider: ProviderType;
    model: string;
    name?: string;
    description?: string;
    apiKeys?: Partial<Record<ProviderType, string>>;
    tools?: any;
    baseURL?: string;
    database?: DatabaseConfig;
}

/**
 * Message and conversation types
 */

interface Message {
    id: string;
    role: 'system' | 'user' | 'assistant' | 'tool';
    content: string;
    timestamp: Date;
    metadata?: MessageMetadata;
    inContext?: boolean;
}
interface MessageMetadata {
    id: string;
    timestamp: Date;
    provider: ProviderType;
    model: string;
    latency: number;
    tokens?: {
        input: number;
        output: number;
        total: number;
        estimated: boolean;
    };
    cost?: {
        input: number;
        output: number;
        total: number;
        currency: 'USD';
        estimated: boolean;
    };
}
interface ConversationMetadata {
    id: string;
    messageCount: number;
    startedAt?: Date;
    lastMessageAt?: Date;
    contextWindow: {
        size: number;
        used: number;
        messagesInContext: {
            start: number;
            end: number;
            count: number;
        };
    };
    totalTokens: {
        input: number;
        output: number;
        total: number;
    };
    totalCost: {
        input: number;
        output: number;
        total: number;
        currency: 'USD';
    };
    files?: {
        uploaded: FileReference[];
        generated: FileReference[];
    };
    stats: {
        total: number;
        userMessages: number;
        assistantMessages: number;
        systemMessages: number;
        toolMessages: number;
        averageMessageLength: number;
    };
    averageLatency: number;
}
interface FileReference {
    id: string;
    name: string;
    type: string;
    size: number;
    timestamp: Date;
    messageId?: string;
}

/**
 * Template system types
 */

interface Template {
    id: string;
    name: string;
    content: string;
    variables?: TemplateVariable[];
    metadata?: Record<string, any>;
}
interface TemplateVariable {
    name: string;
    type?: "string" | "number" | "boolean" | "object" | "array";
    required?: boolean;
    default?: any;
    description?: string;
}
interface PromptTemplate extends Template {
    category?: string;
    tags?: string[];
}
interface ResponseTemplate {
    id: string;
    name: string;
    description?: string;
    schema?: z.ZodSchema;
    format?: "json" | "markdown" | "text" | "xml";
    transform?: (response: string) => any;
    validate?: (response: any) => boolean;
}
interface TemplateConfig {
    systemPrompt?: string | PromptTemplate;
    prompt?: string | PromptTemplate;
    responseTemplate?: string | ResponseTemplate;
    variables?: Record<string, any>;
}
interface TemplateContext {
    [key: string]: any;
}
interface PromptTemplateFile {
    path: string;
    category: string;
    templates: Record<string, PromptTemplate | string>;
}

/**
 * Response types
 */

interface UnifiedResponse {
    content: string;
    metadata?: MessageMetadata;
    raw?: any;
}
interface StreamChunk {
    content: string;
    isComplete: boolean;
}
interface EmbeddingResponse {
    embeddings: number[][];
    model: string;
    usage?: {
        promptTokens: number;
        totalTokens: number;
    };
}
interface SSEEvent {
    event?: string;
    data?: string;
    id?: string;
    retry?: number;
}
interface ResponseTemplateFile {
    path: string;
    category: string;
    templates: Record<string, ResponseTemplate>;
}

/**
 * Model types
 */
interface ModelCapabilities {
    text: boolean;
    image: boolean;
    video: boolean;
    audio: boolean;
    functionCalling?: boolean;
    jsonMode?: boolean;
    maxTokens: number;
    maxOutput?: number;
    costPer1MTokens: {
        input: number;
        output: number;
    };
    rateLimit?: {
        rpm: number;
        tpm: number;
    };
}
interface ModelInfo {
    id: string;
    name: string;
    provider: string;
    capabilities: ModelCapabilities;
    description?: string;
}
interface TaskRequirements {
    needsImage?: boolean;
    needsVideo?: boolean;
    needsAudio?: boolean;
    needsLongContext?: boolean;
    needsFunctionCalling?: boolean;
    needsJsonMode?: boolean;
    preferCheap?: boolean;
    preferFast?: boolean;
    minContextWindow?: number;
    provider?: 'openai' | 'anthropic' | 'google' | 'llama' | 'any';
}

/**
 * Provider-specific types
 */
interface ImageGenerationOptions {
    model?: string;
    size?: string;
    quality?: "standard" | "hd";
    style?: "natural" | "vivid";
    n?: number;
    response_format?: "url" | "b64_json";
}
interface ImageEditOptions extends ImageGenerationOptions {
    mask?: Buffer | Blob;
}
interface TranscriptionOptions {
    model?: string;
    language?: string;
    prompt?: string;
    response_format?: "json" | "text" | "srt" | "verbose_json" | "vtt";
    temperature?: number;
}
interface TTSOptions {
    model?: string;
    voice?: string;
    speed?: number;
    response_format?: "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm";
}
interface VideoGenerationOptions {
    model?: string;
    duration?: number;
    fps?: number;
    resolution?: string;
    aspect_ratio?: string;
}
interface FileUploadOptions {
    purpose?: "fine-tune" | "assistants" | "vision" | "batch";
    filename?: string;
}
interface ModerationResult {
    safe: boolean;
    categories: string[];
    scores?: Record<string, number>;
    flagged?: boolean;
}
interface StructuredOutputOptions {
    temperature?: number;
    maxTokens?: number;
    responseFormat?: "json" | "json_object";
}
interface AIResponse {
    content: string;
    model?: string;
    usage?: {
        promptTokens: number;
        completionTokens: number;
        totalTokens: number;
    };
    originalContent?: string;
    metadata?: AIResponseMetadata;
}
interface AIProvider {
    complete(message: string | any[], options?: any): Promise<AIResponse>;
    stream(message: string | any[], options?: any): AsyncGenerator<any>;
}
interface ForgeConfig {
    provider?: "openai" | "anthropic" | "llama" | "lmstudio" | string;
    apiKey?: string;
    model?: string;
    temperature?: number;
    maxTokens?: number;
    baseURL?: string;
    cache?: boolean;
    safety?: boolean;
    analytics?: boolean;
    metadata?: boolean;
    moderation?: boolean | {
        enabled?: boolean;
        provider?: "openai" | "llama" | "anthropic";
        model?: string;
        threshold?: number;
        categories?: string[];
    };
}
interface AIResponseMetadata {
    timestamp?: string;
    model?: string;
    provider?: string;
    tokens?: {
        input: number;
        output: number;
        total: number;
    };
    cost?: {
        input: number;
        output: number;
        total: number;
    };
    latency?: number;
    type?: string;
    tool_name?: string;
    tool_id?: string;
    [key: string]: any;
}
/**
 * Type definitions for AI provider interfaces
 */
interface OpenAIContentItem {
    type: "input_text" | "input_image" | "input_file" | "output_text";
    text?: string;
    image_url?: string;
    detail?: "low" | "high" | "auto";
    file_url?: string;
    file_id?: string;
    file_data?: string;
    filename?: string;
    annotations?: Array<{
        type: "url_citation";
        start_index: number;
        end_index: number;
        url: string;
        title: string;
    }>;
}
interface OpenAIMessage {
    role: "system" | "user" | "assistant";
    content: string | OpenAIContentItem[];
}
interface OpenAILegacyMessage {
    role: "system" | "user" | "assistant" | "function" | "tool";
    content: string | null;
    name?: string;
    function_call?: {
        name: string;
        arguments: string;
    };
    tool_calls?: Array<{
        id: string;
        type: "function";
        function: {
            name: string;
            arguments: string;
        };
    }>;
}
interface OpenAIResponsesRequestBody {
    model: string;
    input: string | OpenAIMessage[];
    temperature?: number;
    max_output_tokens?: number;
    top_p?: number;
    frequency_penalty?: number;
    presence_penalty?: number;
    stop?: string | string[];
    stream?: boolean;
    tools?: Array<{
        type: "function" | "web_search_preview" | "image_generation" | "mcp" | "file_search" | "code_interpreter";
        name?: string;
        description?: string;
        parameters?: any;
        strict?: boolean;
    }>;
    tool_choice?: "none" | "auto" | "required" | {
        type: string;
        name?: string;
    };
    text?: {
        format?: {
            type: "json_schema" | "json_object" | "text";
            name?: string;
            schema?: any;
            strict?: boolean;
        };
    };
    reasoning?: {
        effort?: "low" | "medium" | "high";
        summary?: "auto" | "concise" | "detailed";
    };
    seed?: number;
    user?: string;
    previous_response_id?: string;
    store?: boolean;
}
interface OpenAIRequestBody {
    model: string;
    messages: OpenAILegacyMessage[];
    temperature?: number;
    max_tokens?: number;
    top_p?: number;
    frequency_penalty?: number;
    presence_penalty?: number;
    stop?: string | string[];
    stream?: boolean;
    tools?: Array<{
        type: "function";
        function: {
            name: string;
            description?: string;
            parameters?: any;
        };
    }>;
    tool_choice?: "none" | "auto" | {
        type: "function";
        function: {
            name: string;
        };
    };
    response_format?: {
        type: "text" | "json_object";
    };
    seed?: number;
    user?: string;
}
interface OpenAIResponseOutputItem {
    id: string;
    type: "message" | "function_call" | "function_call_output" | "web_search_call" | "image_generation_call" | "mcp_list_tools" | "mcp_call" | "reasoning";
    status?: "completed" | "incomplete";
    role?: "assistant" | "user" | "system";
    content?: OpenAIContentItem[];
    call_id?: string;
    name?: string;
    arguments?: string;
    output?: string;
    result?: string;
    revised_prompt?: string;
    summary?: Array<{
        type: "summary_text";
        text: string;
    }>;
}
interface OpenAIResponsesResponse {
    id: string;
    object: "response";
    created_at: number;
    model: string;
    status: "completed" | "incomplete";
    error?: any;
    incomplete_details?: {
        reason: "max_output_tokens" | "content_filter";
    };
    output: OpenAIResponseOutputItem[];
    output_text?: string;
    usage?: {
        input_tokens: number;
        output_tokens: number;
        total_tokens: number;
        input_tokens_details?: {
            cached_tokens?: number;
        };
        output_tokens_details?: {
            reasoning_tokens?: number;
        };
    };
}
interface OpenAIResponse {
    id: string;
    object: string;
    created: number;
    model: string;
    choices: Array<{
        index: number;
        message?: OpenAILegacyMessage;
        delta?: Partial<OpenAILegacyMessage>;
        finish_reason: string | null;
    }>;
    usage?: {
        prompt_tokens: number;
        completion_tokens: number;
        total_tokens: number;
    };
    system_fingerprint?: string;
}
interface OpenAIResponsesStreamEvent {
    type: "response.output_item.added" | "response.output_text.delta" | "response.function_call_arguments.delta" | "response.function_call_arguments.done" | "response.output_item.done" | "response.completed" | "response.error";
    response_id?: string;
    output_index?: number;
    item_id?: string;
    item?: OpenAIResponseOutputItem;
    delta?: string;
    arguments?: string;
    text?: string;
    error?: any;
}
interface OpenAIStreamChunk {
    id: string;
    object: string;
    created: number;
    model: string;
    choices: Array<{
        index: number;
        delta: Partial<OpenAILegacyMessage>;
        finish_reason: string | null;
    }>;
}
interface AnthropicContentBlock {
    type: "text" | "image" | "tool_use" | "tool_result" | "document" | "search_result";
    text?: string;
    source?: {
        type: "base64" | "file";
        media_type?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
        data?: string;
        file_id?: string;
    } | string;
    id?: string;
    name?: string;
    input?: any;
    tool_use_id?: string;
    content?: string | AnthropicContentBlock[];
    is_error?: boolean;
    title?: string;
    citations?: {
        enabled: boolean;
    };
    source_url?: string;
}
interface AnthropicMessage {
    role: "user" | "assistant" | "system";
    content: string | AnthropicContentBlock[];
}
interface AnthropicRequestBody {
    model: string;
    messages: AnthropicMessage[];
    system?: string;
    max_tokens: number;
    temperature?: number;
    top_p?: number;
    top_k?: number;
    stop_sequences?: string[];
    stream?: boolean;
    metadata?: {
        user_id?: string;
    };
    tools?: Array<{
        name: string;
        description?: string;
        input_schema: {
            type: "object";
            properties?: Record<string, any>;
            required?: string[];
        };
    }>;
    tool_choice?: {
        type: "auto" | "any" | "tool";
        name?: string;
    };
}
interface AnthropicResponse {
    id: string;
    type: "message";
    role: "assistant";
    content: AnthropicContentBlock[];
    model: string;
    stop_reason: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | null;
    stop_sequence: string | null;
    usage: {
        input_tokens: number;
        output_tokens: number;
    };
}
interface AnthropicStreamChunk {
    type: string;
    index?: number;
    delta?: {
        type: "text_delta" | "thinking_delta" | "input_json_delta";
        text?: string;
        thinking?: string;
        partial_json?: string;
    };
    content_block?: {
        type: "text" | "thinking" | "tool_use";
        text?: string;
        name?: string;
        id?: string;
    };
    message?: {
        id: string;
        type: string;
        role: "assistant";
        content: [];
        model: string;
        stop_reason: null;
        stop_sequence: null;
        usage: {
            input_tokens: number;
            output_tokens: number;
        };
    } | string;
    error?: {
        type: string;
        message: string;
    };
}
interface TypedFetchResponse<T = any> {
    data: T;
    headers: Record<string, string>;
    status: number;
    statusText: string;
}
interface ProviderOptions {
    model?: string;
    temperature?: number;
    maxTokens?: number;
    topP?: number;
    frequencyPenalty?: number;
    presencePenalty?: number;
    stop?: string | string[];
    stream?: boolean;
    messages?: Array<OpenAIMessage | AnthropicMessage>;
    tools?: any[];
    toolChoice?: any;
    responseFormat?: {
        type: string;
        json_schema?: {
            name: string;
            schema: any;
        };
    };
    reasoning?: {
        effort?: "low" | "medium" | "high";
        summary?: "auto" | "concise" | "detailed";
    };
    previousResponseId?: string;
    store?: boolean;
    topK?: number;
    stopSequences?: string[];
    system?: string;
    thinking?: {
        budget_tokens?: number;
    };
    mcpServers?: any[];
    serviceTier?: string;
    container?: any;
    metadata?: any;
    safety?: any;
    cachedContent?: any;
}
interface LlamaContentItem {
    type: "text" | "image_url";
    text?: string;
    image_url?: {
        url: string;
        alt_text?: string;
    };
}
interface LlamaMessage {
    role: "system" | "user" | "assistant";
    content: string | LlamaContentItem[];
}
interface LlamaRequestBody {
    model: string;
    messages: LlamaMessage[];
    max_tokens?: number;
    max_completion_tokens?: number;
    temperature?: number;
    top_p?: number;
    stop?: string[];
    stream?: boolean;
    tools?: Array<{
        type: "function";
        function: {
            name: string;
            description?: string;
            parameters?: any;
            strict?: boolean;
        };
    }>;
    tool_choice?: any;
    response_format?: {
        type: "json_schema";
        json_schema?: {
            name: string;
            schema: any;
        };
    };
}
interface LlamaResponse {
    completion_message: {
        content: string | {
            text?: string;
            type?: string;
        } | LlamaContentItem[];
        role: "assistant";
        stop_reason: "stop" | "max_tokens" | "tool_calls";
        tool_calls?: Array<{
            id: string;
            function: {
                name: string;
                arguments: string;
            };
        }>;
    };
    model: string;
    metrics?: Array<{
        metric: string;
        value: number;
    }>;
}
interface LlamaRateLimitInfo {
    limitTokens: number;
    remainingTokens: number;
    limitRequests: number;
    remainingRequests: number;
    resetTime?: Date;
}
interface LlamaTokenEstimation {
    textTokens: number;
    imageTokens: number;
    totalTokens: number;
    imageBreakdown?: Array<{
        width: number;
        height: number;
        tiles: number;
        tokens: number;
    }>;
}
interface LlamaConversationMemory {
    messages: LlamaMessage[];
    maxHistory: number;
    summarizedHistory?: string;
    totalTokens: number;
}
interface LlamaStreamChunk {
    event: {
        event_type: "progress" | "tool_call_progress" | "complete";
        delta?: {
            text?: string;
            arguments?: string;
        };
    };
    model?: string;
}
interface LlamaModerationRequest {
    messages: LlamaMessage[];
    model: string;
}
interface LlamaModerationResponse {
    model: string;
    results: Array<{
        flagged: boolean;
        flagged_categories?: string[];
    }>;
}
interface ProviderError extends Error {
    status?: number;
    code?: string;
    type?: string;
    param?: string;
    provider: string;
}
declare function createProviderError(provider: string, message: string, details?: Partial<ProviderError>): ProviderError;

/**
 * Cost estimation and tracking types
 */
interface CostEstimate {
    input: number;
    output: number;
    total: number;
    currency: "USD";
    estimated: boolean;
}
interface ModelCost {
    input: number;
    output: number;
}
interface CostConfig {
    trackCosts?: boolean;
    warnThreshold?: number;
    hardLimit?: number;
}

/**
 * Pipeline system types
 */

interface PipelineStep extends TemplateConfig {
    id?: string;
    name?: string;
    description?: string;
    includeSteps?: number[] | 'all' | 'none';
    config?: Partial<BaseConfig>;
    transform?: (output: any, context: PipelineContext) => any;
    skipIf?: (context: PipelineContext) => boolean;
}
interface PipelineContext {
    steps: StepResult[];
    variables: Record<string, any>;
    metadata: Record<string, any>;
}
interface StepResult {
    stepIndex: number;
    stepId?: string;
    input: {
        systemPrompt?: string;
        prompt: string;
    };
    output: any;
    raw?: any;
    metadata?: any;
    error?: Error;
    skipped?: boolean;
}
interface PipelineConfig {
    id?: string;
    name?: string;
    description?: string;
    steps: PipelineStep[];
    variables?: Record<string, any>;
    config?: Partial<BaseConfig>;
    transformFinal?: (results: StepResult[], context: PipelineContext) => any;
}

/**
 * Tool and function calling types
 */
interface FunctionParameter {
    name: string;
    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
    description?: string;
    required?: boolean;
    enum?: any[];
    properties?: Record<string, FunctionParameter>;
    items?: FunctionParameter;
}
interface FunctionDefinition {
    name: string;
    description: string;
    parameters?: FunctionParameter[];
    returns?: {
        type: string;
        description?: string;
    };
}
interface FunctionCall {
    name: string;
    arguments: Record<string, any>;
    id?: string;
}
interface FunctionResult {
    name: string;
    result: any;
    error?: string;
    id?: string;
}
interface Tool extends FunctionDefinition {
    handler: (...args: any[]) => any | Promise<any>;
    category?: string;
    tags?: string[];
    enabled?: boolean;
}
interface ToolCall {
    tool: Tool;
    call: FunctionCall;
    result?: any;
    error?: Error;
}
interface ToolSystemConfig {
    autoExecute?: boolean;
    maxIterations?: number;
    requireConfirmation?: (tool: Tool, args: any) => boolean | Promise<boolean>;
    onToolCall?: (tool: Tool, args: any) => void;
    onToolResult?: (tool: Tool, result: any) => void;
    onToolError?: (tool: Tool, error: Error) => void;
}

/**
 * Response transformer types
 */
type TransformerFunction = (response: string, metadata?: any) => string | Promise<string>;
interface Transformer {
    id: string;
    name: string;
    description?: string;
    transform: TransformerFunction;
    priority?: number;
    enabled?: boolean;
}

/**
 * Type definitions for LLMRouter integration
 */

/**
 * Response from the router's routing decision endpoint
 */
interface RouterRoutingResponse {
    routing_id: string;
    selected_model: string;
    routing_reason?: string;
    dimensional_scores?: Record<string, number>;
    priority_mode: string;
    estimated_cost?: number;
    cached?: boolean;
}
/**
 * Request payload for executing a routed prompt
 */
interface RouterExecuteRequest {
    routing_id: string;
    prompt: string;
    model?: string;
    priority_mode?: string;
    stream?: boolean;
    temperature?: number;
    max_tokens?: number;
    tools?: any[];
    response_format?: any;
}
/**
 * Feedback submission for improving routing decisions
 */
interface RouterFeedbackRequest {
    routing_id: string;
    helpful: boolean;
    rating?: number;
    comment?: string;
    actual_cost?: number;
    response_time?: number;
}
/**
 * Enhanced AI response with feedback submission capability
 */
interface RoutedAIResponse extends UnifiedResponse {
    submitFeedback: (feedback: Omit<RouterFeedbackRequest, 'routing_id'>) => Promise<void>;
}
/**
 * Priority modes for routing decisions
 */
type RouterPriorityMode = 'aggressive_cost' | 'balanced' | 'quality_first';
/**
 * Router configuration options
 */
interface RouterConfig {
    baseURL?: string;
    apiKey?: string;
    defaultPriority?: RouterPriorityMode;
}

/**
 * Conversation Manager - Manages conversation history for each client
 */

declare class ConversationManager {
    private messages;
    private config;
    private conversationId;
    private currentModel?;
    private currentProvider?;
    private databaseRecorder?;
    private files;
    constructor(config?: ConversationConfig, databaseRecorder?: DatabaseRecorder | null);
    /**
     * Record message to database (fire-and-forget, never blocks)
     */
    private recordMessageAsync;
    /**
     * Add a message to the conversation with proper metadata
     */
    addMessage(message: Omit<Message, 'id' | 'timestamp' | 'inContext'>, metadata?: MessageMetadata): Message;
    /**
     * Get conversation history
     */
    getHistory(limit?: number): Message[];
    /**
     * Get messages formatted for API calls
     */
    getFormattedHistory(limit?: number): Array<{
        role: string;
        content: string;
    }>;
    /**
     * Clear conversation history
     */
    clear(): number;
    /**
     * Set current model for context window tracking
     */
    setModel(provider: string, model: string): void;
    /**
     * Update which messages are in the context window
     */
    private updateContextWindow;
    /**
     * Add a file reference
     */
    addFile(file: FileReference, type: 'uploaded' | 'generated'): void;
    /**
     * Get conversation metadata with context window info
     */
    getConversationMetadata(): ConversationMetadata;
    /**
     * Export conversation as JSON
     */
    export(): string;
    /**
     * Import conversation from JSON
     */
    import(json: string): void;
    /**
     * Get message by ID
     */
    getMessage(id: string): Message | undefined;
    /**
     * Update a message
     */
    updateMessage(id: string, updates: Partial<Message>): boolean;
    /**
     * Remove a message
     */
    removeMessage(id: string): boolean;
    /**
     * Get conversation statistics
     */
    getStats(): {
        total: number;
        userMessages: number;
        assistantMessages: number;
        systemMessages: number;
        toolMessages: number;
        averageMessageLength: number;
    };
    /**
     * Get the last assistant message with metadata
     */
    getLastAssistantMessage(): Message | undefined;
    /**
     * Calculate total conversation cost
     */
    getTotalCost(): number;
}

/**
 * Cost Estimator - Accurate pricing for all providers
 *
 * Last updated: January 2025
 * Prices are in USD per 1000 tokens unless otherwise noted
 */

interface ModelPricing {
    inputPer1k: number;
    outputPer1k: number;
    cached?: boolean;
    notes?: string;
}
declare class CostEstimator {
    private pricing;
    private providerDefaults;
    private cacheMultipliers;
    /**
     * Estimate cost for token usage
     */
    estimate(provider: string, model: string, inputTokens: number, outputTokens: number, options?: {
        cached?: boolean;
        audioTokens?: {
            input?: number;
            output?: number;
        };
    }): Promise<CostEstimate>;
    /**
     * Estimate cost for image generation
     */
    estimateImageGeneration(provider: string, model: string, count?: number, size?: string, quality?: string): Promise<CostEstimate>;
    /**
     * Round cost to reasonable precision
     */
    private roundCost;
    /**
     * Get pricing info for a specific model
     */
    getPricing(provider: string, model: string): ModelPricing | null;
    /**
     * Check if a model is free (local models)
     */
    isFree(provider: string): boolean;
    /**
     * Get all available models for a provider
     */
    getProviderModels(provider: string): string[];
}

/**
 * Unified Rate Limiter for all AI providers
 *
 * Features:
 * - Provider-specific rate limits
 * - Token-based and request-based limiting
 * - Automatic queuing and retry
 * - Invisible to the user (never fails due to rate limits)
 */

declare class RateLimiter extends EventEmitter {
    private queues;
    private usage;
    private processing;
    private config;
    constructor(config?: Partial<RateLimitConfig>);
    /**
     * Execute a request with rate limiting
     */
    execute<T>(provider: ProviderType, model: string, fn: () => Promise<T>, estimatedTokens?: number): Promise<T>;
    /**
     * Check if request can be executed immediately
     */
    private canExecute;
    /**
     * Get rate limits for provider/model combination
     */
    private getLimits;
    /**
     * Get current usage for provider
     */
    private getUsage;
    /**
     * Record usage
     */
    private recordUsage;
    /**
     * Reset usage for provider
     */
    private resetUsage;
    /**
     * Add request to queue
     */
    private enqueue;
    /**
     * Get queue length for provider
     */
    private getQueueLength;
    /**
     * Start processing queued requests
     */
    private startProcessingLoop;
    /**
     * Process all provider queues
     */
    private processQueues;
    /**
     * Process queue for specific provider
     */
    private processProviderQueue;
    /**
     * Check if error is rate limit related
     */
    private isRateLimitError;
    /**
     * Get current queue status
     */
    getStatus(): Record<string, any>;
    /**
     * Clear all queues (use with caution)
     */
    clearQueues(): void;
}

/**
 * Template System for Unified AI Client
 */

declare class TemplateSystem {
    private promptTemplates;
    private responseTemplates;
    private systemPrompts;
    constructor();
    /**
     * Register a prompt template
     */
    registerPromptTemplate(template: PromptTemplate): void;
    /**
     * Register a response template
     */
    registerResponseTemplate(template: ResponseTemplate): void;
    /**
     * Register a system prompt template
     */
    registerSystemPrompt(template: PromptTemplate): void;
    /**
     * Process template configuration
     */
    processTemplateConfig(config: TemplateConfig): {
        systemPrompt?: string;
        prompt: string;
        responseFormat?: any;
    };
    /**
     * Apply response template to raw response
     */
    applyResponseTemplate(response: string, template: ResponseTemplate): Promise<any>;
    /**
     * Get template by ID
     */
    getPromptTemplate(id: string): PromptTemplate | undefined;
    getResponseTemplate(id: string): ResponseTemplate | undefined;
    getSystemPrompt(id: string): PromptTemplate | undefined;
    /**
     * List available templates
     */
    listTemplates(): {
        prompts: string[];
        responses: string[];
        systemPrompts: string[];
    };
    /**
     * Register built-in templates
     */
    private registerBuiltInTemplates;
    /**
     * Load templates from directory
     */
    loadTemplatesFromDirectory(dir: string): void;
    /**
     * Load prompt templates from directory
     */
    loadPromptTemplatesFromDirectory(dir: string): void;
    /**
     * Load response templates from directory
     */
    loadResponseTemplatesFromDirectory(dir: string): void;
}

/**
 * Response Transformer System - Intercept and transform AI responses
 */

declare class ResponseTransformer {
    private transformers;
    private order;
    constructor();
    /**
     * Register a transformer
     */
    register(transformer: Transformer): void;
    /**
     * Remove a transformer
     */
    unregister(id: string): void;
    /**
     * Enable/disable a transformer
     */
    setEnabled(id: string, enabled: boolean): void;
    /**
     * Apply all enabled transformers to a response
     */
    transform(response: string, metadata?: any): Promise<string>;
    /**
     * Update transformer execution order based on priority
     */
    private updateOrder;
    /**
     * Register built-in transformers
     */
    private registerBuiltInTransformers;
    /**
     * Create a custom transformer
     */
    static createTransformer(id: string, name: string, transform: TransformerFunction, priority?: number): Transformer;
    /**
     * Common transformer patterns
     */
    static patterns: {
        removeBetween: (startMarker: string, endMarker: string) => TransformerFunction;
        extractBetween: (startMarker: string, endMarker: string) => TransformerFunction;
        prefixLines: (prefix: string) => TransformerFunction;
        truncate: (maxLength: number, suffix?: string) => TransformerFunction;
    };
    /**
     * List all transformers
     */
    list(): Transformer[];
}

/**
 * Tool System - Unified tool/function calling across providers
 */

declare class ToolSystem {
    private tools;
    private config;
    constructor(config?: ToolSystemConfig);
    /**
     * Register a tool
     */
    register(tool: Tool): void;
    /**
     * Unregister a tool
     */
    unregister(name: string): void;
    /**
     * Get tool by name
     */
    getTool(name: string): Tool | undefined;
    /**
     * List all tools
     */
    listTools(category?: string, enabled?: boolean): Tool[];
    /**
     * Convert tools to provider format
     */
    getToolsForProvider(provider: string, toolNames?: string[]): any[];
    /**
     * Execute a tool call
     */
    executeTool(call: FunctionCall): Promise<FunctionResult>;
    /**
     * Process response for tool calls and optionally execute them
     */
    processToolCalls(response: any, provider: string): Promise<{
        toolCalls: ToolCall[];
        needsResponse: boolean;
    }>;
    /**
     * Format tool results for provider
     */
    formatToolResults(results: FunctionResult[], provider: string): any[];
    /**
     * Register built-in tools
     */
    private registerBuiltInTools;
    /**
     * Create a tool from a simple function
     */
    static createTool(name: string, description: string, handler: Function, parameters?: any[]): Tool;
    /**
     * Create tool from async function with automatic error handling
     */
    static createAsyncTool(name: string, description: string, handler: (...args: any[]) => Promise<any>, parameters?: any[]): Tool;
}

/**
 * Pipeline System - Multi-step AI workflows with flexible data flow
 */

declare class PipelineSystem {
    private client;
    private templateSystem;
    private pipelines;
    constructor(client: UnifiedClient, templateSystem?: TemplateSystem);
    /**
     * Register a pipeline
     */
    registerPipeline(pipeline: PipelineConfig): void;
    /**
     * Execute a pipeline
     */
    execute(pipelineOrId: string | PipelineConfig, variables?: Record<string, any>): Promise<any>;
    /**
     * Execute a single pipeline step
     */
    private executeStep;
    /**
     * Build variables for a step including selected previous outputs
     */
    private buildStepVariables;
    /**
     * Create a simple sequential pipeline
     */
    static createSequential(steps: Array<string | PipelineStep>): PipelineConfig;
    /**
     * Create a map-reduce pipeline
     */
    static createMapReduce(mapPrompt: string | PipelineStep, items: any[], reducePrompt: string | PipelineStep): PipelineConfig;
    /**
     * List registered pipelines
     */
    listPipelines(): string[];
    /**
     * Get pipeline by ID
     */
    getPipeline(id: string): PipelineConfig | undefined;
}

/**
 * Unified AI Client - The core client implementation
 *
 * Provides a clean, unified interface across all AI providers with:
 * - Settings hierarchy (client > global > default)
 * - Automatic metadata collection
 * - Conversation management
 * - Rate limiting
 * - Zero-config support
 */

declare class UnifiedClient {
    protected config: ClientConfig;
    protected globalConfig?: GlobalConfig;
    protected provider: any;
    protected conversation: ConversationManager;
    protected rateLimiter: RateLimiter;
    protected costEstimator: CostEstimator;
    protected templateSystem: TemplateSystem;
    protected responseTransformer: ResponseTransformer;
    protected toolSystem: ToolSystem;
    protected pipelineSystem: PipelineSystem;
    protected databaseRecorder: DatabaseRecorder | null;
    constructor(config: ClientConfig);
    /**
     * Record completion to database (fire-and-forget, never blocks)
     */
    private recordCompletionAsync;
    /**
     * Merge configurations with proper priority
     */
    private mergeConfigs;
    /**
     * Create the appropriate provider instance
     */
    private createProvider;
    /**
     * Get API key with proper hierarchy
     */
    private getApiKey;
    /**
     * Get rate limit configuration
     */
    private getRateLimitConfig;
    /**
     * Main completion method with all features integrated
     */
    completion(prompt: string | TemplateConfig, options?: BaseConfig): Promise<UnifiedResponse>;
    /**
     * Stream responses with metadata
     */
    stream(prompt: string, options?: BaseConfig): AsyncGenerator<any, void, unknown>;
    /**
     * Chat convenience method
     */
    chat(prompt: string, options?: BaseConfig): Promise<UnifiedResponse>;
    /**
     * List available models
     */
    listModels(): Promise<any[]>;
    /**
     * Get embeddings with zero config
     */
    embeddings(texts: string | string[]): Promise<number[][]>;
    /**
     * Text-to-speech with zero config
     */
    tts(text: string, options?: {
        voice?: string;
        speed?: number;
    }): Promise<Buffer>;
    /**
     * Speech-to-text with zero config
     */
    stt(audio: Buffer | string, options?: any): Promise<string>;
    /**
     * Content moderation
     */
    moderate(content: string | string[]): Promise<any>;
    /**
     * File management
     */
    uploadFile(file: Buffer | string, options?: any): Promise<any>;
    deleteFile(fileId: string): Promise<boolean>;
    getFile(fileId: string): Promise<any>;
    listFiles(purpose?: string): Promise<any[]>;
    /**
     * Should retry based on error type
     */
    private shouldRetry;
    /**
     * Retry with exponential backoff
     */
    private retryWithBackoff;
    /**
     * Get provider instance (protected for subclasses)
     */
    protected getProvider(): any;
    /**
     * Execute a pipeline
     */
    pipeline(pipeline: any, variables?: Record<string, any>): Promise<any>;
    /**
     * Access template system
     */
    get templates(): TemplateSystem;
    /**
     * Access tool system
     */
    get tools(): ToolSystem;
    /**
     * Access response transformer
     */
    get transformers(): ResponseTransformer;
    /**
     * Access pipeline system
     */
    get pipelines(): PipelineSystem;
    /**
     * Access conversation manager
     */
    get conversationManager(): ConversationManager;
}

interface FileInput {
    path?: string;
    buffer?: Buffer;
    url?: string;
    mimeType?: string;
}

interface ImageSize {
    width: number;
    height: number;
}
interface ImageGenerationRequest {
    prompt: string;
    negativePrompt?: string;
    size?: string | ImageSize;
    quality?: "standard" | "hd" | "ultra";
    style?: "natural" | "vivid" | "artistic" | "photographic";
    model?: string;
    n?: number;
    seed?: number;
}
interface ImageEditRequest {
    image: string | Buffer | FileInput;
    mask?: string | Buffer | FileInput;
    prompt: string;
    size?: string | ImageSize;
    n?: number;
}
interface ImageVariationRequest {
    image: string | Buffer | FileInput;
    n?: number;
    size?: string | ImageSize;
}

/**
 * Image generation and manipulation utilities
 */

declare class ImageHelpers {
    /**
     * Standard image sizes across providers
     */
    static readonly STANDARD_SIZES: Record<string, ImageSize>;
    /**
     * Image generation models
     */
    static readonly IMAGE_MODELS: Record<string, string>;
    /**
     * Parse size string to dimensions
     */
    static parseSize(size: string | ImageSize): ImageSize;
    /**
     * Format size for provider
     */
    static formatSize(size: ImageSize, provider: string): string;
    /**
     * Build OpenAI image generation request
     */
    static buildOpenAIImageRequest(request: ImageGenerationRequest): any;
    /**
     * Build OpenAI image edit request
     */
    static buildOpenAIImageEditRequest(request: ImageEditRequest): Promise<FormData>;
    /**
     * Build Google Imagen request
     */
    static buildGoogleImageRequest(request: ImageGenerationRequest): any;
    /**
     * Enhance prompt for better generation
     */
    static enhancePrompt(prompt: string, style?: ImageGenerationRequest["style"]): string;
    /**
     * Validate image for editing
     */
    static validateImageForEdit(image: string | Buffer | FileInput, maxSizeMB?: number): Promise<{
        valid: boolean;
        error?: string;
    }>;
    /**
     * Convert response to image URLs
     */
    static extractImageUrls(response: any, provider: string): string[];
    /**
     * Calculate generation cost
     */
    static calculateCost(model: string, quality: string, count?: number): number;
}

/**
 * Image API implementations for all providers
 */

declare class ImageAPI {
    private client;
    constructor(client: UnifiedClientEnhanced);
    /**
     * Safely extract error message from unknown error types
     */
    private getErrorMessage;
    /**
     * Generate images from text prompt
     */
    generate(prompt: string, options?: Partial<ImageGenerationRequest>): Promise<string[]>;
    /**
     * Edit an existing image with a prompt
     */
    edit(image: string | Buffer, prompt: string, options?: Partial<ImageEditRequest>): Promise<string[]>;
    /**
     * Create variations of an image
     */
    variations(image: string | Buffer, options?: Partial<ImageVariationRequest>): Promise<string[]>;
    /**
     * Read/analyze an image
     */
    analyze(image: string | Buffer, prompt?: string): Promise<string>;
    /**
     * OpenAI DALL-E implementation
     */
    private generateOpenAI;
    /**
     * OpenAI image edit implementation
     */
    private editOpenAI;
    /**
     * OpenAI image variations implementation
     */
    private variationsOpenAI;
    /**
     * Google Imagen implementation
     */
    private generateGoogle;
    /**
     * Upscale an image
     */
    upscale(image: string | Buffer, scale?: number): Promise<string>;
    /**
     * Remove background from image
     */
    removeBackground(image: string | Buffer): Promise<string>;
}

declare class UnifiedClientEnhanced extends UnifiedClient {
    image: ImageAPI;
    video: VideoAPI;
    audio: AudioAPI;
    file: FileAPI;
    constructor(config: ClientConfig);
    getProvider(): any;
    get clientConfig(): ClientConfig;
    getConversation(): {
        add: (role: "user" | "assistant" | "system", content: string) => Message;
        clear: () => number;
        history: Message[];
        stats: {
            total: number;
            userMessages: number;
            assistantMessages: number;
            systemMessages: number;
            toolMessages: number;
            averageMessageLength: number;
        };
        export: () => string;
        import: (json: string) => void;
        manager: ConversationManager;
    };
    /**
     * Override chat method to match base class signature
     */
    chat(pr