smartai/readme.md

# @push.rocks/smartai

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, use pnpm:

```bash
pnpm install @push.rocks/smartai
```

## Usage

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

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({
  // 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',              // default model for chat
    visionModel: 'llava'          // default model for vision
  },
  
  // Exo - for distributed inference
  exo: {
    baseUrl: 'http://localhost:8080/v1',
    apiKey: 'your-exo-api-key'
  }
});

// Start the SmartAi instance
await smartAi.start();
```

## 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

SmartAi provides both synchronous and streaming chat capabilities across all supported providers.

#### Synchronous Chat

Simple request-response interactions with any provider:

```typescript
// OpenAI Example
const openAiResponse = await smartAi.openaiProvider.chat({
  systemMessage: 'You are a helpful assistant.',
  userMessage: 'What is the capital of France?',
  messageHistory: []
});
console.log(openAiResponse.message); // "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?' }
  ]
});
```

#### Streaming Chat

For real-time, token-by-token responses:

```typescript
// Create a readable stream for input
const { readable, writable } = new TransformStream();
const writer = writable.getWriter();

// Send a message
const encoder = new TextEncoder();
await writer.write(encoder.encode(JSON.stringify({
  role: 'user',
  content: 'Write a haiku about programming'
})));
await writer.close();

// 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;
  process.stdout.write(value); // Print each chunk as it arrives
}
```

### 2. Text-to-Speech (Audio Generation)

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: 'Hello world! This is a test of the text-to-speech system.'
});

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

### 3. Vision Processing

Analyze images and get detailed descriptions:

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

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

### 4. Document Analysis

Process and analyze PDF documents with AI:

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

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

### 5. Conversation Management

Create persistent conversation sessions with any provider:

```typescript
// Create a conversation with OpenAI
const conversation = smartAi.createConversation('openai');

// Set the system message
await conversation.setSystemMessage('You are a helpful coding assistant.');

// Get input and output streams
const inputWriter = conversation.getInputStreamWriter();
const outputStream = conversation.getOutputStream();

// Set up output reader
const reader = outputStream.getReader();
const decoder = new TextDecoder();

// Send messages
await inputWriter.write('How do I create a REST API in Node.js?');

// 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

Always wrap AI operations in try-catch blocks for robust error handling:

```typescript
try {
  const response = await smartAi.openaiProvider.chat({
    systemMessage: 'You are an assistant.',
    userMessage: 'Hello!',
    messageHistory: []
  });
  console.log(response.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);
  }
}
```

### Streaming with Custom Processing

Implement custom transformations on streaming responses:

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

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

### Provider-Specific Features

Each provider may have unique capabilities. Here's how to leverage them:

```typescript
// OpenAI - Use specific models
const gpt4Response = await smartAi.openaiProvider.chat({
  systemMessage: 'You are a helpful assistant.',
  userMessage: 'Explain quantum computing',
  messageHistory: []
});

// 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: []
});

// 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: []
});
```

### 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

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.