@symerian/symi 3.0.21 → 3.0.22

package/docs/concepts/model-providers.md

@@ -1,424 +0,0 @@
----
-summary: "Model provider overview with example configs + CLI flows"
-read_when:
-  - You need a provider-by-provider model setup reference
-  - You want example configs or CLI onboarding commands for model providers
-title: "Model Providers"
----
-
-# Model providers
-
-This page covers **LLM/model providers** (not chat channels like WhatsApp/Telegram).
-For model selection rules, see [/concepts/models](/concepts/models).
-
-## Quick rules
-
-- Model refs use `provider/model` (example: `opencode/claude-opus-4-6`).
-- If you set `agents.defaults.models`, it becomes the allowlist.
-- CLI helpers: `symi onboard`, `symi models list`, `symi models set <provider/model>`.
-
-## API key rotation
-
-- Supports generic provider rotation for selected providers.
-- Configure multiple keys via:
-  - `SYMI_LIVE_<PROVIDER>_KEY` (single live override, highest priority)
-  - `<PROVIDER>_API_KEYS` (comma or semicolon list)
-  - `<PROVIDER>_API_KEY` (primary key)
-  - `<PROVIDER>_API_KEY_*` (numbered list, e.g. `<PROVIDER>_API_KEY_1`)
-- For Google providers, `GOOGLE_API_KEY` is also included as fallback.
-- Key selection order preserves priority and deduplicates values.
-- Requests are retried with the next key only on rate-limit responses (for example `429`, `rate_limit`, `quota`, `resource exhausted`).
-- Non-rate-limit failures fail immediately; no key rotation is attempted.
-- When all candidate keys fail, the final error is returned from the last attempt.
-
-## Built-in providers (pi-ai catalog)
-
-Symi ships with the pi‑ai catalog. These providers require **no**
-`models.providers` config; just set auth + pick a model.
-
-### OpenAI
-
-- Provider: `openai`
-- Auth: `OPENAI_API_KEY`
-- Optional rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `SYMI_LIVE_OPENAI_KEY` (single override)
-- Example model: `openai/gpt-5.1-codex`
-- CLI: `symi onboard --auth-choice openai-api-key`
-
-```json5
-{
-  agents: { defaults: { model: { primary: "openai/gpt-5.1-codex" } } },
-}
-```
-
-### Anthropic
-
-- Provider: `anthropic`
-- Auth: `ANTHROPIC_API_KEY` or `claude setup-token`
-- Optional rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, plus `SYMI_LIVE_ANTHROPIC_KEY` (single override)
-- Example model: `anthropic/claude-opus-4-6`
-- CLI: `symi onboard --auth-choice token` (paste setup-token) or `symi models auth paste-token --provider anthropic`
-
-```json5
-{
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
-}
-```
-
-### OpenAI Code (Codex)
-
-- Provider: `openai-codex`
-- Auth: OAuth (ChatGPT)
-- Example model: `openai-codex/gpt-5.3-codex`
-- CLI: `symi onboard --auth-choice openai-codex` or `symi models auth login --provider openai-codex`
-
-```json5
-{
-  agents: { defaults: { model: { primary: "openai-codex/gpt-5.3-codex" } } },
-}
-```
-
-### OpenCode Zen
-
-- Provider: `opencode`
-- Auth: `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`)
-- Example model: `opencode/claude-opus-4-6`
-- CLI: `symi onboard --auth-choice opencode-zen`
-
-```json5
-{
-  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
-}
-```
-
-### Google Gemini (API key)
-
-- Provider: `google`
-- Auth: `GEMINI_API_KEY`
-- Optional rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` fallback, and `SYMI_LIVE_GEMINI_KEY` (single override)
-- Example model: `google/gemini-3-pro-preview`
-- CLI: `symi onboard --auth-choice gemini-api-key`
-
-### Google Vertex, Antigravity, and Gemini CLI
-
-- Providers: `google-vertex`, `google-antigravity`, `google-gemini-cli`
-- Auth: Vertex uses gcloud ADC; Antigravity/Gemini CLI use their respective auth flows
-- Antigravity OAuth is shipped as a bundled plugin (`google-antigravity-auth`, disabled by default).
-  - Enable: `symi plugins enable google-antigravity-auth`
-  - Login: `symi models auth login --provider google-antigravity --set-default`
-- Gemini CLI OAuth is shipped as a bundled plugin (`google-gemini-cli-auth`, disabled by default).
-  - Enable: `symi plugins enable google-gemini-cli-auth`
-  - Login: `symi models auth login --provider google-gemini-cli --set-default`
-  - Note: you do **not** paste a client id or secret into `symi.json`. The CLI login flow stores
-    tokens in auth profiles on the gateway host.
-
-### Z.AI (GLM)
-
-- Provider: `zai`
-- Auth: `ZAI_API_KEY`
-- Example model: `zai/glm-4.7`
-- CLI: `symi onboard --auth-choice zai-api-key`
-  - Aliases: `z.ai/*` and `z-ai/*` normalize to `zai/*`
-
-### Vercel AI Gateway
-
-- Provider: `vercel-ai-gateway`
-- Auth: `AI_GATEWAY_API_KEY`
-- Example model: `vercel-ai-gateway/anthropic/claude-opus-4.6`
-- CLI: `symi onboard --auth-choice ai-gateway-api-key`
-
-### Other built-in providers
-
-- OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)
-- Example model: `openrouter/anthropic/claude-sonnet-4-5`
-- xAI: `xai` (`XAI_API_KEY`)
-- Groq: `groq` (`GROQ_API_KEY`)
-- Cerebras: `cerebras` (`CEREBRAS_API_KEY`)
-  - GLM models on Cerebras use ids `zai-glm-4.7` and `zai-glm-4.6`.
-  - OpenAI-compatible base URL: `https://api.cerebras.ai/v1`.
-- Mistral: `mistral` (`MISTRAL_API_KEY`)
-- GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`)
-- Hugging Face Inference: `huggingface` (`HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN`) — OpenAI-compatible router; example model: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `symi onboard --auth-choice huggingface-api-key`. See [Hugging Face (Inference)](/providers/huggingface).
-
-## Providers via `models.providers` (custom/base URL)
-
-Use `models.providers` (or `models.json`) to add **custom** providers or
-OpenAI/Anthropic‑compatible proxies.
-
-### Moonshot AI (Kimi)
-
-Moonshot uses OpenAI-compatible endpoints, so configure it as a custom provider:
-
-- Provider: `moonshot`
-- Auth: `MOONSHOT_API_KEY`
-- Example model: `moonshot/kimi-k2.5`
-
-Kimi K2 model IDs:
-
-{/_moonshot-kimi-k2-model-refs:start_/ && null}
-
-- `moonshot/kimi-k2.5`
-- `moonshot/kimi-k2-0905-preview`
-- `moonshot/kimi-k2-turbo-preview`
-- `moonshot/kimi-k2-thinking`
-- `moonshot/kimi-k2-thinking-turbo`
-  {/_moonshot-kimi-k2-model-refs:end_/ && null}
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "moonshot/kimi-k2.5" } },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      moonshot: {
-        baseUrl: "https://api.moonshot.ai/v1",
-        apiKey: "${MOONSHOT_API_KEY}",
-        api: "openai-completions",
-        models: [{ id: "kimi-k2.5", name: "Kimi K2.5" }],
-      },
-    },
-  },
-}
-```
-
-### Kimi Coding
-
-Kimi Coding uses Moonshot AI's Anthropic-compatible endpoint:
-
-- Provider: `kimi-coding`
-- Auth: `KIMI_API_KEY`
-- Example model: `kimi-coding/k2p5`
-
-```json5
-{
-  env: { KIMI_API_KEY: "sk-..." },
-  agents: {
-    defaults: { model: { primary: "kimi-coding/k2p5" } },
-  },
-}
-```
-
-### Qwen OAuth (free tier)
-
-Qwen provides OAuth access to Qwen Coder + Vision via a device-code flow.
-Enable the bundled plugin, then log in:
-
-```bash
-symi plugins enable qwen-portal-auth
-symi models auth login --provider qwen-portal --set-default
-```
-
-Model refs:
-
-- `qwen-portal/coder-model`
-- `qwen-portal/vision-model`
-
-See [/providers/qwen](/providers/qwen) for setup details and notes.
-
-### Volcano Engine (Doubao)
-
-Volcano Engine (火山引擎) provides access to Doubao and other models in China.
-
-- Provider: `volcengine` (coding: `volcengine-plan`)
-- Auth: `VOLCANO_ENGINE_API_KEY`
-- Example model: `volcengine/doubao-seed-1-8-251228`
-- CLI: `symi onboard --auth-choice volcengine-api-key`
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "volcengine/doubao-seed-1-8-251228" } },
-  },
-}
-```
-
-Available models:
-
-- `volcengine/doubao-seed-1-8-251228` (Doubao Seed 1.8)
-- `volcengine/doubao-seed-code-preview-251028`
-- `volcengine/kimi-k2-5-260127` (Kimi K2.5)
-- `volcengine/glm-4-7-251222` (GLM 4.7)
-- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
-
-Coding models (`volcengine-plan`):
-
-- `volcengine-plan/ark-code-latest`
-- `volcengine-plan/doubao-seed-code`
-- `volcengine-plan/kimi-k2.5`
-- `volcengine-plan/kimi-k2-thinking`
-- `volcengine-plan/glm-4.7`
-
-### BytePlus (International)
-
-BytePlus ARK provides access to the same models as Volcano Engine for international users.
-
-- Provider: `byteplus` (coding: `byteplus-plan`)
-- Auth: `BYTEPLUS_API_KEY`
-- Example model: `byteplus/seed-1-8-251228`
-- CLI: `symi onboard --auth-choice byteplus-api-key`
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "byteplus/seed-1-8-251228" } },
-  },
-}
-```
-
-Available models:
-
-- `byteplus/seed-1-8-251228` (Seed 1.8)
-- `byteplus/kimi-k2-5-260127` (Kimi K2.5)
-- `byteplus/glm-4-7-251222` (GLM 4.7)
-
-Coding models (`byteplus-plan`):
-
-- `byteplus-plan/ark-code-latest`
-- `byteplus-plan/doubao-seed-code`
-- `byteplus-plan/kimi-k2.5`
-- `byteplus-plan/kimi-k2-thinking`
-- `byteplus-plan/glm-4.7`
-
-### Synthetic
-
-Synthetic provides Anthropic-compatible models behind the `synthetic` provider:
-
-- Provider: `synthetic`
-- Auth: `SYNTHETIC_API_KEY`
-- Example model: `synthetic/hf:MiniMaxAI/MiniMax-M2.1`
-- CLI: `symi onboard --auth-choice synthetic-api-key`
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.1" } },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      synthetic: {
-        baseUrl: "https://api.synthetic.new/anthropic",
-        apiKey: "${SYNTHETIC_API_KEY}",
-        api: "anthropic-messages",
-        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.1", name: "MiniMax M2.1" }],
-      },
-    },
-  },
-}
-```
-
-### MiniMax
-
-MiniMax is configured via `models.providers` because it uses custom endpoints:
-
-- MiniMax (Anthropic‑compatible): `--auth-choice minimax-api`
-- Auth: `MINIMAX_API_KEY`
-
-See [/providers/minimax](/providers/minimax) for setup details, model options, and config snippets.
-
-### Ollama
-
-Ollama is a local LLM runtime that provides an OpenAI-compatible API:
-
-- Provider: `ollama`
-- Auth: None required (local server)
-- Example model: `ollama/llama3.3`
-- Installation: [https://ollama.ai](https://ollama.ai)
-
-```bash
-# Install Ollama, then pull a model:
-ollama pull llama3.3
-```
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "ollama/llama3.3" } },
-  },
-}
-```
-
-Ollama is automatically detected when running locally at `http://127.0.0.1:11434/v1`. See [/providers/ollama](/providers/ollama) for model recommendations and custom configuration.
-
-### vLLM
-
-vLLM is a local (or self-hosted) OpenAI-compatible server:
-
-- Provider: `vllm`
-- Auth: Optional (depends on your server)
-- Default base URL: `http://127.0.0.1:8000/v1`
-
-To opt in to auto-discovery locally (any value works if your server doesn’t enforce auth):
-
-```bash
-export VLLM_API_KEY="vllm-local"
-```
-
-Then set a model (replace with one of the IDs returned by `/v1/models`):
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "vllm/your-model-id" } },
-  },
-}
-```
-
-See [/providers/vllm](/providers/vllm) for details.
-
-### Local proxies (LM Studio, vLLM, LiteLLM, etc.)
-
-Example (OpenAI‑compatible):
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "lmstudio/minimax-m2.1-gs32" },
-      models: { "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } },
-    },
-  },
-  models: {
-    providers: {
-      lmstudio: {
-        baseUrl: "http://localhost:1234/v1",
-        apiKey: "LMSTUDIO_KEY",
-        api: "openai-completions",
-        models: [
-          {
-            id: "minimax-m2.1-gs32",
-            name: "MiniMax M2.1",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 200000,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-Notes:
-
-- For custom providers, `reasoning`, `input`, `cost`, `contextWindow`, and `maxTokens` are optional.
-  When omitted, Symi defaults to:
-  - `reasoning: false`
-  - `input: ["text"]`
-  - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
-  - `contextWindow: 200000`
-  - `maxTokens: 8192`
-- Recommended: set explicit values that match your proxy/model limits.
-
-## CLI examples
-
-```bash
-symi onboard --auth-choice opencode-zen
-symi models set opencode/claude-opus-4-6
-symi models list
-```
-
-See also: [/gateway/configuration](/gateway/configuration) for full configuration examples.

package/docs/concepts/models.md

@@ -1,208 +0,0 @@
----
-summary: "Models CLI: list, set, aliases, fallbacks, scan, status"
-read_when:
-  - Adding or modifying models CLI (models list/set/scan/aliases/fallbacks)
-  - Changing model fallback behavior or selection UX
-  - Updating model scan probes (tools/images)
-title: "Models CLI"
----
-
-# Models CLI
-
-See [/concepts/model-failover](/concepts/model-failover) for auth profile
-rotation, cooldowns, and how that interacts with fallbacks.
-Quick provider overview + examples: [/concepts/model-providers](/concepts/model-providers).
-
-## How model selection works
-
-Symi selects models in this order:
-
-1. **Primary** model (`agents.defaults.model.primary` or `agents.defaults.model`).
-2. **Fallbacks** in `agents.defaults.model.fallbacks` (in order).
-3. **Provider auth failover** happens inside a provider before moving to the
-   next model.
-
-Related:
-
-- `agents.defaults.models` is the allowlist/catalog of models Symi can use (plus aliases).
-- `agents.defaults.imageModel` is used **only when** the primary model can’t accept images.
-- Per-agent defaults can override `agents.defaults.model` via `agents.list[].model` plus bindings (see [/concepts/multi-agent](/concepts/multi-agent)).
-
-## Quick model picks (anecdotal)
-
-- **GLM**: a bit better for coding/tool calling.
-- **MiniMax**: better for writing and vibes.
-
-## Setup wizard (recommended)
-
-If you don’t want to hand-edit config, run the onboarding wizard:
-
-```bash
-symi onboard
-```
-
-It can set up model + auth for common providers, including **OpenAI Code (Codex)
-subscription** (OAuth) and **Anthropic** (API key recommended; `claude
-setup-token` also supported).
-
-## Config keys (overview)
-
-- `agents.defaults.model.primary` and `agents.defaults.model.fallbacks`
-- `agents.defaults.imageModel.primary` and `agents.defaults.imageModel.fallbacks`
-- `agents.defaults.models` (allowlist + aliases + provider params)
-- `models.providers` (custom providers written into `models.json`)
-
-Model refs are normalized to lowercase. Provider aliases like `z.ai/*` normalize
-to `zai/*`.
-
-Provider configuration examples (including OpenCode Zen) live in
-[/gateway/configuration](/gateway/configuration#opencode-zen-multi-model-proxy).
-
-## “Model is not allowed” (and why replies stop)
-
-If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and for
-session overrides. When a user selects a model that isn’t in that allowlist,
-Symi returns:
-
-```
-Model "provider/model" is not allowed. Use /model to list available models.
-```
-
-This happens **before** a normal reply is generated, so the message can feel
-like it “didn’t respond.” The fix is to either:
-
-- Add the model to `agents.defaults.models`, or
-- Clear the allowlist (remove `agents.defaults.models`), or
-- Pick a model from `/model list`.
-
-Example allowlist config:
-
-```json5
-{
-  agent: {
-    model: { primary: "anthropic/claude-sonnet-4-5" },
-    models: {
-      "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
-      "anthropic/claude-opus-4-6": { alias: "Opus" },
-    },
-  },
-}
-```
-
-## Switching models in chat (`/model`)
-
-You can switch models for the current session without restarting:
-
-```
-/model
-/model list
-/model 3
-/model openai/gpt-5.2
-/model status
-```
-
-Notes:
-
-- `/model` (and `/model list`) is a compact, numbered picker (model family + available providers).
-- `/model <#>` selects from that picker.
-- `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
-- Model refs are parsed by splitting on the **first** `/`. Use `provider/model` when typing `/model <ref>`.
-- If the model ID itself contains `/` (OpenRouter-style), you must include the provider prefix (example: `/model openrouter/moonshotai/kimi-k2`).
-- If you omit the provider, Symi treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
-
-Full command behavior/config: [Slash commands](/tools/slash-commands).
-
-## CLI commands
-
-```bash
-symi models list
-symi models status
-symi models set <provider/model>
-symi models set-image <provider/model>
-
-symi models aliases list
-symi models aliases add <alias> <provider/model>
-symi models aliases remove <alias>
-
-symi models fallbacks list
-symi models fallbacks add <provider/model>
-symi models fallbacks remove <provider/model>
-symi models fallbacks clear
-
-symi models image-fallbacks list
-symi models image-fallbacks add <provider/model>
-symi models image-fallbacks remove <provider/model>
-symi models image-fallbacks clear
-```
-
-`symi models` (no subcommand) is a shortcut for `models status`.
-
-### `models list`
-
-Shows configured models by default. Useful flags:
-
-- `--all`: full catalog
-- `--local`: local providers only
-- `--provider <name>`: filter by provider
-- `--plain`: one model per line
-- `--json`: machine‑readable output
-
-### `models status`
-
-Shows the resolved primary model, fallbacks, image model, and an auth overview
-of configured providers. It also surfaces OAuth expiry status for profiles found
-in the auth store (warns within 24h by default). `--plain` prints only the
-resolved primary model.
-OAuth status is always shown (and included in `--json` output). If a configured
-provider has no credentials, `models status` prints a **Missing auth** section.
-JSON includes `auth.oauth` (warn window + profiles) and `auth.providers`
-(effective auth per provider).
-Use `--check` for automation (exit `1` when missing/expired, `2` when expiring).
-
-Preferred Anthropic auth is the Claude Code CLI setup-token (run anywhere; paste on the gateway host if needed):
-
-```bash
-claude setup-token
-symi models status
-```
-
-## Scanning (OpenRouter free models)
-
-`symi models scan` inspects OpenRouter’s **free model catalog** and can
-optionally probe models for tool and image support.
-
-Key flags:
-
-- `--no-probe`: skip live probes (metadata only)
-- `--min-params <b>`: minimum parameter size (billions)
-- `--max-age-days <days>`: skip older models
-- `--provider <name>`: provider prefix filter
-- `--max-candidates <n>`: fallback list size
-- `--set-default`: set `agents.defaults.model.primary` to the first selection
-- `--set-image`: set `agents.defaults.imageModel.primary` to the first image selection
-
-Probing requires an OpenRouter API key (from auth profiles or
-`OPENROUTER_API_KEY`). Without a key, use `--no-probe` to list candidates only.
-
-Scan results are ranked by:
-
-1. Image support
-2. Tool latency
-3. Context size
-4. Parameter count
-
-Input
-
-- OpenRouter `/models` list (filter `:free`)
-- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/help/environment))
-- Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
-- Probe controls: `--timeout`, `--concurrency`
-
-When run in a TTY, you can select fallbacks interactively. In non‑interactive
-mode, pass `--yes` to accept defaults.
-
-## Models registry (`models.json`)
-
-Custom providers in `models.providers` are written into `models.json` under the
-agent directory (default `~/.symi/agents/<agentId>/models.json`). This file
-is merged by default unless `models.mode` is set to `replace`.