durar-ai 2026.4.4

package/docs/providers/huggingface.md

@@ -0,0 +1,193 @@
+---
+summary: "Hugging Face Inference setup (auth + model selection)"
+read_when:
+  - You want to use Hugging Face Inference with Durar
+  - 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. Durar 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
+Durar 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
+Durar 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 `~/.Durar/.env` or via
+`env.shellEnv`).
+
+## Model discovery and onboarding dropdown
+
+Durar 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`), Durar uses this GET to discover available chat-completion models. During **interactive setup**, 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, Durar 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)" },
+      },
+    },
+  },
+}
+```
+
+- **Policy suffixes:** Durar's bundled Hugging Face docs and helpers currently treat these two suffixes as the built-in policy variants:
+  - **`:fastest`** — highest throughput.
+  - **`:cheapest`** — lowest cost per output token.
+
+  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 provider 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` or `:cheapest` 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" },
+      },
+    },
+  },
+}
+```
+
+**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

@@ -0,0 +1,81 @@
+---
+summary: "Model providers (LLMs) supported by Durar"
+read_when:
+  - You want to choose a model provider
+  - You need a quick overview of supported LLM backends
+title: "Provider Directory"
+---
+
+# Model Providers
+
+Durar can use many LLM providers. Pick a provider, authenticate, then set the
+default model as `provider/model`.
+
+Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/etc.)? See [Channels](/channels).
+
+## Quick start
+
+1. Authenticate with the provider (usually via `Durar onboard`).
+2. Set the default model:
+
+```json5
+{
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## Provider docs
+
+- [Amazon Bedrock](/providers/bedrock)
+- [Anthropic (API + Claude CLI)](/providers/anthropic)
+- [BytePlus (International)](/concepts/model-providers#byteplus-international)
+- [Chutes](/providers/chutes)
+- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
+- [DeepSeek](/providers/deepseek)
+- [Fireworks](/providers/fireworks)
+- [GitHub Copilot](/providers/github-copilot)
+- [GLM models](/providers/glm)
+- [Google (Gemini)](/providers/google)
+- [Groq (LPU inference)](/providers/groq)
+- [Hugging Face (Inference)](/providers/huggingface)
+- [Kilocode](/providers/kilocode)
+- [LiteLLM (unified gateway)](/providers/litellm)
+- [MiniMax](/providers/minimax)
+- [Mistral](/providers/mistral)
+- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
+- [NVIDIA](/providers/nvidia)
+- [Ollama (cloud + local models)](/providers/ollama)
+- [OpenAI (API + Codex)](/providers/openai)
+- [OpenCode](/providers/opencode)
+- [OpenCode Go](/providers/opencode-go)
+- [OpenRouter](/providers/openrouter)
+- [Perplexity (web search)](/providers/perplexity-provider)
+- [Qianfan](/providers/qianfan)
+- [Qwen Cloud](/providers/qwen)
+- [Qwen / Model Studio (endpoint detail; `qwen-*` canonical, `modelstudio-*` legacy)](/providers/qwen_modelstudio)
+- [SGLang (local models)](/providers/sglang)
+- [StepFun](/providers/stepfun)
+- [Synthetic](/providers/synthetic)
+- [Together AI](/providers/together)
+- [Venice (Venice AI, privacy-focused)](/providers/venice)
+- [Vercel AI Gateway](/providers/vercel-ai-gateway)
+- [vLLM (local models)](/providers/vllm)
+- [Volcengine (Doubao)](/providers/volcengine)
+- [xAI](/providers/xai)
+- [Xiaomi](/providers/xiaomi)
+- [Z.AI](/providers/zai)
+
+## Shared overview pages
+
+- [Additional bundled variants](/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy, and Gemini CLI OAuth
+
+## Transcription providers
+
+- [Deepgram (audio transcription)](/providers/deepgram)
+
+## Community tools
+
+- [Claude Max API Proxy](/providers/claude-max-api-proxy) - Community proxy for Claude subscription credentials (verify Anthropic policy/terms before use)
+
+For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
+see [Model providers](/concepts/model-providers).

package/docs/providers/kilocode.md

@@ -0,0 +1,89 @@
+---
+title: "Kilo Gateway"
+summary: "Use Kilo Gateway's unified API to access many models in Durar"
+read_when:
+  - You want a single API key for many LLMs
+  - You want to run models via Kilo Gateway in Durar
+---
+
+# Kilo Gateway
+
+Kilo Gateway provides a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+## Getting an API key
+
+1. Go to [app.kilo.ai](https://app.kilo.ai)
+2. Sign in or create an account
+3. Navigate to API Keys and generate a new key
+
+## CLI setup
+
+```bash
+Durar onboard --auth-choice kilocode-api-key
+```
+
+Or set the environment variable:
+
+```bash
+export KILOCODE_API_KEY="<your-kilocode-api-key>" # pragma: allowlist secret
+```
+
+## Config snippet
+
+```json5
+{
+  env: { KILOCODE_API_KEY: "<your-kilocode-api-key>" }, // pragma: allowlist secret
+  agents: {
+    defaults: {
+      model: { primary: "kilocode/kilo/auto" },
+    },
+  },
+}
+```
+
+## Default model
+
+The default model is `kilocode/kilo/auto`, a provider-owned smart-routing
+model managed by Kilo Gateway.
+
+Durar treats `kilocode/kilo/auto` as the stable default ref, but does not
+publish a source-backed task-to-upstream-model mapping for that route.
+
+## Available models
+
+Durar dynamically discovers available models from the Kilo Gateway at startup. Use
+`/models kilocode` to see the full list of models available with your account.
+
+Any model available on the gateway can be used with the `kilocode/` prefix:
+
+```
+kilocode/kilo/auto              (default - smart routing)
+kilocode/anthropic/claude-sonnet-4
+kilocode/openai/gpt-5.4
+kilocode/google/gemini-3-pro-preview
+...and many more
+```
+
+## Notes
+
+- Model refs are `kilocode/<model-id>` (e.g., `kilocode/anthropic/claude-sonnet-4`).
+- Default model: `kilocode/kilo/auto`
+- Base URL: `https://api.kilo.ai/api/gateway/`
+- Bundled fallback catalog always includes `kilocode/kilo/auto` (`Kilo Auto`) with
+  `input: ["text", "image"]`, `reasoning: true`, `contextWindow: 1000000`,
+  and `maxTokens: 128000`
+- At startup, Durar tries `GET https://api.kilo.ai/api/gateway/models` and
+  merges discovered models ahead of the static fallback catalog
+- Exact upstream routing behind `kilocode/kilo/auto` is owned by Kilo Gateway,
+  not hard-coded in Durar
+- Kilo Gateway is documented in source as OpenRouter-compatible, so it stays on
+  the proxy-style OpenAI-compatible path rather than native OpenAI request shaping
+- Gemini-backed Kilo refs stay on the proxy-Gemini path, so Durar keeps
+  Gemini thought-signature sanitation there without enabling native Gemini
+  replay validation or bootstrap rewrites.
+- Kilo's shared stream wrapper adds the provider app header and normalizes
+  proxy reasoning payloads for supported concrete model refs. `kilocode/kilo/auto`
+  and other proxy-reasoning-unsupported hints skip that reasoning injection.
+- For more model/provider options, see [/concepts/model-providers](/concepts/model-providers).
+- Kilo Gateway uses a Bearer token with your API key under the hood.

package/docs/providers/litellm.md

@@ -0,0 +1,159 @@
+---
+title: "LiteLLM"
+summary: "Run Durar through LiteLLM Proxy for unified model access and cost tracking"
+read_when:
+  - You want to route Durar 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 Durar through LiteLLM to get centralized cost tracking, logging, and the flexibility to switch backends without changing your Durar config.
+
+## Why use LiteLLM with Durar?
+
+- **Cost tracking** — See exactly what Durar spends across all models
+- **Model routing** — Switch between Claude, GPT-4, Gemini, Bedrock without config changes
+- **Virtual keys** — Create keys with spend limits for Durar
+- **Logging** — Full request/response logs for debugging
+- **Fallbacks** — Automatic failover if your primary provider is down
+
+## Quick start
+
+### Via onboarding
+
+```bash
+Durar 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 Durar to LiteLLM:
+
+```bash
+export LITELLM_API_KEY="your-litellm-key"
+
+Durar
+```
+
+That's it. Durar 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 Durar 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": "Durar",
+    "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
+```
+
+Durar 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
+- Durar connects through LiteLLM's proxy-style OpenAI-compatible `/v1`
+  endpoint
+- Native OpenAI-only request shaping does not apply through LiteLLM:
+  no `service_tier`, no Responses `store`, no prompt-cache hints, and no
+  OpenAI reasoning-compat payload shaping
+- Hidden Durar attribution headers (`originator`, `version`, `User-Agent`)
+  are not injected on custom LiteLLM base URLs
+
+## See also
+
+- [LiteLLM Docs](https://docs.litellm.ai)
+- [Model Providers](/concepts/model-providers)