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

npm install simple-ai-provider
# or
yarn add simple-ai-provider
# or
bun add simple-ai-provider

Quick Start

Basic Usage with Claude

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

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

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

interface AIMessage {
  role: 'system' | 'user' | 'assistant';
  content: string;
  metadata?: Record<string, any>;
}

CompletionParams

interface CompletionParams {
  messages: AIMessage[];
  model?: string;
  maxTokens?: number;
  temperature?: number;
  topP?: number;
  stopSequences?: string[];
  stream?: boolean;
}

CompletionResponse

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.

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.

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:

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:

export ANTHROPIC_API_KEY="your-anthropic-api-key"

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:

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