@symerian/symi 3.0.20 → 3.0.22

package/docs/providers/minimax.md

@@ -1,208 +0,0 @@
----
-summary: "Use MiniMax M2.1 in Symi"
-read_when:
-  - You want MiniMax models in Symi
-  - You need MiniMax setup guidance
-title: "MiniMax"
----
-
-# MiniMax
-
-MiniMax is an AI company that builds the **M2/M2.1** model family. The current
-coding-focused release is **MiniMax M2.1** (December 23, 2025), built for
-real-world complex tasks.
-
-Source: [MiniMax M2.1 release note](https://www.minimax.io/news/minimax-m21)
-
-## Model overview (M2.1)
-
-MiniMax highlights these improvements in M2.1:
-
-- Stronger **multi-language coding** (Rust, Java, Go, C++, Kotlin, Objective-C, TS/JS).
-- Better **web/app development** and aesthetic output quality (including native mobile).
-- Improved **composite instruction** handling for office-style workflows, building on
-  interleaved thinking and integrated constraint execution.
-- **More concise responses** with lower token usage and faster iteration loops.
-- Stronger **tool/agent framework** compatibility and context management (Claude Code,
-  Droid/Factory AI, Cline, Kilo Code, Roo Code, BlackBox).
-- Higher-quality **dialogue and technical writing** outputs.
-
-## MiniMax M2.1 vs MiniMax M2.1 Lightning
-
-- **Speed:** Lightning is the “fast” variant in MiniMax’s pricing docs.
-- **Cost:** Pricing shows the same input cost, but Lightning has higher output cost.
-- **Coding plan routing:** The Lightning back-end isn’t directly available on the MiniMax
-  coding plan. MiniMax auto-routes most requests to Lightning, but falls back to the
-  regular M2.1 back-end during traffic spikes.
-
-## Choose a setup
-
-### MiniMax OAuth (Coding Plan) — recommended
-
-**Best for:** quick setup with MiniMax Coding Plan via OAuth, no API key required.
-
-Enable the bundled OAuth plugin and authenticate:
-
-```bash
-symi plugins enable minimax-portal-auth  # skip if already loaded.
-symi gateway restart  # restart if gateway is already running
-symi onboard --auth-choice minimax-portal
-```
-
-You will be prompted to select an endpoint:
-
-- **Global** - International users (`api.minimax.io`)
-- **CN** - Users in China (`api.minimaxi.com`)
-
-See [MiniMax OAuth plugin README](https://github.com/symi/symi/tree/main/extensions/minimax-portal-auth) for details.
-
-### MiniMax M2.1 (API key)
-
-**Best for:** hosted MiniMax with Anthropic-compatible API.
-
-Configure via CLI:
-
-- Run `symi configure`
-- Select **Model/auth**
-- Choose **MiniMax M2.1**
-
-```json5
-{
-  env: { MINIMAX_API_KEY: "sk-..." },
-  agents: { defaults: { model: { primary: "minimax/MiniMax-M2.1" } } },
-  models: {
-    mode: "merge",
-    providers: {
-      minimax: {
-        baseUrl: "https://api.minimax.io/anthropic",
-        apiKey: "${MINIMAX_API_KEY}",
-        api: "anthropic-messages",
-        models: [
-          {
-            id: "MiniMax-M2.1",
-            name: "MiniMax M2.1",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
-            contextWindow: 200000,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-### MiniMax M2.1 as fallback (Opus primary)
-
-**Best for:** keep Opus 4.6 as primary, fail over to MiniMax M2.1.
-
-```json5
-{
-  env: { MINIMAX_API_KEY: "sk-..." },
-  agents: {
-    defaults: {
-      models: {
-        "anthropic/claude-opus-4-6": { alias: "opus" },
-        "minimax/MiniMax-M2.1": { alias: "minimax" },
-      },
-      model: {
-        primary: "anthropic/claude-opus-4-6",
-        fallbacks: ["minimax/MiniMax-M2.1"],
-      },
-    },
-  },
-}
-```
-
-### Optional: Local via LM Studio (manual)
-
-**Best for:** local inference with LM Studio.
-We have seen strong results with MiniMax M2.1 on powerful hardware (e.g. a
-desktop/server) using LM Studio's local server.
-
-Configure manually via `symi.json`:
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "lmstudio/minimax-m2.1-gs32" },
-      models: { "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } },
-    },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      lmstudio: {
-        baseUrl: "http://127.0.0.1:1234/v1",
-        apiKey: "lmstudio",
-        api: "openai-responses",
-        models: [
-          {
-            id: "minimax-m2.1-gs32",
-            name: "MiniMax M2.1 GS32",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 196608,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-## Configure via `symi configure`
-
-Use the interactive config wizard to set MiniMax without editing JSON:
-
-1. Run `symi configure`.
-2. Select **Model/auth**.
-3. Choose **MiniMax M2.1**.
-4. Pick your default model when prompted.
-
-## Configuration options
-
-- `models.providers.minimax.baseUrl`: prefer `https://api.minimax.io/anthropic` (Anthropic-compatible); `https://api.minimax.io/v1` is optional for OpenAI-compatible payloads.
-- `models.providers.minimax.api`: prefer `anthropic-messages`; `openai-completions` is optional for OpenAI-compatible payloads.
-- `models.providers.minimax.apiKey`: MiniMax API key (`MINIMAX_API_KEY`).
-- `models.providers.minimax.models`: define `id`, `name`, `reasoning`, `contextWindow`, `maxTokens`, `cost`.
-- `agents.defaults.models`: alias models you want in the allowlist.
-- `models.mode`: keep `merge` if you want to add MiniMax alongside built-ins.
-
-## Notes
-
-- Model refs are `minimax/<model>`.
-- Coding Plan usage API: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (requires a coding plan key).
-- Update pricing values in `models.json` if you need exact cost tracking.
-- Referral link for MiniMax Coding Plan (10% off): [https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
-- See [/concepts/model-providers](/concepts/model-providers) for provider rules.
-- Use `symi models list` and `symi models set minimax/MiniMax-M2.1` to switch.
-
-## Troubleshooting
-
-### “Unknown model: minimax/MiniMax-M2.1”
-
-This usually means the **MiniMax provider isn’t configured** (no provider entry
-and no MiniMax auth profile/env key found). A fix for this detection is in
-**2026.1.12** (unreleased at the time of writing). Fix by:
-
-- Upgrading to **2026.1.12** (or run from source `main`), then restarting the gateway.
-- Running `symi configure` and selecting **MiniMax M2.1**, or
-- Adding the `models.providers.minimax` block manually, or
-- Setting `MINIMAX_API_KEY` (or a MiniMax auth profile) so the provider can be injected.
-
-Make sure the model id is **case‑sensitive**:
-
-- `minimax/MiniMax-M2.1`
-- `minimax/MiniMax-M2.1-lightning`
-
-Then recheck with:
-
-```bash
-symi models list
-```

package/docs/providers/models.md

@@ -1,52 +0,0 @@
----
-summary: "Model providers (LLMs) supported by Symi"
-read_when:
-  - You want to choose a model provider
-  - You want quick setup examples for LLM auth + model selection
-title: "Model Provider Quickstart"
----
-
-# Model Providers
-
-Symi can use many LLM providers. Pick one, authenticate, then set the default
-model as `provider/model`.
-
-## Highlight: Venice (Venice AI)
-
-Venice is our recommended Venice AI setup for privacy-first inference with an option to use Opus for the hardest tasks.
-
-- Default: `venice/llama-3.3-70b`
-- Best overall: `venice/claude-opus-45` (Opus remains the strongest)
-
-See [Venice AI](/providers/venice).
-
-## Quick start (two steps)
-
-1. Authenticate with the provider (usually via `symi onboard`).
-2. Set the default model:
-
-```json5
-{
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
-}
-```
-
-## Supported providers (starter set)
-
-- [OpenAI (API + Codex)](/providers/openai)
-- [Anthropic (API + Claude Code CLI)](/providers/anthropic)
-- [OpenRouter](/providers/openrouter)
-- [Vercel AI Gateway](/providers/vercel-ai-gateway)
-- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
-- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
-- [Synthetic](/providers/synthetic)
-- [OpenCode Zen](/providers/opencode)
-- [Z.AI](/providers/zai)
-- [GLM models](/providers/glm)
-- [MiniMax](/providers/minimax)
-- [Venice (Venice AI)](/providers/venice)
-- [Amazon Bedrock](/providers/bedrock)
-- [Qianfan](/providers/qianfan)
-
-For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
-see [Model providers](/concepts/model-providers).

package/docs/providers/moonshot.md

@@ -1,142 +0,0 @@
----
-summary: "Configure Moonshot K2 vs Kimi Coding (separate providers + keys)"
-read_when:
-  - You want Moonshot K2 (Moonshot Open Platform) vs Kimi Coding setup
-  - You need to understand separate endpoints, keys, and model refs
-  - You want copy/paste config for either provider
-title: "Moonshot AI"
----
-
-# Moonshot AI (Kimi)
-
-Moonshot provides the Kimi API with OpenAI-compatible endpoints. Configure the
-provider and set the default model to `moonshot/kimi-k2.5`, or use
-Kimi Coding with `kimi-coding/k2p5`.
-
-Current Kimi K2 model IDs:
-
-{/_moonshot-kimi-k2-ids:start_/ && null}
-
-- `kimi-k2.5`
-- `kimi-k2-0905-preview`
-- `kimi-k2-turbo-preview`
-- `kimi-k2-thinking`
-- `kimi-k2-thinking-turbo`
-  {/_moonshot-kimi-k2-ids:end_/ && null}
-
-```bash
-symi onboard --auth-choice moonshot-api-key
-```
-
-Kimi Coding:
-
-```bash
-symi onboard --auth-choice kimi-code-api-key
-```
-
-Note: Moonshot and Kimi Coding are separate providers. Keys are not interchangeable, endpoints differ, and model refs differ (Moonshot uses `moonshot/...`, Kimi Coding uses `kimi-coding/...`).
-
-## Config snippet (Moonshot API)
-
-```json5
-{
-  env: { MOONSHOT_API_KEY: "sk-..." },
-  agents: {
-    defaults: {
-      model: { primary: "moonshot/kimi-k2.5" },
-      models: {
-        // moonshot-kimi-k2-aliases:start
-        "moonshot/kimi-k2.5": { alias: "Kimi K2.5" },
-        "moonshot/kimi-k2-0905-preview": { alias: "Kimi K2" },
-        "moonshot/kimi-k2-turbo-preview": { alias: "Kimi K2 Turbo" },
-        "moonshot/kimi-k2-thinking": { alias: "Kimi K2 Thinking" },
-        "moonshot/kimi-k2-thinking-turbo": { alias: "Kimi K2 Thinking Turbo" },
-        // moonshot-kimi-k2-aliases:end
-      },
-    },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      moonshot: {
-        baseUrl: "https://api.moonshot.ai/v1",
-        apiKey: "${MOONSHOT_API_KEY}",
-        api: "openai-completions",
-        models: [
-          // moonshot-kimi-k2-models:start
-          {
-            id: "kimi-k2.5",
-            name: "Kimi K2.5",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 256000,
-            maxTokens: 8192,
-          },
-          {
-            id: "kimi-k2-0905-preview",
-            name: "Kimi K2 0905 Preview",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 256000,
-            maxTokens: 8192,
-          },
-          {
-            id: "kimi-k2-turbo-preview",
-            name: "Kimi K2 Turbo",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 256000,
-            maxTokens: 8192,
-          },
-          {
-            id: "kimi-k2-thinking",
-            name: "Kimi K2 Thinking",
-            reasoning: true,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 256000,
-            maxTokens: 8192,
-          },
-          {
-            id: "kimi-k2-thinking-turbo",
-            name: "Kimi K2 Thinking Turbo",
-            reasoning: true,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 256000,
-            maxTokens: 8192,
-          },
-          // moonshot-kimi-k2-models:end
-        ],
-      },
-    },
-  },
-}
-```
-
-## Kimi Coding
-
-```json5
-{
-  env: { KIMI_API_KEY: "sk-..." },
-  agents: {
-    defaults: {
-      model: { primary: "kimi-coding/k2p5" },
-      models: {
-        "kimi-coding/k2p5": { alias: "Kimi K2.5" },
-      },
-    },
-  },
-}
-```
-
-## Notes
-
-- Moonshot model refs use `moonshot/<modelId>`. Kimi Coding model refs use `kimi-coding/<modelId>`.
-- Override pricing and context metadata in `models.providers` if needed.
-- If Moonshot publishes different context limits for a model, adjust
-  `contextWindow` accordingly.
-- Use `https://api.moonshot.ai/v1` for the international endpoint, and `https://api.moonshot.cn/v1` for the China endpoint.

package/docs/providers/nvidia.md

@@ -1,55 +0,0 @@
----
-summary: "Use NVIDIA's OpenAI-compatible API in Symi"
-read_when:
-  - You want to use NVIDIA models in Symi
-  - You need NVIDIA_API_KEY setup
-title: "NVIDIA"
----
-
-# NVIDIA
-
-NVIDIA provides an OpenAI-compatible API at `https://integrate.api.nvidia.com/v1` for Nemotron and NeMo models. Authenticate with an API key from [NVIDIA NGC](https://catalog.ngc.nvidia.com/).
-
-## CLI setup
-
-Export the key once, then run onboarding and set an NVIDIA model:
-
-```bash
-export NVIDIA_API_KEY="nvapi-..."
-symi onboard --auth-choice skip
-symi models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct
-```
-
-If you still pass `--token`, remember it lands in shell history and `ps` output; prefer the env var when possible.
-
-## Config snippet
-
-```json5
-{
-  env: { NVIDIA_API_KEY: "nvapi-..." },
-  models: {
-    providers: {
-      nvidia: {
-        baseUrl: "https://integrate.api.nvidia.com/v1",
-        api: "openai-completions",
-      },
-    },
-  },
-  agents: {
-    defaults: {
-      model: { primary: "nvidia/nvidia/llama-3.1-nemotron-70b-instruct" },
-    },
-  },
-}
-```
-
-## Model IDs
-
-- `nvidia/llama-3.1-nemotron-70b-instruct` (default)
-- `meta/llama-3.3-70b-instruct`
-- `nvidia/mistral-nemo-minitron-8b-8k-instruct`
-
-## Notes
-
-- OpenAI-compatible `/v1` endpoint; use an API key from NVIDIA NGC.
-- Provider auto-enables when `NVIDIA_API_KEY` is set; uses static defaults (131,072-token context window, 4,096 max tokens).

package/docs/providers/ollama.md

@@ -1,250 +0,0 @@
----
-summary: "Run Symi with Ollama (local LLM runtime)"
-read_when:
-  - You want to run Symi with local models via Ollama
-  - You need Ollama setup and configuration guidance
-title: "Ollama"
----
-
-# Ollama
-
-Ollama is a local LLM runtime that makes it easy to run open-source models on your machine. Symi integrates with Ollama's native API (`/api/chat`), supporting streaming and tool calling, and can **auto-discover tool-capable models** when you opt in with `OLLAMA_API_KEY` (or an auth profile) and do not define an explicit `models.providers.ollama` entry.
-
-## Quick start
-
-1. Install Ollama: [https://ollama.ai](https://ollama.ai)
-
-2. Pull a model:
-
-```bash
-ollama pull gpt-oss:20b
-# or
-ollama pull llama3.3
-# or
-ollama pull qwen2.5-coder:32b
-# or
-ollama pull deepseek-r1:32b
-```
-
-3. Enable Ollama for Symi (any value works; Ollama doesn't require a real key):
-
-```bash
-# Set environment variable
-export OLLAMA_API_KEY="ollama-local"
-
-# Or configure in your config file
-symi config set models.providers.ollama.apiKey "ollama-local"
-```
-
-4. Use Ollama models:
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "ollama/gpt-oss:20b" },
-    },
-  },
-}
-```
-
-## Model discovery (implicit provider)
-
-When you set `OLLAMA_API_KEY` (or an auth profile) and **do not** define `models.providers.ollama`, Symi discovers models from the local Ollama instance at `http://127.0.0.1:11434`:
-
-- Queries `/api/tags` and `/api/show`
-- Keeps only models that report `tools` capability
-- Marks `reasoning` when the model reports `thinking`
-- Reads `contextWindow` from `model_info["<arch>.context_length"]` when available
-- Sets `maxTokens` to 10× the context window
-- Sets all costs to `0`
-
-This avoids manual model entries while keeping the catalog aligned with Ollama's capabilities.
-
-To see what models are available:
-
-```bash
-ollama list
-symi models list
-```
-
-To add a new model, simply pull it with Ollama:
-
-```bash
-ollama pull mistral
-```
-
-The new model will be automatically discovered and available to use.
-
-If you set `models.providers.ollama` explicitly, auto-discovery is skipped and you must define models manually (see below).
-
-## Configuration
-
-### Basic setup (implicit discovery)
-
-The simplest way to enable Ollama is via environment variable:
-
-```bash
-export OLLAMA_API_KEY="ollama-local"
-```
-
-### Explicit setup (manual models)
-
-Use explicit config when:
-
-- Ollama runs on another host/port.
-- You want to force specific context windows or model lists.
-- You want to include models that do not report tool support.
-
-```json5
-{
-  models: {
-    providers: {
-      ollama: {
-        baseUrl: "http://ollama-host:11434",
-        apiKey: "ollama-local",
-        api: "ollama",
-        models: [
-          {
-            id: "gpt-oss:20b",
-            name: "GPT-OSS 20B",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 8192,
-            maxTokens: 8192 * 10
-          }
-        ]
-      }
-    }
-  }
-}
-```
-
-If `OLLAMA_API_KEY` is set, you can omit `apiKey` in the provider entry and Symi will fill it for availability checks.
-
-### Custom base URL (explicit config)
-
-If Ollama is running on a different host or port (explicit config disables auto-discovery, so define models manually):
-
-```json5
-{
-  models: {
-    providers: {
-      ollama: {
-        apiKey: "ollama-local",
-        baseUrl: "http://ollama-host:11434",
-      },
-    },
-  },
-}
-```
-
-### Model selection
-
-Once configured, all your Ollama models are available:
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: {
-        primary: "ollama/gpt-oss:20b",
-        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
-      },
-    },
-  },
-}
-```
-
-## Advanced
-
-### Reasoning models
-
-Symi marks models as reasoning-capable when Ollama reports `thinking` in `/api/show`:
-
-```bash
-ollama pull deepseek-r1:32b
-```
-
-### Model Costs
-
-Ollama is free and runs locally, so all model costs are set to $0.
-
-### Streaming Configuration
-
-Symi's Ollama integration uses the **native Ollama API** (`/api/chat`) by default, which fully supports streaming and tool calling simultaneously. No special configuration is needed.
-
-#### Legacy OpenAI-Compatible Mode
-
-If you need to use the OpenAI-compatible endpoint instead (e.g., behind a proxy that only supports OpenAI format), set `api: "openai-completions"` explicitly:
-
-```json5
-{
-  models: {
-    providers: {
-      ollama: {
-        baseUrl: "http://ollama-host:11434/v1",
-        api: "openai-completions",
-        apiKey: "ollama-local",
-        models: [...]
-      }
-    }
-  }
-}
-```
-
-Note: The OpenAI-compatible endpoint may not support streaming + tool calling simultaneously. You may need to disable streaming with `params: { streaming: false }` in model config.
-
-### Context windows
-
-For auto-discovered models, Symi uses the context window reported by Ollama when available, otherwise it defaults to `8192`. You can override `contextWindow` and `maxTokens` in explicit provider config.
-
-## Troubleshooting
-
-### Ollama not detected
-
-Make sure Ollama is running and that you set `OLLAMA_API_KEY` (or an auth profile), and that you did **not** define an explicit `models.providers.ollama` entry:
-
-```bash
-ollama serve
-```
-
-And that the API is accessible:
-
-```bash
-curl http://localhost:11434/api/tags
-```
-
-### No models available
-
-Symi only auto-discovers models that report tool support. If your model isn't listed, either:
-
-- Pull a tool-capable model, or
-- Define the model explicitly in `models.providers.ollama`.
-
-To add models:
-
-```bash
-ollama list  # See what's installed
-ollama pull gpt-oss:20b  # Pull a tool-capable model
-ollama pull llama3.3     # Or another model
-```
-
-### Connection refused
-
-Check that Ollama is running on the correct port:
-
-```bash
-# Check if Ollama is running
-ps aux | grep ollama
-
-# Or restart Ollama
-ollama serve
-```
-
-## See Also
-
-- [Model Providers](/concepts/model-providers) - Overview of all providers
-- [Model Selection](/concepts/models) - How to choose models
-- [Configuration](/gateway/configuration) - Full config reference