@push.rocks/smartai 0.5.4 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartai",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "private": false,
   "description": "SmartAi is a versatile TypeScript library designed to facilitate integration and interaction with various AI models, offering functionalities for chat, audio generation, document processing, and vision tasks.",
   "main": "dist_ts/index.js",
@@ -9,24 +9,24 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.3.2",
-    "@git.zone/tsbundle": "^2.2.5",
+    "@git.zone/tsbuild": "^2.6.4",
+    "@git.zone/tsbundle": "^2.5.1",
     "@git.zone/tsrun": "^1.3.3",
-    "@git.zone/tstest": "^1.0.96",
+    "@git.zone/tstest": "^2.3.2",
     "@push.rocks/qenv": "^6.1.0",
     "@push.rocks/tapbundle": "^6.0.3",
     "@types/node": "^22.15.17"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.50.4",
+    "@anthropic-ai/sdk": "^0.57.0",
     "@push.rocks/smartarray": "^1.1.0",
-    "@push.rocks/smartfile": "^11.2.0",
+    "@push.rocks/smartfile": "^11.2.5",
     "@push.rocks/smartpath": "^5.0.18",
     "@push.rocks/smartpdf": "^3.2.2",
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartrequest": "^2.1.0",
     "@push.rocks/webstream": "^1.0.10",
-    "openai": "^4.98.0"
+    "openai": "^5.10.2"
   },
   "repository": {
     "type": "git",
@@ -76,7 +76,7 @@
     "provider switching"
   ],
   "scripts": {
-    "test": "(tstest test/ --web)",
+    "test": "(tstest test/ --web --verbose)",
     "build": "(tsbuild --web --allowimplicitany)",
     "buildDocs": "(tsdoc)"
   }

package/readme.md

@@ -1,222 +1,392 @@
 # @push.rocks/smartai
 
-SmartAi is a TypeScript library providing a unified interface for integrating and interacting with multiple AI models, supporting chat interactions, audio and document processing, and vision tasks.
+SmartAi is a powerful TypeScript library that provides a unified interface for integrating with multiple AI providers including OpenAI, Anthropic, Perplexity, Ollama, Groq, XAI, and Exo. It offers comprehensive support for chat interactions, streaming conversations, text-to-speech, document analysis, and vision processing.
 
 ## Install
 
-To install SmartAi into your project, you need to run the following command in your terminal:
+To install SmartAi into your project, use pnpm:
 
 ```bash
-npm install @push.rocks/smartai
+pnpm install @push.rocks/smartai
 ```
 
-This command will add the SmartAi library to your project's dependencies, making it available for use in your TypeScript application.
-
 ## Usage
 
-SmartAi is designed to provide a comprehensive and unified API for working seamlessly with multiple AI providers like OpenAI, Anthropic, Perplexity, and others. Below we will delve into how to make the most out of this library, illustrating the setup and functionality with in-depth examples. Our scenarios will explore synchronous and streaming interactions, audio generation, document handling, and vision tasks with different AI providers.
+SmartAi provides a clean, consistent API across all supported AI providers. This documentation covers all features with practical examples for each provider and capability.
 
 ### Initialization
 
-Initialization is the first step before using any AI functionalities. You should provide API tokens for each provider you plan to utilize.
+First, initialize SmartAi with the API tokens and configuration for the providers you want to use:
 
 ```typescript
 import { SmartAi } from '@push.rocks/smartai';
 
 const smartAi = new SmartAi({
-  openaiToken: 'your-openai-token',
-  anthropicToken: 'your-anthropic-token',
-  perplexityToken: 'your-perplexity-token',
-  xaiToken: 'your-xai-token',
-  groqToken: 'your-groq-token',
+  // OpenAI - for GPT models, DALL-E, and TTS
+  openaiToken: 'your-openai-api-key',
+  
+  // Anthropic - for Claude models
+  anthropicToken: 'your-anthropic-api-key',
+  
+  // Perplexity - for research-focused AI
+  perplexityToken: 'your-perplexity-api-key',
+  
+  // Groq - for fast inference
+  groqToken: 'your-groq-api-key',
+  
+  // XAI - for Grok models
+  xaiToken: 'your-xai-api-key',
+  
+  // Ollama - for local models
   ollama: {
     baseUrl: 'http://localhost:11434',
-    model: 'llama2',
-    visionModel: 'llava'
+    model: 'llama2',              // default model for chat
+    visionModel: 'llava'          // default model for vision
   },
+  
+  // Exo - for distributed inference
   exo: {
     baseUrl: 'http://localhost:8080/v1',
-    apiKey: 'your-api-key'
+    apiKey: 'your-exo-api-key'
   }
 });
 
+// Start the SmartAi instance
 await smartAi.start();
 ```
 
-### Chat Interactions
+## Supported Providers
+
+SmartAi supports the following AI providers:
+
+| Provider | Use Case | Key Features |
+|----------|----------|--------------|
+| **OpenAI** | General purpose, GPT models | Chat, streaming, TTS, vision, documents |
+| **Anthropic** | Claude models, safety-focused | Chat, streaming, vision, documents |
+| **Perplexity** | Research and factual queries | Chat, streaming, documents |
+| **Groq** | Fast inference | Chat, streaming |
+| **XAI** | Grok models | Chat, streaming |
+| **Ollama** | Local models | Chat, streaming, vision |
+| **Exo** | Distributed inference | Chat, streaming |
+
+## Core Features
+
+### 1. Chat Interactions
 
-Interaction through chat is a key feature. SmartAi caters to both synchronous and asynchronous (streaming) chats across several AI models.
+SmartAi provides both synchronous and streaming chat capabilities across all supported providers.
 
-#### Regular Synchronous Chat
+#### Synchronous Chat
 
-Connect with AI models via straightforward request-response interactions.
+Simple request-response interactions with any provider:
 
 ```typescript
-const syncResponse = await smartAi.openaiProvider.chat({
+// OpenAI Example
+const openAiResponse = await smartAi.openaiProvider.chat({
   systemMessage: 'You are a helpful assistant.',
   userMessage: 'What is the capital of France?',
-  messageHistory: [] // Could include context or preceding messages
+  messageHistory: []
 });
+console.log(openAiResponse.message); // "The capital of France is Paris."
 
-console.log(syncResponse.message); // Outputs: "The capital of France is Paris."
+// Anthropic Example
+const anthropicResponse = await smartAi.anthropicProvider.chat({
+  systemMessage: 'You are a knowledgeable historian.',
+  userMessage: 'Tell me about the French Revolution',
+  messageHistory: []
+});
+console.log(anthropicResponse.message);
+
+// Using message history for context
+const contextualResponse = await smartAi.openaiProvider.chat({
+  systemMessage: 'You are a math tutor.',
+  userMessage: 'What about multiplication?',
+  messageHistory: [
+    { role: 'user', content: 'Can you teach me math?' },
+    { role: 'assistant', content: 'Of course! What would you like to learn?' }
+  ]
+});
 ```
 
-#### Real-Time Streaming Chat
+#### Streaming Chat
 
-For continuous interaction and lower latency, engage in streaming chat.
+For real-time, token-by-token responses:
 
 ```typescript
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
-
-// Establish a transform stream
-const { writable, readable } = new TransformStream();
+// Create a readable stream for input
+const { readable, writable } = new TransformStream();
 const writer = writable.getWriter();
 
-const message = {
+// Send a message
+const encoder = new TextEncoder();
+await writer.write(encoder.encode(JSON.stringify({
   role: 'user',
-  content: 'Tell me a story about a brave knight'
-};
+  content: 'Write a haiku about programming'
+})));
+await writer.close();
 
-writer.write(textEncoder.encode(JSON.stringify(message) + '\n'));
-
-// Initiate streaming
-const stream = await smartAi.openaiProvider.chatStream(readable);
-const reader = stream.getReader();
+// Get streaming response
+const responseStream = await smartAi.openaiProvider.chatStream(readable);
+const reader = responseStream.getReader();
+const decoder = new TextDecoder();
 
+// Read the stream
 while (true) {
   const { done, value } = await reader.read();
   if (done) break;
-  console.log('AI:', value);
+  process.stdout.write(value); // Print each chunk as it arrives
 }
 ```
 
-### Audio Generation
+### 2. Text-to-Speech (Audio Generation)
 
-Audio generation from textual input is possible using providers like OpenAI.
+Convert text to natural-sounding speech (currently supported by OpenAI):
 
 ```typescript
+import * as fs from 'fs';
+
+// Generate speech from text
 const audioStream = await smartAi.openaiProvider.audio({
-  message: 'This is a test message for generating speech.'
+  message: 'Hello world! This is a test of the text-to-speech system.'
 });
 
-// Use the audioStream e.g., playing or saving it.
+// Save to file
+const writeStream = fs.createWriteStream('output.mp3');
+audioStream.pipe(writeStream);
+
+// Or use in your application directly
+audioStream.on('data', (chunk) => {
+  // Process audio chunks
+});
 ```
 
-### Document Analysis
+### 3. Vision Processing
 
-SmartAi can ingest and process documents, extracting meaningful information or performing classifications.
+Analyze images and get detailed descriptions:
 
 ```typescript
-const pdfBuffer = await fetchPdf('https://example.com/document.pdf');
-const documentRes = await smartAi.openaiProvider.document({
-  systemMessage: 'Determine the nature of the document.',
-  userMessage: 'Classify this document.',
-  messageHistory: [],
-  pdfDocuments: [pdfBuffer]
+import * as fs from 'fs';
+
+// Read an image file
+const imageBuffer = fs.readFileSync('image.jpg');
+
+// OpenAI Vision
+const openAiVision = await smartAi.openaiProvider.vision({
+  image: imageBuffer,
+  prompt: 'What is in this image? Describe in detail.'
 });
+console.log('OpenAI:', openAiVision);
 
-console.log(documentRes.message); // Outputs: classified document type
+// Anthropic Vision
+const anthropicVision = await smartAi.anthropicProvider.vision({
+  image: imageBuffer,
+  prompt: 'Analyze this image and identify any text or objects.'
+});
+console.log('Anthropic:', anthropicVision);
+
+// Ollama Vision (using local model)
+const ollamaVision = await smartAi.ollamaProvider.vision({
+  image: imageBuffer,
+  prompt: 'Describe the colors and composition of this image.'
+});
+console.log('Ollama:', ollamaVision);
 ```
 
-SmartAi allows easy switching between providers, thus giving developers flexibility:
+### 4. Document Analysis
+
+Process and analyze PDF documents with AI:
 
 ```typescript
-const anthopicRes = await smartAi.anthropicProvider.document({
-  systemMessage: 'Analyze this document.',
-  userMessage: 'Extract core points.',
+import * as fs from 'fs';
+
+// Read PDF documents
+const pdfBuffer = fs.readFileSync('document.pdf');
+
+// Analyze with OpenAI
+const openAiAnalysis = await smartAi.openaiProvider.document({
+  systemMessage: 'You are a document analyst. Extract key information.',
+  userMessage: 'Summarize this document and list the main points.',
+  messageHistory: [],
+  pdfDocuments: [pdfBuffer]
+});
+console.log('OpenAI Analysis:', openAiAnalysis.message);
+
+// Analyze with Anthropic
+const anthropicAnalysis = await smartAi.anthropicProvider.document({
+  systemMessage: 'You are a legal expert.',
+  userMessage: 'Identify any legal terms or implications in this document.',
   messageHistory: [],
   pdfDocuments: [pdfBuffer]
 });
+console.log('Anthropic Analysis:', anthropicAnalysis.message);
+
+// Process multiple documents
+const doc1 = fs.readFileSync('contract1.pdf');
+const doc2 = fs.readFileSync('contract2.pdf');
 
-console.log(anthopicRes.message); // Outputs: summarized core points
+const comparison = await smartAi.openaiProvider.document({
+  systemMessage: 'You are a contract analyst.',
+  userMessage: 'Compare these two contracts and highlight the differences.',
+  messageHistory: [],
+  pdfDocuments: [doc1, doc2]
+});
+console.log('Comparison:', comparison.message);
 ```
 
-### Vision Processing
+### 5. Conversation Management
 
-Engage AI models in analyzing and describing images:
+Create persistent conversation sessions with any provider:
 
 ```typescript
-const imageBuffer = await fetchImage('path/to/image.jpg');
+// Create a conversation with OpenAI
+const conversation = smartAi.createConversation('openai');
 
-// Using OpenAI's vision capabilities
-const visionOutput = await smartAi.openaiProvider.vision({
-  image: imageBuffer,
-  prompt: 'Describe the image.'
-});
+// Set the system message
+await conversation.setSystemMessage('You are a helpful coding assistant.');
 
-console.log(visionOutput); // Outputs: image description
-```
+// Get input and output streams
+const inputWriter = conversation.getInputStreamWriter();
+const outputStream = conversation.getOutputStream();
 
-Use other providers for more varied analysis:
+// Set up output reader
+const reader = outputStream.getReader();
+const decoder = new TextDecoder();
 
-```typescript
-const ollamaOutput = await smartAi.ollamaProvider.vision({
-  image: imageBuffer,
-  prompt: 'Detailed analysis required.'
-});
+// Send messages
+await inputWriter.write('How do I create a REST API in Node.js?');
 
-console.log(ollamaOutput); // Outputs: detailed analysis results
+// Read responses
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  console.log('Assistant:', decoder.decode(value));
+}
+
+// Continue the conversation
+await inputWriter.write('Can you show me an example with Express?');
+
+// Create conversations with different providers
+const anthropicConversation = smartAi.createConversation('anthropic');
+const groqConversation = smartAi.createConversation('groq');
 ```
 
+## Advanced Usage
+
 ### Error Handling
 
-Due to the nature of external integrations, ensure to wrap AI calls within try-catch blocks.
+Always wrap AI operations in try-catch blocks for robust error handling:
 
 ```typescript
 try {
-  const response = await smartAi.anthropicProvider.chat({
-    systemMessage: 'Hello!',
-    userMessage: 'Help me out.',
+  const response = await smartAi.openaiProvider.chat({
+    systemMessage: 'You are an assistant.',
+    userMessage: 'Hello!',
     messageHistory: []
   });
   console.log(response.message);
-} catch (error: any) {
-  console.error('Encountered an error:', error.message);
+} catch (error) {
+  if (error.code === 'rate_limit_exceeded') {
+    console.error('Rate limit hit, please retry later');
+  } else if (error.code === 'invalid_api_key') {
+    console.error('Invalid API key provided');
+  } else {
+    console.error('Unexpected error:', error.message);
+  }
 }
 ```
 
-### Providers and Customization
+### Streaming with Custom Processing
 
-The library supports provider-specific customization, enabling tailored interactions:
+Implement custom transformations on streaming responses:
 
 ```typescript
-const smartAi = new SmartAi({
-  openaiToken: 'your-openai-token',
-  anthropicToken: 'your-anthropic-token',
-  ollama: {
-    baseUrl: 'http://localhost:11434',
-    model: 'llama2',
-    visionModel: 'llava'
+// Create a custom transform stream
+const customTransform = new TransformStream({
+  transform(chunk, controller) {
+    // Example: Add timestamps to each chunk
+    const timestamp = new Date().toISOString();
+    controller.enqueue(`[${timestamp}] ${chunk}`);
   }
 });
 
-await smartAi.start();
+// Apply to streaming chat
+const inputStream = new ReadableStream({
+  start(controller) {
+    controller.enqueue(new TextEncoder().encode(JSON.stringify({
+      role: 'user',
+      content: 'Tell me a story'
+    })));
+    controller.close();
+  }
+});
+
+const responseStream = await smartAi.openaiProvider.chatStream(inputStream);
+const processedStream = responseStream.pipeThrough(customTransform);
+
+// Read processed stream
+const reader = processedStream.getReader();
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  console.log(value);
+}
 ```
 
-### Advanced Streaming Customization
+### Provider-Specific Features
 
-Developers can implement real-time processing pipelines with custom transformations:
+Each provider may have unique capabilities. Here's how to leverage them:
 
 ```typescript
-const customProcessingStream = new TransformStream({
-  transform(chunk, controller) {
-    const processed = chunk.toUpperCase(); // Example transformation
-    controller.enqueue(processed);
-  }
+// OpenAI - Use specific models
+const gpt4Response = await smartAi.openaiProvider.chat({
+  systemMessage: 'You are a helpful assistant.',
+  userMessage: 'Explain quantum computing',
+  messageHistory: []
 });
 
-const processedStream = stream.pipeThrough(customProcessingStream);
-const processedReader = processedStream.getReader();
+// Anthropic - Use Claude's strength in analysis
+const codeReview = await smartAi.anthropicProvider.chat({
+  systemMessage: 'You are a code reviewer.',
+  userMessage: 'Review this code for security issues: ...',
+  messageHistory: []
+});
 
-while (true) {
-  const { done, value } = await processedReader.read();
-  if (done) break;
-  console.log('Processed Output:', value);
-}
+// Perplexity - Best for research and current events
+const research = await smartAi.perplexityProvider.chat({
+  systemMessage: 'You are a research assistant.',
+  userMessage: 'What are the latest developments in renewable energy?',
+  messageHistory: []
+});
+
+// Groq - Optimized for speed
+const quickResponse = await smartAi.groqProvider.chat({
+  systemMessage: 'You are a quick helper.',
+  userMessage: 'Give me a one-line summary of photosynthesis',
+  messageHistory: []
+});
 ```
 
-This approach can facilitate adaptive content processing workflows.
+### Performance Optimization
+
+Tips for optimal performance:
+
+```typescript
+// 1. Reuse providers instead of creating new instances
+const smartAi = new SmartAi({ /* config */ });
+await smartAi.start(); // Initialize once
+
+// 2. Use streaming for long responses
+// Streaming reduces time-to-first-token and memory usage
+
+// 3. Batch operations when possible
+const promises = [
+  smartAi.openaiProvider.chat({ /* ... */ }),
+  smartAi.anthropicProvider.chat({ /* ... */ })
+];
+const results = await Promise.all(promises);
+
+// 4. Clean up resources
+await smartAi.stop(); // When done
+```
 
 ## License and Legal Information