@varia-bly/variably-sdk/dist/llm-client.d.ts

Official JavaScript/TypeScript SDK for Variably feature flags, experimentation, LLM experiments with React hooks, and real-time dynamic configurations

/**
 * Variably LLM Client - Main implementation for LLM features
 */
import { EventEmitter } from 'events';
import { LLMConfig, PromptExecutionRequest, PromptExecutionResponse, ResponseEvaluationRequest, ResponseEvaluationResponse, StreamingOptions, ConversationContext, BatchPromptRequest, BatchPromptResponse, LLMCacheConfig, LLMSDKMetrics, ExportFormat, ExportResult, ConversationMessage } from './llm-types';
import { Logger } from './logger';
interface LLMClientConfig {
    apiKey: string;
    baseUrl?: string;
    llmConfig?: Partial<LLMConfig>;
    cacheConfig?: LLMCacheConfig;
    timeout?: number;
    retryAttempts?: number;
    enableMetrics?: boolean;
    logger?: Logger;
}
export declare class VariablyLLMClient extends EventEmitter {
    private config;
    private graphqlClient;
    private logger;
    private cache;
    private metricsCollector;
    private conversationContexts;
    private activeStreams;
    private sdkMetrics;
    constructor(config: LLMClientConfig);
    /**
     * Execute a prompt experiment with automatic variant selection and evaluation tracking
     * RECOMMENDED: Use this method for prompt experiments as it properly saves evaluation data
     *
     * This method uses the backend's evaluation endpoint which:
     * 1. Selects an experiment variant
     * 2. Executes the LLM prompt
     * 3. Saves evaluation data to the database
     *
     * @param experimentKey - The unique key for the experiment (not ID)
     * @param request - The execution request with user context and variables
     */
    executePromptExperiment(experimentKey: string, request: Omit<PromptExecutionRequest, 'experimentId'>): Promise<PromptExecutionResponse>;
    /**
     * Execute a prompt experiment with automatic variant selection (LEGACY)
     *
     * NOTE: This method does NOT save evaluation data to the database.
     * Use executePromptExperiment() instead for proper evaluation tracking.
     */
    executeLLMPrompt(request: PromptExecutionRequest): Promise<PromptExecutionResponse>;
    /**
     * Evaluate a response against specified criteria
     */
    evaluateResponse(request: ResponseEvaluationRequest): Promise<ResponseEvaluationResponse>;
    /**
     * Track a success metric for an LLM prompt experiment
     * Use this to track business outcomes (conversions, user satisfaction, etc.)
     *
     * @param params - The tracking parameters
     * @param params.experimentId - The experiment ID (from executePromptExperiment response)
     * @param params.metricName - Human-readable metric name (e.g., "conversion", "user_satisfaction")
     * @param params.metricKey - Unique metric key for aggregation
     * @param params.userId - The user ID who triggered the outcome
     * @param params.sessionId - Optional session ID (recommended - from executePromptExperiment response)
     * @param params.variantId - The variant UUID (from executePromptExperiment response)
     * @param params.variantKey - Alternative: variant name/key (if variantId not available)
     * @param params.value - Optional numeric value for the metric (default: 1.0)
     * @param params.metadata - Optional additional metadata
     */
    trackSuccessMetric(params: {
        experimentId: string;
        metricName: string;
        metricKey: string;
        userId: string;
        sessionId?: string;
        variantId?: string;
        variantKey?: string;
        value?: number;
        metadata?: Record<string, any>;
    }): Promise<void>;
    /**
     * Execute prompts with streaming support
     */
    executeLLMPromptStreaming(request: PromptExecutionRequest, options: StreamingOptions): Promise<void>;
    /**
     * Execute multiple prompts in batch
     */
    executeBatchPrompts(request: BatchPromptRequest): Promise<BatchPromptResponse>;
    /**
     * Manage conversation context
     */
    addToConversation(sessionId: string, message: ConversationMessage): void;
    getConversationContext(sessionId: string): ConversationContext | undefined;
    clearConversation(sessionId: string): void;
    /**
     * Export execution history
     */
    exportHistory(format: ExportFormat, filter?: any): Promise<ExportResult>;
    /**
     * Get SDK metrics
     */
    getMetrics(): LLMSDKMetrics;
    /**
     * Clear cache
     */
    clearCache(): void;
    private initializeEventHandlers;
    private generateExecutionId;
    private generateCacheKey;
    private checkCache;
    private cacheResponse;
    private createResponseFromCache;
    private getPromptVariant;
    /**
     * Production-grade variant selection using consistent hashing.
     *
     * Algorithm:
     * 1. Generate a deterministic hash bucket (0-9999) for the user+experiment
     * 2. Check if user falls within overall traffic allocation
     * 3. Distribute traffic across variants based on their weights
     *
     * This ensures:
     * - Same user always gets same variant (consistency)
     * - Traffic is distributed according to configured weights
     * - No bias in variant assignment
     */
    private selectVariantByTrafficAllocation;
    /**
     * Hash function for consistent bucketing.
     * Uses MurmurHash3-inspired algorithm for good distribution.
     *
     * @returns Integer in range [0, maxBucket)
     */
    private hashToBucket;
    private compilePrompt;
    private buildConversationContext;
    private executeWithProvider;
    private callProvider;
    private streamFromProvider;
    private evaluateResponseInternal;
    private evaluateDimension;
    private evaluateCustomRules;
    private compareOutputs;
    private generateImprovementRecommendations;
    private trackExecutionMetrics;
    private updateSDKMetrics;
    private updateCacheMetrics;
    private createLLMError;
    private handleExecutionError;
    private classifyError;
    private chunkArray;
}
export {};
//# sourceMappingURL=llm-client.d.ts.map