@matthew.ngo/ai-toolkit
Version:
A comprehensive AI toolkit with multi-provider support
852 lines (840 loc) • 23.1 kB
TypeScript
import { A as AIConfig, G as GenerateOptions, C as Classification, S as SummarizeOptions, I as ImageGenerationOptions, a as ImageResult, T as TranscriptionOptions, b as TranscriptionResult, c as SpeechOptions, d as CodeGenerationOptions, e as CodeResult, f as AIProviderType, g as CacheConfig, R as RateLimitConfig, h as RetryConfig, i as AIUsageStats, P as ProviderStats } from './index-CX4Gj53G.js';
export { p as AIConfigSchema, U as AIProvider, s as AIResponse, k as AnthropicProvider, u as AspectSentiment, B as BaseProvider, z as BoundingBox, n as CacheConfigSchema, J as ChatMessage, L as ChatOptions, y as ColorInfo, x as DetectedFace, D as DetectedObject, Q as ErrorStats, E as ExtractedText, K as FunctionCall, F as FunctionDefinition, l as GoogleProvider, w as ImageAnalysis, v as ImageAnalysisOptions, M as MockProvider, N as ModelStats, O as OpenAIProvider, j as ProviderConfig, m as RateLimitConfigSchema, q as ResponseFormat, o as RetryConfigSchema, t as SentimentAnalysis, H as SpeakerSegment, r as TokenUsage, W as WordTimestamp } from './index-CX4Gj53G.js';
import Boom from '@hapi/boom';
import Bottleneck from 'bottleneck';
import 'zod';
interface AIEngineOptions extends Partial<AIConfig> {
debug?: boolean;
}
declare class AIEngine {
private config;
private providers;
private cache;
private rateLimiter;
private retryManager;
private tokenManager;
private errorHandler;
private performanceMonitor;
private analytics;
private debug;
constructor(options: AIEngineOptions);
/**
* Initialize providers based on configuration
*/
private initializeProviders;
/**
* Create a provider instance
*/
private createProvider;
/**
* Setup rate limiters for each provider
*/
private setupRateLimiters;
/**
* Get provider with fallback support
*/
private getProvider;
/**
* Execute operation with full pipeline
*/
private executeOperation;
/**
* Generate text completion
*/
generateText(prompt: string, options?: GenerateOptions): Promise<string>;
/**
* Generate streaming text completion
*/
generateStream(prompt: string, options?: GenerateOptions): AsyncGenerator<string>;
/**
* Generate embeddings
*/
generateEmbedding(text: string): Promise<number[]>;
/**
* Classify text
*/
classifyText(text: string, labels: string[]): Promise<Classification>;
/**
* Summarize text
*/
summarize(text: string, options?: SummarizeOptions): Promise<string>;
/**
* Generate image
*/
generateImage(prompt: string, options?: ImageGenerationOptions): Promise<ImageResult>;
/**
* Transcribe audio
*/
transcribeAudio(audio: Blob, options?: TranscriptionOptions): Promise<TranscriptionResult>;
/**
* Generate speech
*/
generateSpeech(text: string, options?: SpeechOptions): Promise<Blob>;
/**
* Generate code
*/
generateCode(prompt: string, options?: CodeGenerationOptions): Promise<CodeResult>;
/**
* Update configuration
*/
updateConfig(config: Partial<AIConfig>): Promise<void>;
/**
* Get current statistics
*/
getStats(): any;
/**
* Clear all caches and reset statistics
*/
reset(): Promise<void>;
/**
* Log debug information
*/
private log;
/**
* Export configuration
*/
exportConfig(): Record<string, any>;
/**
* Get available providers
*/
getAvailableProviders(): AIProviderType[];
}
interface CacheOptions extends CacheConfig {
namespace?: string;
}
declare class CacheManager {
private cache;
private enabled;
private namespace;
private stats;
constructor(options: CacheOptions);
/**
* Generate cache key from request parameters
*/
generateKey(method: string, params: any[], options?: Record<string, any>): string;
/**
* Get value from cache
*/
get<T = any>(key: string): Promise<T | null>;
/**
* Set value in cache
*/
set<T = any>(key: string, value: T, metadata?: Record<string, any>): Promise<void>;
/**
* Delete from cache
*/
delete(key: string): Promise<boolean>;
/**
* Clear all cache entries
*/
clear(): Promise<void>;
/**
* Check if key exists in cache
*/
has(key: string): boolean;
/**
* Get cache statistics
*/
getStats(): {
hitRate: number;
size: number;
calculatedSize: number;
maxSize: number;
itemCount: number;
enabled: boolean;
hits: number;
misses: number;
evictions: number;
};
/**
* Get all cache keys
*/
keys(): string[];
/**
* Get cache entries with metadata
*/
entries(): Array<{
key: string;
metadata?: Record<string, any>;
age: number;
}>;
/**
* Prune old entries
*/
prune(): number;
/**
* Enable or disable cache
*/
setEnabled(enabled: boolean): void;
/**
* Update TTL for all entries
*/
updateTTL(ttl: number): void;
/**
* Get memory usage info
*/
getMemoryUsage(): {
used: number;
max: number;
percentage: number;
};
/**
* Setup periodic cleanup
*/
private setupCleanup;
/**
* Cache wrapper for async functions
*/
wrap<T>(key: string, fn: () => Promise<T>, options?: {
ttl?: number;
metadata?: Record<string, any>;
}): Promise<T>;
/**
* Create a cache key for text generation
*/
createTextGenerationKey(prompt: string, options?: GenerateOptions, provider?: string, model?: string): string;
/**
* Create a cache key for embeddings
*/
createEmbeddingKey(text: string, provider?: string, model?: string): string;
/**
* Export cache contents
*/
export(): Record<string, any>;
/**
* Import cache contents
*/
import(data: Record<string, any>): void;
}
declare class ConfigManager {
private config;
private encryptedKeys;
constructor(config: Partial<AIConfig>);
getConfig(): AIConfig;
getProviderConfig(provider?: AIProviderType): {
provider: AIProviderType;
apiKey: string | undefined;
model: string | undefined;
baseUrl: string | undefined;
headers: Record<string, string> | undefined;
};
getApiKey(provider?: AIProviderType): string | undefined;
getModel(provider?: AIProviderType): string | undefined;
getCacheConfig(): {
strategy: "lru" | "fifo" | "lfu";
enabled: boolean;
ttl: number;
maxSize: number;
};
getRateLimitConfig(): {
concurrent: number;
strategy: "fixed-window" | "sliding-window" | "token-bucket";
requestsPerMinute?: number | undefined;
tokensPerMinute?: number | undefined;
requestsPerHour?: number | undefined;
tokensPerHour?: number | undefined;
};
getRetryConfig(): {
maxAttempts: number;
baseDelay: number;
maxDelay: number;
backoff: "exponential" | "linear" | "fixed";
};
getFallbackProviders(): AIProviderType[];
updateConfig(updates: Partial<AIConfig>): void;
private encryptApiKey;
private decryptApiKey;
validateProvider(provider: AIProviderType): {
valid: boolean;
errors: string[];
};
exportConfig(): Record<string, any>;
}
interface ErrorContext {
provider: string;
operation: string;
model?: string;
attempt?: number;
metadata?: Record<string, any>;
}
interface EnhancedError extends Error {
code?: string;
status?: number;
category?: string;
userMessage?: string;
isRetryable?: boolean;
context?: ErrorContext;
recommendations?: string[];
timestamp?: string;
}
declare class ErrorHandler {
private errorHistory;
private maxHistorySize;
/**
* Handle and enhance error
*/
handleError(error: any, context: ErrorContext): EnhancedError;
/**
* Enhance error with additional information
*/
private enhanceError;
/**
* Get error name based on category
*/
private getErrorName;
/**
* Get formatted error message
*/
private getErrorMessage;
/**
* Categorize error
*/
private categorizeError;
/**
* Infer error code
*/
private inferErrorCode;
/**
* Infer HTTP status code
*/
private inferStatusCode;
/**
* Get user-friendly error message
*/
private getUserFriendlyMessage;
/**
* Determine if error is retryable
*/
private isRetryable;
/**
* Get recommendations for resolving the error
*/
private getRecommendations;
/**
* Add error to history
*/
private addToHistory;
/**
* Create HTTP-friendly error using Boom
*/
createHttpError(error: EnhancedError): Boom.Boom;
/**
* Get error statistics
*/
getErrorStats(timeWindow?: number): {
total: number;
byCategory: Record<string, number>;
byProvider: Record<string, number>;
resolutionRate: number;
recentErrors: Array<{
timestamp: string;
category: string;
provider: string;
message: string;
}>;
};
/**
* Mark error as resolved
*/
markResolved(errorId: string): void;
/**
* Clear error history
*/
clearHistory(): void;
/**
* Export error history
*/
exportHistory(): Array<{
timestamp: string;
error: any;
context: ErrorContext;
resolved: boolean;
}>;
}
interface RateLimiterOptions extends RateLimitConfig {
id: string;
}
interface LimiterStats {
running: number;
queued: number;
done: number;
failed: number;
reservoir?: number | null;
}
declare class RateLimiter {
private limiters;
private tokenBuckets;
/**
* Create or get a rate limiter for a specific provider/key
*/
createLimiter(options: RateLimiterOptions): Bottleneck;
/**
* Get limiter by ID
*/
getLimiter(id: string): Bottleneck | undefined;
/**
* Schedule a job with rate limiting
*/
schedule<T>(limiterId: string, fn: () => Promise<T>, priority?: number): Promise<T>;
/**
* Check and consume tokens
*/
consumeTokens(limiterId: string, tokens: number): Promise<boolean>;
/**
* Get statistics for a limiter
*/
getStats(limiterId: string): Promise<LimiterStats | null>;
/**
* Get all limiter statistics
*/
getAllStats(): Promise<Record<string, LimiterStats>>;
/**
* Update limiter configuration
*/
updateLimiter(id: string, newConfig: Partial<RateLimiterOptions>): Promise<void>;
/**
* Clear queued jobs for a limiter
*/
clearQueue(limiterId: string): Promise<void>;
/**
* Stop a limiter
*/
stopLimiter(limiterId: string): Promise<void>;
/**
* Stop all limiters
*/
stopAll(): Promise<void>;
/**
* Create sliding window configuration
*/
private createSlidingWindowConfig;
/**
* Create fixed window configuration
*/
private createFixedWindowConfig;
/**
* Create token bucket configuration
*/
private createTokenBucketConfig;
/**
* Create token bucket for token-based rate limiting
*/
private createTokenBucket;
/**
* Get limiter configuration (mock implementation)
*/
private getLimiterConfig;
}
interface RetryContext {
provider: string;
operation: string;
model?: string;
metadata?: Record<string, any>;
}
interface RetryOptions extends RetryConfig {
onRetry?: (error: Error, attempt: number) => void;
shouldRetry?: (error: any) => boolean;
}
declare class RetryManager {
private config;
constructor(config: RetryConfig);
/**
* Execute operation with retry logic
*/
execute<T>(operation: () => Promise<T>, context: RetryContext, options?: Partial<RetryOptions>): Promise<T>;
/**
* Execute with custom exponential backoff
*/
executeWithBackoff<T>(operation: () => Promise<T>, context: RetryContext, options?: Partial<RetryOptions>): Promise<T>;
/**
* Wrap error with context information
*/
private wrapError;
/**
* Determine if error should trigger retry
*/
private shouldRetry;
/**
* Categorize error type
*/
private categorizeError;
/**
* Create a retry wrapper for a function
*/
wrap<T extends (...args: any[]) => Promise<any>>(fn: T, context: RetryContext, options?: Partial<RetryOptions>): T;
/**
* Update configuration
*/
updateConfig(config: Partial<RetryConfig>): void;
/**
* Get current configuration
*/
getConfig(): RetryConfig;
/**
* Calculate delay for next retry
*/
calculateDelay(attempt: number, options?: Partial<RetryOptions>): number;
/**
* Get retry statistics
*/
getRetryStats(error: any): {
shouldRetry: boolean;
errorType: string;
suggestedDelay: number;
maxAttempts: number;
};
}
interface TokenInfo {
count: number;
truncated: boolean;
originalLength?: number;
}
interface ModelTokenLimits {
[model: string]: number;
}
declare class TokenManager {
private tokenLimits;
private modelPricing;
/**
* Count tokens in text for a specific model
*/
countTokens(text: string, model: string): Promise<number>;
/**
* Count tokens using tiktoken
*/
private countTokensWithTiktoken;
/**
* Estimate tokens based on character count
*/
private estimateTokens;
/**
* Get token information for text
*/
getTokenInfo(text: string, model: string, maxTokens?: number): Promise<TokenInfo>;
/**
* Validate if text fits within token limits
*/
validateTokenLimits(text: string, model: string, maxTokens?: number, responseTokens?: number): Promise<{
valid: boolean;
availableTokens: number;
}>;
/**
* Truncate text to fit within token limit
*/
truncateToTokenLimit(text: string, model: string, maxTokens: number, preserveEnd?: boolean): Promise<string>;
/**
* Split text into chunks that fit within token limits
*/
splitIntoChunks(text: string, model: string, chunkSize: number, overlap?: number): Promise<string[]>;
/**
* Split text into sentences
*/
private splitIntoSentences;
/**
* Get overlap text for chunking
*/
private getOverlapText;
/**
* Estimate cost for tokens
*/
estimateCost(tokens: number, model: string, type?: "input" | "output"): number;
/**
* Get model token limit
*/
getModelTokenLimit(model: string): number;
/**
* Get all model limits
*/
getAllModelLimits(): ModelTokenLimits;
/**
* Estimate tokens for a conversation
*/
estimateConversationTokens(messages: Array<{
role: string;
content: string;
}>, model: string): Promise<number>;
}
interface AnalyticsEvent {
timestamp: Date;
type: "request" | "success" | "error" | "cache_hit" | "rate_limit";
provider: string;
operation: string;
model?: string;
tokens?: {
prompt: number;
completion: number;
total: number;
};
cost?: number;
latency?: number;
error?: string;
metadata?: Record<string, any>;
}
interface UsageTrend {
timestamp: string;
requests: number;
tokens: number;
cost: number;
errors: number;
}
declare class Analytics {
private events;
private maxEvents;
private stats;
/**
* Track an analytics event
*/
trackEvent(event: Omit<AnalyticsEvent, "timestamp">): void;
/**
* Update statistics based on event
*/
private updateStats;
/**
* Calculate error rate for a provider
*/
private calculateErrorRate;
/**
* Update error statistics
*/
private updateErrorStats;
/**
* Get current usage statistics
*/
getStats(): AIUsageStats;
/**
* Get usage trends over time
*/
getTrends(interval?: "hour" | "day" | "week" | "month", limit?: number): UsageTrend[];
/**
* Get top operations by usage
*/
getTopOperations(limit?: number): Array<{
operation: string;
count: number;
percentage: number;
}>;
/**
* Get cost breakdown
*/
getCostBreakdown(): {
total: number;
byProvider: Record<string, number>;
byModel: Record<string, number>;
byOperation: Record<string, number>;
};
/**
* Get provider comparison
*/
getProviderComparison(): Array<{
provider: string;
stats: ProviderStats;
rank: {
speed: number;
reliability: number;
cost: number;
overall: number;
};
}>;
/**
* Get recommendations based on usage
*/
getRecommendations(): string[];
/**
* Reset statistics
*/
reset(): void;
/**
* Export analytics data
*/
exportData(): {
stats: AIUsageStats;
trends: UsageTrend[];
topOperations: ReturnType<any>;
costBreakdown: ReturnType<any>;
providerComparison: ReturnType<any>;
recommendations: string[];
};
}
interface PerformanceMetrics {
operationId: string;
operation: string;
provider: string;
startTime: number;
endTime?: number;
duration?: number;
success: boolean;
error?: string;
metadata?: Record<string, any>;
}
interface PerformanceReport {
operationId: string;
operation: string;
provider: string;
duration: number;
success: boolean;
error?: string;
timestamp: string;
}
interface PerformanceStats {
averageLatency: number;
minLatency: number;
maxLatency: number;
successRate: number;
errorRate: number;
throughput: number;
percentiles: {
p50: number;
p90: number;
p95: number;
p99: number;
};
}
declare class PerformanceMonitor {
private metrics;
private history;
private maxHistorySize;
private windowSize;
/**
* Start monitoring an operation
*/
startOperation(operationId: string, operation: string, provider: string, metadata?: Record<string, any>): void;
/**
* End monitoring an operation
*/
endOperation(operationId: string, success?: boolean, error?: string): PerformanceReport | null;
/**
* Get performance statistics
*/
getStats(filters?: {
provider?: string;
operation?: string;
timeWindow?: number;
}): PerformanceStats;
/**
* Get performance by provider
*/
getStatsByProvider(): Record<string, PerformanceStats>;
/**
* Get performance by operation
*/
getStatsByOperation(): Record<string, PerformanceStats>;
/**
* Get performance trends
*/
getTrends(interval?: "minute" | "hour" | "day", limit?: number): Array<{
timestamp: string;
stats: PerformanceStats;
}>;
/**
* Get error analysis
*/
getErrorAnalysis(): {
totalErrors: number;
errorsByType: Record<string, number>;
errorsByProvider: Record<string, number>;
commonErrors: Array<{
error: string;
count: number;
}>;
};
/**
* Get slow operations
*/
getSlowOperations(threshold?: number): PerformanceReport[];
/**
* Calculate percentile
*/
private getPercentile;
/**
* Clear history
*/
clearHistory(): void;
/**
* Export performance data
*/
exportData(): {
history: PerformanceReport[];
stats: PerformanceStats;
statsByProvider: Record<string, PerformanceStats>;
statsByOperation: Record<string, PerformanceStats>;
errorAnalysis: ReturnType<PerformanceMonitor["getErrorAnalysis"]>;
};
/**
* Get active operations
*/
getActiveOperations(): PerformanceMetrics[];
/**
* Check health status
*/
getHealthStatus(): {
status: "healthy" | "degraded" | "unhealthy";
issues: string[];
};
}
declare const AIPresets: {
readonly development: {
readonly provider: "mock";
readonly cache: {
readonly enabled: true;
readonly ttl: 600000;
readonly maxSize: 100;
readonly strategy: "lru";
};
readonly debug: true;
};
readonly production: {
readonly provider: "openai";
readonly model: "gpt-3.5-turbo";
readonly cache: {
readonly enabled: true;
readonly ttl: 3600000;
readonly maxSize: 500;
readonly strategy: "lru";
};
readonly rateLimit: {
readonly requestsPerMinute: 60;
readonly concurrent: 5;
readonly strategy: "sliding-window";
};
readonly retry: {
readonly maxAttempts: 3;
readonly baseDelay: 1000;
readonly maxDelay: 30000;
readonly backoff: "exponential";
};
};
readonly highPerformance: {
readonly provider: "openai";
readonly model: "gpt-3.5-turbo";
readonly cache: {
readonly enabled: true;
readonly ttl: 7200000;
readonly maxSize: 1000;
readonly strategy: "lru";
};
readonly rateLimit: {
readonly requestsPerMinute: 100;
readonly concurrent: 10;
readonly strategy: "token-bucket";
};
readonly fallbackProviders: readonly ["anthropic", "google"];
};
readonly costOptimized: {
readonly provider: "openai";
readonly model: "gpt-3.5-turbo";
readonly cache: {
readonly enabled: true;
readonly ttl: 86400000;
readonly maxSize: 200;
readonly strategy: "lfu";
};
readonly rateLimit: {
readonly requestsPerMinute: 30;
readonly concurrent: 5;
readonly strategy: "fixed-window";
};
};
};
declare function createAI(config?: Partial<AIConfig>): Promise<AIEngine>;
declare const VERSION = "1.0.0";
export { AIConfig, AIEngine, AIPresets, AIProviderType, AIUsageStats, Analytics, CacheConfig, CacheManager, Classification, CodeGenerationOptions, CodeResult, ConfigManager, type EnhancedError, ErrorHandler, GenerateOptions, ImageGenerationOptions, ImageResult, PerformanceMonitor, ProviderStats, RateLimitConfig, RateLimiter, RetryConfig, RetryManager, SpeechOptions, SummarizeOptions, TokenManager, TranscriptionOptions, TranscriptionResult, VERSION, createAI };