@startsimpli/llm 0.1.1

package/src/types.ts

@@ -0,0 +1,107 @@
+import type { ZodError } from 'zod';
+
+/**
+ * Token usage statistics returned by every provider call.
+ */
+export interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+/**
+ * Raw response envelope from an LLM provider.
+ */
+export interface LLMResponse {
+  /** The raw text content from the LLM */
+  content: string;
+  /** Token usage statistics */
+  usage: TokenUsage;
+  /** Model identifier used for generation */
+  model: string;
+  /** Response ID for debugging/logging */
+  responseId?: string;
+  /** Finish reason (e.g., 'stop', 'length', 'content_filter') */
+  finishReason?: string;
+}
+
+/**
+ * Options passed through to the provider for a single generation call.
+ */
+export interface GenerateOptions {
+  /** Model to use (provider-specific) */
+  model?: string;
+  /** Temperature for response randomness (0-1) */
+  temperature?: number;
+  /** Maximum tokens in response */
+  maxTokens?: number;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** Arbitrary extra data the caller wants to thread through (e.g. domain preferences) */
+  extra?: Record<string, unknown>;
+}
+
+/**
+ * Provider configuration — everything needed to construct a provider instance.
+ */
+export interface ProviderConfig {
+  apiKey: string;
+  baseUrl?: string;
+  defaultModel?: string;
+  defaultTemperature?: number;
+  defaultMaxTokens?: number;
+  timeoutMs?: number;
+}
+
+/**
+ * Result of attempting to extract JSON from an LLM response string.
+ */
+export interface JsonExtractionResult {
+  success: boolean;
+  json?: unknown;
+  error?: string;
+  raw: string;
+}
+
+/**
+ * Generic validation result — parameterized over the domain data type.
+ */
+export interface ValidationResult<T> {
+  valid: boolean;
+  data?: T;
+  zodError?: ZodError;
+  errors?: string[];
+}
+
+/**
+ * Configuration for the generic LLMService.
+ */
+export interface LLMServiceConfig {
+  /** Maximum number of retry attempts for validation failures */
+  maxRetries?: number;
+  /** Preferred provider (will fallback to available if not configured) */
+  preferredProvider?: 'openai' | 'anthropic' | 'mock';
+  /** Default model override */
+  defaultModel?: string;
+  /** Default temperature */
+  defaultTemperature?: number;
+  /** Default max tokens */
+  defaultMaxTokens?: number;
+}
+
+/**
+ * Default LLM configuration values.
+ * Apps can override these via LLMServiceConfig or environment variables.
+ */
+export const LLM_DEFAULTS = {
+  openaiModel: 'gpt-4o-mini',
+  anthropicModel: 'claude-sonnet-4-20250514',
+  /**
+   * Default sampling temperature.
+   * Note: base gpt-5 models (gpt-5, gpt-5.1, gpt-5.2) require temperature=1.0
+   * and the OpenAI provider enforces this automatically.
+   */
+  temperature: 0.7,
+  maxTokens: 8192,
+  timeoutMs: 60000,
+} as const;

package/src/utils/http-status.ts

@@ -0,0 +1,25 @@
+import type { LLMErrorCode } from '../errors'
+
+/**
+ * Maps an LLM error code to an HTTP status code.
+ * Use this in Next.js API routes to return appropriate HTTP responses
+ * when an LLM generation call fails.
+ */
+export function llmErrorToHttpStatus(code: LLMErrorCode | string): number {
+  switch (code) {
+    case 'RATE_LIMITED':
+      return 429
+    case 'CONTENT_FILTERED':
+    case 'INVALID_REQUEST':
+      return 400
+    case 'AUTHENTICATION_ERROR':
+    case 'SERVICE_UNAVAILABLE':
+      return 503
+    case 'TIMEOUT':
+      return 504
+    case 'CONTEXT_LENGTH_EXCEEDED':
+      return 422
+    default:
+      return 500
+  }
+}

package/src/utils/json-extraction.ts

@@ -0,0 +1,60 @@
+import type { JsonExtractionResult } from '../types';
+
+/**
+ * Extract a JSON object from LLM response content.
+ *
+ * Tries three strategies in order:
+ * 1. Direct JSON.parse of the trimmed content
+ * 2. Extract from markdown code blocks (```json ... ```)
+ * 3. Find JSON object boundaries ({ ... })
+ */
+export function extractJson(content: string): JsonExtractionResult {
+  const trimmed = content.trim();
+
+  // Strategy 1: direct parse
+  try {
+    const json = JSON.parse(trimmed);
+    return { success: true, json, raw: trimmed };
+  } catch {
+    // continue to extraction strategies
+  }
+
+  // Strategy 2: markdown code blocks
+  const codeBlockMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+  if (codeBlockMatch) {
+    try {
+      const json = JSON.parse(codeBlockMatch[1].trim());
+      return { success: true, json, raw: codeBlockMatch[1].trim() };
+    } catch (e) {
+      return {
+        success: false,
+        error: `JSON in code block is invalid: ${e instanceof Error ? e.message : 'Parse error'}`,
+        raw: trimmed,
+      };
+    }
+  }
+
+  // Strategy 3: find JSON object boundaries
+  const firstBrace = trimmed.indexOf('{');
+  const lastBrace = trimmed.lastIndexOf('}');
+
+  if (firstBrace !== -1 && lastBrace > firstBrace) {
+    const jsonCandidate = trimmed.slice(firstBrace, lastBrace + 1);
+    try {
+      const json = JSON.parse(jsonCandidate);
+      return { success: true, json, raw: jsonCandidate };
+    } catch (e) {
+      return {
+        success: false,
+        error: `Found JSON-like content but it's invalid: ${e instanceof Error ? e.message : 'Parse error'}`,
+        raw: trimmed,
+      };
+    }
+  }
+
+  return {
+    success: false,
+    error: 'No valid JSON object found in response',
+    raw: trimmed,
+  };
+}

package/src/utils/retry.ts

@@ -0,0 +1,122 @@
+import type { ZodError } from 'zod';
+
+/**
+ * Build a correction prompt for schema validation errors.
+ *
+ * Domain-agnostic: accepts the raw previous response and a ZodError,
+ * formats them into a prompt asking the LLM to fix specific field errors.
+ */
+export function buildSchemaErrorCorrectionPrompt(
+  previousResponse: string,
+  zodError: ZodError
+): string {
+  const errorDetails = zodError.errors
+    .map((e) => {
+      const path = e.path.length > 0 ? e.path.join('.') : 'root';
+      return `- Path "${path}": ${e.message}`;
+    })
+    .join('\n');
+
+  return `Your previous response contained JSON that did not conform to the required schema.
+
+## Previous Response
+
+\`\`\`json
+${previousResponse}
+\`\`\`
+
+## Validation Errors
+
+The following schema validation errors were found:
+
+${errorDetails}
+
+## Instructions
+
+Please generate a corrected JSON response that:
+1. Fixes ALL the validation errors listed above
+2. Maintains the same content and intent
+3. Follows the exact schema structure required
+4. Contains ONLY valid JSON with no text before or after
+
+Common fixes needed:
+- Ensure all required fields are present
+- Check that enum values match the schema exactly
+- Verify number fields contain numbers, not strings
+- Ensure arrays are not empty where minimum length is 1
+- Check that nested objects have all required properties
+
+Respond with ONLY the corrected JSON object.`;
+}
+
+/**
+ * Build a correction prompt for JSON parsing errors.
+ *
+ * Domain-agnostic: accepts the raw response and a parse error message.
+ */
+export function buildParseErrorCorrectionPrompt(
+  previousResponse: string,
+  parseError: string
+): string {
+  const truncatedResponse =
+    previousResponse.length > 2000
+      ? previousResponse.slice(0, 2000) + '\n... [truncated]'
+      : previousResponse;
+
+  return `Your previous response could not be parsed as valid JSON.
+
+## Previous Response (excerpt)
+
+\`\`\`
+${truncatedResponse}
+\`\`\`
+
+## Parse Error
+
+${parseError}
+
+## Instructions
+
+Please generate a valid JSON response that:
+1. Contains ONLY the JSON object - no markdown, no explanations
+2. Does not wrap the JSON in code blocks
+3. Uses proper JSON syntax (double quotes for strings, no trailing commas)
+4. Properly escapes any special characters in strings
+
+Common JSON issues:
+- Using single quotes instead of double quotes
+- Trailing commas after the last item in arrays/objects
+- Unescaped special characters in strings (\\n, \\t, \\\", etc.)
+- Missing commas between object properties
+- Extra text before or after the JSON
+
+Respond with ONLY the corrected JSON object.`;
+}
+
+/**
+ * Build a generic retry prompt when all corrections have failed.
+ *
+ * Domain-agnostic: just re-states the original request and asks for a simpler output.
+ */
+export function buildGenericRetryPrompt(
+  originalPrompt: string,
+  attemptNumber: number
+): string {
+  return `The previous attempt to generate a response encountered issues. This is attempt ${attemptNumber}.
+
+## Original Request
+
+${originalPrompt}
+
+## Instructions
+
+Please generate a fresh response that:
+1. Follows the exact JSON schema structure
+2. Contains only valid, parseable JSON
+3. Includes all required fields
+4. Has accurate data throughout
+
+Focus on generating a complete, valid response rather than a complex one. A simpler response that is fully valid is better than a complex one with errors.
+
+Respond with ONLY the JSON object.`;
+}