# SmartAI Project Hints

## Architecture (v1.0.0 - Vercel AI SDK rewrite)

The package is a **provider registry** built on the Vercel AI SDK (`ai` v6). The core export returns a `LanguageModelV3` from `@ai-sdk/provider`. Specialized capabilities are in subpath exports.

### Core Entry (`ts/`)
- `getModel(options)` → returns `LanguageModelV3` for any supported provider
- `getModelSetup(options)` → returns `{ model, providerOptions }` for request-time AI SDK provider options
- Providers: anthropic, openai, google, groq, mistral, xai, perplexity, ollama
- Anthropic prompt caching via `wrapLanguageModel` middleware (enabled by default)
- Custom Ollama provider implementing `LanguageModelV3` directly (for think, num_ctx support)
- OpenAI ChatGPT/Codex device-code auth in `smartai.auth.openai.ts`; `openAiChatGptAuth` routes OpenAI models to the ChatGPT Codex backend
- Node-only local auth source helpers live in `ts_openai_chatgpt_auth/` and support SmartAI, OpenCode, and Codex auth file formats

### Subpath Exports
- `@push.rocks/smartai/vision` — `analyzeImage()` using `generateText` with image content
- `@push.rocks/smartai/audio` — `textToSpeech()` using OpenAI SDK directly
- `@push.rocks/smartai/image` — `generateImage()`, `editImage()` using OpenAI SDK directly
- `@push.rocks/smartai/document` — `analyzeDocuments()` using SmartPdf + `generateText`
- `@push.rocks/smartai/ocr` — `createMistralOcrEngine()` using Mistral Document AI OCR endpoint
- `@push.rocks/smartai/research` — `research()` using `@anthropic-ai/sdk` web_search tool

## Dependencies

- `ai` ^6.0.175 — Vercel AI SDK core
- `@ai-sdk/*` — Provider packages (anthropic, openai, google, groq, mistral, xai, perplexity)
- `@ai-sdk/provider` ^3.0.10 — LanguageModelV3 types
- `@anthropic-ai/sdk` ^0.95.0 — Direct SDK for research (web search tool)
- `openai` ^6.36.0 — Direct SDK for audio TTS and image generation/editing
- `@push.rocks/smartpdf` ^4.1.3 — PDF to PNG conversion for document analysis

## Build

- `pnpm build` → `tsbuild tsfolders --allowimplicitany`
- Compiles: ts/, ts_vision/, ts_audio/, ts_image/, ts_document/, ts_ocr/, ts_research/

## Important Notes

- LanguageModelV3 uses `unified`/`raw` in FinishReason (not `type`/`rawType`)
- LanguageModelV3 system messages have `content: string` (not array)
- LanguageModelV3 file parts use `mediaType` (not `mimeType`)
- LanguageModelV3FunctionTool uses `inputSchema` (not `parameters`)
- Ollama `think` param goes at request body top level, not inside `options`
- Qwen models get default temperature 0.55 in the custom Ollama provider
- `qenv.getEnvVarOnDemand()` returns a Promise — must be awaited in tests
- OpenAI reasoning options belong in AI SDK `providerOptions`, not model construction options
- SmartAI accepts OpenAI model IDs as plain strings, including `gpt-5.5`
- ChatGPT-authenticated OpenAI model calls use `https://chatgpt.com/backend-api/codex` plus bearer access token and `ChatGPT-Account-ID`, not `https://api.openai.com/v1`

## Testing

```bash
pnpm test                            # all tests
tstest test/test.smartai.ts --verbose # core tests
tstest test/test.ollama.ts --verbose  # ollama provider tests (mocked, no API needed)
```