coderouter-cli 2.5.0__tar.gz → 2.5.2__tar.gz

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/CHANGELOG.md

@@ -6,6 +6,73 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v2.5.2] — 2026-05-22 (Backend-aware Launcher suggestions + backend install guide)
+
+Patch release: a Launcher bug fix and documentation improvements.
+
+### Fixed
+
+- **Launcher "suggest values" (`⚙ 推奨値`) is now backend-aware.**
+  Previously the button emitted llama.cpp flags
+  (`-ngl` / `--ctx-size` / `--threads`) for every backend, but vLLM and
+  MLX reject those. Now:
+  - **llama.cpp** — the flags, as before.
+  - **vLLM** — empty; `--max-model-len` etc. depend on the model's real
+    context length, so the engine's auto-derivation is left to do its job.
+  - **MLX** — empty; it assumes unified memory and takes no launch-time
+    tuning flags.
+
+  Fixed in both the desktop GUI (`launcher_gui.py`) and the Web launcher
+  (`coderouter/ingress/launcher_routes.py`); the `/api/launcher/suggest`
+  endpoint now accepts a `backend` parameter.
+
+### Documentation
+
+- New **`docs/backends/install-backends.md`** (+ `.en.md`) — an
+  installation guide for llama.cpp / vLLM / MLX covering macOS / Linux /
+  Windows, with per-backend verification steps and common pitfalls.
+- **Launcher docs consolidated from 3 files to 2**: `launcher-gui.md` is
+  merged into a unified `launcher.md` (Web + Desktop GUI in one guide,
+  shared reference documented once); `launcher-quickstart.md` is slimmed
+  to delegate installation to the new guide.
+- **Backend venv convention documented**: vLLM / MLX virtual
+  environments live under `~/.coderouter/backends/<backend>/`, one venv
+  per backend.
+
+---
+
+## [v2.5.1] — 2026-05-22 (MLX backend + docs reorganization)
+
+Patch release: a third Launcher backend, a reorganized documentation
+tree, and a security fix.
+
+### Added
+
+- **MLX backend** for the Launcher (`launcher_gui.py` and
+  `coderouter/ingress/launcher_routes.py`): `mlx` joins `llama.cpp` and
+  `vllm`, aimed at Apple Silicon users. Launches
+  `python -m mlx_lm.server --model <m> --port <p>`. The backend
+  selectors (desktop GUI combobox / Web `<select>`) gain an `mlx`
+  option, and the binary-not-found error messages are now
+  backend-agnostic.
+
+### Changed
+
+- **`docs/` reorganized** into role-based folders — `start/`, `guides/`,
+  `backends/`, `concepts/` — with a new bilingual (JA/EN) master index
+  at `docs/README.md` including a quick "what to read" table. Internal
+  cross-links, `README.md` / `README.en.md`, and code/config path
+  references were updated to the new layout.
+- **`plan.md` restructured**: deduplicated, version ordering fixed,
+  sections compressed (1747 → 721 lines).
+
+### Security
+
+- **starlette `1.0.0` → `1.0.1`** (`uv.lock`): fixes PYSEC-2026-161,
+  which failed the `cve-audit` CI job.
+
+---
+
 ## [v2.5.0] — 2026-05-22 (Launcher — llama.cpp / vllm GUI)
 
 Browser-based process manager for local inference backends, integrated

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.5.0
+Version: 2.5.2
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter
@@ -54,7 +54,7 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <a href="./README.en.md">English</a> · <strong>日本語</strong> · <a href="./docs/quickstart.md">10 分で動かす</a> · <a href="./docs/architecture.md">設計詳細</a>
+  <a href="./README.en.md">English</a> · <strong>日本語</strong> · <a href="./docs/start/quickstart.md">10 分で動かす</a> · <a href="./docs/concepts/architecture.md">設計詳細</a>
 </p>
 
 ---
@@ -121,7 +121,7 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 | codex / gemini-cli + Ollama 直繋ぎで動いてる | オプション — フォールバックが欲しいなら |
 | Claude API を直接叩いてて問題ない | 不要 |
 
-詳細は → [要否判定ガイド](./docs/when-do-i-need-coderouter.md)
+詳細は → [要否判定ガイド](./docs/start/when-do-i-need-coderouter.md)
 
 ---
 
@@ -186,7 +186,7 @@ launcher:
           "--max-model-len": 4096
 ```
 
-詳細 → [Launcher ガイド](./docs/launcher.md)
+詳細 → [Launcher ガイド](./docs/backends/launcher.md)
 
 ---
 
@@ -213,7 +213,7 @@ providers:
     api_key_env: OPENROUTER_API_KEY
 ```
 
-もっと詳しい設定 → [利用ガイド](./docs/usage-guide.md) · [設計詳細](./docs/architecture.md)
+もっと詳しい設定 → [利用ガイド](./docs/guides/usage-guide.md) · [設計詳細](./docs/concepts/architecture.md)
 
 ---
 
@@ -221,15 +221,15 @@ providers:
 
 | やりたいこと | ドキュメント |
 |---|---|
-| すぐ動かす | [Quickstart](./docs/quickstart.md) |
-| 使いこなす | [利用ガイド](./docs/usage-guide.md) |
-| 無料で回す | [無料枠ガイド](./docs/free-tier-guide.md) |
-| llama.cpp / vllm を GUI で起動 | [Launcher ガイド](./docs/launcher.md) |
-| 詰まった | [トラブルシューティング](./docs/troubleshooting.md) |
-| 設計を知りたい | [アーキテクチャ詳細](./docs/architecture.md) |
+| すぐ動かす | [Quickstart](./docs/start/quickstart.md) |
+| 使いこなす | [利用ガイド](./docs/guides/usage-guide.md) |
+| 無料で回す | [無料枠ガイド](./docs/guides/free-tier-guide.md) |
+| llama.cpp / vllm を GUI で起動 | [Launcher ガイド](./docs/backends/launcher.md) |
+| 詰まった | [トラブルシューティング](./docs/guides/troubleshooting.md) |
+| 設計を知りたい | [アーキテクチャ詳細](./docs/concepts/architecture.md) |
 | 全リリース履歴 | [CHANGELOG](./CHANGELOG.md) |
 
-English: [Quickstart](./docs/quickstart.en.md) · [Usage guide](./docs/usage-guide.en.md) · [Free-tier](./docs/free-tier-guide.en.md) · [Troubleshooting](./docs/troubleshooting.en.md)
+English: [Quickstart](./docs/start/quickstart.en.md) · [Usage guide](./docs/guides/usage-guide.en.md) · [Free-tier](./docs/guides/free-tier-guide.en.md) · [Troubleshooting](./docs/guides/troubleshooting.en.md)
 
 ---
 
@@ -239,10 +239,10 @@ English: [Quickstart](./docs/quickstart.en.md) · [Usage guide](./docs/usage-gui
 
 | 症状 | 原因 | 詳細 |
 |---|---|---|
-| 401 エラー | API キー未設定 / `.env` に `export` 忘れ | [§1](./docs/troubleshooting.md#1-起動設定で踏みやすい-5-つの罠-v162-追加) |
-| 返信が空 / 意味不明 | Ollama の `num_ctx` が 2048 に切り詰め | [§3](./docs/troubleshooting.md#3-ollama-初心者--サイレント失敗-5-症状-v07-c) |
-| `<think>` タグが漏れる | `output_filters: [strip_thinking]` を付ける | [§3](./docs/troubleshooting.md#3-ollama-初心者--サイレント失敗-5-症状-v07-c) |
-| Claude Code でツール呼び出しがおかしい | tool-call 修復が効いてない | [§4](./docs/troubleshooting.md#4-claude-code-連携で踏みやすい罠-v162-追加) |
+| 401 エラー | API キー未設定 / `.env` に `export` 忘れ | [§1](./docs/guides/troubleshooting.md#1-起動設定で踏みやすい-5-つの罠-v162-追加) |
+| 返信が空 / 意味不明 | Ollama の `num_ctx` が 2048 に切り詰め | [§3](./docs/guides/troubleshooting.md#3-ollama-初心者--サイレント失敗-5-症状-v07-c) |
+| `<think>` タグが漏れる | `output_filters: [strip_thinking]` を付ける | [§3](./docs/guides/troubleshooting.md#3-ollama-初心者--サイレント失敗-5-症状-v07-c) |
+| Claude Code でツール呼び出しがおかしい | tool-call 修復が効いてない | [§4](./docs/guides/troubleshooting.md#4-claude-code-連携で踏みやすい罠-v162-追加) |
 
 `http://localhost:8088/dashboard` を開いておくと、ほとんどの問題が見て 10 秒でわかります。
 
@@ -268,7 +268,7 @@ CodeRouter は backend ルーター層として独立して動きます。`OPENA
 
 ## Security
 
-シークレットは環境変数に置きます。[`docs/security.md`](./docs/security.md) に完全な方針と報告手順があります。
+シークレットは環境変数に置きます。[`docs/security.md`](./docs/guides/security.md) に完全な方針と報告手順があります。
 
 ## License
 

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/README.en.md

@@ -13,7 +13,7 @@
 </p>
 
 <p align="center">
-  <strong>English</strong> · <a href="./README.md">日本語</a> · <a href="./docs/quickstart.en.md">Get started in 10 min</a> · <a href="./docs/architecture.md">Architecture</a>
+  <strong>English</strong> · <a href="./README.md">日本語</a> · <a href="./docs/start/quickstart.en.md">Get started in 10 min</a> · <a href="./docs/concepts/architecture.md">Architecture</a>
 </p>
 
 ---
@@ -80,7 +80,7 @@ That's it. Claude Code works as usual, but your local Ollama is answering behind
 | codex / gemini-cli + Ollama works fine | Optional — if you want fallback |
 | Using Claude API directly, no issues | Not needed |
 
-Full decision matrix → [Do I need CodeRouter?](./docs/when-do-i-need-coderouter.en.md)
+Full decision matrix → [Do I need CodeRouter?](./docs/start/when-do-i-need-coderouter.en.md)
 
 ---
 
@@ -145,7 +145,7 @@ launcher:
           "--max-model-len": 4096
 ```
 
-Details → [Launcher guide](./docs/launcher.md)
+Details → [Launcher guide](./docs/backends/launcher.md)
 
 ---
 
@@ -172,7 +172,7 @@ providers:
     api_key_env: OPENROUTER_API_KEY
 ```
 
-More detail → [Usage guide](./docs/usage-guide.en.md) · [Architecture](./docs/architecture.md)
+More detail → [Usage guide](./docs/guides/usage-guide.en.md) · [Architecture](./docs/concepts/architecture.md)
 
 ---
 
@@ -180,15 +180,15 @@ More detail → [Usage guide](./docs/usage-guide.en.md) · [Architecture](./docs
 
 | Goal | Document |
 |---|---|
-| Get running fast | [Quickstart](./docs/quickstart.en.md) |
-| Use it well | [Usage guide](./docs/usage-guide.en.md) |
-| Run for free | [Free-tier guide](./docs/free-tier-guide.en.md) |
-| Launch llama.cpp / vllm via GUI | [Launcher guide](./docs/launcher.md) |
-| Stuck? | [Troubleshooting](./docs/troubleshooting.en.md) |
-| Understand the design | [Architecture](./docs/architecture.md) |
+| Get running fast | [Quickstart](./docs/start/quickstart.en.md) |
+| Use it well | [Usage guide](./docs/guides/usage-guide.en.md) |
+| Run for free | [Free-tier guide](./docs/guides/free-tier-guide.en.md) |
+| Launch llama.cpp / vllm via GUI | [Launcher guide](./docs/backends/launcher.md) |
+| Stuck? | [Troubleshooting](./docs/guides/troubleshooting.en.md) |
+| Understand the design | [Architecture](./docs/concepts/architecture.md) |
 | Full release history | [CHANGELOG](./CHANGELOG.md) |
 
-日本語: [Quickstart](./docs/quickstart.md) · [利用ガイド](./docs/usage-guide.md) · [無料枠ガイド](./docs/free-tier-guide.md) · [トラブルシューティング](./docs/troubleshooting.md)
+日本語: [Quickstart](./docs/start/quickstart.md) · [利用ガイド](./docs/guides/usage-guide.md) · [無料枠ガイド](./docs/guides/free-tier-guide.md) · [トラブルシューティング](./docs/guides/troubleshooting.md)
 
 ---
 
@@ -198,10 +198,10 @@ More detail → [Usage guide](./docs/usage-guide.en.md) · [Architecture](./docs
 
 | Symptom | Cause | Details |
 |---|---|---|
-| 401 error | API key not set / missing `export` in `.env` | [§1](./docs/troubleshooting.en.md#1-five-startup--config-gotchas-added-in-v162) |
-| Empty / garbage replies | Ollama `num_ctx` truncated to 2048 | [§3](./docs/troubleshooting.en.md#3-ollama-beginner--5-silent-fail-symptoms-v07-c) |
-| `<think>` tags leaking | Add `output_filters: [strip_thinking]` | [§3](./docs/troubleshooting.en.md#3-ollama-beginner--5-silent-fail-symptoms-v07-c) |
-| Tool calls misbehaving in Claude Code | Tool-call repair not kicking in | [§4](./docs/troubleshooting.en.md#4-claude-code-integration-gotchas-added-in-v162) |
+| 401 error | API key not set / missing `export` in `.env` | [§1](./docs/guides/troubleshooting.en.md#1-five-startup--config-gotchas-added-in-v162) |
+| Empty / garbage replies | Ollama `num_ctx` truncated to 2048 | [§3](./docs/guides/troubleshooting.en.md#3-ollama-beginner--5-silent-fail-symptoms-v07-c) |
+| `<think>` tags leaking | Add `output_filters: [strip_thinking]` | [§3](./docs/guides/troubleshooting.en.md#3-ollama-beginner--5-silent-fail-symptoms-v07-c) |
+| Tool calls misbehaving in Claude Code | Tool-call repair not kicking in | [§4](./docs/guides/troubleshooting.en.md#4-claude-code-integration-gotchas-added-in-v162) |
 
 Open `http://localhost:8088/dashboard` while debugging — most issues become visible in 10 seconds.
 
@@ -227,7 +227,7 @@ CodeRouter runs as an independent backend router layer. Point any project's `OPE
 
 ## Security
 
-Secrets go in env vars, not config files. See [`docs/security.en.md`](./docs/security.en.md) for the full policy and reporting instructions.
+Secrets go in env vars, not config files. See [`docs/security.en.md`](./docs/guides/security.en.md) for the full policy and reporting instructions.
 
 ## License
 

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/README.md

@@ -13,7 +13,7 @@
 </p>
 
 <p align="center">
-  <a href="./README.en.md">English</a> · <strong>日本語</strong> · <a href="./docs/quickstart.md">10 分で動かす</a> · <a href="./docs/architecture.md">設計詳細</a>
+  <a href="./README.en.md">English</a> · <strong>日本語</strong> · <a href="./docs/start/quickstart.md">10 分で動かす</a> · <a href="./docs/concepts/architecture.md">設計詳細</a>
 </p>
 
 ---
@@ -80,7 +80,7 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 | codex / gemini-cli + Ollama 直繋ぎで動いてる | オプション — フォールバックが欲しいなら |
 | Claude API を直接叩いてて問題ない | 不要 |
 
-詳細は → [要否判定ガイド](./docs/when-do-i-need-coderouter.md)
+詳細は → [要否判定ガイド](./docs/start/when-do-i-need-coderouter.md)
 
 ---
 
@@ -145,7 +145,7 @@ launcher:
           "--max-model-len": 4096
 ```
 
-詳細 → [Launcher ガイド](./docs/launcher.md)
+詳細 → [Launcher ガイド](./docs/backends/launcher.md)
 
 ---
 
@@ -172,7 +172,7 @@ providers:
     api_key_env: OPENROUTER_API_KEY
 ```
 
-もっと詳しい設定 → [利用ガイド](./docs/usage-guide.md) · [設計詳細](./docs/architecture.md)
+もっと詳しい設定 → [利用ガイド](./docs/guides/usage-guide.md) · [設計詳細](./docs/concepts/architecture.md)
 
 ---
 
@@ -180,15 +180,15 @@ providers:
 
 | やりたいこと | ドキュメント |
 |---|---|
-| すぐ動かす | [Quickstart](./docs/quickstart.md) |
-| 使いこなす | [利用ガイド](./docs/usage-guide.md) |
-| 無料で回す | [無料枠ガイド](./docs/free-tier-guide.md) |
-| llama.cpp / vllm を GUI で起動 | [Launcher ガイド](./docs/launcher.md) |
-| 詰まった | [トラブルシューティング](./docs/troubleshooting.md) |
-| 設計を知りたい | [アーキテクチャ詳細](./docs/architecture.md) |
+| すぐ動かす | [Quickstart](./docs/start/quickstart.md) |
+| 使いこなす | [利用ガイド](./docs/guides/usage-guide.md) |
+| 無料で回す | [無料枠ガイド](./docs/guides/free-tier-guide.md) |
+| llama.cpp / vllm を GUI で起動 | [Launcher ガイド](./docs/backends/launcher.md) |
+| 詰まった | [トラブルシューティング](./docs/guides/troubleshooting.md) |
+| 設計を知りたい | [アーキテクチャ詳細](./docs/concepts/architecture.md) |
 | 全リリース履歴 | [CHANGELOG](./CHANGELOG.md) |
 
-English: [Quickstart](./docs/quickstart.en.md) · [Usage guide](./docs/usage-guide.en.md) · [Free-tier](./docs/free-tier-guide.en.md) · [Troubleshooting](./docs/troubleshooting.en.md)
+English: [Quickstart](./docs/start/quickstart.en.md) · [Usage guide](./docs/guides/usage-guide.en.md) · [Free-tier](./docs/guides/free-tier-guide.en.md) · [Troubleshooting](./docs/guides/troubleshooting.en.md)
 
 ---
 
@@ -198,10 +198,10 @@ English: [Quickstart](./docs/quickstart.en.md) · [Usage guide](./docs/usage-gui
 
 | 症状 | 原因 | 詳細 |
 |---|---|---|
-| 401 エラー | API キー未設定 / `.env` に `export` 忘れ | [§1](./docs/troubleshooting.md#1-起動設定で踏みやすい-5-つの罠-v162-追加) |
-| 返信が空 / 意味不明 | Ollama の `num_ctx` が 2048 に切り詰め | [§3](./docs/troubleshooting.md#3-ollama-初心者--サイレント失敗-5-症状-v07-c) |
-| `<think>` タグが漏れる | `output_filters: [strip_thinking]` を付ける | [§3](./docs/troubleshooting.md#3-ollama-初心者--サイレント失敗-5-症状-v07-c) |
-| Claude Code でツール呼び出しがおかしい | tool-call 修復が効いてない | [§4](./docs/troubleshooting.md#4-claude-code-連携で踏みやすい罠-v162-追加) |
+| 401 エラー | API キー未設定 / `.env` に `export` 忘れ | [§1](./docs/guides/troubleshooting.md#1-起動設定で踏みやすい-5-つの罠-v162-追加) |
+| 返信が空 / 意味不明 | Ollama の `num_ctx` が 2048 に切り詰め | [§3](./docs/guides/troubleshooting.md#3-ollama-初心者--サイレント失敗-5-症状-v07-c) |
+| `<think>` タグが漏れる | `output_filters: [strip_thinking]` を付ける | [§3](./docs/guides/troubleshooting.md#3-ollama-初心者--サイレント失敗-5-症状-v07-c) |
+| Claude Code でツール呼び出しがおかしい | tool-call 修復が効いてない | [§4](./docs/guides/troubleshooting.md#4-claude-code-連携で踏みやすい罠-v162-追加) |
 
 `http://localhost:8088/dashboard` を開いておくと、ほとんどの問題が見て 10 秒でわかります。
 
@@ -227,7 +227,7 @@ CodeRouter は backend ルーター層として独立して動きます。`OPENA
 
 ## Security
 
-シークレットは環境変数に置きます。[`docs/security.md`](./docs/security.md) に完全な方針と報告手順があります。
+シークレットは環境変数に置きます。[`docs/security.md`](./docs/guides/security.md) に完全な方針と報告手順があります。
 
 ## License
 

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/coderouter/cli.py

@@ -61,7 +61,7 @@ def _build_parser() -> argparse.ArgumentParser:
             "binding the server. Repeat to layer multiple files. By "
             "default, file values do NOT override variables already in "
             "the environment (the shell `export` wins). See "
-            "docs/troubleshooting.md §5 for 1Password / direnv / sops "
+            "docs/guides/troubleshooting.md §5 for 1Password / direnv / sops "
             "integration recipes."
         ),
     )
@@ -116,7 +116,7 @@ def _build_parser() -> argparse.ArgumentParser:
             "POSIX file mode (0600 expected), .gitignore coverage, "
             "and git-tracking state. Bare `--check-env` (no PATH) "
             "looks for `./.env` then `~/.coderouter/.env`. "
-            "See docs/troubleshooting.md §5 for the threat model."
+            "See docs/guides/troubleshooting.md §5 for the threat model."
         ),
     )
     doctor.add_argument(

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/coderouter/config/capability_registry.py

@@ -109,7 +109,7 @@ class RegistryCapabilities(BaseModel):
             "harness. ``degraded`` = the model over-eagerly invokes "
             "tools/skills when given Claude Code's system prompt — e.g. "
             "Llama-3.3-70B treating small talk like ``こんにちは`` as "
-            "``Skill(hello)`` invocations (see docs/troubleshooting.md "
+            "``Skill(hello)`` invocations (see docs/guides/troubleshooting.md "
             "§4-1 for the symptom log). ``ok`` = explicitly verified "
             "clean. ``None`` = no opinion (treated as ``ok`` at the "
             "startup check)."

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/coderouter/data/model-capabilities.yaml

@@ -35,7 +35,7 @@
 #                                       Claude Code's agentic-coding harness;
 #                                       "degraded" triggers a startup WARN when
 #                                       the provider is on a `claude-code-*`
-#                                       chain. See docs/troubleshooting.md §4-1.
+#                                       chain. See docs/guides/troubleshooting.md §4-1.
 #
 # First-match semantics: rules within a file are evaluated top-to-bottom
 # per flag; the first rule whose glob matches AND declares that flag
@@ -153,7 +153,7 @@ rules:
   # Llama-3.3-70B (verified 2026-04-24 against NVIDIA NIM) rewrites
   # ``こんにちは`` into ``Skill(hello)`` invocations and fabricates
   # ``AskUserQuestion("What is your name?")`` elicitations — see
-  # docs/articles/note-nvidia-nim.md §6-2 + docs/troubleshooting.md §4-1.
+  # docs/articles/note/note-nvidia-nim.md §6-2 + docs/guides/troubleshooting.md §4-1.
   #
   # Glob coverage: NIM uses ``meta/llama-3.3-70b-instruct``, OpenRouter
   # uses ``meta-llama/llama-3.3-70b-instruct``, some local servers use

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/coderouter/ingress/launcher_routes.py

@@ -1,13 +1,13 @@
 """Launcher routes — ``GET /launcher`` + ``/api/launcher/*``.
 
-llama.cpp / vllm プロセス管理 UI。
+llama.cpp / vllm / mlx プロセス管理 UI。
 
 設計方針:
 - ダッシュボードと同じ "1ファイル完結" スタイル (Tailwind CDN + inline JS)
 - プロセスレジストリは app.state.launcher に持たせる (再起動で消えるが意図通り)
 - option_profiles は providers.yaml の launcher: セクションで管理 → コード変更不要で拡張可
 - 複数プロセスの同時起動に対応 (UUID ベースの ID 管理)
-- llama.cpp / vllm どちらも同じ key-value args スキーマで統一
+- llama.cpp / vllm / mlx いずれも同じ key-value args スキーマで統一
 
 エンドポイント:
   GET  /launcher                   → HTML UI
@@ -62,7 +62,7 @@ class ManagedProcess:
 
     id: str
     name: str
-    backend: str         # "llama.cpp" | "vllm"
+    backend: str         # "llama.cpp" | "vllm" | "mlx"
     model_path: str
     port: int
     options: dict[str, Any]
@@ -150,6 +150,7 @@ def _scan_models(model_dirs: list[str]) -> list[dict[str, Any]]:
 _BACKEND_DEFAULTS: dict[str, str] = {
     "llama.cpp": "llama-server",
     "vllm": "python",
+    "mlx": "python",          # mlx_lm.server (Apple Silicon 向け)
 }
 
 
@@ -252,14 +253,32 @@ def _model_recommendation(size_gb: float, hw: dict[str, Any]) -> dict[str, str]:
     return {"level": "warn", "label": "メモリ厳しい"}
 
 
-def _suggest_launch_flags(size_gb: float, hw: dict[str, Any]) -> str:
-    """選択モデル + ハードから -ngl / --ctx-size / --threads を提案する。
+def _suggest_launch_flags(backend: str, size_gb: float,
+                          hw: dict[str, Any]) -> str:
+    """選択モデル + ハード + バックエンドから推奨起動フラグを提案する。
 
+    バックエンドごとにフラグ体系が違うため分岐する:
+      - llama.cpp : -ngl / --ctx-size / --threads を算出
+      - vllm      : モデル config からの自動導出に任せる (空文字)
+      - mlx       : 統合メモリ前提で起動時フラグ不要 (空文字)
     あくまで目安。他プロセスのメモリ使用や量子化方式までは考慮しない。
     """
-    threads = max(1, int(hw.get("cpu_count", 4)) - 2)
+    if backend == "mlx":
+        # MLX は統合メモリ + Metal 前提。llama.cpp の -ngl に相当する
+        # レイヤーオフロードの概念がなく、mlx_lm.server は起動時の
+        # 性能チューニングフラグを取らない。
+        return ""
+    if backend == "vllm":
+        # vllm の --max-model-len はモデルの実コンテキスト長に依存する。
+        # メモリ量だけのヒューリスティックで値を出すと、モデルの上限を
+        # 超えたときに vllm が起動を拒否する。空にしてエンジンの
+        # 自動導出 (モデル config) に任せるのが安全。
+        return ""
+
+    # llama.cpp (デフォルト)
     usable = _usable_memory_gb(hw)
     weights = size_gb * 1.15                       # 重み + オーバーヘッド概算
+    threads = max(1, int(hw.get("cpu_count", 4)) - 2)
     if hw.get("gpu") == "cpu":
         ngl = 0
     elif usable >= weights + 1.0:
@@ -312,8 +331,17 @@ def _build_cmd(
             "--model", model_path,
             "--port", str(port),
         ]
+    elif backend == "mlx":
+        cmd = [
+            exe, "-m", "mlx_lm.server",
+            "--model", model_path,
+            "--port", str(port),
+        ]
     else:
-        raise ValueError(f"Unknown backend: {backend!r}. Expected 'llama.cpp' or 'vllm'.")
+        raise ValueError(
+            f"Unknown backend: {backend!r}. "
+            "Expected 'llama.cpp', 'vllm' or 'mlx'."
+        )
 
     for flag, val in options.items():
         if isinstance(val, bool):
@@ -610,17 +638,20 @@ async def api_logs(proc_id: str, request: Request, n: int = 100) -> dict[str, An
 
 
 @router.get("/api/launcher/suggest")
-async def api_suggest(model_path: str = "") -> dict[str, Any]:
+async def api_suggest(model_path: str = "",
+                      backend: str = "llama.cpp") -> dict[str, Any]:
     """Suggest launch flags for the given model based on detected hardware.
 
     クライアントの「推奨値」ボタンから呼ばれる。値はあくまで目安。
+    バックエンドごとにフラグ体系が違うため backend も受け取る。
     """
     hw = await asyncio.to_thread(_detect_hardware)
     size_gb = 0.0
     if model_path:
         size_gb = await asyncio.to_thread(_model_size_gb, model_path)
     return {
-        "extra_args": _suggest_launch_flags(size_gb, hw),
+        "extra_args": _suggest_launch_flags(backend, size_gb, hw),
+        "backend": backend,
         "hardware": hw,
         "size_gb": round(size_gb, 2),
     }
@@ -720,6 +751,7 @@ _LAUNCHER_HTML = r"""<!doctype html>
         <select id="f-backend" onchange="onBackendChange()">
           <option value="llama.cpp">llama.cpp</option>
           <option value="vllm">vllm</option>
+          <option value="mlx">mlx</option>
         </select>
         <div id="binary-hint" class="mt-1 text-xs text-slate-500 min-h-[1.2rem]"></div>
       </div>
@@ -894,14 +926,24 @@ _LAUNCHER_HTML = r"""<!doctype html>
   window.suggestOptions = async () => {
     const model = document.getElementById("f-model").value.trim();
     if (!model) { showLaunchErr("先にモデルを選択してください"); return; }
+    const backend = document.getElementById("f-backend").value;
     try {
       const r = await fetch("/api/launcher/suggest?model_path="
-                            + encodeURIComponent(model));
+                            + encodeURIComponent(model)
+                            + "&backend=" + encodeURIComponent(backend));
       const d = await r.json();
       if (!r.ok) { showLaunchErr(d.detail || "推奨値の取得に失敗"); return; }
       document.getElementById("f-extra").value = d.extra_args;
       showLaunchErr("");
-      statusMsg("推奨値を設定(目安): " + d.extra_args);
+      if (d.extra_args) {
+        statusMsg("推奨値を設定(目安): " + d.extra_args);
+      } else if (backend === "mlx") {
+        statusMsg("MLX は起動時の調整フラグ不要です(統合メモリで自動)");
+      } else if (backend === "vllm") {
+        statusMsg("vllm は起動時フラグ不要です(モデル設定から自動導出)");
+      } else {
+        statusMsg("このバックエンドは推奨フラグの自動設定対象外です");
+      }
     } catch (e) {
       showLaunchErr(e.message);
     }
@@ -961,7 +1003,7 @@ _LAUNCHER_HTML = r"""<!doctype html>
     // Enable/disable launch button based on binary availability
     if (!info.found) {
       btn.disabled = true;
-      showLaunchErr(`⚠ "${esc(info.resolved)}" が見つかりません。llama.cpp をインストールするか、providers.yaml の launcher.backends.llama\\.cpp.binary にフルパスを設定してください。`);
+      showLaunchErr(`⚠ "${esc(info.resolved)}" が見つかりません。選択中のバックエンド (${esc(backend)}) をインストールするか、providers.yaml の launcher.backends.${esc(backend)}.binary にフルパスを設定してください。`);
     } else {
       btn.disabled = false;
       // Clear error only if it was a binary-not-found error

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/coderouter/logging.py

@@ -779,7 +779,7 @@ def log_output_filter_applied(
 # v1.7-B: chain-claude-code-suitability-degraded log shape
 #
 # Motivation (plan.md §11.B.4 #2):
-#   v1.6.2 documented in docs/troubleshooting.md §4-1 that putting
+#   v1.6.2 documented in docs/guides/troubleshooting.md §4-1 that putting
 #   Llama-3.3-70B at the head of a Claude-Code-facing chain causes
 #   over-eager tool invocation (small talk like ``こんにちは`` getting
 #   rewritten to ``Skill(hello)`` calls). Docs alone require the operator
@@ -805,7 +805,7 @@ def log_output_filter_applied(
 _DEFAULT_CLAUDE_CODE_SUITABILITY_HINT: str = (
     "move the degraded provider(s) to the tail of the chain or replace "
     "with an agentic-coding-tuned model (e.g. qwen3-coder-480b-a35b-instruct); "
-    "see docs/troubleshooting.md §4-1"
+    "see docs/guides/troubleshooting.md §4-1"
 )
 
 

{coderouter_cli-2.5.0 → coderouter_cli-2.5.2}/coderouter/routing/capability.py

@@ -312,7 +312,7 @@ def anthropic_request_has_cache_control(request: AnthropicRequest) -> bool:
 # v1.7-B: claude_code_suitability startup check
 #
 # Motivation (plan.md §11.B.4 #2):
-#   v1.6.2 documented in docs/troubleshooting.md §4-1 the "Llama-3.3-70B
+#   v1.6.2 documented in docs/guides/troubleshooting.md §4-1 the "Llama-3.3-70B
 #   over-eagerly invokes Skill() for small talk under Claude Code"
 #   symptom. v1.7-B promotes that hint from prose-only to a structured
 #   automatic startup WARN: at app startup we scan every profile whose