feat: add initial implementation of Simple AI Provider package

2025-05-28 11:54:24 +02:00
commit 42902445fb
15 changed files with 1616 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,284 @@
+# Simple AI Provider
+
+A professional, extensible TypeScript package for integrating multiple AI providers into your applications with a unified interface. Currently supports Claude (Anthropic) with plans to add more providers.
+
+## Features
+
+- 🎯 **Unified Interface**: Same API across all AI providers
+- 🔒 **Type-Safe**: Full TypeScript support with comprehensive type definitions
+- 🚀 **Easy to Use**: Simple factory functions and intuitive configuration
+- 📡 **Streaming Support**: Real-time streaming responses where supported
+- 🛡️ **Error Handling**: Robust error handling with categorized error types
+- 🔧 **Extensible**: Easy to add new AI providers
+- 📦 **Modern**: Built with ES modules and modern JavaScript features
+
+## Installation
+
+```bash
+npm install simple-ai-provider
+# or
+yarn add simple-ai-provider
+# or
+bun add simple-ai-provider
+```
+
+## Quick Start
+
+### Basic Usage with Claude
+
+```typescript
+import { createClaudeProvider } from 'simple-ai-provider';
+
+// Create a Claude provider
+const claude = createClaudeProvider('your-anthropic-api-key');
+
+// Initialize the provider
+await claude.initialize();
+
+// Generate a completion
+const response = await claude.complete({
+  messages: [
+    { role: 'user', content: 'Hello! How are you today?' }
+  ],
+  maxTokens: 100,
+  temperature: 0.7
+});
+
+console.log(response.content);
+```
+
+### Streaming Responses
+
+```typescript
+import { createClaudeProvider } from 'simple-ai-provider';
+
+const claude = createClaudeProvider('your-anthropic-api-key');
+await claude.initialize();
+
+// Stream a completion
+for await (const chunk of claude.stream({
+  messages: [
+    { role: 'user', content: 'Write a short story about a robot.' }
+  ],
+  maxTokens: 500
+})) {
+  if (!chunk.isComplete) {
+    process.stdout.write(chunk.content);
+  } else {
+    console.log('\n\nUsage:', chunk.usage);
+  }
+}
+```
+
+### Advanced Configuration
+
+```typescript
+import { ClaudeProvider } from 'simple-ai-provider';
+
+const claude = new ClaudeProvider({
+  apiKey: 'your-anthropic-api-key',
+  defaultModel: 'claude-3-5-sonnet-20241022',
+  timeout: 30000,
+  maxRetries: 3,
+  baseUrl: 'https://api.anthropic.com' // optional custom endpoint
+});
+
+await claude.initialize();
+
+const response = await claude.complete({
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Explain quantum computing in simple terms.' }
+  ],
+  model: 'claude-3-5-haiku-20241022',
+  maxTokens: 300,
+  temperature: 0.5,
+  topP: 0.9,
+  stopSequences: ['\n\n']
+});
+```
+
+## API Reference
+
+### Core Types
+
+#### `AIMessage`
+```typescript
+interface AIMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+  metadata?: Record<string, any>;
+}
+```
+
+#### `CompletionParams`
+```typescript
+interface CompletionParams {
+  messages: AIMessage[];
+  model?: string;
+  maxTokens?: number;
+  temperature?: number;
+  topP?: number;
+  stopSequences?: string[];
+  stream?: boolean;
+}
+```
+
+#### `CompletionResponse`
+```typescript
+interface CompletionResponse {
+  content: string;
+  model: string;
+  usage: TokenUsage;
+  id: string;
+  metadata?: Record<string, any>;
+}
+```
+
+### Factory Functions
+
+#### `createClaudeProvider(apiKey, options?)`
+Creates a Claude provider with simplified configuration.
+
+```typescript
+const claude = createClaudeProvider('your-api-key', {
+  defaultModel: 'claude-3-5-sonnet-20241022',
+  timeout: 30000
+});
+```
+
+#### `createProvider(type, config)`
+Generic factory function for creating any provider type.
+
+```typescript
+const claude = createProvider('claude', {
+  apiKey: 'your-api-key',
+  defaultModel: 'claude-3-5-sonnet-20241022'
+});
+```
+
+### Provider Methods
+
+#### `initialize(): Promise<void>`
+Initializes the provider and validates the configuration.
+
+#### `complete(params): Promise<CompletionResponse>`
+Generates a completion based on the provided parameters.
+
+#### `stream(params): AsyncIterable<CompletionChunk>`
+Generates a streaming completion.
+
+#### `getInfo(): ProviderInfo`
+Returns information about the provider and its capabilities.
+
+#### `isInitialized(): boolean`
+Checks if the provider has been initialized.
+
+## Error Handling
+
+The package provides comprehensive error handling with categorized error types:
+
+```typescript
+import { AIProviderError, AIErrorType } from 'simple-ai-provider';
+
+try {
+  const response = await claude.complete({
+    messages: [{ role: 'user', content: 'Hello!' }]
+  });
+} catch (error) {
+  if (error instanceof AIProviderError) {
+    switch (error.type) {
+      case AIErrorType.AUTHENTICATION:
+        console.error('Invalid API key');
+        break;
+      case AIErrorType.RATE_LIMIT:
+        console.error('Rate limit exceeded');
+        break;
+      case AIErrorType.INVALID_REQUEST:
+        console.error('Invalid request parameters');
+        break;
+      default:
+        console.error('Unknown error:', error.message);
+    }
+  }
+}
+```
+
+## Supported Models
+
+### Claude (Anthropic)
+- `claude-3-5-sonnet-20241022` (default)
+- `claude-3-5-haiku-20241022`
+- `claude-3-opus-20240229`
+- `claude-3-sonnet-20240229`
+- `claude-3-haiku-20240307`
+
+## Environment Variables
+
+You can set your API keys as environment variables:
+
+```bash
+export ANTHROPIC_API_KEY="your-anthropic-api-key"
+```
+
+```typescript
+const claude = createClaudeProvider(process.env.ANTHROPIC_API_KEY!);
+```
+
+## Best Practices
+
+1. **Always initialize providers** before using them
+2. **Handle errors gracefully** with proper error types
+3. **Use appropriate models** for your use case
+4. **Set reasonable timeouts** for your application
+5. **Implement retry logic** for production applications
+6. **Monitor token usage** to control costs
+
+## Extending the Package
+
+To add a new AI provider, extend the `BaseAIProvider` class:
+
+```typescript
+import { BaseAIProvider } from 'simple-ai-provider';
+
+class MyCustomProvider extends BaseAIProvider {
+  protected async doInitialize(): Promise<void> {
+    // Initialize your provider
+  }
+
+  protected async doComplete(params: CompletionParams): Promise<CompletionResponse> {
+    // Implement completion logic
+  }
+
+  protected async *doStream(params: CompletionParams): AsyncIterable<CompletionChunk> {
+    // Implement streaming logic
+  }
+
+  public getInfo(): ProviderInfo {
+    return {
+      name: 'MyCustomProvider',
+      version: '1.0.0',
+      models: ['my-model'],
+      maxContextLength: 4096,
+      supportsStreaming: true
+    };
+  }
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+MIT
+
+## Changelog
+
+### 1.0.0
+- Initial release
+- Claude provider implementation
+- Streaming support
+- Comprehensive error handling
+- TypeScript support