feat(providers): Add Anthropic extended thinking and adapt providers to new streaming/file APIs; bump dependencies and update docs, tests and configuration

2026-01-18 16:26:16 +00:00
parent e8a2a3ff1b
commit b4ced080f2
27 changed files with 2262 additions and 3339 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,11 +1,16 @@
 # @push.rocks/smartai
+
 **One API to rule them all** 🚀

 [![npm version](https://img.shields.io/npm/v/@push.rocks/smartai.svg)](https://www.npmjs.com/package/@push.rocks/smartai)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

-SmartAI unifies the world's leading AI providers - OpenAI, Anthropic, Perplexity, Ollama, Groq, XAI, Exo, and ElevenLabs - under a single, elegant TypeScript interface. Build AI applications at lightning speed without vendor lock-in. 
+SmartAI unifies the world's leading AI providers - OpenAI, Anthropic, Perplexity, Ollama, Groq, XAI, Exo, and ElevenLabs - under a single, elegant TypeScript interface. Build AI applications at lightning speed without vendor lock-in.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

 ## 🎯 Why SmartAI?

@@ -31,8 +36,8 @@ const ai = new SmartAi({
  anthropicToken: 'sk-ant-...',
  elevenlabsToken: 'sk-...',
  elevenlabs: {
-    defaultVoiceId: '19STyYD15bswVz51nqLf' // Optional: Samara voice
-  }
+    defaultVoiceId: '19STyYD15bswVz51nqLf', // Optional: Samara voice
+  },
 });

 await ai.start();
@@ -41,7 +46,7 @@ await ai.start();
 const response = await ai.openaiProvider.chat({
  systemMessage: 'You are a helpful assistant.',
  userMessage: 'Explain quantum computing in simple terms',
-  messageHistory: []
+  messageHistory: [],
 });
 ```

@@ -49,16 +54,16 @@ const response = await ai.openaiProvider.chat({

 Choose the right provider for your use case:

-| Provider | Chat | Streaming | TTS | Vision | Documents | Research | Images | Highlights |
-|----------|:----:|:---------:|:---:|:------:|:---------:|:--------:|:------:|------------|
-| **OpenAI** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | • gpt-image-1<br>• DALL-E 3<br>• Deep research API |
-| **Anthropic** | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | • Claude Sonnet 4.5<br>• Superior reasoning<br>• Web search API |
-| **ElevenLabs** | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | • Premium TTS<br>• 70+ languages<br>• Natural voices |
-| **Ollama** | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | • 100% local<br>• Privacy-first<br>• No API costs |
-| **XAI** | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | • Grok models<br>• Real-time data<br>• Uncensored |
-| **Perplexity** | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | • Web-aware<br>• Research-focused<br>• Sonar Pro models |
-| **Groq** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | • 10x faster<br>• LPU inference<br>• Low latency |
-| **Exo** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | • Distributed<br>• P2P compute<br>• Decentralized |
+| Provider       | Chat | Streaming | TTS | Vision | Documents | Research | Images | Highlights                                                      |
+| -------------- | :--: | :-------: | :-: | :----: | :-------: | :------: | :----: | --------------------------------------------------------------- |
+| **OpenAI**     |  ✅  |    ✅     | ✅  |   ✅   |    ✅     |    ✅    |   ✅   | • gpt-image-1<br>• DALL-E 3<br>• Deep research API              |
+| **Anthropic**  |  ✅  |    ✅     | ❌  |   ✅   |    ✅     |    ✅    |   ❌   | • Claude Sonnet 4.5<br>• Superior reasoning<br>• Web search API |
+| **ElevenLabs** |  ❌  |    ❌     | ✅  |   ❌   |    ❌     |    ❌    |   ❌   | • Premium TTS<br>• 70+ languages<br>• Natural voices            |
+| **Ollama**     |  ✅  |    ✅     | ❌  |   ✅   |    ✅     |    ❌    |   ❌   | • 100% local<br>• Privacy-first<br>• No API costs               |
+| **XAI**        |  ✅  |    ✅     | ❌  |   ❌   |    ✅     |    ❌    |   ❌   | • Grok models<br>• Real-time data<br>• Uncensored               |
+| **Perplexity** |  ✅  |    ✅     | ❌  |   ❌   |    ❌     |    ✅    |   ❌   | • Web-aware<br>• Research-focused<br>• Sonar Pro models         |
+| **Groq**       |  ✅  |    ✅     | ❌  |   ❌   |    ❌     |    ❌    |   ❌   | • 10x faster<br>• LPU inference<br>• Low latency                |
+| **Exo**        |  ✅  |    ✅     | ❌  |   ❌   |    ❌     |    ❌    |   ❌   | • Distributed<br>• P2P compute<br>• Decentralized               |

 ## 🎮 Core Features

@@ -71,21 +76,21 @@ Works identically across all providers:
 const gptResponse = await ai.openaiProvider.chat({
  systemMessage: 'You are a expert physicist.',
  userMessage: 'Explain the implications of quantum entanglement',
-  messageHistory: []
+  messageHistory: [],
 });

 // Use Claude for safety-critical applications
 const claudeResponse = await ai.anthropicProvider.chat({
  systemMessage: 'You are a medical advisor.',
  userMessage: 'Review this patient data for concerns',
-  messageHistory: []
+  messageHistory: [],
 });

 // Use Groq for lightning-fast responses
 const groqResponse = await ai.groqProvider.chat({
  systemMessage: 'You are a code reviewer.',
  userMessage: 'Quick! Find the bug in this code: ...',
-  messageHistory: []
+  messageHistory: [],
 });
 ```

@@ -102,7 +107,7 @@ const reader = stream.getReader();
 while (true) {
  const { done, value } = await reader.read();
  if (done) break;
-  
+
  // Update UI in real-time
  process.stdout.write(value);
 }
@@ -115,7 +120,7 @@ Generate natural voices with OpenAI or ElevenLabs:
 ```typescript
 // OpenAI TTS
 const audioStream = await ai.openaiProvider.audio({
-  message: 'Welcome to the future of AI development!'
+  message: 'Welcome to the future of AI development!',
 });

 // ElevenLabs TTS - Premium quality, natural voices (uses v3 by default)
@@ -123,12 +128,13 @@ const elevenLabsAudio = await ai.elevenlabsProvider.audio({
  message: 'Experience the most lifelike text to speech technology.',
  voiceId: '19STyYD15bswVz51nqLf', // Optional: Samara voice
  modelId: 'eleven_v3', // Optional: defaults to eleven_v3 (70+ languages, most expressive)
-  voiceSettings: { // Optional: fine-tune voice characteristics
-    stability: 0.5,        // 0-1: Speech consistency
+  voiceSettings: {
+    // Optional: fine-tune voice characteristics
+    stability: 0.5, // 0-1: Speech consistency
    similarity_boost: 0.8, // 0-1: Voice similarity to original
-    style: 0.0,            // 0-1: Expressiveness (higher = more expressive)
-    use_speaker_boost: true // Enhanced clarity
-  }
+    style: 0.0, // 0-1: Expressiveness (higher = more expressive)
+    use_speaker_boost: true, // Enhanced clarity
+  },
 });

 // Stream directly to speakers
@@ -148,19 +154,19 @@ const image = fs.readFileSync('product-photo.jpg');
 // OpenAI: General purpose vision
 const gptVision = await ai.openaiProvider.vision({
  image,
-  prompt: 'Describe this product and suggest marketing angles'
+  prompt: 'Describe this product and suggest marketing angles',
 });

 // Anthropic: Detailed analysis
 const claudeVision = await ai.anthropicProvider.vision({
  image,
-  prompt: 'Identify any safety concerns or defects'
+  prompt: 'Identify any safety concerns or defects',
 });

 // Ollama: Private, local analysis
 const ollamaVision = await ai.ollamaProvider.vision({
  image,
-  prompt: 'Extract all text and categorize the content'
+  prompt: 'Extract all text and categorize the content',
 });
 ```

@@ -177,7 +183,7 @@ const analysis = await ai.openaiProvider.document({
  systemMessage: 'You are a legal expert.',
  userMessage: 'Compare these documents and highlight key differences',
  messageHistory: [],
-  pdfDocuments: [contract, invoice]
+  pdfDocuments: [contract, invoice],
 });

 // Multi-document analysis
@@ -186,7 +192,7 @@ const taxAnalysis = await ai.anthropicProvider.document({
  systemMessage: 'You are a tax advisor.',
  userMessage: 'Prepare a tax summary from these documents',
  messageHistory: [],
-  pdfDocuments: taxDocs
+  pdfDocuments: taxDocs,
 });
 ```

@@ -199,7 +205,7 @@ Perform deep research with web search capabilities across multiple providers:
 const deepResearch = await ai.openaiProvider.research({
  query: 'What are the latest developments in quantum computing?',
  searchDepth: 'deep',
-  includeWebSearch: true
+  includeWebSearch: true,
 });

 console.log(deepResearch.answer);
@@ -209,32 +215,73 @@ console.log('Sources:', deepResearch.sources);
 const anthropic = new AnthropicProvider({
  anthropicToken: 'sk-ant-...',
  enableWebSearch: true,
-  searchDomainAllowList: ['nature.com', 'science.org']
+  searchDomainAllowList: ['nature.com', 'science.org'],
 });

 const scientificResearch = await anthropic.research({
  query: 'Latest breakthroughs in CRISPR gene editing',
-  searchDepth: 'advanced'
+  searchDepth: 'advanced',
 });

 // Perplexity - Research-focused with citations
 const perplexityResearch = await ai.perplexityProvider.research({
  query: 'Current state of autonomous vehicle technology',
-  searchDepth: 'deep' // Uses Sonar Pro model
+  searchDepth: 'deep', // Uses Sonar Pro model
 });
 ```

 **Research Options:**
+
 - `searchDepth`: 'basic' | 'advanced' | 'deep'
 - `maxSources`: Number of sources to include
 - `includeWebSearch`: Enable web search (OpenAI)
 - `background`: Run as background task (OpenAI)

 **Supported Providers:**
+
 - **OpenAI**: Deep Research API with specialized models (`o3-deep-research-2025-06-26`, `o4-mini-deep-research-2025-06-26`)
 - **Anthropic**: Web Search API with domain filtering
 - **Perplexity**: Sonar and Sonar Pro models with built-in citations

+### 🧠 Extended Thinking (Anthropic)
+
+Enable Claude to spend more time reasoning about complex problems before generating responses:
+
+```typescript
+import { AnthropicProvider } from '@push.rocks/smartai';
+
+// Configure extended thinking mode at provider level
+const anthropic = new AnthropicProvider({
+  anthropicToken: 'sk-ant-...',
+  extendedThinking: 'normal', // Options: 'quick' | 'normal' | 'deep' | 'off'
+});
+
+await anthropic.start();
+
+// Extended thinking is automatically applied to all methods
+const response = await anthropic.chat({
+  systemMessage: 'You are an expert mathematician.',
+  userMessage: 'Prove the Pythagorean theorem from first principles',
+  messageHistory: [],
+});
+```
+
+**Thinking Modes:**
+
+| Mode | Budget Tokens | Use Case |
+|------|---------------|----------|
+| `'quick'` | 2,048 | Lightweight reasoning for simple queries |
+| `'normal'` | 8,000 | **Default** - Balanced reasoning for most tasks |
+| `'deep'` | 16,000 | Complex reasoning for difficult problems |
+| `'off'` | 0 | Disable extended thinking |
+
+**Best Practices:**
+
+- Start with `'normal'` (default) for general usage
+- Use `'deep'` for complex analytical tasks, philosophy, mathematics, or research
+- Use `'quick'` for simple factual queries where deep reasoning isn't needed
+- Thinking budget counts against total token usage
+
 ### 🎨 Image Generation & Editing

 Generate and edit images with OpenAI's cutting-edge models:
@@ -245,7 +292,7 @@ const image = await ai.openaiProvider.imageGenerate({
  prompt: 'A futuristic robot assistant in a modern office, digital art',
  model: 'gpt-image-1',
  quality: 'high',
-  size: '1024x1024'
+  size: '1024x1024',
 });

 // Save the generated image
@@ -259,7 +306,7 @@ const logo = await ai.openaiProvider.imageGenerate({
  quality: 'high',
  size: '1024x1024',
  background: 'transparent',
-  outputFormat: 'png'
+  outputFormat: 'png',
 });

 // WebP with compression for web use
@@ -269,15 +316,16 @@ const webImage = await ai.openaiProvider.imageGenerate({
  quality: 'high',
  size: '1536x1024',
  outputFormat: 'webp',
-  outputCompression: 85
+  outputCompression: 85,
 });

 // Superior text rendering (gpt-image-1's strength)
 const signage = await ai.openaiProvider.imageGenerate({
-  prompt: 'Vintage cafe sign saying "COFFEE & CODE" in hand-lettered typography',
+  prompt:
+    'Vintage cafe sign saying "COFFEE & CODE" in hand-lettered typography',
  model: 'gpt-image-1',
  quality: 'high',
-  size: '1024x1024'
+  size: '1024x1024',
 });

 // Generate multiple variations at once
@@ -286,7 +334,7 @@ const variations = await ai.openaiProvider.imageGenerate({
  model: 'gpt-image-1',
  n: 3,
  quality: 'medium',
-  size: '1024x1024'
+  size: '1024x1024',
 });

 // Edit an existing image
@@ -294,11 +342,12 @@ const editedImage = await ai.openaiProvider.imageEdit({
  image: originalImageBuffer,
  prompt: 'Add sunglasses and change the background to a beach sunset',
  model: 'gpt-image-1',
-  quality: 'high'
+  quality: 'high',
 });
 ```

 **Image Generation Options:**
+
 - `model`: 'gpt-image-1' | 'dall-e-3' | 'dall-e-2'
 - `quality`: 'low' | 'medium' | 'high' | 'auto'
 - `size`: Multiple aspect ratios up to 4096×4096
@@ -309,6 +358,7 @@ const editedImage = await ai.openaiProvider.imageEdit({
 - `n`: Number of images (1-10)

 **gpt-image-1 Advantages:**
+
 - Superior text rendering in images
 - Up to 4096×4096 resolution
 - Transparent background support
@@ -347,12 +397,12 @@ const supportBot = new SmartAi({
 async function handleCustomerQuery(query: string, history: ChatMessage[]) {
  try {
    const response = await supportBot.anthropicProvider.chat({
-      systemMessage: `You are a helpful customer support agent. 
+      systemMessage: `You are a helpful customer support agent.
                      Be empathetic, professional, and solution-oriented.`,
      userMessage: query,
      messageHistory: history
    });
-    
+
    return response.message;
  } catch (error) {
    // Fallback to another provider if needed
@@ -365,12 +415,12 @@ async function handleCustomerQuery(query: string, history: ChatMessage[]) {

 ```typescript
 const codeReviewer = new SmartAi({
-  groqToken: process.env.GROQ_KEY // Groq for speed
+  groqToken: process.env.GROQ_KEY, // Groq for speed
 });

 async function reviewCode(code: string, language: string) {
  const startTime = Date.now();
-  
+
  const review = await codeReviewer.groqProvider.chat({
    systemMessage: `You are a ${language} expert. Review code for:
                    - Security vulnerabilities
@@ -378,9 +428,9 @@ async function reviewCode(code: string, language: string) {
                    - Best practices
                    - Potential bugs`,
    userMessage: `Review this code:\n\n${code}`,
-    messageHistory: []
+    messageHistory: [],
  });
-  
+
  console.log(`Review completed in ${Date.now() - startTime}ms`);
  return review.message;
 }
@@ -390,17 +440,18 @@ async function reviewCode(code: string, language: string) {

 ```typescript
 const researcher = new SmartAi({
-  perplexityToken: process.env.PERPLEXITY_KEY
+  perplexityToken: process.env.PERPLEXITY_KEY,
 });

 async function research(topic: string) {
  // Perplexity excels at web-aware research
  const findings = await researcher.perplexityProvider.chat({
-    systemMessage: 'You are a research assistant. Provide factual, cited information.',
+    systemMessage:
+      'You are a research assistant. Provide factual, cited information.',
    userMessage: `Research the latest developments in ${topic}`,
-    messageHistory: []
+    messageHistory: [],
  });
-  
+
  return findings.message;
 }
 ```
@@ -412,8 +463,8 @@ const localAI = new SmartAi({
  ollama: {
    baseUrl: 'http://localhost:11434',
    model: 'llama2',
-    visionModel: 'llava'
-  }
+    visionModel: 'llava',
+  },
 });

 // Process sensitive documents without leaving your infrastructure
@@ -422,9 +473,9 @@ async function analyzeSensitiveDoc(pdfBuffer: Buffer) {
    systemMessage: 'Extract and summarize key information.',
    userMessage: 'Analyze this confidential document',
    messageHistory: [],
-    pdfDocuments: [pdfBuffer]
+    pdfDocuments: [pdfBuffer],
  });
-  
+
  // Data never leaves your servers
  return analysis.message;
 }
@@ -437,7 +488,7 @@ async function analyzeSensitiveDoc(pdfBuffer: Buffer) {
 ```typescript
 class SmartAIRouter {
  constructor(private ai: SmartAi) {}
-  
+
  async query(message: string, requirements: {
    speed?: boolean;
    accuracy?: boolean;
@@ -464,8 +515,10 @@ class SmartAIRouter {
 ```typescript
 // Don't wait for the entire response
 async function streamResponse(userQuery: string) {
-  const stream = await ai.openaiProvider.chatStream(createInputStream(userQuery));
-  
+  const stream = await ai.openaiProvider.chatStream(
+    createInputStream(userQuery),
+  );
+
  // Process tokens as they arrive
  for await (const chunk of stream) {
    updateUI(chunk); // Immediate feedback
@@ -484,7 +537,7 @@ async function consensusQuery(question: string) {
    ai.anthropicProvider.chat({...}),
    ai.perplexityProvider.chat({...})
  ];
-  
+
  const responses = await Promise.all(providers);
  return synthesizeResponses(responses);
 }
@@ -500,7 +553,7 @@ const translationStream = new TransformStream({
  async transform(chunk, controller) {
    const translated = await translateChunk(chunk);
    controller.enqueue(translated);
-  }
+  },
 });

 const responseStream = await ai.openaiProvider.chatStream(input);
@@ -512,7 +565,7 @@ const translatedStream = responseStream.pipeThrough(translationStream);
 ```typescript
 class ResilientAI {
  private providers = ['openai', 'anthropic', 'groq'];
-  
+
  async query(opts: ChatOptions): Promise<ChatResponse> {
    for (const provider of this.providers) {
      try {
@@ -535,14 +588,14 @@ class UsageTracker {
  async trackedChat(provider: string, options: ChatOptions) {
    const start = Date.now();
    const response = await ai[`${provider}Provider`].chat(options);
-    
+
    const usage = {
      provider,
      duration: Date.now() - start,
      inputTokens: estimateTokens(options),
-      outputTokens: estimateTokens(response.message)
+      outputTokens: estimateTokens(response.message),
    };
-    
+
    await this.logUsage(usage);
    return response;
  }
@@ -553,7 +606,7 @@ class UsageTracker {

 ### Prerequisites

- Node.js 16+ 
+- Node.js 16+
 - TypeScript 4.5+
 - API keys for your chosen providers

@@ -588,17 +641,17 @@ export ELEVENLABS_API_KEY=sk-...

 ## 🎯 Choosing the Right Provider

-| Use Case | Recommended Provider | Why |
-|----------|---------------------|-----|
-| **General Purpose** | OpenAI | Most features, stable, well-documented |
-| **Complex Reasoning** | Anthropic | Superior logical thinking, safer outputs |
-| **Research & Facts** | Perplexity | Web-aware, provides citations |
-| **Deep Research** | OpenAI | Deep Research API with comprehensive analysis |
-| **Premium TTS** | ElevenLabs | Most natural voices, 70+ languages, superior quality (v3) |
-| **Speed Critical** | Groq | 10x faster inference, sub-second responses |
-| **Privacy Critical** | Ollama | 100% local, no data leaves your servers |
-| **Real-time Data** | XAI | Access to current information |
-| **Cost Sensitive** | Ollama/Exo | Free (local) or distributed compute |
+| Use Case              | Recommended Provider | Why                                                       |
+| --------------------- | -------------------- | --------------------------------------------------------- |
+| **General Purpose**   | OpenAI               | Most features, stable, well-documented                    |
+| **Complex Reasoning** | Anthropic            | Superior logical thinking, safer outputs                  |
+| **Research & Facts**  | Perplexity           | Web-aware, provides citations                             |
+| **Deep Research**     | OpenAI               | Deep Research API with comprehensive analysis             |
+| **Premium TTS**       | ElevenLabs           | Most natural voices, 70+ languages, superior quality (v3) |
+| **Speed Critical**    | Groq                 | 10x faster inference, sub-second responses                |
+| **Privacy Critical**  | Ollama               | 100% local, no data leaves your servers                   |
+| **Real-time Data**    | XAI                  | Access to current information                             |
+| **Cost Sensitive**    | Ollama/Exo           | Free (local) or distributed compute                       |

 ## 📈 Roadmap

@@ -613,19 +666,21 @@ export ELEVENLABS_API_KEY=sk-...

 ## 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. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.

 **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.
+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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

 ### Company Information

-Task Venture Capital GmbH  
-Registered at District court Bremen HRB 35230 HB, Germany
+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.
+For any legal inquiries or 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.
+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.