@startsimpli/llm 0.1.1

package/src/providers/openai.ts

@@ -0,0 +1,273 @@
+/**
+ * OpenAI Provider Implementation
+ *
+ * Uses native fetch to minimize dependencies.
+ * Supports GPT-5.x, GPT-4o models, and custom fine-tuned models.
+ *
+ * To use a custom fine-tuned model:
+ * 1. Set OPENAI_MODEL or LLM_MODEL to your fine-tuned model ID (e.g., "ft:gpt-4o-2024-08-06:org:name:id")
+ * 2. Fine-tuned models will use the configured temperature setting (not forced to 1.0 like base gpt-5)
+ */
+
+import type { ILLMProvider } from './interface';
+import type { LLMResponse, GenerateOptions, ProviderConfig } from '../types';
+import { LLM_DEFAULTS } from '../types';
+import { LLMProviderError } from '../errors';
+import type { LLMErrorCode } from '../errors';
+
+interface OpenAIMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+interface OpenAIRequest {
+  model: string;
+  messages: OpenAIMessage[];
+  temperature?: number;
+  max_tokens?: number;
+  response_format?: { type: 'json_object' | 'text' };
+}
+
+interface OpenAIResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: { role: string; content: string };
+    finish_reason: string;
+  }>;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+interface OpenAIErrorResponse {
+  error: {
+    message: string;
+    type: string;
+    code?: string;
+    param?: string;
+  };
+}
+
+const OPENAI_MODELS = [
+  'gpt-5.2',
+  'gpt-5.1',
+  'gpt-5',
+  'gpt-4o',
+  'gpt-4o-mini',
+] as const;
+
+const MODEL_COSTS: Record<string, { input: number; output: number }> = {
+  'gpt-5.2': { input: 0.005, output: 0.015 },
+  'gpt-5.1': { input: 0.005, output: 0.015 },
+  'gpt-5': { input: 0.005, output: 0.015 },
+  'gpt-4o': { input: 0.0025, output: 0.01 },
+  'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
+};
+
+const DEFAULTS = {
+  baseUrl: 'https://api.openai.com/v1',
+  model: LLM_DEFAULTS.openaiModel,
+  temperature: LLM_DEFAULTS.temperature,
+  maxTokens: LLM_DEFAULTS.maxTokens,
+  timeoutMs: LLM_DEFAULTS.timeoutMs,
+};
+
+export class OpenAIProvider implements ILLMProvider {
+  readonly name = 'openai';
+  readonly availableModels = OPENAI_MODELS;
+  readonly defaultModel: string;
+
+  private readonly config: Required<ProviderConfig>;
+
+  constructor(config: ProviderConfig) {
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl ?? DEFAULTS.baseUrl,
+      defaultModel: config.defaultModel ?? DEFAULTS.model,
+      defaultTemperature: config.defaultTemperature ?? DEFAULTS.temperature,
+      defaultMaxTokens: config.defaultMaxTokens ?? DEFAULTS.maxTokens,
+      timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
+    };
+    this.defaultModel = this.config.defaultModel;
+  }
+
+  isAvailable(): boolean {
+    return Boolean(this.config.apiKey);
+  }
+
+  async generate(
+    userPrompt: string,
+    systemPrompt: string,
+    options?: GenerateOptions
+  ): Promise<LLMResponse> {
+    if (!this.isAvailable()) {
+      throw new LLMProviderError(
+        'OpenAI API key not configured',
+        'AUTHENTICATION_ERROR',
+        false,
+        undefined,
+        this.name
+      );
+    }
+
+    const model = options?.model ?? this.config.defaultModel;
+    // Base gpt-5 models require temperature=1.0, but fine-tuned models use configured temperature
+    const isBaseGpt5 = model === 'gpt-5' || model === 'gpt-5.1' || model === 'gpt-5.2';
+    const isFineTuned = model.startsWith('ft:');
+    const temperature = isBaseGpt5 && !isFineTuned
+      ? 1.0
+      : (options?.temperature ?? this.config.defaultTemperature);
+    const maxTokens = options?.maxTokens ?? this.config.defaultMaxTokens;
+    const timeout = options?.timeout ?? this.config.timeoutMs;
+
+    const requestBody: OpenAIRequest = {
+      model,
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt },
+      ],
+      temperature,
+      max_tokens: maxTokens,
+      response_format: { type: 'json_object' },
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify(requestBody),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({
+          error: { message: 'Unknown error' },
+        }))) as OpenAIErrorResponse;
+        throw this.handleApiError(response.status, errorData);
+      }
+
+      const data = (await response.json()) as OpenAIResponse;
+
+      if (!data.choices?.[0]?.message?.content) {
+        throw new LLMProviderError(
+          'Empty response from OpenAI',
+          'UNKNOWN_ERROR',
+          true,
+          undefined,
+          this.name
+        );
+      }
+
+      return {
+        content: data.choices[0].message.content,
+        usage: {
+          promptTokens: data.usage.prompt_tokens,
+          completionTokens: data.usage.completion_tokens,
+          totalTokens: data.usage.total_tokens,
+        },
+        model: data.model,
+        responseId: data.id,
+        finishReason: data.choices[0].finish_reason,
+      };
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      if (error instanceof LLMProviderError) {
+        throw error;
+      }
+
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new LLMProviderError(
+          `Request timed out after ${timeout}ms`,
+          'TIMEOUT',
+          true,
+          undefined,
+          this.name
+        );
+      }
+
+      throw new LLMProviderError(
+        `OpenAI request failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'UNKNOWN_ERROR',
+        true,
+        undefined,
+        this.name
+      );
+    }
+  }
+
+  estimateCost(
+    promptTokens: number,
+    completionTokens: number,
+    model?: string
+  ): number | undefined {
+    const costs = MODEL_COSTS[model ?? this.config.defaultModel];
+    if (!costs) return undefined;
+    return (promptTokens / 1000) * costs.input + (completionTokens / 1000) * costs.output;
+  }
+
+  private handleApiError(
+    statusCode: number,
+    errorResponse: OpenAIErrorResponse
+  ): LLMProviderError {
+    const message = errorResponse.error?.message ?? 'Unknown OpenAI error';
+    const errorType = errorResponse.error?.type ?? '';
+    const errorCode = errorResponse.error?.code ?? '';
+
+    let code: LLMErrorCode;
+    let retryable = false;
+
+    if (statusCode === 401) {
+      code = 'AUTHENTICATION_ERROR';
+    } else if (statusCode === 429) {
+      code = 'RATE_LIMITED';
+      retryable = true;
+    } else if (statusCode === 400) {
+      if (errorCode === 'context_length_exceeded') {
+        code = 'CONTEXT_LENGTH_EXCEEDED';
+      } else if (errorType === 'invalid_request_error') {
+        code = 'INVALID_REQUEST';
+      } else {
+        code = 'UNKNOWN_ERROR';
+      }
+    } else if (statusCode === 403) {
+      code = errorCode === 'content_filter' ? 'CONTENT_FILTERED' : 'AUTHENTICATION_ERROR';
+    } else if (statusCode >= 500) {
+      code = 'SERVICE_UNAVAILABLE';
+      retryable = true;
+    } else {
+      code = 'UNKNOWN_ERROR';
+    }
+
+    return new LLMProviderError(message, code, retryable, statusCode, this.name);
+  }
+}
+
+/**
+ * Create an OpenAI provider from environment variables.
+ * Returns null if OPENAI_API_KEY is not set.
+ */
+export function createOpenAIProvider(): OpenAIProvider | null {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) return null;
+
+  return new OpenAIProvider({
+    apiKey,
+    baseUrl: process.env.OPENAI_BASE_URL,
+    defaultModel: process.env.OPENAI_MODEL,
+  });
+}

package/src/service.ts

@@ -0,0 +1,366 @@
+/**
+ * Generic LLM Service
+ *
+ * Orchestrates provider selection, generation, JSON extraction,
+ * schema validation, and retry logic. Parameterized over <TOutput>
+ * so domain-specific schemas (Pattern, Recipe, etc.) stay in their apps.
+ */
+
+import type { ZodSchema } from 'zod';
+import { ZodError } from 'zod';
+import type { ILLMProvider } from './providers/interface';
+import type {
+  LLMResponse,
+  GenerateOptions,
+  LLMServiceConfig,
+  ValidationResult,
+} from './types';
+import { LLM_DEFAULTS } from './types';
+import { LLMProviderError } from './errors';
+import { extractJson } from './utils/json-extraction';
+import {
+  buildSchemaErrorCorrectionPrompt,
+  buildParseErrorCorrectionPrompt,
+  buildGenericRetryPrompt,
+} from './utils/retry';
+import { OpenAIProvider, createOpenAIProvider } from './providers/openai';
+import { AnthropicProvider, createAnthropicProvider } from './providers/anthropic';
+import { MockLLMProvider } from './providers/mock';
+
+/**
+ * Metadata about a generation attempt (tokens, model, retries).
+ */
+export interface GenerationMetadata {
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+  validationAttempts: number;
+}
+
+/**
+ * Result of a validated generation. The caller checks `success` to narrow the union.
+ */
+export type GenerationResult<TOutput> =
+  | {
+      success: true;
+      data: TOutput;
+      metadata: GenerationMetadata;
+    }
+  | {
+      success: false;
+      error: { code: string; message: string; retryable: boolean };
+      metadata?: GenerationMetadata;
+    };
+
+const DEFAULT_CONFIG: Required<LLMServiceConfig> = {
+  maxRetries: 2,
+  preferredProvider: 'openai',
+  defaultModel: '',
+  defaultTemperature: LLM_DEFAULTS.temperature,
+  defaultMaxTokens: LLM_DEFAULTS.maxTokens,
+};
+
+/**
+ * Generic LLM service. Consumers supply:
+ * - A Zod schema for output validation
+ * - Prompt builders for their domain
+ *
+ * The service handles provider selection, retries, JSON extraction, and validation.
+ */
+export class LLMService<TOutput> {
+  private readonly config: Required<LLMServiceConfig>;
+  private readonly providers: Map<string, ILLMProvider> = new Map();
+
+  constructor(config?: LLMServiceConfig) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.initializeProviders();
+  }
+
+  private initializeProviders(): void {
+    // Mock provider for testing
+    if (process.env.LLM_PROVIDER === 'mock') {
+      this.providers.set('mock', new MockLLMProvider());
+      return;
+    }
+
+    const openai = createOpenAIProvider();
+    if (openai) this.providers.set('openai', openai);
+
+    const anthropic = createAnthropicProvider();
+    if (anthropic) this.providers.set('anthropic', anthropic);
+  }
+
+  private getProvider(): ILLMProvider {
+    // Try preferred first
+    const preferred = this.providers.get(this.config.preferredProvider);
+    if (preferred?.isAvailable()) return preferred;
+
+    // Fallback to any available
+    for (const provider of this.providers.values()) {
+      if (provider.isAvailable()) return provider;
+    }
+
+    throw new LLMProviderError(
+      'No LLM providers available. Please configure OPENAI_API_KEY or ANTHROPIC_API_KEY.',
+      'AUTHENTICATION_ERROR',
+      false
+    );
+  }
+
+  /** Check if any LLM provider is available. */
+  isAvailable(): boolean {
+    for (const provider of this.providers.values()) {
+      if (provider.isAvailable()) return true;
+    }
+    return false;
+  }
+
+  /** Get list of available provider names. */
+  getAvailableProviders(): string[] {
+    const available: string[] = [];
+    for (const [name, provider] of this.providers.entries()) {
+      if (provider.isAvailable()) available.push(name);
+    }
+    return available;
+  }
+
+  /**
+   * Simple chat-style generation with no schema validation.
+   * Returns the raw LLM response.
+   */
+  async chat(
+    userPrompt: string,
+    systemPrompt: string,
+    options?: GenerateOptions
+  ): Promise<LLMResponse> {
+    const provider = this.getProvider();
+    const generateOptions: GenerateOptions = {
+      temperature: options?.temperature ?? this.config.defaultTemperature,
+      maxTokens: options?.maxTokens ?? this.config.defaultMaxTokens,
+      ...options,
+    };
+
+    return provider.generate(userPrompt, systemPrompt, generateOptions);
+  }
+
+  /**
+   * Generate structured output validated against a Zod schema.
+   *
+   * @param userPrompt - User's request
+   * @param systemPrompt - System instructions
+   * @param schema - Zod schema to validate the parsed JSON against
+   * @param options - Generation options
+   */
+  async generate(
+    userPrompt: string,
+    systemPrompt: string,
+    schema: ZodSchema<TOutput>,
+    options?: GenerateOptions
+  ): Promise<GenerationResult<TOutput>> {
+    const provider = this.getProvider();
+
+    const genOptions: GenerateOptions = {
+      model: this.config.defaultModel || undefined,
+      temperature: this.config.defaultTemperature,
+      maxTokens: this.config.defaultMaxTokens,
+      ...options,
+    };
+
+    let lastError: Error | undefined;
+    let lastResponse: LLMResponse | undefined;
+    let validationAttempts = 0;
+
+    // Initial generation
+    try {
+      lastResponse = await provider.generate(userPrompt, systemPrompt, genOptions);
+      validationAttempts++;
+
+      const extraction = extractJson(lastResponse.content);
+      if (!extraction.success) {
+        // JSON parse error — try correction
+        const result = await this.retryWithCorrection(
+          provider,
+          userPrompt,
+          systemPrompt,
+          lastResponse,
+          'parse',
+          extraction.error!,
+          schema,
+          genOptions,
+          validationAttempts
+        );
+        if (result.data) {
+          return this.buildSuccess(result.data, result.response ?? lastResponse, result.attempts);
+        }
+        lastError = new Error(extraction.error);
+        validationAttempts = result.attempts;
+      } else {
+        // Validate against schema
+        const validation = this.validate(extraction.json, schema);
+        if (validation.valid && validation.data) {
+          return this.buildSuccess(validation.data, lastResponse, validationAttempts);
+        }
+
+        // Schema validation error — try correction
+        const result = await this.retryWithCorrection(
+          provider,
+          userPrompt,
+          systemPrompt,
+          lastResponse,
+          'schema',
+          validation.zodError!,
+          schema,
+          genOptions,
+          validationAttempts
+        );
+        if (result.data) {
+          return this.buildSuccess(result.data, result.response ?? lastResponse, result.attempts);
+        }
+        lastError = validation.zodError;
+        validationAttempts = result.attempts;
+      }
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+    }
+
+    // All retries exhausted
+    return this.buildError(lastError ?? new Error('Unknown error'), lastResponse, validationAttempts);
+  }
+
+  /**
+   * Register an additional provider instance (useful for custom/third-party providers).
+   */
+  registerProvider(name: string, provider: ILLMProvider): void {
+    this.providers.set(name, provider);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  private async retryWithCorrection(
+    provider: ILLMProvider,
+    originalPrompt: string,
+    systemPrompt: string,
+    previousResponse: LLMResponse,
+    errorType: 'parse' | 'schema',
+    error: string | ZodError,
+    schema: ZodSchema<TOutput>,
+    options: GenerateOptions,
+    currentAttempts: number
+  ): Promise<{ data?: TOutput; response?: LLMResponse; attempts: number }> {
+    let attempts = currentAttempts;
+
+    for (let retry = 0; retry < this.config.maxRetries; retry++) {
+      attempts++;
+
+      try {
+        const correctionPrompt =
+          errorType === 'parse'
+            ? buildParseErrorCorrectionPrompt(previousResponse.content, error as string)
+            : buildSchemaErrorCorrectionPrompt(previousResponse.content, error as ZodError);
+
+        const response = await provider.generate(correctionPrompt, systemPrompt, options);
+        const extraction = extractJson(response.content);
+
+        if (!extraction.success) {
+          // Still failing — try generic retry on last attempt
+          if (retry === this.config.maxRetries - 1) {
+            const genericPrompt = buildGenericRetryPrompt(originalPrompt, attempts);
+            const finalResponse = await provider.generate(genericPrompt, systemPrompt, options);
+            attempts++;
+
+            const finalExtraction = extractJson(finalResponse.content);
+            if (finalExtraction.success) {
+              const validation = this.validate(finalExtraction.json, schema);
+              if (validation.valid && validation.data) {
+                return { data: validation.data, response: finalResponse, attempts };
+              }
+            }
+          }
+          continue;
+        }
+
+        const validation = this.validate(extraction.json, schema);
+        if (validation.valid && validation.data) {
+          return { data: validation.data, response, attempts };
+        }
+
+        // Update error for next retry
+        if (validation.zodError) {
+          previousResponse = response;
+          error = validation.zodError;
+          errorType = 'schema';
+        }
+      } catch {
+        // Provider error during retry — continue to next attempt
+      }
+    }
+
+    return { attempts };
+  }
+
+  private validate(data: unknown, schema: ZodSchema<TOutput>): ValidationResult<TOutput> {
+    const result = schema.safeParse(data);
+    if (result.success) {
+      return { valid: true, data: result.data };
+    }
+    return {
+      valid: false,
+      zodError: result.error,
+      errors: result.error.errors.map((e) => `${e.path.join('.')}: ${e.message}`),
+    };
+  }
+
+  private buildSuccess(
+    data: TOutput,
+    response: LLMResponse,
+    validationAttempts: number
+  ): GenerationResult<TOutput> {
+    return {
+      success: true,
+      data,
+      metadata: {
+        model: response.model,
+        promptTokens: response.usage.promptTokens,
+        completionTokens: response.usage.completionTokens,
+        validationAttempts,
+      },
+    };
+  }
+
+  private buildError(
+    error: Error,
+    response?: LLMResponse,
+    validationAttempts?: number
+  ): GenerationResult<TOutput> {
+    const isProviderError = error instanceof LLMProviderError;
+
+    let code = 'GENERATION_FAILED';
+    let retryable = false;
+
+    if (isProviderError) {
+      code = error.code;
+      retryable = error.retryable;
+    } else if (error instanceof ZodError) {
+      code = 'VALIDATION_FAILED';
+      retryable = true;
+    }
+
+    const result: GenerationResult<TOutput> = {
+      success: false,
+      error: { code, message: error.message, retryable },
+    };
+
+    if (response) {
+      result.metadata = {
+        model: response.model,
+        promptTokens: response.usage.promptTokens,
+        completionTokens: response.usage.completionTokens,
+        validationAttempts: validationAttempts ?? 1,
+      };
+    }
+
+    return result;
+  }
+}