nodmix 2026.5.25

package/docs/providers/deepseek.md

@@ -0,0 +1,146 @@
+---
+summary: "DeepSeek setup (auth + model selection)"
+title: "DeepSeek"
+read_when:
+  - You want to use DeepSeek with Nodmix
+  - You need the API key env var or CLI auth choice
+---
+
+[DeepSeek](https://www.deepseek.com) provides powerful AI models with an OpenAI-compatible API.
+
+| Property | Value                      |
+| -------- | -------------------------- |
+| Provider | `deepseek`                 |
+| Auth     | `DEEPSEEK_API_KEY`         |
+| API      | OpenAI-compatible          |
+| Base URL | `https://api.deepseek.com` |
+
+## Getting started
+
+<Steps>
+  <Step title="Get your API key">
+    Create an API key at [platform.deepseek.com](https://platform.deepseek.com/api_keys).
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    nodmix onboard --auth-choice deepseek-api-key
+    ```
+
+    This will prompt for your API key and set `deepseek/deepseek-v4-flash` as the default model.
+
+  </Step>
+  <Step title="Verify models are available">
+    ```bash
+    nodmix models list --provider deepseek
+    ```
+
+    To inspect the bundled static catalog without requiring a running Gateway,
+    use:
+
+    ```bash
+    nodmix models list --all --provider deepseek
+    ```
+
+  </Step>
+</Steps>
+
+<AccordionGroup>
+  <Accordion title="Non-interactive setup">
+    For scripted or headless installations, pass all flags directly:
+
+    ```bash
+    nodmix onboard --non-interactive \
+      --mode local \
+      --auth-choice deepseek-api-key \
+      --deepseek-api-key "$DEEPSEEK_API_KEY" \
+      --skip-health \
+      --accept-risk
+    ```
+
+  </Accordion>
+</AccordionGroup>
+
+<Warning>
+If the Gateway runs as a daemon (launchd/systemd), make sure `DEEPSEEK_API_KEY`
+is available to that process (for example, in `~/.nodmix/.env` or via
+`env.shellEnv`).
+</Warning>
+
+## Built-in catalog
+
+| Model ref                    | Name              | Input | Context   | Max output | Notes                                      |
+| ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ |
+| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text  | 1,000,000 | 384,000    | Default model; V4 thinking-capable surface |
+| `deepseek/deepseek-v4-pro`   | DeepSeek V4 Pro   | text  | 1,000,000 | 384,000    | V4 thinking-capable surface                |
+| `deepseek/deepseek-chat`     | DeepSeek Chat     | text  | 131,072   | 8,192      | DeepSeek V3.2 non-thinking surface         |
+| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text  | 131,072   | 65,536     | Reasoning-enabled V3.2 surface             |
+
+<Tip>
+V4 models support DeepSeek's `thinking` control. Nodmix also replays
+DeepSeek `reasoning_content` on follow-up turns so thinking sessions with tool
+calls can continue.
+Use `/think xhigh` or `/think max` with DeepSeek V4 models to request DeepSeek's
+maximum `reasoning_effort`.
+</Tip>
+
+## Thinking and tools
+
+DeepSeek V4 thinking sessions have a stricter replay contract than most
+OpenAI-compatible providers: after a thinking-enabled turn uses tools, DeepSeek
+expects replayed assistant messages from that turn to include
+`reasoning_content` on follow-up requests. Nodmix handles this inside the
+DeepSeek plugin, so normal multi-turn tool use works with
+`deepseek/deepseek-v4-flash` and `deepseek/deepseek-v4-pro`.
+
+If you switch an existing session from another OpenAI-compatible provider to a
+DeepSeek V4 model, older assistant tool-call turns may not have native
+DeepSeek `reasoning_content`. Nodmix fills that missing field on replayed
+assistant messages for DeepSeek V4 thinking requests so the provider can accept
+the history without requiring `/new`.
+
+When thinking is disabled in Nodmix (including the UI **None** selection),
+Nodmix sends DeepSeek `thinking: { type: "disabled" }` and strips replayed
+`reasoning_content` from the outgoing history. This keeps disabled-thinking
+sessions on the non-thinking DeepSeek path.
+
+Use `deepseek/deepseek-v4-flash` for the default fast path. Use
+`deepseek/deepseek-v4-pro` when you want the stronger V4 model and can accept
+higher cost or latency.
+
+## Live testing
+
+The direct live model suite includes DeepSeek V4 in the modern model set. To
+run only the DeepSeek V4 direct-model checks:
+
+```bash
+NODMIX_LIVE_PROVIDERS=deepseek \
+NODMIX_LIVE_MODELS="deepseek/deepseek-v4-flash,deepseek/deepseek-v4-pro" \
+pnpm test:live src/agents/models.profiles.live.test.ts
+```
+
+That live check verifies both V4 models can complete and that thinking/tool
+follow-up turns preserve the replay payload DeepSeek requires.
+
+## Config example
+
+```json5
+{
+  env: { DEEPSEEK_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "deepseek/deepseek-v4-flash" },
+    },
+  },
+}
+```
+
+## 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>

package/docs/providers/ds4.md

@@ -0,0 +1,309 @@
+---
+summary: "Run Nodmix through ds4, a local DeepSeek V4 Flash OpenAI-compatible server"
+read_when:
+  - You want to run Nodmix against antirez/ds4
+  - You want a local DeepSeek V4 Flash backend with tool calls
+  - You need the Nodmix config for ds4-server
+title: "ds4"
+---
+
+[ds4](https://github.com/antirez/ds4) serves DeepSeek V4 Flash from a local
+Metal backend with an OpenAI-compatible `/v1` API. Nodmix connects to ds4
+through the generic `openai-completions` provider family.
+
+ds4 is not a bundled Nodmix provider plugin. Configure it under
+`models.providers.ds4`, then select `ds4/deepseek-v4-flash`.
+
+- Provider id: `ds4`
+- Plugin: none
+- API: OpenAI-compatible Chat Completions (`openai-completions`)
+- Suggested base URL: `http://127.0.0.1:18000/v1`
+- Model id: `deepseek-v4-flash`
+- Tool calls: supported through OpenAI-style `tools` and `tool_calls`
+- Reasoning: DeepSeek-style `thinking` and `reasoning_effort`
+
+## Requirements
+
+- macOS with Metal support.
+- A working ds4 checkout with `ds4-server` and the DeepSeek V4 Flash GGUF file.
+- Enough memory for the context you choose. Larger `--ctx` values allocate more
+  KV memory when the server starts.
+
+<Warning>
+Nodmix agent turns include tool schemas and workspace context. A tiny context
+such as `--ctx 4096` can pass direct curl tests but fail full agent runs with
+`500 prompt exceeds context`. Use at least `--ctx 32768` for agent and tool
+smoke tests. Use `--ctx 393216` only when you have enough memory and want ds4
+Think Max behavior.
+</Warning>
+
+## Quickstart
+
+<Steps>
+  <Step title="Start ds4-server">
+    Replace `<DS4_DIR>` with your ds4 checkout path.
+
+    ```bash
+    <DS4_DIR>/ds4-server \
+      --model <DS4_DIR>/ds4flash.gguf \
+      --host 127.0.0.1 \
+      --port 18000 \
+      --ctx 32768 \
+      --tokens 128
+    ```
+
+  </Step>
+  <Step title="Verify the OpenAI-compatible endpoint">
+    ```bash
+    curl http://127.0.0.1:18000/v1/models
+    ```
+
+    The response should include `deepseek-v4-flash`.
+
+  </Step>
+  <Step title="Add the Nodmix provider config">
+    Add the config from [Full config](#full-config), then run a one-shot model
+    check:
+
+    ```bash
+    nodmix infer model run \
+      --local \
+      --model ds4/deepseek-v4-flash \
+      --thinking off \
+      --prompt "Reply with exactly: nodmix-ds4-ok" \
+      --json
+    ```
+
+  </Step>
+</Steps>
+
+## Full config
+
+Use this config when ds4 is already running on `127.0.0.1:18000`.
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "ds4/deepseek-v4-flash" },
+      models: {
+        "ds4/deepseek-v4-flash": {
+          alias: "DS4 local",
+        },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      ds4: {
+        baseUrl: "http://127.0.0.1:18000/v1",
+        apiKey: "ds4-local",
+        api: "openai-completions",
+        timeoutSeconds: 300,
+        models: [
+          {
+            id: "deepseek-v4-flash",
+            name: "DeepSeek V4 Flash (ds4)",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 32768,
+            maxTokens: 128,
+            compat: {
+              supportsUsageInStreaming: true,
+              supportsReasoningEffort: true,
+              maxTokensField: "max_tokens",
+              supportsStrictMode: false,
+              thinkingFormat: "deepseek",
+              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+            },
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+Keep `contextWindow` aligned with the `ds4-server --ctx` value. Keep `maxTokens`
+aligned with `--tokens` unless you intentionally want Nodmix to request less
+output than the server default.
+
+## On-demand startup
+
+Nodmix can start ds4 only when a `ds4/...` model is selected. Add
+`localService` to the same provider entry:
+
+```json5
+{
+  models: {
+    providers: {
+      ds4: {
+        baseUrl: "http://127.0.0.1:18000/v1",
+        apiKey: "ds4-local",
+        api: "openai-completions",
+        timeoutSeconds: 300,
+        localService: {
+          command: "<DS4_DIR>/ds4-server",
+          args: [
+            "--model",
+            "<DS4_DIR>/ds4flash.gguf",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            "18000",
+            "--ctx",
+            "32768",
+            "--tokens",
+            "128",
+          ],
+          cwd: "<DS4_DIR>",
+          healthUrl: "http://127.0.0.1:18000/v1/models",
+          readyTimeoutMs: 300000,
+          idleStopMs: 0,
+        },
+        models: [
+          {
+            id: "deepseek-v4-flash",
+            name: "DeepSeek V4 Flash (ds4)",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 32768,
+            maxTokens: 128,
+            compat: {
+              supportsUsageInStreaming: true,
+              supportsReasoningEffort: true,
+              maxTokensField: "max_tokens",
+              supportsStrictMode: false,
+              thinkingFormat: "deepseek",
+              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+            },
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+`command` must be an absolute executable path. Shell lookup and `~` expansion are
+not used. See [Local model services](/gateway/local-model-services) for every
+`localService` field.
+
+## Think Max
+
+ds4 applies Think Max only when both conditions are true:
+
+- `ds4-server` starts with `--ctx 393216` or higher.
+- The request uses `reasoning_effort: "max"` or the equivalent ds4 effort field.
+
+If you run that large context, update both the server flags and Nodmix model
+metadata:
+
+```json5
+{
+  contextWindow: 393216,
+  maxTokens: 384000,
+  compat: {
+    supportsUsageInStreaming: true,
+    supportsReasoningEffort: true,
+    maxTokensField: "max_tokens",
+    supportsStrictMode: false,
+    thinkingFormat: "deepseek",
+    supportedReasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
+  },
+}
+```
+
+## Test
+
+Start with a direct HTTP check:
+
+```bash
+curl http://127.0.0.1:18000/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Reply with exactly: ds4-ok"}],"max_tokens":16,"stream":false,"thinking":{"type":"disabled"}}'
+```
+
+Then test Nodmix model routing:
+
+```bash
+nodmix infer model run \
+  --local \
+  --model ds4/deepseek-v4-flash \
+  --thinking off \
+  --prompt "Reply with exactly: nodmix-ds4-ok" \
+  --json
+```
+
+For a full agent and tool-call smoke, use a context of at least 32768:
+
+```bash
+nodmix agent \
+  --local \
+  --session-id ds4-tool-smoke \
+  --model ds4/deepseek-v4-flash \
+  --thinking off \
+  --message "Use the shell command pwd once, then reply exactly: tool-ok <output>" \
+  --json \
+  --timeout 240
+```
+
+Expected result:
+
+- `executionTrace.winnerProvider` is `ds4`
+- `executionTrace.winnerModel` is `deepseek-v4-flash`
+- `toolSummary.calls` is at least `1`
+- `finalAssistantVisibleText` starts with `tool-ok`
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="curl /v1/models cannot connect">
+    ds4 is not running or not bound to the host and port in `baseUrl`. Start
+    `ds4-server`, then retry:
+
+    ```bash
+    curl http://127.0.0.1:18000/v1/models
+    ```
+
+  </Accordion>
+
+  <Accordion title="500 prompt exceeds context">
+    The configured `--ctx` is too small for the Nodmix turn. Raise
+    `ds4-server --ctx`, then update `models.providers.ds4.models[].contextWindow`
+    to match. Full agent turns with tools need substantially more context than a
+    direct one-message curl request.
+  </Accordion>
+
+  <Accordion title="Think Max does not activate">
+    ds4 only uses Think Max when `--ctx` is at least `393216` and the request
+    asks for `reasoning_effort: "max"`. Smaller contexts fall back to high
+    reasoning.
+  </Accordion>
+
+  <Accordion title="The first request is slow">
+    ds4 has a cold Metal residency and model warmup phase. Use
+    `localService.readyTimeoutMs: 300000` when Nodmix starts the server on
+    demand.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Local model services" href="/gateway/local-model-services" icon="play">
+    Start local model servers on demand before model requests.
+  </Card>
+  <Card title="Local models" href="/gateway/local-models" icon="server">
+    Choose and operate local model backends.
+  </Card>
+  <Card title="Model providers" href="/concepts/model-providers" icon="layers">
+    Configure provider refs, auth, and failover.
+  </Card>
+  <Card title="DeepSeek" href="/providers/deepseek" icon="brain">
+    Native DeepSeek provider behavior and thinking controls.
+  </Card>
+</CardGroup>

package/docs/providers/elevenlabs.md

@@ -0,0 +1,130 @@
+---
+summary: "Use ElevenLabs speech, Scribe STT, and realtime transcription with Nodmix"
+read_when:
+  - You want ElevenLabs text-to-speech in Nodmix
+  - You want ElevenLabs Scribe speech-to-text for audio attachments
+  - You want ElevenLabs realtime transcription for Voice Call or Google Meet
+title: "ElevenLabs"
+---
+
+Nodmix uses ElevenLabs for text-to-speech, batch speech-to-text with Scribe
+v2, and streaming STT with Scribe v2 Realtime.
+
+| Capability               | Nodmix surface                                                     | Default                  |
+| ------------------------ | -------------------------------------------------------------------- | ------------------------ |
+| Text-to-speech           | `messages.tts` / `talk`                                              | `eleven_multilingual_v2` |
+| Batch speech-to-text     | `tools.media.audio`                                                  | `scribe_v2`              |
+| Streaming speech-to-text | Voice Call streaming or Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime`     |
+
+## Authentication
+
+Set `ELEVENLABS_API_KEY` in the environment. `XI_API_KEY` is also accepted for
+compatibility with existing ElevenLabs tooling.
+
+```bash
+export ELEVENLABS_API_KEY="..."
+```
+
+## Text-to-speech
+
+```json5
+{
+  messages: {
+    tts: {
+      providers: {
+        elevenlabs: {
+          apiKey: "${ELEVENLABS_API_KEY}",
+          voiceId: "pMsXgVXv3BLzUgSXRplE",
+          modelId: "eleven_multilingual_v2",
+        },
+      },
+    },
+  },
+}
+```
+
+Set `modelId` to `eleven_v3` to use ElevenLabs v3 TTS. Nodmix keeps
+`eleven_multilingual_v2` as the default for existing installs.
+
+Discord voice channels use ElevenLabs' streaming TTS endpoint when ElevenLabs is
+the selected `voice.tts`/`messages.tts` provider. Playback starts from the
+returned audio stream instead of waiting for Nodmix to download and write the
+whole audio file first. `latencyTier` maps to ElevenLabs'
+`optimize_streaming_latency` query parameter for models that accept it; Nodmix
+omits that parameter for `eleven_v3`, which rejects it.
+
+## Speech-to-text
+
+Use Scribe v2 for inbound audio attachments and short recorded voice segments:
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [{ provider: "elevenlabs", model: "scribe_v2" }],
+      },
+    },
+  },
+}
+```
+
+Nodmix sends multipart audio to ElevenLabs `/v1/speech-to-text` with
+`model_id: "scribe_v2"`. Language hints map to `language_code` when present.
+
+## Streaming STT
+
+The bundled `elevenlabs` plugin registers Scribe v2 Realtime for Voice Call and
+Google Meet agent-mode streaming transcription.
+
+| Setting         | Config path                                                               | Default                                           |
+| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
+| API key         | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Falls back to `ELEVENLABS_API_KEY` / `XI_API_KEY` |
+| Model           | `...elevenlabs.modelId`                                                   | `scribe_v2_realtime`                              |
+| Audio format    | `...elevenlabs.audioFormat`                                               | `ulaw_8000`                                       |
+| Sample rate     | `...elevenlabs.sampleRate`                                                | `8000`                                            |
+| Commit strategy | `...elevenlabs.commitStrategy`                                            | `vad`                                             |
+| Language        | `...elevenlabs.languageCode`                                              | (unset)                                           |
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          streaming: {
+            enabled: true,
+            provider: "elevenlabs",
+            providers: {
+              elevenlabs: {
+                apiKey: "${ELEVENLABS_API_KEY}",
+                audioFormat: "ulaw_8000",
+                commitStrategy: "vad",
+                languageCode: "en",
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+<Note>
+Voice Call receives Twilio media as 8 kHz G.711 u-law. The ElevenLabs realtime
+provider defaults to `ulaw_8000`, so telephony frames can be forwarded without
+transcoding.
+</Note>
+
+For Google Meet agent mode, set
+`plugins.entries.google-meet.config.realtime.transcriptionProvider` to
+`"elevenlabs"` and configure the same provider block under
+`plugins.entries.google-meet.config.realtime.providers.elevenlabs`.
+
+## Related
+
+- [Text-to-speech](/tools/tts)
+- [Google Meet](/plugins/google-meet)
+- [Model selection](/concepts/model-providers)