1 line
35 KiB
JSON
1 line
35 KiB
JSON
{"repo": "0bserver07/chimera", "files": {"docs/mink/providers.md": {"df727d8e612a575e724132a4a0218eb9527f3c30": {"t": 1785746444.2209687, "n": 17388, "h": "02bba812f8377e84", "c": "# Providers — what mink can talk to\n\n`chimera mink` defaults to Ollama (`kimi-k2.6:cloud`, see\n`chimera/mink/cli.py:34`), but the underlying provider stack is pluggable\nthrough `chimera.providers.create_provider()`\n(`chimera/providers/factory.py:36`). Six adapters self-register at import\ntime via `_ensure_builtins_registered()`\n(`chimera/providers/registry.py:55`); a seventh (`proxy`) is registered by\n`chimera/providers/proxy.py:119`.\n\n## Built-in registry\n\n| Name | Module | Self-registers at |\n|---------------|-----------------------------------|--------------------------|\n| `anthropic` | `chimera/providers/anthropic.py` | line 437 |\n| `openai` | `chimera/providers/openai.py` | line 375 |\n| `google` | `chimera/providers/google.py` | line 165 |\n| `ollama` | `chimera/providers/ollama.py` | line 392 |\n| `compatible` | `chimera/providers/compatible.py` | line 150 |\n| `modal` | `chimera/providers/modal.py` | line 171 |\n| `proxy` | `chimera/providers/proxy.py` | line 119 |\n\n`create_provider()` picks one of these by:\n1. explicit `provider_type=`,\n2. prefix on the model name (`claude-*`, `gpt-*`, `gemini-*`, `glm-*`,\n `kimi-*`, `llama*`, `qwen*`, `mistral*`, `phi*`),\n3. `ProviderCatalog` lookup (`chimera/providers/catalog.py:79`),\n4. loose env-var fallback.\n\nSee `_infer_provider()` (`chimera/providers/factory.py:113`) for the exact\norder, including the env-var override that routes anything with\n`ANTHROPIC_BASE_URL` or `ANTHROPIC_AUTH_TOKEN` set through the Anthropic\nadapter.\n\n---\n\n## Ollama (default for mink)\n\nLocal or Ollama-Cloud models served by the `ollama` daemon. The adapter\ntalks to `/api/chat` (NOT the OpenAI-compat shim at `/v1/...`, which\nsilently drops `tool_calls` from streaming chunks; see comment at\n`chimera/providers/ollama.py:25-32`).\n\n- **Use when:** running locally for privacy, or hitting Ollama Cloud\n (`*:cloud` tags) for hosted Kimi / Qwen3 / GLM-4.6.\n- **Setup:**\n ```bash\n brew install ollama # or: curl -fsSL https://ollama.com/install.sh | sh\n ollama serve & # daemon on :11434\n ollama signin # only needed for :cloud tags\n ollama pull qwen3:32b # local fallback\n ```\n- **Auth options:** none for local; Ollama Cloud uses `ollama signin`\n (browser flow stored in the daemon, not in `~/.chimera/`).\n- **Use with mink:**\n ```bash\n chimera mink --model kimi-k2.6:cloud -p \"list files then read README.md\"\n chimera mink --model qwen3:32b -p \"explain this repo\"\n ```\n- **What's wired:** streaming yes (NDJSON over `/api/chat`,\n `chimera/providers/ollama.py:214`); tool calls yes (native\n `tool_calls` field, `chimera/providers/ollama.py:269-295`); thinking\n yes for `kimi*` only (`chimera/providers/ollama.py:50`); JSON-mode no\n on cloud Kimi (server ignores `format` field, see `quickstart.md`);\n vision varies by model (Kimi 2.6 weak); prompt caching no.\n- **Defaults:** `num_ctx=131072`, `keep_alive=\"60m\"`, `OLLAMA_HOST` env\n override, `262144` ctx auto-bumped for `kimi*` (see\n `chimera/mink/cli.py:300`).\n- **Limits:** `tool_choice=\"required\"` is silently dropped when\n `think:true` (`chimera/providers/ollama.py:103`); `:cloud` weights live\n on Moonshot/Ollama infra; first cold-start call can take 10-30s.\n\n---\n\n## Anthropic\n\nAnthropic SDK against the official `api.anthropic.com` endpoint, OR\nagainst any Anthropic-wire-compatible endpoint via `ANTHROPIC_BASE_URL`\n(GLM-4.6 via `api.z.ai`, Moonshot, Ollama's Anthropic-compat shim, etc.).\n\n- **Use when:** you have an Anthropic API key, OR you have a third-party\n provider that speaks the Anthropic Messages API.\n- **Setup:**\n ```bash\n uv sync --extra anthropic # installs the anthropic SDK\n export ANTHROPIC_API_KEY=sk-ant-...\n # OR, for an Anthropic-compat endpoint:\n export ANTHROPIC_BASE_URL=https://api.z.ai/v1/anthropic\n export ANTHROPIC_AUTH_TOKEN=...\n ```\n- **Auth options:**\n - `ANTHROPIC_API_KEY` — first-class env var\n (`chimera/providers/anthropic.py:53`)\n - `ANTHROPIC_AUTH_TOKEN` — Bearer-token alias for OAuth-issued tokens\n or third-party endpoints (same line, fallback)\n - `AuthManager.get_token(\"anthropic\")` — pulls from\n `~/.chimera/auth.json` or environment\n (`chimera/auth/manager.py:36-37`, `chimera/providers/anthropic.py:48`)\n - OAuth device or browser flow via `OAuthDeviceFlow`/`OAuthBrowserFlow`\n (`chimera/auth/oauth.py:20`, `chimera/auth/oauth.py:182`); tokens\n persist to `~/.chimera/credentials.json` (mode `0o600`,\n `chimera/auth/store.py:62`)\n- **Use with mink:**\n ```bash\n chimera mink --model claude-sonnet-4-20250514 -p \"review this PR\"\n ```\n- **What's wired:** streaming yes (`chimera/providers/anthropic.py:204`);\n tool calls yes; native async (`AsyncAnthropic`,\n `chimera/providers/anthropic.py:345`); extended thinking yes\n (`enable_thinking=True`, `chimera/providers/anthropic.py:120-125`);\n prompt caching yes (opt-in via `enable_cache=True`,\n `chimera/providers/anthropic.py:131-143`); vision yes (Claude models);\n JSON mode via tool-calling pattern.\n- **Limits:** when `enable_thinking` is on, temperature is forced to 1\n (`chimera/providers/anthropic.py:125`); `ImportError` if\n `chimera-run[anthropic]` is not installed.\n\n---\n\n## OpenAI\n\nThe official `openai` SDK against `api.openai.com`, or any\n`/v1/chat/completions` endpoint via `base_url=`.\n\n- **Use when:** GPT-4o, o1, o3, Codex, or any provider that ships an\n OpenAI-SDK-compatible endpoint and you want native streaming +\n reasoning-token tracking.\n- **Setup:**\n ```bash\n uv sync --extra openai # installs the openai SDK\n export OPENAI_API_KEY=sk-...\n ```\n- **Auth options:**\n - `OPENAI_API_KEY` (`chimera/providers/openai.py:52`)\n - `AuthManager.get_token(\"openai\")`\n (`chimera/providers/openai.py:46-50`)\n- **Use with mink:**\n ```bash\n chimera mink --model gpt-4o -p \"draft a release note\"\n chimera mink --model o3-mini -p \"prove this invariant\"\n ```\n- **What's wired:** streaming yes (`chimera/providers/openai.py:142`);\n tool calls yes (delta-accumulated by `index`,\n `chimera/providers/openai.py:174-213`); native async (`AsyncOpenAI`,\n `chimera/providers/openai.py:222`); reasoning-token tracking for o-series\n models (`chimera/providers/openai.py:96-99`); prompt-cache hit accounting\n (`chimera/providers/openai.py:100-104`); vision yes (gpt-4o); JSON mode\n yes (via standard SDK options the adapter passes through unchanged).\n- **Limits:** thinking-level enum is accepted but not forwarded — the\n provider relies on the OpenAI SDK's native reasoning behavior; no\n Anthropic-style cache control.\n\n---\n\n## OpenAI-compatible\n\nGeneric adapter for any `/v1/chat/completions` endpoint. Used by\nOpenRouter, Together, Fireworks, Groq, vLLM, SGLang, LM Studio, LiteLLM,\nAnthropic Coding API in OpenAI-compat mode, and `bedrock/`/`azure/`/etc.\ncatalog entries (`chimera/providers/catalog.py:57-76`).\n\n- **Use when:** you have an OpenAI-shaped endpoint and don't want the\n full `openai` SDK dependency.\n- **Setup:**\n ```bash\n # No extra needed — uses httpx (already a dep of mink/Ollama).\n export OPENAI_API_KEY=... # or any bearer-style token\n ```\n- **Auth options:** `OPENAI_API_KEY` env (or any token passed as\n `api_key=`); custom headers via the `headers=` constructor kwarg\n (`chimera/providers/compatible.py:29`).\n- **Use with mink:**\n ```bash\n # via the catalog (resolves base_url + api_key from env)\n chimera mink --model groq/llama-3.3-70b -p \"...\"\n chimera mink --model deepseek-chat -p \"...\"\n ```\n- **What's wired:** non-streaming `complete()` only\n (`chimera/providers/compatible.py:44`); tool calls yes; default\n ASYNC/streaming falls back to base-class wrappers (`base.py:61`,\n `base.py:107`); no thinking, no caching.\n- **Limits:** **no native streaming** — the base-class `stream()` shim\n yields the whole response as one chunk; this is fine for short\n completions but loses token-by-token feel. Use the `openai` adapter if\n you need real streaming against an OpenAI-shaped endpoint.\n\n---\n\n## Google Gemini\n\nGoogle `google-generativeai` SDK against the Gemini API.\n\n- **Use when:** you want Gemini 2.0 Flash, Gemini 1.5 Pro, etc.\n- **Setup:**\n ```bash\n uv sync --extra google # if shipped; otherwise:\n pip install google-generativeai\n export GOOGLE_API_KEY=... # or GEMINI_API_KEY\n ```\n- **Auth options:**\n - `GOOGLE_API_KEY` or `GEMINI_API_KEY`\n (`chimera/auth/manager.py:39`, `chimera/providers/google.py:45`)\n - `AuthManager.get_token(\"google\")`\n- **Use with mink:**\n ```bash\n chimera mink --model gemini-2.0-flash -p \"summarize this doc\"\n ```\n- **What's wired:** non-streaming `complete()` only; tool calls yes\n (function declarations, `chimera/providers/google.py:120`); 1M context\n windows (`chimera/providers/google.py:23-26`); system messages folded\n into the first user turn as `[System] ...`\n (`chimera/providers/google.py:101`).\n- **Limits:** **no streaming** — the base-class shim is used; no async\n override; system-prompt handling is approximate (Gemini wants a\n separate `system_instruction` field, this adapter inlines it instead);\n schema cleanup strips `$ref` / `oneOf` / `additionalProperties` etc.\n unsupported by Gemini (`chimera/providers/google.py:132-146`); thinking\n param is accepted but ignored.\n\n---\n\n## Modal\n\nModal-hosted vLLM container exposing OpenAI-shape `/v1/chat/completions`.\nThe adapter does not deploy the container — it just calls a URL you\nalready have.\n\n- **Use when:** you've deployed an open-weight model on Modal GPUs and\n want mink to drive it.\n- **Setup:**\n ```bash\n pip install modal httpx\n modal token new # browser flow\n export MODAL_TOKEN_ID=... # optional, if you want to skip browser\n export MODAL_TOKEN_SECRET=...\n # then deploy your container and capture its public URL\n ```\n- **Auth options:** `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET` env vars\n (`chimera/providers/modal.py:47-48`); per-container auth is up to your\n vLLM image.\n- **Use with mink:** not directly — `mink --model` only auto-routes to\n Ollama. Use the catalog or `create_provider()` from Python:\n ```python\n from chimera.providers import create_provider\n provider = create_provider(\n \"modal\", model=\"meta-llama/Llama-3.3-70B\",\n base_url=\"https://your-org--llm-app-serve.modal.run/v1\",\n )\n ```\n- **What's wired:** non-streaming `complete()` only; tool calls yes (via\n the OpenAI-compat shape vLLM emits).\n- **Limits:** **no streaming, no async, no thinking, no caching**;\n `base_url` is required — `_get_base_url()` raises if you forget it\n (`chimera/providers/modal.py:55`).\n\n---\n\n## Proxy\n\nHTTP relay for centralized key management, cost tracking, or running\nagents in environments without direct API egress.\n\n- **Use when:** a team wants one server holding the API keys, with mink\n clients pointing at it. The proxy translates Chimera's wire format to\n whatever upstream provider it controls.\n- **Setup:** stand up a server that exposes `POST /api/complete` (and\n optionally `/api/stream`) accepting Chimera's payload shape; see\n `chimera/providers/proxy.py:18-26` for the contract.\n- **Auth options:** Bearer token via the `api_key=` constructor arg, sent\n as `Authorization: Bearer <token>` (`chimera/providers/proxy.py:69`).\n- **Use with mink:** like Modal, only via `create_provider()` from\n Python:\n ```python\n from chimera.providers import create_provider\n provider = create_provider(\n \"proxy\",\n base_url=\"http://proxy.internal:8000\",\n api_key=\"team-token\",\n model=\"claude-sonnet-4\",\n )\n ```\n- **What's wired:** synchronous `complete()` only (uses stdlib\n `urllib.request`, no `httpx`); tool calls forwarded as plain dicts;\n thinking level forwarded as a string for the proxy to interpret\n (`chimera/providers/proxy.py:62-65`).\n- **Limits:** no streaming, no async; the proxy must report `usage`\n itself — the adapter trusts whatever JSON comes back; default\n `context_window=128000` is hardcoded (`chimera/providers/proxy.py:97`).\n\n---\n\n## Custom providers\n\nImplement `Provider` (`chimera/providers/base.py:47`) and call\n`register_provider(\"my-name\", factory)` (`chimera/providers/registry.py:14`).\nFactory signature: `factory(model=..., api_key=..., base_url=..., **kw)`.\nAfter registration, `create_provider(\"my-name\", model=...)` works\nidentically to the built-ins. Drop the factory call into your package's\n`__init__.py` so import triggers self-registration, mirroring the\nbuilt-ins (e.g. `chimera/providers/anthropic.py:436`).\n\n---\n\n## Choosing a provider\n\n| Concern | Pick |\n|-----------------|-------------------------------------------------------------------|\n| Privacy / local | `ollama` with a local model (`qwen3:32b`, `llama3.1:70b-instruct`) |\n| Lowest latency | `ollama` local on GPU; `groq/*` via `compatible` |\n| Best capability | `anthropic` (claude-sonnet/opus) or `openai` (gpt-4o, o3) |\n| Cost-sensitive | `compatible` with `deepseek-chat` or `groq/llama-3.3-70b` |\n| Vision-heavy | `anthropic` (claude-sonnet) or `openai` (gpt-4o); avoid Kimi 2.6 |\n| Long context | `google` (Gemini 1M) or `anthropic` (Claude 200k) or Kimi (262k) |\n| Tools + streaming + thinking, all in one | `anthropic` (claude with `enable_thinking=True`) |\n\n---\n\n## Mixing providers in one session\n\nTwo ways to set the model — last write wins:\n\n1. CLI flag (highest precedence): `chimera mink --model <name>`.\n2. `settings.json` `model:` key, loaded by\n `load_mink_settings()` (`chimera/mink/settings.py:274`). The CLI\n default `kimi-k2.6:cloud` is treated as \"user did not pass --model\"\n so an agent's frontmatter `model:` can override it\n (`chimera/mink/cli.py:796-801`).\n3. Env vars `ANTHROPIC_MODEL` / `OPENAI_MODEL` are picked up only when no\n `--model` and no settings model is set\n (`chimera/providers/factory.py:81-82`).\n\nA single `chimera mink` process holds one provider for the whole\nsession. To swap mid-session, exit and relaunch (or, programmatically,\nbuild a new `Agent` with `create_provider(...)`).\n\n---\n\n## Credentials directory\n\n| Path | Source | Mode |\n|-----------------------------------|---------------------------------------|---------|\n| `~/.chimera/credentials.json` | OAuth-issued tokens, refresh tokens | `0o600` |\n| `~/.chimera/auth.json` | `AuthManager.set_token()` | default |\n| `~/.chimera/sessions/*.jsonl` | Session tree per-cwd (mink REPL) | default |\n| `~/.chimera/eventlog/mink-*/` | `chimera mink -p` persisted runs | default |\n\n`CredentialStore._write` chmods to `0o600` after each save\n(`chimera/auth/store.py:62`); `auth.json` is a plain JSON file written\nby `AuthManager.set_token()` (`chimera/auth/manager.py:154`).\n\n---\n\n## Proxy mode for teams\n\nFor an org-wide gateway sitting in front of Anthropic-shaped providers:\n\n```bash\nexport ANTHROPIC_BASE_URL=http://proxy.internal:8000\nexport ANTHROPIC_AUTH_TOKEN=team-issued-jwt\nchimera mink --model claude-sonnet-4 -p \"...\"\n```\n\n`AnthropicProvider` honors both env vars\n(`chimera/providers/anthropic.py:53,58`); the proxy can be a thin pass-\nthrough, a key-rotating relay, or a budget-enforcing gatekeeper. The\ndedicated `proxy` provider (above) is the alternative when your gateway\nspeaks its own JSON shape rather than the Anthropic wire protocol.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause / fix |\n|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------|\n| `401` / `403` | Wrong key, wrong env var. Check `AuthManager.status()` or `printenv | grep -E '(ANTHROPIC|OPENAI|GOOGLE)_'`. |\n| `ImportError: pip install chimera-run[...]` | Provider's optional extra is missing. `uv sync --extra anthropic` (or `openai`, `google`). |\n| `Cannot infer provider from model name '...'` | Pass `provider_type=...` explicitly, or use a known prefix; see `_infer_provider()` for the list. |\n| Streaming hangs / first call is slow | Cloud cold start. Ollama Cloud needs `keep_alive: 60m` (mink sets this). Anthropic / OpenAI typically warm in <2s.|\n| `tool_calls` always empty on Ollama | You hit `/v1/chat/completions` instead of `/api/chat`. Set `OLLAMA_HOST` to the daemon root, not `.../v1`. |\n| `temperature must be 1 with thinking` | Anthropic extended thinking forces `temperature=1` (see `anthropic.py:125`). Drop your custom temperature. |\n| Ollama Kimi rejects `tool_choice: \"required\"` | Adapter silently drops it when `think:true` is also set (`ollama.py:103`); use `auto`/`none`. |\n| Gemini complains about `$ref` / `oneOf` | The adapter strips them (`google.py:132`); if you see it pass through, check you're hitting the right adapter. |\n"}, "5c5f66b8ec79e110a5ee89f63543c177fdda2d92": {"t": 1785764306.4382997, "n": 17388, "h": "02bba812f8377e84", "c": "# Providers — what mink can talk to\n\n`chimera mink` defaults to Ollama (`kimi-k2.6:cloud`, see\n`chimera/mink/cli.py:34`), but the underlying provider stack is pluggable\nthrough `chimera.providers.create_provider()`\n(`chimera/providers/factory.py:36`). Six adapters self-register at import\ntime via `_ensure_builtins_registered()`\n(`chimera/providers/registry.py:55`); a seventh (`proxy`) is registered by\n`chimera/providers/proxy.py:119`.\n\n## Built-in registry\n\n| Name | Module | Self-registers at |\n|---------------|-----------------------------------|--------------------------|\n| `anthropic` | `chimera/providers/anthropic.py` | line 437 |\n| `openai` | `chimera/providers/openai.py` | line 375 |\n| `google` | `chimera/providers/google.py` | line 165 |\n| `ollama` | `chimera/providers/ollama.py` | line 392 |\n| `compatible` | `chimera/providers/compatible.py` | line 150 |\n| `modal` | `chimera/providers/modal.py` | line 171 |\n| `proxy` | `chimera/providers/proxy.py` | line 119 |\n\n`create_provider()` picks one of these by:\n1. explicit `provider_type=`,\n2. prefix on the model name (`claude-*`, `gpt-*`, `gemini-*`, `glm-*`,\n `kimi-*`, `llama*`, `qwen*`, `mistral*`, `phi*`),\n3. `ProviderCatalog` lookup (`chimera/providers/catalog.py:79`),\n4. loose env-var fallback.\n\nSee `_infer_provider()` (`chimera/providers/factory.py:113`) for the exact\norder, including the env-var override that routes anything with\n`ANTHROPIC_BASE_URL` or `ANTHROPIC_AUTH_TOKEN` set through the Anthropic\nadapter.\n\n---\n\n## Ollama (default for mink)\n\nLocal or Ollama-Cloud models served by the `ollama` daemon. The adapter\ntalks to `/api/chat` (NOT the OpenAI-compat shim at `/v1/...`, which\nsilently drops `tool_calls` from streaming chunks; see comment at\n`chimera/providers/ollama.py:25-32`).\n\n- **Use when:** running locally for privacy, or hitting Ollama Cloud\n (`*:cloud` tags) for hosted Kimi / Qwen3 / GLM-4.6.\n- **Setup:**\n ```bash\n brew install ollama # or: curl -fsSL https://ollama.com/install.sh | sh\n ollama serve & # daemon on :11434\n ollama signin # only needed for :cloud tags\n ollama pull qwen3:32b # local fallback\n ```\n- **Auth options:** none for local; Ollama Cloud uses `ollama signin`\n (browser flow stored in the daemon, not in `~/.chimera/`).\n- **Use with mink:**\n ```bash\n chimera mink --model kimi-k2.6:cloud -p \"list files then read README.md\"\n chimera mink --model qwen3:32b -p \"explain this repo\"\n ```\n- **What's wired:** streaming yes (NDJSON over `/api/chat`,\n `chimera/providers/ollama.py:214`); tool calls yes (native\n `tool_calls` field, `chimera/providers/ollama.py:269-295`); thinking\n yes for `kimi*` only (`chimera/providers/ollama.py:50`); JSON-mode no\n on cloud Kimi (server ignores `format` field, see `quickstart.md`);\n vision varies by model (Kimi 2.6 weak); prompt caching no.\n- **Defaults:** `num_ctx=131072`, `keep_alive=\"60m\"`, `OLLAMA_HOST` env\n override, `262144` ctx auto-bumped for `kimi*` (see\n `chimera/mink/cli.py:300`).\n- **Limits:** `tool_choice=\"required\"` is silently dropped when\n `think:true` (`chimera/providers/ollama.py:103`); `:cloud` weights live\n on Moonshot/Ollama infra; first cold-start call can take 10-30s.\n\n---\n\n## Anthropic\n\nAnthropic SDK against the official `api.anthropic.com` endpoint, OR\nagainst any Anthropic-wire-compatible endpoint via `ANTHROPIC_BASE_URL`\n(GLM-4.6 via `api.z.ai`, Moonshot, Ollama's Anthropic-compat shim, etc.).\n\n- **Use when:** you have an Anthropic API key, OR you have a third-party\n provider that speaks the Anthropic Messages API.\n- **Setup:**\n ```bash\n uv sync --extra anthropic # installs the anthropic SDK\n export ANTHROPIC_API_KEY=sk-ant-...\n # OR, for an Anthropic-compat endpoint:\n export ANTHROPIC_BASE_URL=https://api.z.ai/v1/anthropic\n export ANTHROPIC_AUTH_TOKEN=...\n ```\n- **Auth options:**\n - `ANTHROPIC_API_KEY` — first-class env var\n (`chimera/providers/anthropic.py:53`)\n - `ANTHROPIC_AUTH_TOKEN` — Bearer-token alias for OAuth-issued tokens\n or third-party endpoints (same line, fallback)\n - `AuthManager.get_token(\"anthropic\")` — pulls from\n `~/.chimera/auth.json` or environment\n (`chimera/auth/manager.py:36-37`, `chimera/providers/anthropic.py:48`)\n - OAuth device or browser flow via `OAuthDeviceFlow`/`OAuthBrowserFlow`\n (`chimera/auth/oauth.py:20`, `chimera/auth/oauth.py:182`); tokens\n persist to `~/.chimera/credentials.json` (mode `0o600`,\n `chimera/auth/store.py:62`)\n- **Use with mink:**\n ```bash\n chimera mink --model claude-sonnet-4-20250514 -p \"review this PR\"\n ```\n- **What's wired:** streaming yes (`chimera/providers/anthropic.py:204`);\n tool calls yes; native async (`AsyncAnthropic`,\n `chimera/providers/anthropic.py:345`); extended thinking yes\n (`enable_thinking=True`, `chimera/providers/anthropic.py:120-125`);\n prompt caching yes (opt-in via `enable_cache=True`,\n `chimera/providers/anthropic.py:131-143`); vision yes (Claude models);\n JSON mode via tool-calling pattern.\n- **Limits:** when `enable_thinking` is on, temperature is forced to 1\n (`chimera/providers/anthropic.py:125`); `ImportError` if\n `chimera-run[anthropic]` is not installed.\n\n---\n\n## OpenAI\n\nThe official `openai` SDK against `api.openai.com`, or any\n`/v1/chat/completions` endpoint via `base_url=`.\n\n- **Use when:** GPT-4o, o1, o3, Codex, or any provider that ships an\n OpenAI-SDK-compatible endpoint and you want native streaming +\n reasoning-token tracking.\n- **Setup:**\n ```bash\n uv sync --extra openai # installs the openai SDK\n export OPENAI_API_KEY=sk-...\n ```\n- **Auth options:**\n - `OPENAI_API_KEY` (`chimera/providers/openai.py:52`)\n - `AuthManager.get_token(\"openai\")`\n (`chimera/providers/openai.py:46-50`)\n- **Use with mink:**\n ```bash\n chimera mink --model gpt-4o -p \"draft a release note\"\n chimera mink --model o3-mini -p \"prove this invariant\"\n ```\n- **What's wired:** streaming yes (`chimera/providers/openai.py:142`);\n tool calls yes (delta-accumulated by `index`,\n `chimera/providers/openai.py:174-213`); native async (`AsyncOpenAI`,\n `chimera/providers/openai.py:222`); reasoning-token tracking for o-series\n models (`chimera/providers/openai.py:96-99`); prompt-cache hit accounting\n (`chimera/providers/openai.py:100-104`); vision yes (gpt-4o); JSON mode\n yes (via standard SDK options the adapter passes through unchanged).\n- **Limits:** thinking-level enum is accepted but not forwarded — the\n provider relies on the OpenAI SDK's native reasoning behavior; no\n Anthropic-style cache control.\n\n---\n\n## OpenAI-compatible\n\nGeneric adapter for any `/v1/chat/completions` endpoint. Used by\nOpenRouter, Together, Fireworks, Groq, vLLM, SGLang, LM Studio, LiteLLM,\nAnthropic Coding API in OpenAI-compat mode, and `bedrock/`/`azure/`/etc.\ncatalog entries (`chimera/providers/catalog.py:57-76`).\n\n- **Use when:** you have an OpenAI-shaped endpoint and don't want the\n full `openai` SDK dependency.\n- **Setup:**\n ```bash\n # No extra needed — uses httpx (already a dep of mink/Ollama).\n export OPENAI_API_KEY=... # or any bearer-style token\n ```\n- **Auth options:** `OPENAI_API_KEY` env (or any token passed as\n `api_key=`); custom headers via the `headers=` constructor kwarg\n (`chimera/providers/compatible.py:29`).\n- **Use with mink:**\n ```bash\n # via the catalog (resolves base_url + api_key from env)\n chimera mink --model groq/llama-3.3-70b -p \"...\"\n chimera mink --model deepseek-chat -p \"...\"\n ```\n- **What's wired:** non-streaming `complete()` only\n (`chimera/providers/compatible.py:44`); tool calls yes; default\n ASYNC/streaming falls back to base-class wrappers (`base.py:61`,\n `base.py:107`); no thinking, no caching.\n- **Limits:** **no native streaming** — the base-class `stream()` shim\n yields the whole response as one chunk; this is fine for short\n completions but loses token-by-token feel. Use the `openai` adapter if\n you need real streaming against an OpenAI-shaped endpoint.\n\n---\n\n## Google Gemini\n\nGoogle `google-generativeai` SDK against the Gemini API.\n\n- **Use when:** you want Gemini 2.0 Flash, Gemini 1.5 Pro, etc.\n- **Setup:**\n ```bash\n uv sync --extra google # if shipped; otherwise:\n pip install google-generativeai\n export GOOGLE_API_KEY=... # or GEMINI_API_KEY\n ```\n- **Auth options:**\n - `GOOGLE_API_KEY` or `GEMINI_API_KEY`\n (`chimera/auth/manager.py:39`, `chimera/providers/google.py:45`)\n - `AuthManager.get_token(\"google\")`\n- **Use with mink:**\n ```bash\n chimera mink --model gemini-2.0-flash -p \"summarize this doc\"\n ```\n- **What's wired:** non-streaming `complete()` only; tool calls yes\n (function declarations, `chimera/providers/google.py:120`); 1M context\n windows (`chimera/providers/google.py:23-26`); system messages folded\n into the first user turn as `[System] ...`\n (`chimera/providers/google.py:101`).\n- **Limits:** **no streaming** — the base-class shim is used; no async\n override; system-prompt handling is approximate (Gemini wants a\n separate `system_instruction` field, this adapter inlines it instead);\n schema cleanup strips `$ref` / `oneOf` / `additionalProperties` etc.\n unsupported by Gemini (`chimera/providers/google.py:132-146`); thinking\n param is accepted but ignored.\n\n---\n\n## Modal\n\nModal-hosted vLLM container exposing OpenAI-shape `/v1/chat/completions`.\nThe adapter does not deploy the container — it just calls a URL you\nalready have.\n\n- **Use when:** you've deployed an open-weight model on Modal GPUs and\n want mink to drive it.\n- **Setup:**\n ```bash\n pip install modal httpx\n modal token new # browser flow\n export MODAL_TOKEN_ID=... # optional, if you want to skip browser\n export MODAL_TOKEN_SECRET=...\n # then deploy your container and capture its public URL\n ```\n- **Auth options:** `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET` env vars\n (`chimera/providers/modal.py:47-48`); per-container auth is up to your\n vLLM image.\n- **Use with mink:** not directly — `mink --model` only auto-routes to\n Ollama. Use the catalog or `create_provider()` from Python:\n ```python\n from chimera.providers import create_provider\n provider = create_provider(\n \"modal\", model=\"meta-llama/Llama-3.3-70B\",\n base_url=\"https://your-org--llm-app-serve.modal.run/v1\",\n )\n ```\n- **What's wired:** non-streaming `complete()` only; tool calls yes (via\n the OpenAI-compat shape vLLM emits).\n- **Limits:** **no streaming, no async, no thinking, no caching**;\n `base_url` is required — `_get_base_url()` raises if you forget it\n (`chimera/providers/modal.py:55`).\n\n---\n\n## Proxy\n\nHTTP relay for centralized key management, cost tracking, or running\nagents in environments without direct API egress.\n\n- **Use when:** a team wants one server holding the API keys, with mink\n clients pointing at it. The proxy translates Chimera's wire format to\n whatever upstream provider it controls.\n- **Setup:** stand up a server that exposes `POST /api/complete` (and\n optionally `/api/stream`) accepting Chimera's payload shape; see\n `chimera/providers/proxy.py:18-26` for the contract.\n- **Auth options:** Bearer token via the `api_key=` constructor arg, sent\n as `Authorization: Bearer <token>` (`chimera/providers/proxy.py:69`).\n- **Use with mink:** like Modal, only via `create_provider()` from\n Python:\n ```python\n from chimera.providers import create_provider\n provider = create_provider(\n \"proxy\",\n base_url=\"http://proxy.internal:8000\",\n api_key=\"team-token\",\n model=\"claude-sonnet-4\",\n )\n ```\n- **What's wired:** synchronous `complete()` only (uses stdlib\n `urllib.request`, no `httpx`); tool calls forwarded as plain dicts;\n thinking level forwarded as a string for the proxy to interpret\n (`chimera/providers/proxy.py:62-65`).\n- **Limits:** no streaming, no async; the proxy must report `usage`\n itself — the adapter trusts whatever JSON comes back; default\n `context_window=128000` is hardcoded (`chimera/providers/proxy.py:97`).\n\n---\n\n## Custom providers\n\nImplement `Provider` (`chimera/providers/base.py:47`) and call\n`register_provider(\"my-name\", factory)` (`chimera/providers/registry.py:14`).\nFactory signature: `factory(model=..., api_key=..., base_url=..., **kw)`.\nAfter registration, `create_provider(\"my-name\", model=...)` works\nidentically to the built-ins. Drop the factory call into your package's\n`__init__.py` so import triggers self-registration, mirroring the\nbuilt-ins (e.g. `chimera/providers/anthropic.py:436`).\n\n---\n\n## Choosing a provider\n\n| Concern | Pick |\n|-----------------|-------------------------------------------------------------------|\n| Privacy / local | `ollama` with a local model (`qwen3:32b`, `llama3.1:70b-instruct`) |\n| Lowest latency | `ollama` local on GPU; `groq/*` via `compatible` |\n| Best capability | `anthropic` (claude-sonnet/opus) or `openai` (gpt-4o, o3) |\n| Cost-sensitive | `compatible` with `deepseek-chat` or `groq/llama-3.3-70b` |\n| Vision-heavy | `anthropic` (claude-sonnet) or `openai` (gpt-4o); avoid Kimi 2.6 |\n| Long context | `google` (Gemini 1M) or `anthropic` (Claude 200k) or Kimi (262k) |\n| Tools + streaming + thinking, all in one | `anthropic` (claude with `enable_thinking=True`) |\n\n---\n\n## Mixing providers in one session\n\nTwo ways to set the model — last write wins:\n\n1. CLI flag (highest precedence): `chimera mink --model <name>`.\n2. `settings.json` `model:` key, loaded by\n `load_mink_settings()` (`chimera/mink/settings.py:274`). The CLI\n default `kimi-k2.6:cloud` is treated as \"user did not pass --model\"\n so an agent's frontmatter `model:` can override it\n (`chimera/mink/cli.py:796-801`).\n3. Env vars `ANTHROPIC_MODEL` / `OPENAI_MODEL` are picked up only when no\n `--model` and no settings model is set\n (`chimera/providers/factory.py:81-82`).\n\nA single `chimera mink` process holds one provider for the whole\nsession. To swap mid-session, exit and relaunch (or, programmatically,\nbuild a new `Agent` with `create_provider(...)`).\n\n---\n\n## Credentials directory\n\n| Path | Source | Mode |\n|-----------------------------------|---------------------------------------|---------|\n| `~/.chimera/credentials.json` | OAuth-issued tokens, refresh tokens | `0o600` |\n| `~/.chimera/auth.json` | `AuthManager.set_token()` | default |\n| `~/.chimera/sessions/*.jsonl` | Session tree per-cwd (mink REPL) | default |\n| `~/.chimera/eventlog/mink-*/` | `chimera mink -p` persisted runs | default |\n\n`CredentialStore._write` chmods to `0o600` after each save\n(`chimera/auth/store.py:62`); `auth.json` is a plain JSON file written\nby `AuthManager.set_token()` (`chimera/auth/manager.py:154`).\n\n---\n\n## Proxy mode for teams\n\nFor an org-wide gateway sitting in front of Anthropic-shaped providers:\n\n```bash\nexport ANTHROPIC_BASE_URL=http://proxy.internal:8000\nexport ANTHROPIC_AUTH_TOKEN=team-issued-jwt\nchimera mink --model claude-sonnet-4 -p \"...\"\n```\n\n`AnthropicProvider` honors both env vars\n(`chimera/providers/anthropic.py:53,58`); the proxy can be a thin pass-\nthrough, a key-rotating relay, or a budget-enforcing gatekeeper. The\ndedicated `proxy` provider (above) is the alternative when your gateway\nspeaks its own JSON shape rather than the Anthropic wire protocol.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause / fix |\n|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------|\n| `401` / `403` | Wrong key, wrong env var. Check `AuthManager.status()` or `printenv | grep -E '(ANTHROPIC|OPENAI|GOOGLE)_'`. |\n| `ImportError: pip install chimera-run[...]` | Provider's optional extra is missing. `uv sync --extra anthropic` (or `openai`, `google`). |\n| `Cannot infer provider from model name '...'` | Pass `provider_type=...` explicitly, or use a known prefix; see `_infer_provider()` for the list. |\n| Streaming hangs / first call is slow | Cloud cold start. Ollama Cloud needs `keep_alive: 60m` (mink sets this). Anthropic / OpenAI typically warm in <2s.|\n| `tool_calls` always empty on Ollama | You hit `/v1/chat/completions` instead of `/api/chat`. Set `OLLAMA_HOST` to the daemon root, not `.../v1`. |\n| `temperature must be 1 with thinking` | Anthropic extended thinking forces `temperature=1` (see `anthropic.py:125`). Drop your custom temperature. |\n| Ollama Kimi rejects `tool_choice: \"required\"` | Adapter silently drops it when `think:true` is also set (`ollama.py:103`); use `auto`/`none`. |\n| Gemini complains about `$ref` / `oneOf` | The adapter strips them (`google.py:132`); if you see it pass through, check you're hitting the right adapter. |\n"}}}} |