@libredb/studio 0.9.7

package/src/lib/llm/types.ts

@@ -0,0 +1,173 @@
+/**
+ * LLM Provider Types & Interfaces
+ * Strategy Pattern implementation for multi-provider LLM support
+ */
+
+// ============================================================================
+// Provider Types
+// ============================================================================
+
+export type LLMProviderType = 'gemini' | 'openai' | 'ollama' | 'custom';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface LLMConfig {
+  provider: LLMProviderType;
+  apiKey?: string;
+  model: string;
+  apiUrl?: string;
+}
+
+// ============================================================================
+// Messages
+// ============================================================================
+
+export type LLMMessageRole = 'system' | 'user' | 'assistant';
+
+export interface LLMMessage {
+  role: LLMMessageRole;
+  content: string;
+}
+
+// ============================================================================
+// Stream Options
+// ============================================================================
+
+export interface LLMStreamOptions {
+  messages: LLMMessage[];
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+// ============================================================================
+// Provider Interface (Strategy Pattern)
+// ============================================================================
+
+export interface LLMProvider {
+  /** Provider identifier */
+  readonly name: LLMProviderType;
+
+  /** Current configuration */
+  readonly config: LLMConfig;
+
+  /**
+   * Stream a completion response
+   * @param options - Stream configuration including messages
+   * @returns ReadableStream of UTF-8 encoded chunks
+   */
+  stream(options: LLMStreamOptions): Promise<ReadableStream<Uint8Array>>;
+
+  /**
+   * Validate provider configuration
+   * @throws LLMConfigError if configuration is invalid
+   */
+  validate(): void;
+}
+
+// ============================================================================
+// Error Classes
+// ============================================================================
+
+/**
+ * Base error class for LLM-related errors
+ */
+export class LLMError extends Error {
+  constructor(
+    message: string,
+    public readonly provider?: LLMProviderType,
+    public readonly statusCode?: number
+  ) {
+    super(message);
+    this.name = 'LLMError';
+    Object.setPrototypeOf(this, LLMError.prototype);
+  }
+}
+
+/**
+ * Configuration error - missing or invalid config
+ */
+export class LLMConfigError extends LLMError {
+  constructor(message: string, provider?: LLMProviderType) {
+    super(message, provider);
+    this.name = 'LLMConfigError';
+    Object.setPrototypeOf(this, LLMConfigError.prototype);
+  }
+}
+
+/**
+ * Authentication error - invalid API key (401/403)
+ */
+export class LLMAuthError extends LLMError {
+  constructor(message: string, provider?: LLMProviderType) {
+    super(message, provider, 401);
+    this.name = 'LLMAuthError';
+    Object.setPrototypeOf(this, LLMAuthError.prototype);
+  }
+}
+
+/**
+ * Rate limit error - quota exceeded (429)
+ */
+export class LLMRateLimitError extends LLMError {
+  constructor(message: string, provider?: LLMProviderType) {
+    super(message, provider, 429);
+    this.name = 'LLMRateLimitError';
+    Object.setPrototypeOf(this, LLMRateLimitError.prototype);
+  }
+}
+
+/**
+ * Safety filter error - content blocked
+ */
+export class LLMSafetyError extends LLMError {
+  constructor(message: string, provider?: LLMProviderType) {
+    super(message, provider, 400);
+    this.name = 'LLMSafetyError';
+    Object.setPrototypeOf(this, LLMSafetyError.prototype);
+  }
+}
+
+/**
+ * Streaming error - connection or parsing failure
+ */
+export class LLMStreamError extends LLMError {
+  constructor(message: string, provider?: LLMProviderType) {
+    super(message, provider);
+    this.name = 'LLMStreamError';
+    Object.setPrototypeOf(this, LLMStreamError.prototype);
+  }
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isLLMError(error: unknown): error is LLMError {
+  return error instanceof LLMError;
+}
+
+export function isRetryableError(error: unknown): boolean {
+  if (!isLLMError(error)) {
+    // Network errors are retryable
+    if (error instanceof TypeError && error.message.includes('fetch')) {
+      return true;
+    }
+    return false;
+  }
+
+  // Auth and safety errors are not retryable
+  if (error instanceof LLMAuthError || error instanceof LLMSafetyError) {
+    return false;
+  }
+
+  // Config errors are not retryable
+  if (error instanceof LLMConfigError) {
+    return false;
+  }
+
+  // Rate limit and stream errors may be retryable
+  return true;
+}

package/src/lib/llm/utils/config.ts

@@ -0,0 +1,187 @@
+/**
+ * LLM Configuration Utilities
+ * Environment variable resolution and default configuration
+ */
+
+import { type LLMConfig, type LLMProviderType, LLMConfigError } from '../types';
+
+// ============================================================================
+// Default Configuration
+// ============================================================================
+
+export const DEFAULT_PROVIDER: LLMProviderType = 'gemini';
+
+export const DEFAULT_MODELS: Record<LLMProviderType, string> = {
+  gemini: 'gemini-2.5-flash',
+  openai: 'gpt-4o',
+  ollama: 'llama3.2',
+  custom: 'gpt-3.5-turbo',
+};
+
+export const DEFAULT_API_URLS: Record<string, string> = {
+  ollama: 'http://localhost:11434/v1',
+  openai: 'https://api.openai.com/v1',
+};
+
+// ============================================================================
+// Environment Resolution
+// ============================================================================
+
+function getEnvVar(key: string): string | undefined {
+  return process.env[key];
+}
+
+function resolveProvider(): LLMProviderType {
+  const provider = getEnvVar('LLM_PROVIDER')?.toLowerCase();
+
+  if (!provider) {
+    return DEFAULT_PROVIDER;
+  }
+
+  const validProviders: LLMProviderType[] = ['gemini', 'openai', 'ollama', 'custom'];
+
+  if (!validProviders.includes(provider as LLMProviderType)) {
+    console.error(`[LLM] Invalid provider "${provider}", falling back to "${DEFAULT_PROVIDER}"`);
+    return DEFAULT_PROVIDER;
+  }
+
+  return provider as LLMProviderType;
+}
+
+function resolveApiKey(provider: LLMProviderType): string | undefined {
+  const apiKey = getEnvVar('LLM_API_KEY');
+
+  // Ollama doesn't require API key
+  if (!apiKey && provider === 'ollama') {
+    return undefined;
+  }
+
+  return apiKey;
+}
+
+function resolveModel(provider: LLMProviderType): string {
+  const model = getEnvVar('LLM_MODEL');
+  return model || DEFAULT_MODELS[provider];
+}
+
+function resolveApiUrl(provider: LLMProviderType): string | undefined {
+  // Primary: LLM_API_URL
+  const apiUrl = getEnvVar('LLM_API_URL');
+  if (apiUrl) {
+    return apiUrl;
+  }
+
+  // Default URLs for specific providers
+  if (provider === 'ollama') {
+    return DEFAULT_API_URLS.ollama;
+  }
+
+  if (provider === 'openai') {
+    return DEFAULT_API_URLS.openai;
+  }
+
+  // Custom provider requires explicit URL
+  if (provider === 'custom') {
+    return undefined;
+  }
+
+  return undefined;
+}
+
+// ============================================================================
+// Configuration Resolution
+// ============================================================================
+
+/**
+ * Resolve LLM configuration from environment variables with optional overrides
+ */
+export function resolveConfig(overrides?: Partial<LLMConfig>): LLMConfig {
+  const provider = overrides?.provider ?? resolveProvider();
+
+  return {
+    provider,
+    apiKey: overrides?.apiKey ?? resolveApiKey(provider),
+    model: overrides?.model ?? resolveModel(provider),
+    apiUrl: overrides?.apiUrl ?? resolveApiUrl(provider),
+  };
+}
+
+// ============================================================================
+// Configuration Validation
+// ============================================================================
+
+/**
+ * Validate LLM configuration
+ * @throws LLMConfigError if configuration is invalid
+ */
+export function validateConfig(config: LLMConfig): void {
+  // Validate provider
+  const validProviders: LLMProviderType[] = ['gemini', 'openai', 'ollama', 'custom'];
+  if (!validProviders.includes(config.provider)) {
+    throw new LLMConfigError(
+      `Invalid provider: ${config.provider}. Valid options: ${validProviders.join(', ')}`,
+      config.provider
+    );
+  }
+
+  // Validate API key requirements
+  if (config.provider === 'gemini' && !config.apiKey) {
+    throw new LLMConfigError(
+      'Gemini API key is required. Set LLM_API_KEY environment variable.',
+      'gemini'
+    );
+  }
+
+  if (config.provider === 'openai' && !config.apiKey) {
+    throw new LLMConfigError(
+      'OpenAI API key is required. Set LLM_API_KEY environment variable.',
+      'openai'
+    );
+  }
+
+  // Validate API URL for custom provider
+  if (config.provider === 'custom' && !config.apiUrl) {
+    throw new LLMConfigError(
+      'Custom provider requires LLM_API_URL environment variable.',
+      'custom'
+    );
+  }
+
+  // Validate model
+  if (!config.model || config.model.trim() === '') {
+    throw new LLMConfigError(
+      `Model name is required for ${config.provider} provider.`,
+      config.provider
+    );
+  }
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Check if a provider requires an API key
+ */
+export function requiresApiKey(provider: LLMProviderType): boolean {
+  return provider === 'gemini' || provider === 'openai';
+}
+
+/**
+ * Check if a provider requires a custom API URL
+ */
+export function requiresApiUrl(provider: LLMProviderType): boolean {
+  return provider === 'custom';
+}
+
+/**
+ * Get safe config for logging (API key masked)
+ */
+export function getSafeConfigForLogging(config: LLMConfig): Record<string, string | undefined> {
+  return {
+    provider: config.provider,
+    model: config.model,
+    apiUrl: config.apiUrl,
+    apiKey: config.apiKey ? '***' : undefined,
+  };
+}

package/src/lib/llm/utils/retry.ts

@@ -0,0 +1,119 @@
+/**
+ * Retry Utility with Exponential Backoff
+ * Handles transient failures in LLM API calls
+ */
+
+import { isRetryableError, LLMError, type LLMProviderType } from '../types';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxAttempts?: number;
+  /** Initial delay in milliseconds (default: 1000) */
+  initialDelay?: number;
+  /** Backoff multiplier (default: 2) */
+  backoffMultiplier?: number;
+  /** Maximum delay in milliseconds (default: 10000) */
+  maxDelay?: number;
+  /** Provider name for logging */
+  provider?: LLMProviderType;
+  /** Operation name for logging */
+  operation?: string;
+}
+
+// ============================================================================
+// Default Configuration
+// ============================================================================
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY = 1000;
+const DEFAULT_BACKOFF_MULTIPLIER = 2;
+const DEFAULT_MAX_DELAY = 10000;
+
+// ============================================================================
+// Retry Implementation
+// ============================================================================
+
+/**
+ * Execute a function with retry logic and exponential backoff
+ * @param fn - Async function to execute
+ * @param options - Retry configuration
+ * @returns Result of the function
+ * @throws Last error if all retries fail
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    initialDelay = DEFAULT_INITIAL_DELAY,
+    backoffMultiplier = DEFAULT_BACKOFF_MULTIPLIER,
+    maxDelay = DEFAULT_MAX_DELAY,
+    provider,
+    operation = 'LLM request',
+  } = options;
+
+  let lastError: Error | undefined;
+  let delay = initialDelay;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Check if error is retryable
+      if (!isRetryableError(error)) {
+        throw error;
+      }
+
+      // Don't retry on last attempt
+      if (attempt === maxAttempts) {
+        break;
+      }
+
+      // Log retry attempt
+      console.error(
+        `[LLM${provider ? `:${provider}` : ''}] ${operation} failed (attempt ${attempt}/${maxAttempts}): ${lastError.message}. Retrying in ${delay}ms...`
+      );
+
+      // Wait before retrying
+      await sleep(delay);
+
+      // Increase delay with exponential backoff
+      delay = Math.min(delay * backoffMultiplier, maxDelay);
+    }
+  }
+
+  // All retries exhausted
+  console.error(
+    `[LLM${provider ? `:${provider}` : ''}] ${operation} failed after ${maxAttempts} attempts: ${lastError?.message}`
+  );
+
+  throw lastError ?? new LLMError('Unknown error during retry', provider);
+}
+
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ============================================================================
+// Retry Decorators (for class methods)
+// ============================================================================
+
+/**
+ * Create a retryable version of an async function
+ */
+export function makeRetryable<T extends unknown[], R>(
+  fn: (...args: T) => Promise<R>,
+  options: RetryOptions = {}
+): (...args: T) => Promise<R> {
+  return (...args: T) => withRetry(() => fn(...args), options);
+}

package/src/lib/llm/utils/streaming.ts

@@ -0,0 +1,202 @@
+/**
+ * Streaming Utilities for LLM Providers
+ * SSE parsing and stream transformation helpers
+ */
+
+import { LLMStreamError, type LLMProviderType } from '../types';
+import { logger } from '@/lib/logger';
+
+// ============================================================================
+// Text Encoding/Decoding
+// ============================================================================
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export function encodeText(text: string): Uint8Array {
+  return textEncoder.encode(text);
+}
+
+export function decodeText(bytes: Uint8Array): string {
+  return textDecoder.decode(bytes);
+}
+
+// ============================================================================
+// SSE (Server-Sent Events) Parser
+// ============================================================================
+
+export interface SSEChunk {
+  data: string;
+  event?: string;
+  id?: string;
+}
+
+/**
+ * Parse SSE formatted response for OpenAI-compatible APIs
+ * Handles chunked responses and extracts content from delta objects
+ */
+export function createSSEParser(): TransformStream<Uint8Array, Uint8Array> {
+  let buffer = '';
+
+  return new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      buffer += decodeText(chunk);
+
+      // Process complete lines
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? ''; // Keep incomplete line in buffer
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Skip empty lines and comments
+        if (!trimmed || trimmed.startsWith(':')) {
+          continue;
+        }
+
+        // Handle data lines
+        if (trimmed.startsWith('data: ')) {
+          const data = trimmed.slice(6);
+
+          // Handle stream end marker
+          if (data === '[DONE]') {
+            return;
+          }
+
+          try {
+            const parsed = JSON.parse(data);
+            const content = extractContent(parsed);
+
+            if (content) {
+              controller.enqueue(encodeText(content));
+            }
+          } catch {
+            logger.debug('Skipping malformed JSON chunk in SSE stream');
+          }
+        }
+      }
+    },
+
+    flush(controller) {
+      // Process any remaining data in buffer
+      if (buffer.trim()) {
+        const trimmed = buffer.trim();
+        if (trimmed.startsWith('data: ') && trimmed.slice(6) !== '[DONE]') {
+          try {
+            const parsed = JSON.parse(trimmed.slice(6));
+            const content = extractContent(parsed);
+            if (content) {
+              controller.enqueue(encodeText(content));
+            }
+          } catch {
+            logger.debug('Skipping malformed JSON chunk in SSE stream flush');
+          }
+        }
+      }
+    },
+  });
+}
+
+/**
+ * Extract content from parsed SSE data based on provider format
+ */
+function extractContent(data: unknown): string | null {
+  if (!data || typeof data !== 'object') {
+    return null;
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  // OpenAI format: choices[0].delta.content
+  if (Array.isArray(obj.choices) && obj.choices.length > 0) {
+    const choice = obj.choices[0] as Record<string, unknown>;
+    const delta = choice.delta as Record<string, unknown> | undefined;
+
+    if (delta && typeof delta.content === 'string') {
+      return delta.content;
+    }
+  }
+
+  return null;
+}
+
+// ============================================================================
+// Stream Utilities
+// ============================================================================
+
+/**
+ * Create a ReadableStream from an async iterable
+ */
+export function streamFromAsyncIterable<T>(
+  iterable: AsyncIterable<T>,
+  transform: (item: T) => Uint8Array | null
+): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      try {
+        for await (const item of iterable) {
+          const chunk = transform(item);
+          if (chunk) {
+            controller.enqueue(chunk);
+          }
+        }
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+  });
+}
+
+/**
+ * Create a ReadableStream from a fetch Response with SSE parsing
+ */
+export function createStreamFromSSEResponse(
+  response: Response,
+  provider: LLMProviderType
+): ReadableStream<Uint8Array> {
+  const body = response.body;
+
+  if (!body) {
+    throw new LLMStreamError('Response body is empty', provider);
+  }
+
+  return body.pipeThrough(createSSEParser());
+}
+
+/**
+ * Merge multiple streams into one (useful for multi-part responses)
+ */
+export function mergeStreams(
+  streams: ReadableStream<Uint8Array>[]
+): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      for (const stream of streams) {
+        const reader = stream.getReader();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            controller.enqueue(value);
+          }
+        } finally {
+          reader.releaseLock();
+        }
+      }
+      controller.close();
+    },
+  });
+}
+
+/**
+ * Create an error stream that emits a single error message
+ */
+export function createErrorStream(message: string): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(encodeText(`Error: ${message}`));
+      controller.close();
+    },
+  });
+}