nodmix 2026.5.25

package/docs/providers/senseaudio.md

@@ -0,0 +1,68 @@
+---
+summary: "SenseAudio batch speech-to-text for inbound voice notes"
+read_when:
+  - You want SenseAudio speech-to-text for audio attachments
+  - You need the SenseAudio API key env var or audio config path
+title: "SenseAudio"
+---
+
+SenseAudio can transcribe inbound audio and voice-note attachments through Nodmix's shared `tools.media.audio` pipeline. Nodmix posts multipart audio to the OpenAI-compatible transcription endpoint and injects the returned text as `{{Transcript}}` plus an `[Audio]` block.
+
+| Property      | Value                                            |
+| ------------- | ------------------------------------------------ |
+| Provider id   | `senseaudio`                                     |
+| Plugin        | bundled, `enabledByDefault: true`                |
+| Contract      | `mediaUnderstandingProviders` (audio)            |
+| Auth env var  | `SENSEAUDIO_API_KEY`                             |
+| Default model | `senseaudio-asr-pro-1.5-260319`                  |
+| Default URL   | `https://api.senseaudio.cn/v1`                   |
+| Website       | [senseaudio.cn](https://senseaudio.cn)           |
+| Docs          | [senseaudio.cn/docs](https://senseaudio.cn/docs) |
+
+## Getting started
+
+<Steps>
+  <Step title="Set your API key">
+    ```bash
+    export SENSEAUDIO_API_KEY="..."
+    ```
+  </Step>
+  <Step title="Enable the audio provider">
+    ```json5
+    {
+      tools: {
+        media: {
+          audio: {
+            enabled: true,
+            models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],
+          },
+        },
+      },
+    }
+    ```
+  </Step>
+  <Step title="Send a voice note">
+    Send an audio message through any connected channel. Nodmix uploads the
+    audio to SenseAudio and uses the transcript in the reply pipeline.
+  </Step>
+</Steps>
+
+## Options
+
+| Option     | Path                                  | Description                         |
+| ---------- | ------------------------------------- | ----------------------------------- |
+| `model`    | `tools.media.audio.models[].model`    | SenseAudio ASR model id             |
+| `language` | `tools.media.audio.models[].language` | Optional language hint              |
+| `prompt`   | `tools.media.audio.prompt`            | Optional transcription prompt       |
+| `baseUrl`  | `tools.media.audio.baseUrl` or model  | Override the OpenAI-compatible base |
+| `headers`  | `tools.media.audio.request.headers`   | Extra request headers               |
+
+<Note>
+SenseAudio is batch STT only in Nodmix. Voice Call realtime transcription
+continues to use providers with streaming STT support.
+</Note>
+
+## Related
+
+- [Media understanding (audio)](/nodes/audio)
+- [Model providers](/concepts/model-providers)

package/docs/providers/sglang.md

@@ -0,0 +1,161 @@
+---
+summary: "Run Nodmix with SGLang (OpenAI-compatible self-hosted server)"
+read_when:
+  - You want to run Nodmix against a local SGLang server
+  - You want OpenAI-compatible /v1 endpoints with your own models
+title: "SGLang"
+---
+
+SGLang serves open-weight models via an OpenAI-compatible HTTP API. Nodmix connects to SGLang using the `openai-completions` provider family with auto-discovery of available models.
+
+| Property                  | Value                                                        |
+| ------------------------- | ------------------------------------------------------------ |
+| Provider id               | `sglang`                                                     |
+| Plugin                    | bundled, `enabledByDefault: true`                            |
+| Auth env var              | `SGLANG_API_KEY` (any non-empty value if server has no auth) |
+| Onboarding flag           | `--auth-choice sglang`                                       |
+| API                       | OpenAI-compatible (`openai-completions`)                     |
+| Default base URL          | `http://127.0.0.1:30000/v1`                                  |
+| Default model placeholder | `sglang/Qwen/Qwen3-8B`                                       |
+| Streaming usage           | Yes (`supportsStreamingUsage: true`)                         |
+| Pricing                   | Marked external-free (`modelPricing.external: false`)        |
+
+Nodmix also **auto-discovers** available models from SGLang when you opt in with `SGLANG_API_KEY`. Use `sglang/*` in `agents.defaults.models` to keep discovery dynamic when you also configure a custom SGLang base URL. See [Model discovery (implicit provider)](#model-discovery-implicit-provider) below.
+
+## Getting started
+
+<Steps>
+  <Step title="Start SGLang">
+    Launch SGLang with an OpenAI-compatible server. Your base URL should expose
+    `/v1` endpoints (for example `/v1/models`, `/v1/chat/completions`). SGLang
+    commonly runs on:
+
+    - `http://127.0.0.1:30000/v1`
+
+  </Step>
+  <Step title="Set an API key">
+    Any value works if no auth is configured on your server:
+
+    ```bash
+    export SGLANG_API_KEY="sglang-local"
+    ```
+
+  </Step>
+  <Step title="Run onboarding or set a model directly">
+    ```bash
+    nodmix onboard
+    ```
+
+    Or configure the model manually:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "sglang/your-model-id" },
+        },
+      },
+    }
+    ```
+
+  </Step>
+</Steps>
+
+## Model discovery (implicit provider)
+
+When `SGLANG_API_KEY` is set (or an auth profile exists) and you **do not**
+define `models.providers.sglang`, Nodmix will query:
+
+- `GET http://127.0.0.1:30000/v1/models`
+
+and convert the returned IDs into model entries.
+
+<Note>
+If you set `models.providers.sglang` explicitly, Nodmix uses your declared
+models by default. Add `"sglang/*": {}` to `agents.defaults.models` when you
+want Nodmix to query that configured provider's `/models` endpoint and include
+all advertised SGLang models.
+</Note>
+
+## Explicit configuration (manual models)
+
+Use explicit config when:
+
+- SGLang runs on a different host/port.
+- You want to pin `contextWindow`/`maxTokens` values.
+- Your server requires a real API key (or you want to control headers).
+
+```json5
+{
+  models: {
+    providers: {
+      sglang: {
+        baseUrl: "http://127.0.0.1:30000/v1",
+        apiKey: "${SGLANG_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "your-model-id",
+            name: "Local SGLang Model",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 128000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Proxy-style behavior">
+    SGLang is treated as a proxy-style OpenAI-compatible `/v1` backend, not a
+    native OpenAI endpoint.
+
+    | Behavior | SGLang |
+    |----------|--------|
+    | OpenAI-only request shaping | Not applied |
+    | `service_tier`, Responses `store`, prompt-cache hints | Not sent |
+    | Reasoning-compat payload shaping | Not applied |
+    | Hidden attribution headers (`originator`, `version`, `User-Agent`) | Not injected on custom SGLang base URLs |
+
+  </Accordion>
+
+  <Accordion title="Troubleshooting">
+    **Server not reachable**
+
+    Verify the server is running and responding:
+
+    ```bash
+    curl http://127.0.0.1:30000/v1/models
+    ```
+
+    **Auth errors**
+
+    If requests fail with auth errors, set a real `SGLANG_API_KEY` that matches
+    your server configuration, or configure the provider explicitly under
+    `models.providers.sglang`.
+
+    <Tip>
+    If you run SGLang without authentication, any non-empty value for
+    `SGLANG_API_KEY` is sufficient to opt in to model discovery.
+    </Tip>
+
+  </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="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full config schema including provider entries.
+  </Card>
+</CardGroup>

package/docs/providers/stepfun.md

@@ -0,0 +1,229 @@
+---
+summary: "Use StepFun models with Nodmix"
+read_when:
+  - You want StepFun models in Nodmix
+  - You need StepFun setup guidance
+title: "StepFun"
+---
+
+Nodmix includes a bundled StepFun provider plugin with two provider ids:
+
+- `stepfun` for the standard endpoint
+- `stepfun-plan` for the Step Plan endpoint
+
+<Warning>
+Standard and Step Plan are **separate providers** with different endpoints and model ref prefixes (`stepfun/...` vs `stepfun-plan/...`). Use a China key with the `.com` endpoints and a global key with the `.ai` endpoints.
+</Warning>
+
+## Region and endpoint overview
+
+| Endpoint  | China (`.com`)                         | Global (`.ai`)                        |
+| --------- | -------------------------------------- | ------------------------------------- |
+| Standard  | `https://api.stepfun.com/v1`           | `https://api.stepfun.ai/v1`           |
+| Step Plan | `https://api.stepfun.com/step_plan/v1` | `https://api.stepfun.ai/step_plan/v1` |
+
+Auth env var: `STEPFUN_API_KEY`
+
+## Built-in catalog
+
+Standard (`stepfun`):
+
+| Model ref                | Context | Max output | Notes                  |
+| ------------------------ | ------- | ---------- | ---------------------- |
+| `stepfun/step-3.5-flash` | 262,144 | 65,536     | Default standard model |
+
+Step Plan (`stepfun-plan`):
+
+| Model ref                          | Context | Max output | Notes                      |
+| ---------------------------------- | ------- | ---------- | -------------------------- |
+| `stepfun-plan/step-3.5-flash`      | 262,144 | 65,536     | Default Step Plan model    |
+| `stepfun-plan/step-3.5-flash-2603` | 262,144 | 65,536     | Additional Step Plan model |
+
+## Getting started
+
+Choose your provider surface and follow the setup steps.
+
+<Tabs>
+  <Tab title="Standard">
+    **Best for:** general-purpose use via the standard StepFun endpoint.
+
+    <Steps>
+      <Step title="Choose your endpoint region">
+        | Auth choice                      | Endpoint                         | Region        |
+        | -------------------------------- | -------------------------------- | ------------- |
+        | `stepfun-standard-api-key-intl`  | `https://api.stepfun.ai/v1`     | International |
+        | `stepfun-standard-api-key-cn`    | `https://api.stepfun.com/v1`    | China         |
+      </Step>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard --auth-choice stepfun-standard-api-key-intl
+        ```
+
+        Or for the China endpoint:
+
+        ```bash
+        nodmix onboard --auth-choice stepfun-standard-api-key-cn
+        ```
+      </Step>
+      <Step title="Non-interactive alternative">
+        ```bash
+        nodmix onboard --auth-choice stepfun-standard-api-key-intl \
+          --stepfun-api-key "$STEPFUN_API_KEY"
+        ```
+      </Step>
+      <Step title="Verify models are available">
+        ```bash
+        nodmix models list --provider stepfun
+        ```
+      </Step>
+    </Steps>
+
+    ### Model refs
+
+    - Default model: `stepfun/step-3.5-flash`
+
+  </Tab>
+
+  <Tab title="Step Plan">
+    **Best for:** Step Plan reasoning endpoint.
+
+    <Steps>
+      <Step title="Choose your endpoint region">
+        | Auth choice                  | Endpoint                                | Region        |
+        | ---------------------------- | --------------------------------------- | ------------- |
+        | `stepfun-plan-api-key-intl`  | `https://api.stepfun.ai/step_plan/v1`  | International |
+        | `stepfun-plan-api-key-cn`    | `https://api.stepfun.com/step_plan/v1` | China         |
+      </Step>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard --auth-choice stepfun-plan-api-key-intl
+        ```
+
+        Or for the China endpoint:
+
+        ```bash
+        nodmix onboard --auth-choice stepfun-plan-api-key-cn
+        ```
+      </Step>
+      <Step title="Non-interactive alternative">
+        ```bash
+        nodmix onboard --auth-choice stepfun-plan-api-key-intl \
+          --stepfun-api-key "$STEPFUN_API_KEY"
+        ```
+      </Step>
+      <Step title="Verify models are available">
+        ```bash
+        nodmix models list --provider stepfun-plan
+        ```
+      </Step>
+    </Steps>
+
+    ### Model refs
+
+    - Default model: `stepfun-plan/step-3.5-flash`
+    - Alternate model: `stepfun-plan/step-3.5-flash-2603`
+
+  </Tab>
+</Tabs>
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Full config: Standard provider">
+    ```json5
+    {
+      env: { STEPFUN_API_KEY: "your-key" },
+      agents: { defaults: { model: { primary: "stepfun/step-3.5-flash" } } },
+      models: {
+        mode: "merge",
+        providers: {
+          stepfun: {
+            baseUrl: "https://api.stepfun.ai/v1",
+            api: "openai-completions",
+            apiKey: "${STEPFUN_API_KEY}",
+            models: [
+              {
+                id: "step-3.5-flash",
+                name: "Step 3.5 Flash",
+                reasoning: true,
+                input: ["text"],
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                contextWindow: 262144,
+                maxTokens: 65536,
+              },
+            ],
+          },
+        },
+      },
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Full config: Step Plan provider">
+    ```json5
+    {
+      env: { STEPFUN_API_KEY: "your-key" },
+      agents: { defaults: { model: { primary: "stepfun-plan/step-3.5-flash" } } },
+      models: {
+        mode: "merge",
+        providers: {
+          "stepfun-plan": {
+            baseUrl: "https://api.stepfun.ai/step_plan/v1",
+            api: "openai-completions",
+            apiKey: "${STEPFUN_API_KEY}",
+            models: [
+              {
+                id: "step-3.5-flash",
+                name: "Step 3.5 Flash",
+                reasoning: true,
+                input: ["text"],
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                contextWindow: 262144,
+                maxTokens: 65536,
+              },
+              {
+                id: "step-3.5-flash-2603",
+                name: "Step 3.5 Flash 2603",
+                reasoning: true,
+                input: ["text"],
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                contextWindow: 262144,
+                maxTokens: 65536,
+              },
+            ],
+          },
+        },
+      },
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Notes">
+    - The provider is bundled with Nodmix, so there is no separate plugin install step.
+    - `step-3.5-flash-2603` is currently exposed only on `stepfun-plan`.
+    - A single auth flow writes region-matched profiles for both `stepfun` and `stepfun-plan`, so both surfaces can be discovered together.
+    - Use `nodmix models list` and `nodmix models set <provider/model>` to inspect or switch models.
+
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+For the broader provider overview, see [Model providers](/concepts/model-providers).
+</Note>
+
+## 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="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full config schema for providers, models, and plugins.
+  </Card>
+  <Card title="Model selection" href="/concepts/models" icon="brain">
+    How to choose and configure models.
+  </Card>
+  <Card title="StepFun Platform" href="https://platform.stepfun.com" icon="globe">
+    StepFun API key management and documentation.
+  </Card>
+</CardGroup>

package/docs/providers/synthetic.md

@@ -0,0 +1,154 @@
+---
+summary: "Use Synthetic's Anthropic-compatible API in Nodmix"
+read_when:
+  - You want to use Synthetic as a model provider
+  - You need a Synthetic API key or base URL setup
+title: "Synthetic"
+---
+
+[Synthetic](https://synthetic.new) exposes Anthropic-compatible endpoints.
+Nodmix registers it as the `synthetic` provider and uses the Anthropic
+Messages API.
+
+| Property | Value                                 |
+| -------- | ------------------------------------- |
+| Provider | `synthetic`                           |
+| Auth     | `SYNTHETIC_API_KEY`                   |
+| API      | Anthropic Messages                    |
+| Base URL | `https://api.synthetic.new/anthropic` |
+
+## Getting started
+
+<Steps>
+  <Step title="Get an API key">
+    Obtain a `SYNTHETIC_API_KEY` from your Synthetic account, or let the
+    onboarding wizard prompt you for one.
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    nodmix onboard --auth-choice synthetic-api-key
+    ```
+  </Step>
+  <Step title="Verify the default model">
+    After onboarding the default model is set to:
+    ```
+    synthetic/hf:MiniMaxAI/MiniMax-M2.5
+    ```
+  </Step>
+</Steps>
+
+<Warning>
+Nodmix's Anthropic client appends `/v1` to the base URL automatically, so use
+`https://api.synthetic.new/anthropic` (not `/anthropic/v1`). If Synthetic
+changes its base URL, override `models.providers.synthetic.baseUrl`.
+</Warning>
+
+## Config example
+
+```json5
+{
+  env: { SYNTHETIC_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
+      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      synthetic: {
+        baseUrl: "https://api.synthetic.new/anthropic",
+        apiKey: "${SYNTHETIC_API_KEY}",
+        api: "anthropic-messages",
+        models: [
+          {
+            id: "hf:MiniMaxAI/MiniMax-M2.5",
+            name: "MiniMax M2.5",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 192000,
+            maxTokens: 65536,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## Built-in catalog
+
+All Synthetic models use cost `0` (input/output/cache).
+
+| Model ID                                               | Context window | Max tokens | Reasoning | Input        |
+| ------------------------------------------------------ | -------------- | ---------- | --------- | ------------ |
+| `hf:MiniMaxAI/MiniMax-M2.5`                            | 192,000        | 65,536     | no        | text         |
+| `hf:moonshotai/Kimi-K2-Thinking`                       | 256,000        | 8,192      | yes       | text         |
+| `hf:zai-org/GLM-4.7`                                   | 198,000        | 128,000    | no        | text         |
+| `hf:deepseek-ai/DeepSeek-R1-0528`                      | 128,000        | 8,192      | no        | text         |
+| `hf:deepseek-ai/DeepSeek-V3-0324`                      | 128,000        | 8,192      | no        | text         |
+| `hf:deepseek-ai/DeepSeek-V3.1`                         | 128,000        | 8,192      | no        | text         |
+| `hf:deepseek-ai/DeepSeek-V3.1-Terminus`                | 128,000        | 8,192      | no        | text         |
+| `hf:deepseek-ai/DeepSeek-V3.2`                         | 159,000        | 8,192      | no        | text         |
+| `hf:meta-llama/Llama-3.3-70B-Instruct`                 | 128,000        | 8,192      | no        | text         |
+| `hf:meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 524,000        | 8,192      | no        | text         |
+| `hf:moonshotai/Kimi-K2-Instruct-0905`                  | 256,000        | 8,192      | no        | text         |
+| `hf:moonshotai/Kimi-K2.5`                              | 256,000        | 8,192      | yes       | text + image |
+| `hf:openai/gpt-oss-120b`                               | 128,000        | 8,192      | no        | text         |
+| `hf:Qwen/Qwen3-235B-A22B-Instruct-2507`                | 256,000        | 8,192      | no        | text         |
+| `hf:Qwen/Qwen3-Coder-480B-A35B-Instruct`               | 256,000        | 8,192      | no        | text         |
+| `hf:Qwen/Qwen3-VL-235B-A22B-Instruct`                  | 250,000        | 8,192      | no        | text + image |
+| `hf:zai-org/GLM-4.5`                                   | 128,000        | 128,000    | no        | text         |
+| `hf:zai-org/GLM-4.6`                                   | 198,000        | 128,000    | no        | text         |
+| `hf:zai-org/GLM-5`                                     | 256,000        | 128,000    | yes       | text + image |
+| `hf:deepseek-ai/DeepSeek-V3`                           | 128,000        | 8,192      | no        | text         |
+| `hf:Qwen/Qwen3-235B-A22B-Thinking-2507`                | 256,000        | 8,192      | yes       | text         |
+
+<Tip>
+Model refs use the form `synthetic/<modelId>`. Use
+`nodmix models list --provider synthetic` to see all models available on your
+account.
+</Tip>
+
+<AccordionGroup>
+  <Accordion title="Model allowlist">
+    If you enable a model allowlist (`agents.defaults.models`), add every
+    Synthetic model you plan to use. Models not in the allowlist will be hidden
+    from the agent.
+  </Accordion>
+
+  <Accordion title="Base URL override">
+    If Synthetic changes its API endpoint, override the base URL in your config:
+
+    ```json5
+    {
+      models: {
+        providers: {
+          synthetic: {
+            baseUrl: "https://new-api.synthetic.new/anthropic",
+          },
+        },
+      },
+    }
+    ```
+
+    Remember that Nodmix appends `/v1` automatically.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Provider rules, model refs, and failover behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full config schema including provider settings.
+  </Card>
+  <Card title="Synthetic" href="https://synthetic.new" icon="arrow-up-right-from-square">
+    Synthetic dashboard and API docs.
+  </Card>
+</CardGroup>