coderouter-cli 1.7.0__py3-none-any.whl

coderouter/config/loader.py

@@ -0,0 +1,73 @@
+"""Load and validate CodeRouter configuration.
+
+Search order (first hit wins):
+    1. Path passed explicitly (CLI --config flag)
+    2. $CODEROUTER_CONFIG env var
+    3. ./providers.yaml (current working dir)
+    4. ~/.coderouter/providers.yaml
+
+Secrets are resolved by reading the env var named by `api_key_env`.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+from coderouter.config.schemas import CodeRouterConfig
+
+
+def _candidate_paths(explicit: str | os.PathLike[str] | None) -> list[Path]:
+    paths: list[Path] = []
+    if explicit:
+        paths.append(Path(explicit))
+    if env_path := os.environ.get("CODEROUTER_CONFIG"):
+        paths.append(Path(env_path))
+    paths.append(Path.cwd() / "providers.yaml")
+    paths.append(Path.home() / ".coderouter" / "providers.yaml")
+    return paths
+
+
+def load_config(path: str | os.PathLike[str] | None = None) -> CodeRouterConfig:
+    """Load providers.yaml + apply ALLOW_PAID env override."""
+    candidates = _candidate_paths(path)
+    chosen: Path | None = next((p for p in candidates if p.is_file()), None)
+    if chosen is None:
+        searched = "\n  ".join(str(p) for p in candidates)
+        raise FileNotFoundError(
+            f"providers.yaml not found. Searched:\n  {searched}\n"
+            f"Hint: copy examples/providers.yaml to ~/.coderouter/providers.yaml"
+        )
+
+    with chosen.open("r", encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+
+    # v0.6-A: CODEROUTER_MODE env overrides the YAML default_profile BEFORE
+    # initial validation, so that (a) a typo'd file default that would otherwise
+    # 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.
+    env_mode = os.environ.get("CODEROUTER_MODE", "").strip()
+    if env_mode:
+        raw["default_profile"] = env_mode
+
+    config = CodeRouterConfig.model_validate(raw)
+
+    # Env var ALLOW_PAID overrides file value (so users can flip it per-shell)
+    env_paid = os.environ.get("ALLOW_PAID", "").strip().lower()
+    if env_paid in {"1", "true", "yes", "on"}:
+        config.allow_paid = True
+    elif env_paid in {"0", "false", "no", "off"}:
+        config.allow_paid = False
+
+    return config
+
+
+def resolve_api_key(api_key_env: str | None) -> str | None:
+    """Look up an API key from the named env var. Returns None if unset."""
+    if not api_key_env:
+        return None
+    value = os.environ.get(api_key_env, "").strip()
+    return value or None

coderouter/config/schemas.py

@@ -0,0 +1,515 @@
+"""Pydantic schemas for providers.yaml and runtime config.
+
+Design notes (see plan.md §2 / §5.4):
+- Capability flags let providers declare what they support.
+- `paid: true` providers are blocked unless ALLOW_PAID=true (memo.txt §2.3).
+- Adapter `kind` in v0.3.x:
+    - "openai_compat": llama.cpp / Ollama / OpenRouter / LM Studio / Together / Groq ...
+    - "anthropic":     native Anthropic Messages API passthrough (api.anthropic.com,
+                       or any server speaking the Anthropic wire format). When the
+                       Anthropic ingress routes to this provider, no translation is
+                       performed — request and response flow through verbatim.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
+
+
+class Capabilities(BaseModel):
+    """Capability flags per provider (plan.md §2.5)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    chat: bool = True
+    streaming: bool = True
+    tools: bool = False
+    vision: bool = False
+    prompt_cache: bool = False
+    # v0.5-A: Anthropic's extended-thinking body field (`thinking: {type:
+    # enabled, budget_tokens: N}` or `{type: enabled}` adaptive). Narrow,
+    # per-model flag — when unset, the capability gate falls back to a
+    # model-name heuristic (see coderouter/routing/capability.py). Distinct
+    # from `reasoning_control` below, which is the v1.0+ abstract interface.
+    thinking: bool = False
+    # v0.5-C: opt out of the openai_compat adapter's passive `reasoning`
+    # field strip. By default (False), the adapter removes non-standard
+    # `message.reasoning` / `delta.reasoning` fields emitted by some
+    # OpenRouter free-tier models (gpt-oss-120b:free confirmed 2026-04)
+    # because strict OpenAI clients reject the unknown key. Set True when
+    # you explicitly want the raw reasoning text to flow to the client
+    # (e.g. CodeRouter is fronting a reasoning-aware downstream).
+    reasoning_passthrough: bool = False
+    # v1.0+ fields, declared early so providers.yaml can future-proof
+    reasoning_control: Literal["none", "openai", "anthropic", "provider_specific"] = "none"
+    mcp: Literal["none", "anthropic", "provider_specific"] = "none"
+    openai_compatible: bool = True
+
+
+class ProviderConfig(BaseModel):
+    """A single provider entry from providers.yaml.
+
+    Examples:
+        - Local llama.cpp server: kind=openai_compat, base_url=http://localhost:8080/v1
+        - OpenRouter free: kind=openai_compat, base_url=https://openrouter.ai/api/v1
+        - (future) Anthropic: kind=anthropic, base_url=https://api.anthropic.com
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., description="Unique identifier used in profiles.yaml")
+    kind: Literal["openai_compat", "anthropic"] = Field(
+        default="openai_compat",
+        description=(
+            "Adapter type. 'openai_compat' covers llama.cpp / Ollama / "
+            "OpenRouter / LM Studio / Together / Groq. 'anthropic' is the "
+            "native Anthropic Messages API passthrough (v0.3.x)."
+        ),
+    )
+    base_url: HttpUrl
+    model: str = Field(..., description="Upstream model id sent in the request body")
+    api_key_env: str | None = Field(
+        default=None,
+        description="Env var name holding the API key. None = no auth (e.g. local).",
+    )
+
+    # Routing-relevant flags
+    paid: bool = Field(
+        default=False,
+        description="If true, only used when ALLOW_PAID=true (plan.md §2.3).",
+    )
+    timeout_s: float = Field(default=30.0, ge=1.0, le=600.0)
+
+    # Provider-specific extras merged into the outbound request body.
+    # Use for non-standard fields like Ollama's `think: false`, `keep_alive`,
+    # `options.num_ctx`, or any vendor-specific toggle. User-supplied request
+    # fields take precedence over these defaults.
+    extra_body: dict[str, object] = Field(default_factory=dict)
+
+    # Directive appended to the system message content before sending.
+    # Use for model-intrinsic switches that travel reliably through any API
+    # layer — e.g. Qwen3's "/no_think" to skip the reasoning track, since
+    # Ollama's OpenAI-compat endpoint silently drops the native `think` flag.
+    append_system_prompt: str | None = Field(
+        default=None,
+        description="Appended to existing system message (or added as a new one).",
+    )
+
+    # v1.0-A: declarative output cleaning chain. Names map to filter
+    # implementations in ``coderouter/output_filters.py`` — currently
+    # ``strip_thinking`` (``<think>...</think>`` blocks) and
+    # ``strip_stop_markers`` (``<|python_tag|>`` / ``<|eot_id|>`` /
+    # ``<|im_end|>`` / ``<|turn|>`` / ``<|end|>`` / ``<|channel>thought``).
+    # Empty = no scrubbing (backward compatible with v0.7.x). Applied at
+    # the adapter boundary on both streaming and non-streaming paths;
+    # stateful across SSE chunk boundaries. Unknown names fail at load.
+    output_filters: list[str] = Field(
+        default_factory=list,
+        description=(
+            "v1.0-A: ordered filter chain applied to assistant content. "
+            "Known: strip_thinking, strip_stop_markers. Empty = off."
+        ),
+    )
+
+    capabilities: Capabilities = Field(default_factory=Capabilities)
+
+    @model_validator(mode="after")
+    def _check_output_filters_known(self) -> ProviderConfig:
+        """v1.0-A: fail at config-load on a typo'd filter name.
+
+        Same fast-fail pattern as ``_check_default_profile_exists`` —
+        surfaces ``output_filters: [strp_thinking]`` at startup rather
+        than silently no-op'ing forever.
+        """
+        # Import locally to avoid a hard package-level cycle
+        # (output_filters imports nothing from config).
+        from coderouter.output_filters import validate_output_filters
+
+        validate_output_filters(self.output_filters)
+        return self
+
+
+class FallbackChain(BaseModel):
+    """An ordered list of provider names to try in sequence.
+
+    v0.6-B: optional profile-level overrides for ``timeout_s`` and
+    ``append_system_prompt``. When set, these REPLACE the provider's own
+    values for calls routed through this profile — "replace" rather than
+    "append" semantics keeps debugging predictable and matches how
+    ``timeout_s`` (a scalar limit) naturally behaves. Unset fields leave
+    the provider's own defaults in effect. The ``retry_max`` field is
+    deferred to a later minor until a retry mechanism exists at the
+    adapter layer (§9.3 #4 partial).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., description="Profile name, e.g. 'default', 'coding'")
+    providers: list[str] = Field(
+        ...,
+        min_length=1,
+        description="Provider names in fallback order. First success wins.",
+    )
+    timeout_s: float | None = Field(
+        default=None,
+        ge=1.0,
+        le=600.0,
+        description=(
+            "v0.6-B: profile-level HTTP timeout override (seconds). When "
+            "set, replaces ``ProviderConfig.timeout_s`` for every call "
+            "routed through this profile. Unset = provider default."
+        ),
+    )
+    append_system_prompt: str | None = Field(
+        default=None,
+        description=(
+            "v0.6-B: profile-level override for the provider's "
+            "``append_system_prompt`` directive. When set, REPLACES the "
+            "provider's directive for this profile (not appended). Pass "
+            "an empty string to explicitly clear the provider directive "
+            "for this profile."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# v1.6-A: auto_router — declarative request-body classifier
+# ---------------------------------------------------------------------------
+
+
+class RuleMatcher(BaseModel):
+    """One-of matcher for an :class:`AutoRouteRule`.
+
+    Exactly one of the matcher fields must be set; the ``_exactly_one``
+    validator enforces this at load. Adding a new matcher type means
+    adding a new optional field — the single-field invariant enforces
+    discriminated-union semantics without pydantic's tagged-union syntax.
+
+    Variants (v1.6-A):
+
+    - ``has_image: True`` — any ``image_url`` / ``image`` /
+      ``input_image`` content block in the latest user message.
+    - ``code_fence_ratio_min: 0.3`` — triple-backtick span chars ÷ total
+      chars of latest user message is ``>=`` this threshold.
+    - ``content_contains: "foo"`` — substring match (case-sensitive).
+    - ``content_regex: r"..."`` — Python ``re.search``; compiled at
+      model-construction time so typos fail startup.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    has_image: bool | None = None
+    code_fence_ratio_min: float | None = Field(default=None, ge=0.0, le=1.0)
+    content_contains: str | None = None
+    content_regex: str | None = None
+
+    _MATCHER_FIELDS: tuple[str, ...] = (
+        "has_image",
+        "code_fence_ratio_min",
+        "content_contains",
+        "content_regex",
+    )
+
+    @model_validator(mode="after")
+    def _exactly_one(self) -> Self:
+        set_fields = [
+            name for name in self._MATCHER_FIELDS if getattr(self, name) is not None
+        ]
+        if len(set_fields) != 1:
+            raise ValueError(
+                f"RuleMatcher must have exactly one matcher field set, "
+                f"got {len(set_fields)}: {set_fields}"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _compile_regex_eagerly(self) -> Self:
+        """Compile ``content_regex`` at load so bad patterns fail startup."""
+        if self.content_regex is not None:
+            try:
+                re.compile(self.content_regex)
+            except re.error as exc:
+                raise ValueError(
+                    f"Invalid regex for content_regex {self.content_regex!r}: {exc}"
+                ) from exc
+        return self
+
+
+class AutoRouteRule(BaseModel):
+    """One rule in ``auto_router.rules``: matcher → profile."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(
+        description=(
+            "Stable identifier surfaced in the auto-router-resolved log "
+            "payload. Recommended prefixes: ``builtin:`` for bundled "
+            "rules, ``user:`` for YAML-defined rules."
+        ),
+    )
+    profile: str = Field(
+        description="Profile name to resolve to. Must exist in profiles[].",
+    )
+    match: RuleMatcher
+
+
+class AutoRouterConfig(BaseModel):
+    """The ``auto_router:`` block in providers.yaml.
+
+    When absent and ``default_profile == "auto"``, the bundled ruleset
+    (``BUNDLED_RULES`` in :mod:`coderouter.routing.auto_router`) applies.
+    When present, ``rules`` entirely **replaces** bundled rules (no
+    merge) — see ``docs/designs/v1.6-auto-router.md`` §7 for rationale.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    disabled: bool = Field(
+        default=False,
+        description=(
+            "Hard off-switch. When True, classification is skipped and "
+            "``default_rule_profile`` is used unconditionally."
+        ),
+    )
+    rules: list[AutoRouteRule] = Field(
+        default_factory=list,
+        description="Ordered rules; first match wins.",
+    )
+    default_rule_profile: str = Field(
+        default="writing",
+        description=(
+            "Profile used when no rule matches (or when ``disabled`` is "
+            "True). Must exist in profiles[]."
+        ),
+    )
+
+
+class CodeRouterConfig(BaseModel):
+    """Top-level config loaded from providers.yaml."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    allow_paid: bool = Field(
+        default=False,
+        description="Master switch. ALLOW_PAID=false blocks all paid providers (plan.md §2.3).",
+    )
+    default_profile: str = Field(default="default")
+    providers: list[ProviderConfig] = Field(..., min_length=1)
+    profiles: list[FallbackChain] = Field(..., min_length=1)
+    mode_aliases: dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            "v0.6-D: intent-to-profile mapping. Clients send "
+            "``X-CodeRouter-Mode: coding`` and the ingress resolves it to "
+            "the aliased profile name. Lets clients name their intent "
+            "(``coding`` / ``long`` / ``fast``) independently of the "
+            "underlying profile names — you can rewire the chain without "
+            "touching client code. Keys = mode names, values = profile "
+            "names (must exist in ``profiles``). Empty dict = feature off."
+        ),
+    )
+    # v1.5-E: display-time timezone for dashboard + ``coderouter stats``.
+    # The metrics ring keeps timestamps in UTC ISO form (stable wire format,
+    # matches JsonLineFormatter); this field only affects rendering. When
+    # unset, consumers default to UTC (no behavior change from v1.5-D). An
+    # IANA name is required — offset strings like ``+09:00`` are rejected to
+    # keep DST semantics unambiguous. Validated via ``zoneinfo.ZoneInfo`` at
+    # load time so a typo like ``Asia/Tokyoo`` fails fast rather than 500'ing
+    # the first dashboard poll.
+    display_timezone: str | None = Field(
+        default=None,
+        description=(
+            "v1.5-E: IANA timezone name used for rendering timestamps in "
+            "``/dashboard`` and ``coderouter stats``. Example: ``Asia/Tokyo`` "
+            "or ``America/New_York``. None → UTC. The underlying "
+            "``/metrics.json`` snapshot keeps UTC ISO timestamps; conversion "
+            "is display-only."
+        ),
+    )
+    # v1.6-A: optional auto-routing rules. When ``default_profile == "auto"``
+    # and this field is None, the bundled ruleset (image → multi /
+    # code-fence → coding / fallthrough → writing) applies. When set,
+    # ``rules`` is a complete replacement (no merge with bundled).
+    auto_router: AutoRouterConfig | None = Field(
+        default=None,
+        description=(
+            "v1.6-A: classifier rules consulted only when "
+            "``default_profile == 'auto'``. None + auto → bundled rules "
+            "apply (requires multi/coding/writing profiles to exist). "
+            "Set to override bundled behavior."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _check_default_profile_exists(self) -> CodeRouterConfig:
+        """v0.6-A: surface a typo'd ``default_profile`` at load time.
+
+        Previously a bad ``default_profile`` only blew up on the first
+        request (``profile_by_name`` → KeyError → 500). Checking here
+        converts a silent-until-used misconfig into a fast-fail at
+        startup, which matches how ``--mode`` / ``CODEROUTER_MODE`` are
+        validated in ``loader.py``.
+
+        v1.6-A: ``default_profile == "auto"`` is a reserved sentinel
+        that triggers the auto-router; it never maps to a declared
+        profile directly and is therefore exempt from this existence
+        check.
+        """
+        if self.default_profile == "auto":
+            return self
+        names = {p.name for p in self.profiles}
+        if self.default_profile not in names:
+            raise ValueError(
+                f"default_profile {self.default_profile!r} is not declared in "
+                f"profiles: known={sorted(names)}"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_auto_is_reserved(self) -> CodeRouterConfig:
+        """v1.6-A: ``auto`` is a reserved sentinel for the auto-router.
+
+        Users cannot define a profile named ``auto`` — it would collide
+        with the ``default_profile: auto`` trigger. Fast-fail at load
+        with a pointer to rename.
+        """
+        for prof in self.profiles:
+            if prof.name == "auto":
+                raise ValueError(
+                    "'auto' is reserved as a profile name in v1.6+ "
+                    "(it is the sentinel that activates auto_router). "
+                    "Rename this profile to something else, e.g. "
+                    "'auto-route' or 'smart'."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _check_auto_router_profiles_exist(self) -> CodeRouterConfig:
+        """v1.6-A: every ``auto_router.rules[*].profile`` must be declared.
+
+        Also validates ``default_rule_profile``. Same fast-fail
+        philosophy as :meth:`_check_default_profile_exists` and
+        :meth:`_check_mode_alias_targets_exist`.
+        """
+        if self.auto_router is None:
+            return self
+        names = {p.name for p in self.profiles}
+        bad = sorted(
+            {
+                r.profile
+                for r in self.auto_router.rules
+                if r.profile not in names
+            }
+        )
+        if bad:
+            raise ValueError(
+                f"auto_router.rules points to unknown profile(s): {bad}. "
+                f"known profiles={sorted(names)}"
+            )
+        if self.auto_router.default_rule_profile not in names:
+            raise ValueError(
+                f"auto_router.default_rule_profile "
+                f"{self.auto_router.default_rule_profile!r} is not declared "
+                f"in profiles: known={sorted(names)}"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_bundled_auto_router_requirements(self) -> CodeRouterConfig:
+        """v1.6-A: bundled ruleset needs multi/coding/writing to exist.
+
+        Only fires when the user opted into auto routing
+        (``default_profile == 'auto'``) without supplying a custom
+        ``auto_router`` block. In that path the classifier falls back to
+        the bundled rules (see
+        :mod:`coderouter.routing.auto_router`), which reference three
+        named profiles. Missing any of them would 500 on the first
+        request, so we surface it at load instead.
+        """
+        if self.default_profile != "auto" or self.auto_router is not None:
+            return self
+        names = {p.name for p in self.profiles}
+        required = ("multi", "coding", "writing")
+        missing = [r for r in required if r not in names]
+        if missing:
+            raise ValueError(
+                f"bundled auto_router requires profiles {list(required)} to "
+                f"exist, but missing: {missing}. "
+                f"Either (a) define all three profiles in providers.yaml, or "
+                f"(b) override with a custom ``auto_router:`` block, or "
+                f"(c) set ``default_profile`` to a non-auto profile name."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_display_timezone_resolves(self) -> CodeRouterConfig:
+        """v1.5-E: fail fast on a typo'd IANA zone name.
+
+        Same philosophy as the other ``_check_*`` validators — a broken
+        ``display_timezone`` would otherwise silently fall back to UTC
+        (or worse, blow up the first dashboard poll with a stack trace).
+        Checking at load time converts that into a startup error with the
+        offending value in the message.
+        """
+        if self.display_timezone is None:
+            return self
+        # Imported locally to sidestep the slow ``zoneinfo`` cold-import
+        # cost on machines that never set a display timezone.
+        from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+        try:
+            ZoneInfo(self.display_timezone)
+        except ZoneInfoNotFoundError as exc:
+            raise ValueError(
+                f"display_timezone={self.display_timezone!r} is not a known "
+                f"IANA zone (try 'Asia/Tokyo', 'America/New_York', 'UTC'): {exc}"
+            ) from exc
+        return self
+
+    @model_validator(mode="after")
+    def _check_mode_alias_targets_exist(self) -> CodeRouterConfig:
+        """v0.6-D: every ``mode_aliases`` value must point to a declared profile.
+
+        Same fast-fail philosophy as ``_check_default_profile_exists``: a
+        broken alias should 500 at load, not silently 400 for every
+        request that uses that mode.
+        """
+        names = {p.name for p in self.profiles}
+        bad = {mode: profile for mode, profile in self.mode_aliases.items() if profile not in names}
+        if bad:
+            raise ValueError(
+                f"mode_aliases points to unknown profile(s): {bad}. known profiles={sorted(names)}"
+            )
+        return self
+
+    def provider_by_name(self, name: str) -> ProviderConfig:
+        """Look up a provider config by name. Raises KeyError if not found."""
+        for p in self.providers:
+            if p.name == name:
+                return p
+        raise KeyError(f"Provider not found: {name!r}")
+
+    def profile_by_name(self, name: str) -> FallbackChain:
+        """Look up a profile (fallback chain) by name."""
+        for prof in self.profiles:
+            if prof.name == name:
+                return prof
+        raise KeyError(f"Profile not found: {name!r}")
+
+    def resolve_mode(self, mode: str) -> str:
+        """v0.6-D: resolve a mode alias to a profile name.
+
+        The startup validator guarantees every alias target exists in
+        ``profiles``, so callers can pass the returned value straight to
+        ``profile_by_name`` without a second existence check.
+
+        Raises ``KeyError`` when ``mode`` is not in ``mode_aliases`` —
+        the ingress layer catches it and returns 400 with the list of
+        available modes.
+        """
+        if mode in self.mode_aliases:
+            return self.mode_aliases[mode]
+        raise KeyError(f"Unknown mode alias: {mode!r}")

coderouter/data/__init__.py

@@ -0,0 +1,7 @@
+"""Package-data resources for CodeRouter.
+
+Currently holds the bundled ``model-capabilities.yaml`` registry (v0.7-A).
+Kept as a real package (with ``__init__.py``) rather than a plain data
+directory so that ``importlib.resources.files('coderouter.data')`` works
+cleanly under every install mode (wheel / editable / zipapp).
+"""

coderouter/data/model-capabilities.yaml

@@ -0,0 +1,86 @@
+# ============================================================
+# CodeRouter — bundled model-capabilities.yaml
+#
+# Declarative capability registry — glob + first-match defaults per
+# (kind, model) pair.
+#
+# Loaded by ``coderouter.config.capability_registry.CapabilityRegistry``
+# at startup. Users can extend / override via
+# ``~/.coderouter/model-capabilities.yaml`` (optional; merged on top of
+# this file — user rules are evaluated first, so a user rule overrides
+# a bundled rule for the same flag).
+#
+# Precedence for the capability gate (see coderouter/routing/capability.py):
+#   1. providers.yaml ``capabilities.*`` per-provider explicit flag
+#      (highest priority — verbatim opt-in).
+#   2. ``~/.coderouter/model-capabilities.yaml`` (user rules).
+#   3. This file (bundled rules).
+#   4. Unset ⇒ flag defaults to False (not-supported).
+#
+# Schema
+# ------
+# version: int        — format version (currently 1)
+# rules: list
+#   - match: str      — fnmatch-style glob applied against ProviderConfig.model
+#                       (case-sensitive). Supported wildcards: *, ?, [seq].
+#     kind: str       — optional; restricts rule to this adapter kind.
+#                       One of "anthropic", "openai_compat", "any".
+#                       Default: "any".
+#     capabilities:   — dict of flag overrides (all fields optional).
+#       thinking: bool                — Anthropic `thinking: {type: enabled}` body field
+#       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
+#
+# First-match semantics: rules within a file are evaluated top-to-bottom
+# per flag; the first rule whose glob matches AND declares that flag
+# determines the value. Rules that don't declare a flag are skipped for
+# that flag's lookup (so a specific rule can override `thinking` while
+# leaving `tools` to fall through to a broader later rule).
+#
+# When to edit this file vs. the user file:
+#   - Bundled (this file): shared defaults that ship with CodeRouter.
+#     Update when a new model family verifiably accepts a capability.
+#   - User file (~/.coderouter/model-capabilities.yaml): per-deployment
+#     overrides, e.g. "my local Ollama qwen3-coder:7b is reliable with
+#     tool calling, declare tools: true for it".
+# ============================================================
+
+version: 1
+
+rules:
+  # ------------------------------------------------------------------
+  # Anthropic families — `thinking: {type: enabled}` support.
+  #
+  # Verified 2026-04 against api.anthropic.com (v0.5-A):
+  #   claude-sonnet-4-5-*   → 400 "adaptive thinking is not supported"
+  #   claude-sonnet-4-6+    → accepts adaptive + budgeted thinking
+  #   claude-opus-4-*       → accepts (all 4.x opus)
+  #   claude-haiku-4-*      → accepts (all 4.x haiku)
+  #
+  # Forward-compat entry for 4-7 is included so a named-later model ships
+  # without requiring a CodeRouter update. When Anthropic releases 4-8
+  # or 5-0, add the glob here. The per-provider YAML escape hatch
+  # (``providers.yaml`` ``capabilities.thinking: true``) remains the
+  # interim path while a new family is un-listed.
+  # ------------------------------------------------------------------
+
+  - match: "claude-opus-4-*"
+    kind: anthropic
+    capabilities:
+      thinking: true
+
+  - match: "claude-sonnet-4-6*"
+    kind: anthropic
+    capabilities:
+      thinking: true
+
+  - match: "claude-sonnet-4-7*"
+    kind: anthropic
+    capabilities:
+      thinking: true
+
+  - match: "claude-haiku-4-*"
+    kind: anthropic
+    capabilities:
+      thinking: true