@startsimpli/llm 0.1.1

package/src/providers/anthropic.ts

@@ -0,0 +1,273 @@
+/**
+ * Anthropic Provider Implementation
+ *
+ * Uses native fetch to minimize dependencies.
+ * Supports Claude 4 and Claude 3.x models.
+ */
+
+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 AnthropicMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+interface AnthropicRequest {
+  model: string;
+  max_tokens: number;
+  messages: AnthropicMessage[];
+  system?: string;
+  temperature?: number;
+}
+
+interface AnthropicResponse {
+  id: string;
+  type: 'message';
+  role: 'assistant';
+  content: Array<{ type: 'text'; text: string }>;
+  model: string;
+  stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | null;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+  };
+}
+
+interface AnthropicErrorResponse {
+  type: 'error';
+  error: {
+    type: string;
+    message: string;
+  };
+}
+
+const ANTHROPIC_MODELS = [
+  'claude-opus-4-6',
+  'claude-opus-4-20250514',
+  'claude-sonnet-4-6',
+  'claude-sonnet-4-20250514',
+  'claude-3-5-sonnet-20241022',
+  'claude-3-5-haiku-20241022',
+  'claude-3-opus-20240229',
+  'claude-3-sonnet-20240229',
+  'claude-3-haiku-20240307',
+] as const;
+
+const MODEL_COSTS: Record<string, { input: number; output: number }> = {
+  'claude-opus-4-6': { input: 0.015, output: 0.075 },
+  'claude-opus-4-20250514': { input: 0.015, output: 0.075 },
+  'claude-sonnet-4-6': { input: 0.003, output: 0.015 },
+  'claude-sonnet-4-20250514': { input: 0.003, output: 0.015 },
+  'claude-3-5-sonnet-20241022': { input: 0.003, output: 0.015 },
+  'claude-3-5-haiku-20241022': { input: 0.0008, output: 0.004 },
+  'claude-3-opus-20240229': { input: 0.015, output: 0.075 },
+  'claude-3-sonnet-20240229': { input: 0.003, output: 0.015 },
+  'claude-3-haiku-20240307': { input: 0.00025, output: 0.00125 },
+};
+
+const DEFAULTS = {
+  baseUrl: 'https://api.anthropic.com/v1',
+  model: LLM_DEFAULTS.anthropicModel,
+  temperature: LLM_DEFAULTS.temperature,
+  maxTokens: LLM_DEFAULTS.maxTokens,
+  timeoutMs: LLM_DEFAULTS.timeoutMs,
+  apiVersion: '2023-06-01',
+};
+
+export class AnthropicProvider implements ILLMProvider {
+  readonly name = 'anthropic';
+  readonly availableModels = ANTHROPIC_MODELS;
+  readonly defaultModel: string;
+
+  private readonly config: Required<ProviderConfig>;
+  private readonly apiVersion: string;
+
+  constructor(config: ProviderConfig, apiVersion?: string) {
+    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;
+    this.apiVersion = apiVersion ?? DEFAULTS.apiVersion;
+  }
+
+  isAvailable(): boolean {
+    return Boolean(this.config.apiKey);
+  }
+
+  async generate(
+    userPrompt: string,
+    systemPrompt: string,
+    options?: GenerateOptions
+  ): Promise<LLMResponse> {
+    if (!this.isAvailable()) {
+      throw new LLMProviderError(
+        'Anthropic API key not configured',
+        'AUTHENTICATION_ERROR',
+        false,
+        undefined,
+        this.name
+      );
+    }
+
+    const model = options?.model ?? this.config.defaultModel;
+    const temperature = options?.temperature ?? this.config.defaultTemperature;
+    const maxTokens = options?.maxTokens ?? this.config.defaultMaxTokens;
+    const timeout = options?.timeout ?? this.config.timeoutMs;
+
+    // Wrap user prompt to request JSON output
+    const jsonWrappedPrompt = `${userPrompt}
+
+Please respond with a valid JSON object only. Do not include any text before or after the JSON.`;
+
+    const requestBody: AnthropicRequest = {
+      model,
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: jsonWrappedPrompt }],
+      system: systemPrompt,
+      temperature,
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await fetch(`${this.config.baseUrl}/messages`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.config.apiKey,
+          'anthropic-version': this.apiVersion,
+        },
+        body: JSON.stringify(requestBody),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({
+          error: { type: 'unknown', message: 'Unknown error' },
+        }))) as AnthropicErrorResponse;
+        throw this.handleApiError(response.status, errorData);
+      }
+
+      const data = (await response.json()) as AnthropicResponse;
+
+      const textContent = data.content.find((c) => c.type === 'text');
+      if (!textContent?.text) {
+        throw new LLMProviderError(
+          'Empty response from Anthropic',
+          'UNKNOWN_ERROR',
+          true,
+          undefined,
+          this.name
+        );
+      }
+
+      return {
+        content: textContent.text,
+        usage: {
+          promptTokens: data.usage.input_tokens,
+          completionTokens: data.usage.output_tokens,
+          totalTokens: data.usage.input_tokens + data.usage.output_tokens,
+        },
+        model: data.model,
+        responseId: data.id,
+        finishReason: data.stop_reason ?? undefined,
+      };
+    } 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(
+        `Anthropic 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: AnthropicErrorResponse
+  ): LLMProviderError {
+    const message = errorResponse.error?.message ?? 'Unknown Anthropic error';
+    const errorType = errorResponse.error?.type ?? '';
+
+    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 (errorType === 'invalid_request_error') {
+        code = (message.includes('token') || message.includes('length'))
+          ? 'CONTEXT_LENGTH_EXCEEDED'
+          : 'INVALID_REQUEST';
+      } else {
+        code = 'UNKNOWN_ERROR';
+      }
+    } else if (statusCode === 403) {
+      code = 'AUTHENTICATION_ERROR';
+    } else if (statusCode === 529 || statusCode >= 500) {
+      code = 'SERVICE_UNAVAILABLE';
+      retryable = true;
+    } else {
+      code = 'UNKNOWN_ERROR';
+    }
+
+    return new LLMProviderError(message, code, retryable, statusCode, this.name);
+  }
+}
+
+/**
+ * Create an Anthropic provider from environment variables.
+ * Returns null if ANTHROPIC_API_KEY is not set.
+ */
+export function createAnthropicProvider(): AnthropicProvider | null {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) return null;
+
+  return new AnthropicProvider({
+    apiKey,
+    baseUrl: process.env.ANTHROPIC_BASE_URL,
+    defaultModel: process.env.ANTHROPIC_MODEL,
+  });
+}

package/src/providers/interface.ts

@@ -0,0 +1,44 @@
+import type { LLMResponse, GenerateOptions } from '../types';
+
+/**
+ * Contract that every LLM provider must implement.
+ *
+ * Generic over nothing — the provider just takes string prompts and returns
+ * string content. Domain-specific parsing/validation lives in the service layer.
+ */
+export interface ILLMProvider {
+  /** Unique identifier for the provider (e.g. 'openai', 'anthropic') */
+  readonly name: string;
+
+  /** List of available models */
+  readonly availableModels: readonly string[];
+
+  /** Default model for this provider */
+  readonly defaultModel: string;
+
+  /**
+   * Send a prompt pair to the LLM and return the raw response.
+   *
+   * @param userPrompt - The user's message / generation request
+   * @param systemPrompt - System-level instructions
+   * @param options - Generation options (model, temperature, etc.)
+   */
+  generate(
+    userPrompt: string,
+    systemPrompt: string,
+    options?: GenerateOptions
+  ): Promise<LLMResponse>;
+
+  /** Check if the provider is properly configured and available */
+  isAvailable(): boolean;
+
+  /**
+   * Estimate cost for a request (in USD).
+   * Returns undefined if cost cannot be estimated.
+   */
+  estimateCost?(
+    promptTokens: number,
+    completionTokens: number,
+    model?: string
+  ): number | undefined;
+}

package/src/providers/mock.ts

@@ -0,0 +1,134 @@
+/**
+ * Mock LLM Provider for Testing
+ *
+ * Provides deterministic responses for testing.
+ * Can simulate errors, delays, and custom responses.
+ */
+
+import type { ILLMProvider } from './interface';
+import type { LLMResponse, GenerateOptions } from '../types';
+import { LLMProviderError } from '../errors';
+
+export interface MockBehavior {
+  /** Delay before responding (ms) */
+  delay?: number;
+  /** Simulate an error */
+  error?: {
+    code: 'RATE_LIMITED' | 'SERVICE_UNAVAILABLE' | 'CONTENT_FILTERED' | 'TIMEOUT';
+    message: string;
+  };
+  /** Return invalid JSON (for validation retry testing) */
+  returnInvalidJson?: boolean;
+  /** Custom response content string */
+  customResponse?: string;
+}
+
+// Global mock behavior that can be set in tests
+let mockBehavior: MockBehavior = {};
+
+/**
+ * Set mock behavior for testing.
+ */
+export function setMockBehavior(behavior: MockBehavior) {
+  mockBehavior = behavior;
+}
+
+/**
+ * Reset mock behavior to defaults.
+ */
+export function resetMockBehavior() {
+  mockBehavior = {};
+}
+
+/**
+ * Default valid JSON response for when no custom response is configured.
+ * Returns a minimal valid JSON object — domain-specific schemas should override via customResponse.
+ */
+function getDefaultResponse(): string {
+  return JSON.stringify({ mock: true, timestamp: new Date().toISOString() });
+}
+
+/**
+ * Default invalid JSON response for testing validation retries.
+ */
+function getInvalidResponse(): string {
+  return JSON.stringify({ incomplete: true });
+}
+
+export class MockLLMProvider implements ILLMProvider {
+  readonly name = 'mock';
+  readonly availableModels = ['mock-model-1', 'mock-model-2'] as const;
+  readonly defaultModel = 'mock-model-1';
+
+  private callCount = 0;
+
+  async generate(
+    _userPrompt: string,
+    _systemPrompt: string,
+    _options?: GenerateOptions
+  ): Promise<LLMResponse> {
+    this.callCount++;
+
+    if (mockBehavior.error) {
+      throw new LLMProviderError(
+        mockBehavior.error.message,
+        mockBehavior.error.code,
+        mockBehavior.error.code === 'RATE_LIMITED',
+        mockBehavior.error.code === 'RATE_LIMITED' ? 429 : 503,
+        'mock'
+      );
+    }
+
+    if (mockBehavior.delay) {
+      await new Promise((resolve) => setTimeout(resolve, mockBehavior.delay));
+    }
+
+    if (mockBehavior.customResponse) {
+      return {
+        content: mockBehavior.customResponse,
+        usage: { promptTokens: 100, completionTokens: 500, totalTokens: 600 },
+        model: this.defaultModel,
+        responseId: `mock-${this.callCount}`,
+        finishReason: 'stop',
+      };
+    }
+
+    if (mockBehavior.returnInvalidJson) {
+      return {
+        content: getInvalidResponse(),
+        usage: { promptTokens: 100, completionTokens: 200, totalTokens: 300 },
+        model: this.defaultModel,
+        responseId: `mock-${this.callCount}`,
+        finishReason: 'stop',
+      };
+    }
+
+    return {
+      content: getDefaultResponse(),
+      usage: { promptTokens: 150, completionTokens: 800, totalTokens: 950 },
+      model: this.defaultModel,
+      responseId: `mock-${this.callCount}`,
+      finishReason: 'stop',
+    };
+  }
+
+  isAvailable(): boolean {
+    return true;
+  }
+
+  estimateCost(
+    promptTokens: number,
+    completionTokens: number,
+    _model?: string
+  ): number {
+    return (promptTokens + completionTokens) * 0.00001;
+  }
+
+  getCallCount(): number {
+    return this.callCount;
+  }
+
+  resetCallCount(): void {
+    this.callCount = 0;
+  }
+}