smartai/readme.hints.md

# SmartAI Project Hints

## Dependencies

- Uses `@git.zone/tstest` v3.x for testing (import from `@git.zone/tstest/tapbundle`)
- `@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
- `@push.rocks/smartrequest` v5.x - uses `response.stream()` + `Readable.fromWeb()` for streaming

## Important Notes

- 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 (December 2025) - native PDF processing without image conversion
- **Chat capabilities** using Mistral's chat models (`mistral-large-latest`, etc.)

### Key Advantage: Native PDF Support

Unlike other providers that require converting PDFs to images (using SmartPdf), Mistral OCR natively accepts PDF documents as base64-encoded data. This makes document processing potentially faster and more accurate for text extraction.

### Configuration

```typescript
import * as smartai from '@push.rocks/smartai';

const provider = new smartai.MistralProvider({
  mistralToken: 'your-token-here',
  chatModel: 'mistral-large-latest',  // default
  ocrModel: 'mistral-ocr-latest',     // default
  tableFormat: 'markdown',             // 'markdown' or 'html'
});

await provider.start();
```

### API Key

Tests require `MISTRAL_API_KEY` in `.nogit/env.json`.

## Anthropic Extended Thinking Feature

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

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

### Implementation Details

- Extended thinking is implemented via `getThinkingConfig()` private method
- When thinking is enabled, temperature must NOT be set
- Uses `claude-sonnet-4-5-20250929` model

## Testing

Run tests with:

```bash
pnpm test
```

Run specific tests:

```bash
npx tstest test/test.something.ts --verbose
```