simple-ai-provider/README.md

# 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