@startsimpli/llm 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,353 @@
+import { ZodError, ZodSchema } from 'zod';
+
+/**
+ * LLM error codes for classifying provider failures.
+ */
+type LLMErrorCode = 'RATE_LIMITED' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST' | 'CONTEXT_LENGTH_EXCEEDED' | 'CONTENT_FILTERED' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | 'PARSE_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Typed error for LLM provider failures.
+ * Carries a machine-readable code and a retryable flag so callers can
+ * decide whether to retry or surface the error to the user.
+ */
+declare class LLMProviderError extends Error {
+    readonly code: LLMErrorCode;
+    readonly retryable: boolean;
+    readonly statusCode?: number | undefined;
+    readonly provider?: string | undefined;
+    constructor(message: string, code: LLMErrorCode, retryable?: boolean, statusCode?: number | undefined, provider?: string | undefined);
+}
+
+/**
+ * Token usage statistics returned by every provider call.
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Raw response envelope from an LLM provider.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+interface JsonExtractionResult {
+    success: boolean;
+    json?: unknown;
+    error?: string;
+    raw: string;
+}
+/**
+ * Generic validation result — parameterized over the domain data type.
+ */
+interface ValidationResult<T> {
+    valid: boolean;
+    data?: T;
+    zodError?: ZodError;
+    errors?: string[];
+}
+/**
+ * Configuration for the generic LLMService.
+ */
+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.
+ */
+declare const LLM_DEFAULTS: {
+    readonly openaiModel: "gpt-4o-mini";
+    readonly 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.
+     */
+    readonly temperature: 0.7;
+    readonly maxTokens: 8192;
+    readonly timeoutMs: 60000;
+};
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * 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)
+ */
+
+declare class OpenAIProvider implements ILLMProvider {
+    readonly name = "openai";
+    readonly availableModels: readonly ["gpt-5.2", "gpt-5.1", "gpt-5", "gpt-4o", "gpt-4o-mini"];
+    readonly defaultModel: string;
+    private readonly config;
+    constructor(config: ProviderConfig);
+    isAvailable(): boolean;
+    generate(userPrompt: string, systemPrompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    estimateCost(promptTokens: number, completionTokens: number, model?: string): number | undefined;
+    private handleApiError;
+}
+/**
+ * Create an OpenAI provider from environment variables.
+ * Returns null if OPENAI_API_KEY is not set.
+ */
+declare function createOpenAIProvider(): OpenAIProvider | null;
+
+/**
+ * Anthropic Provider Implementation
+ *
+ * Uses native fetch to minimize dependencies.
+ * Supports Claude 4 and Claude 3.x models.
+ */
+
+declare class AnthropicProvider implements ILLMProvider {
+    readonly name = "anthropic";
+    readonly availableModels: readonly ["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"];
+    readonly defaultModel: string;
+    private readonly config;
+    private readonly apiVersion;
+    constructor(config: ProviderConfig, apiVersion?: string);
+    isAvailable(): boolean;
+    generate(userPrompt: string, systemPrompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    estimateCost(promptTokens: number, completionTokens: number, model?: string): number | undefined;
+    private handleApiError;
+}
+/**
+ * Create an Anthropic provider from environment variables.
+ * Returns null if ANTHROPIC_API_KEY is not set.
+ */
+declare function createAnthropicProvider(): AnthropicProvider | null;
+
+/**
+ * Mock LLM Provider for Testing
+ *
+ * Provides deterministic responses for testing.
+ * Can simulate errors, delays, and custom responses.
+ */
+
+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;
+}
+/**
+ * Set mock behavior for testing.
+ */
+declare function setMockBehavior(behavior: MockBehavior): void;
+/**
+ * Reset mock behavior to defaults.
+ */
+declare function resetMockBehavior(): void;
+declare class MockLLMProvider implements ILLMProvider {
+    readonly name = "mock";
+    readonly availableModels: readonly ["mock-model-1", "mock-model-2"];
+    readonly defaultModel = "mock-model-1";
+    private callCount;
+    generate(_userPrompt: string, _systemPrompt: string, _options?: GenerateOptions): Promise<LLMResponse>;
+    isAvailable(): boolean;
+    estimateCost(promptTokens: number, completionTokens: number, _model?: string): number;
+    getCallCount(): number;
+    resetCallCount(): void;
+}
+
+/**
+ * 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 ({ ... })
+ */
+declare function extractJson(content: string): JsonExtractionResult;
+
+/**
+ * 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.
+ */
+declare function llmErrorToHttpStatus(code: LLMErrorCode | string): number;
+
+/**
+ * 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.
+ */
+declare function buildSchemaErrorCorrectionPrompt(previousResponse: string, zodError: ZodError): string;
+/**
+ * Build a correction prompt for JSON parsing errors.
+ *
+ * Domain-agnostic: accepts the raw response and a parse error message.
+ */
+declare function buildParseErrorCorrectionPrompt(previousResponse: string, parseError: string): string;
+/**
+ * Build a generic retry prompt when all corrections have failed.
+ *
+ * Domain-agnostic: just re-states the original request and asks for a simpler output.
+ */
+declare function buildGenericRetryPrompt(originalPrompt: string, attemptNumber: number): string;
+
+/**
+ * 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.
+ */
+
+/**
+ * Metadata about a generation attempt (tokens, model, retries).
+ */
+interface GenerationMetadata {
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    validationAttempts: number;
+}
+/**
+ * Result of a validated generation. The caller checks `success` to narrow the union.
+ */
+type GenerationResult<TOutput> = {
+    success: true;
+    data: TOutput;
+    metadata: GenerationMetadata;
+} | {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+    metadata?: GenerationMetadata;
+};
+/**
+ * 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.
+ */
+declare class LLMService<TOutput> {
+    private readonly config;
+    private readonly providers;
+    constructor(config?: LLMServiceConfig);
+    private initializeProviders;
+    private getProvider;
+    /** Check if any LLM provider is available. */
+    isAvailable(): boolean;
+    /** Get list of available provider names. */
+    getAvailableProviders(): string[];
+    /**
+     * Simple chat-style generation with no schema validation.
+     * Returns the raw LLM response.
+     */
+    chat(userPrompt: string, systemPrompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    /**
+     * 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
+     */
+    generate(userPrompt: string, systemPrompt: string, schema: ZodSchema<TOutput>, options?: GenerateOptions): Promise<GenerationResult<TOutput>>;
+    /**
+     * Register an additional provider instance (useful for custom/third-party providers).
+     */
+    registerProvider(name: string, provider: ILLMProvider): void;
+    private retryWithCorrection;
+    private validate;
+    private buildSuccess;
+    private buildError;
+}
+
+export { AnthropicProvider, type GenerateOptions, type GenerationMetadata, type GenerationResult, type ILLMProvider, type JsonExtractionResult, type LLMErrorCode, LLMProviderError, type LLMResponse, LLMService, type LLMServiceConfig, LLM_DEFAULTS, type MockBehavior, MockLLMProvider, OpenAIProvider, type ProviderConfig, type TokenUsage, type ValidationResult, buildGenericRetryPrompt, buildParseErrorCorrectionPrompt, buildSchemaErrorCorrectionPrompt, createAnthropicProvider, createOpenAIProvider, extractJson, llmErrorToHttpStatus, resetMockBehavior, setMockBehavior };

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+import { ZodError, ZodSchema } from 'zod';
+
+/**
+ * LLM error codes for classifying provider failures.
+ */
+type LLMErrorCode = 'RATE_LIMITED' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST' | 'CONTEXT_LENGTH_EXCEEDED' | 'CONTENT_FILTERED' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | 'PARSE_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Typed error for LLM provider failures.
+ * Carries a machine-readable code and a retryable flag so callers can
+ * decide whether to retry or surface the error to the user.
+ */
+declare class LLMProviderError extends Error {
+    readonly code: LLMErrorCode;
+    readonly retryable: boolean;
+    readonly statusCode?: number | undefined;
+    readonly provider?: string | undefined;
+    constructor(message: string, code: LLMErrorCode, retryable?: boolean, statusCode?: number | undefined, provider?: string | undefined);
+}
+
+/**
+ * Token usage statistics returned by every provider call.
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Raw response envelope from an LLM provider.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+interface JsonExtractionResult {
+    success: boolean;
+    json?: unknown;
+    error?: string;
+    raw: string;
+}
+/**
+ * Generic validation result — parameterized over the domain data type.
+ */
+interface ValidationResult<T> {
+    valid: boolean;
+    data?: T;
+    zodError?: ZodError;
+    errors?: string[];
+}
+/**
+ * Configuration for the generic LLMService.
+ */
+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.
+ */
+declare const LLM_DEFAULTS: {
+    readonly openaiModel: "gpt-4o-mini";
+    readonly 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.
+     */
+    readonly temperature: 0.7;
+    readonly maxTokens: 8192;
+    readonly timeoutMs: 60000;
+};
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * 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)
+ */
+
+declare class OpenAIProvider implements ILLMProvider {
+    readonly name = "openai";
+    readonly availableModels: readonly ["gpt-5.2", "gpt-5.1", "gpt-5", "gpt-4o", "gpt-4o-mini"];
+    readonly defaultModel: string;
+    private readonly config;
+    constructor(config: ProviderConfig);
+    isAvailable(): boolean;
+    generate(userPrompt: string, systemPrompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    estimateCost(promptTokens: number, completionTokens: number, model?: string): number | undefined;
+    private handleApiError;
+}
+/**
+ * Create an OpenAI provider from environment variables.
+ * Returns null if OPENAI_API_KEY is not set.
+ */
+declare function createOpenAIProvider(): OpenAIProvider | null;
+
+/**
+ * Anthropic Provider Implementation
+ *
+ * Uses native fetch to minimize dependencies.
+ * Supports Claude 4 and Claude 3.x models.
+ */
+
+declare class AnthropicProvider implements ILLMProvider {
+    readonly name = "anthropic";
+    readonly availableModels: readonly ["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"];
+    readonly defaultModel: string;
+    private readonly config;
+    private readonly apiVersion;
+    constructor(config: ProviderConfig, apiVersion?: string);
+    isAvailable(): boolean;
+    generate(userPrompt: string, systemPrompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    estimateCost(promptTokens: number, completionTokens: number, model?: string): number | undefined;
+    private handleApiError;
+}
+/**
+ * Create an Anthropic provider from environment variables.
+ * Returns null if ANTHROPIC_API_KEY is not set.
+ */
+declare function createAnthropicProvider(): AnthropicProvider | null;
+
+/**
+ * Mock LLM Provider for Testing
+ *
+ * Provides deterministic responses for testing.
+ * Can simulate errors, delays, and custom responses.
+ */
+
+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;
+}
+/**
+ * Set mock behavior for testing.
+ */
+declare function setMockBehavior(behavior: MockBehavior): void;
+/**
+ * Reset mock behavior to defaults.
+ */
+declare function resetMockBehavior(): void;
+declare class MockLLMProvider implements ILLMProvider {
+    readonly name = "mock";
+    readonly availableModels: readonly ["mock-model-1", "mock-model-2"];
+    readonly defaultModel = "mock-model-1";
+    private callCount;
+    generate(_userPrompt: string, _systemPrompt: string, _options?: GenerateOptions): Promise<LLMResponse>;
+    isAvailable(): boolean;
+    estimateCost(promptTokens: number, completionTokens: number, _model?: string): number;
+    getCallCount(): number;
+    resetCallCount(): void;
+}
+
+/**
+ * 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 ({ ... })
+ */
+declare function extractJson(content: string): JsonExtractionResult;
+
+/**
+ * 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.
+ */
+declare function llmErrorToHttpStatus(code: LLMErrorCode | string): number;
+
+/**
+ * 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.
+ */
+declare function buildSchemaErrorCorrectionPrompt(previousResponse: string, zodError: ZodError): string;
+/**
+ * Build a correction prompt for JSON parsing errors.
+ *
+ * Domain-agnostic: accepts the raw response and a parse error message.
+ */
+declare function buildParseErrorCorrectionPrompt(previousResponse: string, parseError: string): string;
+/**
+ * Build a generic retry prompt when all corrections have failed.
+ *
+ * Domain-agnostic: just re-states the original request and asks for a simpler output.
+ */
+declare function buildGenericRetryPrompt(originalPrompt: string, attemptNumber: number): string;
+
+/**
+ * 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.
+ */
+
+/**
+ * Metadata about a generation attempt (tokens, model, retries).
+ */
+interface GenerationMetadata {
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    validationAttempts: number;
+}
+/**
+ * Result of a validated generation. The caller checks `success` to narrow the union.
+ */
+type GenerationResult<TOutput> = {
+    success: true;
+    data: TOutput;
+    metadata: GenerationMetadata;
+} | {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+    metadata?: GenerationMetadata;
+};
+/**
+ * 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.
+ */
+declare class LLMService<TOutput> {
+    private readonly config;
+    private readonly providers;
+    constructor(config?: LLMServiceConfig);
+    private initializeProviders;
+    private getProvider;
+    /** Check if any LLM provider is available. */
+    isAvailable(): boolean;
+    /** Get list of available provider names. */
+    getAvailableProviders(): string[];
+    /**
+     * Simple chat-style generation with no schema validation.
+     * Returns the raw LLM response.
+     */
+    chat(userPrompt: string, systemPrompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    /**
+     * 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
+     */
+    generate(userPrompt: string, systemPrompt: string, schema: ZodSchema<TOutput>, options?: GenerateOptions): Promise<GenerationResult<TOutput>>;
+    /**
+     * Register an additional provider instance (useful for custom/third-party providers).
+     */
+    registerProvider(name: string, provider: ILLMProvider): void;
+    private retryWithCorrection;
+    private validate;
+    private buildSuccess;
+    private buildError;
+}
+
+export { AnthropicProvider, type GenerateOptions, type GenerationMetadata, type GenerationResult, type ILLMProvider, type JsonExtractionResult, type LLMErrorCode, LLMProviderError, type LLMResponse, LLMService, type LLMServiceConfig, LLM_DEFAULTS, type MockBehavior, MockLLMProvider, OpenAIProvider, type ProviderConfig, type TokenUsage, type ValidationResult, buildGenericRetryPrompt, buildParseErrorCorrectionPrompt, buildSchemaErrorCorrectionPrompt, createAnthropicProvider, createOpenAIProvider, extractJson, llmErrorToHttpStatus, resetMockBehavior, setMockBehavior };