fix(docs): update documentation: clarify provider capabilities, add provider capabilities summary, polish examples and formatting, and remove Serena project config
This commit is contained in:
216
readme.hints.md
216
readme.hints.md
@@ -3,7 +3,7 @@
|
||||
## Dependencies
|
||||
|
||||
- Uses `@git.zone/tstest` v3.x for testing (import from `@git.zone/tstest/tapbundle`)
|
||||
- `@push.rocks/smartfs` v1.x for file system operations (replaced smartfile)
|
||||
- `@push.rocks/smartfs` v1.x for file system operations
|
||||
- `@anthropic-ai/sdk` v0.71.x with extended thinking support
|
||||
- `@mistralai/mistralai` v1.x for Mistral OCR and chat capabilities
|
||||
- `openai` v6.x for OpenAI API integration
|
||||
@@ -14,12 +14,26 @@
|
||||
- When extended thinking is enabled, temperature parameter must NOT be set (or set to 1)
|
||||
- The `streamNode()` method was removed in smartrequest v5, use `response.stream()` with `Readable.fromWeb()` instead
|
||||
|
||||
## Provider Capabilities Summary
|
||||
|
||||
| Provider | Chat | Stream | TTS | Vision | Documents | Research | Images |
|
||||
|--------------|------|--------|-----|--------|-----------|----------|--------|
|
||||
| OpenAI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| Anthropic | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
|
||||
| Mistral | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
|
||||
| ElevenLabs | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| Ollama | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
|
||||
| XAI | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
|
||||
| Perplexity | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
|
||||
| Groq | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
| Exo | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
|
||||
## Mistral Provider Integration
|
||||
|
||||
### Overview
|
||||
|
||||
The Mistral provider supports:
|
||||
- **Document AI** via Mistral OCR 3 (December 2025) - native PDF processing without image conversion
|
||||
- **Document AI** via Mistral OCR (December 2025) - native PDF processing without image conversion
|
||||
- **Chat capabilities** using Mistral's chat models (`mistral-large-latest`, etc.)
|
||||
|
||||
### Key Advantage: Native PDF Support
|
||||
@@ -41,47 +55,12 @@ const provider = new smartai.MistralProvider({
|
||||
await provider.start();
|
||||
```
|
||||
|
||||
### Supported Methods
|
||||
|
||||
| Method | Support | Notes |
|
||||
|--------|---------|-------|
|
||||
| `chat()` | ✅ | Standard chat completion |
|
||||
| `chatStream()` | ✅ | Streaming chat responses |
|
||||
| `document()` | ✅ | Native PDF OCR - no image conversion needed |
|
||||
| `vision()` | ✅ | Image OCR with optional chat analysis |
|
||||
| `audio()` | ❌ | Not supported - use ElevenLabs |
|
||||
| `research()` | ❌ | Not supported - use Perplexity |
|
||||
| `imageGenerate()` | ❌ | Not supported - use OpenAI |
|
||||
| `imageEdit()` | ❌ | Not supported - use OpenAI |
|
||||
|
||||
### Document Processing
|
||||
|
||||
The `document()` method uses Mistral OCR to extract text from PDFs, then uses Mistral chat to process the user's query with the extracted content.
|
||||
|
||||
```typescript
|
||||
const result = await provider.document({
|
||||
systemMessage: 'You are a document analyst.',
|
||||
userMessage: 'Summarize this document.',
|
||||
pdfDocuments: [pdfBuffer],
|
||||
messageHistory: [],
|
||||
});
|
||||
```
|
||||
|
||||
### API Key
|
||||
|
||||
Tests require `MISTRAL_API_KEY` in `.nogit/env.json`.
|
||||
|
||||
### Pricing (as of December 2025)
|
||||
|
||||
- OCR: $2 per 1,000 pages ($1 with Batch API)
|
||||
- Chat: Varies by model (see Mistral pricing page)
|
||||
|
||||
## 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:
|
||||
@@ -97,8 +76,6 @@ const provider = new smartai.AnthropicProvider({
|
||||
|
||||
### Thinking Modes
|
||||
|
||||
The `extendedThinking` parameter accepts four modes:
|
||||
|
||||
| Mode | Budget Tokens | Use Case |
|
||||
| ---------- | ------------- | ----------------------------------------------- |
|
||||
| `'quick'` | 2,048 | Lightweight reasoning for simple queries |
|
||||
@@ -106,141 +83,13 @@ The `extendedThinking` parameter accepts four modes:
|
||||
| `'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).
|
||||
### Implementation Details
|
||||
|
||||
### Supported Methods
|
||||
- Extended thinking is implemented via `getThinkingConfig()` private method
|
||||
- When thinking is enabled, temperature must NOT be set
|
||||
- Uses `claude-sonnet-4-5-20250929` model
|
||||
|
||||
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
|
||||
## Testing
|
||||
|
||||
Run tests with:
|
||||
|
||||
@@ -248,27 +97,8 @@ Run tests with:
|
||||
pnpm test
|
||||
```
|
||||
|
||||
Run specific thinking tests:
|
||||
Run specific tests:
|
||||
|
||||
```bash
|
||||
npx tstest test/test.thinking.anthropic.ts --verbose
|
||||
npx tstest test/test.something.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.
|
||||
|
||||
Reference in New Issue
Block a user