A professional, extensible TypeScript package for integrating multiple AI providers into your applications with a unified interface. Currently supports Claude (Anthropic), OpenAI (GPT), and Google Gemini 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
🌐 Multi-Provider: Switch between Claude, OpenAI, and Gemini seamlessly

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);

Basic Usage with OpenAI

import { createOpenAIProvider } from 'simple-ai-provider';

// Create an OpenAI provider
const openai = createOpenAIProvider('your-openai-api-key');

// Initialize the provider
await openai.initialize();

// Generate a completion
const response = await openai.complete({
  messages: [
    { role: 'user', content: 'Hello! How are you today?' }
  ],
  maxTokens: 100,
  temperature: 0.7
});

console.log(response.content);

Basic Usage with Gemini

import { createGeminiProvider } from 'simple-ai-provider';

// Create a Gemini provider
const gemini = createGeminiProvider('your-google-ai-api-key');

// Initialize the provider
await gemini.initialize();

// Generate a completion
const response = await gemini.complete({
  messages: [
    { role: 'user', content: 'Hello! How are you today?' }
  ],
  maxTokens: 100,
  temperature: 0.7
});

console.log(response.content);

Multi-Provider Usage

import { createProvider, createClaudeProvider, createOpenAIProvider, createGeminiProvider } from 'simple-ai-provider';

// Method 1: Using specific factory functions
const claude = createClaudeProvider('your-anthropic-api-key');
const openai = createOpenAIProvider('your-openai-api-key');
const gemini = createGeminiProvider('your-google-ai-api-key');

// Method 2: Using generic factory
const claude2 = createProvider('claude', { apiKey: 'your-anthropic-api-key' });
const openai2 = createProvider('openai', { apiKey: 'your-openai-api-key' });
const gemini2 = createProvider('gemini', { apiKey: 'your-google-ai-api-key' });

// Initialize all
await Promise.all([claude.initialize(), openai.initialize(), gemini.initialize()]);

// Use the same interface for all providers
const prompt = { messages: [{ role: 'user', content: 'Explain AI' }] };

const claudeResponse = await claude.complete(prompt);
const openaiResponse = await openai.complete(prompt);
const geminiResponse = await gemini.complete(prompt);

Streaming Responses

import { createGeminiProvider } from 'simple-ai-provider';

const gemini = createGeminiProvider('your-google-ai-api-key');
await gemini.initialize();

// Stream a completion
for await (const chunk of gemini.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, OpenAIProvider, GeminiProvider } from 'simple-ai-provider';

// Claude with custom configuration
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
});

// OpenAI with organization and project
const openai = new OpenAIProvider({
  apiKey: 'your-openai-api-key',
  defaultModel: 'gpt-4',
  organization: 'org-your-org-id',
  project: 'proj-your-project-id',
  timeout: 60000,
  maxRetries: 5
});

// Gemini with safety settings and generation config
const gemini = new GeminiProvider({
  apiKey: 'your-google-ai-api-key',
  defaultModel: 'gemini-1.5-pro',
  safetySettings: [], // Configure content filtering
  generationConfig: {
    temperature: 0.8,
    topP: 0.9,
    topK: 40,
    maxOutputTokens: 2048
  },
  timeout: 45000
});

await Promise.all([claude.initialize(), openai.initialize(), gemini.initialize()]);

const response = await gemini.complete({
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain quantum computing in simple terms.' }
  ],
  model: 'gemini-1.5-flash',
  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
});

`createOpenAIProvider(apiKey, options?)`

Creates an OpenAI provider with simplified configuration.

const openai = createOpenAIProvider('your-api-key', {
  defaultModel: 'gpt-4',
  organization: 'org-123',
  timeout: 60000
});

`createGeminiProvider(apiKey, options?)`

Creates a Gemini provider with simplified configuration.

const gemini = createGeminiProvider('your-api-key', {
  defaultModel: 'gemini-1.5-pro',
  safetySettings: [],
  generationConfig: {
    temperature: 0.8,
    topK: 40
  }
});

`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'
});

const openai = createProvider('openai', {
  apiKey: 'your-api-key',
  defaultModel: 'gpt-4'
});

const gemini = createProvider('gemini', {
  apiKey: 'your-api-key',
  defaultModel: 'gemini-1.5-flash'
});

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 openai.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

OpenAI (GPT)

gpt-4 (default)
gpt-4-turbo
gpt-4-turbo-preview
gpt-4-0125-preview
gpt-4-1106-preview
gpt-3.5-turbo
gpt-3.5-turbo-0125
gpt-3.5-turbo-1106

Google Gemini

gemini-1.5-flash (default)
gemini-1.5-flash-8b
gemini-1.5-pro
gemini-1.0-pro
gemini-1.0-pro-vision

Environment Variables

You can set your API keys as environment variables:

export ANTHROPIC_API_KEY="your-anthropic-api-key"
export OPENAI_API_KEY="your-openai-api-key"
export GOOGLE_AI_API_KEY="your-google-ai-api-key"

const claude = createClaudeProvider(process.env.ANTHROPIC_API_KEY!);
const openai = createOpenAIProvider(process.env.OPENAI_API_KEY!);
const gemini = createGeminiProvider(process.env.GOOGLE_AI_API_KEY!);

Provider Comparison

Feature	Claude	OpenAI	Gemini
Models	5 models	8+ models	5 models
Max Context	200K tokens	128K tokens	1M tokens
Streaming	✅	✅	✅
Vision	✅	✅	✅
Function Calling	✅	✅	✅
JSON Mode	❌	✅	❌
System Messages	✅ (separate)	✅ (inline)	✅ (separate)
Multimodal	✅	✅	✅
Safety Controls	Basic	Basic	Advanced
Special Features	Advanced reasoning	JSON mode, plugins	Largest context, advanced safety

Best Practices

Always initialize providers before using them
Handle errors gracefully with proper error types
Use appropriate models for your use case (speed vs. capability vs. context)
Set reasonable timeouts for your application
Implement retry logic for production applications
Monitor token usage to control costs
Use environment variables for API keys
Consider provider-specific features when choosing
Configure safety settings appropriately for Gemini
Leverage large context capabilities of Gemini for complex tasks

Advanced Usage

Provider Registry

import { ProviderRegistry } from 'simple-ai-provider';

// List all registered providers
console.log(ProviderRegistry.getRegisteredProviders()); // ['claude', 'openai', 'gemini']

// Create provider by name
const provider = ProviderRegistry.create('gemini', {
  apiKey: 'your-api-key'
});

// Check if provider is registered
if (ProviderRegistry.isRegistered('gemini')) {
  console.log('Gemini is available!');
}

Gemini-Specific Features

import { createGeminiProvider } from 'simple-ai-provider';

const gemini = createGeminiProvider('your-api-key', {
  defaultModel: 'gemini-1.5-pro',
  safetySettings: [
    {
      category: 'HARM_CATEGORY_HARASSMENT',
      threshold: 'BLOCK_MEDIUM_AND_ABOVE'
    }
  ],
  generationConfig: {
    temperature: 0.9,
    topP: 0.8,
    topK: 40,
    maxOutputTokens: 2048,
    stopSequences: ['END', 'STOP']
  }
});

await gemini.initialize();

// Large context example (up to 1M tokens)
const response = await gemini.complete({
  messages: [
    { role: 'system', content: 'You are analyzing a large document.' },
    { role: 'user', content: 'Your very large text here...' }
  ],
  maxTokens: 2048
});

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
OpenAI provider implementation
Gemini provider implementation
Streaming support for all providers
Comprehensive error handling
TypeScript support
Provider registry system
Multi-provider examples
Large context support (Gemini)
Advanced safety controls (Gemini)