@agentic-qe/v3 3.0.0-alpha.6 → 3.0.0-alpha.8

package/src/shared/llm/interfaces.ts

@@ -1,629 +0,0 @@
-/**
- * Agentic QE v3 - LLM Provider Interfaces
- * ADR-011: LLM Provider System for Quality Engineering
- *
- * Defines core interfaces for multi-provider LLM support with:
- * - Provider abstraction for Claude, OpenAI, and Ollama
- * - Cost tracking and token management
- * - Circuit breaker support for resilience
- * - Response caching
- */
-
-// ============================================================================
-// Core Types
-// ============================================================================
-
-/**
- * Supported LLM provider types
- */
-export type LLMProviderType = 'claude' | 'openai' | 'ollama';
-
-/**
- * Message role in a conversation
- */
-export type MessageRole = 'system' | 'user' | 'assistant';
-
-/**
- * A single message in a conversation
- */
-export interface Message {
-  role: MessageRole;
-  content: string;
-}
-
-/**
- * Token usage information
- */
-export interface TokenUsage {
-  promptTokens: number;
-  completionTokens: number;
-  totalTokens: number;
-}
-
-/**
- * Cost information for a request
- */
-export interface CostInfo {
-  inputCost: number;
-  outputCost: number;
-  totalCost: number;
-  currency: 'USD';
-}
-
-// ============================================================================
-// Response Types
-// ============================================================================
-
-/**
- * LLM generation response
- */
-export interface LLMResponse {
-  /** Generated text content */
-  content: string;
-  /** Model used for generation */
-  model: string;
-  /** Provider that generated the response */
-  provider: LLMProviderType;
-  /** Token usage statistics */
-  usage: TokenUsage;
-  /** Cost of this request */
-  cost: CostInfo;
-  /** Response generation time in ms */
-  latencyMs: number;
-  /** Finish reason from the model */
-  finishReason: 'stop' | 'length' | 'content_filter' | 'error';
-  /** Whether response was served from cache */
-  cached: boolean;
-  /** Request ID for tracing */
-  requestId: string;
-}
-
-/**
- * Embedding response
- */
-export interface EmbeddingResponse {
-  /** Embedding vector */
-  embedding: number[];
-  /** Model used */
-  model: string;
-  /** Provider that generated the embedding */
-  provider: LLMProviderType;
-  /** Token count for input */
-  tokenCount: number;
-  /** Generation time in ms */
-  latencyMs: number;
-  /** Whether response was served from cache */
-  cached: boolean;
-}
-
-/**
- * Completion response (for code completion use cases)
- */
-export interface CompletionResponse {
-  /** Completed text */
-  completion: string;
-  /** Model used */
-  model: string;
-  /** Provider that generated the completion */
-  provider: LLMProviderType;
-  /** Token usage */
-  usage: TokenUsage;
-  /** Generation time in ms */
-  latencyMs: number;
-  /** Whether response was served from cache */
-  cached: boolean;
-}
-
-// ============================================================================
-// Configuration Types
-// ============================================================================
-
-/**
- * Base LLM configuration
- */
-export interface LLMConfig {
-  /** API key for authentication */
-  apiKey?: string;
-  /** Base URL for API calls (for self-hosted or proxied setups) */
-  baseUrl?: string;
-  /** Default model to use */
-  model: string;
-  /** Maximum tokens to generate */
-  maxTokens?: number;
-  /** Temperature for generation (0-2) */
-  temperature?: number;
-  /** Top-p sampling parameter */
-  topP?: number;
-  /** Request timeout in ms */
-  timeoutMs?: number;
-  /** Number of retries on failure */
-  maxRetries?: number;
-  /** Enable response caching */
-  enableCache?: boolean;
-  /** Enable circuit breaker */
-  enableCircuitBreaker?: boolean;
-}
-
-/**
- * Claude-specific configuration
- */
-export interface ClaudeConfig extends LLMConfig {
-  /** Claude model version */
-  model:
-    | 'claude-opus-4-5-20251101'
-    | 'claude-sonnet-4-20250514'
-    | 'claude-3-5-haiku-20241022'
-    | string;
-  /** Anthropic API version */
-  anthropicVersion?: string;
-  /** Maximum thinking tokens for extended thinking */
-  maxThinkingTokens?: number;
-}
-
-/**
- * OpenAI-specific configuration
- */
-export interface OpenAIConfig extends LLMConfig {
-  /** OpenAI model */
-  model: 'gpt-4o' | 'gpt-4o-mini' | 'gpt-4-turbo' | 'gpt-3.5-turbo' | string;
-  /** Organization ID */
-  organization?: string;
-  /** Presence penalty (-2 to 2) */
-  presencePenalty?: number;
-  /** Frequency penalty (-2 to 2) */
-  frequencyPenalty?: number;
-}
-
-/**
- * Ollama-specific configuration
- */
-export interface OllamaConfig extends LLMConfig {
-  /** Local model name */
-  model: string;
-  /** Ollama server URL */
-  baseUrl?: string;
-  /** Context window size */
-  contextLength?: number;
-  /** Number of GPU layers to use */
-  numGpu?: number;
-  /** Keep model loaded in memory */
-  keepAlive?: string;
-}
-
-/**
- * Provider manager configuration
- */
-export interface ProviderManagerConfig {
-  /** Primary provider to use */
-  primary: LLMProviderType;
-  /** Fallback providers in order of preference */
-  fallbacks: LLMProviderType[];
-  /** Load balancing strategy */
-  loadBalancing: 'round-robin' | 'least-cost' | 'least-latency' | 'random';
-  /** Provider-specific configurations */
-  providers: {
-    claude?: ClaudeConfig;
-    openai?: OpenAIConfig;
-    ollama?: OllamaConfig;
-  };
-  /** Global settings */
-  global?: {
-    /** Max total cost per hour in USD */
-    maxCostPerHour?: number;
-    /** Max total cost per day in USD */
-    maxCostPerDay?: number;
-    /** Enable cost tracking */
-    enableCostTracking?: boolean;
-    /** Enable metrics collection */
-    enableMetrics?: boolean;
-  };
-}
-
-// ============================================================================
-// Request Types
-// ============================================================================
-
-/**
- * Generation request options
- */
-export interface GenerateOptions {
-  /** Override default model */
-  model?: string;
-  /** Override temperature */
-  temperature?: number;
-  /** Override max tokens */
-  maxTokens?: number;
-  /** System prompt */
-  systemPrompt?: string;
-  /** Stop sequences */
-  stopSequences?: string[];
-  /** Request timeout in ms */
-  timeoutMs?: number;
-  /** Force skip cache */
-  skipCache?: boolean;
-  /** Force specific provider */
-  preferredProvider?: LLMProviderType;
-  /** User identifier for tracking */
-  userId?: string;
-  /** Request metadata */
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Embedding request options
- */
-export interface EmbedOptions {
-  /** Override default model */
-  model?: string;
-  /** Request timeout in ms */
-  timeoutMs?: number;
-  /** Force skip cache */
-  skipCache?: boolean;
-}
-
-/**
- * Completion request options (for code completion)
- */
-export interface CompleteOptions {
-  /** Override default model */
-  model?: string;
-  /** Override temperature (usually low for code) */
-  temperature?: number;
-  /** Maximum tokens to generate */
-  maxTokens?: number;
-  /** Stop sequences (e.g., newlines for single-line completion) */
-  stopSequences?: string[];
-  /** Force skip cache */
-  skipCache?: boolean;
-}
-
-// ============================================================================
-// Provider Interface
-// ============================================================================
-
-/**
- * Abstract LLM provider interface
- * Implementations: ClaudeProvider, OpenAIProvider, OllamaProvider
- */
-export interface LLMProvider {
-  /** Provider type identifier */
-  readonly type: LLMProviderType;
-
-  /** Provider display name */
-  readonly name: string;
-
-  /** Check if provider is available and configured */
-  isAvailable(): Promise<boolean>;
-
-  /** Health check with latency measurement */
-  healthCheck(): Promise<HealthCheckResult>;
-
-  /**
-   * Generate text from a prompt or messages
-   * @param input - String prompt or array of messages
-   * @param options - Generation options
-   */
-  generate(
-    input: string | Message[],
-    options?: GenerateOptions
-  ): Promise<LLMResponse>;
-
-  /**
-   * Generate embedding for text
-   * @param text - Input text to embed
-   * @param options - Embedding options
-   */
-  embed(text: string, options?: EmbedOptions): Promise<EmbeddingResponse>;
-
-  /**
-   * Complete a partial text (code completion style)
-   * @param prompt - Partial text to complete
-   * @param options - Completion options
-   */
-  complete(
-    prompt: string,
-    options?: CompleteOptions
-  ): Promise<CompletionResponse>;
-
-  /** Get current provider configuration */
-  getConfig(): LLMConfig;
-
-  /** Get supported models */
-  getSupportedModels(): string[];
-
-  /** Get cost per token for current model */
-  getCostPerToken(): { input: number; output: number };
-
-  /** Dispose provider resources */
-  dispose(): Promise<void>;
-}
-
-/**
- * Health check result
- */
-export interface HealthCheckResult {
-  /** Whether provider is healthy */
-  healthy: boolean;
-  /** Latency in ms (if healthy) */
-  latencyMs?: number;
-  /** Error message (if unhealthy) */
-  error?: string;
-  /** Available models */
-  models?: string[];
-  /** Provider status details */
-  details?: Record<string, unknown>;
-}
-
-// ============================================================================
-// Circuit Breaker Types
-// ============================================================================
-
-/**
- * Circuit breaker states
- */
-export type CircuitBreakerState = 'closed' | 'open' | 'half-open';
-
-/**
- * Circuit breaker configuration
- */
-export interface CircuitBreakerConfig {
-  /** Number of failures before opening circuit */
-  failureThreshold: number;
-  /** Time in ms to wait before half-open */
-  resetTimeoutMs: number;
-  /** Number of successes in half-open before closing */
-  halfOpenSuccessThreshold: number;
-  /** Time window for failure counting in ms */
-  failureWindowMs: number;
-  /** Whether to include timeouts as failures */
-  includeTimeouts: boolean;
-}
-
-/**
- * Circuit breaker statistics
- */
-export interface CircuitBreakerStats {
-  /** Current state */
-  state: CircuitBreakerState;
-  /** Total requests */
-  totalRequests: number;
-  /** Successful requests */
-  successCount: number;
-  /** Failed requests */
-  failureCount: number;
-  /** Requests rejected due to open circuit */
-  rejectedCount: number;
-  /** Last failure time */
-  lastFailureTime?: Date;
-  /** Last success time */
-  lastSuccessTime?: Date;
-  /** Time until circuit transitions (for open/half-open) */
-  timeUntilTransitionMs?: number;
-}
-
-// ============================================================================
-// Cost Tracking Types
-// ============================================================================
-
-/**
- * Cost tracking period
- */
-export type CostPeriod = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'all';
-
-/**
- * Cost summary for a period
- */
-export interface CostSummary {
-  /** Period type */
-  period: CostPeriod;
-  /** Start of period */
-  periodStart: Date;
-  /** End of period */
-  periodEnd: Date;
-  /** Total cost in USD */
-  totalCost: number;
-  /** Cost breakdown by provider */
-  byProvider: Record<LLMProviderType, number>;
-  /** Cost breakdown by model */
-  byModel: Record<string, number>;
-  /** Total tokens used */
-  totalTokens: number;
-  /** Total requests */
-  totalRequests: number;
-}
-
-/**
- * Cost alert configuration
- */
-export interface CostAlert {
-  /** Alert threshold in USD */
-  threshold: number;
-  /** Period for threshold */
-  period: CostPeriod;
-  /** Callback when threshold reached */
-  onThreshold: (summary: CostSummary) => void;
-  /** Whether alert is currently active */
-  active: boolean;
-}
-
-// ============================================================================
-// Cache Types
-// ============================================================================
-
-/**
- * Cache entry structure
- */
-export interface CacheEntry<T> {
-  /** Cached value */
-  value: T;
-  /** Creation timestamp */
-  createdAt: Date;
-  /** Last access timestamp */
-  lastAccessedAt: Date;
-  /** Access count */
-  accessCount: number;
-  /** Time-to-live in ms (0 = no expiry) */
-  ttlMs: number;
-  /** Cache key hash */
-  keyHash: string;
-}
-
-/**
- * Cache configuration
- */
-export interface LLMCacheConfig {
-  /** Maximum number of entries */
-  maxSize: number;
-  /** Default TTL in ms (0 = no expiry) */
-  defaultTtlMs: number;
-  /** Enable LRU eviction */
-  enableLRU: boolean;
-  /** Cache generation responses */
-  cacheGenerations: boolean;
-  /** Cache embedding responses */
-  cacheEmbeddings: boolean;
-  /** Cache completion responses */
-  cacheCompletions: boolean;
-}
-
-/**
- * Cache statistics
- */
-export interface LLMCacheStats {
-  /** Current number of entries */
-  size: number;
-  /** Maximum size */
-  maxSize: number;
-  /** Cache hit count */
-  hits: number;
-  /** Cache miss count */
-  misses: number;
-  /** Hit rate (0-1) */
-  hitRate: number;
-  /** Total evictions */
-  evictions: number;
-  /** Memory usage estimate in bytes */
-  memoryUsageBytes: number;
-}
-
-// ============================================================================
-// Provider Manager Types
-// ============================================================================
-
-/**
- * Provider selection result
- */
-export interface ProviderSelection {
-  /** Selected provider */
-  provider: LLMProvider;
-  /** Reason for selection */
-  reason:
-    | 'primary'
-    | 'fallback'
-    | 'load-balance'
-    | 'cost-optimization'
-    | 'latency-optimization';
-  /** Selection metadata */
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Provider metrics
- */
-export interface ProviderMetrics {
-  /** Provider type */
-  provider: LLMProviderType;
-  /** Total requests */
-  totalRequests: number;
-  /** Successful requests */
-  successCount: number;
-  /** Failed requests */
-  failureCount: number;
-  /** Average latency in ms */
-  avgLatencyMs: number;
-  /** P95 latency in ms */
-  p95LatencyMs: number;
-  /** P99 latency in ms */
-  p99LatencyMs: number;
-  /** Total cost */
-  totalCost: number;
-  /** Total tokens */
-  totalTokens: number;
-  /** Circuit breaker state */
-  circuitState: CircuitBreakerState;
-}
-
-// ============================================================================
-// Error Types
-// ============================================================================
-
-/**
- * LLM-specific error codes
- */
-export type LLMErrorCode =
-  | 'API_KEY_INVALID'
-  | 'API_KEY_MISSING'
-  | 'RATE_LIMITED'
-  | 'CONTEXT_LENGTH_EXCEEDED'
-  | 'CONTENT_FILTERED'
-  | 'MODEL_NOT_FOUND'
-  | 'PROVIDER_UNAVAILABLE'
-  | 'CIRCUIT_OPEN'
-  | 'TIMEOUT'
-  | 'NETWORK_ERROR'
-  | 'COST_LIMIT_EXCEEDED'
-  | 'UNKNOWN';
-
-/**
- * LLM error with rich context
- */
-export interface LLMError extends Error {
-  /** Error code */
-  code: LLMErrorCode;
-  /** Provider that caused the error */
-  provider?: LLMProviderType;
-  /** Model that caused the error */
-  model?: string;
-  /** Whether error is retryable */
-  retryable: boolean;
-  /** Suggested retry after time in ms */
-  retryAfterMs?: number;
-  /** Original error */
-  cause?: Error;
-}
-
-/**
- * Create an LLM error
- */
-export function createLLMError(
-  message: string,
-  code: LLMErrorCode,
-  options?: {
-    provider?: LLMProviderType;
-    model?: string;
-    retryable?: boolean;
-    retryAfterMs?: number;
-    cause?: Error;
-  }
-): LLMError {
-  const error = new Error(message) as LLMError;
-  error.name = 'LLMError';
-  error.code = code;
-  error.provider = options?.provider;
-  error.model = options?.model;
-  error.retryable = options?.retryable ?? false;
-  error.retryAfterMs = options?.retryAfterMs;
-  error.cause = options?.cause;
-  return error;
-}
-
-/**
- * Type guard for LLM errors
- */
-export function isLLMError(error: unknown): error is LLMError {
-  return (
-    error instanceof Error &&
-    'code' in error &&
-    typeof (error as LLMError).code === 'string'
-  );
-}