@libredb/studio 0.9.7 → 0.9.13

package/src/lib/llm/types.ts

@@ -1,173 +0,0 @@
-/**
- * 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

@@ -1,187 +0,0 @@
-/**
- * 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

@@ -1,119 +0,0 @@
-/**
- * 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

@@ -1,202 +0,0 @@
-/**
- * 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();
-    },
-  });
-}