simple-ai-provider
Version:
A simple and extensible AI provider package for easy integration of multiple AI services
204 lines (203 loc) • 7.46 kB
TypeScript
/**
* 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';
import { AIProviderError } from '../types/index.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<string>>;
/**
* 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<T = any>(params: CompletionParams<T>): AsyncIterable<CompletionChunk>;
/**
* Returns comprehensive information about the Claude provider.
*
* @returns Provider information including models, capabilities, and limits
*/
getInfo(): ProviderInfo;
protected getModelNamePatterns(): RegExp[];
protected sendValidationProbe(): Promise<void>;
protected providerErrorMessages(): Partial<Record<number, string>>;
protected mapProviderError(error: any): AIProviderError | null;
/**
* 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;
}