@proveanything/smartlinks 2.0.34 → 2.0.35

package/dist/docs/ai.md

@@ -1,1779 +1,1805 @@
-# SmartLinks AI
-
-Build AI-powered SmartLinks experiences with a practical SDK guide for responses, chat, product assistants, streaming, voice, and real-world integration patterns.
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Quick Start](#quick-start)
-- [Authentication](#authentication)
-- [Responses API](#responses-api)
-- [Chat Completions](#chat-completions)
-- [RAG: Product Assistants](#rag-product-assistants)
-- [Voice Integration](#voice-integration)
-- [Podcast Generation](#podcast-generation)
-- [Types & API reference](#types--api-reference)
-- [Usage Examples](#usage-examples)
-- [Error Handling](#error-handling)
-- [Rate Limiting](#rate-limiting)
-- [Best Practices](#best-practices)
-- [Providing Content to the AI Assistant](#providing-content-to-the-ai-assistant)
-
----
-
-## Overview
-
-This guide is written for SDK users building real products, not backend operators. It focuses on the public SDK surface, recommended starting points, and examples you can adapt directly.
-
-### Start with the path that matches your job
-
-| If you want to... | Start here |
-|---|---|
-| Build a new AI workflow | Use [Responses API](#responses-api) |
-| Add compatibility with existing chat clients | Use [Chat Completions](#chat-completions) |
-| Build a product/manual assistant | Use [RAG: Product Assistants](#rag-product-assistants) |
-| Add spoken input/output | Use [Voice Integration](#voice-integration) |
-| Add progressive rendering | Use [Streaming Responses](#streaming-responses) or [Streaming Chat](#streaming-chat) |
-
-> **Which AI chat API? Three surfaces, three jobs — don't confuse them:**
-> - **`ai.chat.responses`** — the **default for new work**. Structured input, tool use, multi-agent, streaming; you manage any history. Reach for this first.
-> - **`ai.chat.completions`** — **OpenAI-compatible** (`messages[]`). Use it *only* to drop into existing OpenAI-style code; prefer Responses for anything new.
-> - **`ai.public.chat`** (+ `getSession` / `clearSession`) — the **public product assistant** with **server-managed conversation sessions** (RAG-grounded). This is the "ongoing conversation" surface, and it's public-facing.
->
-> Responses and Completions are *generation* APIs (not single-shot vs conversation — both take history); `ai.public.chat` is the one that keeps a conversation for you.
-
-### Recommended starting points
-
-- New AI features: start with `ai.chat.responses.create(...)`
-- Product/manual assistants: start with `ai.public.chat(...)`
-- Existing OpenAI-style clients: use `ai.chat.completions.create(...)`
-- Real-time voice: use `ai.public.getToken(...)` and your provider's live client
-
-SmartLinks AI provides five main capabilities:
-
-1. **Responses API** - Preferred API for agentic workflows, multimodal inputs, and tool-driven responses
-2. **Chat Completions** - OpenAI-compatible text generation with streaming and tool calling
-3. **RAG (Retrieval-Augmented Generation)** - Document-grounded Q&A for product assistants
-4. **Voice Integration** - Voice-to-text and text-to-voice for hands-free interaction
-5. **Podcast Generation** - NotebookLM-style multi-voice conversational podcasts from documents
-
-### Key Features
-
-- ✅ Full TypeScript support with type safety
-- ✅ Streaming responses with async iterators
-- ✅ Automatic rate limit handling
-- ✅ Session management for conversations
-- ✅ Voice input/output helpers
-- ✅ Tool/function calling support
-- ✅ OpenAI-style Responses API support
-- ✅ Document indexing and retrieval
-- ✅ Customizable assistant behavior
-
----
-
-## Quick Start
-
-If you're only reading one section, start here. The three snippets below cover the most common public SDK use cases.
-
-### 1. Generate a response
-
-```typescript
-import { initializeApi, ai } from '@proveanything/smartlinks';
-
-// Initialize the SDK
-initializeApi({
-  baseURL: 'https://smartlinks.app/api/v1',
-  apiKey: process.env.SMARTLINKS_API_KEY // Required for admin endpoints
-});
-
-// Preferred: create a response
-const response = await ai.chat.responses.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  input: 'Summarize the key safety steps for descaling a coffee maker.'
-});
-
-console.log(response.output_text);
-```
-
-### 2. Build a product assistant
-
-```typescript
-import { initializeApi, ai } from '@proveanything/smartlinks';
-
-initializeApi({ baseURL: 'https://smartlinks.app/api/v1' });
-
-const answer = await ai.public.chat('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  userId: 'user-123',
-  message: 'How do I descale this machine?'
-});
-
-console.log(answer.message);
-```
-
-### 3. Stream output into your UI
-
-```typescript
-const stream = await ai.chat.responses.create('my-collection', {
-  input: 'Write a launch checklist for a new product page.',
-  stream: true
-});
-
-for await (const event of stream) {
-  if (event.type === 'response.output_text.delta') {
-    updateUi(event.delta);
-  }
-}
-```
-
----
-
-## Authentication
-
-### Admin Endpoints
-
-Admin endpoints require an API key passed during initialization:
-
-```typescript
-initializeApi({
-  baseURL: 'https://smartlinks.app/api/v1',
-  apiKey: process.env.SMARTLINKS_API_KEY
-});
-```
-
-The SDK automatically includes the API key in the `Authorization: Bearer <token>` header.
-
-### Public Endpoints
-
-Public endpoints don't require an API key but are rate-limited by `userId`:
-
-```typescript
-// No API key needed
-const response = await ai.public.chat('my-collection', {
-  productId: 'coffee-maker',
-  userId: 'user-123',
-  message: 'How do I clean this?'
-});
-```
-
----
-
-## Responses API
-
-The Responses API is the recommended starting point for new integrations. Use it when you want a single endpoint for structured input, tool use, and streaming output.
-
-### Basic Response
-
-```typescript
-const response = await ai.chat.responses.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  input: 'Write a friendly two-sentence welcome for a product assistant.'
-});
-
-console.log(response.output_text);
-```
-
-### Multimessage Input
-
-```typescript
-const response = await ai.chat.responses.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  input: [
-    {
-      role: 'system',
-      content: [
-        { type: 'input_text', text: 'You are a concise support assistant.' }
-      ]
-    },
-    {
-      role: 'user',
-      content: [
-        { type: 'input_text', text: 'Give me three troubleshooting steps for a grinder that will not start.' }
-      ]
-    }
-  ]
-});
-
-console.log(response.output_text);
-```
-
-### Streaming Responses
-
-When you pass `stream: true`, the SDK returns an `AsyncIterable` of SSE events instead of a final JSON object. You do not need to parse raw SSE frames yourself — just iterate with `for await...of`.
-
-```typescript
-const result = await ai.chat.responses.create('my-collection', {
-  input: 'Summarize the manual',
-  stream: true
-});
-
-for await (const event of result) {
-  if (event.type === 'response.output_text.delta') {
-    process.stdout.write(event.delta);
-  }
-}
-```
-
-If you omit `stream: true`, the same method returns the final `ResponsesResult` object instead.
-
-```typescript
-const stream = await ai.chat.responses.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  input: 'Explain how to descale an espresso machine step by step.',
-  stream: true
-});
-
-for await (const event of stream) {
-  if (event.type === 'response.output_text.delta') {
-    process.stdout.write(event.delta);
-  }
-}
-```
-
-### Tool Calling
-
-```typescript
-const response = await ai.chat.responses.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  input: 'What is the weather in Paris?',
-  tools: [
-    {
-      type: 'function',
-      name: 'get_weather',
-      description: 'Get the current weather for a city',
-      parameters: {
-        type: 'object',
-        properties: {
-          location: { type: 'string' }
-        },
-        required: ['location']
-      }
-    }
-  ]
-});
-
-console.log(response.output);
-```
-
-### Server-side tools (built-in agent loop)
-
-The example above is **client-relayed** tool calling: you define the tools, the model returns
-`tool_call` requests, and *your app* executes them and sends results back. For the common tools —
-reading and searching the web, vision, reading documents, generating images — the platform ships a
-curated, tested **built-in toolset it runs itself**. Opt in with `server_tools` and the server
-executes each tool and feeds the result back automatically, looping until the model has its answer.
-You get one final response; no relay code.
-
-```typescript
-// Enable the whole built-in toolset:
-const res = await ai.chat.responses.create('my-collection', {
-  model: 'balanced',
-  input: 'Research acme.com and summarise what they sell, with their brand colours.',
-  server_tools: true
-});
-console.log(res.output_text);
-console.log(res._agent.toolResults); // trace: which tools ran, with what result
-```
-
-Scope it to specific tools (recommended — smaller blast radius, faster), by name or capability:
-
-```typescript
-import { AI_TOOL_NAMES } from '@proveanything/smartlinks';
-
-const res = await ai.chat.responses.create('my-collection', {
-  input: 'Find the current price of this product and return it as JSON.',
-  server_tools: [AI_TOOL_NAMES.WEB_SEARCH, AI_TOOL_NAMES.DATA_EXTRACT],
-  // or: allowCapabilities: ['web:read'],   exclude: ['image.generate'],
-  maxSteps: 6 // cap model round-trips (1–12, default 8)
-});
-```
-
-**Streaming** surfaces tool progress as it happens — ideal for a "thinking…" UI. You get
-`agent.tool_call` / `agent.tool_result` events, then a final `response.completed`:
-
-```typescript
-const stream = await ai.chat.responses.create('my-collection', {
-  input: 'Research acme.com', server_tools: true, stream: true
-});
-for await (const ev of stream) {
-  if (ev.type === 'agent.tool_call')   showStep(`Running ${ev.name}…`);
-  if (ev.type === 'agent.tool_result') showStep(`${ev.name} done`);
-  if (ev.type === 'response.completed') render(ev.response.output_text);
-}
-```
-
-`server_tools` can't be combined with `previous_response_id`/`conversation` yet — pass prior turns
-in `input`.
-
-#### Built-in tools
-
-| Tool | Does |
-|------|------|
-| `web.search` | Live web search → candidate results (url/title/description). |
-| `web.fetchPage` | Fetch a page → clean markdown + metadata + schema.org JSON-LD. |
-| `web.extractSchema` | Return only a page's schema.org data of a given `@type` (deterministic). |
-| `document.read` | Read a document at a URL — **PDF, deck, doc**, or article — into markdown. |
-| `data.extract` | Page + JSON-schema/prompt → **typed JSON** (turn a page into UI data). |
-| `brand.assets` | Extract a site's logo, colours, and design. |
-| `web.screenshot` | Screenshot a page → hosted image URL (feed to `image.describe`). |
-| `image.describe` | Vision: describe an image / read its text. |
-| `image.generate` | Generate an image from a prompt → hosted URL. |
-| `image.fromReference` | Image-to-image: generate guided by reference image(s). |
-| `image.searchStock` | Search real stock photos (Unsplash). |
-| `image.transform` | Resize / crop / rotate / grayscale / format-convert / compress → hosted URL. |
-| `pdf.create` | Render HTML → PDF → hosted URL. |
-| `pdf.fill` | Fill an AcroForm PDF's fields (`{ field: value }`) → hosted URL. |
-| `pdf.merge` | Merge several PDFs into one, in order → hosted URL. |
-| `pdf.inspect` | Cheap, no-AI introspection: page count/sizes, which pages have a real text layer, raster present, and a routing hint (`text` vs `vision`). |
-| `pdf.render` | Rasterize one page — or just a region (`clip: { x0, y0, x1, y1 }`, 0–1 from top-left) — to a PNG at a chosen DPI → hosted image URL (permanent). Max 40 MP per call; larger requests return `code: "too_large"` + `suggestedDpi`. |
-| `image.ocr` | **Deterministic OCR** (Google Vision, no generative model): exact characters with per-word `confidence` (0–1) and pixel `bbox`, plus lines with spacing as printed. Input: `imageUrl`, or a PDF `url` + `page` + `dpi` + optional `clip`. Optional `languages` hints. Use for small print and text outlined to curves. |
-| `pdf.extract` | PDF → typed JSON in one call (schema and/or prompt). Auto-routes text vs vision. Optional per-field `confidence`/`source` (`includeConfidence`) and `bbox` (`includeBoxes`) in `fieldsMeta`. |
-| `pdf.decodeBarcodes` | Deterministically decode barcodes/QR on a page (WASM, no AI) → value + symbology + page + bbox + confidence. Use this for barcode digits, never vision. |
-| `pdf.inspectGraphics` | Prepress inspection: per-page path/image/outlined-text counts + colour spaces, plus named SPOT colours (e.g. "PANTONE 871 C"). No AI. |
-| `http.request` | SSRF-guarded outbound HTTP(S) to a public URL (call a REST API). |
-| `translate` | Translate text into one or more languages (generic, model-based). |
-
-**Working with PDFs.** The PDF tools split into *read/analyse* and *produce*:
-
-- **Read a whole PDF as text** → `document.read` (Firecrawl; good for prose/decks).
-- **Turn a PDF into structured fields** → `pdf.extract` (give it a JSON schema and/or a prompt; it
-  returns typed JSON). It routes itself, but you can drive the route yourself: call `pdf.inspect`
-  first (deterministic, no AI) to see whether each page has a real text layer, then `pdf.extract`
-  (cheap text path) or `pdf.render` → `image.describe`/vision for curve-only or raster artwork.
-- **Read small print exactly** (INCI/allergen lists, net weight, text outlined to curves) → `image.ocr`
-  with a PDF `url`, `page`, `dpi: 300–400` and a `clip` around the panel. It returns the characters it
-  sees with a per-word confidence — it never "corrects" a misspelling the way a vision model can, so
-  flag words below ~0.9 for human review rather than re-reading them with a model.
-- **Zoom in visually** (layout, artwork) → `pdf.render` with `clip` to rasterise just a region at a high
-  DPI, instead of the whole sheet. Renders over 40 MP return `code: "too_large"` with `suggestedDpi`
-  — retry at that dpi or with a smaller clip, don't blind-retry.
-- **Barcodes / QR** → `pdf.decodeBarcodes` (deterministic WASM decode) — never trust vision for barcode
-  digits; it hallucinates them.
-- **Prepress / print QA** (spot colours, colour spaces, vector vs raster) → `pdf.inspectGraphics`.
-- **A review UI that flags guessed fields** → `pdf.extract` with `includeConfidence` (per-field
-  confidence + source) and `includeBoxes` (per-field bbox on text-native pages) in `fieldsMeta`.
-- **Produce a PDF** → `pdf.create` (HTML → PDF), `pdf.fill` (populate an AcroForm's fields),
-  `pdf.merge` (combine several). These return a hosted `hostedUrl` (`pdf.create` also returns it as
-  `url`). `pdf.create` loads remote `<img>` URLs before rendering and honours `page-break-inside`; pass
-  `margin: "0"` when your HTML sets its own body margin (default page margin is 18mm/14mm).
-
-Every tool is also directly callable without the model loop via `ai.tools.run(collectionId, name,
-args)` — e.g. render a page or extract fields straight from a UI, no agent round-trip:
-
-```ts
-// Read the ingredients panel of a sleeve exactly (deterministic OCR of a clipped region)
-const { result } = await SL.ai.tools.run(collectionId, 'image.ocr', {
-  url: sleevePdfUrl, page: 1, dpi: 400,
-  clip: { x0: 0.40, y0: 0.20, x1: 0.60, y1: 0.40 },
-  languages: ['en', 'fr'],
-})
-// result.lines → [{ text: 'INGREDIENTS: Aqua, Glycerin, …', confidence: 0.97, bbox: {…} }]
-const toReview = result.words.filter((w) => w.confidence < 0.9)
-```
-
-Discover tools two ways:
-- **Design time (typed):** import `BUILTIN_AI_TOOLS`, `AI_TOOL_NAMES`, and the per-tool arg types
-  (`WebSearchArgs`, `DataExtractArgs`, `PdfExtractArgs`, …) from the SDK. This is the core set —
-  stable, versioned, documented here.
-- **Runtime (live):** `await ai.catalog(collectionId)` returns the registry as the server sees it,
-  including any future app-contributed tools. The built-in set above is always present.
-
-### Recommended Models
-
-For agentic workflows on `v1/responses`, GPT-5.6 ships in three tiers. Pass either the full model
-id (`openai/gpt-5.6-sol`) or the shorthand tier alias (`'cheap'`, `'balanced'`, `'premium'`) as
-`model` — both resolve through the same server-side model registry.
-
-| Tier | Model | Alias | Use for |
-|------|-------|-------|---------|
-| Cheapest (default) | `openai/gpt-5.6-luna` | `'cheap'` / omit `model` | Everyday chat, high-volume/simple turns |
-| Balanced | `openai/gpt-5.6-terra` | `'balanced'` | Admin agent / tool-heavy setup workflows (route default) |
-| Flagship | `openai/gpt-5.6-sol` | `'premium'` | Most demanding reasoning, coding, and multi-step tool use |
-
-Every tier supports function/tool calling, Programmatic Tool Calling, and Multi-agent (see below), and all
-three accept `service_tier: 'flex'` (≈50% cheaper, Batch-API rates, slower) or `'priority'` (premium, guaranteed
-throughput) alongside the default `'standard'` tier. Pass it straight through in the request body:
-
-```typescript
-const response = await ai.chat.responses.create('my-collection', {
-  model: 'balanced',
-  input: 'Summarize this week\'s ingested documents.',
-  service_tier: 'flex' // non-interactive/background work: cheaper, but can take minutes
-});
-```
-
-Flex requests run noticeably slower — reserve `flex` for non-production/background work (batch enrichment,
-evaluations, async jobs), not user-facing chat turns. The server already raises its own timeout to 15
-minutes for any request with `service_tier: 'flex'`, matching OpenAI's guidance — nothing to configure on
-the client. On a `429` ("resource unavailable") the request wasn't charged; retry with backoff or drop
-`service_tier` (or set it to `'auto'`) to fall back to standard processing.
-
-### Programmatic Tool Calling
-
-Lets the model write a short in-memory program that orchestrates several tool calls (filtering,
-looping, aggregating) before handing back one result, instead of a full message round-trip per
-call. Add the hosted `programmatic_tool_calling` tool, and mark each function tool the program is
-allowed to invoke with `allowed_callers: ['programmatic']`:
-
-```typescript
-const response = await ai.chat.responses.create('my-collection', {
-  model: 'balanced',
-  input: 'Compare inventory with demand for every SKU in this collection.',
-  tools: [
-    {
-      type: 'function',
-      name: 'get_inventory',
-      description: 'Return available_units for a sku',
-      parameters: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
-      output_schema: { type: 'object', properties: { sku: { type: 'string' }, available_units: { type: 'number' } } },
-      allowed_callers: ['programmatic']
-    },
-    {
-      type: 'function',
-      name: 'get_demand',
-      description: 'Return requested_units for a sku',
-      parameters: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
-      output_schema: { type: 'object', properties: { sku: { type: 'string' }, requested_units: { type: 'number' } } },
-      allowed_callers: ['programmatic']
-    },
-    { type: 'programmatic_tool_calling' }
-  ]
-});
-```
-
-The response's `output` array can include a `program` item (the generated code), one
-`function_call` item per program-issued call (tagged with `caller: { type: 'program', caller_id }`),
-and a `program_output` item with the program's final `result`/`status`. Execute the `function_call`
-items as normal and send results back keyed by their `call_id` on the next turn.
-
-### Multi-agent (subagents)
-
-Lets the root agent spawn a tree of subagents that run in parallel and get synthesized back into
-one response — useful for tasks that split cleanly into independent workstreams (e.g. research +
-draft + review). Enable it by setting `multi_agent.enabled: true` — that's the entire contract on
-your end; nothing else to configure or pass.
-
-This is upstream beta functionality (OpenAI may still be limiting it to certain accounts/rollout),
-so treat behavior and availability as subject to change until it's GA.
-
-```typescript
-const response = await ai.chat.responses.create('my-collection', {
-  model: 'premium', // Sol recommended for the root agent when spawning subagents
-  input: 'Research three competitor loyalty programs, then draft a comparison summary.',
-  multi_agent: { enabled: true, max_concurrent_subagents: 3 }
-});
-```
-
-Subagent output arrives as additional items in `output`, each tagged `agent: { agent_name: '/root/<name>' }`
-(root agent output uses `/root`). Notes/limits carried over from OpenAI's beta:
-
-- `max_concurrent_subagents` defaults to `3`
-- `reasoning.summary` and `max_tool_calls` are not supported while multi-agent is enabled
-- Streaming is not supported while multi-agent is enabled — the SDK throws if you pass both
-  `stream: true` and `multi_agent.enabled: true`
-
----
-
-## Chat Completions
-
-OpenAI-compatible chat completions with streaming and tool calling support. Use this for compatibility with existing Chat Completions integrations; prefer the Responses API for new agentic features.
-
-### Basic Chat
-
-```typescript
-const response = await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'What is the capital of France?' }
-  ]
-});
-
-console.log(response.choices[0].message.content);
-// Output: "The capital of France is Paris."
-```
-
-### Streaming Chat
-
-Stream responses in real-time for better UX:
-
-- Set `stream: true`
-- The SDK returns an `AsyncIterable<ChatCompletionChunk>`
-- Iterate over chunks with `for await...of`
-- Read incremental text from `chunk.choices[0]?.delta?.content`
-- If `stream` is omitted or `false`, the method returns the normal `ChatCompletionResponse`
-
-```typescript
-const stream = await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  messages: [
-    { role: 'user', content: 'Write a short poem about coding' }
-  ],
-  stream: true
-});
-
-for await (const chunk of stream) {
-  const content = chunk.choices[0]?.delta?.content || '';
-  process.stdout.write(content);
-}
-```
-
-### Tool/Function Calling
-
-Define tools (functions) that the AI can call:
-
-```typescript
-const tools = [
-  {
-    type: 'function',
-    function: {
-      name: 'get_weather',
-      description: 'Get the current weather for a location',
-      parameters: {
-        type: 'object',
-        properties: {
-          location: {
-            type: 'string',
-            description: 'City name'
-          },
-          unit: {
-            type: 'string',
-            enum: ['celsius', 'fahrenheit']
-          }
-        },
-        required: ['location']
-      }
-    }
-  }
-];
-
-const response = await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  messages: [
-    { role: 'user', content: 'What\'s the weather in Paris?' }
-  ],
-  tools
-});
-
-const toolCall = response.choices[0].message.tool_calls?.[0];
-if (toolCall) {
-  console.log('Function:', toolCall.function.name);
-  console.log('Arguments:', JSON.parse(toolCall.function.arguments));
-  // { location: "Paris", unit: "celsius" }
-}
-```
-
-### Available Models
-
-```typescript
-// List all available models
-const models = await ai.models.list('my-collection');
-
-// Or filter by provider / capability
-const openAiModels = await ai.models.list('my-collection', {
-  provider: 'openai'
-});
-
-const visionModels = await ai.models.list('my-collection', {
-  capability: 'vision'
-});
-
-models.data.forEach(model => {
-  console.log(`${model.name}`);
-  console.log(`  Provider: ${model.provider}`);
-  console.log(`  Context: ${model.contextWindow} tokens`);
-  console.log(`  Pricing: $${model.pricing.input}/1M input tokens`);
-});
-
-// Get specific model info
-const model = await ai.models.get('my-collection', 'google/gemini-2.5-flash');
-console.log(model.capabilities); // ['text', 'vision', 'audio', 'code']
-```
-
-Use `ai.models.list(collectionId)` as the source of truth for what your collection can use at runtime. The public docs provide recommendations, but actual availability depends on the SmartLinks model catalog exposed to that collection.
-
-**Recommended Models:**
-
-| Model | Use Case | Speed | Cost |
-|-------|----------|-------|------|
-| `openai/gpt-5.4` | Default for new agentic and structured-output workflows | Balanced | Medium |
-| `openai/gpt-5-mini` | Lower-cost general purpose and JSON tasks | Fast | Low |
-| `google/gemini-2.5-flash` | Fast multimodal and cost-sensitive general use | Fast | Low |
-| `google/gemini-2.5-pro` | Complex reasoning and heavier multimodal tasks | Slower | Higher |
-
-If you want a safe default for most new work, start with `openai/gpt-5.4`. If you want a lower-cost fallback, use `openai/gpt-5-mini` or `google/gemini-2.5-flash` depending on your latency and pricing goals.
-
----
-
-## RAG: Product Assistants
-
-Create intelligent product assistants that answer questions based on product documentation.
-
-### Setup: Index Documents
-
-First, index your product documentation:
-
-```typescript
-// Index a product manual from URL
-const result = await ai.rag.indexDocument('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  documentUrl: 'https://example.com/manuals/coffee-maker.pdf',
-  chunkSize: 500,      // Tokens per chunk
-  overlap: 50,         // Token overlap between chunks
-  provider: 'openai'   // Embedding provider
-});
-
-console.log(`Indexed ${result.chunks} chunks`);
-console.log(`Dimensions: ${result.metadata.embeddingDimensions}`);
-
-// Or index from text directly
-await ai.rag.indexDocument('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  text: 'Your product manual content here...',
-  metadata: {
-    source: 'manual',
-    version: '2.0'
-  }
-});
-```
-
-### Configure Assistant
-
-Customize the assistant's behavior:
-
-```typescript
-await ai.rag.configureAssistant('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  systemPrompt: 'You are a helpful coffee maker assistant. Be concise and friendly.',
-  model: 'google/gemini-2.5-flash',
-  temperature: 0.7,
-  maxTokensPerResponse: 500,
-  rateLimitPerUser: 20,
-  allowedTopics: ['usage', 'cleaning', 'troubleshooting'],
-  customInstructions: {
-    tone: 'friendly',
-    additionalRules: 'Always include safety warnings when relevant.'
-  }
-});
-```
-
-### Public Chat
-
-Users can chat with the product assistant without authentication:
-
-```typescript
-// First question
-const response = await ai.public.chat('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  userId: 'user-123',
-  message: 'How do I descale my coffee maker?'
-});
-
-console.log('Answer:', response.message);
-console.log('Used', response.context.chunksUsed, 'document sections');
-console.log('Top similarity:', response.context.topSimilarity);
-```
-
-### Conversation History
-
-Maintain conversation context with sessions:
-
-```typescript
-const sessionId = `session-${Date.now()}`;
-
-// First question
-const q1 = await ai.public.chat('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  userId: 'user-123',
-  message: 'How do I clean it?',
-  sessionId
-});
-
-// Follow-up question (uses history)
-const q2 = await ai.public.chat('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  userId: 'user-123',
-  message: 'How often should I do that?',
-  sessionId
-});
-
-// Get full conversation history
-const session = await ai.public.getSession('my-collection', sessionId);
-console.log('Messages:', session.messages);
-console.log('Total messages:', session.messageCount);
-
-// Clear session when done
-await ai.public.clearSession('my-collection', sessionId);
-```
-
-### Session Management
-
-```typescript
-// Get session statistics (admin)
-const stats = await ai.sessions.stats('my-collection');
-console.log('Total sessions:', stats.totalSessions);
-console.log('Active sessions:', stats.activeSessions);
-console.log('Total messages:', stats.totalMessages);
-console.log('Rate-limited users:', stats.rateLimitedUsers);
-```
-
----
-
-## Voice Integration
-
-Enable voice input and output for hands-free interaction.
-
-### Voice Patterns
-
-The SDK supports three practical voice patterns:
-
-| Pattern | Best For | SDK Building Blocks |
-|---------|----------|---------------------|
-| Voice → Text → AI → Text | Manual helper Q&A, troubleshooting steps | `ai.voice.listen()` + `ai.public.chat()` |
-| Voice → Text → AI → Voice | Hands-free assistants, accessibility | `ai.voice.listen()` + `ai.public.chat()` + `ai.voice.speak()` or `ai.tts.generate()` |
-| Real-time Voice | Low-latency spoken conversation | `ai.public.getToken()` + Gemini Live client |
-
-### Current SDK Support
-
-- `ai.voice.listen()` and `ai.voice.speak()` are browser helpers built on the Web Speech APIs.
-- `ai.public.getToken()` generates ephemeral tokens for Gemini Live sessions.
-- `ai.tts.generate()` supports server-side text-to-speech generation.
-- The SDK does not currently expose a first-class transcription endpoint like Whisper; if you need that flow, implement it as your own backend endpoint and feed the transcribed text into `ai.public.chat()` or `ai.chat.responses.create()`.
-
-### Recommended Approach
-
-For product assistants and RAG-backed support, start with Voice → Text → AI → Text/Voice. It gives you the best control over retrieval, session history, and cost. Use Gemini Live when low-latency spoken conversation matters more than deep document grounding.
-
-### Browser Voice Helpers
-
-These helpers are browser-only and rely on native speech recognition / speech synthesis support.
-
-```typescript
-// Check if voice is supported
-if (ai.voice.isSupported()) {
-  // Listen for voice input
-  const question = await ai.voice.listen('en-US');
-  console.log('User said:', question);
-  
-  // Get answer from AI
-  const response = await ai.public.chat('my-collection', {
-    productId: 'coffee-maker-deluxe',
-    userId: 'user-123',
-    message: question
-  });
-  
-  // Speak the answer
-  await ai.voice.speak(response.message, {
-    voice: 'alloy',
-    rate: 1.0
-  });
-}
-```
-
-### Voice Assistant Class
-
-Create a complete voice assistant:
-
-```typescript
-class ProductVoiceAssistant {
-  private collectionId: string;
-  private productId: string;
-  private userId: string;
-  private sessionId: string;
-
-  constructor(config: { 
-    collectionId: string;
-    productId: string;
-    userId: string;
-  }) {
-    this.collectionId = config.collectionId;
-    this.productId = config.productId;
-    this.userId = config.userId;
-    this.sessionId = `voice-${Date.now()}`;
-  }
-
-  async ask(): Promise<string> {
-    // Listen for question
-    console.log('Listening...');
-    const question = await ai.voice.listen();
-
-    // Get answer
-    console.log('Processing...');
-    const response = await ai.public.chat(this.collectionId, {
-      productId: this.productId,
-      userId: this.userId,
-      message: question,
-      sessionId: this.sessionId
-    });
-
-    // Speak answer
-    console.log('Speaking...');
-    await ai.voice.speak(response.message);
-
-    return response.message;
-  }
-
-  async getRemainingQuestions(): Promise<number> {
-    const status = await ai.public.getRateLimit(this.collectionId, this.userId);
-    return status.remaining;
-  }
-}
-
-// Usage
-const assistant = new ProductVoiceAssistant({
-  collectionId: 'my-collection',
-  productId: 'coffee-maker-deluxe',
-  userId: 'user-123'
-});
-
-await assistant.ask(); // Voice question → Voice answer
-const remaining = await assistant.getRemainingQuestions();
-console.log(`${remaining} questions remaining`);
-```
-
-### Gemini Live Integration
-
-Generate ephemeral tokens for Gemini Live (multimodal voice):
-
-Use this path for real-time voice sessions. The SDK only issues the short-lived token; the actual live connection is made with the provider client.
-
-```typescript
-// Generate token for voice session
-const token = await ai.public.getToken('my-collection', {
-  settings: {
-    ttl: 3600,        // 1 hour
-    voice: 'alloy',
-    language: 'en-US'
-  }
-});
-
-console.log('Token:', token.token);
-console.log('Expires at:', new Date(token.expiresAt));
-
-// Use token with Gemini Live API
-// (See Google's Gemini documentation)
-```
-
-### Voice + RAG Guidance
-
-For document-grounded assistants, prefer this pattern:
-
-1. Capture voice with `ai.voice.listen()` or your own transcription flow.
-2. Send the transcribed text to `ai.public.chat()`.
-3. Render the text response for readability.
-4. Optionally speak the answer with `ai.voice.speak()` or `ai.tts.generate()`.
-
-This is usually a better fit for manuals and procedural guidance than trying to use a live voice session as the primary retrieval layer.
-
----
-
-## Podcast Generation
-
-Generate NotebookLM-style multi-voice conversational podcasts from product documentation.
-
-### Generate a Podcast
-
-```typescript
-const podcast = await ai.podcast.generate('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  duration: 5,              // Target 5 minutes
-  style: 'casual',          // 'casual' | 'professional' | 'educational' | 'entertaining'
-  voices: {
-    host1: 'nova',          // Female voice
-    host2: 'onyx'           // Male voice
-  },
-  includeAudio: true        // Generate audio files
-});
-
-console.log('Podcast Title:', podcast.script.title);
-console.log('Duration:', podcast.metadata.duration, 'seconds');
-console.log('Download:', podcast.audio?.mixedUrl);
-```
-
-### Available Voices
-
-| Voice | Gender | Personality | Best For |
-|-------|--------|-------------|----------|
-| `alloy` | Neutral | Balanced, neutral | Professional podcasts |
-| `echo` | Male | Clear, authoritative | Expert/teacher role |
-| `fable` | Neutral | Warm, storytelling | Narrative content |
-| `onyx` | Male | Deep, engaging | Main host, discussions |
-| `nova` | Female | Friendly, enthusiastic | Co-host, questions |
-| `shimmer` | Female | Bright, energetic | Entertaining content |
-
-**Recommended Combinations:**
-- **Casual**: Nova + Onyx - Friendly and engaging
-- **Professional**: Alloy + Echo - Authoritative and clear
-- **Educational**: Fable + Echo - Teaching style
-- **Entertaining**: Shimmer + Onyx - High energy
-
-### Access the Script
-
-```typescript
-// View the generated script
-podcast.script.segments.forEach((segment, i) => {
-  const speaker = segment.speaker === 'host1' ? 'Host 1' : 'Host 2';
-  console.log(`${speaker}: ${segment.text}`);
-});
-```
-
-### Check Generation Status
-
-For long-running podcast generation, poll for status:
-
-```typescript
-// Start generation
-const podcast = await ai.podcast.generate('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  duration: 10,
-  includeAudio: true
-});
-
-// Poll for status
-const checkStatus = async () => {
-  const status = await ai.podcast.getStatus('my-collection', podcast.podcastId);
-  
-  console.log(`Status: ${status.status} (${status.progress}%)`);
-  
-  if (status.status === 'completed' && status.result) {
-    console.log('Podcast ready!');
-    console.log('Listen:', status.result.audio?.mixedUrl);
-    return true;
-  } else if (status.status === 'failed') {
-    console.error('Generation failed:', status.error);
-    return true;
-  }
-  
-  return false;
-};
-
-// Check every 5 seconds
-const interval = setInterval(async () => {
-  const done = await checkStatus();
-  if (done) clearInterval(interval);
-}, 5000);
-```
-
-### Text-to-Speech (TTS)
-
-Generate custom audio from text:
-
-```typescript
-const audioBlob = await ai.tts.generate('my-collection', {
-  text: 'Welcome to our podcast about coffee makers!',
-  voice: 'nova',
-  speed: 1.0,
-  format: 'mp3'
-});
-
-// Create audio URL for playback
-const audioUrl = URL.createObjectURL(audioBlob);
-```
-
----
-
-
-## Types & API reference
-
-Full TypeScript types and the per-endpoint HTTP reference for every `SL.ai.*` method live in the
-**generated** references — they're not duplicated here so they can't drift:
-
-- **[`API_SUMMARY.md`](API_SUMMARY.md)** — every function signature + type (search `ai.`).
-- **[`openapi.yaml`](../openapi.yaml)** — the raw HTTP endpoints.
-
-For inline types, use LSP hover / go-to-definition on `SL.ai.*`.
-
-## Usage Examples
-
-### Example 1: Product FAQ Bot
-
-```typescript
-async function createProductFAQ() {
-  const collectionId = 'my-collection';
-  const productId = 'coffee-maker-deluxe';
-
-  // 1. Index product documentation
-  await ai.rag.indexDocument(collectionId, {
-    productId,
-    documentUrl: 'https://example.com/manual.pdf'
-  });
-
-  // 2. Configure assistant
-  await ai.rag.configureAssistant(collectionId, {
-    productId,
-    systemPrompt: 'You are a coffee maker expert. Provide clear, step-by-step instructions.',
-    rateLimitPerUser: 30
-  });
-
-  // 3. Answer user questions
-  const answer = await ai.public.chat(collectionId, {
-    productId,
-    userId: 'user-123',
-    message: 'How do I make espresso?'
-  });
-
-  console.log(answer.message);
-}
-```
-
-### Example 2: Streaming Chatbot UI
-
-```typescript
-async function streamingChatbot(userMessage: string) {
-  const stream = await ai.chat.completions.create('my-collection', {
-    model: 'google/gemini-2.5-flash',
-    messages: [
-      { role: 'system', content: 'You are a helpful assistant.' },
-      { role: 'user', content: userMessage }
-    ],
-    stream: true
-  });
-
-  let fullResponse = '';
-  
-  for await (const chunk of stream) {
-    const content = chunk.choices[0]?.delta?.content || '';
-    fullResponse += content;
-    
-    // Update UI in real-time
-    updateChatUI(content);
-  }
-
-  return fullResponse;
-}
-```
-
-### Example 3: Multi-Turn Conversation
-
-```typescript
-async function chatConversation() {
-  const collectionId = 'my-collection';
-  const sessionId = `chat-${Date.now()}`;
-  const userId = 'user-123';
-  const productId = 'coffee-maker-deluxe';
-
-  // Question 1
-  const a1 = await ai.public.chat(collectionId, {
-    productId,
-    userId,
-    message: 'How do I clean the machine?',
-    sessionId
-  });
-  console.log('A1:', a1.message);
-
-  // Question 2 (references previous context)
-  const a2 = await ai.public.chat(collectionId, {
-    productId,
-    userId,
-    message: 'How often should I do that?',
-    sessionId
-  });
-  console.log('A2:', a2.message);
-
-  // Get full history
-  const session = await ai.public.getSession(collectionId, sessionId);
-  console.log('Full conversation:', session.messages);
-}
-```
-
-### Example 4: React Hook for Product Assistant
-
-```typescript
-import { useState, useCallback } from 'react';
-import { ai } from '@proveanything/smartlinks';
-
-export function useProductAssistant(
-  collectionId: string,
-  productId: string,
-  userId: string
-) {
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [rateLimit, setRateLimit] = useState({ remaining: 20, limit: 20 });
-
-  const ask = useCallback(async (message: string) => {
-    setLoading(true);
-    setError(null);
-
-    try {
-      const response = await ai.public.chat(collectionId, {
-        productId,
-        userId,
-        message
-      });
-
-      setRateLimit(prev => ({
-        ...prev,
-        remaining: prev.remaining - 1
-      }));
-
-      return response.message;
-    } catch (err: any) {
-      setError(err.message);
-      throw err;
-    } finally {
-      setLoading(false);
-    }
-  }, [collectionId, productId, userId]);
-
-  return { ask, loading, error, rateLimit };
-}
-
-// Usage in component
-function ProductHelp() {
-  const { ask, loading, rateLimit } = useProductAssistant(
-    'my-collection',
-    'coffee-maker',
-    'user-123'
-  );
-  const [answer, setAnswer] = useState('');
-
-  const handleAsk = async () => {
-    const response = await ask('How do I clean this?');
-    setAnswer(response);
-  };
-
-  return (
-    <div>
-      <button onClick={handleAsk} disabled={loading}>
-        {loading ? 'Asking...' : 'Ask Question'}
-      </button>
-      {answer && <p>{answer}</p>}
-      <p>{rateLimit.remaining} questions remaining</p>
-    </div>
-  );
-}
-```
-
-
----
-
-## Error Handling
-
-### Error Codes
-
-| Code | Type | HTTP Status | Description |
-|------|------|-------------|-------------|
-| `rate_limit_exceeded` | `rate_limit_error` | 429 | User exceeded rate limit |
-| `invalid_request` | `invalid_request_error` | 400 | Invalid parameters |
-| `authentication_error` | `authentication_error` | 401 | Invalid/missing API key |
-| `permission_denied` | `permission_error` | 403 | Insufficient permissions |
-| `not_found` | `not_found_error` | 404 | Resource not found |
-| `document_not_found` | `not_found_error` | 404 | Product document not indexed |
-| `server_error` | `server_error` | 500 | Internal server error |
-| `service_unavailable` | `server_error` | 503 | Service temporarily unavailable |
-
-### Error Handling Pattern
-
-```typescript
-import { SmartLinksAIError } from '@proveanything/smartlinks';
-
-async function robustChat() {
-  try {
-    const response = await ai.public.chat('my-collection', {
-      productId: 'coffee-maker',
-      userId: 'user-123',
-      message: 'Help!'
-    });
-    return response.message;
-  } catch (error) {
-    if (error instanceof SmartLinksAIError) {
-      switch (error.code) {
-        case 'rate_limit_exceeded':
-          console.error('Rate limit exceeded');
-          console.log('Try again at:', new Date(error.resetAt!));
-          break;
-        case 'document_not_found':
-          console.error('Product manual not indexed yet');
-          break;
-        case 'authentication_error':
-          console.error('Invalid API key');
-          break;
-        case 'invalid_request':
-          console.error('Invalid request:', error.message);
-          break;
-        default:
-          console.error('API error:', error.message);
-      }
-    } else {
-      console.error('Unexpected error:', error);
-    }
-    throw error;
-  }
-}
-```
-
-### Rate Limit Retry
-
-```typescript
-async function chatWithRetry(
-  request: PublicChatRequest,
-  maxRetries = 3
-) {
-  let retries = 0;
-
-  while (retries < maxRetries) {
-    try {
-      return await ai.public.chat('my-collection', request);
-    } catch (error) {
-      if (error instanceof SmartLinksAIError && error.isRateLimitError()) {
-        if (retries === maxRetries - 1) throw error;
-
-        const resetTime = new Date(error.resetAt!).getTime();
-        const waitTime = resetTime - Date.now();
-
-        console.log(`Rate limited. Waiting ${waitTime}ms...`);
-        await new Promise(resolve => setTimeout(resolve, waitTime));
-
-        retries++;
-      } else {
-        throw error;
-      }
-    }
-  }
-}
-```
-
----
-
-## Rate Limiting
-
-### Rate Limit Overview
-
-Public endpoints are rate-limited per `userId`:
-
-| Endpoint Type | Default Limit | Window |
-|--------------|---------------|--------|
-| Public Chat | 20 requests | 1 hour |
-| Token Generation | 10 requests | 1 hour |
-| Admin Endpoints | Unlimited* | - |
-
-*Admin endpoints use API key authentication and are not rate-limited by default.
-
-### Rate Limit Headers
-
-All API responses include rate limit information:
-
-```
-X-RateLimit-Limit: 20
-X-RateLimit-Remaining: 15
-X-RateLimit-Reset: 1707300000000
-```
-
-### Checking Rate Limit
-
-```typescript
-// Check rate limit status before making requests
-const status = await ai.public.getRateLimit('my-collection', 'user-123');
-
-console.log('Used:', status.used);
-console.log('Remaining:', status.remaining);
-console.log('Resets at:', new Date(status.resetAt));
-
-if (status.remaining > 0) {
-  // Safe to make request
-  await ai.public.chat(/* ... */);
-} else {
-  // Show user when they can ask again
-  console.log('Rate limit reached. Try again at:', status.resetAt);
-}
-```
-
-### Resetting Rate Limits (Admin)
-
-```typescript
-// Reset rate limit for a specific user
-await ai.rateLimit.reset('my-collection', 'user-123');
-console.log('Rate limit reset for user-123');
-```
-
----
-
-## Best Practices
-
-### 1. Choose the Right Model
-
-```typescript
-// For most new workflows (recommended default)
-await ai.chat.responses.create('my-collection', {
-  model: 'openai/gpt-5.4',
-  input: 'Create a concise onboarding checklist.'
-});
-
-// For lower-cost structured or JSON-oriented work
-await ai.chat.responses.create('my-collection', {
-  model: 'openai/gpt-5-mini',
-  input: 'Return a color palette as JSON.'
-});
-
-// For fast multimodal or cost-sensitive general use
-await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  messages: [...]
-});
-
-// When you need the actual available catalog for this collection
-const available = await ai.models.list('my-collection');
-console.log(available.data.map(model => model.id));
-```
-
-### 2. Use Streaming for Long Responses
-
-Improve perceived performance with streaming:
-
-```typescript
-// Non-streaming: User waits for full response
-const response = await ai.chat.completions.create('my-collection', {
-  messages: [...]
-});
-
-// Streaming: User sees progress immediately
-const stream = await ai.chat.completions.create('my-collection', {
-  stream: true,
-  messages: [...]
-});
-
-for await (const chunk of stream) {
-  updateUI(chunk.choices[0]?.delta?.content);
-}
-```
-
-### 3. Maintain Session Context
-
-Keep conversations coherent with session IDs:
-
-```typescript
-// Generate unique session ID per conversation
-const sessionId = `user-${userId}-product-${productId}`;
-
-// All questions in same conversation use same sessionId
-await ai.public.chat('my-collection', {
-  sessionId,
-  message: 'First question',
-  ...
-});
-
-await ai.public.chat('my-collection', {
-  sessionId,
-  message: 'Follow-up question',
-  ...
-});
-```
-
-### 4. Handle Rate Limits Gracefully
-
-Show clear feedback to users:
-
-```typescript
-try {
-  await ai.public.chat('my-collection', {...});
-} catch (error) {
-  if (error instanceof SmartLinksAIError && error.isRateLimitError()) {
-    const resetTime = new Date(error.resetAt!);
-    showNotification(
-      `You've reached your question limit. ` +
-      `Try again at ${resetTime.toLocaleTimeString()}`
-    );
-  }
-}
-```
-
-### 5. Optimize Voice UX
-
-Provide clear status updates:
-
-```typescript
-async function voiceAssistant() {
-  try {
-    showStatus('Listening...');
-    const question = await ai.voice.listen();
-
-    showStatus('Processing...');
-    const answer = await ai.public.chat('my-collection', {
-      message: question,
-      ...
-    });
-
-    showStatus('Speaking...');
-    await ai.voice.speak(answer.message);
-
-    showStatus('Ready');
-  } catch (error) {
-    showStatus('Error', error.message);
-  }
-}
-```
-
-### 6. Chunk Large Documents
-
-For better RAG performance, chunk documents appropriately:
-
-```typescript
-// For technical manuals
-await ai.rag.indexDocument('my-collection', {
-  productId: 'coffee-maker',
-  documentUrl: '...',
-  chunkSize: 500,  // Smaller chunks for precise answers
-  overlap: 50      // Overlap maintains context
-});
-
-// For narrative content
-await ai.rag.indexDocument('my-collection', {
-  productId: 'coffee-maker',
-  documentUrl: '...',
-  chunkSize: 1000, // Larger chunks for coherent responses
-  overlap: 100
-});
-```
-
-### 7. Use System Prompts Effectively
-
-Provide clear instructions:
-
-```typescript
-await ai.chat.completions.create('my-collection', {
-  messages: [
-    {
-      role: 'system',
-      content: `You are a coffee maker expert assistant.
-- Be concise and clear
-- Use numbered lists for steps
-- Always mention safety precautions
-- If unsure, ask for clarification`
-    },
-    { role: 'user', content: 'How do I descale?' }
-  ]
-});
-```
-
-### 8. Monitor Usage and Costs
-
-Track usage for cost management:
-
-```typescript
-const response = await ai.chat.completions.create('my-collection', {
-  messages: [...]
-});
-
-// Log token usage
-console.log('Usage:', response.usage);
-console.log('Prompt tokens:', response.usage.prompt_tokens);
-console.log('Completion tokens:', response.usage.completion_tokens);
-console.log('Total tokens:', response.usage.total_tokens);
-
-// Calculate estimated cost
-const model = await ai.models.get('my-collection', response.model);
-const cost = 
-  (response.usage.prompt_tokens * model.pricing.input / 1_000_000) +
-  (response.usage.completion_tokens * model.pricing.output / 1_000_000);
-console.log('Estimated cost: $', cost.toFixed(4));
-```
-
----
-
-## Providing Content to the AI Assistant
-
-The portal's built-in AI assistant can discuss the content currently visible to the user. To make this work, your app must supply contextual content when the assistant requests it. There are three extraction methods, tried in priority order:
-
-| Priority | Method | When Used |
-|----------|--------|-----------|
-| 1 | **Direct prop callback** | Container/widget rendered in the parent React context |
-| 2 | **PostMessage protocol** | App rendered in an iframe |
-| 3 | **DOM text fallback** | Neither of the above responded |
-
-This section covers **methods 1 and 2** — the ones you implement in your app.
-
-### Method 1: Direct Prop (`onRequestAIContent`)
-
-When your app is rendered as a **container** (a direct component in the parent's React tree), the framework passes an `onRequestAIContent` prop to your exported component. You do **not** call this prop yourself — the framework calls it when the AI assistant needs context.
-
-Structure your component to make current state accessible when the callback fires:
-
-```tsx
-import { useEffect, useRef } from 'react';
-
-export function PublicContainer(props) {
-  const { onRequestAIContent, appId, ...rest } = props;
-
-  // Keep a ref to the latest content so the callback always returns fresh data
-  const currentContentRef = useRef(null);
-
-  useEffect(() => {
-    currentContentRef.current = buildCurrentContent();
-  }, [relevantState]);
-
-  return <div data-app-container={appId}>{/* your UI */}</div>;
-}
-```
-
-The framework registers the content provider internally via `useAIContentExtraction.registerContentProvider()`. Your component just needs to respond when the callback is invoked.
-
-### Method 2: PostMessage Protocol (Iframes)
-
-For iframe-embedded apps the framework sends a `postMessage` request and expects a response within **500 ms**. If your app doesn't reply in time the framework falls back to DOM text extraction.
-
-**Request sent by the framework to your iframe:**
-
-```typescript
-{
-  type: 'smartlinks:request-ai-content',
-  requestId: 'ai-content-1709834567890-abc123'  // unique per request
-}
-```
-
-**Response your app must send back:**
-
-```typescript
-{
-  type: 'smartlinks:ai-content-response',
-  requestId: 'ai-content-1709834567890-abc123',  // echo back the requestId
-  content: AIContentResponse
-}
-```
-
-**Minimal implementation:**
-
-```typescript
-window.addEventListener('message', async (event) => {
-  if (event.data?.type === 'smartlinks:request-ai-content') {
-    const content = await gatherAIContent();
-
-    window.parent.postMessage({
-      type: 'smartlinks:ai-content-response',
-      requestId: event.data.requestId,
-      content,
-    }, '*');
-  }
-});
-
-async function gatherAIContent(): Promise<AIContentResponse> {
-  return {
-    text: 'The user is viewing the warranty registration form...',
-    contentLabel: 'Warranty Registration',
-  };
-}
-```
-
-### The `AIContentResponse` Interface
-
-```typescript
-interface AIContentResponse {
-  /**
-   * Plain text or markdown for the AI to use as context.
-   * Injected into the system prompt. Max recommended: ~4000 characters.
-   */
-  text: string;
-
-  /**
-   * Optional structured metadata (key-value pairs).
-   * Not used directly in prompts but available for custom providers.
-   */
-  metadata?: Record<string, unknown>;
-
-  /**
-   * Pre-built RAG configuration. When provided, the assistant can use
-  * SL.ai.public.chat() to ground answers in indexed product documents.
-   */
-  ragHint?: {
-    /** The product ID whose indexed documents should be queried */
-    productId: string;
-    /** Optional session ID for multi-turn RAG conversations */
-    sessionId?: string;
-    /** Optional context hint to help scope the RAG query */
-    context?: string;
-  };
-
-  /**
-   * Human-readable label shown in context-update messages
-   * (e.g. "Product Manual", "FAQ").
-   */
-  contentLabel?: string;
-
-  /**
-   * How the assistant should use this content:
-   * - 'context' (default): inject text into the system prompt
-  * - 'rag': use ragHint to query indexed docs via SL.ai.public.chat()
-   * - 'hybrid': inject text as context AND ground answers via RAG
-   */
-  strategy?: 'context' | 'rag' | 'hybrid';
-}
-```
-
-### Response Strategies
-
-#### `context` (Default)
-
-Return readable text. The assistant injects it into the system prompt as background knowledge. Good for descriptions, summaries, structured data, and FAQs.
-
-```typescript
-return {
-  text: `
-## Wine Details
-- **Name**: 2023 Château Margaux
-- **Region**: Bordeaux, France
-- **Tasting Notes**: Dark fruit, cedar, tobacco
-- **Food Pairing**: Lamb, aged cheese
-  `,
-  contentLabel: 'Wine Information',
-  strategy: 'context',
-};
-```
-
-#### `rag`
-
-Tell the assistant to query pre-indexed documents via SmartLinks RAG. The `text` field is minimal — the real knowledge comes from the indexed docs. Good for product manuals, large document sets, and technical specs.
-
-```typescript
-return {
-  text: 'The user is viewing the espresso machine product page.',
-  contentLabel: 'Product Assistant',
-  strategy: 'rag',
-  ragHint: {
-    productId: 'espresso-machine-pro',
-    sessionId: `rag-session-${userId}`,
-    context: 'User is on the troubleshooting section',
-  },
-};
-```
-
-When the assistant receives a `rag` strategy it routes the question through `SL.ai.public.chat()`:
-
-```typescript
-const response = await SL.ai.public.chat(collectionId, {
-  productId: ragHint.productId,
-  userId: currentUserId,
-  message: userQuestion,
-  sessionId: ragHint.sessionId,
-});
-```
-
-#### `hybrid`
-
-Combines both — the `text` is injected as additional context **and** the user's questions are also grounded via RAG. Good for museum exhibits, guided experiences, or any scenario with rich metadata alongside large document sets.
-
-```typescript
-return {
-  text: `
-## Exhibit: The Starry Night
-- **Artist**: Vincent van Gogh
-- **Year**: 1889
-- **Current Location**: Gallery 3, East Wing
-- **Audio Guide**: Available in 12 languages
-  `,
-  contentLabel: 'Museum Exhibit',
-  strategy: 'hybrid',
-  ragHint: {
-    productId: 'starry-night-exhibit',
-    context: 'Art history and technique questions',
-  },
-};
-```
-
-### Content Extraction Examples
-
-#### Museum Guide App
-
-```typescript
-async function gatherAIContent(): Promise<AIContentResponse> {
-  const exhibit = getCurrentExhibit();
-
-  return {
-    text: `
-Exhibit: "${exhibit.title}" by ${exhibit.artist}
-Period: ${exhibit.period}
-Medium: ${exhibit.medium}
-Description: ${exhibit.curatorNotes}
-Related works in this gallery: ${exhibit.relatedWorks.join(', ')}
-    `.trim(),
-    contentLabel: `Exhibit: ${exhibit.title}`,
-    strategy: 'hybrid',
-    ragHint: {
-      productId: exhibit.smartlinksProductId,
-      context: `Art history, technique, and visitor information for ${exhibit.title}`,
-    },
-    metadata: {
-      exhibitId: exhibit.id,
-      gallery: exhibit.gallery,
-      audioGuideAvailable: exhibit.hasAudioGuide,
-    },
-  };
-}
-```
-
-#### Wine Product App
-
-```typescript
-async function gatherAIContent(): Promise<AIContentResponse> {
-  const wine = getCurrentWine();
-  const reviews = await fetchRecentReviews(wine.id, 5);
-
-  return {
-    text: `
-Wine: ${wine.name} (${wine.vintage})
-Winery: ${wine.winery}
-Region: ${wine.region}, ${wine.country}
-Grape: ${wine.grape}
-ABV: ${wine.abv}%
-Price: ${wine.price}
-Tasting Notes: ${wine.tastingNotes}
-
-Recent Reviews:
-${reviews.map(r => `- "${r.text}" (${r.rating}/5)`).join('\n')}
-    `.trim(),
-    contentLabel: 'Wine Details',
-    strategy: 'context',
-  };
-}
-```
-
-#### Equipment Manual App (RAG-only)
-
-```typescript
-async function gatherAIContent(): Promise<AIContentResponse> {
-  const equipment = getCurrentEquipment();
-
-  return {
-    text: `User is viewing: ${equipment.name} (Model: ${equipment.modelNumber})`,
-    contentLabel: `${equipment.name} Assistant`,
-    strategy: 'rag',
-    ragHint: {
-      productId: equipment.smartlinksProductId,
-      sessionId: `manual-${equipment.id}-${Date.now()}`,
-      context: 'Technical manual, troubleshooting, and maintenance',
-    },
-  };
-}
-```
-
-### Timing & Lifecycle
-
-- **On navigation**: When the user navigates to a new product/proof/app, the assistant automatically requests fresh content and injects a context-update system message.
-- **On first message**: If no content has been gathered yet, the assistant requests it before the first AI call.
-- **On manual refresh**: The assistant can re-request content at any time (e.g. if the user's view within the app has changed).
-
-Content is requested **lazily** — your handler is only called when the AI assistant is active and needs context. If the user never opens the assistant, your handler is never called.
-
-### Method 3: DOM Fallback (Automatic)
-
-If your app doesn't implement either of the above, the framework extracts `innerText` from the DOM element with `data-app-container="{appId}"`, truncated to ~4000 characters. This is a **last resort** — content quality is much lower than a structured response. Implementing Method 1 or 2 is strongly recommended.
-
----
-
-## Related Documentation
-
-- [API Summary](./API_SUMMARY.md) - Complete API reference
-- [Widgets](./widgets.md) - Embedding SmartLinks components
-- [Realtime](./realtime.md) - Realtime data updates
-- [iframe Responder](./iframe-responder.md) - iframe integration
-
----
-
-## Support
-
-For questions or issues:
-
-- **Documentation:** https://smartlinks.app/docs
-- **GitHub:** https://github.com/Prove-Anything/smartlinks
-- **Email:** support@smartlinks.app
+# SmartLinks AI
+
+Build AI-powered SmartLinks experiences with a practical SDK guide for responses, chat, product assistants, streaming, voice, and real-world integration patterns.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Responses API](#responses-api)
+- [Chat Completions](#chat-completions)
+- [RAG: Product Assistants](#rag-product-assistants)
+- [Voice Integration](#voice-integration)
+- [Podcast Generation](#podcast-generation)
+- [Types & API reference](#types--api-reference)
+- [Usage Examples](#usage-examples)
+- [Error Handling](#error-handling)
+- [Rate Limiting](#rate-limiting)
+- [Best Practices](#best-practices)
+- [Providing Content to the AI Assistant](#providing-content-to-the-ai-assistant)
+
+---
+
+## Overview
+
+This guide is written for SDK users building real products, not backend operators. It focuses on the public SDK surface, recommended starting points, and examples you can adapt directly.
+
+### Start with the path that matches your job
+
+| If you want to... | Start here |
+|---|---|
+| Build a new AI workflow | Use [Responses API](#responses-api) |
+| Add compatibility with existing chat clients | Use [Chat Completions](#chat-completions) |
+| Build a product/manual assistant | Use [RAG: Product Assistants](#rag-product-assistants) |
+| Add spoken input/output | Use [Voice Integration](#voice-integration) |
+| Add progressive rendering | Use [Streaming Responses](#streaming-responses) or [Streaming Chat](#streaming-chat) |
+
+> **Which AI chat API? Three surfaces, three jobs — don't confuse them:**
+> - **`ai.chat.responses`** — the **default for new work**. Structured input, tool use, multi-agent, streaming; you manage any history. Reach for this first.
+> - **`ai.chat.completions`** — **OpenAI-compatible** (`messages[]`). Use it *only* to drop into existing OpenAI-style code; prefer Responses for anything new.
+> - **`ai.public.chat`** (+ `getSession` / `clearSession`) — the **public product assistant** with **server-managed conversation sessions** (RAG-grounded). This is the "ongoing conversation" surface, and it's public-facing.
+>
+> Responses and Completions are *generation* APIs (not single-shot vs conversation — both take history); `ai.public.chat` is the one that keeps a conversation for you.
+
+### Recommended starting points
+
+- New AI features: start with `ai.chat.responses.create(...)`
+- Product/manual assistants: start with `ai.public.chat(...)`
+- Existing OpenAI-style clients: use `ai.chat.completions.create(...)`
+- Real-time voice: use `ai.public.getToken(...)` and your provider's live client
+
+SmartLinks AI provides five main capabilities:
+
+1. **Responses API** - Preferred API for agentic workflows, multimodal inputs, and tool-driven responses
+2. **Chat Completions** - OpenAI-compatible text generation with streaming and tool calling
+3. **RAG (Retrieval-Augmented Generation)** - Document-grounded Q&A for product assistants
+4. **Voice Integration** - Voice-to-text and text-to-voice for hands-free interaction
+5. **Podcast Generation** - NotebookLM-style multi-voice conversational podcasts from documents
+
+### Key Features
+
+- ✅ Full TypeScript support with type safety
+- ✅ Streaming responses with async iterators
+- ✅ Automatic rate limit handling
+- ✅ Session management for conversations
+- ✅ Voice input/output helpers
+- ✅ Tool/function calling support
+- ✅ OpenAI-style Responses API support
+- ✅ Document indexing and retrieval
+- ✅ Customizable assistant behavior
+
+---
+
+## Quick Start
+
+If you're only reading one section, start here. The three snippets below cover the most common public SDK use cases.
+
+### 1. Generate a response
+
+```typescript
+import { initializeApi, ai } from '@proveanything/smartlinks';
+
+// Initialize the SDK
+initializeApi({
+  baseURL: 'https://smartlinks.app/api/v1',
+  apiKey: process.env.SMARTLINKS_API_KEY // Required for admin endpoints
+});
+
+// Preferred: create a response
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  input: 'Summarize the key safety steps for descaling a coffee maker.'
+});
+
+console.log(response.output_text);
+```
+
+### 2. Build a product assistant
+
+```typescript
+import { initializeApi, ai } from '@proveanything/smartlinks';
+
+initializeApi({ baseURL: 'https://smartlinks.app/api/v1' });
+
+const answer = await ai.public.chat('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  userId: 'user-123',
+  message: 'How do I descale this machine?'
+});
+
+console.log(answer.message);
+```
+
+### 3. Stream output into your UI
+
+```typescript
+const stream = await ai.chat.responses.create('my-collection', {
+  input: 'Write a launch checklist for a new product page.',
+  stream: true
+});
+
+for await (const event of stream) {
+  if (event.type === 'response.output_text.delta') {
+    updateUi(event.delta);
+  }
+}
+```
+
+---
+
+## Authentication
+
+### Admin Endpoints
+
+Admin endpoints require an API key passed during initialization:
+
+```typescript
+initializeApi({
+  baseURL: 'https://smartlinks.app/api/v1',
+  apiKey: process.env.SMARTLINKS_API_KEY
+});
+```
+
+The SDK automatically includes the API key in the `Authorization: Bearer <token>` header.
+
+### Public Endpoints
+
+Public endpoints don't require an API key but are rate-limited by `userId`:
+
+```typescript
+// No API key needed
+const response = await ai.public.chat('my-collection', {
+  productId: 'coffee-maker',
+  userId: 'user-123',
+  message: 'How do I clean this?'
+});
+```
+
+---
+
+## Responses API
+
+The Responses API is the recommended starting point for new integrations. Use it when you want a single endpoint for structured input, tool use, and streaming output.
+
+### Basic Response
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  input: 'Write a friendly two-sentence welcome for a product assistant.'
+});
+
+console.log(response.output_text);
+```
+
+### Multimessage Input
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  input: [
+    {
+      role: 'system',
+      content: [
+        { type: 'input_text', text: 'You are a concise support assistant.' }
+      ]
+    },
+    {
+      role: 'user',
+      content: [
+        { type: 'input_text', text: 'Give me three troubleshooting steps for a grinder that will not start.' }
+      ]
+    }
+  ]
+});
+
+console.log(response.output_text);
+```
+
+### Streaming Responses
+
+When you pass `stream: true`, the SDK returns an `AsyncIterable` of SSE events instead of a final JSON object. You do not need to parse raw SSE frames yourself — just iterate with `for await...of`.
+
+```typescript
+const result = await ai.chat.responses.create('my-collection', {
+  input: 'Summarize the manual',
+  stream: true
+});
+
+for await (const event of result) {
+  if (event.type === 'response.output_text.delta') {
+    process.stdout.write(event.delta);
+  }
+}
+```
+
+If you omit `stream: true`, the same method returns the final `ResponsesResult` object instead.
+
+```typescript
+const stream = await ai.chat.responses.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  input: 'Explain how to descale an espresso machine step by step.',
+  stream: true
+});
+
+for await (const event of stream) {
+  if (event.type === 'response.output_text.delta') {
+    process.stdout.write(event.delta);
+  }
+}
+```
+
+### Tool Calling
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  input: 'What is the weather in Paris?',
+  tools: [
+    {
+      type: 'function',
+      name: 'get_weather',
+      description: 'Get the current weather for a city',
+      parameters: {
+        type: 'object',
+        properties: {
+          location: { type: 'string' }
+        },
+        required: ['location']
+      }
+    }
+  ]
+});
+
+console.log(response.output);
+```
+
+### Server-side tools (built-in agent loop)
+
+The example above is **client-relayed** tool calling: you define the tools, the model returns
+`tool_call` requests, and *your app* executes them and sends results back. For the common tools —
+reading and searching the web, vision, reading documents, generating images — the platform ships a
+curated, tested **built-in toolset it runs itself**. Opt in with `server_tools` and the server
+executes each tool and feeds the result back automatically, looping until the model has its answer.
+You get one final response; no relay code.
+
+```typescript
+// Enable the whole built-in toolset:
+const res = await ai.chat.responses.create('my-collection', {
+  model: 'balanced',
+  input: 'Research acme.com and summarise what they sell, with their brand colours.',
+  server_tools: true
+});
+console.log(res.output_text);
+console.log(res._agent.toolResults); // trace: which tools ran, with what result
+```
+
+Scope it to specific tools (recommended — smaller blast radius, faster), by name or capability:
+
+```typescript
+import { AI_TOOL_NAMES } from '@proveanything/smartlinks';
+
+const res = await ai.chat.responses.create('my-collection', {
+  input: 'Find the current price of this product and return it as JSON.',
+  server_tools: [AI_TOOL_NAMES.WEB_SEARCH, AI_TOOL_NAMES.DATA_EXTRACT],
+  // or: allowCapabilities: ['web:read'],   exclude: ['image.generate'],
+  maxSteps: 6 // cap model round-trips (1–12, default 8)
+});
+```
+
+**Streaming** surfaces tool progress as it happens — ideal for a "thinking…" UI. You get
+`agent.tool_call` / `agent.tool_result` events, then a final `response.completed`:
+
+```typescript
+const stream = await ai.chat.responses.create('my-collection', {
+  input: 'Research acme.com', server_tools: true, stream: true
+});
+for await (const ev of stream) {
+  if (ev.type === 'agent.tool_call')   showStep(`Running ${ev.name}…`);
+  if (ev.type === 'agent.tool_result') showStep(`${ev.name} done`);
+  if (ev.type === 'response.completed') render(ev.response.output_text);
+}
+```
+
+`server_tools` can't be combined with `previous_response_id`/`conversation` yet — pass prior turns
+in `input`.
+
+#### Built-in tools
+
+| Tool | Does |
+|------|------|
+| `web.search` | Live web search → candidate results (url/title/description). |
+| `web.fetchPage` | Fetch a page → clean markdown + metadata + schema.org JSON-LD. |
+| `web.extractSchema` | Return only a page's schema.org data of a given `@type` (deterministic). |
+| `document.read` | Read a document at a URL — **PDF, deck, doc**, or article — into markdown. |
+| `data.extract` | Page + JSON-schema/prompt → **typed JSON** (turn a page into UI data). |
+| `brand.assets` | Extract a site's logo, colours, and design. |
+| `web.screenshot` | Screenshot a page → hosted image URL (feed to `image.describe`). |
+| `image.describe` | Vision: describe an image / read its text. |
+| `image.generate` | Generate an image from a prompt → hosted URL. |
+| `image.fromReference` | Image-to-image: generate guided by reference image(s). |
+| `image.searchStock` | Search real stock photos (Unsplash). |
+| `image.transform` | Resize / crop / rotate / grayscale / format-convert / compress → hosted URL. |
+| `pdf.create` | Render HTML → PDF → hosted URL. |
+| `pdf.fill` | Fill an AcroForm PDF's fields (`{ field: value }`) → hosted URL. |
+| `pdf.merge` | Merge several PDFs into one, in order → hosted URL. |
+| `pdf.inspect` | Cheap, no-AI introspection: page count/sizes, which pages have a real text layer, raster present, and a routing hint (`text` vs `vision`). |
+| `pdf.render` | Rasterize one page — or just a region (`clip: { x0, y0, x1, y1 }`, 0–1 from top-left) — to a PNG at a chosen DPI → hosted image URL (permanent). Max 40 MP per call; larger requests return `code: "too_large"` + `suggestedDpi`. |
+| `image.ocr` | **Deterministic OCR** (Google Vision, no generative model): exact characters with per-word `confidence` (0–1) and pixel `bbox`, plus lines with spacing as printed. Input: `imageUrl`, or a PDF `url` + `page` + `dpi` + optional `clip`. Optional `languages` hints. Use for small print and text outlined to curves. |
+| `pdf.extract` | PDF → typed JSON in one call (schema and/or prompt). Auto-routes text vs vision. Optional per-field `confidence`/`source` (`includeConfidence`) and `bbox` (`includeBoxes`) in `fieldsMeta`. |
+| `pdf.decodeBarcodes` | Deterministically decode barcodes/QR on a page (WASM, no AI) → value + symbology + page + bbox + confidence. Use this for barcode digits, never vision. |
+| `pdf.inspectGraphics` | Prepress inspection: per-page path/image/outlined-text counts + colour spaces, plus named SPOT colours (e.g. "PANTONE 871 C"). No AI. |
+| `pdf.edit` | Edit an existing PDF: replace **live** text (glyph-exact removal, neighbours never move; original font when it has the glyphs, else an embedded fallback; CMYK/spot colour kept; matches may span lines), add text / images in boxes (`colorSpace: "cmyk"` converts images for print). Per-item `results` with `verified`. |
+| `pdf.preflight` | Prepress preflight, no changes: fonts, RGB/Lab, TrimBox/BleedBox + bleed, effective image dpi, transparency, white overprint, output intent. No AI. |
+| `pdf.printReady` | RGB→CMYK with a press profile (spot colours kept), embed fonts, optional flattening, mark PDF/X-1a or PDF/X-4 with the output intent embedded, then preflight the result → `{ url, report }`. |
+| `http.request` | SSRF-guarded outbound HTTP(S) to a public URL (call a REST API). |
+| `translate` | Translate text into one or more languages (generic, model-based). |
+
+**Working with PDFs.** The PDF tools split into *read/analyse* and *produce*:
+
+- **Read a whole PDF as text** → `document.read` (Firecrawl; good for prose/decks).
+- **Turn a PDF into structured fields** → `pdf.extract` (give it a JSON schema and/or a prompt; it
+  returns typed JSON). It routes itself, but you can drive the route yourself: call `pdf.inspect`
+  first (deterministic, no AI) to see whether each page has a real text layer, then `pdf.extract`
+  (cheap text path) or `pdf.render` → `image.describe`/vision for curve-only or raster artwork.
+- **Read small print exactly** (INCI/allergen lists, net weight, text outlined to curves) → `image.ocr`
+  with a PDF `url`, `page`, `dpi: 300–400` and a `clip` around the panel. It returns the characters it
+  sees with a per-word confidence — it never "corrects" a misspelling the way a vision model can, so
+  flag words below ~0.9 for human review rather than re-reading them with a model.
+- **Zoom in visually** (layout, artwork) → `pdf.render` with `clip` to rasterise just a region at a high
+  DPI, instead of the whole sheet. Renders over 40 MP return `code: "too_large"` with `suggestedDpi`
+  — retry at that dpi or with a smaller clip, don't blind-retry.
+- **Barcodes / QR** → `pdf.decodeBarcodes` (deterministic WASM decode) — never trust vision for barcode
+  digits; it hallucinates them.
+- **Prepress / print QA** (spot colours, colour spaces, vector vs raster) → `pdf.inspectGraphics`.
+- **Change the artwork itself** → `pdf.edit`. `replaceText` edits only LIVE text: the matched glyphs are
+  cut out with an exact-width gap (nothing else moves) and the new text is drawn at the same spot, in the
+  same colour, in the original font if its embedded glyphs cover the new text (otherwise an embedded
+  fallback, reported as `usedFallbackFont`). A replacement longer than the original is flagged in `note`
+  — it may run into neighbouring text. Text outlined to curves can't be edited: the item fails with
+  "not found as live text" — put it on the designer change list. `verified: true` means the new text
+  reads back from the output.
+- **Is it print-ready?** → `pdf.preflight` (report only). **Make it print-ready** → `pdf.printReady`
+  with `profile` (`pdfx-4` default; `pdfx-1a` for CMYK-only workflows), `outputIntent` (e.g. `FOGRA39`)
+  and `bleed: { mm: 3 }`. `report.compliant` comes from preflighting the OUTPUT, so remaining issues
+  (low-res images, missing bleed, white overprint) are reported rather than hidden. Flattening for
+  PDF/X-1a turns affected pages into images — opt in with `flattenTransparency: true`.
+
+```ts
+const edited = await SL.ai.tools.run(collectionId, 'pdf.edit', {
+  url: artworkUrl,
+  replaceText: [{ id: 'f1', page: 1, find: 'Best before: see lid', replace: 'Best before: see base' }],
+})
+const ready = await SL.ai.tools.run(collectionId, 'pdf.printReady', {
+  url: edited.result.url, profile: 'pdfx-4', outputIntent: 'FOGRA39', bleed: { mm: 3 },
+})
+if (!ready.result.report.compliant) showFindings(ready.result.report.findings)
+```
+- **A review UI that flags guessed fields** → `pdf.extract` with `includeConfidence` (per-field
+  confidence + source) and `includeBoxes` (per-field bbox on text-native pages) in `fieldsMeta`.
+- **Produce a PDF** → `pdf.create` (HTML → PDF), `pdf.fill` (populate an AcroForm's fields),
+  `pdf.merge` (combine several). These return a hosted `hostedUrl` (`pdf.create` also returns it as
+  `url`). `pdf.create` loads remote `<img>` URLs before rendering and honours `page-break-inside`; pass
+  `margin: "0"` when your HTML sets its own body margin (default page margin is 18mm/14mm).
+
+Every tool is also directly callable without the model loop via `ai.tools.run(collectionId, name,
+args)` — e.g. render a page or extract fields straight from a UI, no agent round-trip:
+
+```ts
+// Read the ingredients panel of a sleeve exactly (deterministic OCR of a clipped region)
+const { result } = await SL.ai.tools.run(collectionId, 'image.ocr', {
+  url: sleevePdfUrl, page: 1, dpi: 400,
+  clip: { x0: 0.40, y0: 0.20, x1: 0.60, y1: 0.40 },
+  languages: ['en', 'fr'],
+})
+// result.lines → [{ text: 'INGREDIENTS: Aqua, Glycerin, …', confidence: 0.97, bbox: {…} }]
+const toReview = result.words.filter((w) => w.confidence < 0.9)
+```
+
+Discover tools two ways:
+- **Design time (typed):** import `BUILTIN_AI_TOOLS`, `AI_TOOL_NAMES`, and the per-tool arg types
+  (`WebSearchArgs`, `DataExtractArgs`, `PdfExtractArgs`, …) from the SDK. This is the core set —
+  stable, versioned, documented here.
+- **Runtime (live):** `await ai.catalog(collectionId)` returns the registry as the server sees it,
+  including any future app-contributed tools. The built-in set above is always present.
+
+### Recommended Models
+
+For agentic workflows on `v1/responses`, GPT-5.6 ships in three tiers. Pass either the full model
+id (`openai/gpt-5.6-sol`) or the shorthand tier alias (`'cheap'`, `'balanced'`, `'premium'`) as
+`model` — both resolve through the same server-side model registry.
+
+| Tier | Model | Alias | Use for |
+|------|-------|-------|---------|
+| Cheapest (default) | `openai/gpt-5.6-luna` | `'cheap'` / omit `model` | Everyday chat, high-volume/simple turns |
+| Balanced | `openai/gpt-5.6-terra` | `'balanced'` | Admin agent / tool-heavy setup workflows (route default) |
+| Flagship | `openai/gpt-5.6-sol` | `'premium'` | Most demanding reasoning, coding, and multi-step tool use |
+
+Every tier supports function/tool calling, Programmatic Tool Calling, and Multi-agent (see below), and all
+three accept `service_tier: 'flex'` (≈50% cheaper, Batch-API rates, slower) or `'priority'` (premium, guaranteed
+throughput) alongside the default `'standard'` tier. Pass it straight through in the request body:
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'balanced',
+  input: 'Summarize this week\'s ingested documents.',
+  service_tier: 'flex' // non-interactive/background work: cheaper, but can take minutes
+});
+```
+
+Flex requests run noticeably slower — reserve `flex` for non-production/background work (batch enrichment,
+evaluations, async jobs), not user-facing chat turns. The server already raises its own timeout to 15
+minutes for any request with `service_tier: 'flex'`, matching OpenAI's guidance — nothing to configure on
+the client. On a `429` ("resource unavailable") the request wasn't charged; retry with backoff or drop
+`service_tier` (or set it to `'auto'`) to fall back to standard processing.
+
+### Programmatic Tool Calling
+
+Lets the model write a short in-memory program that orchestrates several tool calls (filtering,
+looping, aggregating) before handing back one result, instead of a full message round-trip per
+call. Add the hosted `programmatic_tool_calling` tool, and mark each function tool the program is
+allowed to invoke with `allowed_callers: ['programmatic']`:
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'balanced',
+  input: 'Compare inventory with demand for every SKU in this collection.',
+  tools: [
+    {
+      type: 'function',
+      name: 'get_inventory',
+      description: 'Return available_units for a sku',
+      parameters: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
+      output_schema: { type: 'object', properties: { sku: { type: 'string' }, available_units: { type: 'number' } } },
+      allowed_callers: ['programmatic']
+    },
+    {
+      type: 'function',
+      name: 'get_demand',
+      description: 'Return requested_units for a sku',
+      parameters: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
+      output_schema: { type: 'object', properties: { sku: { type: 'string' }, requested_units: { type: 'number' } } },
+      allowed_callers: ['programmatic']
+    },
+    { type: 'programmatic_tool_calling' }
+  ]
+});
+```
+
+The response's `output` array can include a `program` item (the generated code), one
+`function_call` item per program-issued call (tagged with `caller: { type: 'program', caller_id }`),
+and a `program_output` item with the program's final `result`/`status`. Execute the `function_call`
+items as normal and send results back keyed by their `call_id` on the next turn.
+
+### Multi-agent (subagents)
+
+Lets the root agent spawn a tree of subagents that run in parallel and get synthesized back into
+one response — useful for tasks that split cleanly into independent workstreams (e.g. research +
+draft + review). Enable it by setting `multi_agent.enabled: true` — that's the entire contract on
+your end; nothing else to configure or pass.
+
+This is upstream beta functionality (OpenAI may still be limiting it to certain accounts/rollout),
+so treat behavior and availability as subject to change until it's GA.
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'premium', // Sol recommended for the root agent when spawning subagents
+  input: 'Research three competitor loyalty programs, then draft a comparison summary.',
+  multi_agent: { enabled: true, max_concurrent_subagents: 3 }
+});
+```
+
+Subagent output arrives as additional items in `output`, each tagged `agent: { agent_name: '/root/<name>' }`
+(root agent output uses `/root`). Notes/limits carried over from OpenAI's beta:
+
+- `max_concurrent_subagents` defaults to `3`
+- `reasoning.summary` and `max_tool_calls` are not supported while multi-agent is enabled
+- Streaming is not supported while multi-agent is enabled — the SDK throws if you pass both
+  `stream: true` and `multi_agent.enabled: true`
+
+---
+
+## Chat Completions
+
+OpenAI-compatible chat completions with streaming and tool calling support. Use this for compatibility with existing Chat Completions integrations; prefer the Responses API for new agentic features.
+
+### Basic Chat
+
+```typescript
+const response = await ai.chat.completions.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What is the capital of France?' }
+  ]
+});
+
+console.log(response.choices[0].message.content);
+// Output: "The capital of France is Paris."
+```
+
+### Streaming Chat
+
+Stream responses in real-time for better UX:
+
+- Set `stream: true`
+- The SDK returns an `AsyncIterable<ChatCompletionChunk>`
+- Iterate over chunks with `for await...of`
+- Read incremental text from `chunk.choices[0]?.delta?.content`
+- If `stream` is omitted or `false`, the method returns the normal `ChatCompletionResponse`
+
+```typescript
+const stream = await ai.chat.completions.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  messages: [
+    { role: 'user', content: 'Write a short poem about coding' }
+  ],
+  stream: true
+});
+
+for await (const chunk of stream) {
+  const content = chunk.choices[0]?.delta?.content || '';
+  process.stdout.write(content);
+}
+```
+
+### Tool/Function Calling
+
+Define tools (functions) that the AI can call:
+
+```typescript
+const tools = [
+  {
+    type: 'function',
+    function: {
+      name: 'get_weather',
+      description: 'Get the current weather for a location',
+      parameters: {
+        type: 'object',
+        properties: {
+          location: {
+            type: 'string',
+            description: 'City name'
+          },
+          unit: {
+            type: 'string',
+            enum: ['celsius', 'fahrenheit']
+          }
+        },
+        required: ['location']
+      }
+    }
+  }
+];
+
+const response = await ai.chat.completions.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  messages: [
+    { role: 'user', content: 'What\'s the weather in Paris?' }
+  ],
+  tools
+});
+
+const toolCall = response.choices[0].message.tool_calls?.[0];
+if (toolCall) {
+  console.log('Function:', toolCall.function.name);
+  console.log('Arguments:', JSON.parse(toolCall.function.arguments));
+  // { location: "Paris", unit: "celsius" }
+}
+```
+
+### Available Models
+
+```typescript
+// List all available models
+const models = await ai.models.list('my-collection');
+
+// Or filter by provider / capability
+const openAiModels = await ai.models.list('my-collection', {
+  provider: 'openai'
+});
+
+const visionModels = await ai.models.list('my-collection', {
+  capability: 'vision'
+});
+
+models.data.forEach(model => {
+  console.log(`${model.name}`);
+  console.log(`  Provider: ${model.provider}`);
+  console.log(`  Context: ${model.contextWindow} tokens`);
+  console.log(`  Pricing: $${model.pricing.input}/1M input tokens`);
+});
+
+// Get specific model info
+const model = await ai.models.get('my-collection', 'google/gemini-2.5-flash');
+console.log(model.capabilities); // ['text', 'vision', 'audio', 'code']
+```
+
+Use `ai.models.list(collectionId)` as the source of truth for what your collection can use at runtime. The public docs provide recommendations, but actual availability depends on the SmartLinks model catalog exposed to that collection.
+
+**Recommended Models:**
+
+| Model | Use Case | Speed | Cost |
+|-------|----------|-------|------|
+| `openai/gpt-5.4` | Default for new agentic and structured-output workflows | Balanced | Medium |
+| `openai/gpt-5-mini` | Lower-cost general purpose and JSON tasks | Fast | Low |
+| `google/gemini-2.5-flash` | Fast multimodal and cost-sensitive general use | Fast | Low |
+| `google/gemini-2.5-pro` | Complex reasoning and heavier multimodal tasks | Slower | Higher |
+
+If you want a safe default for most new work, start with `openai/gpt-5.4`. If you want a lower-cost fallback, use `openai/gpt-5-mini` or `google/gemini-2.5-flash` depending on your latency and pricing goals.
+
+---
+
+## RAG: Product Assistants
+
+Create intelligent product assistants that answer questions based on product documentation.
+
+### Setup: Index Documents
+
+First, index your product documentation:
+
+```typescript
+// Index a product manual from URL
+const result = await ai.rag.indexDocument('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  documentUrl: 'https://example.com/manuals/coffee-maker.pdf',
+  chunkSize: 500,      // Tokens per chunk
+  overlap: 50,         // Token overlap between chunks
+  provider: 'openai'   // Embedding provider
+});
+
+console.log(`Indexed ${result.chunks} chunks`);
+console.log(`Dimensions: ${result.metadata.embeddingDimensions}`);
+
+// Or index from text directly
+await ai.rag.indexDocument('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  text: 'Your product manual content here...',
+  metadata: {
+    source: 'manual',
+    version: '2.0'
+  }
+});
+```
+
+### Configure Assistant
+
+Customize the assistant's behavior:
+
+```typescript
+await ai.rag.configureAssistant('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  systemPrompt: 'You are a helpful coffee maker assistant. Be concise and friendly.',
+  model: 'google/gemini-2.5-flash',
+  temperature: 0.7,
+  maxTokensPerResponse: 500,
+  rateLimitPerUser: 20,
+  allowedTopics: ['usage', 'cleaning', 'troubleshooting'],
+  customInstructions: {
+    tone: 'friendly',
+    additionalRules: 'Always include safety warnings when relevant.'
+  }
+});
+```
+
+### Public Chat
+
+Users can chat with the product assistant without authentication:
+
+```typescript
+// First question
+const response = await ai.public.chat('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  userId: 'user-123',
+  message: 'How do I descale my coffee maker?'
+});
+
+console.log('Answer:', response.message);
+console.log('Used', response.context.chunksUsed, 'document sections');
+console.log('Top similarity:', response.context.topSimilarity);
+```
+
+### Conversation History
+
+Maintain conversation context with sessions:
+
+```typescript
+const sessionId = `session-${Date.now()}`;
+
+// First question
+const q1 = await ai.public.chat('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  userId: 'user-123',
+  message: 'How do I clean it?',
+  sessionId
+});
+
+// Follow-up question (uses history)
+const q2 = await ai.public.chat('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  userId: 'user-123',
+  message: 'How often should I do that?',
+  sessionId
+});
+
+// Get full conversation history
+const session = await ai.public.getSession('my-collection', sessionId);
+console.log('Messages:', session.messages);
+console.log('Total messages:', session.messageCount);
+
+// Clear session when done
+await ai.public.clearSession('my-collection', sessionId);
+```
+
+### Session Management
+
+```typescript
+// Get session statistics (admin)
+const stats = await ai.sessions.stats('my-collection');
+console.log('Total sessions:', stats.totalSessions);
+console.log('Active sessions:', stats.activeSessions);
+console.log('Total messages:', stats.totalMessages);
+console.log('Rate-limited users:', stats.rateLimitedUsers);
+```
+
+---
+
+## Voice Integration
+
+Enable voice input and output for hands-free interaction.
+
+### Voice Patterns
+
+The SDK supports three practical voice patterns:
+
+| Pattern | Best For | SDK Building Blocks |
+|---------|----------|---------------------|
+| Voice → Text → AI → Text | Manual helper Q&A, troubleshooting steps | `ai.voice.listen()` + `ai.public.chat()` |
+| Voice → Text → AI → Voice | Hands-free assistants, accessibility | `ai.voice.listen()` + `ai.public.chat()` + `ai.voice.speak()` or `ai.tts.generate()` |
+| Real-time Voice | Low-latency spoken conversation | `ai.public.getToken()` + Gemini Live client |
+
+### Current SDK Support
+
+- `ai.voice.listen()` and `ai.voice.speak()` are browser helpers built on the Web Speech APIs.
+- `ai.public.getToken()` generates ephemeral tokens for Gemini Live sessions.
+- `ai.tts.generate()` supports server-side text-to-speech generation.
+- The SDK does not currently expose a first-class transcription endpoint like Whisper; if you need that flow, implement it as your own backend endpoint and feed the transcribed text into `ai.public.chat()` or `ai.chat.responses.create()`.
+
+### Recommended Approach
+
+For product assistants and RAG-backed support, start with Voice → Text → AI → Text/Voice. It gives you the best control over retrieval, session history, and cost. Use Gemini Live when low-latency spoken conversation matters more than deep document grounding.
+
+### Browser Voice Helpers
+
+These helpers are browser-only and rely on native speech recognition / speech synthesis support.
+
+```typescript
+// Check if voice is supported
+if (ai.voice.isSupported()) {
+  // Listen for voice input
+  const question = await ai.voice.listen('en-US');
+  console.log('User said:', question);
+  
+  // Get answer from AI
+  const response = await ai.public.chat('my-collection', {
+    productId: 'coffee-maker-deluxe',
+    userId: 'user-123',
+    message: question
+  });
+  
+  // Speak the answer
+  await ai.voice.speak(response.message, {
+    voice: 'alloy',
+    rate: 1.0
+  });
+}
+```
+
+### Voice Assistant Class
+
+Create a complete voice assistant:
+
+```typescript
+class ProductVoiceAssistant {
+  private collectionId: string;
+  private productId: string;
+  private userId: string;
+  private sessionId: string;
+
+  constructor(config: { 
+    collectionId: string;
+    productId: string;
+    userId: string;
+  }) {
+    this.collectionId = config.collectionId;
+    this.productId = config.productId;
+    this.userId = config.userId;
+    this.sessionId = `voice-${Date.now()}`;
+  }
+
+  async ask(): Promise<string> {
+    // Listen for question
+    console.log('Listening...');
+    const question = await ai.voice.listen();
+
+    // Get answer
+    console.log('Processing...');
+    const response = await ai.public.chat(this.collectionId, {
+      productId: this.productId,
+      userId: this.userId,
+      message: question,
+      sessionId: this.sessionId
+    });
+
+    // Speak answer
+    console.log('Speaking...');
+    await ai.voice.speak(response.message);
+
+    return response.message;
+  }
+
+  async getRemainingQuestions(): Promise<number> {
+    const status = await ai.public.getRateLimit(this.collectionId, this.userId);
+    return status.remaining;
+  }
+}
+
+// Usage
+const assistant = new ProductVoiceAssistant({
+  collectionId: 'my-collection',
+  productId: 'coffee-maker-deluxe',
+  userId: 'user-123'
+});
+
+await assistant.ask(); // Voice question → Voice answer
+const remaining = await assistant.getRemainingQuestions();
+console.log(`${remaining} questions remaining`);
+```
+
+### Gemini Live Integration
+
+Generate ephemeral tokens for Gemini Live (multimodal voice):
+
+Use this path for real-time voice sessions. The SDK only issues the short-lived token; the actual live connection is made with the provider client.
+
+```typescript
+// Generate token for voice session
+const token = await ai.public.getToken('my-collection', {
+  settings: {
+    ttl: 3600,        // 1 hour
+    voice: 'alloy',
+    language: 'en-US'
+  }
+});
+
+console.log('Token:', token.token);
+console.log('Expires at:', new Date(token.expiresAt));
+
+// Use token with Gemini Live API
+// (See Google's Gemini documentation)
+```
+
+### Voice + RAG Guidance
+
+For document-grounded assistants, prefer this pattern:
+
+1. Capture voice with `ai.voice.listen()` or your own transcription flow.
+2. Send the transcribed text to `ai.public.chat()`.
+3. Render the text response for readability.
+4. Optionally speak the answer with `ai.voice.speak()` or `ai.tts.generate()`.
+
+This is usually a better fit for manuals and procedural guidance than trying to use a live voice session as the primary retrieval layer.
+
+---
+
+## Podcast Generation
+
+Generate NotebookLM-style multi-voice conversational podcasts from product documentation.
+
+### Generate a Podcast
+
+```typescript
+const podcast = await ai.podcast.generate('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  duration: 5,              // Target 5 minutes
+  style: 'casual',          // 'casual' | 'professional' | 'educational' | 'entertaining'
+  voices: {
+    host1: 'nova',          // Female voice
+    host2: 'onyx'           // Male voice
+  },
+  includeAudio: true        // Generate audio files
+});
+
+console.log('Podcast Title:', podcast.script.title);
+console.log('Duration:', podcast.metadata.duration, 'seconds');
+console.log('Download:', podcast.audio?.mixedUrl);
+```
+
+### Available Voices
+
+| Voice | Gender | Personality | Best For |
+|-------|--------|-------------|----------|
+| `alloy` | Neutral | Balanced, neutral | Professional podcasts |
+| `echo` | Male | Clear, authoritative | Expert/teacher role |
+| `fable` | Neutral | Warm, storytelling | Narrative content |
+| `onyx` | Male | Deep, engaging | Main host, discussions |
+| `nova` | Female | Friendly, enthusiastic | Co-host, questions |
+| `shimmer` | Female | Bright, energetic | Entertaining content |
+
+**Recommended Combinations:**
+- **Casual**: Nova + Onyx - Friendly and engaging
+- **Professional**: Alloy + Echo - Authoritative and clear
+- **Educational**: Fable + Echo - Teaching style
+- **Entertaining**: Shimmer + Onyx - High energy
+
+### Access the Script
+
+```typescript
+// View the generated script
+podcast.script.segments.forEach((segment, i) => {
+  const speaker = segment.speaker === 'host1' ? 'Host 1' : 'Host 2';
+  console.log(`${speaker}: ${segment.text}`);
+});
+```
+
+### Check Generation Status
+
+For long-running podcast generation, poll for status:
+
+```typescript
+// Start generation
+const podcast = await ai.podcast.generate('my-collection', {
+  productId: 'coffee-maker-deluxe',
+  duration: 10,
+  includeAudio: true
+});
+
+// Poll for status
+const checkStatus = async () => {
+  const status = await ai.podcast.getStatus('my-collection', podcast.podcastId);
+  
+  console.log(`Status: ${status.status} (${status.progress}%)`);
+  
+  if (status.status === 'completed' && status.result) {
+    console.log('Podcast ready!');
+    console.log('Listen:', status.result.audio?.mixedUrl);
+    return true;
+  } else if (status.status === 'failed') {
+    console.error('Generation failed:', status.error);
+    return true;
+  }
+  
+  return false;
+};
+
+// Check every 5 seconds
+const interval = setInterval(async () => {
+  const done = await checkStatus();
+  if (done) clearInterval(interval);
+}, 5000);
+```
+
+### Text-to-Speech (TTS)
+
+Generate custom audio from text:
+
+```typescript
+const audioBlob = await ai.tts.generate('my-collection', {
+  text: 'Welcome to our podcast about coffee makers!',
+  voice: 'nova',
+  speed: 1.0,
+  format: 'mp3'
+});
+
+// Create audio URL for playback
+const audioUrl = URL.createObjectURL(audioBlob);
+```
+
+---
+
+
+## Types & API reference
+
+Full TypeScript types and the per-endpoint HTTP reference for every `SL.ai.*` method live in the
+**generated** references — they're not duplicated here so they can't drift:
+
+- **[`API_SUMMARY.md`](API_SUMMARY.md)** — every function signature + type (search `ai.`).
+- **[`openapi.yaml`](../openapi.yaml)** — the raw HTTP endpoints.
+
+For inline types, use LSP hover / go-to-definition on `SL.ai.*`.
+
+## Usage Examples
+
+### Example 1: Product FAQ Bot
+
+```typescript
+async function createProductFAQ() {
+  const collectionId = 'my-collection';
+  const productId = 'coffee-maker-deluxe';
+
+  // 1. Index product documentation
+  await ai.rag.indexDocument(collectionId, {
+    productId,
+    documentUrl: 'https://example.com/manual.pdf'
+  });
+
+  // 2. Configure assistant
+  await ai.rag.configureAssistant(collectionId, {
+    productId,
+    systemPrompt: 'You are a coffee maker expert. Provide clear, step-by-step instructions.',
+    rateLimitPerUser: 30
+  });
+
+  // 3. Answer user questions
+  const answer = await ai.public.chat(collectionId, {
+    productId,
+    userId: 'user-123',
+    message: 'How do I make espresso?'
+  });
+
+  console.log(answer.message);
+}
+```
+
+### Example 2: Streaming Chatbot UI
+
+```typescript
+async function streamingChatbot(userMessage: string) {
+  const stream = await ai.chat.completions.create('my-collection', {
+    model: 'google/gemini-2.5-flash',
+    messages: [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: userMessage }
+    ],
+    stream: true
+  });
+
+  let fullResponse = '';
+  
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content || '';
+    fullResponse += content;
+    
+    // Update UI in real-time
+    updateChatUI(content);
+  }
+
+  return fullResponse;
+}
+```
+
+### Example 3: Multi-Turn Conversation
+
+```typescript
+async function chatConversation() {
+  const collectionId = 'my-collection';
+  const sessionId = `chat-${Date.now()}`;
+  const userId = 'user-123';
+  const productId = 'coffee-maker-deluxe';
+
+  // Question 1
+  const a1 = await ai.public.chat(collectionId, {
+    productId,
+    userId,
+    message: 'How do I clean the machine?',
+    sessionId
+  });
+  console.log('A1:', a1.message);
+
+  // Question 2 (references previous context)
+  const a2 = await ai.public.chat(collectionId, {
+    productId,
+    userId,
+    message: 'How often should I do that?',
+    sessionId
+  });
+  console.log('A2:', a2.message);
+
+  // Get full history
+  const session = await ai.public.getSession(collectionId, sessionId);
+  console.log('Full conversation:', session.messages);
+}
+```
+
+### Example 4: React Hook for Product Assistant
+
+```typescript
+import { useState, useCallback } from 'react';
+import { ai } from '@proveanything/smartlinks';
+
+export function useProductAssistant(
+  collectionId: string,
+  productId: string,
+  userId: string
+) {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [rateLimit, setRateLimit] = useState({ remaining: 20, limit: 20 });
+
+  const ask = useCallback(async (message: string) => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const response = await ai.public.chat(collectionId, {
+        productId,
+        userId,
+        message
+      });
+
+      setRateLimit(prev => ({
+        ...prev,
+        remaining: prev.remaining - 1
+      }));
+
+      return response.message;
+    } catch (err: any) {
+      setError(err.message);
+      throw err;
+    } finally {
+      setLoading(false);
+    }
+  }, [collectionId, productId, userId]);
+
+  return { ask, loading, error, rateLimit };
+}
+
+// Usage in component
+function ProductHelp() {
+  const { ask, loading, rateLimit } = useProductAssistant(
+    'my-collection',
+    'coffee-maker',
+    'user-123'
+  );
+  const [answer, setAnswer] = useState('');
+
+  const handleAsk = async () => {
+    const response = await ask('How do I clean this?');
+    setAnswer(response);
+  };
+
+  return (
+    <div>
+      <button onClick={handleAsk} disabled={loading}>
+        {loading ? 'Asking...' : 'Ask Question'}
+      </button>
+      {answer && <p>{answer}</p>}
+      <p>{rateLimit.remaining} questions remaining</p>
+    </div>
+  );
+}
+```
+
+
+---
+
+## Error Handling
+
+### Error Codes
+
+| Code | Type | HTTP Status | Description |
+|------|------|-------------|-------------|
+| `rate_limit_exceeded` | `rate_limit_error` | 429 | User exceeded rate limit |
+| `invalid_request` | `invalid_request_error` | 400 | Invalid parameters |
+| `authentication_error` | `authentication_error` | 401 | Invalid/missing API key |
+| `permission_denied` | `permission_error` | 403 | Insufficient permissions |
+| `not_found` | `not_found_error` | 404 | Resource not found |
+| `document_not_found` | `not_found_error` | 404 | Product document not indexed |
+| `server_error` | `server_error` | 500 | Internal server error |
+| `service_unavailable` | `server_error` | 503 | Service temporarily unavailable |
+
+### Error Handling Pattern
+
+```typescript
+import { SmartLinksAIError } from '@proveanything/smartlinks';
+
+async function robustChat() {
+  try {
+    const response = await ai.public.chat('my-collection', {
+      productId: 'coffee-maker',
+      userId: 'user-123',
+      message: 'Help!'
+    });
+    return response.message;
+  } catch (error) {
+    if (error instanceof SmartLinksAIError) {
+      switch (error.code) {
+        case 'rate_limit_exceeded':
+          console.error('Rate limit exceeded');
+          console.log('Try again at:', new Date(error.resetAt!));
+          break;
+        case 'document_not_found':
+          console.error('Product manual not indexed yet');
+          break;
+        case 'authentication_error':
+          console.error('Invalid API key');
+          break;
+        case 'invalid_request':
+          console.error('Invalid request:', error.message);
+          break;
+        default:
+          console.error('API error:', error.message);
+      }
+    } else {
+      console.error('Unexpected error:', error);
+    }
+    throw error;
+  }
+}
+```
+
+### Rate Limit Retry
+
+```typescript
+async function chatWithRetry(
+  request: PublicChatRequest,
+  maxRetries = 3
+) {
+  let retries = 0;
+
+  while (retries < maxRetries) {
+    try {
+      return await ai.public.chat('my-collection', request);
+    } catch (error) {
+      if (error instanceof SmartLinksAIError && error.isRateLimitError()) {
+        if (retries === maxRetries - 1) throw error;
+
+        const resetTime = new Date(error.resetAt!).getTime();
+        const waitTime = resetTime - Date.now();
+
+        console.log(`Rate limited. Waiting ${waitTime}ms...`);
+        await new Promise(resolve => setTimeout(resolve, waitTime));
+
+        retries++;
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+```
+
+---
+
+## Rate Limiting
+
+### Rate Limit Overview
+
+Public endpoints are rate-limited per `userId`:
+
+| Endpoint Type | Default Limit | Window |
+|--------------|---------------|--------|
+| Public Chat | 20 requests | 1 hour |
+| Token Generation | 10 requests | 1 hour |
+| Admin Endpoints | Unlimited* | - |
+
+*Admin endpoints use API key authentication and are not rate-limited by default.
+
+### Rate Limit Headers
+
+All API responses include rate limit information:
+
+```
+X-RateLimit-Limit: 20
+X-RateLimit-Remaining: 15
+X-RateLimit-Reset: 1707300000000
+```
+
+### Checking Rate Limit
+
+```typescript
+// Check rate limit status before making requests
+const status = await ai.public.getRateLimit('my-collection', 'user-123');
+
+console.log('Used:', status.used);
+console.log('Remaining:', status.remaining);
+console.log('Resets at:', new Date(status.resetAt));
+
+if (status.remaining > 0) {
+  // Safe to make request
+  await ai.public.chat(/* ... */);
+} else {
+  // Show user when they can ask again
+  console.log('Rate limit reached. Try again at:', status.resetAt);
+}
+```
+
+### Resetting Rate Limits (Admin)
+
+```typescript
+// Reset rate limit for a specific user
+await ai.rateLimit.reset('my-collection', 'user-123');
+console.log('Rate limit reset for user-123');
+```
+
+---
+
+## Best Practices
+
+### 1. Choose the Right Model
+
+```typescript
+// For most new workflows (recommended default)
+await ai.chat.responses.create('my-collection', {
+  model: 'openai/gpt-5.4',
+  input: 'Create a concise onboarding checklist.'
+});
+
+// For lower-cost structured or JSON-oriented work
+await ai.chat.responses.create('my-collection', {
+  model: 'openai/gpt-5-mini',
+  input: 'Return a color palette as JSON.'
+});
+
+// For fast multimodal or cost-sensitive general use
+await ai.chat.completions.create('my-collection', {
+  model: 'google/gemini-2.5-flash',
+  messages: [...]
+});
+
+// When you need the actual available catalog for this collection
+const available = await ai.models.list('my-collection');
+console.log(available.data.map(model => model.id));
+```
+
+### 2. Use Streaming for Long Responses
+
+Improve perceived performance with streaming:
+
+```typescript
+// Non-streaming: User waits for full response
+const response = await ai.chat.completions.create('my-collection', {
+  messages: [...]
+});
+
+// Streaming: User sees progress immediately
+const stream = await ai.chat.completions.create('my-collection', {
+  stream: true,
+  messages: [...]
+});
+
+for await (const chunk of stream) {
+  updateUI(chunk.choices[0]?.delta?.content);
+}
+```
+
+### 3. Maintain Session Context
+
+Keep conversations coherent with session IDs:
+
+```typescript
+// Generate unique session ID per conversation
+const sessionId = `user-${userId}-product-${productId}`;
+
+// All questions in same conversation use same sessionId
+await ai.public.chat('my-collection', {
+  sessionId,
+  message: 'First question',
+  ...
+});
+
+await ai.public.chat('my-collection', {
+  sessionId,
+  message: 'Follow-up question',
+  ...
+});
+```
+
+### 4. Handle Rate Limits Gracefully
+
+Show clear feedback to users:
+
+```typescript
+try {
+  await ai.public.chat('my-collection', {...});
+} catch (error) {
+  if (error instanceof SmartLinksAIError && error.isRateLimitError()) {
+    const resetTime = new Date(error.resetAt!);
+    showNotification(
+      `You've reached your question limit. ` +
+      `Try again at ${resetTime.toLocaleTimeString()}`
+    );
+  }
+}
+```
+
+### 5. Optimize Voice UX
+
+Provide clear status updates:
+
+```typescript
+async function voiceAssistant() {
+  try {
+    showStatus('Listening...');
+    const question = await ai.voice.listen();
+
+    showStatus('Processing...');
+    const answer = await ai.public.chat('my-collection', {
+      message: question,
+      ...
+    });
+
+    showStatus('Speaking...');
+    await ai.voice.speak(answer.message);
+
+    showStatus('Ready');
+  } catch (error) {
+    showStatus('Error', error.message);
+  }
+}
+```
+
+### 6. Chunk Large Documents
+
+For better RAG performance, chunk documents appropriately:
+
+```typescript
+// For technical manuals
+await ai.rag.indexDocument('my-collection', {
+  productId: 'coffee-maker',
+  documentUrl: '...',
+  chunkSize: 500,  // Smaller chunks for precise answers
+  overlap: 50      // Overlap maintains context
+});
+
+// For narrative content
+await ai.rag.indexDocument('my-collection', {
+  productId: 'coffee-maker',
+  documentUrl: '...',
+  chunkSize: 1000, // Larger chunks for coherent responses
+  overlap: 100
+});
+```
+
+### 7. Use System Prompts Effectively
+
+Provide clear instructions:
+
+```typescript
+await ai.chat.completions.create('my-collection', {
+  messages: [
+    {
+      role: 'system',
+      content: `You are a coffee maker expert assistant.
+- Be concise and clear
+- Use numbered lists for steps
+- Always mention safety precautions
+- If unsure, ask for clarification`
+    },
+    { role: 'user', content: 'How do I descale?' }
+  ]
+});
+```
+
+### 8. Monitor Usage and Costs
+
+Track usage for cost management:
+
+```typescript
+const response = await ai.chat.completions.create('my-collection', {
+  messages: [...]
+});
+
+// Log token usage
+console.log('Usage:', response.usage);
+console.log('Prompt tokens:', response.usage.prompt_tokens);
+console.log('Completion tokens:', response.usage.completion_tokens);
+console.log('Total tokens:', response.usage.total_tokens);
+
+// Calculate estimated cost
+const model = await ai.models.get('my-collection', response.model);
+const cost = 
+  (response.usage.prompt_tokens * model.pricing.input / 1_000_000) +
+  (response.usage.completion_tokens * model.pricing.output / 1_000_000);
+console.log('Estimated cost: $', cost.toFixed(4));
+```
+
+---
+
+## Providing Content to the AI Assistant
+
+The portal's built-in AI assistant can discuss the content currently visible to the user. To make this work, your app must supply contextual content when the assistant requests it. There are three extraction methods, tried in priority order:
+
+| Priority | Method | When Used |
+|----------|--------|-----------|
+| 1 | **Direct prop callback** | Container/widget rendered in the parent React context |
+| 2 | **PostMessage protocol** | App rendered in an iframe |
+| 3 | **DOM text fallback** | Neither of the above responded |
+
+This section covers **methods 1 and 2** — the ones you implement in your app.
+
+### Method 1: Direct Prop (`onRequestAIContent`)
+
+When your app is rendered as a **container** (a direct component in the parent's React tree), the framework passes an `onRequestAIContent` prop to your exported component. You do **not** call this prop yourself — the framework calls it when the AI assistant needs context.
+
+Structure your component to make current state accessible when the callback fires:
+
+```tsx
+import { useEffect, useRef } from 'react';
+
+export function PublicContainer(props) {
+  const { onRequestAIContent, appId, ...rest } = props;
+
+  // Keep a ref to the latest content so the callback always returns fresh data
+  const currentContentRef = useRef(null);
+
+  useEffect(() => {
+    currentContentRef.current = buildCurrentContent();
+  }, [relevantState]);
+
+  return <div data-app-container={appId}>{/* your UI */}</div>;
+}
+```
+
+The framework registers the content provider internally via `useAIContentExtraction.registerContentProvider()`. Your component just needs to respond when the callback is invoked.
+
+### Method 2: PostMessage Protocol (Iframes)
+
+For iframe-embedded apps the framework sends a `postMessage` request and expects a response within **500 ms**. If your app doesn't reply in time the framework falls back to DOM text extraction.
+
+**Request sent by the framework to your iframe:**
+
+```typescript
+{
+  type: 'smartlinks:request-ai-content',
+  requestId: 'ai-content-1709834567890-abc123'  // unique per request
+}
+```
+
+**Response your app must send back:**
+
+```typescript
+{
+  type: 'smartlinks:ai-content-response',
+  requestId: 'ai-content-1709834567890-abc123',  // echo back the requestId
+  content: AIContentResponse
+}
+```
+
+**Minimal implementation:**
+
+```typescript
+window.addEventListener('message', async (event) => {
+  if (event.data?.type === 'smartlinks:request-ai-content') {
+    const content = await gatherAIContent();
+
+    window.parent.postMessage({
+      type: 'smartlinks:ai-content-response',
+      requestId: event.data.requestId,
+      content,
+    }, '*');
+  }
+});
+
+async function gatherAIContent(): Promise<AIContentResponse> {
+  return {
+    text: 'The user is viewing the warranty registration form...',
+    contentLabel: 'Warranty Registration',
+  };
+}
+```
+
+### The `AIContentResponse` Interface
+
+```typescript
+interface AIContentResponse {
+  /**
+   * Plain text or markdown for the AI to use as context.
+   * Injected into the system prompt. Max recommended: ~4000 characters.
+   */
+  text: string;
+
+  /**
+   * Optional structured metadata (key-value pairs).
+   * Not used directly in prompts but available for custom providers.
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * Pre-built RAG configuration. When provided, the assistant can use
+  * SL.ai.public.chat() to ground answers in indexed product documents.
+   */
+  ragHint?: {
+    /** The product ID whose indexed documents should be queried */
+    productId: string;
+    /** Optional session ID for multi-turn RAG conversations */
+    sessionId?: string;
+    /** Optional context hint to help scope the RAG query */
+    context?: string;
+  };
+
+  /**
+   * Human-readable label shown in context-update messages
+   * (e.g. "Product Manual", "FAQ").
+   */
+  contentLabel?: string;
+
+  /**
+   * How the assistant should use this content:
+   * - 'context' (default): inject text into the system prompt
+  * - 'rag': use ragHint to query indexed docs via SL.ai.public.chat()
+   * - 'hybrid': inject text as context AND ground answers via RAG
+   */
+  strategy?: 'context' | 'rag' | 'hybrid';
+}
+```
+
+### Response Strategies
+
+#### `context` (Default)
+
+Return readable text. The assistant injects it into the system prompt as background knowledge. Good for descriptions, summaries, structured data, and FAQs.
+
+```typescript
+return {
+  text: `
+## Wine Details
+- **Name**: 2023 Château Margaux
+- **Region**: Bordeaux, France
+- **Tasting Notes**: Dark fruit, cedar, tobacco
+- **Food Pairing**: Lamb, aged cheese
+  `,
+  contentLabel: 'Wine Information',
+  strategy: 'context',
+};
+```
+
+#### `rag`
+
+Tell the assistant to query pre-indexed documents via SmartLinks RAG. The `text` field is minimal — the real knowledge comes from the indexed docs. Good for product manuals, large document sets, and technical specs.
+
+```typescript
+return {
+  text: 'The user is viewing the espresso machine product page.',
+  contentLabel: 'Product Assistant',
+  strategy: 'rag',
+  ragHint: {
+    productId: 'espresso-machine-pro',
+    sessionId: `rag-session-${userId}`,
+    context: 'User is on the troubleshooting section',
+  },
+};
+```
+
+When the assistant receives a `rag` strategy it routes the question through `SL.ai.public.chat()`:
+
+```typescript
+const response = await SL.ai.public.chat(collectionId, {
+  productId: ragHint.productId,
+  userId: currentUserId,
+  message: userQuestion,
+  sessionId: ragHint.sessionId,
+});
+```
+
+#### `hybrid`
+
+Combines both — the `text` is injected as additional context **and** the user's questions are also grounded via RAG. Good for museum exhibits, guided experiences, or any scenario with rich metadata alongside large document sets.
+
+```typescript
+return {
+  text: `
+## Exhibit: The Starry Night
+- **Artist**: Vincent van Gogh
+- **Year**: 1889
+- **Current Location**: Gallery 3, East Wing
+- **Audio Guide**: Available in 12 languages
+  `,
+  contentLabel: 'Museum Exhibit',
+  strategy: 'hybrid',
+  ragHint: {
+    productId: 'starry-night-exhibit',
+    context: 'Art history and technique questions',
+  },
+};
+```
+
+### Content Extraction Examples
+
+#### Museum Guide App
+
+```typescript
+async function gatherAIContent(): Promise<AIContentResponse> {
+  const exhibit = getCurrentExhibit();
+
+  return {
+    text: `
+Exhibit: "${exhibit.title}" by ${exhibit.artist}
+Period: ${exhibit.period}
+Medium: ${exhibit.medium}
+Description: ${exhibit.curatorNotes}
+Related works in this gallery: ${exhibit.relatedWorks.join(', ')}
+    `.trim(),
+    contentLabel: `Exhibit: ${exhibit.title}`,
+    strategy: 'hybrid',
+    ragHint: {
+      productId: exhibit.smartlinksProductId,
+      context: `Art history, technique, and visitor information for ${exhibit.title}`,
+    },
+    metadata: {
+      exhibitId: exhibit.id,
+      gallery: exhibit.gallery,
+      audioGuideAvailable: exhibit.hasAudioGuide,
+    },
+  };
+}
+```
+
+#### Wine Product App
+
+```typescript
+async function gatherAIContent(): Promise<AIContentResponse> {
+  const wine = getCurrentWine();
+  const reviews = await fetchRecentReviews(wine.id, 5);
+
+  return {
+    text: `
+Wine: ${wine.name} (${wine.vintage})
+Winery: ${wine.winery}
+Region: ${wine.region}, ${wine.country}
+Grape: ${wine.grape}
+ABV: ${wine.abv}%
+Price: ${wine.price}
+Tasting Notes: ${wine.tastingNotes}
+
+Recent Reviews:
+${reviews.map(r => `- "${r.text}" (${r.rating}/5)`).join('\n')}
+    `.trim(),
+    contentLabel: 'Wine Details',
+    strategy: 'context',
+  };
+}
+```
+
+#### Equipment Manual App (RAG-only)
+
+```typescript
+async function gatherAIContent(): Promise<AIContentResponse> {
+  const equipment = getCurrentEquipment();
+
+  return {
+    text: `User is viewing: ${equipment.name} (Model: ${equipment.modelNumber})`,
+    contentLabel: `${equipment.name} Assistant`,
+    strategy: 'rag',
+    ragHint: {
+      productId: equipment.smartlinksProductId,
+      sessionId: `manual-${equipment.id}-${Date.now()}`,
+      context: 'Technical manual, troubleshooting, and maintenance',
+    },
+  };
+}
+```
+
+### Timing & Lifecycle
+
+- **On navigation**: When the user navigates to a new product/proof/app, the assistant automatically requests fresh content and injects a context-update system message.
+- **On first message**: If no content has been gathered yet, the assistant requests it before the first AI call.
+- **On manual refresh**: The assistant can re-request content at any time (e.g. if the user's view within the app has changed).
+
+Content is requested **lazily** — your handler is only called when the AI assistant is active and needs context. If the user never opens the assistant, your handler is never called.
+
+### Method 3: DOM Fallback (Automatic)
+
+If your app doesn't implement either of the above, the framework extracts `innerText` from the DOM element with `data-app-container="{appId}"`, truncated to ~4000 characters. This is a **last resort** — content quality is much lower than a structured response. Implementing Method 1 or 2 is strongly recommended.
+
+---
+
+## Related Documentation
+
+- [API Summary](./API_SUMMARY.md) - Complete API reference
+- [Widgets](./widgets.md) - Embedding SmartLinks components
+- [Realtime](./realtime.md) - Realtime data updates
+- [iframe Responder](./iframe-responder.md) - iframe integration
+
+---
+
+## Support
+
+For questions or issues:
+
+- **Documentation:** https://smartlinks.app/docs
+- **GitHub:** https://github.com/Prove-Anything/smartlinks
+- **Email:** support@smartlinks.app