0.8.0

changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2025-10-30 - 0.8.0 - feat(provider.anthropic)
+Add extended thinking modes to AnthropicProvider and apply thinking budgets to API calls
+
+- Introduce IAnthropicProviderOptions.extendedThinking to configure thinking modes: 'quick' | 'normal' | 'deep' | 'off'.
+- Add getThinkingConfig() helper mapping modes to token budgets (quick=2048, normal=8000, deep=16000, off=0).
+- Apply thinking configuration to Anthropic API calls (chat, chatStream, vision, document, research) and increase max_tokens where appropriate (up to 20000).
+- Add comprehensive tests (test/test.thinking.anthropic.ts) and update readme.hints.md with usage examples and recommendations.
+- Add .claude/settings.local.json for local assistant permissions used in development/testing.
+
 ## 2025-10-10 - 0.7.7 - fix(MultiModalModel)
 Lazy-load SmartPdf and guard document processing across providers; ensure SmartPdf is initialized only when needed
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartai",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "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",

readme.hints.md

@@ -1 +1,183 @@
- 
+# SmartAI Project Hints
+
+## Anthropic Extended Thinking Feature
+
+### Overview
+The Anthropic provider now supports extended thinking by default across all methods. Extended thinking enables Claude to spend more time reasoning about complex problems before generating responses, leading to higher quality answers for difficult questions.
+
+### Configuration
+
+Extended thinking is configured at the provider level during instantiation:
+
+```typescript
+import * as smartai from '@push.rocks/smartai';
+
+const provider = new smartai.AnthropicProvider({
+  anthropicToken: 'your-token-here',
+  extendedThinking: 'normal', // Options: 'quick' | 'normal' | 'deep' | 'off'
+});
+```
+
+### Thinking Modes
+
+The `extendedThinking` parameter accepts four 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 |
+
+**Default Behavior**: If `extendedThinking` is not specified, it defaults to `'normal'` mode (8,000 tokens).
+
+### Supported Methods
+
+Extended thinking is automatically applied to all Anthropic provider methods:
+- `chat()` - Synchronous chat
+- `chatStream()` - Streaming chat
+- `vision()` - Image analysis
+- `document()` - PDF document processing
+- `research()` - Web research with citations
+
+### Token Budget Constraints
+
+**Important**: The thinking budget must be less than `max_tokens` for the API call. The current `max_tokens` values are:
+
+- `chatStream()`: 20,000 tokens (sufficient for all modes ✓)
+- `chat()`: 20,000 tokens (sufficient for all modes ✓)
+- `vision()`: 10,000 tokens (sufficient for all modes ✓)
+- `document()`: 20,000 tokens (sufficient for all modes ✓)
+- `research()`: 20,000 tokens for all searchDepth levels (sufficient ✓)
+
+### Performance and Cost Implications
+
+**Token Usage**:
+- You are charged for the **full thinking tokens** generated, not just the summary
+- Higher thinking budgets may result in more thorough reasoning but increased costs
+- The budget is a **target**, not a strict limit - actual usage may vary
+
+**Response Quality**:
+- `'quick'`: Fast responses, basic reasoning
+- `'normal'`: Good balance between quality and speed (recommended for most use cases)
+- `'deep'`: Highest quality reasoning for complex problems, slower responses
+
+**Recommendations**:
+- 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
+- Use `'off'` only if you want traditional Claude behavior without extended thinking
+
+### Usage Examples
+
+#### Example 1: Default (Normal Mode)
+```typescript
+const provider = new smartai.AnthropicProvider({
+  anthropicToken: process.env.ANTHROPIC_TOKEN,
+  // extendedThinking defaults to 'normal'
+});
+
+await provider.start();
+
+const response = await provider.chat({
+  systemMessage: 'You are a helpful assistant.',
+  userMessage: 'Explain the implications of quantum computing.',
+  messageHistory: [],
+});
+```
+
+#### Example 2: Deep Thinking for Complex Analysis
+```typescript
+const provider = new smartai.AnthropicProvider({
+  anthropicToken: process.env.ANTHROPIC_TOKEN,
+  extendedThinking: 'deep', // 16,000 token budget
+});
+
+await provider.start();
+
+const response = await provider.chat({
+  systemMessage: 'You are a philosopher and ethicist.',
+  userMessage: 'Analyze the trolley problem from multiple ethical frameworks.',
+  messageHistory: [],
+});
+```
+
+#### Example 3: Quick Mode for Simple Queries
+```typescript
+const provider = new smartai.AnthropicProvider({
+  anthropicToken: process.env.ANTHROPIC_TOKEN,
+  extendedThinking: 'quick', // 2,048 token budget
+});
+
+await provider.start();
+
+const response = await provider.chat({
+  systemMessage: 'You are a helpful assistant.',
+  userMessage: 'What is the capital of France?',
+  messageHistory: [],
+});
+```
+
+#### Example 4: Disable Thinking
+```typescript
+const provider = new smartai.AnthropicProvider({
+  anthropicToken: process.env.ANTHROPIC_TOKEN,
+  extendedThinking: 'off', // No extended thinking
+});
+
+await provider.start();
+
+const response = await provider.chat({
+  systemMessage: 'You are a helpful assistant.',
+  userMessage: 'Tell me a joke.',
+  messageHistory: [],
+});
+```
+
+#### Example 5: Extended Thinking with Vision
+```typescript
+const provider = new smartai.AnthropicProvider({
+  anthropicToken: process.env.ANTHROPIC_TOKEN,
+  extendedThinking: 'normal',
+});
+
+await provider.start();
+
+const imageBuffer = await fs.promises.readFile('./image.jpg');
+const analysis = await provider.vision({
+  image: imageBuffer,
+  prompt: 'Analyze this image in detail and explain what you see.',
+});
+```
+
+### Testing
+
+Comprehensive tests for extended thinking are available in:
+- `test/test.thinking.anthropic.ts` - Tests all thinking modes
+
+Run tests with:
+```bash
+pnpm test
+```
+
+Run specific thinking tests:
+```bash
+npx tstest test/test.thinking.anthropic.ts --verbose
+```
+
+### API Reference
+
+According to Anthropic's documentation:
+- Extended thinking is supported on Claude Sonnet 4.5, 4, 3.7, Haiku 4.5, and Opus 4.1, 4
+- The current model used is `claude-sonnet-4-5-20250929`
+- Minimum thinking budget is 1,024 tokens
+- Thinking budget must be less than `max_tokens`
+
+### Implementation Details
+
+The extended thinking feature is implemented via:
+1. **Interface**: `IAnthropicProviderOptions.extendedThinking` property
+2. **Helper Method**: `getThinkingConfig()` private method that maps modes to token budgets
+3. **API Parameter**: Adds `thinking: { type: 'enabled', budget_tokens: number }` to all API calls
+
+The thinking configuration is applied automatically to all API calls when the provider is instantiated.

test/test.thinking.anthropic.ts

@@ -0,0 +1,151 @@
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as qenv from '@push.rocks/qenv';
+
+const testQenv = new qenv.Qenv('./', './.nogit/');
+
+import * as smartai from '../ts/index.js';
+
+let anthropicProviderQuick: smartai.AnthropicProvider;
+let anthropicProviderNormal: smartai.AnthropicProvider;
+let anthropicProviderDeep: smartai.AnthropicProvider;
+let anthropicProviderOff: smartai.AnthropicProvider;
+
+// Test 'quick' mode
+tap.test('Extended Thinking: should create Anthropic provider with quick mode', async () => {
+  anthropicProviderQuick = new smartai.AnthropicProvider({
+    anthropicToken: await testQenv.getEnvVarOnDemand('ANTHROPIC_TOKEN'),
+    extendedThinking: 'quick',
+  });
+  await anthropicProviderQuick.start();
+  expect(anthropicProviderQuick).toBeInstanceOf(smartai.AnthropicProvider);
+});
+
+tap.test('Extended Thinking: should chat with quick mode (2048 tokens)', async () => {
+  const userMessage = 'Explain quantum entanglement in simple terms.';
+  const response = await anthropicProviderQuick.chat({
+    systemMessage: 'You are a helpful physics teacher.',
+    userMessage: userMessage,
+    messageHistory: [],
+  });
+  console.log(`Quick Mode - User: ${userMessage}`);
+  console.log(`Quick Mode - Response length: ${response.message.length} chars`);
+  expect(response.role).toEqual('assistant');
+  expect(response.message).toBeTruthy();
+  expect(response.message.toLowerCase()).toInclude('quantum');
+});
+
+tap.test('Extended Thinking: should stop quick mode provider', async () => {
+  await anthropicProviderQuick.stop();
+});
+
+// Test 'normal' mode (default)
+tap.test('Extended Thinking: should create Anthropic provider with normal mode (default)', async () => {
+  anthropicProviderNormal = new smartai.AnthropicProvider({
+    anthropicToken: await testQenv.getEnvVarOnDemand('ANTHROPIC_TOKEN'),
+    // extendedThinking not specified, should default to 'normal'
+  });
+  await anthropicProviderNormal.start();
+  expect(anthropicProviderNormal).toBeInstanceOf(smartai.AnthropicProvider);
+});
+
+tap.test('Extended Thinking: should chat with normal mode (8000 tokens default)', async () => {
+  const userMessage = 'What are the implications of the P vs NP problem?';
+  const response = await anthropicProviderNormal.chat({
+    systemMessage: 'You are a helpful computer science expert.',
+    userMessage: userMessage,
+    messageHistory: [],
+  });
+  console.log(`Normal Mode - User: ${userMessage}`);
+  console.log(`Normal Mode - Response length: ${response.message.length} chars`);
+  expect(response.role).toEqual('assistant');
+  expect(response.message).toBeTruthy();
+  expect(response.message.length).toBeGreaterThan(50);
+});
+
+tap.test('Extended Thinking: should stop normal mode provider', async () => {
+  await anthropicProviderNormal.stop();
+});
+
+// Test 'deep' mode
+tap.test('Extended Thinking: should create Anthropic provider with deep mode', async () => {
+  anthropicProviderDeep = new smartai.AnthropicProvider({
+    anthropicToken: await testQenv.getEnvVarOnDemand('ANTHROPIC_TOKEN'),
+    extendedThinking: 'deep',
+  });
+  await anthropicProviderDeep.start();
+  expect(anthropicProviderDeep).toBeInstanceOf(smartai.AnthropicProvider);
+});
+
+tap.test('Extended Thinking: should chat with deep mode (16000 tokens)', async () => {
+  const userMessage = 'Analyze the philosophical implications of artificial consciousness.';
+  const response = await anthropicProviderDeep.chat({
+    systemMessage: 'You are a philosopher and cognitive scientist.',
+    userMessage: userMessage,
+    messageHistory: [],
+  });
+  console.log(`Deep Mode - User: ${userMessage}`);
+  console.log(`Deep Mode - Response length: ${response.message.length} chars`);
+  expect(response.role).toEqual('assistant');
+  expect(response.message).toBeTruthy();
+  expect(response.message.length).toBeGreaterThan(100);
+});
+
+tap.test('Extended Thinking: should stop deep mode provider', async () => {
+  await anthropicProviderDeep.stop();
+});
+
+// Test 'off' mode
+tap.test('Extended Thinking: should create Anthropic provider with thinking disabled', async () => {
+  anthropicProviderOff = new smartai.AnthropicProvider({
+    anthropicToken: await testQenv.getEnvVarOnDemand('ANTHROPIC_TOKEN'),
+    extendedThinking: 'off',
+  });
+  await anthropicProviderOff.start();
+  expect(anthropicProviderOff).toBeInstanceOf(smartai.AnthropicProvider);
+});
+
+tap.test('Extended Thinking: should chat with thinking disabled', async () => {
+  const userMessage = 'What is 2 + 2?';
+  const response = await anthropicProviderOff.chat({
+    systemMessage: 'You are a helpful assistant.',
+    userMessage: userMessage,
+    messageHistory: [],
+  });
+  console.log(`Thinking Off - User: ${userMessage}`);
+  console.log(`Thinking Off - Response: ${response.message}`);
+  expect(response.role).toEqual('assistant');
+  expect(response.message).toBeTruthy();
+  expect(response.message).toInclude('4');
+});
+
+tap.test('Extended Thinking: should stop off mode provider', async () => {
+  await anthropicProviderOff.stop();
+});
+
+// Test with vision method
+tap.test('Extended Thinking: should work with vision method', async () => {
+  const provider = new smartai.AnthropicProvider({
+    anthropicToken: await testQenv.getEnvVarOnDemand('ANTHROPIC_TOKEN'),
+    extendedThinking: 'normal',
+  });
+  await provider.start();
+
+  // Create a simple test image (1x1 red pixel PNG)
+  const redPixelPng = Buffer.from(
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==',
+    'base64'
+  );
+
+  const response = await provider.vision({
+    image: redPixelPng,
+    prompt: 'What color is this image?',
+  });
+
+  console.log(`Vision with Thinking - Response: ${response}`);
+  expect(response).toBeTruthy();
+  expect(response.toLowerCase()).toInclude('red');
+
+  await provider.stop();
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartai',
-  version: '0.7.7',
+  version: '0.8.0',
   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.'
 }

ts/provider.anthropic.ts

@@ -20,6 +20,7 @@ export interface IAnthropicProviderOptions {
   enableWebSearch?: boolean;
   searchDomainAllowList?: string[];
   searchDomainBlockList?: string[];
+  extendedThinking?: 'quick' | 'normal' | 'deep' | 'off';
 }
 
 export class AnthropicProvider extends MultiModalModel {
@@ -42,6 +43,25 @@ export class AnthropicProvider extends MultiModalModel {
     await super.stop();
   }
 
+  /**
+   * Returns the thinking configuration based on provider options.
+   * Defaults to 'normal' mode (8000 tokens) if not specified.
+   */
+  private getThinkingConfig(): { type: 'enabled'; budget_tokens: number } | undefined {
+    const mode = this.options.extendedThinking ?? 'normal';
+
+    const budgetMap = {
+      quick: 2048,
+      normal: 8000,
+      deep: 16000,
+      off: 0,
+    };
+
+    const budget = budgetMap[mode];
+
+    return budget > 0 ? { type: 'enabled', budget_tokens: budget } : undefined;
+  }
+
   public async chatStream(input: ReadableStream<Uint8Array>): Promise<ReadableStream<string>> {
     // Create a TextDecoder to handle incoming chunks
     const decoder = new TextDecoder();
@@ -76,12 +96,14 @@ export class AnthropicProvider extends MultiModalModel {
 
         // If we have a complete message, send it to Anthropic
         if (currentMessage) {
+          const thinkingConfig = this.getThinkingConfig();
           const stream = await this.anthropicApiClient.messages.create({
             model: 'claude-sonnet-4-5-20250929',
             messages: [{ role: currentMessage.role, content: currentMessage.content }],
             system: '',
             stream: true,
-            max_tokens: 4000,
+            max_tokens: 20000,
+            ...(thinkingConfig && { thinking: thinkingConfig }),
           });
 
           // Process each chunk from Anthropic
@@ -120,6 +142,7 @@ export class AnthropicProvider extends MultiModalModel {
       content: msg.content
     }));
 
+    const thinkingConfig = this.getThinkingConfig();
     const result = await this.anthropicApiClient.messages.create({
       model: 'claude-sonnet-4-5-20250929',
       system: optionsArg.systemMessage,
@@ -127,7 +150,8 @@ export class AnthropicProvider extends MultiModalModel {
         ...messages,
         { role: 'user' as const, content: optionsArg.userMessage }
       ],
-      max_tokens: 4000,
+      max_tokens: 20000,
+      ...(thinkingConfig && { thinking: thinkingConfig }),
     });
 
     // Extract text content from the response
@@ -167,13 +191,15 @@ export class AnthropicProvider extends MultiModalModel {
       }
     ];
 
+    const thinkingConfig = this.getThinkingConfig();
     const result = await this.anthropicApiClient.messages.create({
       model: 'claude-sonnet-4-5-20250929',
       messages: [{
         role: 'user',
         content
       }],
-      max_tokens: 1024
+      max_tokens: 10000,
+      ...(thinkingConfig && { thinking: thinkingConfig }),
     });
 
     // Extract text content from the response
@@ -229,6 +255,7 @@ export class AnthropicProvider extends MultiModalModel {
       });
     }
 
+    const thinkingConfig = this.getThinkingConfig();
     const result = await this.anthropicApiClient.messages.create({
       model: 'claude-sonnet-4-5-20250929',
       system: optionsArg.systemMessage,
@@ -236,7 +263,8 @@ export class AnthropicProvider extends MultiModalModel {
         ...messages,
         { role: 'user', content }
       ],
-      max_tokens: 4096
+      max_tokens: 20000,
+      ...(thinkingConfig && { thinking: thinkingConfig }),
     });
 
     // Extract text content from the response
@@ -286,8 +314,8 @@ export class AnthropicProvider extends MultiModalModel {
       }
 
       // Configure the request based on search depth
-      const maxTokens = optionsArg.searchDepth === 'deep' ? 8192 :
-                        optionsArg.searchDepth === 'advanced' ? 6144 : 4096;
+      const maxTokens = optionsArg.searchDepth === 'deep' ? 20000 :
+                        optionsArg.searchDepth === 'advanced' ? 20000 : 20000;
 
       // Create the research request
       const requestParams: any = {
@@ -308,6 +336,12 @@ export class AnthropicProvider extends MultiModalModel {
         requestParams.tools = tools;
       }
 
+      // Add thinking configuration if enabled
+      const thinkingConfig = this.getThinkingConfig();
+      if (thinkingConfig) {
+        requestParams.thinking = thinkingConfig;
+      }
+
       // Execute the research request
       const result = await this.anthropicApiClient.messages.create(requestParams);