coderouter-cli 1.7.0__py3-none-any.whl

coderouter/config/__init__.py

@@ -0,0 +1,10 @@
+"""Configuration loading and schemas."""
+
+from coderouter.config.loader import load_config
+from coderouter.config.schemas import (
+    Capabilities,
+    CodeRouterConfig,
+    ProviderConfig,
+)
+
+__all__ = ["Capabilities", "CodeRouterConfig", "ProviderConfig", "load_config"]

coderouter/config/capability_registry.py

@@ -0,0 +1,339 @@
+"""Declarative model-capabilities.yaml registry (v0.7-A).
+
+Motivation
+    v0.5-A hardcoded the "which Anthropic models accept the `thinking`
+    body field" heuristic as a regex literal inside
+    ``coderouter.routing.capability``. Adding a new family (or a new
+    capability flag) meant a code change. v0.7-A externalizes that
+    heuristic into a YAML registry so the common maintenance action —
+    "Anthropic shipped 4-8, which accepts thinking" — becomes a one-line
+    YAML edit instead of a Python patch.
+
+    The registry answers "given (kind, model), what capability flags are
+    declared?" and is consulted by the v0.5 capability gate functions
+    (``provider_supports_thinking`` et al.) after the per-provider
+    explicit flag on ``providers.yaml`` has been checked. Precedence:
+
+        providers.yaml capabilities.*      ─── highest (explicit opt-in)
+        user file ~/.coderouter/mcy        ─── per-deployment overrides
+        bundled  coderouter/data/mcy       ─── shipped defaults
+        unset                               ─── flag defaults to False
+
+Design notes
+    - Pure functions + a small Pydantic schema. No I/O outside the
+      loader entry points. The registry instance is loaded once at
+      startup (via ``CapabilityRegistry.load_default``) and reused.
+    - fnmatch globs, not regex. Globs cover the real-world pattern
+      ("all claude-opus-4-x", "qwen3-coder:*") without making the YAML
+      author learn escape rules.
+    - First-match-per-flag semantics: rules are walked top-to-bottom
+      per flag, first rule whose glob matches AND declares that flag
+      determines the value. A rule may declare only a subset of flags;
+      undeclared flags keep looking further down the list. This means a
+      specific early rule can override one capability while letting a
+      broader later rule handle the rest.
+    - ``kind`` filter is optional (``"any"`` default). When set, only
+      providers of that adapter kind are candidates. This replaces the
+      old hardcoded ``if kind != "anthropic": return False`` guard —
+      the bundled YAML simply does not declare any openai_compat rules
+      for thinking, so openai_compat providers get ``thinking=None``
+      from the registry, which the gate function treats as False.
+    - No mutation. Registry instances are immutable; ``load_default``
+      re-reads disk each call (cheap), but the capability module caches
+      a single instance.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+# ---------------------------------------------------------------------------
+# YAML schema
+# ---------------------------------------------------------------------------
+
+
+class RegistryCapabilities(BaseModel):
+    """Per-rule capability flag declarations (all optional).
+
+    ``None`` means "this rule does not have an opinion about this flag".
+    Rules that omit a flag let the lookup fall through to later rules
+    (or to the Python fallback of False / None) for that specific flag.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    thinking: bool | None = Field(
+        default=None,
+        description=(
+            "Anthropic `thinking: {type: enabled}` body field support. "
+            "When True, the capability gate treats this (kind, model) as "
+            "able to receive the block without translation loss."
+        ),
+    )
+    reasoning_passthrough: bool | None = Field(
+        default=None,
+        description=(
+            "Opt-OUT of the openai_compat adapter's passive strip of the "
+            "non-standard `message.reasoning` field. True = let the raw "
+            "reasoning text flow to the client. Default (None/False) = "
+            "strip it (v0.5-C behavior)."
+        ),
+    )
+    tools: bool | None = Field(
+        default=None,
+        description=(
+            "Model reliably emits structured tool_calls. Declared here "
+            'as a glob default (e.g. "qwen3-coder:*" tools=true); the '
+            "actual adapter-level handling sits in v0.3-A tool repair."
+        ),
+    )
+    max_context_tokens: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Declared context window for this model. Used by v0.7-B "
+            "doctor --check-model num_ctx probe (not consumed in v0.7-A)."
+        ),
+    )
+
+
+class CapabilityRule(BaseModel):
+    """One entry in the registry YAML ``rules:`` list."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    match: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "fnmatch-style glob applied case-sensitively against "
+            "ProviderConfig.model. Supported wildcards: *, ?, [seq]."
+        ),
+    )
+    kind: Literal["anthropic", "openai_compat", "any"] = Field(
+        default="any",
+        description=(
+            "Restrict rule to providers of this adapter kind. 'any' "
+            "means the rule matches regardless of kind."
+        ),
+    )
+    capabilities: RegistryCapabilities = Field(default_factory=RegistryCapabilities)
+
+    def kind_matches(self, provider_kind: str) -> bool:
+        """True if this rule's kind filter admits ``provider_kind``."""
+        return self.kind == "any" or self.kind == provider_kind
+
+    def glob_matches(self, model: str) -> bool:
+        """True if this rule's glob matches ``model`` (case-sensitive)."""
+        return fnmatch.fnmatchcase(model, self.match)
+
+
+class CapabilityRegistryFile(BaseModel):
+    """Top-level shape of a model-capabilities.yaml file."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    version: Literal[1] = Field(
+        default=1,
+        description="Registry format version — bump on breaking schema changes.",
+    )
+    rules: list[CapabilityRule] = Field(
+        default_factory=list,
+        description="First-match-per-flag rule list.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Lookup result
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ResolvedCapabilities:
+    """Result of a registry lookup — merged per-flag from the rule chain.
+
+    Each field is ``None`` when no matching rule declared that flag; the
+    gate function coerces ``None`` to the conservative "not supported"
+    answer (False), matching the pre-v0.7-A regex fallback.
+    """
+
+    thinking: bool | None = None
+    reasoning_passthrough: bool | None = None
+    tools: bool | None = None
+    max_context_tokens: int | None = None
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+
+_BUNDLED_PACKAGE = "coderouter.data"
+_BUNDLED_NAME = "model-capabilities.yaml"
+_USER_PATH = Path.home() / ".coderouter" / "model-capabilities.yaml"
+
+
+class CapabilityRegistry:
+    """Layered, glob-based capability registry.
+
+    The rule list is ordered with user rules first (higher priority),
+    bundled rules second. Lookup walks the combined list top-to-bottom;
+    for each declared flag, the first rule whose ``(kind, match)`` fits
+    the query wins. A rule that does not declare a given flag is
+    transparent for that flag — the walk continues past it.
+
+    Thread-safety: the instance is read-only after construction, so
+    concurrent ``lookup`` calls are safe. Loading is not thread-safe but
+    is expected to happen once at process startup.
+    """
+
+    def __init__(self, rules: list[CapabilityRule]) -> None:
+        self._rules: list[CapabilityRule] = list(rules)
+
+    @property
+    def rules(self) -> list[CapabilityRule]:
+        """Return a copy of the rule list in evaluation order."""
+        return list(self._rules)
+
+    def lookup(self, *, kind: str, model: str) -> ResolvedCapabilities:
+        """Resolve capability flags for ``(kind, model)``.
+
+        Per-flag first-match: for each of the four flags, returns the
+        value from the first rule whose ``kind`` filter admits the
+        query AND whose glob matches ``model`` AND which explicitly
+        declares that flag.
+
+        ``model`` may be the empty string; globs that match "" still
+        apply (but no bundled rule does today). Callers pass
+        ``provider.model or ""`` directly.
+        """
+        resolved_thinking: bool | None = None
+        resolved_reasoning: bool | None = None
+        resolved_tools: bool | None = None
+        resolved_max_ctx: int | None = None
+
+        thinking_locked = False
+        reasoning_locked = False
+        tools_locked = False
+        max_ctx_locked = False
+
+        for rule in self._rules:
+            if not rule.kind_matches(kind):
+                continue
+            if not rule.glob_matches(model):
+                continue
+            caps = rule.capabilities
+            if not thinking_locked and caps.thinking is not None:
+                resolved_thinking = caps.thinking
+                thinking_locked = True
+            if not reasoning_locked and caps.reasoning_passthrough is not None:
+                resolved_reasoning = caps.reasoning_passthrough
+                reasoning_locked = True
+            if not tools_locked and caps.tools is not None:
+                resolved_tools = caps.tools
+                tools_locked = True
+            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:
+                break
+
+        return ResolvedCapabilities(
+            thinking=resolved_thinking,
+            reasoning_passthrough=resolved_reasoning,
+            tools=resolved_tools,
+            max_context_tokens=resolved_max_ctx,
+        )
+
+    # ------------------------------------------------------------------
+    # Loaders
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_rule_lists(
+        cls,
+        *,
+        user: list[CapabilityRule] | None = None,
+        bundled: list[CapabilityRule] | None = None,
+    ) -> CapabilityRegistry:
+        """Build a registry from pre-loaded rule lists.
+
+        Primarily useful for tests that want to inject rule data without
+        touching disk. The order in the returned registry is
+        ``user + bundled`` — user rules are evaluated first.
+        """
+        return cls((user or []) + (bundled or []))
+
+    @classmethod
+    def load_default(cls) -> CapabilityRegistry:
+        """Load the bundled YAML + optional user override.
+
+        User file is resolved at ``~/.coderouter/model-capabilities.yaml``;
+        missing = empty user layer. Bundled file is required — if it
+        cannot be read, this raises ``RuntimeError`` (the package is
+        broken). Both files are validated against
+        ``CapabilityRegistryFile``; schema errors propagate as
+        Pydantic ``ValidationError`` so the failure is visible at load.
+        """
+        bundled = cls._read_bundled_file()
+        user = cls._read_user_file()
+        return cls.from_rule_lists(user=user, bundled=bundled)
+
+    @staticmethod
+    def _read_bundled_file() -> list[CapabilityRule]:
+        try:
+            text = (
+                resources.files(_BUNDLED_PACKAGE)
+                .joinpath(_BUNDLED_NAME)
+                .read_text(encoding="utf-8")
+            )
+        except (FileNotFoundError, ModuleNotFoundError) as exc:
+            raise RuntimeError(
+                "Bundled model-capabilities.yaml is missing from the "
+                f"'{_BUNDLED_PACKAGE}' package — installation is "
+                "incomplete or corrupted."
+            ) from exc
+        raw = yaml.safe_load(text) or {}
+        return CapabilityRegistryFile.model_validate(raw).rules
+
+    @staticmethod
+    def _read_user_file(path: Path | None = None) -> list[CapabilityRule]:
+        target = path or _USER_PATH
+        if not target.is_file():
+            return []
+        raw = yaml.safe_load(target.read_text(encoding="utf-8")) or {}
+        return CapabilityRegistryFile.model_validate(raw).rules
+
+    @classmethod
+    def load_from_paths(
+        cls,
+        *,
+        bundled_path: Path,
+        user_path: Path | None = None,
+    ) -> CapabilityRegistry:
+        """Test-friendly loader that reads YAML from explicit paths.
+
+        Production code uses :meth:`load_default`; this variant lets
+        tests stage a custom bundled file alongside an optional user
+        file without relying on the package data location.
+        """
+        bundled_raw = yaml.safe_load(bundled_path.read_text(encoding="utf-8")) or {}
+        bundled = CapabilityRegistryFile.model_validate(bundled_raw).rules
+        user = cls._read_user_file(user_path)
+        return cls.from_rule_lists(user=user, bundled=bundled)
+
+
+__all__ = [
+    "CapabilityRegistry",
+    "CapabilityRegistryFile",
+    "CapabilityRule",
+    "RegistryCapabilities",
+    "ResolvedCapabilities",
+]

coderouter/config/env_file.py

@@ -0,0 +1,295 @@
+"""`.env` file loader (v1.6.3).
+
+Purpose
+-------
+Provide a standard-library-only parser for `.env`-style files so that
+``coderouter serve --env-file PATH`` can act as a thin gateway between
+CodeRouter and any tool that emits a `.env` (1Password CLI, sops,
+direnv, plain hand-edited files, etc.).
+
+We deliberately do NOT pull in ``python-dotenv``: the runtime-deps
+freeze policy (5 packages, see plan.md §5.4) is part of the project's
+audit story. The parser below covers the cases that 1Password / sops /
+manual editing actually emit; the spec is intentionally narrower than
+``python-dotenv`` (no variable expansion, no command substitution, no
+multi-line values).
+
+File format
+-----------
+Each non-empty, non-comment line must match::
+
+    [export ]KEY=value
+
+Where:
+
+* ``KEY`` is ``[A-Za-z_][A-Za-z0-9_]*`` (POSIX identifier).
+* ``value`` is one of:
+    - bare:        ``value`` (no whitespace, no quotes)
+    - double-quoted: ``"value with spaces"`` — backslash escapes
+      ``\\n`` ``\\t`` ``\\"`` ``\\\\`` are interpreted.
+    - single-quoted: ``'literal value'`` — no escape processing,
+      contents are taken verbatim.
+* Inline comments (` # comment`) are stripped from BARE values only.
+  Quoted values keep ``#`` verbatim.
+* Lines starting with ``#`` (after optional whitespace) are skipped.
+* Blank lines are skipped.
+* The ``export`` prefix is optional and discarded — supports `.env`
+  files that double as shell sources (``source .env``).
+
+Loading semantics
+-----------------
+:func:`load_env_file` returns a ``dict[str, str]`` and (by default)
+copies entries into ``os.environ`` ONLY for keys that are not already
+set. This is the v1.6.3 default — the file is treated as
+"defaults / setup" rather than authoritative override, so an operator
+who deliberately exports an override at the shell wins. Pass
+``override=True`` to flip the precedence (useful for tests).
+
+The parser raises :class:`EnvFileError` on malformed lines (not on
+unknown keys — those just become entries in the returned dict). The
+caller is expected to surface the error to the user; the CLI does so
+with a friendly stderr message and exit 1.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+__all__ = [
+    "EnvFileError",
+    "load_env_file",
+    "parse_env_file",
+]
+
+
+# POSIX identifier — matches sh / bash / zsh shell variable name rules.
+# This is intentionally strict: keys with hyphens or starting with a
+# digit are rejected so we surface the typo before exporting them
+# into a place that can't actually consume them.
+_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+# Recognized double-quote escape sequences. Anything else after a
+# backslash inside double quotes is left as `\<char>` (matches POSIX
+# "weak quote" behavior of the shell — surprising-free for users who
+# copy paste shell snippets).
+_DQ_ESCAPES = {
+    "n": "\n",
+    "t": "\t",
+    "r": "\r",
+    '"': '"',
+    "\\": "\\",
+    "$": "$",  # so ``"\$VAR"`` survives as ``$VAR`` literally
+    "`": "`",
+}
+
+
+class EnvFileError(ValueError):
+    """Raised when a `.env`-style file cannot be parsed.
+
+    The exception message contains the file path and 1-based line
+    number so the user can jump straight to the offending row. Caught
+    by the CLI to emit a friendly error and exit 1.
+    """
+
+
+def parse_env_file(path: str | os.PathLike[str]) -> dict[str, str]:
+    """Parse a `.env` file at ``path`` into a ``dict[str, str]``.
+
+    Does NOT mutate ``os.environ`` — that is :func:`load_env_file`'s
+    job. Pure parser, useful for tests and for callers that want to
+    diff against the current environment before applying.
+
+    Raises:
+        FileNotFoundError: ``path`` does not exist.
+        EnvFileError: malformed line (with file path + 1-based line
+            number in the message).
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"env file not found: {p}")
+
+    parsed: dict[str, str] = {}
+    text = p.read_text(encoding="utf-8")
+    for lineno, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.strip()
+        # Skip blank lines and pure comment lines.
+        if not line or line.startswith("#"):
+            continue
+
+        # Strip optional ``export `` prefix. After ``.strip()`` above,
+        # ``line == "export"`` (no trailing whitespace) is impossible to
+        # land in this branch — that case falls through to the
+        # missing-``=`` check below, which surfaces a sufficient error
+        # to the user. We only need to peel ``export`` when followed
+        # by content.
+        if line.startswith("export ") or line.startswith("export\t"):
+            line = line[len("export") :].lstrip()
+
+        # Split on the FIRST `=`. Subsequent `=` are part of the value.
+        if "=" not in line:
+            raise EnvFileError(f"{p}:{lineno}: missing `=` separator: {raw_line!r}")
+        key_raw, value_raw = line.split("=", 1)
+        key = key_raw.strip()
+
+        if not _KEY_RE.match(key):
+            raise EnvFileError(
+                f"{p}:{lineno}: invalid key {key!r} "
+                f"(must match {_KEY_RE.pattern})"
+            )
+
+        try:
+            value = _parse_value(value_raw)
+        except EnvFileError as exc:
+            # Re-attach file:lineno context.
+            raise EnvFileError(f"{p}:{lineno}: {exc}") from None
+
+        parsed[key] = value
+
+    return parsed
+
+
+def load_env_file(
+    path: str | os.PathLike[str],
+    *,
+    override: bool = False,
+    environ: dict[str, str] | None = None,
+) -> list[str]:
+    """Parse ``path`` and copy entries into ``environ`` (default: ``os.environ``).
+
+    Args:
+        path: Path to the `.env`-style file.
+        override: If ``False`` (default), only set keys that aren't
+            already in ``environ`` — file values are best-effort
+            defaults, the shell environment wins. If ``True``, file
+            values overwrite existing entries.
+        environ: Target mapping; defaults to ``os.environ``. Tests can
+            pass a plain ``dict`` to avoid mutating the real env.
+
+    Returns:
+        List of key names that were actually applied (i.e. either
+        newly set or overwritten). Useful for the CLI to log
+        "loaded N variables from <path>".
+
+    Raises:
+        FileNotFoundError, EnvFileError: see :func:`parse_env_file`.
+    """
+    target = environ if environ is not None else os.environ
+    applied: list[str] = []
+    for key, value in parse_env_file(path).items():
+        if not override and key in target:
+            continue
+        target[key] = value
+        applied.append(key)
+    return applied
+
+
+def load_env_files(
+    paths: Iterable[str | os.PathLike[str]],
+    *,
+    override: bool = False,
+    environ: dict[str, str] | None = None,
+) -> list[tuple[str, list[str]]]:
+    """Apply :func:`load_env_file` to multiple paths in order.
+
+    Useful for layering: ``[~/.coderouter/.env, ./.env]`` lets a user
+    keep cross-project defaults globally and override per-project at
+    the cwd. Files are processed left-to-right, so later files override
+    earlier ones (when ``override=True``) or fill in gaps (default).
+
+    Returns a list of ``(path, applied_keys)`` tuples in load order so
+    the caller can log a per-file summary.
+    """
+    out: list[tuple[str, list[str]]] = []
+    for p in paths:
+        out.append((str(p), load_env_file(p, override=override, environ=environ)))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_value(raw: str) -> str:
+    """Parse the right-hand side of `KEY=value`.
+
+    Strips leading whitespace (so ``KEY = value`` is tolerated, though
+    style-discouraged), detects quoting, applies the appropriate
+    escape rules.
+    """
+    s = raw.lstrip()
+
+    if not s:
+        return ""
+
+    if s[0] == '"':
+        # Double-quoted: process escapes, terminate at unescaped ".
+        return _parse_double_quoted(s)
+    if s[0] == "'":
+        # Single-quoted: literal until next single quote.
+        return _parse_single_quoted(s)
+
+    # Bare value: strip inline comment and trailing whitespace.
+    # We use a tiny state machine rather than a regex so we don't
+    # accidentally match `#` inside a hash-bang-looking value
+    # (e.g. ``KEY=#1`` — though questionable, this preserves it).
+    # The rule: a bare value's inline comment requires whitespace
+    # before `#`, so ``KEY=foo#bar`` keeps `foo#bar`.
+    out_chars: list[str] = []
+    prev_was_space = False
+    for ch in s:
+        if ch == "#" and prev_was_space:
+            break
+        out_chars.append(ch)
+        prev_was_space = ch in (" ", "\t")
+    return "".join(out_chars).rstrip()
+
+
+def _parse_double_quoted(s: str) -> str:
+    """Parse a string starting at the opening ``"``.
+
+    Recognized escapes: ``\\n``, ``\\t``, ``\\r``, ``\\"``, ``\\\\``,
+    ``\\$``, ``\\```. Unknown escapes pass through as-is (POSIX weak
+    quoting compatible).
+    """
+    assert s[0] == '"'
+    out: list[str] = []
+    i = 1
+    while i < len(s):
+        ch = s[i]
+        if ch == "\\" and i + 1 < len(s):
+            nxt = s[i + 1]
+            out.append(_DQ_ESCAPES.get(nxt, "\\" + nxt))
+            i += 2
+            continue
+        if ch == '"':
+            # End of quoted value. Anything after (other than whitespace
+            # and an inline comment) is a syntax error.
+            tail = s[i + 1 :].lstrip()
+            if tail and not tail.startswith("#"):
+                raise EnvFileError(
+                    f"unexpected content after closing quote: {tail!r}"
+                )
+            return "".join(out)
+        out.append(ch)
+        i += 1
+    raise EnvFileError("unterminated double-quoted value")
+
+
+def _parse_single_quoted(s: str) -> str:
+    """Parse a string starting at the opening ``'``.
+
+    Single quotes are literal — no escapes, the value is everything
+    up to the next ``'``.
+    """
+    assert s[0] == "'"
+    end = s.find("'", 1)
+    if end == -1:
+        raise EnvFileError("unterminated single-quoted value")
+    tail = s[end + 1 :].lstrip()
+    if tail and not tail.startswith("#"):
+        raise EnvFileError(f"unexpected content after closing quote: {tail!r}")
+    return s[1:end]