fengming 0.3.9 → 0.3.11

package/docs/providers/moonshot.md

@@ -1,413 +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 provides the Kimi API with OpenAI-compatible endpoints. Configure the
-provider and set the default model to `moonshot/kimi-k2.6`, or use
-Kimi Coding with `kimi/kimi-for-coding`.
-
-<Warning>
-Moonshot and Kimi Coding are **separate providers**. Keys are not interchangeable, endpoints differ, and model refs differ (`moonshot/...` vs `kimi/...`).
-</Warning>
-
-## Built-in model catalog
-
-[//]: # "moonshot-kimi-k2-ids:start"
-
-| Model ref                         | Name                   | Reasoning | Input       | Context | Max output |
-| --------------------------------- | ---------------------- | --------- | ----------- | ------- | ---------- |
-| `moonshot/kimi-k2.6`              | Kimi K2.6              | No        | text, image | 262,144 | 262,144    |
-| `moonshot/kimi-k2.5`              | Kimi K2.5              | No        | text, image | 262,144 | 262,144    |
-| `moonshot/kimi-k2-thinking`       | Kimi K2 Thinking       | Yes       | text        | 262,144 | 262,144    |
-| `moonshot/kimi-k2-thinking-turbo` | Kimi K2 Thinking Turbo | Yes       | text        | 262,144 | 262,144    |
-| `moonshot/kimi-k2-turbo`          | Kimi K2 Turbo          | No        | text        | 256,000 | 16,384     |
-
-[//]: # "moonshot-kimi-k2-ids:end"
-
-Bundled cost estimates for current Moonshot-hosted K2 models use Moonshot's
-published pay-as-you-go rates: Kimi K2.6 is $0.16/MTok cache hit,
-$0.95/MTok input, and $4.00/MTok output; Kimi K2.5 is $0.10/MTok cache hit,
-$0.60/MTok input, and $3.00/MTok output. Other legacy catalog entries keep
-zero-cost placeholders unless you override them in config.
-
-## Getting started
-
-Choose your provider and follow the setup steps.
-
-<Tabs>
-  <Tab title="Moonshot API">
-    **Best for:** Kimi K2 models via the Moonshot Open Platform.
-
-    <Steps>
-      <Step title="Choose your endpoint region">
-        | Auth choice            | Endpoint                       | Region        |
-        | ---------------------- | ------------------------------ | ------------- |
-        | `moonshot-api-key`     | `https://api.moonshot.ai/v1`   | International |
-        | `moonshot-api-key-cn`  | `https://api.moonshot.cn/v1`   | China         |
-      </Step>
-      <Step title="Run onboarding">
-        ```bash
-        fengming onboard --auth-choice moonshot-api-key
-        ```
-
-        Or for the China endpoint:
-
-        ```bash
-        fengming onboard --auth-choice moonshot-api-key-cn
-        ```
-      </Step>
-      <Step title="Set a default model">
-        ```json5
-        {
-          agents: {
-            defaults: {
-              model: { primary: "moonshot/kimi-k2.6" },
-            },
-          },
-        }
-        ```
-      </Step>
-      <Step title="Verify models are available">
-        ```bash
-        fengming models list --provider moonshot
-        ```
-      </Step>
-      <Step title="Run a live smoke test">
-        Use an isolated state dir when you want to verify model access and cost
-        tracking without touching your normal sessions:
-
-        ```bash
-        FENGMING_CONFIG_PATH=/tmp/fengming-kimi/fengming.json \
-        FENGMING_STATE_DIR=/tmp/fengming-kimi \
-        fengming agent --local \
-          --session-id live-kimi-cost \
-          --message 'Reply exactly: KIMI_LIVE_OK' \
-          --thinking off \
-          --json
-        ```
-
-        The JSON response should report `provider: "moonshot"` and
-        `model: "kimi-k2.6"`. The assistant transcript entry stores normalized
-        token usage plus estimated cost under `usage.cost` when Moonshot returns
-        usage metadata.
-      </Step>
-    </Steps>
-
-    ### Config example
-
-    ```json5
-    {
-      env: { MOONSHOT_API_KEY: "sk-..." },
-      agents: {
-        defaults: {
-          model: { primary: "moonshot/kimi-k2.6" },
-          models: {
-            // moonshot-kimi-k2-aliases:start
-            "moonshot/kimi-k2.6": { alias: "Kimi K2.6" },
-            "moonshot/kimi-k2.5": { alias: "Kimi K2.5" },
-            "moonshot/kimi-k2-thinking": { alias: "Kimi K2 Thinking" },
-            "moonshot/kimi-k2-thinking-turbo": { alias: "Kimi K2 Thinking Turbo" },
-            "moonshot/kimi-k2-turbo": { alias: "Kimi K2 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.6",
-                name: "Kimi K2.6",
-                reasoning: false,
-                input: ["text", "image"],
-                cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
-                contextWindow: 262144,
-                maxTokens: 262144,
-              },
-              {
-                id: "kimi-k2.5",
-                name: "Kimi K2.5",
-                reasoning: false,
-                input: ["text", "image"],
-                cost: { input: 0.6, output: 3, cacheRead: 0.1, cacheWrite: 0 },
-                contextWindow: 262144,
-                maxTokens: 262144,
-              },
-              {
-                id: "kimi-k2-thinking",
-                name: "Kimi K2 Thinking",
-                reasoning: true,
-                input: ["text"],
-                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-                contextWindow: 262144,
-                maxTokens: 262144,
-              },
-              {
-                id: "kimi-k2-thinking-turbo",
-                name: "Kimi K2 Thinking Turbo",
-                reasoning: true,
-                input: ["text"],
-                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-                contextWindow: 262144,
-                maxTokens: 262144,
-              },
-              {
-                id: "kimi-k2-turbo",
-                name: "Kimi K2 Turbo",
-                reasoning: false,
-                input: ["text"],
-                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-                contextWindow: 256000,
-                maxTokens: 16384,
-              },
-              // moonshot-kimi-k2-models:end
-            ],
-          },
-        },
-      },
-    }
-    ```
-
-  </Tab>
-
-  <Tab title="Kimi Coding">
-    **Best for:** code-focused tasks via the Kimi Coding endpoint.
-
-    <Note>
-    Kimi Coding uses a different API key and provider prefix (`kimi/...`) than Moonshot (`moonshot/...`). The stable API model ref is `kimi/kimi-for-coding`; legacy refs `kimi/kimi-code` and `kimi/k2p5` remain accepted and normalize to that API model id.
-    </Note>
-
-    <Steps>
-      <Step title="Run onboarding">
-        ```bash
-        fengming onboard --auth-choice kimi-code-api-key
-        ```
-      </Step>
-      <Step title="Set a default model">
-        ```json5
-        {
-          agents: {
-            defaults: {
-              model: { primary: "kimi/kimi-for-coding" },
-            },
-          },
-        }
-        ```
-      </Step>
-      <Step title="Verify the model is available">
-        ```bash
-        fengming models list --provider kimi
-        ```
-      </Step>
-    </Steps>
-
-    ### Config example
-
-    ```json5
-    {
-      env: { KIMI_API_KEY: "sk-..." },
-      agents: {
-        defaults: {
-          model: { primary: "kimi/kimi-for-coding" },
-          models: {
-            "kimi/kimi-for-coding": { alias: "Kimi" },
-          },
-        },
-      },
-    }
-    ```
-
-  </Tab>
-</Tabs>
-
-## Kimi web search
-
-FengMing also ships **Kimi** as a `web_search` provider, backed by Moonshot web
-search.
-
-<Steps>
-  <Step title="Run interactive web search setup">
-    ```bash
-    fengming configure --section web
-    ```
-
-    Choose **Kimi** in the web-search section to store
-    `plugins.entries.moonshot.config.webSearch.*`.
-
-  </Step>
-  <Step title="Configure the web search region and model">
-    Interactive setup prompts for:
-
-    | Setting             | Options                                                              |
-    | ------------------- | -------------------------------------------------------------------- |
-    | API region          | `https://api.moonshot.ai/v1` (international) or `https://api.moonshot.cn/v1` (China) |
-    | Web search model    | Defaults to `kimi-k2.6`                                             |
-
-  </Step>
-</Steps>
-
-Config lives under `plugins.entries.moonshot.config.webSearch`:
-
-```json5
-{
-  plugins: {
-    entries: {
-      moonshot: {
-        config: {
-          webSearch: {
-            apiKey: "sk-...", // or use KIMI_API_KEY / MOONSHOT_API_KEY
-            baseUrl: "https://api.moonshot.ai/v1",
-            model: "kimi-k2.6",
-          },
-        },
-      },
-    },
-  },
-  tools: {
-    web: {
-      search: {
-        provider: "kimi",
-      },
-    },
-  },
-}
-```
-
-## Advanced configuration
-
-<AccordionGroup>
-  <Accordion title="Native thinking mode">
-    Moonshot Kimi supports binary native thinking:
-
-    - `thinking: { type: "enabled" }`
-    - `thinking: { type: "disabled" }`
-
-    Configure it per model via `agents.defaults.models.<provider/model>.params`:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          models: {
-            "moonshot/kimi-k2.6": {
-              params: {
-                thinking: { type: "disabled" },
-              },
-            },
-          },
-        },
-      },
-    }
-    ```
-
-    FengMing also maps runtime `/think` levels for Moonshot:
-
-    | `/think` level       | Moonshot behavior          |
-    | -------------------- | -------------------------- |
-    | `/think off`         | `thinking.type=disabled`   |
-    | Any non-off level    | `thinking.type=enabled`    |
-
-    <Warning>
-    When Moonshot thinking is enabled, `tool_choice` must be `auto` or `none`. FengMing normalizes incompatible `tool_choice` values to `auto` for compatibility.
-    </Warning>
-
-    Kimi K2.6 also accepts an optional `thinking.keep` field that controls
-    multi-turn retention of `reasoning_content`. Set it to `"all"` to keep full
-    reasoning across turns; omit it (or leave it `null`) to use the server
-    default strategy. FengMing only forwards `thinking.keep` for
-    `moonshot/kimi-k2.6` and strips it from other models.
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          models: {
-            "moonshot/kimi-k2.6": {
-              params: {
-                thinking: { type: "enabled", keep: "all" },
-              },
-            },
-          },
-        },
-      },
-    }
-    ```
-
-  </Accordion>
-
-  <Accordion title="Tool call id sanitization">
-    Moonshot Kimi serves tool_call ids shaped like `functions.<name>:<index>`. FengMing preserves them unchanged so multi-turn tool calls keep working.
-
-    To force strict sanitization on a custom OpenAI-compatible provider, set `sanitizeToolCallIds: true`:
-
-    ```json5
-    {
-      models: {
-        providers: {
-          "my-kimi-proxy": {
-            api: "openai-completions",
-            sanitizeToolCallIds: true,
-          },
-        },
-      },
-    }
-    ```
-
-  </Accordion>
-
-  <Accordion title="Streaming usage compatibility">
-    Native Moonshot endpoints (`https://api.moonshot.ai/v1` and
-    `https://api.moonshot.cn/v1`) advertise streaming usage compatibility on the
-    shared `openai-completions` transport. FengMing keys that off endpoint
-    capabilities, so compatible custom provider ids targeting the same native
-    Moonshot hosts inherit the same streaming-usage behavior.
-
-    With the bundled K2.6 pricing, streamed usage that includes input, output,
-    and cache-read tokens is also converted into local estimated USD cost for
-    `/status`, `/usage full`, `/usage cost`, and transcript-backed session
-    accounting.
-
-  </Accordion>
-
-  <Accordion title="Endpoint and model ref reference">
-    | Provider   | Model ref prefix | Endpoint                      | Auth env var        |
-    | ---------- | ---------------- | ----------------------------- | ------------------- |
-    | Moonshot   | `moonshot/`      | `https://api.moonshot.ai/v1`  | `MOONSHOT_API_KEY`  |
-    | Moonshot CN| `moonshot/`      | `https://api.moonshot.cn/v1`  | `MOONSHOT_API_KEY`  |
-    | Kimi Coding| `kimi/`          | Kimi Coding endpoint          | `KIMI_API_KEY`      |
-    | Web search | N/A              | Same as Moonshot API region   | `KIMI_API_KEY` or `MOONSHOT_API_KEY` |
-
-    - Kimi web search uses `KIMI_API_KEY` or `MOONSHOT_API_KEY`, and defaults to `https://api.moonshot.ai/v1` with model `kimi-k2.6`.
-    - Override pricing and context metadata in `models.providers` if needed.
-    - If Moonshot publishes different context limits for a model, adjust `contextWindow` accordingly.
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
-    Choosing providers, model refs, and failover behavior.
-  </Card>
-  <Card title="Web search" href="/tools/web" icon="magnifying-glass">
-    Configuring web search providers including Kimi.
-  </Card>
-  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
-    Full config schema for providers, models, and plugins.
-  </Card>
-  <Card title="Moonshot Open Platform" href="https://platform.moonshot.ai" icon="globe">
-    Moonshot API key management and documentation.
-  </Card>
-</CardGroup>

package/docs/providers/novita.md

@@ -1,92 +0,0 @@
----
-summary: "Use NovitaAI's OpenAI-compatible API with FengMing"
-read_when:
-  - You want to run FengMing with NovitaAI models
-  - You need the Novita provider id, key, or endpoint
-title: "NovitaAI"
----
-
-NovitaAI is a hosted AI infrastructure provider with an OpenAI-compatible model
-API. In FengMing it is a bundled model provider, so the provider id is
-`novita`, credentials go through the normal model auth flow, and model refs look
-like `novita/deepseek/deepseek-v3-0324`.
-
-Use Novita when you want hosted access to open-weight and third-party model
-routes without running your own inference server. The bundled catalog focuses on
-chat models that are practical for agent turns, including DeepSeek, Moonshot,
-MiniMax, GLM, and Qwen routes exposed by Novita.
-
-This provider uses Novita's OpenAI-compatible endpoint. FengMing handles
-provider registration, auth, aliases, model ref normalization, and base URL
-selection; Novita controls live model availability, account permissions,
-pricing, and rate limits.
-
-## Setup
-
-Create an API key at [novita.ai/settings/key-management](https://novita.ai/settings/key-management), then run:
-
-```bash
-fengming onboard --auth-choice novita-api-key
-```
-
-Or set:
-
-```bash
-export NOVITA_API_KEY="<your-novita-api-key>" # pragma: allowlist secret
-```
-
-## Defaults
-
-- Provider: `novita`
-- Aliases: `novita-ai`, `novitaai`
-- Base URL: `https://api.novita.ai/openai/v1`
-- Env var: `NOVITA_API_KEY`
-- Default model: `novita/deepseek/deepseek-v3-0324`
-
-## When to choose Novita
-
-- You want hosted open-weight model access with an OpenAI-compatible API.
-- You want DeepSeek, Kimi, MiniMax, GLM, or Qwen-family routes through a single
-  provider account.
-- You want another hosted fallback path beside OpenRouter, GMI, DeepInfra, or
-  direct vendor APIs.
-- You prefer provider-side model hosting over maintaining vLLM, SGLang, LM
-  Studio, or Ollama infrastructure.
-
-Choose a direct vendor provider when you need vendor-native request parameters
-or support contracts. Choose a local provider when the model must run on your
-own hardware or behind your own network boundary.
-
-## Models
-
-The bundled catalog seeds commonly available NovitaAI route ids, including:
-
-- `novita/moonshotai/kimi-k2.5`
-- `novita/minimax/minimax-m2.7`
-- `novita/zai-org/glm-5`
-- `novita/deepseek/deepseek-v3-0324`
-- `novita/deepseek/deepseek-r1-0528`
-- `novita/qwen/qwen3-235b-a22b-fp8`
-
-The catalog is a starting point for FengMing model selection. Your account,
-region, or Novita's current catalog may add, remove, or restrict routes. Check
-the provider from the CLI before setting a long-lived default:
-
-```bash
-fengming models list --provider novita
-```
-
-## Troubleshooting
-
-- `401` or `403`: verify the key in Novita's key management page and re-run
-  `fengming onboard --auth-choice novita-api-key` if the stored profile is
-  stale.
-- Unknown model errors: use the exact `novita/<route-id>` returned by
-  `fengming models list --provider novita`.
-- Slow or failed routes: try another Novita model route or set Novita as a
-  fallback provider for workloads that can tolerate provider-specific variance.
-
-## Related
-
-- [Model providers](/concepts/model-providers)
-- [All providers](/providers/index)

package/docs/providers/nvidia.md

@@ -1,158 +0,0 @@
----
-summary: "Use NVIDIA's OpenAI-compatible API in FengMing"
-read_when:
-  - You want to use open models in FengMing for free
-  - You need NVIDIA_API_KEY setup
-title: "NVIDIA"
----
-
-NVIDIA provides an OpenAI-compatible API at `https://integrate.api.nvidia.com/v1` for
-open models for free. Authenticate with an API key from
-[build.nvidia.com](https://build.nvidia.com/settings/api-keys).
-
-## Getting started
-
-<Steps>
-  <Step title="Get your API key">
-    Create an API key at [build.nvidia.com](https://build.nvidia.com/settings/api-keys).
-  </Step>
-  <Step title="Export the key and run onboarding">
-    ```bash
-    export NVIDIA_API_KEY="nvapi-..."
-    fengming onboard --auth-choice nvidia-api-key
-    ```
-  </Step>
-  <Step title="Set an NVIDIA model">
-    ```bash
-    fengming models set nvidia/nvidia/nemotron-3-super-120b-a12b
-    ```
-  </Step>
-</Steps>
-
-<Warning>
-If you pass `--nvidia-api-key` instead of the env var, the value lands in shell
-history and `ps` output. Prefer the `NVIDIA_API_KEY` environment variable when
-possible.
-</Warning>
-
-For non-interactive setup, you can also pass the key directly:
-
-```bash
-fengming onboard --auth-choice nvidia-api-key --nvidia-api-key "nvapi-..."
-```
-
-## Config example
-
-```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/nemotron-3-super-120b-a12b" },
-    },
-  },
-}
-```
-
-## Featured catalog
-
-When an NVIDIA API key is configured, FengMing setup and model-selection paths
-try NVIDIA's public featured-model catalog from
-`https://assets.ngc.nvidia.com/products/api-catalog/featured-models.json` and
-caches the ranked result for 24 hours. New featured models from build.nvidia.com
-therefore appear in setup and model-selection surfaces without waiting for an
-FengMing release.
-
-The fetch uses a fixed HTTPS host policy for `assets.ngc.nvidia.com`. If no
-NVIDIA API key is configured, or if that public catalog is unavailable or
-malformed, FengMing falls back to the bundled catalog below.
-
-## Bundled fallback catalog
-
-| Model ref                                  | Name                         | Context | Max output | Notes                             |
-| ------------------------------------------ | ---------------------------- | ------- | ---------- | --------------------------------- |
-| `nvidia/nvidia/nemotron-3-super-120b-a12b` | NVIDIA Nemotron 3 Super 120B | 262,144 | 8,192      | Featured fallback                 |
-| `nvidia/moonshotai/kimi-k2.5`              | Kimi K2.5                    | 262,144 | 8,192      | Featured fallback                 |
-| `nvidia/minimaxai/minimax-m2.7`            | Minimax M2.7                 | 196,608 | 8,192      | Featured fallback                 |
-| `nvidia/z-ai/glm-5.1`                      | GLM 5.1                      | 202,752 | 8,192      | Featured fallback                 |
-| `nvidia/minimaxai/minimax-m2.5`            | MiniMax M2.5                 | 196,608 | 8,192      | Deprecated, upgrade compatibility |
-| `nvidia/z-ai/glm5`                         | GLM-5                        | 202,752 | 8,192      | Deprecated, upgrade compatibility |
-
-## Advanced configuration
-
-<AccordionGroup>
-  <Accordion title="Auto-enable behavior">
-    The provider auto-enables when the `NVIDIA_API_KEY` environment variable is set.
-    No explicit provider config is required beyond the key.
-  </Accordion>
-
-  <Accordion title="Catalog and pricing">
-    FengMing prefers NVIDIA's public featured-model catalog when NVIDIA auth is
-    configured and caches it for 24 hours. The bundled fallback catalog is static
-    and keeps deprecated shipped refs for upgrade compatibility. Costs default to
-    `0` in source since NVIDIA currently offers free API access for the listed
-    models.
-  </Accordion>
-
-  <Accordion title="OpenAI-compatible endpoint">
-    NVIDIA uses the standard `/v1` completions endpoint. Any OpenAI-compatible
-    tooling should work out of the box with the NVIDIA base URL.
-  </Accordion>
-
-  <Accordion title="Slow custom provider responses">
-    Some NVIDIA-hosted custom models can take longer than the default model idle
-    watchdog before they emit a first response chunk. For custom NVIDIA provider
-    entries, raise the provider timeout instead of raising the whole agent
-    runtime timeout:
-
-    ```json5
-    {
-      models: {
-        providers: {
-          "custom-integrate-api-nvidia-com": {
-            baseUrl: "https://integrate.api.nvidia.com/v1",
-            api: "openai-completions",
-            apiKey: "NVIDIA_API_KEY",
-            timeoutSeconds: 300,
-          },
-        },
-      },
-      agents: {
-        defaults: {
-          models: {
-            "custom-integrate-api-nvidia-com/meta/llama-3.1-70b-instruct": {
-              params: { thinking: "off" },
-            },
-          },
-        },
-      },
-    }
-    ```
-
-  </Accordion>
-</AccordionGroup>
-
-<Tip>
-NVIDIA models are currently free to use. Check
-[build.nvidia.com](https://build.nvidia.com/) for the latest availability and
-rate-limit details.
-</Tip>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
-    Choosing providers, model refs, and failover behavior.
-  </Card>
-  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
-    Full config reference for agents, models, and providers.
-  </Card>
-</CardGroup>