coderouter-cli 2.10.0__tar.gz → 2.11.0__tar.gz

{coderouter_cli-2.10.0 → coderouter_cli-2.11.0}/CHANGELOG.md

@@ -9,6 +9,109 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.11.0] — 2026-07-28 (launcher backend variants)
+
+### Added
+
+- **Backend variants — pick which llama.cpp build to launch.**
+  `launcher.backends` now accepts keys of the form `<base>-<variant>`
+  (`llama.cpp-cuda`, `llama.cpp-vulkan`, `llama.cpp-rocm`), each naming
+  an additional build of the same backend with its own `binary` path.
+  Declared variants appear as extra entries in the Launcher's backend
+  select (GUI and Web) marked `⚙`, and each one gets its own
+  `--list-devices` probe, its own `option_profiles`, and can be pinned
+  per model in `launcher.swap`. Motivation: on a machine with mixed
+  GPUs the visible devices differ per build — the CUDA build enumerates
+  `CUDA0`/`CUDA1` (RTX 5090 + 3090) while the Vulkan build also
+  enumerates `Vulkan2` (Radeon 8060S) and the ROCm build only the
+  Radeon — so the best build varies by model. Previously `binary` held
+  a single path and switching meant editing `providers.yaml` and
+  restarting. Docs: `docs/backends/launcher.md` "特化ビルドの切り替え",
+  design: `docs/designs/launcher-multi-build.md`.
+- **`option_profiles` inheritance for variants.** A variant key
+  inherits the base backend's presets and appends its own; a preset
+  whose `name` collides replaces the inherited one *in place* (order
+  stays stable, no duplicate at the tail). Shared presets no longer
+  need duplicating under every variant key. Shared implementation:
+  `launcher_devices.resolve_option_profiles` (used by the Web routes,
+  the Tk GUI and `launcher_swap`).
+- **Cross-build bench sweep.** With two or more llama.cpp builds
+  declared, the sweep panel shows a "⚙ ビルド横断" button that probes
+  every build and generates configurations labelled
+  `cuda / CUDA0 単体`, `vulkan / Vulkan2 単体`, … Running the sweep
+  launches the same model on each build in turn, so one sweep answers
+  "which build is fastest for this model". `SweepStep.backend` /
+  `SweepConfigItem.backend` carry the per-step build; `None` keeps the
+  previous plan-wide behaviour. New
+  `launcher_devices.build_cross_variant_sweep_configs`. Configurations
+  never mix devices across builds — one process runs one executable.
+- **Device-id namespace guard.** Device ids are build-specific
+  (`CUDA0` and `Vulkan0` are not the same GPU). Switching backend in
+  either launcher now clears the device selection, and
+  `POST /api/launcher/start` / `sweep/start` reject ids that do not
+  exist in the chosen build with a 400 instead of letting
+  `--device CUDA0` reach a Vulkan build and fail at startup. Skipped
+  when `--list-devices` itself fails (best-effort, per the
+  `hardware.py` invariant). New `launcher_devices.unknown_device_ids`.
+
+### Changed
+
+- **BREAKING: `launcher.backends` keys are now validated.** A key must
+  be `llama.cpp` / `vllm` / `mlx` or one of those with a
+  `-<variant>` suffix (variant matching `[a-z0-9][a-z0-9._-]*`).
+  Previously any key was accepted and silently ignored, because the
+  backend list was a hard-coded set of three; a typo such as
+  `llamacpp:` therefore had no effect and no warning. It is now a
+  config-load error. Check key spelling if startup fails after
+  upgrading.
+- **A backend variant must set `binary`.** Allowing it to be omitted
+  would fall back to the base default on PATH, meaning an operator who
+  selected `llama.cpp-cuda` could silently get the plain build — the
+  hardest failure of this feature to notice. Rejected at config load.
+  Base keys keep `binary` optional (PATH resolution), unchanged.
+- **The Launcher's backend list is now config-derived.** Both launchers
+  build the select from the three base backends plus whatever variants
+  `launcher.backends` declares, instead of a hard-coded list. Declaring
+  no variants yields exactly the previous three entries, so specialized
+  builds stay invisible to operators who have not opted in.
+- `SwapModelSpec.backend` relaxed from
+  `Literal["llama.cpp","vllm","mlx"]` to a validated `str` so it can
+  name a variant; the three previous values still validate unchanged.
+  When a variant is named, config load verifies it is declared in
+  `launcher.backends`.
+- `GET /api/launcher/backends` entries gained `base` and `variant`
+  keys. All pre-existing keys (`resolved` / `configured` / `default` /
+  `is_custom` / `found`) are unchanged.
+
+### Fixed
+
+- **Backend-name branches are normalized through a single helper.**
+  Backend name drove behaviour in ten places, several of which would
+  have failed *open* for a variant name rather than raising. Two
+  mattered: `_MODEL_FLAGS.get(backend, frozenset())` would have
+  returned an empty set and **disabled the H8 model-override guard**
+  (letting `options` / `extra_args` re-specify `-m` and load an
+  arbitrary model), and `_backend_ready`'s
+  `backend in ("llama.cpp","vllm")` would have degraded readiness to a
+  bare TCP connect — re-introducing the bug readiness gating was added
+  to fix (provider registered before the model finished loading). All
+  branches now go through `launcher_devices.base_backend()`, in
+  `launcher_routes.py`, `launcher_speculative.py`, `launcher_gui.py`
+  and the inline SPA JS. `_assert_no_model_override` additionally
+  became fail-closed: an unrecognized base uses the union of every
+  banned flag set rather than an empty one.
+
+### Tests
+
+- 4 new files, 150 new cases (`test_launcher_backend_variants.py`,
+  `test_launcher_variant_config.py`, `test_launcher_variant_routes.py`,
+  `test_launcher_variant_sweep.py`, `test_launcher_variant_gui.py`).
+  The fail-open branches above each have a 1:1 regression test, plus
+  byte-identical-argv and unchanged-API-payload tests for configs
+  without variants. Suite: 2098 passed, ruff clean.
+
+---
+
 ## [v2.10.0] — 2026-07-20 (VSCode workspace scaffolder)
 
 ### Added

{coderouter_cli-2.10.0 → coderouter_cli-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.10.0
+Version: 2.11.0
 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
@@ -224,6 +224,7 @@ providers:
 | **ログビューア** | 各プロセスの stdout/stderr をブラウザ内でリアルタイム確認 |
 | **provider 自動同期** (v2.7.4) | 起動したバックエンドを provider として自動登録(`launcher-llamacpp-8085` 等)。providers.yaml 無編集で `X-CodeRouter-Profile: launcher` からルーティング可能。メモリ内のみ・serve と同寿命 |
 | **モデル名パススルー** (v2.7.4) | `model: ""` の provider は `/v1/models` が上流のロード中モデル ID(gguf 名)をそのまま返す。gguf を差し替えても config 編集不要 — 外部ベンチからモデルを識別できる |
+| **特化ビルドの切り替え** (v2.11.0) | `llama.cpp-cuda` / `-vulkan` / `-rocm` を `backends` に登録すると、起動ごとにどのビルドの `llama-server` を使うか選べる。ビルド別にデバイス検出・option_profiles・ベンチスイープが独立(書かなければ従来どおり) |
 
 ```yaml
 # providers.yaml に追記するだけで有効になる

{coderouter_cli-2.10.0 → coderouter_cli-2.11.0}/README.en.md

@@ -69,6 +69,8 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 
 That's it. Claude Code works as usual, but your local Ollama is answering behind the scenes.
 
+**From VSCode's integrated terminal**, avoid the env-var footgun with `coderouter vscode-init`. Run it once at your project root and it merges `terminal.integrated.env.*` into `.vscode/settings.json`, so `claude` in VSCode's terminal just works from then on. Cheat-sheet snippets for Cline / Roo Code / Continue.dev are printed at the end of the same run → [VSCode integration guide](./docs/guides/vscode.md) (JP only for now).
+
 ---
 
 ## Do you need it?
@@ -217,6 +219,7 @@ More detail → [Usage guide](./docs/guides/usage-guide.en.md) · [Architecture]
 | 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) |
 | Measure & avoid the language tax | [Language Tax guide](./docs/guides/language-tax.en.md) |
+| Use from VSCode / Cline / Continue | [VSCode integration guide](./docs/guides/vscode.md) (JP) |
 | Reach it safely from another machine | [Remote access guide](./docs/guides/remote-access.en.md) |
 | Stuck? | [Troubleshooting](./docs/guides/troubleshooting.en.md) |
 | Understand the design | [Architecture](./docs/concepts/architecture.md) |

{coderouter_cli-2.10.0 → coderouter_cli-2.11.0}/README.md

@@ -179,6 +179,7 @@ providers:
 | **ログビューア** | 各プロセスの stdout/stderr をブラウザ内でリアルタイム確認 |
 | **provider 自動同期** (v2.7.4) | 起動したバックエンドを provider として自動登録(`launcher-llamacpp-8085` 等)。providers.yaml 無編集で `X-CodeRouter-Profile: launcher` からルーティング可能。メモリ内のみ・serve と同寿命 |
 | **モデル名パススルー** (v2.7.4) | `model: ""` の provider は `/v1/models` が上流のロード中モデル ID(gguf 名)をそのまま返す。gguf を差し替えても config 編集不要 — 外部ベンチからモデルを識別できる |
+| **特化ビルドの切り替え** (v2.11.0) | `llama.cpp-cuda` / `-vulkan` / `-rocm` を `backends` に登録すると、起動ごとにどのビルドの `llama-server` を使うか選べる。ビルド別にデバイス検出・option_profiles・ベンチスイープが独立(書かなければ従来どおり) |
 
 ```yaml
 # providers.yaml に追記するだけで有効になる

{coderouter_cli-2.10.0 → coderouter_cli-2.11.0}/coderouter/config/schemas.py

@@ -17,7 +17,14 @@ import re
 import warnings
 from typing import Any, Literal, Self
 
-from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    HttpUrl,
+    field_validator,
+    model_validator,
+)
 
 
 class Capabilities(BaseModel):
@@ -1414,6 +1421,29 @@ class LauncherBackendConfig(BaseModel):
             binary: ~/llama.cpp/build/bin/llama-server
           vllm:
             binary: ~/.venv/bin/python
+
+    **Backend variants** (v2.11.0+, docs/designs/launcher-multi-build.md):
+    a key may also be ``<base>-<variant>`` to register an additional build of
+    the same backend — typically llama.cpp compiled for a specific GPU
+    runtime. Each variant appears as its own entry in the Launcher's backend
+    select, gets its own ``--list-devices`` probe (device IDs differ per
+    build: ``CUDA0`` and ``Vulkan0`` are not the same GPU) and can carry its
+    own ``option_profiles``. ``binary`` is **required** for a variant::
+
+        backends:
+          llama.cpp:                    # 素のビルド (binary 省略可 = PATH)
+            binary: ~/llm/apps/llama.cpp/build/bin/llama-server
+          llama.cpp-cuda:
+            binary: ~/llm/apps/llama.cpp/build-cuda/bin/llama-server
+          llama.cpp-vulkan:
+            binary: ~/llm/apps/llama.cpp/build-vulkan/bin/llama-server
+          llama.cpp-rocm:
+            binary: ~/llm/apps/llama.cpp/build-rocm/bin/llama-server
+
+    Variants are an advanced option: the matching GPU runtime (CUDA Toolkit /
+    Vulkan runtime + ICD / ROCm) must already be installed by the operator.
+    CodeRouter never selects a variant implicitly — omit them and both the UI
+    and the resulting argv are identical to before.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -1544,9 +1574,39 @@ class SwapModelSpec(BaseModel):
             "only widens *catalog* matching for ``SwapManager.match``."
         ),
     )
-    backend: Literal["llama.cpp", "vllm", "mlx"] = Field(
-        ..., description="Same backend set as the manual launcher UI / _build_cmd.",
+    backend: str = Field(
+        ...,
+        description=(
+            "Same backend set as the manual launcher UI / _build_cmd: "
+            "'llama.cpp' / 'vllm' / 'mlx', optionally with a '-<variant>' "
+            "suffix naming a specific build declared in launcher.backends "
+            "(e.g. 'llama.cpp-cuda' to pin this model to the CUDA build). "
+            "Validated by the field validator below plus "
+            "LauncherConfig._check_swap_backends_declared."
+        ),
     )
+
+    @field_validator("backend")
+    @classmethod
+    def _check_backend_name(cls, v: str) -> str:
+        """基底名 or 既知基底名 + 妥当なバリアントのみ許す。
+
+        以前は ``Literal["llama.cpp","vllm","mlx"]`` だった。バリアント
+        (``llama.cpp-cuda``) を通すため str に緩めたので、代わりに形式検証を
+        ここで行う。既存の 3 値はそのまま通る (後方互換)。
+        """
+        from coderouter.launcher_devices import (
+            KNOWN_BASE_BACKENDS,
+            is_valid_backend_name,
+        )
+
+        if not is_valid_backend_name(v):
+            raise ValueError(
+                f"backend {v!r} is not valid. Expected one of "
+                f"{list(KNOWN_BASE_BACKENDS)} or '<base>-<variant>' "
+                "(e.g. 'llama.cpp-cuda')."
+            )
+        return v
     model_path: str = Field(
         ...,
         description=(
@@ -1802,10 +1862,13 @@ class LauncherConfig(BaseModel):
         default_factory=dict,
         description=(
             "Per-backend binary path overrides. "
-            "Keys are backend names ('llama.cpp', 'vllm'). "
-            "When a key is absent, the default executable is used "
-            "('llama-server' / 'python') and resolved via PATH. "
-            "Useful when running a from-source build or a venv-specific binary."
+            "Keys are backend names ('llama.cpp', 'vllm', 'mlx') or backend "
+            "variants ('llama.cpp-cuda', 'llama.cpp-vulkan', ...) naming an "
+            "additional build of the same backend — see "
+            "LauncherBackendConfig. When a base key is absent, the default "
+            "executable is used ('llama-server' / 'python') and resolved via "
+            "PATH. Variants must set 'binary' explicitly and additionally "
+            "appear in the Launcher's backend select."
         ),
     )
     option_profiles: dict[str, list[LauncherOptionProfile]] = Field(
@@ -1813,6 +1876,10 @@ class LauncherConfig(BaseModel):
         description=(
             "Named option presets per backend. "
             "Keys should be backend names: 'llama.cpp', 'vllm'. "
+            "A backend-variant key ('llama.cpp-cuda') is also accepted: its "
+            "presets are appended to the base backend's list, and a preset "
+            "whose 'name' collides replaces the inherited one in place "
+            "(see launcher_devices.resolve_option_profiles). "
             "Each key maps to an ordered list of named presets. "
             "A free-form 'extra args' field is always available in the UI "
             "for one-off overrides without touching this config."
@@ -1929,15 +1996,82 @@ class LauncherConfig(BaseModel):
             )
         return self
 
+    @model_validator(mode="after")
+    def _check_backend_names_and_variant_binaries(self) -> LauncherConfig:
+        """``backends`` のキー形式と、バリアントの ``binary`` 必須を検証する。
+
+        設計: docs/designs/launcher-multi-build.md §5.2。
+
+        1. キーは既知基底名 (``llama.cpp`` / ``vllm`` / ``mlx``) そのもの、
+           または ``<既知基底名>-<バリアント>`` (``llama.cpp-cuda`` 等) のみ。
+           **破壊的変更**: これまで ``llamacpp:`` のような typo は黙って無視
+           されていた (バックエンド一覧が固定 3 キーだったため)。今後は
+           ロード時エラーになる。
+        2. **バリアントは ``binary`` 必須**。``llama.cpp-cuda: {}`` を許すと
+           既定名フォールバックで PATH の ``llama-server`` が使われ、CUDA
+           ビルドを指定したつもりで素のビルドが静かに動く —— 本機能で最も
+           気づきにくい事故なのでロード時に殺す。基底名は従来どおり
+           ``binary`` 省略可 (PATH 解決)。
+        """
+        from coderouter.launcher_devices import (
+            KNOWN_BASE_BACKENDS,
+            is_valid_backend_name,
+            is_variant,
+        )
+
+        for name, bc in self.backends.items():
+            if not is_valid_backend_name(name):
+                raise ValueError(
+                    f"launcher.backends: invalid backend key {name!r}. "
+                    f"Expected one of {list(KNOWN_BASE_BACKENDS)} or "
+                    "'<base>-<variant>' where variant matches "
+                    "[a-z0-9][a-z0-9._-]* (e.g. 'llama.cpp-cuda')."
+                )
+            if is_variant(name) and not bc.binary:
+                raise ValueError(
+                    f"launcher.backends[{name!r}]: 'binary' is required for a "
+                    "backend variant. Without it the launcher would fall back "
+                    "to the base default on PATH and silently run a different "
+                    "build than the one you selected."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _check_swap_backends_declared(self) -> LauncherConfig:
+        """swap のモデルがバリアントを指すなら ``backends`` に実在すること。
+
+        設計 §5.2-3。基底名 (``llama.cpp`` 等) は ``backends`` に書かなくても
+        PATH 解決で動くので従来どおり不要。バリアントは実行ファイルパスが
+        ``backends`` にしか無いので、宣言漏れをロード時に弾く。
+        """
+        if self.swap is None:
+            return self
+        from coderouter.launcher_devices import is_variant
+
+        for spec in self.swap.models:
+            if is_variant(spec.backend) and spec.backend not in self.backends:
+                raise ValueError(
+                    f"launcher.swap.models[{spec.name!r}]: backend "
+                    f"{spec.backend!r} is a variant but is not declared in "
+                    "launcher.backends (its binary path is unknown)."
+                )
+        return self
+
     @model_validator(mode="after")
     def _check_swap_option_profiles_exist(self) -> LauncherConfig:
-        """§5.4 #2: a swap model's ``option_profile`` must be a real preset."""
+        """§5.4 #2: a swap model's ``option_profile`` must be a real preset.
+
+        バリアント backend の場合は基底名のプロファイルも継承されるので
+        (:func:`resolve_option_profiles`)、マージ後の一覧で判定する。
+        """
         if self.swap is None:
             return self
+        from coderouter.launcher_devices import resolve_option_profiles
+
         for spec in self.swap.models:
             if spec.option_profile is None:
                 continue
-            profiles = self.option_profiles.get(spec.backend, [])
+            profiles = resolve_option_profiles(self.option_profiles, spec.backend)
             if not any(p.name == spec.option_profile for p in profiles):
                 raise ValueError(
                     f"launcher.swap.models[{spec.name!r}]: option_profile "