fengming 0.3.10 → 0.3.12

package/docs/providers/groq.md

@@ -1,171 +0,0 @@
----
-summary: "Groq setup (auth + model selection + Whisper transcription)"
-title: "Groq"
-read_when:
-  - You want to use Groq with FengMing
-  - You need the API key env var or CLI auth choice
-  - You are configuring Whisper audio transcription on Groq
----
-
-[Groq](https://groq.com) provides ultra-fast inference on open-weight models (Llama, Gemma, Kimi, Qwen, GPT OSS, and more) using custom LPU hardware. FengMing includes a bundled Groq plugin that registers both an OpenAI-compatible chat provider and an audio media-understanding provider.
-
-| Property               | Value                                    |
-| ---------------------- | ---------------------------------------- |
-| Provider id            | `groq`                                   |
-| Plugin                 | bundled, `enabledByDefault: true`        |
-| Auth env var           | `GROQ_API_KEY`                           |
-| Onboarding flag        | `--auth-choice groq-api-key`             |
-| API                    | OpenAI-compatible (`openai-completions`) |
-| Base URL               | `https://api.groq.com/openai/v1`         |
-| Audio transcription    | `whisper-large-v3-turbo` (default)       |
-| Suggested chat default | `groq/llama-3.3-70b-versatile`           |
-
-## Getting started
-
-<Steps>
-  <Step title="Get an API key">
-    Create an API key at [console.groq.com/keys](https://console.groq.com/keys).
-  </Step>
-  <Step title="Set the API key">
-    <CodeGroup>
-
-```bash Onboarding
-fengming onboard --auth-choice groq-api-key
-```
-
-```bash Env only
-export GROQ_API_KEY=gsk_...
-```
-
-    </CodeGroup>
-
-  </Step>
-  <Step title="Set a default model">
-    ```json5
-    {
-      agents: {
-        defaults: {
-          model: { primary: "groq/llama-3.3-70b-versatile" },
-        },
-      },
-    }
-    ```
-  </Step>
-  <Step title="Verify the catalog is reachable">
-    ```bash
-    fengming models list --provider groq
-    ```
-  </Step>
-</Steps>
-
-### Config file example
-
-```json5
-{
-  env: { GROQ_API_KEY: "gsk_..." },
-  agents: {
-    defaults: {
-      model: { primary: "groq/llama-3.3-70b-versatile" },
-    },
-  },
-}
-```
-
-## Built-in catalog
-
-FengMing ships a manifest-backed Groq catalog with both reasoning and non-reasoning entries. Run `fengming models list --provider groq` to see the bundled rows for your installed version, or check [console.groq.com/docs/models](https://console.groq.com/docs/models) for Groq's authoritative list.
-
-| Model ref                                        | Name                    | Reasoning | Input        | Context |
-| ------------------------------------------------ | ----------------------- | --------- | ------------ | ------- |
-| `groq/llama-3.3-70b-versatile`                   | Llama 3.3 70B Versatile | no        | text         | 131,072 |
-| `groq/llama-3.1-8b-instant`                      | Llama 3.1 8B Instant    | no        | text         | 131,072 |
-| `groq/meta-llama/llama-4-scout-17b-16e-instruct` | Llama 4 Scout 17B       | no        | text + image | 131,072 |
-| `groq/openai/gpt-oss-120b`                       | GPT OSS 120B            | yes       | text         | 131,072 |
-| `groq/openai/gpt-oss-20b`                        | GPT OSS 20B             | yes       | text         | 131,072 |
-| `groq/openai/gpt-oss-safeguard-20b`              | Safety GPT OSS 20B      | yes       | text         | 131,072 |
-| `groq/qwen/qwen3-32b`                            | Qwen3 32B               | yes       | text         | 131,072 |
-| `groq/groq/compound`                             | Compound                | yes       | text         | 131,072 |
-| `groq/groq/compound-mini`                        | Compound Mini           | yes       | text         | 131,072 |
-
-<Tip>
-  The catalog evolves with each FengMing release. `fengming models list --provider groq` shows the rows known to your installed version; cross-check with [console.groq.com/docs/models](https://console.groq.com/docs/models) for newly-added or deprecated models.
-</Tip>
-
-## Reasoning models
-
-FengMing maps its shared `/think` levels to Groq's model-specific `reasoning_effort` values:
-
-- For `qwen/qwen3-32b`, disabled thinking sends `none` and enabled thinking sends `default`.
-- For Groq GPT OSS reasoning models (`openai/gpt-oss-*`), FengMing sends `low`, `medium`, or `high` based on `/think` level. Disabled thinking omits `reasoning_effort` because those models do not support a disabled value.
-- DeepSeek R1 Distill, Qwen QwQ, and Compound use Groq's native reasoning surface; `/think` controls visibility but the model always reasons.
-
-See [Thinking modes](/tools/thinking) for the shared `/think` levels and how FengMing translates them per provider.
-
-## Audio transcription
-
-Groq's bundled plugin also registers an **audio media-understanding provider** so voice messages can be transcribed through the shared `tools.media.audio` surface.
-
-| Property           | Value                                     |
-| ------------------ | ----------------------------------------- |
-| Shared config path | `tools.media.audio`                       |
-| Default base URL   | `https://api.groq.com/openai/v1`          |
-| Default model      | `whisper-large-v3-turbo`                  |
-| Auto priority      | 20                                        |
-| API endpoint       | OpenAI-compatible `/audio/transcriptions` |
-
-To make Groq the default audio backend:
-
-```json5
-{
-  tools: {
-    media: {
-      audio: {
-        models: [{ provider: "groq" }],
-      },
-    },
-  },
-}
-```
-
-<AccordionGroup>
-  <Accordion title="Environment availability for the daemon">
-    If the Gateway runs as a managed service (launchd, systemd, Docker), `GROQ_API_KEY` must be visible to that process — not just to your interactive shell.
-
-    <Warning>
-      A key exported only in an interactive shell will not help a launchd or systemd daemon unless that environment is imported there too. Set the key in `~/.fengming/.env` or via `env.shellEnv` to make it readable from the gateway process.
-    </Warning>
-
-  </Accordion>
-
-  <Accordion title="Custom Groq model ids">
-    FengMing accepts any Groq model id at runtime. Use the exact id shown by Groq and prefix it with `groq/`. The bundled catalog covers the common cases; uncatalogued ids fall through to the default OpenAI-compatible template.
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          model: { primary: "groq/<your-model-id>" },
-        },
-      },
-    }
-    ```
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Model providers" href="/concepts/model-providers" icon="layers">
-    Choosing providers, model refs, and failover behavior.
-  </Card>
-  <Card title="Thinking modes" href="/tools/thinking" icon="brain">
-    Reasoning effort levels and provider-policy interaction.
-  </Card>
-  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
-    Full config schema including provider and audio settings.
-  </Card>
-  <Card title="Groq Console" href="https://console.groq.com" icon="arrow-up-right-from-square">
-    Groq dashboard, API docs, and pricing.
-  </Card>
-</CardGroup>

package/docs/providers/huggingface.md

@@ -1,235 +0,0 @@
----
-summary: "Hugging Face Inference setup (auth + model selection)"
-read_when:
-  - You want to use Hugging Face Inference with FengMing
-  - You need the HF token env var or CLI auth choice
-title: "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. FengMing 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.
-
-## Getting started
-
-<Steps>
-  <Step title="Create a fine-grained token">
-    Go to [Hugging Face Settings Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) and create a new fine-grained token.
-
-    <Warning>
-    The token must have the **Make calls to Inference Providers** permission enabled or API requests will be rejected.
-    </Warning>
-
-  </Step>
-  <Step title="Run onboarding">
-    Choose **Hugging Face** in the provider dropdown, then enter your API key when prompted:
-
-    ```bash
-    fengming onboard --auth-choice huggingface-api-key
-    ```
-
-  </Step>
-  <Step title="Select a default model">
-    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.
-
-    You can also set or change the default model later in config:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
-        },
-      },
-    }
-    ```
-
-  </Step>
-  <Step title="Verify the model is available">
-    ```bash
-    fengming models list --provider huggingface
-    ```
-  </Step>
-</Steps>
-
-### Non-interactive setup
-
-```bash
-fengming 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.
-
-## Model IDs
-
-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.
-
-| 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`              |
-
-<Tip>
-You can append `:fastest` or `:cheapest` to any 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.
-</Tip>
-
-## Advanced configuration
-
-<AccordionGroup>
-  <Accordion title="Model discovery and onboarding dropdown">
-    FengMing 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`), FengMing 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, FengMing 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.
-
-  </Accordion>
-
-  <Accordion title="Model names, aliases, and policy suffixes">
-    - **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` becomes "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:** FengMing'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.
-
-  </Accordion>
-
-  <Accordion title="Environment and daemon setup">
-    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 `~/.fengming/.env` or via `env.shellEnv`).
-
-    <Note>
-    FengMing accepts both `HUGGINGFACE_HUB_TOKEN` and `HF_TOKEN` as env var aliases. Either one works; if both are set, `HUGGINGFACE_HUB_TOKEN` takes precedence.
-    </Note>
-
-  </Accordion>
-
-  <Accordion title="Config: 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" },
-          },
-        },
-      },
-    }
-    ```
-  </Accordion>
-
-  <Accordion title="Config: Qwen 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)" },
-          },
-        },
-      },
-    }
-    ```
-  </Accordion>
-
-  <Accordion title="Config: 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" },
-          },
-        },
-      },
-    }
-    ```
-  </Accordion>
-
-  <Accordion title="Config: Multiple Qwen and DeepSeek 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" },
-          },
-        },
-      },
-    }
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
-    Overview of all providers, model refs, and failover behavior.
-  </Card>
-  <Card title="Model selection" href="/concepts/models" icon="brain">
-    How to choose and configure models.
-  </Card>
-  <Card title="Inference Providers docs" href="https://huggingface.co/docs/inference-providers" icon="book">
-    Official Hugging Face Inference Providers documentation.
-  </Card>
-  <Card title="Configuration" href="/gateway/configuration" icon="gear">
-    Full config reference.
-  </Card>
-</CardGroup>

package/docs/providers/index.md

@@ -1,105 +0,0 @@
----
-summary: "Model providers (LLMs) supported by FengMing"
-read_when:
-  - You want to choose a model provider
-  - You need a quick overview of supported LLM backends
-title: "Provider directory"
----
-
-FengMing 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 `fengming onboard`).
-2. Set the default model:
-
-```json5
-{
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
-}
-```
-
-## Provider docs
-
-- [Alibaba Model Studio](/providers/alibaba)
-- [Amazon Bedrock](/providers/bedrock)
-- [Amazon Bedrock Mantle](/providers/bedrock-mantle)
-- [Anthropic (API + Claude CLI)](/providers/anthropic)
-- [Arcee AI (Trinity models)](/providers/arcee)
-- [Azure Speech](/providers/azure-speech)
-- [BytePlus (International)](/concepts/model-providers#byteplus-international)
-- [Cerebras](/providers/cerebras)
-- [Chutes](/providers/chutes)
-- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
-- [ComfyUI](/providers/comfy)
-- [DeepSeek](/providers/deepseek)
-- [ds4 (local DeepSeek V4)](/providers/ds4)
-- [ElevenLabs](/providers/elevenlabs)
-- [fal](/providers/fal)
-- [Fireworks](/providers/fireworks)
-- [GitHub Copilot](/providers/github-copilot)
-- [GMI Cloud](/providers/gmi)
-- [Google (Gemini)](/providers/google)
-- [Gradium](/providers/gradium)
-- [Groq (LPU inference)](/providers/groq)
-- [Hugging Face (Inference)](/providers/huggingface)
-- [inferrs (local models)](/providers/inferrs)
-- [Kilocode](/providers/kilocode)
-- [LiteLLM (unified gateway)](/providers/litellm)
-- [LM Studio (local models)](/providers/lmstudio)
-- [MiniMax](/providers/minimax)
-- [Mistral](/providers/mistral)
-- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
-- [NVIDIA](/providers/nvidia)
-- [NovitaAI](/providers/novita)
-- [Ollama (cloud + local models)](/providers/ollama)
-- [Ollama Cloud](/providers/ollama-cloud)
-- [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 OAuth / Portal](/providers/qwen-oauth)
-- [Runway](/providers/runway)
-- [SenseAudio](/providers/senseaudio)
-- [SGLang (local models)](/providers/sglang)
-- [StepFun](/providers/stepfun)
-- [Synthetic](/providers/synthetic)
-- [Tencent Cloud (TokenHub)](/providers/tencent)
-- [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)
-- [Vydra](/providers/vydra)
-- [xAI](/providers/xai)
-- [Xiaomi](/providers/xiaomi)
-- [Z.AI (GLM)](/providers/zai)
-
-## Shared overview pages
-
-- [Additional bundled variants](/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy, and Gemini CLI OAuth
-- [Image Generation](/tools/image-generation) - Shared `image_generate` tool, provider selection, and failover
-- [Music Generation](/tools/music-generation) - Shared `music_generate` tool, provider selection, and failover
-- [Video Generation](/tools/video-generation) - Shared `video_generate` tool, provider selection, and failover
-
-## Transcription providers
-
-- [Deepgram (audio transcription)](/providers/deepgram)
-- [ElevenLabs](/providers/elevenlabs#speech-to-text)
-- [Mistral](/providers/mistral#audio-transcription-voxtral)
-- [OpenAI](/providers/openai#speech-to-text)
-- [SenseAudio](/providers/senseaudio)
-- [xAI](/providers/xai#speech-to-text)
-
-## 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).