From 0b1a7d90dab6ce90557e5a225990b03c29cb3d44 Mon Sep 17 00:00:00 2001 From: Jan-Marlon Leibl Date: Wed, 1 Oct 2025 14:32:50 +0200 Subject: [PATCH] docs: update README with new features and architecture details --- README.md | 292 ++++++++++++++++++++++++++++++++++++++++++++------- src/index.ts | 2 +- 2 files changed, 254 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index db04b87..76347ea 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,21 @@ A professional, type-safe TypeScript package that provides a unified interface f - ๐Ÿ“ฆ **Zero Dependencies**: Lightweight with minimal external dependencies - ๐ŸŒ **Local Support**: OpenWebUI integration for local/private AI models - ๐ŸŽจ **Structured Output**: Define custom response types for type-safe AI outputs +- ๐Ÿ—๏ธ **Provider Registry**: Dynamic provider registration and creation system +- โœ… **Comprehensive Testing**: Full test coverage with Bun test framework +- ๐Ÿ” **Advanced Validation**: Input validation with detailed error messages + +## ๐Ÿ—๏ธ Architecture + +The library is built on solid design principles: + +- **Template Method Pattern**: Base provider defines the workflow, subclasses implement specifics +- **Factory Pattern**: Clean provider creation and management +- **Strategy Pattern**: Unified interface across different AI providers +- **Type Safety**: Comprehensive TypeScript support throughout +- **Error Normalization**: Consistent error handling across all providers +- **Validation First**: Input validation before processing +- **Extensibility**: Easy to add new providers via registry system ## ๐Ÿš€ Quick Start @@ -75,15 +90,33 @@ Create providers using factory functions for cleaner code: import { createProvider, createClaudeProvider, createOpenAIProvider, createGeminiProvider, createOpenWebUIProvider } from 'simple-ai-provider'; // Method 1: Specific factory functions -const claude = createClaudeProvider({ apiKey: 'your-key' }); -const openai = createOpenAIProvider({ apiKey: 'your-key' }); -const gemini = createGeminiProvider({ apiKey: 'your-key' }); +const claude = createClaudeProvider('your-key', { defaultModel: 'claude-3-5-sonnet-20241022' }); +const openai = createOpenAIProvider('your-key', { defaultModel: 'gpt-4o' }); +const gemini = createGeminiProvider('your-key', { defaultModel: 'gemini-1.5-flash' }); const openwebui = createOpenWebUIProvider({ apiKey: 'your-key', baseUrl: 'http://localhost:3000' }); // Method 2: Generic factory const provider = createProvider('claude', { apiKey: 'your-key' }); ``` +### Provider Registry + +For dynamic provider creation and registration: + +```typescript +import { ProviderRegistry, ClaudeProvider } from 'simple-ai-provider'; + +// Register a custom provider +ProviderRegistry.register('my-claude', ClaudeProvider); + +// Create provider dynamically +const provider = ProviderRegistry.create('my-claude', { apiKey: 'your-key' }); + +// Check available providers +const availableProviders = ProviderRegistry.getRegisteredProviders(); +console.log(availableProviders); // ['claude', 'openai', 'gemini', 'openwebui', 'my-claude'] +``` + ## ๐ŸŽจ Structured Response Types Define custom response types for type-safe, structured AI outputs. The library automatically parses the AI's response into your desired type. @@ -303,46 +336,76 @@ for (const [name, provider] of Object.entries(providers)) { | **Claude** | 200K tokens | โœ… | โœ… | โœ… | โŒ | Reasoning, Analysis, Code Review | | **OpenAI** | 128K tokens | โœ… | โœ… | โœ… | โŒ | General Purpose, Function Calling | | **Gemini** | 1M tokens | โœ… | โœ… | โœ… | โŒ | Large Documents, Multimodal | -| **OpenWebUI** | 8K-32K tokens | โœ… | Varies | Limited | โœ… | Privacy, Custom Models, Local | +| **OpenWebUI** | 32K tokens | โœ… | โŒ | โŒ | โœ… | Privacy, Custom Models, Local | -## ๐ŸŽฏ Available Models +### Detailed Capabilities -### Claude Models -- `claude-3-5-sonnet-20241022` (recommended) -- `claude-3-5-haiku-20241022` -- `claude-3-opus-20240229` -- `claude-3-sonnet-20240229` -- `claude-3-haiku-20240307` +Each provider offers unique capabilities: -### OpenAI Models -- `gpt-4o` (recommended) -- `gpt-4o-mini` -- `gpt-4-turbo` -- `gpt-4` -- `gpt-3.5-turbo` +#### Claude (Anthropic) -### Gemini Models -- `gemini-1.5-flash` (recommended, fast) -- `gemini-1.5-flash-8b` (fastest) -- `gemini-1.5-pro` (most capable) -- `gemini-1.0-pro` -- `gemini-1.0-pro-vision` +- Advanced reasoning and analysis +- Excellent code review capabilities +- Strong safety features +- System message support -### OpenWebUI Models -*Available models depend on your local installation:* -- `llama3.1`, `llama3.1:8b`, `llama3.1:70b` -- `llama3.2`, `llama3.2:1b`, `llama3.2:3b` -- `codellama`, `codellama:7b`, `codellama:13b`, `codellama:34b` -- `mistral`, `mistral:7b` -- `mixtral`, `mixtral:8x7b` -- `phi3`, `phi3:mini` -- `gemma2`, `gemma2:2b`, `gemma2:9b` -- `qwen2.5`, `granite3.1-dense:8b` -- *Custom models as installed* +#### OpenAI + +- Broad model selection +- Function calling support +- JSON mode for structured outputs +- Vision capabilities + +#### Gemini (Google) + +- Largest context window (1M tokens) +- Multimodal capabilities +- Cost-effective pricing +- Strong multilingual support + +#### OpenWebUI + +- Complete privacy (local execution) +- Custom model support +- No API costs +- RAG (Retrieval Augmented Generation) support + +## ๐ŸŽฏ Model Selection + +### Getting Available Models + +Instead of maintaining a static list, you can programmatically get available models: + +```typescript +// Get provider information including available models +const info = provider.getInfo(); +console.log('Available models:', info.models); + +// Example output: +// Claude: ['claude-3-5-sonnet-20241022', 'claude-3-5-haiku-20241022', ...] +// OpenAI: ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', ...] +// Gemini: ['gemini-1.5-flash', 'gemini-1.5-pro', ...] +// OpenWebUI: ['llama3.1:latest', 'mistral:latest', ...] +``` + +### Model Selection Guidelines + +**For Claude (Anthropic):** +- Check [Anthropic's model documentation](https://docs.anthropic.com/claude/docs/models-overview) for latest models + +**For OpenAI:** +- Check [OpenAI's model documentation](https://platform.openai.com/docs/models) for latest models + +**For Gemini (Google):** +- Check [Google AI's model documentation](https://ai.google.dev/docs/models) for latest models + +**For OpenWebUI:** +- Models depend on your local installation +- Check your OpenWebUI instance for available models ## ๐Ÿšจ Error Handling -The package provides standardized error handling: +The package provides comprehensive, standardized error handling with detailed error types: ```typescript import { AIProviderError, AIErrorType } from 'simple-ai-provider'; @@ -355,24 +418,47 @@ try { if (error instanceof AIProviderError) { switch (error.type) { case AIErrorType.AUTHENTICATION: - console.log('Invalid API key'); + console.log('Invalid API key or authentication failed'); break; case AIErrorType.RATE_LIMIT: console.log('Rate limited, try again later'); break; case AIErrorType.MODEL_NOT_FOUND: - console.log('Model not available'); + console.log('Model not available or not found'); + break; + case AIErrorType.INVALID_REQUEST: + console.log('Invalid request parameters'); break; case AIErrorType.NETWORK: console.log('Network/connection issue'); break; - default: + case AIErrorType.TIMEOUT: + console.log('Request timed out'); + break; + case AIErrorType.UNKNOWN: console.log('Unknown error:', error.message); + break; + default: + console.log('Error:', error.message); } + + // Access additional error details + console.log('Status Code:', error.statusCode); + console.log('Original Error:', error.originalError); } } ``` +### Error Types + +- **AUTHENTICATION**: Invalid API keys or authentication failures +- **RATE_LIMIT**: API rate limits exceeded +- **INVALID_REQUEST**: Malformed requests or invalid parameters +- **MODEL_NOT_FOUND**: Requested model is not available +- **NETWORK**: Connection issues or server errors +- **TIMEOUT**: Request timeout exceeded +- **UNKNOWN**: Unclassified errors + ## ๐Ÿ”ง Advanced Usage ### Custom Base URLs @@ -436,6 +522,7 @@ try { ``` **OpenWebUI API Modes:** + - **Chat Completions** (`useOllamaProxy: false`): OpenWebUI's native API with full features - **Ollama Proxy** (`useOllamaProxy: true`): Direct access to Ollama API for raw model interaction @@ -452,7 +539,10 @@ import type { ClaudeConfig, OpenAIConfig, GeminiConfig, - OpenWebUIConfig + OpenWebUIConfig, + AIMessage, + ResponseType, + TokenUsage } from 'simple-ai-provider'; // Type-safe configuration @@ -464,12 +554,136 @@ const config: ClaudeConfig = { // Type-safe responses const response: CompletionResponse = await provider.complete(params); + +// Type-safe messages with metadata +const messages: AIMessage[] = [ + { + role: 'user', + content: 'Hello', + metadata: { timestamp: Date.now() } + } +]; + +// Type-safe response types +interface UserProfile { + name: string; + age: number; +} + +const responseType: ResponseType = createResponseType( + 'A user profile with name and age', + { name: 'John', age: 30 } +); +``` + +### Advanced Type Features + +- **Generic Response Types**: Type-safe structured outputs +- **Message Metadata**: Support for custom message properties +- **Provider-Specific Configs**: Type-safe configuration for each provider +- **Error Types**: Comprehensive error type definitions +- **Factory Functions**: Type-safe provider creation + +## ๐Ÿงช Testing + +The package includes comprehensive tests using Bun test framework: + +```bash +# Run all tests +bun test + +# Run tests for specific provider +bun test tests/claude.test.ts +bun test tests/openai.test.ts +bun test tests/gemini.test.ts +bun test tests/openwebui.test.ts + +# Run tests with coverage +bun test --coverage +``` + +### Test Coverage + +- โœ… Provider initialization and configuration +- โœ… Message validation and conversion +- โœ… Error handling and normalization +- โœ… Response formatting +- โœ… Streaming functionality +- โœ… Structured response types +- โœ… Factory functions +- โœ… Provider registry + +## ๐Ÿ› ๏ธ Development + +### Prerequisites + +- Node.js 18.0.0 or higher +- Bun (recommended) or npm/yarn +- TypeScript 5.0 or higher + +### Setup + +```bash +# Clone the repository +git clone https://gitea.jleibl.net/jleibl/simple-ai-provider.git +cd simple-ai-provider + +# Install dependencies +bun install + +# Build the project +bun run build + +# Run tests +bun test + +# Run examples +bun run examples/basic-usage.ts +bun run examples/structured-response-types.ts +bun run examples/multi-provider.ts +``` + +### Project Structure + +```text +src/ +โ”œโ”€โ”€ index.ts # Main entry point +โ”œโ”€โ”€ types/ +โ”‚ โ””โ”€โ”€ index.ts # Type definitions and utilities +โ”œโ”€โ”€ providers/ +โ”‚ โ”œโ”€โ”€ base.ts # Abstract base provider +โ”‚ โ”œโ”€โ”€ claude.ts # Claude provider implementation +โ”‚ โ”œโ”€โ”€ openai.ts # OpenAI provider implementation +โ”‚ โ”œโ”€โ”€ gemini.ts # Gemini provider implementation +โ”‚ โ”œโ”€โ”€ openwebui.ts # OpenWebUI provider implementation +โ”‚ โ””โ”€โ”€ index.ts # Provider exports +โ””โ”€โ”€ utils/ + โ””โ”€โ”€ factory.ts # Factory functions and registry + +examples/ +โ”œโ”€โ”€ basic-usage.ts # Basic usage examples +โ”œโ”€โ”€ structured-response-types.ts # Structured output examples +โ””โ”€โ”€ multi-provider.ts # Multi-provider examples + +tests/ +โ”œโ”€โ”€ claude.test.ts # Claude provider tests +โ”œโ”€โ”€ openai.test.ts # OpenAI provider tests +โ”œโ”€โ”€ gemini.test.ts # Gemini provider tests +โ””โ”€โ”€ openwebui.test.ts # OpenWebUI provider tests ``` ## ๐Ÿค 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. +### Development Guidelines + +1. **Code Style**: Follow the existing TypeScript patterns +2. **Testing**: Add tests for new features +3. **Documentation**: Update README for new features +4. **Type Safety**: Maintain comprehensive type definitions +5. **Error Handling**: Use standardized error types + ## ๐Ÿ“„ License MIT License - see the [LICENSE](LICENSE) file for details. diff --git a/src/index.ts b/src/index.ts index a3e9332..b10b84a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -58,4 +58,4 @@ export const SUPPORTED_PROVIDERS = ['claude', 'openai', 'gemini', 'openwebui'] a /** * Package version */ -export const VERSION = '1.2.0'; \ No newline at end of file +export const VERSION = '1.3.1'; \ No newline at end of file