simple-ai-provider/dist/providers/claude.d.ts

A simple and extensible AI provider package for easy integration of multiple AI services

/**
 * Anthropic Claude AI Provider Implementation
 *
 * This module provides integration with Anthropic's Claude models through their official SDK.
 * Claude is known for its advanced reasoning capabilities, long context length, and excellent
 * performance on complex analytical tasks.
 *
 * Key Features:
 * - Support for all Claude 3.x model variants (Opus, Sonnet, Haiku)
 * - Native streaming support with real-time response chunks
 * - Advanced system message handling (separate from conversation context)
 * - Comprehensive error mapping for Anthropic-specific issues
 * - Automatic retry logic with exponential backoff
 *
 * Claude-Specific Considerations:
 * - System messages must be passed separately from conversation messages
 * - Uses "input_tokens" and "output_tokens" terminology instead of "prompt_tokens"
 * - Supports advanced features like function calling and vision (model-dependent)
 * - Has specific rate limiting and token usage patterns
 *
 * @author Jan-Marlon Leibl
 * @version 1.0.0
 * @see https://docs.anthropic.com/claude/reference/
 */
import type { AIProviderConfig, CompletionParams, CompletionResponse, CompletionChunk, ProviderInfo } from '../types/index.js';
import { BaseAIProvider } from './base.js';
/**
 * Configuration interface for Claude provider with Anthropic-specific options.
 *
 * @example
 * ```typescript
 * const config: ClaudeConfig = {
 *   apiKey: process.env.ANTHROPIC_API_KEY!,
 *   defaultModel: 'claude-3-5-sonnet-20241022',
 *   version: '2023-06-01',
 *   timeout: 60000,
 *   maxRetries: 3
 * };
 * ```
 */
export interface ClaudeConfig extends AIProviderConfig {
    /**
     * Default Claude model to use for requests.
     *
     * Recommended models:
     * - 'claude-3-5-sonnet-20241022': Best balance of capability and speed
     * - 'claude-3-5-haiku-20241022': Fastest responses, good for simple tasks
     * - 'claude-3-opus-20240229': Most capable, best for complex reasoning
     *
     * @default 'claude-3-5-sonnet-20241022'
     */
    defaultModel?: string;
    /**
     * Anthropic API version header value.
     *
     * This ensures compatibility with specific API features and response formats.
     * Check Anthropic's documentation for the latest version.
     *
     * @default '2023-06-01'
     * @see https://docs.anthropic.com/claude/reference/versioning
     */
    version?: string;
}
/**
 * Anthropic Claude AI provider implementation.
 *
 * This class handles all interactions with Anthropic's Claude models through
 * their official TypeScript SDK. It provides optimized handling of Claude's
 * unique features like separate system message processing and advanced
 * streaming capabilities.
 *
 * Usage Pattern:
 * 1. Create instance with configuration
 * 2. Call initialize() to set up client and validate connection
 * 3. Use complete() or stream() for text generation
 * 4. Handle any AIProviderError exceptions appropriately
 *
 * @example
 * ```typescript
 * const claude = new ClaudeProvider({
 *   apiKey: process.env.ANTHROPIC_API_KEY!,
 *   defaultModel: 'claude-3-5-sonnet-20241022'
 * });
 *
 * await claude.initialize();
 *
 * const response = await claude.complete({
 *   messages: [
 *     { role: 'system', content: 'You are a helpful assistant.' },
 *     { role: 'user', content: 'Explain quantum computing.' }
 *   ],
 *   maxTokens: 1000,
 *   temperature: 0.7
 * });
 * ```
 */
export declare class ClaudeProvider extends BaseAIProvider {
    /** Anthropic SDK client instance (initialized during doInitialize) */
    private client;
    /** Default model identifier for requests */
    private readonly defaultModel;
    /** API version for Anthropic requests */
    private readonly version;
    /**
     * Creates a new Claude provider instance.
     *
     * @param config - Claude-specific configuration options
     * @throws {AIProviderError} If configuration validation fails
     */
    constructor(config: ClaudeConfig);
    /**
     * Initializes the Claude provider by setting up the Anthropic client.
     *
     * This method:
     * 1. Creates the Anthropic SDK client with configuration
     * 2. Tests the connection with a minimal API call
     * 3. Validates API key permissions and model access
     *
     * @protected
     * @throws {Error} If client creation or connection validation fails
     */
    protected doInitialize(): Promise<void>;
    /**
     * Generates a text completion using Claude's message API.
     *
     * This method:
     * 1. Processes messages to separate system content
     * 2. Builds optimized request parameters
     * 3. Makes API call with error handling
     * 4. Formats response to standard interface
     *
     * @protected
     * @param params - Validated completion parameters
     * @returns Promise resolving to formatted completion response
     * @throws {Error} If API request fails
     */
    protected doComplete(params: CompletionParams): Promise<CompletionResponse>;
    /**
     * Generates a streaming text completion using Claude's streaming API.
     *
     * This method:
     * 1. Processes messages and builds streaming request
     * 2. Handles real-time stream chunks from Anthropic
     * 3. Yields formatted chunks with proper completion tracking
     * 4. Provides final usage statistics when stream completes
     *
     * @protected
     * @param params - Validated completion parameters
     * @returns AsyncIterable yielding completion chunks
     * @throws {Error} If streaming request fails
     */
    protected doStream(params: CompletionParams): AsyncIterable<CompletionChunk>;
    /**
     * Returns comprehensive information about the Claude provider.
     *
     * @returns Provider information including models, capabilities, and limits
     */
    getInfo(): ProviderInfo;
    /**
     * Validates the connection by making a minimal test request.
     *
     * @private
     * @throws {AIProviderError} If connection validation fails
     */
    private validateConnection;
    /**
     * Validates model name format for Claude models.
     *
     * @private
     * @param modelName - Model name to validate
     * @throws {AIProviderError} If model name format is invalid
     */
    private validateModelName;
    /**
     * Processes messages to separate system content from conversation.
     *
     * Claude requires system messages to be passed separately from the
     * conversation messages array. This method handles that transformation.
     *
     * @private
     * @param messages - Input messages array
     * @returns Processed messages with separated system content
     */
    private processMessages;
    /**
     * Builds optimized request parameters for Anthropic API.
     *
     * @private
     * @param params - Input completion parameters
     * @param system - Processed system content
     * @param messages - Processed conversation messages
     * @param stream - Whether to enable streaming
     * @returns Formatted request parameters
     */
    private buildRequestParams;
    /**
     * Processes streaming response chunks from Anthropic API.
     *
     * @private
     * @param stream - Anthropic streaming response
     * @returns AsyncIterable of formatted completion chunks
     */
    private processStreamChunks;
    /**
     * Formats Anthropic's completion response to our standard interface.
     *
     * @private
     * @param response - Raw Anthropic API response
     * @returns Formatted completion response
     * @throws {AIProviderError} If response format is unexpected
     */
    private formatCompletionResponse;
    /**
     * Handles and transforms Anthropic-specific errors.
     *
     * This method maps Anthropic's error responses to our standardized
     * error format, providing helpful context and suggestions.
     *
     * @private
     * @param error - Original error from Anthropic API
     * @returns Normalized AIProviderError
     */
    private handleAnthropicError;
}