PolyLLM v0.1.0 — multi-provider BYOK AI workspace (OpenAI, Anthropic, Gemini, xAI) · 5734499 · polyllm

PolyLLM v0.1.0 — multi-provider BYOK AI workspace (OpenAI, Anthropic, Gemini, xAI)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Simon-Pierre Boucher committed 2 mo ago (Sep 8, 2026) Browse files

44 changed files +20,001 −0

added .env.example +35 −0

++# --- Runtime -------------------------------------------------------------
++NODE_ENV=production
++PORT=3000
++# Public origin used in emails, auth callbacks and canonical links. No trailing slash.
++PUBLIC_APP_URL=https://www.polyllm.io
++
++# --- Database ------------------------------------------------------------
++DATABASE_URL=postgres://localhost:5432/polyllm
++DB_POOL_MAX=10
++
++# --- Auth ----------------------------------------------------------------
++# 32+ random bytes, hex or base64. `openssl rand -hex 32`
++AUTH_SECRET=
++
++# --- Email (Resend) ------------------------------------------------------
++RESEND_API_KEY=
++RESEND_FROM_EMAIL="PolyLLM <mail@spboucher.ai>"
++# Set to 1 to log emails instead of sending (development).
++EMAIL_DRY_RUN=0
++
++# --- Encryption of user provider keys (AES-256-GCM, server-side only) ----
++# 32+ random bytes. Rotating this secret invalidates every stored key.
++API_KEY_ENCRYPTION_SECRET=
++
++# --- Owner / development provider keys (TEST ONLY — never used for users) -
++OPENAI_API_KEY=
++ANTHROPIC_API_KEY=
++GOOGLE_GEMINI_API_KEY=
++XAI_API_KEY=
++
++# --- Admin ---------------------------------------------------------------
++# Comma-separated emails with access to /admin.
++ADMIN_EMAILS=
++# Model catalog refresh interval (minutes). 0 disables the scheduler.
++MODEL_SYNC_INTERVAL_MINUTES=360

added .gitignore +33 −0

++# dependencies
++node_modules/
++.pnpm-store/
++
++# next
++.next/
++out/
++next-env.d.ts
++*.tsbuildinfo
++
++# env & secrets — never commit
++.env
++.env.*
++!.env.example
++deploy/*.mld.json
++
++# research scratch (installed SDKs, probe outputs)
++research/*/node_modules/
++research/*/out/
++research/*/*.log
++
++# tests
++coverage/
++playwright-report/
++test-results/
++qa/out/
++
++# misc
++.DS_Store
++logs/
++tmp/
++.turbo/
++.claude/

added CLAUDE.md +38 −0

++# PolyLLM — repository guide
++
++PolyLLM (www.polyllm.io) is a BYOK multi-provider AI workspace: OpenAI, Anthropic, Gemini, xAI behind one normalized
++adapter layer, real streaming, capability-driven configuration, Arena comparisons, usage/cost tracking.
++The original product brief lives in `docs/SPEC-original.md`; the UI conventions in `docs/UI-BRIEF.md`.
++
++## Non-negotiables
++- **Research before provider changes.** Read `docs/provider-research/<provider>.md`, re-fetch the official docs, probe the
++  real API (`pnpm providers:matrix`), then update `src/lib/ai/providers/<provider>/catalog*.ts`. Never assume model ids,
++  parameters, event names or limits from memory. Bump `Last documentation audit`.
++- **Provider quirks stay inside `src/lib/ai/providers/*`.** UI and services only see `PolyModel`, `UnifiedChatRequest`,
++  `UnifiedStreamEvent`, `PolyProviderError`.
++- **Capabilities drive the UI.** Never branch on a model id in components; use `model.capabilities` / `model.parameters`.
++  Never send a parameter the model does not accept (`filterSettings()` + adapter translation).
++- **Keys.** User keys are encrypted (`src/lib/crypto/keys.ts`) and decrypted only in `getDecryptedKey()` right before a
++  request. Never log, return or serialize them; `PublicConnection` exposes `keyHint` only. Owner keys in `.env` are for the
++  registry sync, admin diagnostics and tests — never for user requests.
++- **No fake integrations.** A capability is ✅ only after a real request passed (`docs/provider-test-matrix.md`).
++- Secrets only in `.env` (gitignored) and the mld manifest on M1M32; `.env.example` documents the variables.
++
++## Commands
++`pnpm dev` · `pnpm typecheck` · `pnpm lint` · `pnpm test` (vitest) · `pnpm test:e2e` (Playwright; dev server with
++`EMAIL_DRY_RUN=1 EMAIL_DRY_RUN_PRINT=1`) · `pnpm db:generate` / `pnpm db:migrate` · `pnpm models:sync [provider]` ·
++`pnpm providers:matrix [provider]`.
++
++## Deploy
++`mld` from the laptop (see `docs/deployment-cluster.md`): `mld stage . polyllm && mld deploy polyllm --node M3U96a`.
++Manifest with secrets: `M1M32:~/dispatch/apps/polyllm.json` (local gitignored copy `deploy/polyllm.mld.json`).
++
++## Gotchas
++- React Compiler lint: no `Date.now()`/impure calls in render, no setState synchronously in effects without an explicit
++  eslint-disable, memoize derived lists.
++- `import "server-only"` modules are used by CLI scripts through `scripts/hooks.mjs` (tsx `--import`) and by vitest via an alias.
++- Anthropic: adaptive thinking may legitimately produce zero thinking tokens on easy prompts; Haiku 4.5 needs `budget_tokens`.
++- Gemini: free-tier keys have tiny per-model daily quotas (429 `limit: 20`) and some models are paid-tier only (429 `limit: 0`);
++  thought signatures must be replayed on function-call parts.
++- xAI: bad keys return HTTP **400** (`Incorrect API key`), `frequency/presence_penalty` always 400, web search only via `/v1/responses`.
++- OpenAI: Responses API has no `seed`/`stop`; sampling params only when `reasoning.effort === "none"` on reasoning models.

added README.md +46 −0

++# PolyLLM
++
++**One interface. Every model. Bring your own keys.** — https://www.polyllm.io
++
++PolyLLM is a universal control center for AI models: connect your own OpenAI, Anthropic, Google Gemini and xAI API keys,
++discover the models your keys can reach, configure each one with only the parameters it supports, chat with real
++token-by-token streaming, compare up to four models side by side in the Arena, and track tokens, latency and estimated
++cost. Keys are encrypted at rest (AES-256-GCM, HKDF-derived data key, AAD-bound to the user) and only decrypted on the
++server immediately before a provider request.
++
++## Stack
++Next.js 16 (App Router, Route Handlers with SSE streaming) · React 19 · TypeScript · Tailwind v4 · PostgreSQL 17 + Drizzle ·
++Better Auth 1.7 (Argon2id, email verification, sessions, reset, change email, delete account) · Resend · Zod ·
++official provider SDKs (`openai`, `@anthropic-ai/sdk`, `@google/genai`; xAI through the OpenAI SDK at `api.x.ai`).
++
++## Layout
++```
++src/app                 routes: (marketing) landing/legal · (auth) login/signup/verify/reset · app/* workspace · admin/* · share/[id] · api/*
++src/lib/ai/core         provider-neutral contract: PolyModel, UnifiedChatRequest, UnifiedStreamEvent, errors, retry, pricing, normalization
++src/lib/ai/providers    adapters (openai, anthropic, gemini, xai) + catalogs — provider quirks live ONLY here
++src/lib/ai/registry     model registry: live listing → catalog merge → Postgres; scheduled + manual sync
++src/lib/chat            turn orchestration (edit/regenerate/continue/branch), built-in tools loop, SSE
++src/lib/providers       encrypted key storage & validation
++src/components          ui kit · app shell · chat · arena · settings · marketing
++docs/                   provider-research (per provider, dated), provider-test-matrix (generated), deployment-cluster, final-audit, UI brief
++scripts/                sync-models, provider-matrix (real-API tests)
++e2e/, tests/            Playwright workflows, vitest unit tests
++```
++
++## Development
++```bash
++cp .env.example .env            # fill AUTH_SECRET, API_KEY_ENCRYPTION_SECRET, RESEND_API_KEY, owner provider keys (optional)
++createdb polyllm && pnpm install && pnpm db:migrate
++pnpm models:sync                # populate the registry with the owner keys
++pnpm dev                        # http://localhost:3000
++pnpm typecheck && pnpm lint && pnpm test
++pnpm providers:matrix           # real-API capability matrix → docs/provider-test-matrix.md
++EMAIL_DRY_RUN=1 EMAIL_DRY_RUN_PRINT=1 pnpm dev && pnpm test:e2e   # full browser workflow (links read from the dev log)
++```
++
++## Deployment
++Runs on the private MacLustr cluster behind ngrok — see `docs/deployment-cluster.md`.
++
++## Security notes
++No provider key ever reaches the browser, logs or analytics (structured logger redacts key-shaped strings and sensitive
++field names). CSP, HSTS, HttpOnly/SameSite cookies, rate limits on auth and provider endpoints, per-user audit log.

added deploy/backup/install.sh +28 −0

++#!/bin/bash
++# Installs the daily PostgreSQL backup for PolyLLM on the deployment node (run ON the node).
++set -euo pipefail
++mkdir -p ~/backups/polyllm ~/Library/LaunchAgents
++cat > ~/backups/polyllm/backup.sh <<'SH'
++#!/bin/bash
++set -euo pipefail
++export PATH="/opt/homebrew/opt/postgresql@17/bin:/opt/homebrew/bin:$PATH"
++out=~/backups/polyllm/polyllm-$(date +%Y%m%d).sql.gz
++pg_dump polyllm | gzip -9 > "$out.tmp" && mv "$out.tmp" "$out"
++find ~/backups/polyllm -name 'polyllm-*.sql.gz' -mtime +14 -delete
++echo "$(date -Iseconds) ok $(du -h "$out" | cut -f1)" >> ~/backups/polyllm/backup.log
++SH
++chmod +x ~/backups/polyllm/backup.sh
++cat > ~/Library/LaunchAgents/dev.polyllm.backup.plist <<PLIST
++<?xml version="1.0" encoding="UTF-8"?>
++<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
++<plist version="1.0"><dict>
++  <key>Label</key><string>dev.polyllm.backup</string>
++  <key>ProgramArguments</key><array><string>/bin/bash</string><string>$HOME/backups/polyllm/backup.sh</string></array>
++  <key>StartCalendarInterval</key><dict><key>Hour</key><integer>3</integer><key>Minute</key><integer>45</integer></dict>
++  <key>StandardOutPath</key><string>$HOME/backups/polyllm/launchd.log</string>
++  <key>StandardErrorPath</key><string>$HOME/backups/polyllm/launchd.log</string>
++</dict></plist>
++PLIST
++launchctl bootout gui/$(id -u)/dev.polyllm.backup 2>/dev/null || true
++launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.polyllm.backup.plist
++~/backups/polyllm/backup.sh && echo "backup installed + first dump done"

added docs/SPEC-original.md +3 −0

++# PolyLLM — original product brief (CLAUDE.md provided by the owner, 2026-09-08)
++
++The full brief was supplied in the build session; its normative rules are reproduced in the repository `CLAUDE.md` and `docs/UI-BRIEF.md`. Key sections: research-before-implementation, live model catalog, adapter architecture, mandatory email verification, encrypted BYOK keys, unified streaming events, capability-driven configuration, Arena, usage/cost tracking, security/privacy/logging rules, cluster deployment through ngrok at https://www.polyllm.io, real-API test matrix, final audit.

added docs/UI-BRIEF.md +64 −0

++# PolyLLM — UI brief for contributors (humans and agents)
++
++PolyLLM (www.polyllm.io) is a **universal control center for AI models**: users bring their own API keys
++(OpenAI, Anthropic, Gemini, xAI), discover current models, configure them precisely, chat with real streaming,
++compare models in the Arena and track usage/costs. Tagline: **"Your models. Your keys. One workspace."**
++
++## Stack & conventions
++- Next.js 16 App Router, React 19, TypeScript strict, Tailwind v4 (tokens in `src/app/globals.css`), shadcn-style
++  primitives in `src/components/ui/*` (button, input/textarea/label/field, badge, dialog, dropdown-menu, popover,
++  select, slider, switch, tabs, tooltip, toast (`toast.success/error/info`), misc: Card/CardHeader/CardBody, Stat,
++  PageHeader, EmptyState, Skeleton, CopyButton, Kbd, Spinner, Divider). Icons: `lucide-react`. Motion: `motion/react` (sparingly).
++- Client data: `useApi<T>(url)` (SWR) and `api<T>(url, { method, json })` from `src/lib/client/api.ts`;
++  `streamEvents(url, body, onEvent, signal)` for SSE. Types: `src/lib/client/types.ts`. Provider metadata:
++  `src/lib/client/providers.ts` (`PROVIDERS`, `PROVIDER_ORDER`, `providerName`). Brand: `src/components/brand/logo.tsx`
++  (`Logo`, `LogoMark`), `src/components/brand/provider-icon.tsx` (`ProviderIcon`).
++- App state: `useApp()` from `src/components/app/store.tsx` → `{ user, preferences, updatePreferences, models, modelsByKey,
++  favorites, recents, connectedProviders, connections, folders, toggleFavorite, refreshModels, refreshConnections,
++  selectedModelKey, setSelectedModelKey, setPaletteOpen }`. Everything under `/app/*` is wrapped by the shell
++  (sidebar + command palette) in `src/app/app/layout.tsx`; pages render inside `<div className="relative flex min-w-0 flex-1 flex-col">`.
++  A page should typically be `<main className="min-h-0 flex-1 overflow-y-auto scrollbar-thin"><div className="mx-auto w-full max-w-5xl px-4 py-6 sm:px-6 lg:px-8">…</div></main>`.
++- Auth client: `authClient`, `signIn`, `signUp`, `signOut`, `useSession` from `src/lib/auth-client.ts` (Better Auth 1.7).
++  Server: `requireUser()` / `getSession()` in `src/lib/session.ts`.
++- Formatting helpers: `formatUsd`, `formatTokens`, `formatMs`, `formatRelative`, `formatNumber`, `cn` in `src/lib/utils.ts`.
++- Never render key material. Connections only expose `keyHint` like `sk-••••••••9A2K`.
++- React Compiler lint rules apply: no setState synchronously in effects without the eslint-disable, no components defined
++  inside render, derive state with useMemo. Run `pnpm lint` and `pnpm typecheck`.
++
++## Design language (must feel premium, unique, not a template)
++- Minimal, dense-when-useful, excellent typography (Geist Sans/Mono via `font-sans`/`font-mono`), subtle borders
++  (`border-border`), surfaces `bg-bg / bg-bg-subtle / bg-bg-muted / bg-bg-elevated`, text `text-fg / text-fg-muted / text-fg-subtle`,
++  accent `text-accent / bg-accent / bg-accent-soft`, semantic `success/warning/danger/info` (+ `-soft`). Radii `rounded-md/lg/xl`.
++  Provider colors: `text-openai`, `text-anthropic`, `text-gemini`, `text-xai` or `style={{color: PROVIDERS[p].colorVar}}`.
++- Dark and light must both look great. No cheap gradients, no childish AI imagery, no huge empty whitespace, no boxed-card overload.
++  A single restrained gradient (`.text-gradient`) is allowed for hero words. Use `.dot-grid` / `.glass` utilities sparingly.
++- Mobile first: no horizontal overflow, 16px inputs on mobile (`text-[15px] sm:text-sm` is already in Input), safe-area aware.
++- Keyboard-first: ⌘K palette, ⌘N new chat, ⌘Enter send, Esc stop, ⌘/ model selector, ⌘B sidebar.
++- Accessibility: semantic HTML, labels, visible focus, aria on icon buttons, reduced motion respected.
++
++## API routes (all JSON unless noted; all under a verified session)
++- `GET /api/models` → `{ models: PolyModel[], favorites: string[], recents: string[], connectedProviders }`;
++  `POST /api/models {action:"toggle-favorite", modelKey}`; `POST /api/models/sync {provider?}` → `{results: SyncResult[]}`.
++- `GET /api/providers` → `{connections: PublicConnection[]}`; `PUT /api/providers {provider, apiKey}` → `{ok, error?, modelsAvailable?, connections}`;
++  `POST /api/providers {action:"validate", provider}`; `DELETE /api/providers?provider=`.
++- `GET /api/conversations?q&provider&model&folder&archived=1&pinned=1&since&until&limit&cursor`; `POST /api/conversations`;
++  `GET|PATCH|DELETE /api/conversations/:id`; `POST /api/conversations/:id/actions {action: duplicate|branch|export|share|unshare|share-status|delete-message}`.
++- `POST /api/chat` (SSE) body `ChatRequestInput` → events `ChatStreamEvent` (see `src/lib/client/types.ts`).
++- `GET /api/folders`, `POST {name,color}`, `PATCH {id,…}`, `DELETE ?id=`.
++- `POST /api/attachments` (multipart `file`) → `{attachment}`; `GET /api/attachments?id=` streams the file.
++- `GET /api/usage?range=today|7d|30d|all` → `{ totals, series[{bucket,requests,inputTokens,outputTokens,costUsd}], byProvider[], byModel[], recent[] }`.
++- `GET /api/presets` → `{modelPresets, promptPresets}`; `POST /api/presets?kind=model|prompt`; `PATCH ?kind&id`; `DELETE ?kind&id`.
++- `GET /api/preferences` / `PATCH /api/preferences` (theme, defaultModelKey, defaultSystemPrompt, enterToSend, streaming, codeWrap, showReasoning, showCosts, autoTitle, onboardingCompleted).
++- `GET /api/arena` → `{sessions}`; `POST /api/arena {prompt, systemPrompt?, modelKeys[1..4], settings?, attachmentIds?}` → `{session}`;
++  `POST /api/arena/stream {sessionId, modelKey}` (SSE: meta → text-delta/reasoning-delta/citation → done|error); `PATCH /api/arena {responseId, ratings}`.
++- `GET /api/account` → `{audit}`; `GET /api/account?export=1` downloads the full account export.
++- `GET /api/search?q=`.
++- Admin: `GET /api/admin/providers`, `POST /api/admin/providers {action:"sync", provider?}` (owner only, `user.isAdmin`).
++- Better Auth: `/api/auth/*` (client SDK). Email verification is mandatory: unverified users are redirected to `/verify-email`.
++
++## Model capability sheet (drives every configuration UI)
++`PolyModel.capabilities` {text, vision, audioInput, audioOutput, imageGeneration, video, reasoning, tools, structuredOutput,
++streaming, files, webSearch}; `parameters` {temperature, topP, topK, maxTokens, reasoningEffort, reasoningEffortLevels[],
++thinkingBudget, thinkingBudgetRange, stop, seed, frequencyPenalty, presencePenalty, verbosity, temperatureRange};
++`limits` {contextTokens, maxOutputTokens}; `pricing` {inputPerMillion, cachedInputPerMillion, outputPerMillion};
++`status` active|preview|deprecated|unknown; `metadata.shutdownDate`, `metadata.aliases`, etc. **Never show a control the model does not support.**

added docs/deployment-cluster.md +91 −0

++# PolyLLM — cluster deployment (MacLustr)
++
++Production runs on the owner's private Apple Silicon cluster and is exposed through ngrok at
++**https://www.polyllm.io**. Everything is orchestrated by `mld` (maclustr-dispatch) from the gateway node M1M32.
++
++```
++Internet → www.polyllm.io (CNAME → ngrok) → ngrok agent (PM2 polyllm-ngrok) → Next.js `next start` 0.0.0.0:8240 → PostgreSQL 17 (localhost)
++```
++
++| Item | Value |
++| --- | --- |
++| Node | M3U96a (pinned: local PostgreSQL 17, same host as fetcha / spinza / rareindex) |
++| Directory | `~/apps/polyllm` (rsync'd by mld from the laptop staging area) |
++| Processes | PM2 `polyllm-web` (Next 16, port 8240, binds 0.0.0.0), PM2 `polyllm-ngrok` (`--domain www.polyllm.io`) |
++| Database | `postgres://localhost:5432/polyllm` (created by the post-sync hook if missing) |
++| Manifest | `M1M32:~/dispatch/apps/polyllm.json` — **the only place secrets live** (gitignored copy `deploy/polyllm.mld.json`) |
++| Health | `GET /api/health` (liveness), `GET /api/health/ready` (DB ping; used by mld) |
++| Registry | `mld status` / `mld status --live` |
++
++## Environment variables (production)
++
++See `.env.example`. Required: `NODE_ENV=production`, `PORT=8240`, `PUBLIC_APP_URL=https://www.polyllm.io`,
++`DATABASE_URL`, `AUTH_SECRET` (32+ bytes), `API_KEY_ENCRYPTION_SECRET` (32+ bytes — **rotating it invalidates every
++stored user key**), `RESEND_API_KEY`, `RESEND_FROM_EMAIL`, `ADMIN_EMAILS`. Optional owner keys
++(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_GEMINI_API_KEY`, `XAI_API_KEY`) are used **only** for the scheduled
++model-registry refresh and the admin diagnostics; user requests always use the user's own encrypted key.
++
++## Build & deploy
++
++```bash
++# laptop
++cd ~/Desktop/Projets/apps-web/polyllm
++pnpm typecheck && pnpm lint && pnpm test          # gates
++scp deploy/polyllm.mld.json M1M32:~/dispatch/apps/polyllm.json   # first time / when secrets change
++~/Desktop/cluster-skill/mld stage . polyllm       # laptop → M1M32 staging
++~/Desktop/cluster-skill/mld deploy polyllm --node M3U96a
++```
++
++`mld deploy` runs the manifest hooks on the node: `pnpm install --frozen-lockfile` → `createdb polyllm` (if needed) +
++`pnpm db:migrate` (Drizzle migrations in `drizzle/`, version-controlled) → `pnpm build` → PM2 start/reload of
++`polyllm-web` and `polyllm-ngrok` → local health check (`/api/health/ready`) → public health check (`https://www.polyllm.io/api/health/ready`) → registry update.
++
++Restart / logs on the node:
++
++```bash
++ssh M3U96a 'pm2 restart polyllm-web; pm2 logs polyllm-web --lines 100 --nostream'
++ssh M3U96a 'pm2 logs polyllm-ngrok --lines 30 --nostream'
++```
++
++Migrations are applied by the hook before the new build starts; they must stay backward compatible with the running
++version (add columns, never drop in the same release).
++
++## ngrok / domain / TLS
++
++- DNS (GoDaddy): `www.polyllm.io` CNAME → the ngrok-cname target shown in the ngrok dashboard for the reserved domain.
++  The apex `polyllm.io` should redirect to `https://www.polyllm.io` (GoDaddy forwarding).
++- TLS terminates at ngrok (automatic certificate for the reserved domain). The app sees `X-Forwarded-For` /
++  `X-Forwarded-Proto`; Better Auth is configured with `baseURL = PUBLIC_APP_URL` and secure cookies in production.
++- The PM2 process `polyllm-ngrok` runs `ngrok http 8240 --domain www.polyllm.io`. Only port 8240 is exposed; no admin port.
++- Streaming: SSE responses send a `: ping` heartbeat every 15 s so ngrok never closes idle long reasoning turns.
++
++## Process management
++
++PM2 with `pm2 startup` (LaunchAgent) on the node → processes survive terminal closure and reboots; `autorestart: true`,
++`max_memory_restart: 2G`. The model-registry scheduler runs inside the web process (`src/instrumentation.ts`, every
++`MODEL_SYNC_INTERVAL_MINUTES`, default 360) plus a startup sync.
++
++## Backups
++
++- Daily `pg_dump` at 03:45 via launchd `dev.polyllm.backup` on M3U96a → `~/backups/polyllm/polyllm-YYYYMMDD.sql.gz`,
++  14-day retention (`find -mtime +14 -delete`). Install with `deploy/backup/install.sh` (see that file).
++- Restore: `gunzip -c ~/backups/polyllm/polyllm-YYYYMMDD.sql.gz | psql polyllm_restore` after `createdb polyllm_restore`;
++  swap with `ALTER DATABASE … RENAME` during a maintenance window. Test restore on the 1st of each month into a scratch DB
++  and run `select count(*) from users;` to validate.
++- Encrypted user keys are only decryptable with the same `API_KEY_ENCRYPTION_SECRET`: back up the manifest too
++  (`M1M32:~/dispatch/apps/polyllm.json` is included in the spbgit gateway backup).
++
++## Rollback
++
++```bash
++ssh M3U96a 'cd ~/apps/polyllm && git log --oneline -5'          # deployed commit
++# redeploy the previous tag from the laptop:
++git checkout <previous-tag> && ~/Desktop/cluster-skill/mld stage . polyllm && ~/Desktop/cluster-skill/mld deploy polyllm --node M3U96a
++```
++
++If a migration must be reverted, restore last night's dump (see Backups) — Drizzle migrations are forward-only.
++
++## Moving to another node
++
++`mld move polyllm --to <node>` handles rsync, PM2 and ngrok, but the database is local: dump on M3U96a, restore on the
++target (PostgreSQL 17 via Homebrew), then update `DATABASE_URL` in the manifest before the move.

added docs/provider-research.md +30 −0

++# Provider research — index
++
++**Last documentation audit: 2026-09-08**
++
++PolyLLM never relies on remembered API shapes. Before each adapter was written, the CURRENT official
++documentation was fetched and every claim that matters for the adapter was **probed against the real API**
++with the owner's keys. The per-provider reports below contain the base URLs, auth, SDKs and versions, streaming
++protocols and event names, tool/structured-output formats, reasoning controls, modalities, limits, parameter
++support matrices with exact rejection strings, error schemas, rate limits, pricing, lifecycle, and the probe
++scripts that produced the evidence.
++
++| Provider | Report | Model data | SDK used | Primary API | Probe scripts |
++| --- | --- | --- | --- | --- | --- |
++| OpenAI | [openai.md](provider-research/openai.md) | [openai.models.json](provider-research/openai.models.json) (84) | `openai` 7.10 | Responses API (`store:false`, encrypted reasoning replay) | `research/openai/` |
++| Anthropic | [anthropic.md](provider-research/anthropic.md) | Models API (live capabilities) + `src/lib/ai/providers/anthropic/catalog.ts` (pricing) | `@anthropic-ai/sdk` 0.124 | Messages API (adaptive thinking, `output_config`) | `scripts/provider-matrix.ts` |
++| Google Gemini | [gemini.md](provider-research/gemini.md) | [gemini.models.json](provider-research/gemini.models.json) (19) | `@google/genai` 2.21 | `generateContentStream` (thinkingLevel/budget per family, thought signatures) | `research/gemini/` |
++| xAI | [xai.md](provider-research/xai.md) | [xai.models.json](provider-research/xai.models.json) (7) | `openai` 7.10 with `baseURL https://api.x.ai/v1` | Chat Completions (+ `/v1/responses` for server-side web search) | `research/xai/` |
++
++The verified behaviour is encoded in code, not prose:
++
++- `src/lib/ai/providers/<provider>/catalog*.ts` — capability sheets, parameter support, pricing, lifecycle.
++- `src/lib/ai/providers/<provider>/index.ts` — request translation that only sends what the model accepts.
++- `docs/provider-test-matrix.md` — generated by `pnpm providers:matrix` from live requests.
++
++## Re-audit procedure (before every release)
++
++1. `pnpm models:sync` — refresh the registry from the live listing endpoints; check `model_sync_runs` for removed/added ids.
++2. Re-fetch the docs pages linked at the bottom of each report; update the catalog data when parameters, limits or prices moved.
++3. `pnpm providers:matrix` — must be all ✅; investigate any ❌ before shipping.
++4. Bump `Last documentation audit` in this file and in each report.

added docs/provider-research/anthropic.md +41 −0

++# Anthropic — provider research
++
++**Last documentation audit: 2026-09-08** — sources: Claude Platform docs (Messages API, Models API, extended thinking,
++structured outputs, tool use, prompt caching, pricing, errors), the bundled `claude-api` reference (models table cached
++2026-06-24), SDK type definitions of `@anthropic-ai/sdk` 0.124.0, and live probes with the owner key (`scripts/provider-matrix.ts`
++and `GET /v1/models`).
++
++## Endpoint, auth, SDK
++- Base URL `https://api.anthropic.com`; headers `x-api-key`, `anthropic-version: 2023-06-01`. Invalid key → **401** `authentication_error`.
++- SDK `@anthropic-ai/sdk` 0.124.0 (`client.messages.create({stream:true})` returns an async iterable of raw events; `client.models.list()` auto-paginates; `client.messages.countTokens`).
++- Timeouts: SDK default 10 min; PolyLLM uses 10 min for chats, 20 s for validation/listing; SDK retries 1 (PolyLLM never retries mid-stream).
++
++## Models API (live capability metadata — verified)
++`GET /v1/models` returns `id, display_name, created_at, max_input_tokens, max_tokens, capabilities` with
++`thinking.types.{adaptive,enabled}`, `effort.{low,medium,high,xhigh,max}`, `image_input`, `pdf_input`, `structured_outputs`,
++`code_execution`, `citations`, `batch`, `context_management`. 11 models for this key: `claude-fable-5-1`, `claude-opus-5`,
++`claude-sonnet-5`, `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-opus-4-6`,
++`claude-opus-4-5-20251101`, `claude-haiku-4-5-20251001`, `claude-sonnet-4-5-20250929`. Aliases (`claude-haiku-4-5`) resolve to dated snapshots.
++All current models: 1M context (Haiku 4.5: 200k), 128k max output (Haiku 4.5: 64k).
++
++## Verified rules encoded in the adapter
++- **Adaptive-only generations** (`thinking.types.enabled.supported === false`: Fable 5/5.1, Opus 5/4.8/4.7, Sonnet 5) reject
++  `temperature`/`top_p`/`top_k` (400) and `budget_tokens`; the adapter exposes none of them. Effort via `output_config.effort`.
++  Sending `thinking:{type:"adaptive"}` to Haiku 4.5 → 400 `adaptive thinking is not supported on this model` (probed) → Haiku uses `{type:"enabled", budget_tokens}` (≥1024, < max_tokens).
++- Fable 5.x: thinking always on, `{type:"disabled"}` → 400; forced `tool_choice` `any`/`tool` → 400 on Fable 5.1 (adapter downgrades to `auto`).
++- Adaptive thinking decides when to think: trivial prompts produce **no thinking block and 0 thinking tokens** even at effort `high` (probed on Sonnet 5); a harder prompt produced 3.5k thinking tokens with `display:"summarized"`.
++- Streaming events: `message_start` (input usage incl. cache), `content_block_start/delta/stop` with `text_delta`, `thinking_delta`,
++  `signature_delta`, `input_json_delta`, `citations_delta`; `message_delta` carries `stop_reason` (`end_turn|max_tokens|stop_sequence|tool_use|pause_turn|refusal|model_context_window_exceeded`),
++  `usage.output_tokens` and `usage.output_tokens_details.thinking_tokens`; `stop_details` on refusal.
++- Tools: `tools[{name, description, input_schema, strict}]`; tool results as `tool_result` blocks in a **user** turn; thinking blocks replayed with signature only on the same model.
++- Server tools: `web_search_20260209` (Opus 5/4.8/4.7/4.6, Sonnet 5/4.6; not combinable with `code_execution_20260521`), `web_search_20250305` for older models.
++- Structured output: `output_config.format = { type: "json_schema", schema }` (Opus 4.7+, Sonnet 5, Fable — `structured_outputs.supported`).
++- Files: PDF as `document` (base64), text files as `document` with `text/plain` source; images base64 `image` blocks.
++- Errors: `{type:"error", error:{type, message}}`: `authentication_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `overloaded_error` (529, retryable), `billing_error`, `request_too_large`, `invalid_request_error`.
++- Pricing (USD/M, first-party): Fable 5.1 10/50 (cache read 0.25), Opus 5 5/25, Sonnet 5 2/10, Sonnet 4.6 3/15, Haiku 4.5 1/5 — see `catalog.ts`; cache reads 10 % of input.
++- Prompt caching: `cache_control` (not used by PolyLLM v0.1; usage reports `cache_read_input_tokens`, folded into cached tokens).
++
++## Probe results (2026-09-08, `pnpm providers:matrix`)
++Auth ✅ · Model list ✅ (11) · Text ✅ · Streaming ✅ · System ✅ · Vision ✅ (64×64 PNG → "Red") · Tools ✅ (streamed `input_json_delta`, args rebuilt) ·
++Structured output ✅ · Reasoning ✅ (Sonnet 5, effort high, 3 558 thinking tokens, summary streamed) · Token usage ✅ · Invalid key ✅ (401) ·
++Error normalization ✅ (unknown model → `not_found_error` → MODEL_NOT_FOUND) · Long response ✅ (407 words).

added docs/provider-research/gemini.md +302 −0

++# Google Gemini (Gemini Developer API) — provider research for PolyLLM
++
++Last documentation audit: **2026-09-08**. SDK probed: `@google/genai` **2.21.0** (Node 25.9, tsx 4.23). Probe scripts and raw outputs: `research/gemini/*.ts`, `research/gemini/out/*.json` (keys redacted). Key used: free-tier `AQ.`-style ("auth") key.
++
++> Headline for the adapter: `generateContent` / `streamGenerateContent` remain **fully supported** but Google now labels them legacy and documents everything on the new **Interactions API** (`ai.interactions.create`, GA June 2026, "recommended for all new projects", all new features land there first). This audit targets `generateContent` (what the SDK's `ai.models.*` uses) and notes Interactions where relevant.
++
++---
++
++## 1. Endpoint, auth, headers
++
++| Item | Value (verified by probe unless marked docs) |
++|---|---|
++| Base URL | `https://generativelanguage.googleapis.com` |
++| API version | `v1beta` (SDK default; needed for computer use / MCP / preview features). `v1` also works: probed `gemini-3.8-flash` + `thinkingLevel` on `v1` -> OK. Select via `new GoogleGenAI({ apiKey, httpOptions: { apiVersion: "v1" } })`. |
++| Auth header | `x-goog-api-key: <key>` (works with `AQ.` keys). `?key=` query param also works (200). **`Authorization: Bearer <api key>` does NOT work**: 401 `UNAUTHENTICATED`, reason `ACCESS_TOKEN_TYPE_UNSUPPORTED` (Bearer is only for the OpenAI-compat endpoint). |
++| Other headers | `Content-Type: application/json`. No rate-limit headers are returned (only `server-timing`, `vary`, `alt-svc`). |
++| Key formats | New keys created in AI Studio are "auth keys" bound to a service account (`AQ.` prefix). Docs: **standard (legacy) keys will be rejected after September 2026** — expect BYOK users with old keys to break. Leaked keys: `"Your API key was reported as leaked. Please use another API key."` |
++| SDK env vars | `GEMINI_API_KEY` or `GOOGLE_API_KEY` (`GOOGLE_API_KEY` wins if both). Pass `apiKey` explicitly in a BYOK app. |
++| OpenAI-compat | `https://generativelanguage.googleapis.com/v1beta/openai/` with `Authorization: Bearer <key>`; `reasoning_effort` maps to thinking levels (3.x) or budgets 1024/8192/24576 (2.5); Gemini extras via `extra_body.google.*`. Beta. Not probed. |
++
++Docs: https://ai.google.dev/gemini-api/docs/api-key , https://ai.google.dev/gemini-api/docs/api-versions , https://ai.google.dev/gemini-api/docs/openai
++
++## 2. SDK
++
++```bash
++pnpm add @google/genai@latest   # 2.21.0 on 2026-09-08; Node >= 20 (3.x will require Node 22+)
++```
++```ts
++import { GoogleGenAI } from "@google/genai";
++const ai = new GoogleGenAI({ apiKey, httpOptions: { timeout: 120_000 /* ms */, apiVersion: "v1beta" } });
++```
++- `ai.models.generateContent / generateContentStream / countTokens / list / get`, `ai.chats.create` (client-side history helper), `ai.caches`, `ai.files`, `ai.batches`, `ai.live`, `ai.interactions` (new), `mcpToTool()`.
++- Errors: `ApiError { name: "ApiError", status: <http>, message: <JSON string of the body> }` — message is the raw `{"error":{code,message,status,details}}` JSON; parse it. Retries: `httpOptions.retryOptions` exists (defaults not documented for JS).
++- `config.abortSignal` supported on generate calls.
++- Legacy `@google/generative-ai` is deprecated (since 2025-11-30) — do not use.
++- SDK-side guard: `toolConfig.functionCallingConfig.streamFunctionCallArguments` throws `"streamFunctionCallArguments parameter is only supported in Gemini Enterprise Agent Platform mode, not in Gemini Developer API mode."` (no partial-args streaming on the Developer API).
++
++Docs: https://github.com/googleapis/js-genai , https://ai.google.dev/gemini-api/docs/libraries
++
++## 3. generateContent / streamGenerateContent
++
++REST: `POST /v1beta/models/{model}:generateContent` and `POST /v1beta/models/{model}:streamGenerateContent?alt=sse`.
++
++Request body: `contents[]` (`{role:"user"|"model", parts:[...]}`), `systemInstruction` (`{parts:[{text}]}`), `tools[]`, `toolConfig`, `safetySettings[]`, `generationConfig`, `cachedContent`, `serviceTier`, `store`.
++Response: `candidates[0].content.parts[]`, `candidates[0].finishReason`, `usageMetadata`, `modelVersion`, `responseId`, `promptFeedback`, `modelStatus`.
++
++Part fields seen in probes: `text`, `thought: true` (thought summary), `thoughtSignature` (base64 string, 300–700 chars), `functionCall {name, args, id}`, `functionResponse`, `inlineData {mimeType, data}`, `fileData {fileUri, mimeType}`, `executableCode {language:"PYTHON", code, id}`, `codeExecutionResult {outcome:"OUTCOME_OK", output, id}`.
++
++FinishReason enum (SDK 2.21): `STOP, MAX_TOKENS, SAFETY, RECITATION, LANGUAGE, OTHER, BLOCKLIST, PROHIBITED_CONTENT, SPII, MALFORMED_FUNCTION_CALL, IMAGE_SAFETY, UNEXPECTED_TOOL_CALL, TOO_MANY_TOOL_CALLS, IMAGE_PROHIBITED_CONTENT, NO_IMAGE, IMAGE_RECITATION, IMAGE_OTHER`.
++
++Docs: https://ai.google.dev/api/generate-content , https://ai.google.dev/gemini-api/docs/text-generation
++
++### 3.1 Streaming protocol (verified)
++
++- REST with `alt=sse`: `Content-Type: text/event-stream`; each event is `data: {GenerateContentResponse JSON}` terminated by **CRLF CRLF** (`\r\n\r\n`); no `event:` lines, no `[DONE]` sentinel — the stream simply ends. Errors before the first token come back as a normal HTTP error status (400 etc.) but still with `text/event-stream` content type and a JSON `{error}` body — check `res.ok` before parsing SSE.
++- REST without `alt=sse`: `application/json` **JSON array** of responses (`[{...},{...}]`) streamed incrementally — avoid.
++- SDK: `for await (const chunk of await ai.models.generateContentStream({...}))`, each chunk is a full `GenerateContentResponse` (`chunk.text` getter concatenates non-thought text).
++- Chunk shape observed (Gemini 3.x Flash): 2–4 chunks for short answers. With `includeThoughts: true` the **first chunk** carries `parts:[{text:"…", thought:true}]`; then text chunks; the **last chunk** has `finishReason` and typically an **empty text part carrying `thoughtSignature`** (`{text:"", thoughtSignature:"…"}`) — do not render it as text, but keep it if you replay history.
++- `usageMetadata` is present on **every** chunk. On 3.5/3.6 Flash the first chunk has only `promptTokenCount/totalTokenCount/promptTokensDetails/serviceTier`; subsequent chunks have the full set (`candidatesTokenCount`, `thoughtsTokenCount`). On 3.7 Flash all chunks were full. Rule: **take usage from the last chunk**.
++- Function calls stream as a single chunk: `parts:[{functionCall:{name,args,id:"call_…"}, thoughtSignature:"…"}]`, followed by a final chunk with an empty `text` part and `finishReason:"STOP"` (not `FUNCTION_CALL`). Args are complete (never partial).
++
++### 3.2 usageMetadata fields
++`promptTokenCount`, `candidatesTokenCount`, `thoughtsTokenCount` (absent when 0), `cachedContentTokenCount` (absent when 0), `toolUsePromptTokenCount`, `totalTokenCount` (= prompt + candidates + thoughts), `promptTokensDetails[{modality:"TEXT"|"IMAGE"|…, tokenCount}]`, `cacheTokensDetails[]`, `candidatesTokensDetails[]`, `serviceTier:"standard"`. Thinking tokens are billed as output.
++
++### 3.3 Exact SDK code that worked
++
++```ts
++const stream = await ai.models.generateContentStream({
++  model: "gemini-3.5-flash-lite",
++  contents: [{ role: "user", parts: [{ text: "Count from 1 to 12, then say DONE." }] }],
++  config: {
++    systemInstruction: "You are terse.",
++    maxOutputTokens: 2000,                       // includes thinking tokens!
++    thinkingConfig: { includeThoughts: true, thinkingLevel: "LOW" }, // never combine with thinkingBudget
++  },
++});
++let usage;
++for await (const chunk of stream) {
++  for (const part of chunk.candidates?.[0]?.content?.parts ?? []) {
++    if (part.thought) emitReasoning(part.text);
++    else if (part.text) emitText(part.text);             // may be "" on the final signature-only part
++    if (part.functionCall) emitToolCall(part.functionCall.id, part.functionCall.name, part.functionCall.args, part.thoughtSignature);
++  }
++  if (chunk.candidates?.[0]?.finishReason) finish = chunk.candidates[0].finishReason;
++  usage = chunk.usageMetadata ?? usage;                   // last chunk wins
++}
++```
++
++## 4. generationConfig parameter support (probed matrix)
++
++Probed with `maxOutputTokens: 1500` on the models the free-tier key can call. Legend: OK / 400 "…" = exact server message / — = not probed (quota).
++
++| param | 3.8-flash | 3.5-flash | 3.5-flash-lite | 3.1-flash-lite | 3-flash-preview | gemma-4-31b-it |
++|---|---|---|---|---|---|---|
++| temperature 0 / 1.5 / 2 | OK | OK | OK | OK | OK | 2 OK; 0,1.5 → 500 INTERNAL (flaky) |
++| temperature 2.5 | 400 `* GenerateContentRequest.generation_config.temperature: temperature must be in the range [0.0, 2.0].` | same | same | same | same | same |
++| topP 0.9 | OK | OK | OK | OK | OK | 500 INTERNAL (flaky) |
++| topK 40 | — | OK | OK | OK | OK | OK |
++| seed 42 | — | OK | OK | OK | OK | OK |
++| stopSequences ["DONE"] | — | OK (stopped before DONE) | OK | OK | OK | 500 INTERNAL (flaky) |
++| frequencyPenalty 0.5 | — | 400 `Penalty is not enabled for this model` | same | same | same | same |
++| presencePenalty 0.5 | — | 400 `Penalty is not enabled for this model` | same | same | same | same |
++| candidateCount 2 | 400 `Multiple candidates is not enabled for this model` | same | same | same | same | same |
++| responseMimeType application/json | — | OK | OK | OK | OK | 500 (flaky) |
++| responseSchema (OpenAPI, `OBJECT/STRING`) | — | OK | OK | OK | OK | OK |
++| responseJsonSchema (JSON Schema) | — | OK | OK | OK | OK | OK |
++| responseMimeType text/x.enum + enum schema | — | OK (`blue`) | OK | OK | OK | OK |
++| thinkingConfig.thinkingBudget 0 | — | OK (0 thoughts) | 400 `Request contains an invalid argument.` | OK | OK | 400 `Thinking budget is not supported for this model.` |
++| thinkingBudget 1024 / -1 | — | — | OK / OK | OK / OK | OK / OK (-1 → 1436 thought tokens) | 400 same |
++| includeThoughts true | — | OK (thought parts) | OK | OK | OK | 500 (flaky) |
++| thinkingLevel MINIMAL | docs: **error** | — | OK (0 thoughts) | OK (0) | OK (0) | 500 (flaky) |
++| thinkingLevel LOW / MEDIUM / HIGH | — | — | OK | OK | HIGH, MEDIUM OK; LOW — | 400 `Thinking level is not supported for this model.` (HIGH → 500) |
++| thinkingLevel + thinkingBudget | — | — | 400 `You can only set only one of thinking budget and thinking level.` | same | same | same |
++| responseLogprobs/logprobs | 400 `Logprobs is not enabled for this model` | — | same | same | — | same |
++
++Notes:
++- **Sampling deprecation**: changelog 2026-07-21 — "The sampling parameters `temperature`, `top_p` and `top_k` are now deprecated" (for 3.6 Flash / 3.5 Flash-Lite onward; the 3.8 guide says "Strip `temperature`, `top_p`, and `top_k` from generation configs"). They are still **accepted** by `generateContent` (probed) but Google recommends not sending them; Gemini 3 guide: "strongly recommend keeping the temperature parameter at its default value of 1.0" (lower values can cause looping). Adapter: default to not sending temperature/topP/topK for Gemini 3.x unless the user overrides.
++- Default temperature/topP/topK reported by the models endpoint: 1 / 0.95 / 64 (maxTemperature 2) for all Gemini text models.
++- `maxOutputTokens` **includes thinking tokens**: `gemini-3.8-flash` with `maxOutputTokens: 100` returned empty text, `finishReason: MAX_TOKENS`, `thoughtsTokenCount: 97`. Give thinking models a generous budget (>= 1024 + expected answer) or disable thinking.
++- `stopSequences` are honoured but the stop string itself is stripped.
++
++## 5. Reasoning controls per family
++
++| Family | Default | Controls | Probe evidence |
++|---|---|---|---|
++| Gemini 3.8 / 3.7 Flash | `thinkingLevel` **medium** | `low, medium, high`; `minimal` → error (docs). `thinkingBudget` still accepted "for backward compatibility" per Gemini 3 guide but 3.8 guide says replace it. Cannot be disabled. | 3.8: thoughts 199–330 on trivial prompts. |
++| Gemini 3.6 Flash | medium | `minimal, low, medium, high` | stream has thought part first. |
++| Gemini 3.5 Flash | medium (docs) | all four levels (docs); `thinkingBudget: 0` **does** disable (probed). | thoughts 136–515 by default. |
++| Gemini 3.5 Flash-Lite / 3.1 Flash-Lite | **minimal (off)** | all four levels; `thinkingBudget` 1024 / -1 OK; `thinkingBudget: 0` rejected on 3.5-lite (use MINIMAL) but OK on 3.1-lite. | thoughts 0 unless requested. |
++| Gemini 3 Flash Preview / 3.1 Pro Preview | high (dynamic) | `minimal, low, medium, high`; budgets 0/1024/-1 OK on 3-flash-preview. | |
++| Gemini 2.5 Pro / Flash / Flash-Lite | on / on / off | `thinkingBudget` (Pro 128–32768 cannot disable; Flash 0–24576; Lite 512–24576; -1 dynamic) + `thinkingLevel` low/medium/high (docs). | **Not callable with new keys (404)** — docs only. |
++| Gemma 4 | thinks by default | **no control**: both `thinkingBudget` and `thinkingLevel` → 400. | thoughts 47–430. |
++
++- `includeThoughts: true` → thought **summaries** as parts with `thought: true` (streamed first). Raw reasoning is never returned.
++- Thinking tokens: `usageMetadata.thoughtsTokenCount`, billed at the output rate.
++- SDK enum: `ThinkingLevel.MINIMAL|LOW|MEDIUM|HIGH` (strings `"MINIMAL"`… accepted; Interactions API uses lowercase).
++
++Docs: https://ai.google.dev/gemini-api/docs/thinking , https://ai.google.dev/gemini-api/docs/gemini-3 , https://ai.google.dev/gemini-api/docs/latest-model
++
++### 5.1 Thought signatures (critical for tool calling)
++- Gemini 3.x attaches `thoughtSignature` to the **functionCall part** (and to the last text/empty part of a text answer, and to `executableCode` parts).
++- **Function calling is strict**: replaying the model turn without the signature → 400 `INVALID_ARGUMENT`: `Function call is missing a thought_signature in functionCall parts. This is required for tools to work correctly, and missing thought_signature may lead to degraded model performance. Additional data, function call `default_api:get_weather` , position 2. Please refer to https://ai.google.dev/gemini-api/docs/thought-signatures for more details.` (probed on gemini-3.7-flash).
++- Echoing the real signature → OK. The documented escape hatch `thoughtSignature: "skip_thought_signature_validator"` on the functionCall part → accepted (probed) — useful when importing history from another provider.
++- Text-only multi-turn **without** signatures works (probed): signatures on text parts are optional.
++- Adapter rule: persist `thoughtSignature` alongside each tool call (and ideally each assistant part) in the conversation store and replay it verbatim in `contents`.
++
++## 6. Tool calling (function declarations)
++
++```ts
++const tools = [{ functionDeclarations: [{
++  name: "get_weather", description: "Get weather for a city.",
++  parametersJsonSchema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] }, // JSON Schema (lowercase types)
++  // or legacy: parameters: { type: "OBJECT", properties: { city: { type: "STRING" } }, required: ["city"] }
++}]}];
++// model turn → parts: [{ functionCall: { name, args, id: "call_88210" }, thoughtSignature }]
++// reply:
++contents.push({ role: "model", parts: modelPartsVerbatim });            // keep thoughtSignature!
++contents.push({ role: "user", parts: [{ functionResponse: { name, id, response: { /* any JSON object */ } } }] });
++```
++- `toolConfig.functionCallingConfig`: `mode: AUTO | ANY | NONE | VALIDATED`, `allowedFunctionNames[]`. `ANY` + `allowedFunctionNames` probed OK on 3.6 Flash (forced call).
++- Parallel calls arrive as multiple `functionCall` parts in one turn; send all `functionResponse` parts in one user turn (same order).
++- `functionCall.id` is present on 3.x (`call_NNNNN`); echo it in `functionResponse.id`.
++- Built-in tools **can be combined with function declarations on Gemini 3** (not on 2.5). Structured output + tools also allowed on Gemini 3.
++- SDK automatic function calling exists (`config.automaticFunctionCalling`) — disable it in a UI adapter (`{ disable: true }`) to keep control of the loop.
++- MCP: `mcpToTool(client)` in the SDK (experimental) and server-side `tools:[{ mcpServers: [...] }]` (v1beta, docs: HTTP transport only).
++
++Docs: https://ai.google.dev/gemini-api/docs/function-calling (now Interactions-only; legacy shapes verified by probe and SDK types)
++
++## 7. Structured output / JSON schema
++- `responseMimeType: "application/json"` alone → valid JSON of free shape (one model returned an array).
++- `responseJsonSchema` (standard JSON Schema: lowercase types, `additionalProperties`, `anyOf`, `$ref:"#"`, `enum`, `format` date/time, `minimum/maximum`, `items/prefixItems/minItems/maxItems`) → **preferred**; probed OK on all callable models incl. Gemma 4.
++- `responseSchema` (legacy OpenAPI `Schema` with uppercase `TYPE`s, `propertyOrdering`) → still OK. Don't send both.
++- `responseMimeType: "text/x.enum"` + `{type:"STRING", enum:[…]}` → bare enum value (probed).
++- Works together with thinking (JSON is in non-thought parts) and, on Gemini 3, with tools.
++
++Docs: https://ai.google.dev/gemini-api/docs/structured-output
++
++## 8. Modalities
++| Modality | How | Limits / notes |
++|---|---|---|
++| Image in | `inlineData {mimeType, data(base64)}` or `fileData {fileUri}`; PNG/JPEG/WebP/HEIC/HEIF; inline request total <= 20 MB; up to 3,600 images | Probed 2x2 PNG → `promptTokensDetails IMAGE 1089` tokens on 3.8/3.5 Flash (Gemini 3 default media resolution is high; docs' "258 tokens" applies to older models / low res). Use `mediaResolution` to cut cost. |
++| PDF | `inlineData application/pdf` or Files API; <= 50 MB, <= 1000 pages, ~258 tokens/page | Not probed. |
++| Audio in | wav/mp3/aiff/aac/ogg/flac/m4a/opus/webm…; 32 tokens/s; <= 9.5 h/prompt; >20 MB via Files API | Not probed. |
++| Video in | inline <100 MB, Files API up to 2 GB (free) / 20 GB (paid), YouTube URLs via `fileData.fileUri`; ~100 tok/s low / 300 tok/s high res; 3.5+ have "agentic" video mode | Not probed. |
++| Audio out | **Not via chat models.** TTS models (`gemini-3.1-flash-tts-preview`, `gemini-2.5-*-preview-tts`) with `responseModalities:["AUDIO"]` + `speechConfig` → `inlineData audio/L16 24 kHz PCM`; 32k context; Live API (`bidiGenerateContent`, WebSocket) for realtime voice. | Not probed. |
++| Image out | Image models only (`gemini-3.1-flash-image`, `gemini-3.1-flash-lite-image`, `gemini-3-pro-image`, `gemini-2.5-flash-image`), `responseModalities:["TEXT","IMAGE"]`, `imageConfig {aspectRatio, imageSize "512px"/"1K"/"2K"/"4K"}` → `inlineData image/png`; SynthID watermark; priced per image (~$0.045–0.151). | Not probed. |
++| Video out | `gemini-omni-1.1-flash` / `gemini-omni-flash-preview` (paid tier only), Veo 3.1 via `predictLongRunning`. | Not chat models. |
++
++Docs: image-understanding, document-processing, audio, video-understanding, speech-generation, image-generation, files pages under https://ai.google.dev/gemini-api/docs/
++
++## 9. Files API
++`ai.files.upload({file, config:{mimeType}})` → `{uri, mimeType, state}`; poll until `ACTIVE`; reference with `fileData:{fileUri, mimeType}`. 48 h retention, 2 GB/file, 20 GB/project. Use when the request exceeds 20 MB (100 MB for video per newer docs). Not probed.
++
++## 10. System instruction
++`config.systemInstruction` (string or `Content`) — probed OK on 3.5/3.6/3.7/3.8 Flash ("BLUE" uppercase obeyed). Not probed on Gemma 4 (historically Gemma rejected developer instructions on this API; Gemma 4 docs say the system role is now supported — verify before enabling).
++
++## 11. Conversation state
++- `generateContent` is **stateless**: send the full `contents` history each turn (`ai.chats` is a client-side helper only).
++- Server-side state exists only in the **Interactions API** (`previous_interaction_id`, `store` default true; paid tier retains 55 days, free 1 day). Probed `ai.interactions.create({model, input, generation_config:{thinking_level:"low"}, store:false})` → works with this key; response has `steps[]`, `output_text`, `usage{total_input_tokens,total_output_tokens,total_thought_tokens,total_cached_tokens,total_tool_use_tokens}`. Consider it for a later "Gemini v2" adapter; it lacks Batch, explicit caching and custom safety settings today.
++
++## 12. Context caching
++- **Implicit** caching is on by default for 2.5+ (min 4,096 tokens on 3.x Flash / 3.1 Pro, 2,048 on 2.5); savings show as `usageMetadata.cachedContentTokenCount`; cached input billed at ~10 % (e.g. 3.8 Flash $0.075/M). Put static content first.
++- **Explicit**: `ai.caches.create({model, config:{contents, systemInstruction, tools, ttl:"300s"|expireTime, displayName}})` → pass `config.cachedContent = cache.name`. Models with `createCachedContent` in `supportedGenerationMethods` (all Gemini text models; not Gemma/omni). Storage $0.50–4.50 /M tokens/hour. Probe on 2.5-flash hit the 404 (model gone); not re-probed.
++
++Docs: https://ai.google.dev/gemini-api/docs/caching , https://ai.google.dev/api/caching
++
++## 13. Built-in tools
++- **Google Search grounding**: `tools:[{googleSearch:{}}]`. Response `candidates[0].groundingMetadata { webSearchQueries[], searchEntryPoint{renderedContent: HTML chip — must be displayed per ToS}, groundingChunks[{web:{uri,title}}], groundingSupports[{segment{startIndex,endIndex,text}, groundingChunkIndices[], confidenceScores[]}] }` (docs + SDK types; probe hit 429 on both attempts — **unverified**). Pricing: 3.x — 5,000 free requests/month shared, then $14/1,000; 2.5 — 1,500 free RPD then $35/1,000. Legacy `googleSearchRetrieval` only for 1.5.
++- **URL context**: `tools:[{urlContext:{}}]`, <= 20 URLs, 34 MB each, `candidates[0].urlContextMetadata`; billed as input tokens.
++- **Code execution**: `tools:[{codeExecution:{}}]` probed OK on 3.6 Flash → parts `executableCode{language:"PYTHON", code, id}` + `codeExecutionResult{outcome:"OUTCOME_OK", output, id}` (both also carry `thoughtSignature`), then text. 30 s runtime, matplotlib only for plots, billed as tokens.
++- **File Search** (RAG): stores + `tools:[{fileSearch:{fileSearchStoreNames:[…]}}]`, citations with `media_id`/page numbers; indexing $0.15/M embedding tokens, storage free. Not probed.
++- **Computer use**: `tools:[{computerUse:{environment:"browser"|"mobile"|"desktop"}}]` on 3.8/3.7/3.5 Flash(-Lite) (preview, documented for Interactions). Not probed.
++- **Google Maps grounding**, **MCP servers** tool: v1beta. Not probed.
++
++## 14. Safety settings
++`safetySettings:[{category, threshold}]`; categories `HARM_CATEGORY_HARASSMENT | HATE_SPEECH | SEXUALLY_EXPLICIT | DANGEROUS_CONTENT` (+ `CIVIC_INTEGRITY` in SDK enum); thresholds `OFF | BLOCK_NONE | BLOCK_ONLY_HIGH | BLOCK_MEDIUM_AND_ABOVE | BLOCK_LOW_AND_ABOVE`. Default for 2.5/3 models is **OFF**. Blocked prompt → `promptFeedback.blockReason` (`SAFETY|OTHER|BLOCKLIST|PROHIBITED_CONTENT|IMAGE_SAFETY`) with no candidates; blocked answer → `finishReason: SAFETY` + `safetyRatings`. Probe was routed to 2.5-flash-lite (404) — not re-probed. Not supported on the Interactions API.
++
++## 15. Rate limits and tiers
++- Tiers: Free, Tier 1 (billing linked), Tier 2 ($100 spent + 3 days), Tier 3 ($1,000 + 30 days). Dimensions: RPM, TPM (input), RPD (resets midnight Pacific) + rolling 10-minute spend caps ($10/$50/$200). Per-model tables are only shown in AI Studio (`https://aistudio.google.com/rate-limit`), not in docs.
++- Observed free-tier quotas (from 429 `google.rpc.QuotaFailure` details): `GenerateRequestsPerDayPerProjectPerModel-FreeTier` **quotaValue 20** for `gemini-3.8-flash`; per-minute quota trips after ~5–10 requests; `gemini-3.1-pro*`, `gemini-pro-latest`, `gemini-omni-*` → **limit 0** (paid only). Quotas are **per model**, so parallelising across models is fine.
++- 429 body includes `details[]`: `google.rpc.Help`, `google.rpc.QuotaFailure{violations[{quotaMetric, quotaId, quotaDimensions{model,location}, quotaValue}]}`, `google.rpc.RetryInfo{retryDelay:"24s"}` → honour `retryDelay`.
++- 503 `UNAVAILABLE` "This model is currently experiencing high demand…" was frequent on 3.8-flash and gemini-flash-latest (transient; retry with backoff). Gemma 4 returned 500 `INTERNAL` on ~50 % of calls (retry).
++
++Docs: https://ai.google.dev/gemini-api/docs/rate-limits
++
++## 16. Errors
++Body: `{"error":{"code":<http>,"message":"…","status":"<grpc status>","details":[…]}}`. Seen:
++
++| HTTP | status | Example |
++|---|---|---|
++| 400 | INVALID_ARGUMENT | temperature range, `Penalty is not enabled for this model`, `Multiple candidates is not enabled for this model`, `Logprobs is not enabled for this model`, `You can only set only one of thinking budget and thinking level.`, missing thought_signature, `Request contains an invalid argument.` |
++| 401 | UNAUTHENTICATED | invalid key: `Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential…`, `details[0].reason: "ACCESS_TOKEN_TYPE_UNSUPPORTED"`. (Docs list 400 `API_KEY_INVALID` for malformed keys — with `AQ.`-style bogus key we got 401.) |
++| 403 | PERMISSION_DENIED | key lacks permission / wrong project (docs) |
++| 404 | NOT_FOUND | unknown model: `models/gemini-9-ultra is not found for API version v1beta, or is not supported for generateContent. Call ModelService.ListModels…`; **retired-for-new-users**: `This model models/gemini-2.5-flash is no longer available to new users. Please update your code to use models/gemini-3.6-flash for the latest features and improvements. We recommend you to use the Interactions API.` |
++| 429 | RESOURCE_EXHAUSTED | quota (see §15) |
++| 500 | INTERNAL | `Internal error encountered.` (Gemma 4, transient) |
++| 503 | UNAVAILABLE | high demand |
++| 504 | DEADLINE_EXCEEDED | docs |
++
++Retry: exponential backoff with jitter on 429/500/503/504 (and network), honour `RetryInfo.retryDelay`; never retry 400/401/403/404. Streaming errors mid-stream: SDK throws from the iterator. Timeouts: set `httpOptions.timeout` (ms); long outputs with thinking can take >60 s — use 120 s+ for streaming.
++
++Docs: https://ai.google.dev/gemini-api/docs/troubleshooting , https://ai.google.dev/gemini-api/docs/api-errors (now describes Interactions snake_case codes)
++
++## 17. Token counting
++`ai.models.countTokens({model, contents})` → `{totalTokens}` (free, no quota cost documented). REST `:countTokens` with `generateContentRequest{contents, systemInstruction, tools}` counts everything (probed: 11 tokens text-only → 51 with system + tool) and returns `promptTokensDetails`. Rules of thumb: ~4 chars/token; image 258 tokens (<=384 px) or per 768 px tile — but Gemini 3 high res gave 1,089 for a tiny PNG; audio 32 tok/s; video ~100–300 tok/s.
++
++## 18. Model listing
++`GET /v1beta/models?pageSize=1000` (paginated via `nextPageToken`; SDK `ai.models.list()` / `ai.models.get({model})`). 54 models on 2026-09-08. Fields: `name`, `version`, `displayName`, `description`, `inputTokenLimit`, `outputTokenLimit`, `supportedGenerationMethods[]` (SDK renames to `supportedActions`), `temperature`, `maxTemperature`, `topP`, `topK`, `thinking` (boolean). Filter chat models with `supportedGenerationMethods.includes("generateContent")` and exclude by name pattern (`-image`, `-tts`, `lyria`, `veo`, `transcribe`, `live`, `native-audio`, `robotics`, `computer-use`, `deep-research`, `antigravity`, `embedding`, `aqa`). **The list includes models the key cannot call** (2.5 family → 404 for new users; paid-only → 429 limit 0), so the picker must tolerate per-model failures.
++
++## 19. Pricing (paid tier, USD per 1M tokens; pricing page 2026-09-08)
++| Model | Input | Cached | Output (incl. thinking) |
++|---|---|---|---|
++| 3.8 / 3.7 / 3.6 Flash | 0.75 (1.50 from 2027-01-01) | 0.075 (0.15) | 3.75 (7.50) |
++| 3.5 Flash | 1.50 | 0.15 | 9.00 |
++| 3.5 Flash-Lite | 0.30 | 0.03 | 2.50 |
++| 3.1 Flash-Lite | 0.25 (audio 0.50) | n/a | 1.50 |
++| 3 Flash Preview | 0.50 (audio 1.00) | n/a | 3.00 |
++| 3.1 Pro Preview | 2.00 / 4.00 (>200k) | 0.20 / 0.40 | 12.00 / 18.00 |
++| 2.5 Pro | 1.25 / 2.50 | 0.125 / 0.25 | 10.00 / 15.00 |
++| 2.5 Flash | 0.30 (audio 1.00) | 0.03 | 2.50 |
++| 2.5 Flash-Lite | 0.10 (audio 0.30) | 0.01 | 0.40 |
++| Omni Flash | 1.50 | n/a | 9.00 text / 17.50 video |
++| Gemma 4 | free (free tier only; "Not available" on paid) | | |
++Batch = 50 % off; priority tier = 1.8x; cache storage $0.50–4.50 /M/h; Search grounding see §13. Free tier: prompts may be used for product improvement.
++
++Docs: https://ai.google.dev/gemini-api/docs/pricing
++
++## 20. Lifecycle, aliases, deprecations
++- Stable ids don't change (`gemini-3.6-flash`); previews get >= 2 weeks' notice; `-latest` aliases are hot-swapped with a 2-week email notice: `gemini-flash-latest` → 3.5 Flash (changelog), `gemini-flash-lite-latest` → 3.5 Flash-Lite (probed), `gemini-pro-latest` → 3.1 Pro (quota dimension).
++- Shut down: all `gemini-2.0-*` (2026-06-01), `gemini-3.1-flash-lite-preview` (2026-05-25; the id still answers as 3.1-flash-lite), 2.5 previews. **Gemini 2.5 Pro/Flash/Flash-Lite are closed to new users** (404) though still listed and priced.
++- Preview shutdown windows are 3–9 months. Legacy JS SDK deprecated 2025-11-30. Standard API keys rejected after Sept 2026.
++
++Docs: https://ai.google.dev/gemini-api/docs/deprecations , https://ai.google.dev/gemini-api/docs/changelog , https://ai.google.dev/gemini-api/docs/models
++
++## 21. Probe results summary
++
++| Probe | 3.8-flash | 3.7-flash | 3.6-flash | 3.5-flash | 3.5-flash-lite | 3.1-flash-lite | 3-flash-preview | gemma-4-31b-it | 3.1-pro-preview | 2.5-flash / 2.5-pro | omni-1.1-flash |
++|---|---|---|---|---|---|---|---|---|---|---|---|
++| generateContent + systemInstruction | OK | OK | OK | OK | OK (no sysinstr) | OK (no sysinstr) | OK (no sysinstr) | OK (no sysinstr) | 429 limit 0 | 404 gone | 429 limit 0 |
++| stream (chunk shape, usage) | 503 then quota | OK 3 chunks, usage full each | OK 4 chunks | OK 3 chunks | — | — | — | — | — | 404 | — |
++| params matrix | partial (RPD 20) | — | — | most | full | full | most | full (flaky 500s) | — | 404 | — |
++| function call stream + round trip | 503/429 | OK (+signature tests) | OK | OK | OK | OK | — | — | — | 404 | — |
++| responseJsonSchema | — | — | OK | OK | OK | OK | OK | OK | — | 404 | — |
++| vision (inline PNG) | OK 1089 img tokens | — | — | OK | — | — | — | — | 429 | 404 | 429 |
++| googleSearch grounding | 429 | — | 429 | — | — | — | — | — | — | 404 | — |
++| codeExecution | 429 | — | OK | — | — | — | — | — | — | — | — |
++| invalid key | 401 UNAUTHENTICATED (REST + SDK) | | | | | | | | | | |
++| countTokens / models.get / v1 apiVersion / interactions.create | OK / OK / OK / OK | | | | | | | | | | |
++
++Not probed (docs only): audio/video/PDF input, Files API, explicit caching, safety settings behaviour, TTS/image output, Live API, File Search, computer use, MCP, Batch, 3.1 Pro & omni anything (paid tier), 2.5 anything (closed to new users).
++
++## 22. Gotchas for the adapter (checklist)
++1. Use `x-goog-api-key`, never Bearer. Expect 401 (not 400/403) for bad keys.
++2. Filter the model list by `generateContent` + name patterns, and **probe-or-handle 404 "no longer available to new users"** (2.5 family) and 429 "limit: 0" (paid-only) gracefully — hide or badge those models.
++3. Gemini 3.x: prefer `thinkingLevel` (uppercase enum in SDK), never send both level and budget, `MINIMAL` errors on 3.7/3.8, Gemma rejects both. Map PolyLLM "reasoning effort" → level; "off" → `MINIMAL` on lite/3.5-flash-lite, `thinkingBudget: 0` on 3.5 Flash / 3.1-lite / 3-flash-preview, and "not disableable" on 3.6+/Pro.
++4. `maxOutputTokens` includes thoughts — floor it (e.g. >= 2048) when thinking is on, or you get empty text with `MAX_TOKENS`.
++5. Store and replay `thoughtSignature` on tool-call parts (400 otherwise); `skip_thought_signature_validator` is the documented escape hatch. Strip empty signature-only text parts from the UI but keep them in history.
++6. Usage: read `usageMetadata` from the last chunk; thoughts = `thoughtsTokenCount`, cache hits = `cachedContentTokenCount`.
++7. Penalties, `candidateCount > 1`, logprobs → 400 on every model: don't expose them for Gemini. Temperature/topP/topK are accepted but deprecated for 3.6+; don't send by default.
++8. SSE events are CRLF-delimited `data:` lines with no terminator; HTTP error status can arrive with `text/event-stream` content type.
++9. Quotas are per model; free tier is tiny (20 RPD on 3.8-flash) — surface `RetryInfo.retryDelay` to the user.
++10. Consider a future switch to the Interactions API (server-side state, unified steps); today `generateContent` is stable and complete for chat.

added docs/provider-research/gemini.models.json +231 −0

++[
++  {
++    "id": "gemini-3.8-flash",
++    "displayName": "Gemini 3.8 Flash",
++    "family": "gemini-3.x-flash",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 (accepted; Google recommends leaving 1.0; deprecated for 3.6+ per changelog 2026-07-21)", "topP": true, "topK": true, "maxTokens": true, "reasoningEffort": ["low", "medium", "high"], "thinkingBudget": "docs: legacy, replace with thinkingLevel; not probed (free-tier RPD=20 exhausted)", "stop": true, "seed": true, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0.75, "cachedInputPerMillion": 0.075, "outputPerMillion": 3.75, "note": "introductory through 2026-12-31; from 2027-01-01: 1.50 / 0.15 / 7.50. >200k-token prompts not tiered." },
++    "status": "active",
++    "notes": "Stable, released 2026-09-02. Probed: generateContent+systemInstruction OK, vision OK (2x2 PNG = 1089 image tokens), temperature 0/1.5/2 OK, candidateCount=2 -> 400, logprobs -> 400. Default thinkingLevel medium; 'minimal' returns an error (docs). Free tier: 20 requests/day (quotaValue=20 seen in 429). Thinking tokens count against maxOutputTokens (maxOutputTokens=100 gave empty text, finishReason MAX_TOKENS, 97 thought tokens)."
++  },
++  {
++    "id": "gemini-3.7-flash",
++    "displayName": "Gemini 3.7 Flash",
++    "family": "gemini-3.x-flash",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 (deprecated, keep 1.0)", "topP": true, "topK": true, "maxTokens": true, "reasoningEffort": ["low", "medium", "high"], "thinkingBudget": "docs-only: legacy", "stop": "docs-only", "seed": "docs-only", "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0.75, "cachedInputPerMillion": 0.075, "outputPerMillion": 3.75, "note": "same as 3.8 Flash: introductory through 2026-12-31, then 1.50 / 0.15 / 7.50" },
++    "status": "active",
++    "notes": "Stable, Aug 2026. Probed: generateContent+systemInstruction OK; stream 3 chunks with full usageMetadata on every chunk; function call round trip OK; thought signature on functionCall part is MANDATORY (400 'Function call is missing a thought_signature in functionCall parts...' when omitted; dummy 'skip_thought_signature_validator' accepted); text-only multi-turn without signatures OK. Param matrix not probed (family assumed = 3.8)."
++  },
++  {
++    "id": "gemini-3.6-flash",
++    "displayName": "Gemini 3.6 Flash",
++    "family": "gemini-3.x-flash",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 (deprecated per changelog 2026-07-21, keep 1.0)", "topP": "deprecated", "topK": "deprecated", "maxTokens": true, "reasoningEffort": ["minimal", "low", "medium", "high"], "thinkingBudget": "docs-only: legacy", "stop": "docs-only", "seed": "docs-only", "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0.75, "cachedInputPerMillion": 0.075, "outputPerMillion": 3.75, "note": "same as 3.8 Flash: introductory through 2026-12-31, then 1.50 / 0.15 / 7.50" },
++    "status": "active",
++    "status_note": "Google's recommended replacement for gemini-2.5-flash (404 message).",
++    "notes": "Stable, July 2026. Probed: generateContent OK; stream 4 chunks (thought summary chunk first when includeThoughts, last chunk = empty text part carrying thoughtSignature + finishReason STOP); function call streaming (1 chunk with functionCall+thoughtSignature+id, then final empty chunk) and round trip OK; responseJsonSchema OK; codeExecution tool OK (executableCode{language:'PYTHON',code,id} + codeExecutionResult{outcome:'OUTCOME_OK',output,id}); googleSearch probe hit 429 (unverified). Param matrix not probed."
++  },
++  {
++    "id": "gemini-3.5-flash",
++    "displayName": "Gemini 3.5 Flash",
++    "family": "gemini-3.x-flash",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 probed OK (2.5 -> 400)", "topP": true, "topK": true, "maxTokens": true, "reasoningEffort": "docs: minimal/low/medium/high (default medium); levels not probed (429)", "thinkingBudget": "0 probed OK (disables thinking); 1024/-1 not probed (429)", "stop": true, "seed": true, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 1.5, "cachedInputPerMillion": 0.15, "outputPerMillion": 9.0 },
++    "status": "active",
++    "notes": "GA May 2026; current target of gemini-flash-latest per changelog. Probed: systemInstruction OK, stream 3 chunks (first chunk usage has only promptTokenCount; later chunks full), includeThoughts -> parts with thought:true, function call streaming + round trip OK (functionCall has id 'call_...'), responseMimeType json / responseSchema / responseJsonSchema / text/x.enum OK, penalties -> 400 'Penalty is not enabled for this model', candidateCount=2 -> 400, vision OK. Free tier RPD low (~20)."
++  },
++  {
++    "id": "gemini-3.5-flash-lite",
++    "displayName": "Gemini 3.5 Flash-Lite",
++    "family": "gemini-3.x-flash-lite",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 probed OK (deprecated per changelog 2026-07-21)", "topP": true, "topK": true, "maxTokens": true, "reasoningEffort": ["minimal", "low", "medium", "high"], "thinkingBudget": "1024 and -1 OK; 0 -> 400 'Request contains an invalid argument.' (use thinkingLevel MINIMAL to disable)", "stop": true, "seed": true, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0.3, "cachedInputPerMillion": 0.03, "outputPerMillion": 2.5 },
++    "status": "active",
++    "notes": "Stable, July 2026; default thinking OFF (thoughtsTokenCount 0 unless thinkingLevel/thinkingBudget set). Full param matrix probed: all thinkingLevel values OK (minimal=0 thoughts), thinkingLevel+thinkingBudget together -> 400 'You can only set only one of thinking budget and thinking level.', penalties/candidateCount/logprobs -> 400. Function calling + responseJsonSchema OK. gemini-flash-lite-latest currently resolves here (modelVersion)."
++  },
++  {
++    "id": "gemini-3.1-flash-lite",
++    "displayName": "Gemini 3.1 Flash-Lite",
++    "family": "gemini-3.x-flash-lite",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 probed OK", "topP": true, "topK": true, "maxTokens": true, "reasoningEffort": ["minimal", "low", "medium", "high"], "thinkingBudget": "0 / 1024 / -1 all OK", "stop": true, "seed": true, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0.25, "cachedInputPerMillion": null, "outputPerMillion": 1.5, "note": "audio input 0.50/M; cached price not listed on pricing page" },
++    "status": "active",
++    "notes": "GA May 2026; default thinkingLevel minimal (thinking off). Full param matrix probed: same acceptance pattern as 3.5-flash-lite except thinkingBudget 0 is accepted. Function calling + responseJsonSchema OK. gemini-3.1-flash-lite-preview alias still answers and reports modelVersion gemini-3.1-flash-lite (changelog says preview shut down 2026-05-25)."
++  },
++  {
++    "id": "gemini-3-flash-preview",
++    "displayName": "Gemini 3 Flash Preview",
++    "family": "gemini-3.x-flash",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 probed OK", "topP": true, "topK": true, "maxTokens": true, "reasoningEffort": ["minimal", "low", "medium", "high"], "thinkingBudget": "0 / 1024 / -1 all OK (-1 produced 1436 thought tokens)", "stop": true, "seed": true, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0.5, "cachedInputPerMillion": null, "outputPerMillion": 3.0, "note": "audio input 1.00/M" },
++    "status": "preview",
++    "notes": "Dec 2025 preview; superseded by gemini-3.5-flash (stable). Default thinking high (dynamic). Param matrix probed except thinkingLevel low / logprobs (429). No shutdown date published."
++  },
++  {
++    "id": "gemini-3.1-pro-preview",
++    "displayName": "Gemini 3.1 Pro Preview",
++    "family": "gemini-3.x-pro",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 (2.5 -> 400 probed; keep 1.0)", "topP": "docs-only", "topK": "docs-only", "maxTokens": true, "reasoningEffort": ["minimal", "low", "medium", "high"], "thinkingBudget": "docs-only: legacy", "stop": "docs-only", "seed": "docs-only", "frequencyPenalty": "docs-only (family pattern: rejected)", "presencePenalty": "docs-only (family pattern: rejected)" },
++    "pricing": { "inputPerMillion": 2.0, "cachedInputPerMillion": 0.2, "outputPerMillion": 12.0, "note": ">200k prompt: 4.00 in / 0.40 cached / 18.00 out; storage 4.50/M/hr" },
++    "status": "preview",
++    "notes": "PAID TIER ONLY: free-tier quota is 0 (429 RESOURCE_EXHAUSTED 'limit: 0', quotaId GenerateRequestsPerDayPerProjectPerModel-FreeTier). Not probed beyond that. Default thinkingLevel high. gemini-pro-latest currently resolves here (also 429 limit 0 on free tier). Google's recommended replacement for gemini-2.5-pro."
++  },
++  {
++    "id": "gemini-3.1-pro-preview-customtools",
++    "displayName": "Gemini 3.1 Pro Preview (custom tools)",
++    "family": "gemini-3.x-pro",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2", "topP": "docs-only", "topK": "docs-only", "maxTokens": true, "reasoningEffort": ["low", "medium", "high"], "thinkingBudget": "docs-only", "stop": "docs-only", "seed": "docs-only", "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 2.0, "cachedInputPerMillion": 0.2, "outputPerMillion": 12.0, "note": "assumed same as gemini-3.1-pro-preview (not separately listed)" },
++    "status": "preview",
++    "notes": "Variant that prioritises custom (function) tools over built-ins in agentic/bash workflows; 'may see quality fluctuations'. Paid tier only (429 limit 0 on free tier). Not probed."
++  },
++  {
++    "id": "gemini-2.5-pro",
++    "displayName": "Gemini 2.5 Pro",
++    "family": "gemini-2.5",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 (2.5 -> 400 probed)", "topP": "docs-only", "topK": "docs-only", "maxTokens": true, "reasoningEffort": "docs: thinkingLevel low/medium/high accepted; OpenAI-compat maps minimal/low=1024, medium=8192, high=24576 budget", "thinkingBudget": "docs-only: 128-32768, cannot be disabled (-1 dynamic)", "stop": "docs-only", "seed": "docs-only", "frequencyPenalty": "docs-only", "presencePenalty": "docs-only" },
++    "pricing": { "inputPerMillion": 1.25, "cachedInputPerMillion": 0.125, "outputPerMillion": 10.0, "note": ">200k prompt: 2.50 / 0.25 / 15.00; paid tier only" },
++    "status": "deprecated",
++    "notes": "LISTED by /v1beta/models but generateContent returns 404 NOT_FOUND: 'This model models/gemini-2.5-pro is no longer available to new users. Please update your code to use models/gemini-3.1-pro-preview ... We recommend you to use the Interactions API.' Only pre-existing users can call it. Knowledge cutoff Jan 2025. Treat as legacy/hidden in a BYOK app unless the user's key is grandfathered (detect via 404 message)."
++  },
++  {
++    "id": "gemini-2.5-flash",
++    "displayName": "Gemini 2.5 Flash",
++    "family": "gemini-2.5",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2 (2.5 -> 400 probed)", "topP": "docs-only", "topK": "docs-only", "maxTokens": true, "reasoningEffort": "docs: low/medium/high", "thinkingBudget": "docs-only: 0 (off) to 24576, -1 dynamic", "stop": "docs-only", "seed": "docs-only", "frequencyPenalty": "docs-only", "presencePenalty": "docs-only" },
++    "pricing": { "inputPerMillion": 0.3, "cachedInputPerMillion": 0.03, "outputPerMillion": 2.5, "note": "audio input 1.00/M, cached audio 0.10/M" },
++    "status": "deprecated",
++    "notes": "LISTED by /v1beta/models but generateContent, streamGenerateContent, cachedContents.create all return 404 'no longer available to new users' -> use gemini-3.6-flash. Only grandfathered keys can use it. Knowledge cutoff Jan 2025."
++  },
++  {
++    "id": "gemini-2.5-flash-lite",
++    "displayName": "Gemini 2.5 Flash-Lite",
++    "family": "gemini-2.5",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2", "topP": "docs-only", "topK": "docs-only", "maxTokens": true, "reasoningEffort": "docs: low/medium/high (default off)", "thinkingBudget": "docs-only: 512-24576, 0 off", "stop": "docs-only", "seed": "docs-only", "frequencyPenalty": "docs-only", "presencePenalty": "docs-only" },
++    "pricing": { "inputPerMillion": 0.1, "cachedInputPerMillion": 0.01, "outputPerMillion": 0.4, "note": "audio input 0.30/M" },
++    "status": "deprecated",
++    "notes": "LISTED but 404 'no longer available to new users' -> use gemini-3.5-flash-lite (probed via chats + safetySettings probes)."
++  },
++  {
++    "id": "gemini-flash-latest",
++    "displayName": "Gemini Flash (latest alias)",
++    "family": "alias",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2", "topP": true, "topK": true, "maxTokens": true, "reasoningEffort": ["minimal", "low", "medium", "high"], "thinkingBudget": "legacy", "stop": true, "seed": true, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 1.5, "cachedInputPerMillion": 0.15, "outputPerMillion": 9.0, "note": "billed as the model it resolves to (currently gemini-3.5-flash per changelog May 2026); not listed on pricing page" },
++    "status": "active",
++    "notes": "Hot-swapped alias; Google gives 2 weeks' email notice before re-pointing. Probe returned 503 'high demand' (transient) so resolution not confirmed live; changelog says gemini-3.5-flash. Avoid as default in a registry: pin explicit ids and show alias as convenience."
++  },
++  {
++    "id": "gemini-flash-lite-latest",
++    "displayName": "Gemini Flash-Lite (latest alias)",
++    "family": "alias",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2", "topP": true, "topK": true, "maxTokens": true, "reasoningEffort": ["minimal", "low", "medium", "high"], "thinkingBudget": "1024/-1 OK, 0 rejected (as 3.5-flash-lite)", "stop": true, "seed": true, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0.3, "cachedInputPerMillion": 0.03, "outputPerMillion": 2.5, "note": "billed as gemini-3.5-flash-lite (probe modelVersion = gemini-3.5-flash-lite)" },
++    "status": "active",
++    "notes": "Probed: resolves to gemini-3.5-flash-lite (modelVersion). Used for the raw REST SSE probe (works)."
++  },
++  {
++    "id": "gemini-pro-latest",
++    "displayName": "Gemini Pro (latest alias)",
++    "family": "alias",
++    "contextTokens": 1048576,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": true, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": true, "structuredOutput": true, "streaming": true, "files": true, "webSearch": true },
++    "parameters": { "temperature": "0-2", "topP": "docs-only", "topK": "docs-only", "maxTokens": true, "reasoningEffort": ["low", "medium", "high"], "thinkingBudget": "legacy", "stop": "docs-only", "seed": "docs-only", "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 2.0, "cachedInputPerMillion": 0.2, "outputPerMillion": 12.0, "note": "billed as the resolved model (429 quota dimension showed model=gemini-3.1-pro -> resolves to 3.1 Pro preview)" },
++    "status": "active",
++    "notes": "Paid tier only (free-tier 429 limit 0, quota dimension model=gemini-3.1-pro)."
++  },
++  {
++    "id": "gemma-4-31b-it",
++    "displayName": "Gemma 4 31B (instruction-tuned)",
++    "family": "gemma-4",
++    "contextTokens": 262144,
++    "maxOutputTokens": 32768,
++    "capabilities": { "text": true, "vision": "docs: image/video/audio input supported by Gemma 4; not probed on the API", "audioInput": null, "audioOutput": false, "imageGeneration": false, "video": null, "reasoning": true, "tools": "docs: yes; not probed", "structuredOutput": true, "streaming": true, "files": null, "webSearch": false },
++    "parameters": { "temperature": "0-2 accepted (2 probed OK; 0/1.5 hit transient 500s)", "topP": "probed: 500 INTERNAL x2 (transient?)", "topK": true, "maxTokens": true, "reasoningEffort": false, "thinkingBudget": false, "stop": "probed: 500 INTERNAL x2 (transient?)", "seed": true, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0, "cachedInputPerMillion": null, "outputPerMillion": 0, "note": "Free tier: 'Free of charge' (data used for product improvement). Paid tier: 'Not available'." },
++    "status": "active",
++    "notes": "Open model served on Gemini API. Thinks by default (thoughtsTokenCount 47-430) but thinkingConfig is rejected: thinkingBudget -> 400 'Thinking budget is not supported for this model.'; thinkingLevel -> 400 'Thinking level is not supported for this model.' responseSchema / responseJsonSchema / text/x.enum OK. ~50% of probe requests returned 500 INTERNAL 'Internal error encountered.' (flaky; retry). systemInstruction not probed. No createCachedContent / batch support (supportedGenerationMethods = generateContent, countTokens)."
++  },
++  {
++    "id": "gemma-4-26b-a4b-it",
++    "displayName": "Gemma 4 26B A4B (MoE, instruction-tuned)",
++    "family": "gemma-4",
++    "contextTokens": 262144,
++    "maxOutputTokens": 32768,
++    "capabilities": { "text": true, "vision": null, "audioInput": null, "audioOutput": false, "imageGeneration": false, "video": null, "reasoning": true, "tools": null, "structuredOutput": null, "streaming": true, "files": null, "webSearch": false },
++    "parameters": { "temperature": "0-2", "topP": null, "topK": null, "maxTokens": true, "reasoningEffort": false, "thinkingBudget": false, "stop": null, "seed": null, "frequencyPenalty": false, "presencePenalty": false },
++    "pricing": { "inputPerMillion": 0, "cachedInputPerMillion": null, "outputPerMillion": 0, "note": "free tier only" },
++    "status": "active",
++    "notes": "Probed once: 'pong' OK with 58 thought tokens. Assume same behaviour as gemma-4-31b-it (unknowns = null)."
++  },
++  {
++    "id": "gemini-omni-1.1-flash",
++    "displayName": "Gemini Omni 1.1 Flash",
++    "family": "gemini-omni",
++    "contextTokens": 131072,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": "docs: text output priced (9.00/M) but model card says output = video only", "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": null, "structuredOutput": null, "streaming": null, "files": null, "webSearch": false },
++    "parameters": { "temperature": "0-2 (2.5 -> 400 probed)", "topP": null, "topK": null, "maxTokens": true, "reasoningEffort": null, "thinkingBudget": null, "stop": null, "seed": null, "frequencyPenalty": null, "presencePenalty": null },
++    "pricing": { "inputPerMillion": 1.5, "cachedInputPerMillion": null, "outputPerMillion": 9.0, "note": "video output 17.50/M (~0.10/s); paid tier only" },
++    "status": "active",
++    "notes": "Video-generation model (GA Aug 2026; 3-10 s clips, 360p-4K). Models endpoint says inputTokenLimit 131072 (model card says 1,048,576 — endpoint value preferred). PAID TIER ONLY: free tier 429 'limit: 0'. Not usable for chat; exclude from the chat model picker or gate behind paid-tier detection."
++  },
++  {
++    "id": "gemini-omni-flash-preview",
++    "displayName": "Gemini Omni Flash Preview",
++    "family": "gemini-omni",
++    "contextTokens": 131072,
++    "maxOutputTokens": 65536,
++    "capabilities": { "text": null, "vision": true, "audioInput": true, "audioOutput": false, "imageGeneration": false, "video": true, "reasoning": true, "tools": null, "structuredOutput": null, "streaming": null, "files": null, "webSearch": false },
++    "parameters": { "temperature": "0-2", "topP": null, "topK": null, "maxTokens": true, "reasoningEffort": null, "thinkingBudget": null, "stop": null, "seed": null, "frequencyPenalty": null, "presencePenalty": null },
++    "pricing": { "inputPerMillion": 1.5, "cachedInputPerMillion": null, "outputPerMillion": 9.0, "note": "video output 17.50/M; paid tier only" },
++    "status": "preview",
++    "notes": "Preview predecessor of gemini-omni-1.1-flash (June 2026). Free tier 429 'limit: 0'. Not a chat model."
++  }
++]

added docs/provider-research/openai.md +390 −0

++# OpenAI provider audit for PolyLLM
++
++Last documentation audit: 2026-09-08
++SDK probed: `openai@7.10.0` (npm), Node 25.9.0, `tsx` 4.23.13. Probe scripts and raw results: `research/openai/` (`results/*.json`, no secrets).
++Model registry produced from this audit: `docs/provider-research/openai.models.json` (84 entries).
++
++> Docs moved: every `platform.openai.com/docs/...` URL now 301-redirects to `https://developers.openai.com/api/docs/...`. The API reference pages there render only partially through a headless fetch (the "create response" and "streaming events" pages surfaced only the cancel endpoint), so event names, enums and parameter lists below were cross-checked against the SDK type definitions (`node_modules/openai/resources/responses/responses.d.ts`, `shared.d.ts`) and against live probes. Where docs and probes disagree, the probe wins and the disagreement is called out.
++
++---
++
++## 1. Endpoint, auth, headers
++
++| Item | Value |
++|---|---|
++| Base URL | `https://api.openai.com/v1/` (docs also mention data-residency endpoints in the SDK 7.6 release notes; not needed for BYOK) |
++| Auth | `Authorization: Bearer <OPENAI_API_KEY>` |
++| Optional headers | `OpenAI-Organization: org_...`, `OpenAI-Project: proj_...` (billing scope), `X-Client-Request-Id` (ASCII, <= 512 chars), `OpenAI-Safety-Identifier` (Realtime only; for HTTP use the `safety_identifier` body param) |
++| Response headers seen | `x-request-id`, `openai-processing-ms`, `openai-version: 2020-10-01`, `openai-organization`, `openai-project`, `x-ratelimit-*` (see section 13) |
++| Header size limits | total < 64 KiB, single custom header value < 60 KiB |
++| `OpenAI-Beta` | Not required for Responses, Chat Completions, tools or structured outputs (none sent by SDK 7.x for these). |
++
++Source: https://developers.openai.com/api/docs/api-reference/introduction
++
++## 2. Which API: Responses vs Chat Completions
++
++- **Use the Responses API (`POST /v1/responses`) as the primary adapter.** Docs: "While Chat Completions remains supported, Responses is recommended for all new projects." Chat Completions is *not* labelled legacy/deprecated and has no shutdown date, but:
++  - Pro models (`gpt-5.5-pro`, `gpt-5.4-pro`, `gpt-5.2-pro`, `gpt-5-pro`, `o3-pro`, `o1-pro`), `gpt-5.3-codex` and `gpt-5.6-cyber` are **Responses-only**.
++  - Built-in tools (web_search, file_search, code_interpreter, MCP, image_generation, computer use) exist only in Responses (Chat Completions has only `web_search_options` on the `*-search-*` models).
++  - Reasoning docs: "Reasoning models work better with the Responses API"; GPT-6 Astra page: "Requires Responses API for tool calling (Chat Completions available but limited)".
++  - Reasoning summaries, encrypted reasoning, `previous_response_id`, `conversation`, background mode, `reasoning.context` are Responses-only.
++- Chat Completions still works (verified 2026-09-08 on gpt-4.1-mini, gpt-5.5, o4-mini): chunk shape `chat.completion.chunk` with `choices[0].delta`, `usage` only in the final chunk when `stream_options.include_usage: true`; usage fields `prompt_tokens`/`completion_tokens`/`prompt_tokens_details.cached_tokens`/`completion_tokens_details.reasoning_tokens`. `max_tokens` is rejected on new models (`gpt-6-astra`: `400 unsupported_parameter "'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead."`).
++- The Chat-Completions-only web search models (`gpt-5-search-api`, `gpt-4o-search-preview`, `gpt-4o-mini-search-preview`) return `400 model_not_found "The requested model 'gpt-5-search-api' is not supported with the Responses API."` on Responses. Do not expose them; use the `web_search` tool on a normal model.
++- Assistants API shut down 2026-08-26 (replaced by Responses + Conversations). `v1/prompts` (reusable prompts), Evals, Agent Builder shut down 2026-11-30.
++
++Sources: https://developers.openai.com/api/docs/api-reference/chat , https://developers.openai.com/api/docs/guides/migrate-to-responses , https://developers.openai.com/api/docs/deprecations
++
++### Chat Completions -> Responses mapping (for the adapter)
++
++| Chat Completions | Responses |
++|---|---|
++| `messages` | `input` (string, or array of items: messages `{role, content}` / `function_call` / `function_call_output` / `reasoning` ...) |
++| `system` message | `instructions` (top-level) or a `developer` (or `system`) role message; all three verified to work |
++| `max_tokens` / `max_completion_tokens` | `max_output_tokens` (min 16; includes reasoning tokens) |
++| `response_format` | `text.format` (`{type:"text"}` / `{type:"json_schema", name, schema, strict}` / `{type:"json_object"}`) |
++| `tools[].function.{name,parameters}` | flattened `tools[] = {type:"function", name, description, parameters, strict}` |
++| `tool_calls[]` in message | separate `function_call` output items (`call_id`, `name`, `arguments`) |
++| `role:"tool"` message | `{type:"function_call_output", call_id, output}` input item |
++| `reasoning_effort`, `verbosity` | `reasoning.effort`, `text.verbosity` |
++| `usage.prompt_tokens` / `completion_tokens` | `usage.input_tokens` / `output_tokens` (+ `input_tokens_details.cached_tokens`, `cache_write_tokens`, `output_tokens_details.reasoning_tokens`, `total_tokens`) |
++| `n`, `seed`, `stop`, `logprobs` (bool) | `n` removed; **`seed` and `stop` do not exist** (`400 unknown_parameter`); logprobs via `top_logprobs` + `include:["message.output_text.logprobs"]` |
++| `stream_options.include_usage` | not needed: `response.completed` carries the full `response.usage` |
++
++## 3. Request shape (Responses) - parameters that matter
++
++From SDK `ResponseCreateParams` (7.10.0) and probes:
++
++`model`, `input`, `instructions`, `max_output_tokens` (>= 16), `reasoning {effort, summary, mode, context}`, `text {format, verbosity}`, `tools`, `tool_choice` (`"auto"|"none"|"required"|{type:"function",name}|{type:"allowed_tools",...}`), `parallel_tool_calls`, `temperature`, `top_p`, `top_logprobs`, `include[]`, `store` (default **true**), `previous_response_id`, `conversation`, `stream`, `stream_options {include_obfuscation}`, `background`, `truncation` (`"auto"|"disabled"`, default disabled), `metadata`, `service_tier` (`auto|default|flex|priority|fast`), `prompt_cache_key`, `prompt_cache_retention` (`in_memory|24h`, pre-5.6), `prompt_cache_options {mode, ttl:"30m"}` (5.6+), `safety_identifier`, `user`, `context_management` (compaction), `moderation`, `prompt`.
++
++`include` values: `file_search_call.results`, `web_search_call.results`, `web_search_call.action.sources`, `message.input_image.image_url`, `computer_call_output.output.image_url`, `code_interpreter_call.outputs`, `reasoning.encrypted_content`, `message.output_text.logprobs`.
++
++Response object: `id` (`resp_...`), `object:"response"`, `status` (`completed|failed|in_progress|cancelled|queued|incomplete`), `incomplete_details.reason` (`max_output_tokens|max_messages|content_filter|steered`), `error`, `model` (resolved snapshot, e.g. `gpt-5.5-2026-04-23`), `output[]` items, `usage`, plus echoes of `reasoning`, `text`, `temperature`, `top_p`, `truncation`, `store`, `service_tier`, `previous_response_id`, `tools`. The SDK adds a convenience `output_text` getter **only on non-streaming `create()` results** (the `response` object inside a `response.completed` event does not have it - accumulate deltas or read `output[].content[].text`).
++
++## 4. Streaming protocol
++
++SSE; every event is JSON with `type` and a monotonically increasing `sequence_number` (verified: strictly +1 per event). Text deltas also carry an `obfuscation` padding string (disable via `stream_options.include_obfuscation:false`).
++
++Event names observed in probes (exact strings):
++
++```
++response.created > response.in_progress
++  > response.output_item.added {item:{type:"reasoning"...}}            (reasoning models, effort >= low)
++      > response.reasoning_summary_part.added
++      > response.reasoning_summary_text.delta {delta}   (x N)          (only when reasoning.summary is set AND the model emits one)
++      > response.reasoning_summary_text.done {text}
++      > response.reasoning_summary_part.done
++    > response.output_item.done
++  > response.output_item.added {item:{type:"message", role:"assistant"}}
++    > response.content_part.added {part:{type:"output_text", text:"", annotations:[]}}
++      > response.output_text.delta {delta, item_id, output_index, content_index, logprobs, obfuscation}   (x N)
++      > response.output_text.annotation.added {annotation:{type:"url_citation",...}, annotation_index}    (web search)
++      > response.output_text.done {text}
++    > response.content_part.done
++  > response.output_item.done
++> response.completed {response:{...usage}}   |  response.incomplete  |  response.failed  |  error
++```
++
++Function calls (verified on all six models):
++
++```
++response.output_item.added   {item:{type:"function_call", id:"fc_...", call_id:"call_...", name, arguments:"", status:"in_progress"}, output_index}
++response.function_call_arguments.delta {delta, item_id, output_index}
++response.function_call_arguments.done  {arguments:"{...}", item_id}
++response.output_item.done    {item:{type:"function_call", ..., arguments:"{...}", status:"completed"}}
++response.completed
++```
++
++Web search: `response.web_search_call.in_progress` > `.searching` > `.completed` (item type `web_search_call`).
++
++Full list of event types in the SDK (for exhaustive switch statements): `response.created, response.in_progress, response.queued, response.completed, response.incomplete, response.failed, error, response.output_item.added/done, response.content_part.added/done, response.output_text.delta/done, response.output_text.annotation.added, response.refusal.delta/done, response.reasoning_text.delta/done, response.reasoning_summary_part.added/done, response.reasoning_summary_text.delta/done, response.function_call_arguments.delta/done, response.custom_tool_call_input.delta/done, response.web_search_call.in_progress/searching/completed, response.file_search_call.in_progress/searching/completed, response.code_interpreter_call.in_progress/interpreting/completed, response.code_interpreter_call_code.delta/done, response.image_generation_call.in_progress/generating/partial_image/completed, response.mcp_call.in_progress/completed/failed, response.mcp_call_arguments.delta/done, response.mcp_list_tools.in_progress/completed/failed, response.shell_call_command.added/delta/done, response.shell_call_output_content.delta/done, response.audio.delta/done, response.audio.transcript.delta/done, response.steer.*`.
++
++Resumable streams: with `background:true, stream:true`, reconnect with `GET /v1/responses/{id}?stream=true&starting_after={sequence_number}`.
++
++Sources: https://developers.openai.com/api/docs/guides/streaming-responses , https://developers.openai.com/api/docs/guides/background , SDK types.
++
++### Exact SDK streaming code that worked (research/openai/03-stream.ts, 05-tools-stream.ts)
++
++```ts
++import OpenAI from "openai";
++const client = new OpenAI({ maxRetries: 1, timeout: 180_000 }); // key from OPENAI_API_KEY
++
++const stream = await client.responses.create({
++  model: "gpt-5.5",
++  input: [{ role: "user", content: "Say hello in five words." }],
++  reasoning: { effort: "low", summary: "auto" },
++  max_output_tokens: 200,
++  stream: true,
++});
++let text = "", final: OpenAI.Responses.Response | null = null;
++for await (const ev of stream) {
++  switch (ev.type) {
++    case "response.output_text.delta": text += ev.delta; break;
++    case "response.reasoning_summary_text.delta": /* show thinking */ break;
++    case "response.function_call_arguments.delta": /* accumulate by ev.item_id */ break;
++    case "response.output_item.done": if (ev.item.type === "function_call") { /* ev.item.call_id, name, arguments */ } break;
++    case "response.completed": case "response.incomplete": final = ev.response; break; // final.usage, final.output
++    case "error": throw new Error(ev.message);
++  }
++}
++```
++
++Tool round trip (stateless): replay `[...previousInput, ...final.output, { type: "function_call_output", call_id, output: JSON.stringify(result) }]`. Replaying the *entire* `output` array (including `reasoning` items) is what the docs require for reasoning models; verified on gpt-5.5, gpt-5.4-mini, gpt-5.6-sol, gpt-6-astra, gpt-4.1-mini. Stateful alternative verified on gpt-5.4-mini: `previous_response_id: final.id, input: [function_call_output]`.
++
++## 5. Tool calling format
++
++- Definition: `{ type: "function", name, description, parameters: <JSON Schema>, strict: true }` (flattened; `strict` recommended; strict requires `additionalProperties:false` and all properties in `required`).
++- Output item: `{ id: "fc_...", type: "function_call", status: "completed", call_id: "call_...", name, arguments: "<json string>" }` (verified shape). `call_id` is what you echo back; `id` is the item id.
++- Result item: `{ type: "function_call_output", call_id, output: string | [content parts for images/files] }` (SDK 7.7 made the `id` optional).
++- `tool_choice`: `"auto"` (default) | `"none"` | `"required"` | `{type:"function", name}` | `{type:"allowed_tools", mode:"auto"|"required", tools:[...]}`.
++- `parallel_tool_calls` default true.
++- Other tool types accepted in `tools[]`: `web_search` (and legacy `web_search_preview`), `file_search`, `code_interpreter`, `image_generation`, `mcp`, `computer` / `computer_use_preview`, `shell`, `local_shell`, `apply_patch`, `custom` (free-form text tool), `namespace` (grouping, `defer_loading`), `tool_search`, `programmatic_tool_calling`.
++
++Sources: https://developers.openai.com/api/docs/guides/function-calling , https://developers.openai.com/api/docs/guides/tools
++
++## 6. Structured output / JSON schema
++
++- `text: { format: { type: "json_schema", name, schema, strict: true } }` - verified on gpt-5.5, gpt-5.4-mini, gpt-5.6-sol, gpt-6-astra, gpt-4.1-mini (parsed `{name:"Marie Curie",age:66,city:"Paris"}`); o4-mini accepted it but ran out of the 200-token budget on reasoning.
++- Schema subset: root must be `object`; every property in `required`; `additionalProperties:false`; optional fields via `type:["string","null"]`; supports `enum`, `anyOf`, `$ref`/`$defs`, recursion; no `minLength`/`pattern`/`format` etc. Numeric limits (depth/property count/enum size) exist but the page did not expose them - keep schemas modest.
++- Refusals arrive as a `refusal` content part (`response.refusal.delta/done`) instead of JSON.
++- `{type:"json_object"}` (JSON mode) is the fallback for gpt-4 / gpt-3.5-turbo which lack structured outputs.
++- SDK helpers: `zodTextFormat(schema, "name")` + `client.responses.parse(...)` -> `response.output_parsed`.
++
++Source: https://developers.openai.com/api/docs/guides/structured-outputs
++
++## 7. Reasoning controls
++
++- `reasoning.effort` values in the SDK enum: `none | minimal | low | medium | high | xhigh | max`. **Per-model acceptance (verified, exact error strings in section 20):**
++  - gpt-6-astra: `low, medium, high, xhigh, max` (default `medium`; `none`/`minimal` -> 400)
++  - gpt-5.6-sol/terra/luna: `none, low, medium, high, xhigh, max` (default `medium`)
++  - gpt-5.5: `none, low, medium, high, xhigh` (default `medium`)
++  - gpt-5.4 / 5.4-mini / 5.4-nano, gpt-5.2: `none, low, medium, high, xhigh` (default **`none`** - verified echo)
++  - gpt-5.1: `none, low, medium, high` (default `none`)
++  - gpt-5 / 5-mini / 5-nano: `minimal, low, medium, high` (default `medium`; no `none`)
++  - o3, o4-mini, o3-mini, o1: `low, medium, high` (default `medium`)
++  - pro models: 5.5-pro `medium|high|xhigh` (default high), 5.4-pro / 5.2-pro `medium|high|xhigh`, gpt-5-pro `high` only
++  - gpt-4.1 / gpt-4o / chat-latest: `reasoning.effort` -> `400 unsupported_parameter`
++- `reasoning.summary`: `auto | concise | detailed` (server echoes `detailed` for `auto`). Summary text arrives in `reasoning` items' `summary[]` and via `response.reasoning_summary_*` events; gpt-5.5 and gpt-6-astra returned no summary on a trivial prompt while gpt-5.6-sol and o4-mini did. Never assume a summary will exist. Non-reasoning models silently ignore `summary`.
++- `reasoning.mode`: `standard | pro` (GPT-5.6; pro replaces the `*-pro` models). Not probed (cost).
++- `reasoning.context`: `current_turn | all_turns` (`all_turns` is the default on 5.6 and 6; earlier models default `current_turn`). Reasoning persists only within a family.
++- Reasoning tokens are billed as output and count against `max_output_tokens`; `usage.output_tokens_details.reasoning_tokens` reports them. Docs recommend reserving >= 25k tokens; with tiny caps, o4-mini / gpt-5-nano return `status:"incomplete", incomplete_details.reason:"max_output_tokens"` with an empty message (verified). **Adapter rule: never cap reasoning models below ~1-2k output tokens; treat `incomplete` + empty text as "reasoning exhausted the budget".**
++- Encrypted reasoning for stateless (store:false) multi-turn: `store:false, include:["reasoning.encrypted_content"]` -> `reasoning` items carry `encrypted_content` (~1.2 kB for a trivial turn); replaying them in the next `input` works (verified on gpt-5.5). `previous_response_id` on a `store:false` response fails: `400 previous_response_not_found`.
++- GPT-6 Astra: mid-conversation `configuration_update` items to change effort; async tool calling (`async:true`); no `none` effort.
++
++Sources: https://developers.openai.com/api/docs/guides/reasoning , https://developers.openai.com/api/docs/guides/latest-model
++
++## 8. Sampling parameter support matrix (Responses API, verified 2026-09-08)
++
++| Param | gpt-6-astra | gpt-5.6-sol | gpt-5.5 | gpt-5.4-mini (default effort none) | gpt-4.1-mini | o4-mini |
++|---|---|---|---|---|---|---|
++| `temperature` | rejected | rejected unless `effort:"none"` (then accepted) | rejected unless `effort:"none"` | accepted | accepted | rejected |
++| `top_p` | rejected | same as temperature | same | accepted | accepted | rejected |
++| `frequency_penalty` | rejected | rejected (effort medium) | rejected | accepted | accepted | rejected |
++| `presence_penalty` | rejected | rejected | rejected | accepted | accepted | rejected |
++| `seed` | `unknown_parameter` on every model (does not exist in Responses) | | | | | |
++| `stop` | `unknown_parameter` on every model ("Did you mean 'store'?") | | | | | |
++| logprobs (`top_logprobs`+include) | rejected (reasoning) | rejected | rejected | accepted (`logprobs[]` on content part) | accepted | rejected |
++| `reasoning.effort` | low..max | none..max | none..xhigh | none..xhigh | rejected | low..high |
++| `reasoning.summary` | accepted | accepted | accepted | accepted | ignored (no error) | accepted |
++| `text.verbosity: "low"` | accepted | accepted | accepted | accepted | rejected (`Supported values are: 'medium'`) | rejected |
++| `max_output_tokens` | min 16 on all (`integer_below_min_value`) | | | | | |
++| `truncation:"auto"` | accepted on all | | | | | |
++| `store:false` + `include:["reasoning.encrypted_content"]` | accepted on all (non-reasoning models just have no reasoning item) | | | | | |
++| `prompt_cache_key` | accepted on all | | | | | |
++
++Default `top_p` echoed by GPT-5.x/6 is `0.98`, by GPT-4.1 `1`. `temperature` default 1. `top_k` does not exist. There is no thinking *budget* parameter (effort only). Chat Completions on gpt-5.5: `temperature:0.3` -> `400 unsupported_value "'temperature' does not support 0.3 with this model. Only the default (1) value is supported."`
++
++Practical rule for the adapter: send sampling params only when (model is non-reasoning) or (reasoning-capable model with `reasoning.effort === "none"`); otherwise drop them client-side and show "not supported" in the UI. Never send `seed`/`stop` to Responses.
++
++## 9. Roles and instructions
++
++Input roles accepted: `user`, `assistant`, `developer`, `system` (both `system` and `developer` verified on gpt-5.5 and gpt-4.1-mini; docs describe `developer` as the canonical name and treat `instructions` as equivalent to a developer message). `instructions` is not inherited through `previous_response_id`; resend it each call. Content parts: `input_text`, `input_image`, `input_file`, (`input_audio` rejected, see 10); assistant output parts: `output_text`, `refusal`.
++
++Source: https://developers.openai.com/api/docs/guides/text
++
++## 10. Modalities
++
++| Modality | Responses API support | Notes |
++|---|---|---|
++| Text in/out | yes | |
++| Image in | yes on every current model except `o3-mini`, `gpt-4`, `gpt-3.5-turbo` | `{type:"input_image", image_url:"data:image/png;base64,..." \| https URL \| file_id, detail:"low"\|"high"\|"auto"\|"original"}`. PNG/JPEG/WEBP/non-animated GIF; <= 512 MB per request, <= 1,500 images, <= 30,000 patches after resize. Tokens ~ `ceil(w/32)*ceil(h/32)` x model multiplier (1.2-2.46). Verified with a 2x2 PNG on all six probe models (31-33 input tokens). |
++| PDF / file in | yes (vision models) | `{type:"input_file", filename, file_data:"data:application/pdf;base64,..." \| file_id \| file_url}`; <= 50 MB per file and per request; both text and page images are sent (costly). Verified on gpt-5.4-mini (answered `42` from the PDF). |
++| Image out | via tool only | `tools:[{type:"image_generation"}]` uses `gpt-image-2`; returns base64 in an `image_generation_call` item; events `response.image_generation_call.partial_image`. Not probed. Older gpt-image-1* shut down 2026-10-23 / 2026-12-01. |
++| Audio in/out | **no** in Responses | probe: `400 invalid_request_error param=input "Audio input is not available."`. Audio chat = Chat Completions with `gpt-audio-1.5` (`input_audio` parts, `modalities:["text","audio"]`) or Realtime (`gpt-realtime-2.1`). TTS: `gpt-4o-mini-tts`; STT: `gpt-transcribe`, `gpt-live-transcribe` (whisper-1/gpt-4o-transcribe shut down 2027-02-26). |
++| Video | no | Sora 2 / Videos API shut down 2026-09-24. |
++
++Sources: https://developers.openai.com/api/docs/guides/images-vision , https://developers.openai.com/api/docs/guides/pdf-files , https://developers.openai.com/api/docs/guides/audio
++
++## 11. Context windows, max output, pricing (per 1M tokens, USD, standard tier)
++
++| Model | Context | Max output | Input | Cached | Output | Notes |
++|---|---|---|---|---|---|---|
++| gpt-6-astra | 1,050,000 | 128,000 | 10 | 1 | 50 | cache write 12.50; >272K input: 2x in / 1.5x out |
++| gpt-5.6-sol (`gpt-5.6`) | 1,050,000 | 128,000 | 4 | 0.40 | 20 | |
++| gpt-5.6-terra | 1,050,000 (922K input) | 128,000 | 2 | 0.20 | 12 | |
++| gpt-5.6-luna | 1,050,000 | 128,000 | 0.20 | 0.02 | 1.20 | |
++| gpt-5.5 | 1,050,000 | 128,000 | 5 | 0.50 | 30 | >272K: 2x/1.5x |
++| gpt-5.5-pro | 1,050,000 | 128,000 | 30 | - | 180 | Responses only |
++| gpt-5.4 | 1,050,000 | 128,000 | 2.50 | 0.25 | 15 | |
++| gpt-5.4-mini | 400,000 | 128,000 | 0.75 | 0.075 | 4.50 | |
++| gpt-5.4-nano | 400,000 | 128,000 | 0.20 | 0.02 | 1.25 | |
++| gpt-5.4-pro | 1,050,000 | 128,000 | 30 | - | 180 | Responses only |
++| gpt-5.3-codex | 400,000 | 128,000 | 1.75 | 0.175 | 14 | Responses only, coding |
++| gpt-5.2 | 400,000 | 128,000 | 1.75 | 0.175 | 14 | |
++| gpt-5.2-pro | 400,000 | 128,000 | 21 | - | 168 | Responses only |
++| gpt-5.1 | 400,000 | 128,000 | 1.25 | 0.125 | 10 | |
++| gpt-5 | 400,000 | 128,000 | 1.25 | 0.125 | 10 | snapshot shuts down 2026-12-11 |
++| gpt-5-mini | 400,000 | 128,000 | 0.25 | 0.025 | 2 | snapshot shuts down 2026-12-11 |
++| gpt-5-nano | 400,000 | 128,000 | 0.05 | 0.005 | 0.40 | snapshot shuts down 2026-12-11 |
++| gpt-5-pro | 400,000 | 272,000 | 15 | - | 120 | Responses only |
++| chat-latest | 400,000 (272K input) | 128,000 | 5 | 0.50 | 30 | ChatGPT Instant, non-reasoning |
++| gpt-4.1 | 1,047,576 | 32,768 | 2 | 0.50 | 8 | |
++| gpt-4.1-mini | 1,047,576 | 32,768 | 0.40 | 0.10 | 1.60 | |
++| gpt-4.1-nano | 1,047,576 | 32,768 | 0.10 | 0.025 | 0.40 | shuts down 2026-10-23 |
++| gpt-4o | 128,000 | 16,384 | 2.50 | 1.25 | 10 | alias -> 2024-08-06 |
++| gpt-4o-mini | 128,000 | 16,384 | 0.15 | 0.075 | 0.60 | |
++| o3 | 200,000 | 100,000 | 2 | 0.50 | 8 | snapshot shuts down 2026-12-11 |
++| o3-pro | 200,000 | 100,000 | 20 | - | 80 | Responses only |
++| o4-mini | 200,000 | 100,000 | 1.10 | 0.275 | 4.40 | shuts down 2026-10-23 |
++| o3-mini | 200,000 | 100,000 | 1.10 | 0.55 | 4.40 | text only; shuts down 2026-10-23 |
++| o1 | 200,000 | 100,000 | 15 | 7.50 | 60 | shuts down 2026-10-23 |
++| o1-pro | 200,000 | 100,000 | 150 | - | 600 | shuts down 2026-10-23 |
++| gpt-4-turbo | 128,000 | 4,096 | 10 | - | 30 | shuts down 2026-10-23 |
++| gpt-4 | 8,192 | 8,192 | 30 | - | 60 | shuts down 2026-10-23 |
++| gpt-3.5-turbo | 16,385 | 4,096 | 0.50 | - | 1.50 | shuts down 2026-10-23 |
++
++Tiers: Batch and Flex = ~50% of standard; Priority higher; Fast = 2x (not for gpt-6-astra with EU residency). Regional data residency +10% for models released after 2026-03-05. Tools: web search $10 / 1k calls (+ tokens), file search $2.50 / 1k calls + $0.10/GB/day storage (1 GB free), code interpreter $0.03-$1.92 per 20-min session by memory tier, MCP = tokens only. Unknown for this key: `gpt-5-search-api`, `gpt-4o-mini-search-preview`, the dead codex snapshots (set to `null` in the JSON).
++
++Sources: per-model pages under https://developers.openai.com/api/docs/models/<id> , https://developers.openai.com/api/docs/pricing
++
++## 12. Prompt caching
++
++Automatic prefix caching; minimum cacheable prefix 1,024 tokens (GPT-5.6+) / 2,048 (earlier). Reads at the "cached" price (0.1x on 5.6+, 0.5x on gpt-4o/o3-mini/o1); GPT-5.6+ also bill **cache writes at 1.25x** (reported in `usage.input_tokens_details.cache_write_tokens`, present in every usage object we saw). `prompt_cache_key` (routing hint, accepted on every model) ; `prompt_cache_retention: "in_memory" | "24h"` for pre-5.6 models (accepted on gpt-5.5 and even gpt-6-astra, but docs say it is deprecated for 6 -> use `prompt_cache_options: { ttl: "30m" }`, verified accepted on gpt-5.6-sol, echoed `{mode:"implicit", ttl:"30m"}`). `cached_tokens` is exact on 5.6+, rounded to 128 earlier. Cache lifetime 5-10 min (up to 1 h) or 24 h; not shared across orgs.
++
++Source: https://developers.openai.com/api/docs/guides/prompt-caching
++
++## 13. Rate limits, headers, retries, timeouts
++
++- Dimensions: RPM, TPM, RPD, TPD, IPM (+ audio minutes). Tiers Free..Tier 5 by cumulative spend; this key is Tier 5 (headers show 15,000 RPM / 40M TPM on gpt-5.5, 30,000 RPM / 150M TPM on gpt-4.1-mini).
++- Headers (verified on every 200): `x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests`, `x-ratelimit-reset-requests` (e.g. `4ms`, `6m0s`), `x-ratelimit-limit-tokens`, `x-ratelimit-remaining-tokens`, `x-ratelimit-reset-tokens`; docs also list `x-ratelimit-limit-project-tokens` / `x-ratelimit-remaining-project-tokens` and `Retry-After` (seconds) on 429/503. Also `x-request-id` and `openai-processing-ms`.
++- 429 codes: `rate_limit_exceeded`, `slow_down` (traffic ramped too fast), `insufficient_quota` / `credit_balance_exhausted`, `organization_spend_limit_exceeded`, `project_spend_limit_exceeded`, `organization_usage_limit_exceeded`. 503 `server_is_overloaded`. Billing/quota 429s must **not** be retried.
++- Retry guidance: honour `Retry-After` when present, else exponential backoff with jitter; ramp traffic <= +50% per 15 min above 1M TPM. SDK default: `maxRetries: 2`, retries 408/409/429/>=500 and any response with `x-should-retry: true`, honours `retry-after-ms` / `retry-after`, backoff 0.5 s x 2^n capped at 8 s with up to 25% jitter. For a BYOK chat UI use `maxRetries: 1-2` for non-streaming, and do not retry once streaming has begun.
++- Timeouts: SDK default 10 minutes (`OpenAI.DEFAULT_TIMEOUT = 600000`). Recommend: 60 s connect/first-byte for chat, overall 5-10 min for high/xhigh/max effort, and `background: true` (+ polling / resumable stream) for pro models and anything expected to run > 1-2 min. Docs: streaming is "the single most effective approach" to perceived latency; `service_tier: "priority" | "fast"` buys lower latency at higher price (`flex` accepted on gpt-5.4-mini: slower, cheaper).
++
++Sources: https://developers.openai.com/api/docs/guides/rate-limits , https://developers.openai.com/api/docs/guides/error-codes , https://developers.openai.com/api/docs/guides/latency-optimization , SDK `client.js`
++
++## 14. Error schema
++
++HTTP body: `{ "error": { "message", "type", "param", "code" } }` (raw fetch with a bad key also returned a top-level `"status": 401`). SDK maps to `BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `RateLimitError` (429), `InternalServerError` (>=500), `APIConnectionError`, `APITimeoutError`; each exposes `.status`, `.code`, `.type`, `.param`, `.requestID`, `.headers`, `.error` (raw body).
++
++Verified examples:
++
++| Case | Status | `type` | `code` | `param` | `message` |
++|---|---|---|---|---|---|
++| invalid key | 401 | invalid_request_error | `invalid_api_key` | null | `Incorrect API key provided: sk-inva*****key. You can find your API key at https://platform.openai.com/account/api-keys.` |
++| unknown model | 404 | invalid_request_error | `model_not_found` | null | ``The model `gpt-does-not-exist` does not exist or you do not have access to it.`` |
++| CC-only model on Responses | 400 | invalid_request_error | `model_not_found` | model | `The requested model 'gpt-5-search-api' is not supported with the Responses API.` |
++| wrong type | 400 | invalid_request_error | `invalid_type` | max_output_tokens | `Invalid type for 'max_output_tokens': expected an integer, but got a string instead.` |
++| below min | 400 | invalid_request_error | `integer_below_min_value` | max_output_tokens | `Invalid 'max_output_tokens': integer below minimum value. Expected a value >= 16, but got 5 instead.` |
++| unsupported param | 400 | invalid_request_error | **null** | temperature | `Unsupported parameter: 'temperature' is not supported with this model.` |
++| unsupported param | 400 | invalid_request_error | `unsupported_parameter` | reasoning.effort | `Unsupported parameter: 'reasoning.effort' is not supported with this model.` |
++| unsupported value | 400 | invalid_request_error | `unsupported_value` | reasoning.effort | `Unsupported value: 'minimal' is not supported with the 'gpt-5.5' model. Supported values are: 'none', 'low', 'medium', 'high', and 'xhigh'.` |
++| unknown param | 400 | invalid_request_error | `unknown_parameter` | stop | `Unknown parameter: 'stop'. Did you mean 'store'?` |
++| logprobs on reasoning | 400 | invalid_request_error | `unsupported_parameter` | - | `logprobs are not supported with reasoning models.` |
++| prev response gone | 400 | invalid_request_error | `previous_response_not_found` | previous_response_id | `Previous response with id 'resp_...' not found.` |
++| audio in Responses | 400 | invalid_request_error | null | input | `Audio input is not available.` |
++
++Note `code` is sometimes null for "Unsupported parameter" errors; match on `param` + message prefix as well. Other documented codes: `context_length_exceeded`, `invalid_service_tier`, `insufficient_quota`, `rate_limit_exceeded`, `slow_down`, `server_is_overloaded`.
++
++## 15. Usage reporting and token counting
++
++- Every response (and `response.completed`) has `usage: { input_tokens, input_tokens_details: { cached_tokens, cache_write_tokens }, output_tokens, output_tokens_details: { reasoning_tokens }, total_tokens }`. Web search inflates `input_tokens` heavily (4.7k-8.8k for a one-line question) because search results are injected as context and billed as input.
++- Chat Completions usage: `prompt_tokens`, `completion_tokens`, `total_tokens`, `prompt_tokens_details {cached_tokens, audio_tokens}`, `completion_tokens_details {reasoning_tokens, audio_tokens, accepted_prediction_tokens, rejected_prediction_tokens}`; streaming needs `stream_options: {include_usage: true}` (usage arrives in a final chunk with empty `choices`).
++- Pre-flight counting: `POST /v1/responses/input_tokens` (`{model, input, instructions?, tools?, conversation?, previous_response_id?}` -> `{object:"response.input_tokens", input_tokens}`); SDK: `client.responses.inputTokens.count(...)`. Client-side: `tiktoken` / `js-tiktoken` with `o200k_base` for gpt-4o and newer (approximation only for images/PDF). Rule of thumb 1 token ~ 4 chars English.
++- SDK 7.8 added `compute_units` tracking on usage for some tiers (not observed in our responses).
++
++Source: https://developers.openai.com/api/docs/api-reference/responses/input-tokens
++
++## 16. Model listing
++
++`GET /v1/models` (SDK `client.models.list()` auto-paginates) returns `{id, object:"model", created, owned_by, shutdown_date}`. **`shutdown_date` is the only lifecycle signal** (ISO date or null; documented as "The date when the model will shut down, or null if not announced"). No capability, context or pricing metadata is exposed, so a static registry is mandatory (`openai.models.json`). 131 ids were returned for this key on 2026-09-08; 55 carried a `shutdown_date`, several already in the past (see 18). Filtering heuristics for chat models: exclude ids matching `babbage|davinci|instruct|transcribe|tts|whisper|audio|realtime|image|sora|embedding|moderation|search-preview|search-api|deep-research|codex` and anything whose `shutdown_date < today`; keep the rest and look it up in the registry (unknown ids -> show as "unverified").
++
++Source: https://developers.openai.com/api/docs/api-reference/models
++
++## 17. Aliases
++
++- `gpt-5.6` -> `gpt-5.6-sol` (documented; verified `response.model === "gpt-5.6-sol"`; **not** itself listed by `/v1/models`).
++- `gpt-5.5` -> `gpt-5.5-2026-04-23`; `gpt-5.4` -> `-2026-03-05`; `gpt-5.4-mini`/`-nano` -> `-2026-03-17`; `gpt-5.2` -> `-2025-12-11`; `gpt-5.1` -> `-2025-11-13`; `gpt-5*` -> `-2025-08-07`; `gpt-4.1*` -> `-2025-04-14`; `gpt-4o` -> `-2024-08-06` (not the newest 11-20 snapshot); `gpt-4o-mini` -> `-2024-07-18`; `o3` -> `-2025-04-16`; `o4-mini` -> `-2025-04-16`; `o3-mini` -> `-2025-01-31`; `gpt-4-turbo` -> `-2024-04-09`; `gpt-3.5-turbo` -> `-0125`. `gpt-6-astra`, `gpt-5.6-*`, `gpt-5.3-codex`, `chat-latest` have no dated snapshot (echoed as-is).
++- `*-chat-latest` aliases (gpt-5 / 5.1 / 5.2 / 5.3) are **dead** (404) although still listed; `chat-latest` is the live ChatGPT-Instant alias.
++
++## 18. Lifecycle / deprecations relevant to a chat app
++
++| Shutdown | Models | Replacement |
++|---|---|---|
++| 2026-07-23 (passed; 404 today) | gpt-5-chat-latest, gpt-5.1-chat-latest, gpt-5-codex, gpt-5.1-codex(-max/-mini), gpt-5.2-codex, o3-deep-research, o4-mini-deep-research, *-search-preview-2025-03-11 snapshots | gpt-6-astra / gpt-5.3-codex |
++| 2026-08-10 (passed; 404) | gpt-5.2-chat-latest, gpt-5.3-chat-latest | chat-latest / gpt-6-astra |
++| 2026-08-26 | Assistants API | Responses + Conversations |
++| 2026-09-24 | sora-2, sora-2-pro, Videos API | - |
++| 2026-09-28 | gpt-3.5-turbo-1106, gpt-3.5-turbo-instruct, babbage-002, davinci-002 | gpt-5.6-terra |
++| 2026-10-23 | gpt-3.5-turbo(-0125), gpt-4(-0613), gpt-4-turbo, gpt-4.1-nano, gpt-4o-2024-05-13, gpt-image-1, o1, o1-pro, o3-mini, o4-mini | gpt-5.6-sol / terra / luna (o1-pro -> 5.6-sol `reasoning.mode: pro`) |
++| 2026-11-30 | v1/prompts, Evals, Agent Builder | - |
++| 2026-12-01 | gpt-image-1-mini, gpt-image-1.5, chatgpt-image-latest | gpt-image-2 |
++| 2026-12-11 | gpt-5-2025-08-07, gpt-5-mini-2025-08-07, gpt-5-nano-2025-08-07, gpt-5-pro-2025-10-06, o3-2025-04-16, o3-pro-2025-06-10 (the bare aliases `gpt-5`, `o3` currently have `shutdown_date: null`) | gpt-5.6-sol / terra / luna |
++| 2027-01-20 / 2027-02-26 | legacy audio/realtime/transcribe models | gpt-audio-1.5, gpt-realtime-2.1, gpt-transcribe |
++
++Fine-tuning: closed to new orgs since 2026-05-07; no new jobs at all after 2027-01-06.
++
++Source: https://developers.openai.com/api/docs/deprecations + `shutdown_date` from `/v1/models`
++
++## 19. Built-in tools, state, safety
++
++- **Conversation state**: `store` defaults to **true** (30-day retention, visible in dashboard logs) - set `store:false` for privacy-minded BYOK usage and manage history client-side; then use `include:["reasoning.encrypted_content"]` and replay all output items. `previous_response_id` (verified) and `conversation` (Conversations API, `conv_...`, not subject to 30-day TTL) require `store:true`. Server-side compaction: `context_management:[{type:"compaction", compact_threshold}]`.
++- **Web search**: `{type:"web_search", search_context_size?:"low"|"medium"|"high", user_location?:{type:"approximate", country, city, region, timezone}, filters?:{allowed_domains[] | blocked_domains[]} (<=100), external_web_access?, search_content_types?:["text","image"], return_token_budget?}` (legacy `web_search_preview` still accepted). Output: `web_search_call` items (`action: {type:"search", queries[], query} | {type:"open_page", url} | {type:"find_in_page"}`) then a `message` whose `output_text` part has `annotations: [{type:"url_citation", start_index, end_index, url, title}]` and inline markdown links with `?utm_source=openai`. Events: `response.web_search_call.{in_progress,searching,completed}`, `response.output_text.annotation.added`. Verified on gpt-4.1-mini and gpt-5.5 (effort low); the gpt-5.5 default-effort attempt at 200 tokens ended with three searches and no message - budget again. Search context capped at 128k. Supported per docs on gpt-6, 5.6, 5.5, 5.4 family, 5.2, 5.1, 5(-mini/-nano), 4.1(-mini), 4o(-mini), o3, o4-mini, chat-latest; not on gpt-4.1-nano, o3-mini, o1, gpt-4, gpt-3.5.
++- **Code execution**: `{type:"code_interpreter", container: {type:"auto", memory_limit?:"1g"|"4g"|"16g"|"64g", file_ids?} | "cntr_..."}` -> `code_interpreter_call {code, outputs, container_id}`; generated files as `container_file_citation` annotations; 100 RPM/org; events `response.code_interpreter_call*`. Also `shell` (hosted shell), `local_shell`, `apply_patch`, skills.
++- **File search**: `{type:"file_search", vector_store_ids[], max_num_results?, filters?, ranking_options?}` -> `file_search_call` + `file_citation {file_id, filename, index}` annotations; `include:["file_search_call.results"]`.
++- **Computer use**: `{type:"computer"}` (new) or `computer_use_preview {display_width, display_height, environment}`; `computer_call` -> reply with `computer_call_output {call_id, output:{type:"computer_screenshot", image_url}}`; docs recommend GPT-6 Astra with code execution instead. Not relevant for PolyLLM v1.
++- **MCP**: `{type:"mcp", server_label, server_url | connector_id, server_description?, authorization?, headers?, allowed_tools?, require_approval:"never"|"always"|{...}, defer_loading?}` -> `mcp_list_tools`, `mcp_call`, `mcp_approval_request` (answer with `mcp_approval_response {approval_request_id, approve}`); events `response.mcp_call*`, `response.mcp_list_tools*`. Billing = tokens only. 8 first-party connectors (Gmail, Drive, Calendar, Dropbox, Teams, Outlook x2, SharePoint).
++- **Citations/annotations**: `url_citation`, `file_citation`, `container_file_citation`, `file_path` types on `output_text.annotations[]`; streamed through `response.output_text.annotation.added`.
++- **Safety**: send `safety_identifier` (hashed user id) on every request; `incomplete_details.reason:"content_filter"` and `refusal` parts must be surfaced; free Moderation API (`omni-moderation-latest`) available; revoke leaked keys immediately. `moderation` request param exists in the SDK types.
++
++Sources: https://developers.openai.com/api/docs/guides/conversation-state , https://developers.openai.com/api/docs/guides/tools-web-search , https://developers.openai.com/api/docs/guides/tools-code-interpreter , https://developers.openai.com/api/docs/guides/tools-file-search , https://developers.openai.com/api/docs/guides/tools-computer-use , https://developers.openai.com/api/docs/guides/tools-remote-mcp , https://developers.openai.com/api/docs/guides/safety-best-practices
++
++## 20. Probe results (2026-09-08, key = Tier 5 project key)
++
++Legend: OK = completed with expected output; INC = accepted but `status:"incomplete"` (reasoning consumed the <= 200-token cap); 4xx = rejected with the quoted message.
++
++| Probe | gpt-5.5 | gpt-5.4-mini | gpt-5.6-sol | gpt-6-astra | gpt-4.1-mini | o4-mini |
++|---|---|---|---|---|---|---|
++| (a) basic Responses, 200 tok | OK (`gpt-5.5-2026-04-23`, 12 reasoning tok) | OK (0 reasoning) | OK (0 reasoning) | OK (0 reasoning) | OK | OK (64 reasoning) |
++| (b) streaming events | OK, reasoning item but no summary events | OK | OK, `reasoning_summary_*` events seen | OK, no summary events | OK | INC: summary events, then `response.incomplete` |
++| (c) temperature / top_p | 400 `Unsupported parameter: 'temperature' is not supported with this model.` (OK with `effort:"none"`) | OK (echo 0.5) | 400 same (OK with `effort:"none"`) | 400 same; `effort:"none"` itself rejected | OK | 400 same |
++| (c) frequency/presence_penalty | 400 `Unsupported parameter: 'frequency_penalty' is not supported with this model.` | OK | 400 | 400 | OK | 400 |
++| (c) seed | 400 `unknown_parameter` `Unknown parameter: 'seed'.` (all models) | | | | | |
++| (c) stop | 400 `unknown_parameter` `Unknown parameter: 'stop'. Did you mean 'store'?` (all models) | | | | | |
++| (c) logprobs | 400 `logprobs are not supported with reasoning models.` | OK | 400 | 400 | OK | 400 |
++| (c) effort none | OK | OK | OK | 400 `Unsupported value: 'none' is not supported with the 'gpt-6-astra' model. Supported values are: 'low', 'medium', 'high', 'xhigh', and 'max'.` | 400 `Unsupported parameter: 'reasoning.effort' is not supported with this model.` | 400 `Supported values are: 'low', 'medium', and 'high'.` |
++| (c) effort minimal | 400 `... Supported values are: 'none', 'low', 'medium', 'high', and 'xhigh'.` | 400 same | 400 `... 'none', 'low', 'medium', 'high', 'xhigh', and 'max'.` | 400 | 400 | 400 |
++| (c) effort low/medium/high | OK | OK | OK | OK | 400 | OK |
++| (c) effort xhigh | OK | OK | OK | OK | 400 | 400 |
++| (c) effort max | 400 | 400 | OK | OK | 400 | 400 |
++| (c) reasoning.summary auto | OK (echo `detailed`) | OK | OK | OK | OK (ignored) | OK |
++| (c) text.verbosity low | OK | OK | OK | OK | 400 `Unsupported value: 'low' is not supported with the 'gpt-4.1-mini' model. Supported values are: 'medium'.` | 400 same wording |
++| (c) max_output_tokens 5 | 400 `integer_below_min_value` `Expected a value >= 16, but got 5 instead.` (all) | | | | | |
++| (c) truncation auto, prompt_cache_key, store:false+encrypted | OK on all six | | | | | |
++| (d) function call, streaming | OK: `function_call` item, args `{"city":"Paris","unit":"c"}`, round trip -> "18°C and cloudy" | OK (+ `previous_response_id` variant OK) | OK | OK | OK | INC (192 reasoning tokens, no call) |
++| (e) json_schema strict | OK parsed | OK | OK | OK | OK | INC |
++| (f) vision 2x2 PNG | INC at default effort; OK with `effort:"none"` | OK | INC default; OK with `effort:"none"` | OK (`effort:"low"`, detail high) | OK | INC (even at `effort:"low"`) |
++| (h) web_search tool | OK with `effort:"low"`: `web_search_call` + `url_citation` annotation; default effort at 200 tok: 3 searches, no message | OK (3 searches + message, no citation) | not probed | not probed | OK with citation | not probed |
++| (i) Chat Completions | `temperature:0.3` -> 400 `Only the default (1) value is supported`; `reasoning_effort`+`verbosity` OK | - | - | `max_tokens` -> 400 `Use 'max_completion_tokens' instead.` | OK streaming, usage in last chunk | OK streaming |
++| (g) invalid key | 401 `invalid_api_key` (`AuthenticationError`) - see section 14 | | | | | |
++
++Other probes: `gpt-5.6` alias OK; 26-model sweep OK except `gpt-5.3-chat-latest` (404); `gpt-5-nano` INC at default effort; `o1` INC at 32 tokens; `gpt-5.5-pro` OK (7.3 s, "pong"); `gpt-4.1-nano`, `gpt-4-turbo`, `gpt-3.5-turbo`, `o3-mini` still answer despite announced shutdowns; `gpt-5-search-api` works only via `chat.completions`; PDF input OK on gpt-5.4-mini; `previous_response_id` OK (remembered "7"); `service_tier:"flex"` OK; `input_audio` -> 400 `Audio input is not available.`; `prompt_cache_options.ttl:"30m"` OK on gpt-5.6-sol.
++
++## 21. Adapter recommendations (summary)
++
++1. Responses API only; Chat Completions merely as an optional legacy toggle (needed for `gpt-audio-*`, `*-search-*`).
++2. Registry-driven parameter gating: sampling params allowed iff model is non-reasoning or `effort === "none"`; never send `seed`/`stop`; `max_output_tokens >= 16` and default it high (>= 4k) for reasoning models; effort dropdown filtered per model (`reasoningEfforts` in the JSON).
++3. Stream handler keyed on `event.type`; treat `response.incomplete` as a normal terminal event (show partial text + "reasoning exhausted budget" hint when `reason === "max_output_tokens"` and no text).
++4. Default `store:false` + `include:["reasoning.encrypted_content"]`, replay full `output` items each turn; offer `previous_response_id` mode only when the user opts into server-side storage.
++5. Persist `usage` (incl. `cached_tokens`, `cache_write_tokens`, `reasoning_tokens`) per message and price with the registry table; web-search turns cost 5-9k input tokens.
++6. Model list = `GET /v1/models` filtered by regex + `shutdown_date`, then joined with `openai.models.json`; show shutdown badges for dates < 90 days away.
++7. Errors: map on `status` + `code` + `param`; `code` can be null for "Unsupported parameter" - fall back to message prefix; never retry 401/400/quota-429.

added docs/provider-research/openai.models.json +4472 −0

Large diff (4,472 lines) is not loaded by default to keep the page fast.Load diff

added docs/provider-research/xai.md +280 −0

Large diff (280 lines) is not loaded by default to keep the page fast.Load diff

added docs/provider-research/xai.models.json +356 −0

Large diff (356 lines) is not loaded by default to keep the page fast.Load diff

added docs/provider-test-matrix.md +34 −0

Large diff (34 lines) is not loaded by default to keep the page fast.Load diff

added drizzle.config.ts +10 −0

Large diff (10 lines) is not loaded by default to keep the page fast.Load diff

added drizzle/0000_foamy_loners.sql +370 −0

Large diff (371 lines) is not loaded by default to keep the page fast.Load diff

added drizzle/meta/0000_snapshot.json +2748 −0

Large diff (2,749 lines) is not loaded by default to keep the page fast.Load diff

added drizzle/meta/_journal.json +13 −0

Large diff (14 lines) is not loaded by default to keep the page fast.Load diff

added e2e/full-flow.spec.ts +156 −0

Large diff (156 lines) is not loaded by default to keep the page fast.Load diff

added e2e/helpers.ts +44 −0

Large diff (44 lines) is not loaded by default to keep the page fast.Load diff

added e2e/mobile.spec.ts +12 −0

Large diff (12 lines) is not loaded by default to keep the page fast.Load diff

added eslint.config.mjs +10 −0

Large diff (10 lines) is not loaded by default to keep the page fast.Load diff

added next.config.ts +51 −0

Large diff (51 lines) is not loaded by default to keep the page fast.Load diff

added package.json +80 −0

Large diff (80 lines) is not loaded by default to keep the page fast.Load diff

added playwright.config.ts +18 −0

Large diff (18 lines) is not loaded by default to keep the page fast.Load diff

added pnpm-lock.yaml +9267 −0

Large diff (9,267 lines) is not loaded by default to keep the page fast.Load diff

added postcss.config.mjs +2 −0

Large diff (2 lines) is not loaded by default to keep the page fast.Load diff

added public/icon.svg +1 −0

Large diff (1 lines) is not loaded by default to keep the page fast.Load diff

added public/robots.txt +6 −0

Large diff (6 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/00-models-list.ts +44 −0

Large diff (44 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/01-basic-stream.ts +83 −0

Large diff (83 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/02-params.ts +68 −0

Large diff (68 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/03-tools.ts +107 −0

Large diff (107 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/04-vision.ts +36 −0

Large diff (36 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/05-errors-misc.ts +104 −0

Large diff (104 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/06-availability.ts +26 −0

Large diff (26 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/07-signature.ts +47 −0

Large diff (47 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/08-rest-sse.ts +20 −0

Large diff (20 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/lib.ts +89 −0

Large diff (89 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/package.json +24 −0

Large diff (24 lines) is not loaded by default to keep the page fast.Load diff

added research/gemini/pnpm-lock.yaml +91 −0

Large diff (91 lines) is not loaded by default to keep the page fast.Load diff

Diff truncated — file too large.

spb/polyllm

PolyLLM v0.1.0 — multi-provider BYOK AI workspace (OpenAI, Anthropic, Gemini, xAI)

Theme