coderouter-cli 1.7.0__py3-none-any.whl → 1.8.1__py3-none-any.whl

coderouter/cli.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import sys
+from pathlib import Path
 
 import uvicorn
 
@@ -126,6 +127,40 @@ def _build_parser() -> argparse.ArgumentParser:
             "./providers.yaml, or ~/.coderouter/providers.yaml."
         ),
     )
+    # v1.7-B (#3): --apply writes the doctor-emitted YAML patches back
+    # into providers.yaml / model-capabilities.yaml while preserving
+    # comments and key order. --dry-run is the same path minus the file
+    # write — prints a unified diff (``git apply``-compatible) for review.
+    # Bare ``--dry-run`` (without ``--apply``) is the canonical "preview"
+    # form; ``--apply --dry-run`` is also accepted as an explicit synonym
+    # so muscle-memory from ``git apply --dry-run`` works either way.
+    # Both flags are no-ops when --check-model is absent (--check-env
+    # has its own remediation surface and is not in scope for --apply).
+    # Implementation lives in coderouter/doctor_apply.py — round-trip
+    # via the optional ``ruamel.yaml`` dependency, see that module's
+    # docstring for the contract and shape invariants.
+    doctor.add_argument(
+        "--apply",
+        action="store_true",
+        help=(
+            "After --check-model, write the suggested patches back into "
+            "providers.yaml / model-capabilities.yaml. A `.bak` backup is "
+            "created next to each modified file. Idempotent: a re-run "
+            "after a successful apply is a no-op (no write, exit 0). "
+            "Requires the optional `ruamel.yaml` dependency — install "
+            "via `pip install coderouter-cli[doctor]`."
+        ),
+    )
+    doctor.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Preview --apply changes as a unified diff without writing "
+            "to disk. Implies --apply mode for diff generation. The "
+            "output is `git apply`-compatible so it can be saved and "
+            "applied later (or piped to `patch -p0`)."
+        ),
+    )
 
     # v1.5-C: `coderouter stats` — live TUI over GET /metrics.json.
     # Lazy-imports ``curses`` inside the runner so the CLI boot stays
@@ -283,7 +318,14 @@ def _run_doctor(args: argparse.Namespace) -> int:
 
 
 def _run_check_model(args: argparse.Namespace) -> int:
-    """v0.7-B: per-provider HTTP capability probe."""
+    """v0.7-B: per-provider HTTP capability probe.
+
+    v1.7-B (#3): when ``--apply`` or ``--dry-run`` is also set, we run
+    the same probes and then route the emitted patches through
+    :func:`coderouter.doctor_apply.apply_doctor_patches`. Bare probe
+    (no apply / dry-run flags) keeps the original behavior verbatim
+    so existing CI integrations don't change shape.
+    """
     from coderouter.config.loader import load_config
     from coderouter.doctor import (
         exit_code_for,
@@ -307,7 +349,131 @@ def _run_check_model(args: argparse.Namespace) -> int:
         return 1
 
     print(format_report(report))
-    return exit_code_for(report)
+    base_exit = exit_code_for(report)
+
+    apply_mode = bool(getattr(args, "apply", False))
+    dry_run_mode = bool(getattr(args, "dry_run", False))
+    if apply_mode or dry_run_mode:
+        # Resolve the same providers.yaml the loader picked up so the
+        # apply step writes back to the exact file that was probed
+        # (avoids a mismatch when CODEROUTER_CONFIG points elsewhere
+        # than the default path).
+        config_path = _resolve_config_path(args.config)
+        return _run_apply_or_dry_run(
+            report=report,
+            config_path=config_path,
+            write=apply_mode and not dry_run_mode,
+            base_exit=base_exit,
+        )
+
+    return base_exit
+
+
+def _resolve_config_path(explicit: str | None) -> Path:
+    """Mirror loader._candidate_paths and return the file actually used.
+
+    Used by ``--apply`` to write back to the same path the loader
+    picked up when it parsed providers.yaml. Falls through the same
+    search order so a ``CODEROUTER_CONFIG`` env or default-path lookup
+    matches the live config.
+    """
+    import os
+
+    candidates: list[Path] = []
+    if explicit:
+        candidates.append(Path(explicit))
+    if env_path := os.environ.get("CODEROUTER_CONFIG"):
+        candidates.append(Path(env_path))
+    candidates.append(Path.cwd() / "providers.yaml")
+    candidates.append(Path.home() / ".coderouter" / "providers.yaml")
+    for p in candidates:
+        if p.is_file():
+            return p
+    # Fall back to the last candidate even if absent — the apply step
+    # will surface a clearer error than this resolver would.
+    return candidates[-1]
+
+
+def _run_apply_or_dry_run(
+    *,
+    report: object,
+    config_path: Path,
+    write: bool,
+    base_exit: int,
+) -> int:
+    """v1.7-B (#3): drive ``apply_doctor_patches`` and render the result.
+
+    Returns 0 when the apply step itself is clean (regardless of
+    whether the underlying probes flagged ``NEEDS_TUNING``). The
+    rationale: once the operator has applied the patches, the next
+    ``doctor`` run is the right place to re-evaluate the chain — a
+    successful apply should not propagate the "exit 2 / needs tuning"
+    signal because the issue is now (presumably) addressed.
+    """
+    from coderouter.doctor_apply import (
+        DoctorApplyError,
+        MissingDependencyError,
+        apply_doctor_patches,
+    )
+
+    print()  # blank line between probe report and apply section
+    try:
+        result = apply_doctor_patches(
+            report=report,
+            config_path=config_path,
+            write=write,
+        )
+    except MissingDependencyError as exc:
+        print(f"doctor --apply: {exc}", file=sys.stderr)
+        return 1
+    except DoctorApplyError as exc:
+        print(f"doctor --apply: {exc}", file=sys.stderr)
+        return 1
+
+    label = "Apply" if write else "Dry-run"
+    print(f"{label}: {len(result.target_paths)} target file(s).")
+    if result.skipped_unknown_target:
+        print(
+            f"  warning: {len(result.skipped_unknown_target)} probe(s) "
+            f"emitted an unknown target_file value: "
+            f"{sorted(set(result.skipped_unknown_target))}",
+            file=sys.stderr,
+        )
+
+    if result.is_no_op:
+        # Distinguish "nothing to do because base_exit was 0" from
+        # "nothing to do because everything already applied":
+        if base_exit == 0:
+            print("  No NEEDS_TUNING patches to apply — chain is healthy.")
+        else:
+            print(
+                f"  All {result.no_op_patches} patch(es) already applied "
+                f"— providers.yaml is up to date."
+            )
+        return 0
+
+    print(
+        f"  {result.changes_applied} patch(es) applied"
+        + (f", {result.no_op_patches} already up to date" if result.no_op_patches else "")
+        + "."
+    )
+    for path in result.target_paths:
+        diff = result.diffs.get(str(path), "")
+        if not diff:
+            continue
+        print()
+        print(diff, end="" if diff.endswith("\n") else "\n")
+
+    if write:
+        for orig, bak in result.backups.items():
+            print(f"  Backup: {orig} → {bak}")
+    else:
+        print()
+        print("  (dry-run — no files were modified. Re-run with --apply to write.)")
+
+    return 0
+
+
 
 
 def _run_check_env(arg_value: str) -> int:

coderouter/config/capability_registry.py

@@ -102,6 +102,19 @@ class RegistryCapabilities(BaseModel):
             "doctor --check-model num_ctx probe (not consumed in v0.7-A)."
         ),
     )
+    claude_code_suitability: Literal["ok", "degraded"] | None = Field(
+        default=None,
+        description=(
+            "v1.7-B: hint for use behind Claude Code's agentic-coding "
+            "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 "
+            "§4-1 for the symptom log). ``ok`` = explicitly verified "
+            "clean. ``None`` = no opinion (treated as ``ok`` at the "
+            "startup check)."
+        ),
+    )
 
 
 class CapabilityRule(BaseModel):
@@ -168,6 +181,7 @@ class ResolvedCapabilities:
     reasoning_passthrough: bool | None = None
     tools: bool | None = None
     max_context_tokens: int | None = None
+    claude_code_suitability: Literal["ok", "degraded"] | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -218,11 +232,13 @@ class CapabilityRegistry:
         resolved_reasoning: bool | None = None
         resolved_tools: bool | None = None
         resolved_max_ctx: int | None = None
+        resolved_suitability: Literal["ok", "degraded"] | None = None
 
         thinking_locked = False
         reasoning_locked = False
         tools_locked = False
         max_ctx_locked = False
+        suitability_locked = False
 
         for rule in self._rules:
             if not rule.kind_matches(kind):
@@ -242,7 +258,16 @@ class CapabilityRegistry:
             if not max_ctx_locked and caps.max_context_tokens is not None:
                 resolved_max_ctx = caps.max_context_tokens
                 max_ctx_locked = True
-            if thinking_locked and reasoning_locked and tools_locked and max_ctx_locked:
+            if not suitability_locked and caps.claude_code_suitability is not None:
+                resolved_suitability = caps.claude_code_suitability
+                suitability_locked = True
+            if (
+                thinking_locked
+                and reasoning_locked
+                and tools_locked
+                and max_ctx_locked
+                and suitability_locked
+            ):
                 break
 
         return ResolvedCapabilities(
@@ -250,6 +275,7 @@ class CapabilityRegistry:
             reasoning_passthrough=resolved_reasoning,
             tools=resolved_tools,
             max_context_tokens=resolved_max_ctx,
+            claude_code_suitability=resolved_suitability,
         )
 
     # ------------------------------------------------------------------

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/data/model-capabilities.yaml

@@ -31,6 +31,11 @@
 #       reasoning_passthrough: bool   — opt OUT of the adapter's passive `reasoning` strip
 #       tools: bool                   — upstream reliably emits tool_calls
 #       max_context_tokens: int       — declared model context window
+#       claude_code_suitability: str  — "ok" | "degraded". Hint for use behind
+#                                       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.
 #
 # First-match semantics: rules within a file are evaluated top-to-bottom
 # per flag; the first rule whose glob matches AND declares that flag
@@ -84,3 +89,253 @@ rules:
     kind: anthropic
     capabilities:
       thinking: true
+
+  # ------------------------------------------------------------------
+  # Claude Code suitability — agentic harness compatibility hint (v1.7-B).
+  #
+  # "degraded" = the model over-eagerly invokes tools / skills when given
+  # Claude Code's system prompt, even for trivial small talk. Concretely,
+  # 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.
+  #
+  # Glob coverage: NIM uses ``meta/llama-3.3-70b-instruct``, OpenRouter
+  # uses ``meta-llama/llama-3.3-70b-instruct``, some local servers use
+  # ``Llama-3.3-70B-Instruct``. fnmatch is case-sensitive so we declare
+  # both common case-variants explicitly. The leading ``*`` wildcard
+  # absorbs any vendor-prefix slug (``meta/`` / ``meta-llama/`` / etc.).
+  #
+  # An operator who has tuned their Llama-3.3 deployment (custom system
+  # prompt, tool whitelist, etc.) can opt out via
+  # ``~/.coderouter/model-capabilities.yaml`` with the matching glob and
+  # ``claude_code_suitability: ok``.
+  # ------------------------------------------------------------------
+
+  - match: "*llama-3.3-70b*"
+    kind: openai_compat
+    capabilities:
+      claude_code_suitability: degraded
+
+  - match: "*Llama-3.3-70B*"
+    kind: openai_compat
+    capabilities:
+      claude_code_suitability: degraded
+
+  # ------------------------------------------------------------------
+  # Qwen3-Coder family — agentic coding 専用設計 (v1.7-B 追加)
+  #
+  # Alibaba の Qwen3-Coder series は agentic coding と tool use を
+  # 主目的に学習されており、Claude Sonnet の tool-call 行動に最も近い
+  # ローカル/オープン代替として知られています (note 記事 + r/LocalLLaMA
+  # 2026-04 Megathread コミュニティ評)。
+  #
+  # ここで `tools: true` を先回り宣言することで、providers.yaml 側で
+  # 個別に capabilities.tools: true を書かなくても tool-call 経路が
+  # 有効になります。`claude_code_suitability: ok` も併せて宣言、
+  # claude-code-* プロファイル startup check (v1.7-B) で degraded 警告が
+  # 出ないことを保証。
+  #
+  # glob 範囲 (case-sensitive — 大文字版も併記):
+  #   Ollama tag       : qwen3-coder:*       (例: qwen3-coder:30b-a3b)
+  #   NIM slug         : qwen/qwen3-coder-*  (例: qwen/qwen3-coder-480b-a35b-instruct)
+  #   OpenRouter slug  : qwen/qwen3-coder*   (例: qwen/qwen3-coder:free)
+  #   HF GGUF (Ollama) : hf.co/*/Qwen3-Coder-*-GGUF*  (大文字)
+  # ------------------------------------------------------------------
+
+  - match: "qwen3-coder:*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+      claude_code_suitability: ok
+
+  - match: "qwen/qwen3-coder-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+      claude_code_suitability: ok
+
+  - match: "qwen/qwen3-coder*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+      claude_code_suitability: ok
+
+  - match: "*Qwen3-Coder-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+      claude_code_suitability: ok
+
+  # ------------------------------------------------------------------
+  # Qwen3.6 family (v1.7-B 追加、v1.8.1 で suitability 撤回)
+  #
+  # 2026-04 リリースの Qwen3.6 シリーズ。Ollama 公式 tag は
+  # 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
+
+  - match: "qwen/qwen3.6-*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  # ------------------------------------------------------------------
+  # Gemma 4 family (v1.7-B 追加)
+  #
+  # Google 公式 Gemma 4。Ollama 公式 tag は gemma4:e2b / e4b / 26b / 31b、
+  # 全 variant が tools+vision+thinking 対応、E2B/E4B は audio もサポート。
+  # MoE (26b は active 3.8B / total 25.2B)。note 記事で「日常・バランスの
+  # 王者」と評価。Claude Haiku 互換性に近い簡潔な応答スタイル。
+  # ------------------------------------------------------------------
+
+  - match: "gemma4:*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  - match: "google/gemma-4*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  # ------------------------------------------------------------------
+  # GLM family (Z.AI / Zhipu AI、v1.7-B 追加)
+  #
+  # Z.AI の OpenAI-compat エンドポイントから利用する GLM-4.x / 5.x 系列。
+  # モデル名 slug は **大文字必須** (Cursor 等のドキュメント明記)。
+  # tools / vision 対応、Coding Plan の API 経由でも General API 経由でも
+  # 同じモデルが利用可能。
+  #
+  # GLM-5.1 / GLM-5-Turbo: Opus 級フラッグシップ
+  # GLM-4.7: Sonnet/Opus 級、Coding Plan のデフォルト
+  # GLM-4.5-Air: Haiku 級、軽量・高速
+  #
+  # note 記事は「intent 理解が Claude Opus 級」と評価。reasoning 用途に
+  # 特に向く。
+  # ------------------------------------------------------------------
+
+  - match: "GLM-5*"
+    kind: openai_compat
+    capabilities:
+      tools: true
+
+  - match: "GLM-4.[5-9]*"
+    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