@symerian/symi 3.0.20 → 3.0.22

package/docs/providers/github-copilot.md

@@ -1,72 +0,0 @@
----
-summary: "Sign in to GitHub Copilot from Symi using the device flow"
-read_when:
-  - You want to use GitHub Copilot as a model provider
-  - You need the `symi models auth login-github-copilot` flow
-title: "GitHub Copilot"
----
-
-# GitHub Copilot
-
-## What is GitHub Copilot?
-
-GitHub Copilot is GitHub's AI coding assistant. It provides access to Copilot
-models for your GitHub account and plan. Symi can use Copilot as a model
-provider in two different ways.
-
-## Two ways to use Copilot in Symi
-
-### 1) Built-in GitHub Copilot provider (`github-copilot`)
-
-Use the native device-login flow to obtain a GitHub token, then exchange it for
-Copilot API tokens when Symi runs. This is the **default** and simplest path
-because it does not require VS Code.
-
-### 2) Copilot Proxy plugin (`copilot-proxy`)
-
-Use the **Copilot Proxy** VS Code extension as a local bridge. Symi talks to
-the proxy’s `/v1` endpoint and uses the model list you configure there. Choose
-this when you already run Copilot Proxy in VS Code or need to route through it.
-You must enable the plugin and keep the VS Code extension running.
-
-Use GitHub Copilot as a model provider (`github-copilot`). The login command runs
-the GitHub device flow, saves an auth profile, and updates your config to use that
-profile.
-
-## CLI setup
-
-```bash
-symi models auth login-github-copilot
-```
-
-You'll be prompted to visit a URL and enter a one-time code. Keep the terminal
-open until it completes.
-
-### Optional flags
-
-```bash
-symi models auth login-github-copilot --profile-id github-copilot:work
-symi models auth login-github-copilot --yes
-```
-
-## Set a default model
-
-```bash
-symi models set github-copilot/gpt-4o
-```
-
-### Config snippet
-
-```json5
-{
-  agents: { defaults: { model: { primary: "github-copilot/gpt-4o" } } },
-}
-```
-
-## Notes
-
-- Requires an interactive TTY; run it directly in a terminal.
-- Copilot model availability depends on your plan; if a model is rejected, try
-  another ID (for example `github-copilot/gpt-4.1`).
-- The login stores a GitHub token in the auth profile store and exchanges it for a
-  Copilot API token when Symi runs.

package/docs/providers/glm.md

@@ -1,33 +0,0 @@
----
-summary: "GLM model family overview + how to use it in Symi"
-read_when:
-  - You want GLM models in Symi
-  - You need the model naming convention and setup
-title: "GLM Models"
----
-
-# GLM models
-
-GLM is a **model family** (not a company) available through the Z.AI platform. In Symi, GLM
-models are accessed via the `zai` provider and model IDs like `zai/glm-5`.
-
-## CLI setup
-
-```bash
-symi onboard --auth-choice zai-api-key
-```
-
-## Config snippet
-
-```json5
-{
-  env: { ZAI_API_KEY: "sk-..." },
-  agents: { defaults: { model: { primary: "zai/glm-5" } } },
-}
-```
-
-## Notes
-
-- GLM versions and availability can change; check Z.AI's docs for the latest.
-- Example model IDs include `glm-5`, `glm-4.7`, and `glm-4.6`.
-- For provider details, see [/providers/zai](/providers/zai).

package/docs/providers/huggingface.md

@@ -1,209 +0,0 @@
----
-summary: "Hugging Face Inference setup (auth + model selection)"
-read_when:
-  - You want to use Hugging Face Inference with Symi
-  - You need the HF token env var or CLI auth choice
-title: "Hugging Face (Inference)"
----
-
-# Hugging Face (Inference)
-
-[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) offer OpenAI-compatible chat completions through a single router API. You get access to many models (DeepSeek, Llama, and more) with one token. Symi uses the **OpenAI-compatible endpoint** (chat completions only); for text-to-image, embeddings, or speech use the [HF inference clients](https://huggingface.co/docs/api-inference/quicktour) directly.
-
-- Provider: `huggingface`
-- Auth: `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` (fine-grained token with **Make calls to Inference Providers**)
-- API: OpenAI-compatible (`https://router.huggingface.co/v1`)
-- Billing: Single HF token; [pricing](https://huggingface.co/docs/inference-providers/pricing) follows provider rates with a free tier.
-
-## Quick start
-
-1. Create a fine-grained token at [Hugging Face → Settings → Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) with the **Make calls to Inference Providers** permission.
-2. Run onboarding and choose **Hugging Face** in the provider dropdown, then enter your API key when prompted:
-
-```bash
-symi onboard --auth-choice huggingface-api-key
-```
-
-3. In the **Default Hugging Face model** dropdown, pick the model you want (the list is loaded from the Inference API when you have a valid token; otherwise a built-in list is shown). Your choice is saved as the default model.
-4. You can also set or change the default model later in config:
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
-    },
-  },
-}
-```
-
-## Non-interactive example
-
-```bash
-symi onboard --non-interactive \
-  --mode local \
-  --auth-choice huggingface-api-key \
-  --huggingface-api-key "$HF_TOKEN"
-```
-
-This will set `huggingface/deepseek-ai/DeepSeek-R1` as the default model.
-
-## Environment note
-
-If the Gateway runs as a daemon (launchd/systemd), make sure `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN`
-is available to that process (for example, in `~/.symi/.env` or via
-`env.shellEnv`).
-
-## Model discovery and onboarding dropdown
-
-Symi discovers models by calling the **Inference endpoint directly**:
-
-```bash
-GET https://router.huggingface.co/v1/models
-```
-
-(Optional: send `Authorization: Bearer $HUGGINGFACE_HUB_TOKEN` or `$HF_TOKEN` for the full list; some endpoints return a subset without auth.) The response is OpenAI-style `{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`.
-
-When you configure a Hugging Face API key (via onboarding, `HUGGINGFACE_HUB_TOKEN`, or `HF_TOKEN`), Symi uses this GET to discover available chat-completion models. During **interactive onboarding**, after you enter your token you see a **Default Hugging Face model** dropdown populated from that list (or the built-in catalog if the request fails). At runtime (e.g. Gateway startup), when a key is present, Symi again calls **GET** `https://router.huggingface.co/v1/models` to refresh the catalog. The list is merged with a built-in catalog (for metadata like context window and cost). If the request fails or no key is set, only the built-in catalog is used.
-
-## Model names and editable options
-
-- **Name from API:** The model display name is **hydrated from GET /v1/models** when the API returns `name`, `title`, or `display_name`; otherwise it is derived from the model id (e.g. `deepseek-ai/DeepSeek-R1` → “DeepSeek R1”).
-- **Override display name:** You can set a custom label per model in config so it appears the way you want in the CLI and UI:
-
-```json5
-{
-  agents: {
-    defaults: {
-      models: {
-        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
-        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
-      },
-    },
-  },
-}
-```
-
-- **Provider / policy selection:** Append a suffix to the **model id** to choose how the router picks the backend:
-  - **`:fastest`** — highest throughput (router picks; provider choice is **locked** — no interactive backend picker).
-  - **`:cheapest`** — lowest cost per output token (router picks; provider choice is **locked**).
-  - **`:provider`** — force a specific backend (e.g. `:sambanova`, `:together`).
-
-  When you select **:cheapest** or **:fastest** (e.g. in the onboarding model dropdown), the provider is locked: the router decides by cost or speed and no optional “prefer specific backend” step is shown. You can add these as separate entries in `models.providers.huggingface.models` or set `model.primary` with the suffix. You can also set your default order in [Inference Provider settings](https://hf.co/settings/inference-providers) (no suffix = use that order).
-
-- **Config merge:** Existing entries in `models.providers.huggingface.models` (e.g. in `models.json`) are kept when config is merged. So any custom `name`, `alias`, or model options you set there are preserved.
-
-## Model IDs and configuration examples
-
-Model refs use the form `huggingface/<org>/<model>` (Hub-style IDs). The list below is from **GET** `https://router.huggingface.co/v1/models`; your catalog may include more.
-
-**Example IDs (from the inference endpoint):**
-
-| Model                  | Ref (prefix with `huggingface/`)    |
-| ---------------------- | ----------------------------------- |
-| DeepSeek R1            | `deepseek-ai/DeepSeek-R1`           |
-| DeepSeek V3.2          | `deepseek-ai/DeepSeek-V3.2`         |
-| Qwen3 8B               | `Qwen/Qwen3-8B`                     |
-| Qwen2.5 7B Instruct    | `Qwen/Qwen2.5-7B-Instruct`          |
-| Qwen3 32B              | `Qwen/Qwen3-32B`                    |
-| Llama 3.3 70B Instruct | `meta-llama/Llama-3.3-70B-Instruct` |
-| Llama 3.1 8B Instruct  | `meta-llama/Llama-3.1-8B-Instruct`  |
-| GPT-OSS 120B           | `openai/gpt-oss-120b`               |
-| GLM 4.7                | `zai-org/GLM-4.7`                   |
-| Kimi K2.5              | `moonshotai/Kimi-K2.5`              |
-
-You can append `:fastest`, `:cheapest`, or `:provider` (e.g. `:together`, `:sambanova`) to the model id. Set your default order in [Inference Provider settings](https://hf.co/settings/inference-providers); see [Inference Providers](https://huggingface.co/docs/inference-providers) and **GET** `https://router.huggingface.co/v1/models` for the full list.
-
-### Complete configuration examples
-
-**Primary DeepSeek R1 with Qwen fallback:**
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: {
-        primary: "huggingface/deepseek-ai/DeepSeek-R1",
-        fallbacks: ["huggingface/Qwen/Qwen3-8B"],
-      },
-      models: {
-        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
-        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
-      },
-    },
-  },
-}
-```
-
-**Qwen as default, with :cheapest and :fastest variants:**
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "huggingface/Qwen/Qwen3-8B" },
-      models: {
-        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
-        "huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (cheapest)" },
-        "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (fastest)" },
-      },
-    },
-  },
-}
-```
-
-**DeepSeek + Llama + GPT-OSS with aliases:**
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: {
-        primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
-        fallbacks: [
-          "huggingface/meta-llama/Llama-3.3-70B-Instruct",
-          "huggingface/openai/gpt-oss-120b",
-        ],
-      },
-      models: {
-        "huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
-        "huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
-        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
-      },
-    },
-  },
-}
-```
-
-**Force a specific backend with :provider:**
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1:together" },
-      models: {
-        "huggingface/deepseek-ai/DeepSeek-R1:together": { alias: "DeepSeek R1 (Together)" },
-      },
-    },
-  },
-}
-```
-
-**Multiple Qwen and DeepSeek models with policy suffixes:**
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
-      models: {
-        "huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
-        "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B (cheap)" },
-        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fast)" },
-        "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
-      },
-    },
-  },
-}
-```

package/docs/providers/index.md

@@ -1,67 +0,0 @@
----
-summary: "Model providers (LLMs) supported by Symi"
-read_when:
-  - You want to choose a model provider
-  - You need a quick overview of supported LLM backends
-title: "Model Providers"
----
-
-# Model Providers
-
-Symi can use many LLM providers. Pick a provider, 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 hard tasks.
-
-- Default: `venice/llama-3.3-70b`
-- Best overall: `venice/claude-opus-45` (Opus remains the strongest)
-
-See [Venice AI](/providers/venice).
-
-## Quick start
-
-1. Authenticate with the provider (usually via `symi onboard`).
-2. Set the default model:
-
-```json5
-{
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
-}
-```
-
-## Provider docs
-
-- [OpenAI (API + Codex)](/providers/openai)
-- [Anthropic (API + Claude Code CLI)](/providers/anthropic)
-- [Qwen (OAuth)](/providers/qwen)
-- [OpenRouter](/providers/openrouter)
-- [LiteLLM (unified gateway)](/providers/litellm)
-- [Vercel AI Gateway](/providers/vercel-ai-gateway)
-- [Together AI](/providers/together)
-- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
-- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
-- [OpenCode Zen](/providers/opencode)
-- [Amazon Bedrock](/providers/bedrock)
-- [Z.AI](/providers/zai)
-- [Xiaomi](/providers/xiaomi)
-- [GLM models](/providers/glm)
-- [MiniMax](/providers/minimax)
-- [Venice (Venice AI, privacy-focused)](/providers/venice)
-- [Hugging Face (Inference)](/providers/huggingface)
-- [Ollama (local models)](/providers/ollama)
-- [vLLM (local models)](/providers/vllm)
-- [Qianfan](/providers/qianfan)
-- [NVIDIA](/providers/nvidia)
-
-## Transcription providers
-
-- [Deepgram (audio transcription)](/providers/deepgram)
-
-## Community tools
-
-- [Claude Max API Proxy](/providers/claude-max-api-proxy) - Use Claude Max/Pro subscription as an OpenAI-compatible API endpoint
-
-For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
-see [Model providers](/concepts/model-providers).

package/docs/providers/litellm.md

@@ -1,153 +0,0 @@
----
-summary: "Run Symi through LiteLLM Proxy for unified model access and cost tracking"
-read_when:
-  - You want to route Symi through a LiteLLM proxy
-  - You need cost tracking, logging, or model routing through LiteLLM
----
-
-# LiteLLM
-
-[LiteLLM](https://litellm.ai) is an open-source LLM gateway that provides a unified API to 100+ model providers. Route Symi through LiteLLM to get centralized cost tracking, logging, and the flexibility to switch backends without changing your Symi config.
-
-## Why use LiteLLM with Symi?
-
-- **Cost tracking** — See exactly what Symi spends across all models
-- **Model routing** — Switch between Claude, GPT-4, Gemini, Bedrock without config changes
-- **Virtual keys** — Create keys with spend limits for Symi
-- **Logging** — Full request/response logs for debugging
-- **Fallbacks** — Automatic failover if your primary provider is down
-
-## Quick start
-
-### Via onboarding
-
-```bash
-symi onboard --auth-choice litellm-api-key
-```
-
-### Manual setup
-
-1. Start LiteLLM Proxy:
-
-```bash
-pip install 'litellm[proxy]'
-litellm --model claude-opus-4-6
-```
-
-2. Point Symi to LiteLLM:
-
-```bash
-export LITELLM_API_KEY="your-litellm-key"
-
-symi
-```
-
-That's it. Symi now routes through LiteLLM.
-
-## Configuration
-
-### Environment variables
-
-```bash
-export LITELLM_API_KEY="sk-litellm-key"
-```
-
-### Config file
-
-```json5
-{
-  models: {
-    providers: {
-      litellm: {
-        baseUrl: "http://localhost:4000",
-        apiKey: "${LITELLM_API_KEY}",
-        api: "openai-completions",
-        models: [
-          {
-            id: "claude-opus-4-6",
-            name: "Claude Opus 4.6",
-            reasoning: true,
-            input: ["text", "image"],
-            contextWindow: 200000,
-            maxTokens: 64000,
-          },
-          {
-            id: "gpt-4o",
-            name: "GPT-4o",
-            reasoning: false,
-            input: ["text", "image"],
-            contextWindow: 128000,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-  agents: {
-    defaults: {
-      model: { primary: "litellm/claude-opus-4-6" },
-    },
-  },
-}
-```
-
-## Virtual keys
-
-Create a dedicated key for Symi with spend limits:
-
-```bash
-curl -X POST "http://localhost:4000/key/generate" \
-  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "key_alias": "symi",
-    "max_budget": 50.00,
-    "budget_duration": "monthly"
-  }'
-```
-
-Use the generated key as `LITELLM_API_KEY`.
-
-## Model routing
-
-LiteLLM can route model requests to different backends. Configure in your LiteLLM `config.yaml`:
-
-```yaml
-model_list:
-  - model_name: claude-opus-4-6
-    litellm_params:
-      model: claude-opus-4-6
-      api_key: os.environ/ANTHROPIC_API_KEY
-
-  - model_name: gpt-4o
-    litellm_params:
-      model: gpt-4o
-      api_key: os.environ/OPENAI_API_KEY
-```
-
-Symi keeps requesting `claude-opus-4-6` — LiteLLM handles the routing.
-
-## Viewing usage
-
-Check LiteLLM's dashboard or API:
-
-```bash
-# Key info
-curl "http://localhost:4000/key/info" \
-  -H "Authorization: Bearer sk-litellm-key"
-
-# Spend logs
-curl "http://localhost:4000/spend/logs" \
-  -H "Authorization: Bearer $LITELLM_MASTER_KEY"
-```
-
-## Notes
-
-- LiteLLM runs on `http://localhost:4000` by default
-- Symi connects via the OpenAI-compatible `/v1/chat/completions` endpoint
-- All Symi features work through LiteLLM — no limitations
-
-## See also
-
-- [LiteLLM Docs](https://docs.litellm.ai)
-- [Model Providers](/concepts/model-providers)