coderouter-cli 1.8.0__tar.gz → 1.8.1__tar.gz

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/CHANGELOG.md

@@ -6,6 +6,79 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v1.8.1] — 2026-04-26 (実機検証反映 patch — mode_aliases 解決 + Gemma 4 第一候補化 + Ollama 既知問題ドキュメント化)
+
+**Theme: v1.8.0 出荷直後の実機検証 (M3 Max 32GB / Ollama 0.21.2) で踏んだ問題 3 件を patch で解消。**
+
+v1.8.0 の用途別 4 プロファイルが、NIM example yaml ベースで運用しているユーザーで `coderouter serve --mode coding` が **`default_profile 'coding' is not declared in profiles`** エラーで起動失敗する loader bug が判明。あわせて `coding` profile の primary に置いていた Qwen3.6:27b/35b が Ollama 経由で実用厳しい (num_ctx silent cap / tool_calls 0 / streaming 0 chars) ことも実機検証で確認。**「note 記事や HF 評判が高くても Ollama 経由ですぐ動くとは限らない」現実**を troubleshooting.md §4-2 として明文化。
+
+- Tests: 729 → **730** (+1: loader の mode_aliases 解決テスト)
+- Runtime deps: 5 → 5 (19 sub-release 連続据え置き)
+- Backward compat: 完全互換、`providers.yaml` 編集不要 (loader が alias 経由で解決)
+
+### Changes
+
+#### Bug fixes (実機検証で踏んだもの)
+
+- **`coderouter/config/loader.py`**: `CODEROUTER_MODE` env (= `--mode` CLI) が **`mode_aliases` を解決せず直接 `default_profile` に代入** していた v0.6-A の素朴実装を修正。runtime の `X-CodeRouter-Mode` ヘッダ (v0.6-D) は alias 解決していたので、startup と runtime で semantic 非対称だった。v1.8.1 で env_mode を `mode_aliases` 経由で解決してから `default_profile` 代入する流れに揃え、両者を symmetric に。これで `cr serve --mode coding` が NIM example yaml (profiles=`[claude-code-nim, ...]`、mode_aliases=`{coding: claude-code-nim}`) でも validation エラーにならず起動する
+- **`examples/providers.nvidia-nim.yaml`**: v1.8.0 で main `providers.yaml` に追加した `mode_aliases` (default/coding/general/multi/reasoning/fast/cheap/think/vision) を NIM example yaml にも追加。NIM ユーザーも `--mode coding|general|reasoning|multi` を canonical な短縮 alias として使えるように
+
+#### `coding` profile primary を実機検証反映に調整
+
+- **`examples/providers.yaml`**: `coding` profile の providers リスト先頭を Qwen3.6:35b/27b → **`ollama-qwen-coder-14b` / `ollama-gemma4-26b` / `ollama-qwen-coder-7b` / `ollama-qwen3-coder-30b`** の順に変更。Qwen3.6 系は末尾退避線にコメントアウトで降格 (LM/llama.cpp が後日対応強化されたら primary に戻す候補として残置)。順序原則「枯れて確実に動くもの」を上に、note 推奨の新しいものは安定確認後に昇格、を反映
+- **`coderouter/data/model-capabilities.yaml`**: `qwen3.6:*` / `qwen/qwen3.6-*` の `claude_code_suitability: ok` を**撤回**。v1.7-B 追加時は note 記事の伝聞ベースで先回り宣言していたが、v1.8.1 実機検証で num_ctx / tool_calls / streaming すべて NEEDS_TUNING 確認、確証ない以上 `tools` 宣言だけ残して suitability は出さない方針に。実機で動いた人は `~/.coderouter/model-capabilities.yaml` で `claude_code_suitability: ok` を user-side override 可能 (registry の first-match-per-flag walk が user → bundled の順序なので)
+
+#### Documentation: 実機 Ollama 運用の Known Issues 追加
+
+- **`docs/troubleshooting.md` §4-2 新設「ローカル Ollama 経由で踏みやすい既知問題」**:
+  - **§4-2-A**: Qwen3.6:27b/35b が Ollama 0.21.2 経由で実用厳しい (num_ctx silent cap / tool_calls 0 / streaming 0)、`/no_think` でも改善せず。回避は Gemma 4 / Qwen2.5-Coder を上位に
+  - **§4-2-B**: Qwen3.5 系 HF 蒸留モデル (Qwopus3.5 等) は llama.cpp が `qwen35` architecture (hybrid Transformer-SSM) 未対応で `unable to load model` 500 エラー。フレームワーク本体の対応待ち
+  - **§4-2-C**: Gemma 4 26B が無加工で tool_calls OK 確認、note 記事「日常の王者」評価が裏付け
+  - **§4-2-D**: ベスト実践「枯れたモデル + 観測ツール (doctor)」、HF で見つけた新モデルは `ollama run` → server log で `unknown model architecture` 確認、出たら今は諦め
+
+### Why
+
+v1.8.0 出荷で「用途別 4 プロファイルで `--mode coding` が使える」と謳ったが、NIM example yaml ベースのユーザーが踏むことが分かった loader bug は**最初の実プロンプト到達前に validation で死ぬ**ので最重要修正。あわせて、v1.8.0 example の primary に置いていた Qwen3.6 系列が実機で 3 つの probe NEEDS_TUNING を出すこと、Qwen3.5 ベース HF 蒸留が llama.cpp 未対応であることは、**「先回り実装より実機 evidence」原則** (plan.md §5.4) を再確認させる結果。
+
+### Migration
+
+`pyproject.toml version 1.8.0 → 1.8.1`、`coderouter --version` は 1.8.1 を返す。**手元の `~/.coderouter/providers.yaml` は触らない限り完全に変化なし**。
+
+NIM example ベースで `cr serve --mode coding` が動かなかったユーザーは、
+
+```bash
+# 最新 example をコピー (v1.8.1 で mode_aliases 追加済み)
+cp examples/providers.nvidia-nim.yaml ~/.coderouter/providers.yaml
+# あるいは手で mode_aliases セクションを既存ファイルに追加
+```
+
+または、`cr` をローカル開発版から再 install:
+
+```bash
+uv tool install --reinstall --force --from /path/to/CodeRouter coderouter-cli --with ruamel.yaml
+```
+
+### Real-machine verification
+
+```
+$ pytest -q
+730 passed, 1 skipped in 1.86s
+
+$ ruff check coderouter/ tests/
+All checks passed!
+
+$ cr serve --port 8088 --mode coding   # NIM example yaml でも起動成功
+$ cr doctor --check-model ollama-gemma4-26b --apply   # tool_calls OK 確認済み
+```
+
+### Out of scope / 次回送り
+
+- Qwen3.5 系 HF 蒸留 (Qwopus / 類似): llama.cpp が `qwen35` architecture を実装したら再評価
+- Qwen3.6:27b/35b の Ollama 経由動作: Ollama / llama.cpp 側の改善があれば再評価、`claude_code_suitability` を再付与の検討
+- v1.7-C 候補 (network audit / launcher / 起動時 update check) は引き続き需要待ち
+
+---
+
 ## [v1.8.0] — 2026-04-26 (用途別 4 プロファイル + GLM/Gemma 4/Qwen3.6 公式化 + apply 自動化)
 
 **Theme: 「Claude Code で意味合いがズレない代替モデル」を operator に渡す minor。** plan.md §11.B (v1.7-B umbrella) を 6 タスクで一気に消化:

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 1.8.0
+Version: 1.8.1
 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

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/coderouter/config/loader.py

@@ -49,8 +49,35 @@ def load_config(path: str | os.PathLike[str] | None = None) -> CodeRouterConfig:
     # fail can be rescued by an explicit env-set mode, and (b) the model-
     # validator's "default_profile must exist in profiles" check applies to the
     # *effective* mode the engine will see, not the pre-override YAML value.
+    #
+    # v1.8.0+: also resolve env_mode through ``mode_aliases`` before assigning,
+    # so that startup-time ``--mode coding`` (env CODEROUTER_MODE=coding)
+    # behaves symmetrically with the runtime ``X-CodeRouter-Mode: coding``
+    # header — both should accept short intent names like ``coding`` /
+    # ``general`` / ``reasoning`` and resolve them to the underlying profile
+    # (e.g. ``claude-code-nim`` in providers.nvidia-nim.yaml). Without this,
+    # users on the NIM example yaml hit
+    #   "default_profile 'coding' is not declared in profiles:
+    #    known=['claude-code-nim', ...]"
+    # because mode_aliases only fired at request time, not at startup.
     env_mode = os.environ.get("CODEROUTER_MODE", "").strip()
     if env_mode:
+        # Pre-validation alias resolution: if env_mode isn't directly a
+        # profile name but matches an entry in raw["mode_aliases"], swap it
+        # for the underlying profile name. This avoids forcing every example
+        # yaml to mirror the v1.8.0 four-profile names (multi/coding/general
+        # /reasoning) just to accept the canonical short --mode flags.
+        raw_profiles = raw.get("profiles", []) or []
+        profile_names = {
+            p.get("name") for p in raw_profiles if isinstance(p, dict)
+        }
+        raw_aliases = raw.get("mode_aliases", {}) or {}
+        if (
+            env_mode not in profile_names
+            and isinstance(raw_aliases, dict)
+            and env_mode in raw_aliases
+        ):
+            env_mode = raw_aliases[env_mode]
         raw["default_profile"] = env_mode
 
     config = CodeRouterConfig.model_validate(raw)

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/coderouter/data/model-capabilities.yaml

@@ -168,26 +168,36 @@ rules:
       claude_code_suitability: ok
 
   # ------------------------------------------------------------------
-  # Qwen3.6 family (v1.7-B 追加)
+  # Qwen3.6 family (v1.7-B 追加、v1.8.1 で suitability 撤回)
   #
   # 2026-04 リリースの Qwen3.6 シリーズ。Ollama 公式 tag は
-  # qwen3.6:27b / qwen3.6:35b、全 variant が tools+vision+thinking 対応、
-  # 256K context。note 記事 (r/LocalLLaMA 2026-04 Megathread) で
-  # 「Claude Code 代替として最高」「local champ」と評価。
-  # Qwen3-Coder と並んで Claude Sonnet 互換性が高い。
+  # qwen3.6:27b / qwen3.6:35b、metadata 上は tools+vision+thinking 対応、
+  # 256K context を宣言。note 記事 (r/LocalLLaMA 2026-04 Megathread) で
+  # 「Claude Code 代替として最高」「local champ」と評価されている。
+  #
+  # ただし v1.8.0 までで `claude_code_suitability: ok` を declare していた
+  # のは note 記事の伝聞ベースの先回り宣言で、v1.8.1 (2026-04-26) の
+  # 実機検証 (M3 Max 32GB / Ollama 0.21.2) で次の課題が判明:
+  #   - num_ctx を declare 32768 しても Ollama 側で silent に縮められる
+  #     (canary echo-back probe 失敗)
+  #   - tool_calls probe が native tool_calls / 修復可能 JSON のいずれも
+  #     返さず NEEDS_TUNING
+  #   - streaming probe が finish_reason='length' で 0 chars 打ち切り
+  # これらは Ollama 経由特有の問題で、HF / vLLM 直接ロードなら違う可能性。
+  # 確証ない以上、`claude_code_suitability` は撤回し `tools` 宣言だけ残す。
+  # 実機で動いたユーザーは `~/.coderouter/model-capabilities.yaml` で
+  # `claude_code_suitability: ok` を上書きできる。
   # ------------------------------------------------------------------
 
   - match: "qwen3.6:*"
     kind: openai_compat
     capabilities:
       tools: true
-      claude_code_suitability: ok
 
   - match: "qwen/qwen3.6-*"
     kind: openai_compat
     capabilities:
       tools: true
-      claude_code_suitability: ok
 
   # ------------------------------------------------------------------
   # Gemma 4 family (v1.7-B 追加)
@@ -233,3 +243,99 @@ rules:
     kind: openai_compat
     capabilities:
       tools: true
+
+  # ------------------------------------------------------------------
+  # Kimi K2 family (Moonshot AI、v1.8.0 追加)
+  #
+  # NVIDIA NIM 経由で実機検証済み (2026-04-23) の tool-capable モデル。
+  # examples/providers.nvidia-nim.yaml の `nim-kimi-k2` / `nim-kimi-k2-thinking`
+  # で運用実績あり。Unsloth tool-calling guide にも tool calling 対応モデル
+  # として掲載 (Kimi K2.5 / K2 Thinking)。providers.yaml 側で個別の
+  # `capabilities.tools: true` 宣言を省略可能にするのが目的。
+  # ------------------------------------------------------------------
+
+  - match: "moonshotai/kimi-k2*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  - match: "moonshotai/Kimi-K2*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  # ------------------------------------------------------------------
+  # gpt-oss family (OpenAI 117B MoE オープンウェイト、v1.8.0 追加)
+  #
+  # OpenRouter free 経由で実機検証済み (`openai/gpt-oss-120b:free` を
+  # examples/providers.yaml の `openrouter-gpt-oss-free` で運用)。
+  # native tool calling 設計、131K context、Unsloth tool-calling guide
+  # にも tool calling 対応モデルとして掲載 (gpt-oss)。
+  # ------------------------------------------------------------------
+
+  - match: "openai/gpt-oss-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  - match: "gpt-oss-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  # ------------------------------------------------------------------
+  # 先回り宣言 family (Unsloth tool-calling guide 掲載、v1.8.0 追加)
+  #
+  # Unsloth のローカル LLM tool-calling ガイド
+  # (https://unsloth.ai/docs/jp/ji-ben/tool-calling-guide-for-local-llms)
+  # で tool-calling 対応モデルとして掲載されているが、CodeRouter 側で
+  # 実機検証は未実施。tools=true の事前宣言だけ入れて、providers.yaml で
+  # これらを使う際の `capabilities.tools: true` 明示宣言を不要にする。
+  # claude_code_suitability は実機検証後に追加判断 — それまでは "意見なし"。
+  # 不具合があれば user-side の `~/.coderouter/model-capabilities.yaml` で
+  # `tools: false` を declare して上書き可能 (first-match-per-flag)。
+  # ------------------------------------------------------------------
+
+  # DeepSeek-V3.x — DeepSeek-AI の主力 (V3.1 / V3.2 等)
+  - match: "deepseek-ai/DeepSeek-V3*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  - match: "deepseek/deepseek-v3*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  # MiniMax — MiniMaxAI の MoE 系
+  - match: "MiniMaxAI/MiniMax-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  - match: "minimax/minimax-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  # NVIDIA Nemotron 3 — Nano 系の小型モデル
+  - match: "nvidia/nemotron-3-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  - match: "nvidia/Nemotron-3-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  # Devstral 2 — Mistral AI の coding 特化 fine-tune
+  - match: "mistralai/Devstral-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  - match: "mistral/devstral*"
+    kind: openai_compat
+    capabilities:
+      tools: true

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/docs/hf-ollama-models.md

@@ -237,6 +237,8 @@ ollama cp hf.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:Q4_K_M qwen3-coder:30b
 
 - Ollama HF integration: <https://huggingface.co/docs/hub/en/ollama>
 - Unsloth (高速量子化版の代表的アップローダー): <https://huggingface.co/unsloth>
+- **Unsloth: Tool calling guide for local LLMs (日本語)**: <https://unsloth.ai/docs/jp/ji-ben/tool-calling-guide-for-local-llms>
+  — Qwen / Llama / Gemma など local LLM で tool-call が動かない／壊れる原因と対策をモデル別に整理。CodeRouter で `tool_calls: NEEDS_TUNING` が出たときの背景理解にちょうど良い。
 - bartowski (品質重視の量子化版): <https://huggingface.co/bartowski>
 - Qwen3-Coder (Alibaba 公式): <https://huggingface.co/collections/Qwen/qwen3-coder>
 - Gemma 4 (Google 公式): <https://huggingface.co/collections/google/gemma-4>

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/docs/troubleshooting.en.md

@@ -187,6 +187,8 @@ coderouter doctor --check-model <provider>
 
 With `tools: false` the chain moves on to the next provider when a tool-heavy request arrives. Pair this with a stronger model later in the chain (e.g. qwen2.5-coder:14b or a cloud fallback).
 
+> **Further reading**: Unsloth's [Tool calling guide for local LLMs](https://unsloth.ai/docs/jp/ji-ben/tool-calling-guide-for-local-llms) (Japanese) walks through per-model tool-call quirks (Qwen / Llama / Gemma) — a useful background read when CodeRouter's doctor flags `tool_calls: NEEDS_TUNING` and you want to understand why.
+
 **3. `<think>...</think>` tags leak into the UI.** Qwen3-distilled models, DeepSeek-R1 distills, and some HF GGUF variants emit chain-of-thought inside the regular content channel (not an Anthropic `thinking` block). The tags land in Claude Code's terminal verbatim.
 
 ```bash
@@ -278,6 +280,8 @@ profiles:
 
 `examples/providers.nvidia-nim.yaml` (v1.6.2 onwards) ships with the Qwen-first ordering. Llama-3.3-70B works fine for many things, but for Claude Code chat traffic specifically, Qwen3-Coder-480B / Kimi-K2 are operationally more stable.
 
+> **Background on per-model tool-call behavior**: Llama-3.3-70B's tendency to rewrite plain text into tool calls comes from its aggressive agentic-tuning RLHF signal interacting with Claude Code's system prompt. Unsloth's [Tool calling guide for local LLMs](https://unsloth.ai/docs/jp/ji-ben/tool-calling-guide-for-local-llms) (Japanese) covers this and other model-specific quirks well — useful background for the v1.8.0 `claude_code_suitability` heuristic.
+
 ### 4-2. `UserPromptSubmit hook error` (third-party Claude Code plugins)
 
 ```

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/docs/troubleshooting.md

@@ -187,6 +187,8 @@ coderouter doctor --check-model <provider>
 
 `tools: false` にすると、ツール要求リクエスト到来時にチェーンは次のプロバイダに進みます。強いモデル (qwen2.5-coder:14b やクラウドフォールバック) と組み合わせて使ってください。
 
+> **補足資料**: モデル別の tool-call 対応状況や、量子化 / システムプロンプト / chat template の落とし穴は Unsloth の [Tool calling guide for local LLMs (日本語)](https://unsloth.ai/docs/jp/ji-ben/tool-calling-guide-for-local-llms) にきれいにまとまっています。Qwen / Llama / Gemma 各系列で tool-call が動かない原因を踏み込んで知りたい人向け。
+
 **3. UI に `<think>...</think>` タグが漏れる。** Qwen3 蒸留モデル、DeepSeek-R1 蒸留、一部の HF GGUF 変種は chain-of-thought を Anthropic の `thinking` ブロックではなく通常のコンテンツチャネルに吐きます。タグが Claude Code のターミナルにそのまま出ます。
 
 ```bash
@@ -278,7 +280,64 @@ profiles:
 
 `examples/providers.nvidia-nim.yaml` (v1.6.2 以降) は Qwen-first の順序になっています。Llama-3.3-70B 自体は動作確認済みですが、Claude Code 単独の対話用途では Qwen3-Coder-480B / Kimi-K2 のほうが運用上は安定します。
 
-### 4-2. `UserPromptSubmit hook error` が出る (第三者 Claude Code プラグイン)
+> **モデル別 tool-call 挙動の深掘り**: Llama-3.3-70B 系の「自然文を tool 呼び出しに変換しがち」性質は、agentic tuning の RLHF signal とシステムプロンプトの相性に起因します。各モデルの傾向と回避策は Unsloth の [Tool calling guide for local LLMs (日本語)](https://unsloth.ai/docs/jp/ji-ben/tool-calling-guide-for-local-llms) が読みやすく、CodeRouter v1.8.0 で導入した `claude_code_suitability` 判定の背景理解にも役立ちます。
+
+### 4-2. ローカル Ollama 経由で踏みやすい既知問題 (v1.8.1 追記)
+
+2026-04-26 の実機検証 (M3 Max 32GB / Ollama 0.21.2 / CodeRouter v1.8.0) で、**note 記事や HF で評価が高いモデルでも Ollama 経由では動かないケース**が判明したのでまとめます。
+
+#### 4-2-A. **Qwen3.6:27b / 35b** が Claude Code で実用厳しい
+
+`coderouter doctor --check-model ollama-qwen3-6-27b` の結果：
+
+| Probe | 結果 | 症状 |
+|---|---|---|
+| auth+basic-chat | OK | 短い chat なら動く |
+| **num_ctx** | **NEEDS_TUNING** | `extra_body.options.num_ctx: 32768` を declare しても canary echo されない (Ollama が silent に縮めてる疑い) |
+| **tool_calls** | **NEEDS_TUNING** | native tool_calls / 修復可能 JSON のいずれも返さず |
+| **streaming** | **NEEDS_TUNING** | `finish_reason='length'` で 0 chars 打ち切り |
+
+`/no_think` を `append_system_prompt` に入れても改善せず。Ollama 0.21.2 / llama.cpp 側の Qwen3.6 family 対応がまだ完全でない可能性が高い。
+
+**回避**: `claude-code-nim` profile の primary に Qwen3.6 を置かず、**Gemma 4 26B または Qwen2.5-Coder 14b を上位に**。bundled `model-capabilities.yaml` も v1.8.1 で `qwen3.6:*` の `claude_code_suitability: ok` を撤回 (declaration 過信の例)。
+
+#### 4-2-B. **Qwen3.5 系の HF 蒸留モデル** (Qwopus3.5 等) は llama.cpp 未対応
+
+例えば `Jackrong/Qwopus3.5-9B-v3-GGUF` (Qwen3.5-VL ベース + Claude Opus 蒸留、Apache-2.0、Vision) を `ollama pull` すると **blob は完全に落ちてくる**が `ollama run` で：
+
+```
+Error: 500 Internal Server Error: unable to load model:
+  ...sha256-19d52ddc.../...
+```
+
+Ollama server log を見ると：
+
+```
+llama_model_load: error loading model: error loading model architecture:
+  unknown model architecture: 'qwen35'
+```
+
+**原因**: Qwen3.5 は新アーキテクチャ (hybrid Transformer-SSM、`qwen35.ssm.*` 系のキーが GGUF metadata に含まれる) で、llama.cpp / Ollama に **`qwen35` architecture 実装が未マージ**。Ollama version の問題ではなく、フレームワーク本体の対応待ち。
+
+**回避**: 現状は HF / Transformers / vLLM 直接ロード経由で使うしかない (CodeRouter は Ollama OpenAI-compat 経由なので非対応)。llama.cpp が `qwen35` を実装したら再評価。
+
+> **教訓**: HF で「Qwen3.5 + Opus 蒸留」のような新しい組み合わせは note / r/LocalLLaMA で評判が立っていても、**Ollama 経由ですぐ使えるとは限らない**。`ollama pull` → `ollama run` で 500 が出たら、まず Ollama server log で `unknown model architecture` を確認。出たら今は諦めて他のモデルに行くのが時間効率的に正解。
+
+#### 4-2-C. **Gemma 4 26B** は無加工で tool_calls OK
+
+同じ実機検証で `coderouter doctor --check-model ollama-gemma4-26b` の `tool_calls` probe が **無加工で `[OK]`**。`num_ctx` / `streaming` は patch (`--apply`) で解消可能。Ollama 経由 Claude Code 用途では **note 記事の「Gemma 4 が日常の王者」評価が裏付けられた**形。v1.8.1 で `coding` profile primary を Gemma 4 / Qwen-Coder 14b へ調整しています。
+
+#### 4-2-D. ベスト実践 — 「枯れたモデル + 観測ツール」
+
+実機運用での提案：
+
+1. **第一候補は枯れたもの**: `qwen2.5-coder:14b` / `qwen2.5-coder:7b` / `gemma4:26b` / `gemma4:e4b`
+2. **doctor で確認**: `cr doctor --check-model <provider>` で 6 probe を回す
+3. **`--apply` で patch 適用**: NEEDS_TUNING の YAML パッチを非破壊書き戻し (`pip install 'coderouter-cli[doctor]'` 必要)
+4. **新興モデルは慎重に**: HF で見つけた新モデルは Ollama 0.20+ でも未対応のことあり、`ollama run` → server log で確認
+5. **fallback chain で守る**: ローカル primary が落ちても NIM / OpenRouter free に流れるように chain を厚く
+
+### 4-3. `UserPromptSubmit hook error` が出る (第三者 Claude Code プラグイン)
 
 ```
 ❯ こんにちは

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/examples/providers.nvidia-nim.yaml

@@ -112,6 +112,33 @@ allow_paid: false
 default_profile: claude-code-nim
 display_timezone: Asia/Tokyo
 
+# v1.8.0: NIM example でも `--mode coding|general|reasoning|multi` を
+# 受けられるように、メイン examples/providers.yaml と同じ短縮 alias を
+# 用意。ユーザーが「examples/providers.yaml の説明通りの mode を試したら
+# default_profile 'coding' is not declared」エラーで詰まるのを回避。
+#
+# alias 解決:
+#   coding    → claude-code-nim   (NIM 主軸の coding chain)
+#   general   → claude-code-nim   (NIM は general 専用 profile が無いので兼用)
+#   reasoning → nim-reasoning     (Kimi-K2-Thinking 起点の長文推論 chain)
+#   multi     → claude-code-nim   (NIM ネイティブ vision profile は未提供。
+#                                  画像が必要なら examples/providers.yaml の
+#                                  multi profile (Gemma 4 26B vision) を併用)
+#   default   → claude-code-nim
+#   fast      → free-only-nim     (有料を絶対に呼ばない安全重視)
+#   cheap     → free-only-nim
+#   think     → nim-reasoning
+mode_aliases:
+  default: claude-code-nim
+  coding: claude-code-nim
+  general: claude-code-nim
+  reasoning: nim-reasoning
+  multi: claude-code-nim
+  fast: free-only-nim
+  cheap: free-only-nim
+  think: nim-reasoning
+  vision: claude-code-nim
+
 providers:
   # ------------------------------------------------------------
   # Tier 1: local (same as the main examples/providers.yaml)

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/examples/providers.yaml

@@ -533,6 +533,13 @@ providers:
     api_key_env: Z_AI_API_KEY
     paid: true
     timeout_s: 60
+    # Unsloth tool-calling guide
+    # (https://unsloth.ai/docs/jp/ji-ben/tool-calling-guide-for-local-llms)
+    # の GLM 4.7 推奨値。Claude Code が temperature/top_p を明示的に
+    # 投げてくる場合はそちらが優先される (extra_body は default)。
+    extra_body:
+      temperature: 0.7
+      top_p: 1.0
     capabilities:
       chat: true
       streaming: true
@@ -857,21 +864,33 @@ profiles:
       - anthropic-direct               # paid: Sonnet 4-6 with vision (★★★★★)
 
   # --------------------------------------------------------------------------
-  # coding — Claude Code / agentic coding 用。Qwen3.6 / Qwen3-Coder 主軸。
+  # coding — Claude Code / agentic coding 用。
   # --------------------------------------------------------------------------
-  # Sonnet の tool-call 行動に最も近い Qwen3.6 35B-A3B を local primary に
-  # 置き、Qwen3-Coder family を量サイズ別の fallback、cloud は NIM/OR の
-  # qwen3-coder:free、最後に Sonnet または GLM-4.7 有料。
+  # 2026-04-26 実機検証 (M3 Max 32GB / Ollama 0.21.2) を反映:
+  #   - Gemma 4 26B が tool_calls を無加工で OK (Ollama 公式 tag、note "日常の王者")
+  #   - Qwen-Coder 14b/7b は v0.x からの実機検証済み (枯れた選択)
+  #   - Qwen3.6 27b/35b は num_ctx を Ollama が silent に縮める /
+  #     tool_calls が出ない / streaming 0 chars の三重課題で Ollama 経由
+  #     では実用厳しい (HF / vLLM 直なら可かもしれない、要再検証)
+  #   - Qwen3-Coder 30B は llama.cpp 対応モデルで、Qwen3.6 系列より安定
+  #
+  # 順序原則: 「枯れて確実に動くもの」を上、「note 推奨だが新しい」は
+  # その後に置く。Sonnet の tool-call 行動に最も近いのは依然として
+  # Qwen3-Coder family (agentic coding 専用設計)。
   - name: coding
     append_system_prompt: |
       Match Claude Sonnet's coding style: terse, structured, tools used precisely.
       Prefer code blocks over prose. Avoid filler explanations unless asked.
       When using tools, batch independent operations in parallel.
     providers:
-      - ollama-qwen3-6-35b             # local primary (note "local champ")
-      - ollama-qwen3-coder-30b         # local: agentic-coding 特化 fallback
-      - ollama-qwen-coder-14b          # local quality fallback
+      - ollama-qwen-coder-14b          # local primary (実機検証済み、枯れた選択)
+      - ollama-gemma4-26b              # local: tool_calls OK 実機確認 (note 推奨)
       - ollama-qwen-coder-7b           # local fast fallback
+      - ollama-qwen3-coder-30b         # local: agentic-coding 専用 (llama.cpp 対応)
+      # Qwen3.6 系は Ollama 経由で実用厳しいので末尾退避線。マシンに余裕
+      # ある + llama.cpp が後日対応強化されたら primary に戻す候補:
+      # - ollama-qwen3-6-27b
+      # - ollama-qwen3-6-35b
       - openrouter-free                # cloud: qwen3-coder:free (262K ctx)
       - openrouter-gpt-oss-free        # cloud: vendor diversity (rate-limit 逃げ)
       - zai-coding-glm-4-7             # paid: GLM-4.7 (Sonnet 級、Z.AI Coding Plan)

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/pyproject.toml

@@ -11,7 +11,7 @@
 # in plan.md §11.B; once granted, this name will become an alias and
 # `coderouter` will become the canonical distribution name.
 name = "coderouter-cli"
-version = "1.8.0"
+version = "1.8.1"
 description = "Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible."
 readme = "README.md"
 requires-python = ">=3.12"

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/tests/test_capability_registry.py

@@ -403,6 +403,52 @@ def test_bundled_yaml_does_not_flag_other_llama_families_as_degraded() -> None:
     )
 
 
+# ======================================================================
+# v1.8.0: Unsloth tool-calling guide 掲載モデル群の registry 反映
+# ======================================================================
+
+
+@pytest.mark.parametrize(
+    "model_slug",
+    [
+        # Kimi K2 family — NIM で実機検証済み
+        "moonshotai/kimi-k2-instruct",
+        "moonshotai/kimi-k2-thinking",
+        "moonshotai/Kimi-K2-Instruct",
+        # gpt-oss — OpenRouter free で実機検証済み
+        "openai/gpt-oss-120b:free",
+        "openai/gpt-oss-20b",
+        "gpt-oss-120b",
+        # DeepSeek-V3.x — Unsloth ガイド掲載 (先回り宣言)
+        "deepseek-ai/DeepSeek-V3.1",
+        "deepseek-ai/DeepSeek-V3.2",
+        "deepseek/deepseek-v3.1",
+        # MiniMax — Unsloth ガイド掲載
+        "MiniMaxAI/MiniMax-M2",
+        "minimax/minimax-m2",
+        # NVIDIA Nemotron 3 — Unsloth ガイド掲載
+        "nvidia/nemotron-3-nano-9b",
+        "nvidia/Nemotron-3-Nano-12B",
+        # Devstral 2 — Unsloth ガイド掲載
+        "mistralai/Devstral-2-24B",
+        "mistral/devstral-2",
+    ],
+)
+def test_bundled_yaml_unsloth_listed_models_resolve_tools_true(model_slug: str) -> None:
+    """v1.8.0: Unsloth tool-calling guide 掲載 (Kimi K2 / gpt-oss / DeepSeek-V3 /
+    MiniMax / Nemotron / Devstral) の各 family が tools=true で解決される。
+
+    providers.yaml で個別に capabilities.tools: true を declare しなくても、
+    bundled registry がデフォルトで tool-call 対応として扱う。
+    """
+    reg = CapabilityRegistry.load_default()
+    result = reg.lookup(kind="openai_compat", model=model_slug)
+    assert result.tools is True, (
+        f"{model_slug}: Unsloth ガイド掲載 family は registry が "
+        f"tools=true を返すべき (got tools={result.tools!r})"
+    )
+
+
 def test_lookup_any_kind_rule_matches_both_adapter_kinds() -> None:
     """A rule with kind='any' applies regardless of the adapter kind."""
     reg = CapabilityRegistry(

{coderouter_cli-1.8.0 → coderouter_cli-1.8.1}/tests/test_config.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from pathlib import Path
 
 import pytest
+import yaml
 
 from coderouter.config.loader import load_config, resolve_api_key
 from coderouter.config.schemas import CodeRouterConfig
@@ -73,6 +74,68 @@ def test_env_overrides_default_profile(
         load_config(yaml_config_path)
 
 
+def test_env_mode_resolves_through_mode_aliases_at_startup(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """v1.8.0: CODEROUTER_MODE goes through mode_aliases before validation.
+
+    Matches the runtime ``X-CodeRouter-Mode`` header semantics — startup
+    should accept canonical short intent names (``coding`` / ``general`` /
+    ``reasoning`` / ``multi`` / ``fast`` / ``cheap``) and resolve them to
+    the underlying profile via ``mode_aliases`` instead of failing
+    validation with "default_profile 'coding' is not declared".
+
+    Repro for the v1.8.0 NIM-yaml bug: the user's providers.yaml has
+    profiles=[claude-code-nim, ...] and mode_aliases={coding:claude-code-nim};
+    ``coderouter serve --mode coding`` (= env CODEROUTER_MODE=coding) used to
+    blow up because env_mode was assigned directly to default_profile
+    bypassing the alias map.
+    """
+    cfg_file = tmp_path / "providers.yaml"
+    cfg_file.write_text(
+        yaml.safe_dump(
+            {
+                "default_profile": "claude-code-nim",
+                "mode_aliases": {
+                    "coding": "claude-code-nim",
+                    "reasoning": "nim-reasoning",
+                },
+                "providers": [
+                    {
+                        "name": "p",
+                        "kind": "openai_compat",
+                        "base_url": "http://localhost:11434/v1",
+                        "model": "x",
+                    }
+                ],
+                "profiles": [
+                    {"name": "claude-code-nim", "providers": ["p"]},
+                    {"name": "nim-reasoning", "providers": ["p"]},
+                ],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    # Alias should resolve: 'coding' → 'claude-code-nim'.
+    monkeypatch.setenv("CODEROUTER_MODE", "coding")
+    cfg = load_config(cfg_file)
+    assert cfg.default_profile == "claude-code-nim", (
+        f"CODEROUTER_MODE=coding should resolve through mode_aliases to "
+        f"'claude-code-nim', got {cfg.default_profile!r}"
+    )
+
+    # Direct profile names still work.
+    monkeypatch.setenv("CODEROUTER_MODE", "claude-code-nim")
+    cfg = load_config(cfg_file)
+    assert cfg.default_profile == "claude-code-nim"
+
+    # Unknown intent (not in profiles, not in aliases) → fast-fail.
+    monkeypatch.setenv("CODEROUTER_MODE", "totally-unknown")
+    with pytest.raises(ValueError, match="totally-unknown"):
+        load_config(cfg_file)
+
+
 def test_env_override_default_profile_ignores_empty_string(
     yaml_config_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None: