coderouter-cli 1.8.3__py3-none-any.whl → 1.9.0__py3-none-any.whl

coderouter/config/capability_registry.py

@@ -115,6 +115,24 @@ class RegistryCapabilities(BaseModel):
             "startup check)."
         ),
     )
+    cache_control: bool | None = Field(
+        default=None,
+        description=(
+            "v1.9-B: does the upstream preserve Anthropic ``cache_control`` "
+            "markers end-to-end on the wire? When True, the v0.5-B "
+            "translation-lossy gate stays quiet and the doctor cache probe "
+            "treats the upstream as eligible for hit-rate verification. "
+            "Independent from ``providers.yaml capabilities.prompt_cache`` "
+            "(provider-level explicit opt-in); the registry value carries "
+            "model-family defaults that match real-world wire support — "
+            "for Anthropic native (``claude-sonnet-*`` / ``claude-opus-*``) "
+            "and LM Studio's ``/v1/messages`` for ``qwen3.5-*`` / "
+            "``qwen3.6-*`` (verified live in v1.8.4, "
+            "``cache_read_input_tokens: 280`` observed). "
+            "``None`` (default) = no opinion → the v0.5-B gate falls back "
+            "to ``provider.kind == 'anthropic'`` for the answer."
+        ),
+    )
 
 
 class CapabilityRule(BaseModel):
@@ -182,6 +200,7 @@ class ResolvedCapabilities:
     tools: bool | None = None
     max_context_tokens: int | None = None
     claude_code_suitability: Literal["ok", "degraded"] | None = None
+    cache_control: bool | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -233,12 +252,14 @@ class CapabilityRegistry:
         resolved_tools: bool | None = None
         resolved_max_ctx: int | None = None
         resolved_suitability: Literal["ok", "degraded"] | None = None
+        resolved_cache_control: bool | None = None
 
         thinking_locked = False
         reasoning_locked = False
         tools_locked = False
         max_ctx_locked = False
         suitability_locked = False
+        cache_control_locked = False
 
         for rule in self._rules:
             if not rule.kind_matches(kind):
@@ -261,12 +282,16 @@ class CapabilityRegistry:
             if not suitability_locked and caps.claude_code_suitability is not None:
                 resolved_suitability = caps.claude_code_suitability
                 suitability_locked = True
+            if not cache_control_locked and caps.cache_control is not None:
+                resolved_cache_control = caps.cache_control
+                cache_control_locked = True
             if (
                 thinking_locked
                 and reasoning_locked
                 and tools_locked
                 and max_ctx_locked
                 and suitability_locked
+                and cache_control_locked
             ):
                 break
 
@@ -276,6 +301,7 @@ class CapabilityRegistry:
             tools=resolved_tools,
             max_context_tokens=resolved_max_ctx,
             claude_code_suitability=resolved_suitability,
+            cache_control=resolved_cache_control,
         )
 
     # ------------------------------------------------------------------

coderouter/config/schemas.py

@@ -49,6 +49,87 @@ class Capabilities(BaseModel):
     openai_compatible: bool = True
 
 
+class CostConfig(BaseModel):
+    """v1.9-D: per-provider unit pricing for cost aggregation.
+
+    All fields are optional. When :attr:`ProviderConfig.cost` is unset,
+    the provider contributes zero to the cost dashboard but still
+    appears in token-count totals — same shape as a free local model.
+
+    Pricing model
+    -------------
+
+    Anthropic's prompt-cache pricing (verified 2026-04 docs.anthropic.com):
+
+      * Normal input  : 1.0x ``input_tokens_per_million``
+      * Normal output : 1.0x ``output_tokens_per_million``
+      * Cache read    : ``cache_read_discount`` x normal input
+      * Cache creation: ``cache_creation_premium`` x normal input
+
+    The 4-class breakdown (cache_hit / cache_creation / no_cache /
+    unknown) recorded by v1.9-A's ``cache-observed`` log lets the
+    cost aggregator apply the right multiplier per token, and the
+    "savings" figure in the dashboard is computed as
+    ``cache_read_input_tokens x normal x (1 - cache_read_discount)``
+    — i.e. what the operator *would have* paid without prompt
+    caching.
+
+    LiteLLM's cost tracker (verified 2026-04) does not implement
+    cache-aware breakdown; it bills ``cache_read_input_tokens`` at
+    full input rate, overstating spend on cache-heavy workloads. The
+    CodeRouter dashboard's selling point is correctness here.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    input_tokens_per_million: float | None = Field(
+        default=None,
+        ge=0.0,
+        description=(
+            "USD per million input tokens at normal (uncached) rate. "
+            "Anthropic Sonnet 4.x is around 3.00, Opus 4.x around 15.00 "
+            "(check the upstream's pricing page — values change)."
+        ),
+    )
+    output_tokens_per_million: float | None = Field(
+        default=None,
+        ge=0.0,
+        description=(
+            "USD per million output tokens. Output is invariably the "
+            "expensive side of the meter — for coding workloads with "
+            "large completions this dominates the bill."
+        ),
+    )
+    cache_read_discount: float = Field(
+        default=0.10,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Multiplier applied to ``input_tokens_per_million`` for "
+            "tokens served from prompt cache. Anthropic's 2026-04 "
+            "pricing is 0.10 (i.e. cache reads are billed at 10% of "
+            "normal input rate). LM Studio /v1/messages locally "
+            "honors the cache_read field but local backends usually "
+            "have ``input_tokens_per_million`` of 0.0, so this field "
+            "is moot there."
+        ),
+    )
+    cache_creation_premium: float = Field(
+        default=1.25,
+        ge=0.0,
+        description=(
+            "Multiplier applied to ``input_tokens_per_million`` for "
+            "tokens *written* to the prompt cache on the first hit. "
+            "Anthropic's 2026-04 pricing is 1.25 (cache writes cost "
+            "25% more than normal input on the writeback call; "
+            "subsequent reads then cost ``cache_read_discount`` x, "
+            "amortizing the writeback). Above 1.0 means premium, "
+            "1.0 = no premium, below 1.0 = discount on creation "
+            "(unusual but theoretically supported by the schema)."
+        ),
+    )
+
+
 class ProviderConfig(BaseModel):
     """A single provider entry from providers.yaml.
 
@@ -116,6 +197,19 @@ class ProviderConfig(BaseModel):
 
     capabilities: Capabilities = Field(default_factory=Capabilities)
 
+    cost: CostConfig | None = Field(
+        default=None,
+        description=(
+            "v1.9-D: per-provider unit pricing for cost aggregation. "
+            "Unset = provider contributes zero to the cost dashboard "
+            "(typical for local models). Set on paid endpoints to "
+            "feed the ``/dashboard`` cost panel and the "
+            "``coderouter stats --cost`` TUI summary. Cache-aware "
+            "calculation differentiates cache_read (90% discount on "
+            "Anthropic) from normal input — see :class:`CostConfig`."
+        ),
+    )
+
     @model_validator(mode="after")
     def _check_output_filters_known(self) -> ProviderConfig:
         """v1.0-A: fail at config-load on a typo'd filter name.
@@ -173,6 +267,73 @@ class FallbackChain(BaseModel):
             "for this profile."
         ),
     )
+    # v1.9-E (L3): tool-loop detection guard.
+    #
+    # Long-running agent loops can fall into "tool stuck" states where
+    # the assistant repeatedly calls the same tool with identical args
+    # because it can't make progress. The guard inspects the assistant
+    # tool_use history in the inbound request and, when the same call
+    # repeats above the threshold, takes the configured action.
+    #
+    # Three actions trade off intervention against UX disruption:
+    #   * ``warn``   — emit a structured ``tool-loop-detected`` log only.
+    #                  Diagnostic; default for v1.9-E.
+    #   * ``inject`` — append a system message reminder ("you appear to
+    #                  be looping, try a different approach") so the
+    #                  next assistant turn has a chance to course-correct.
+    #   * ``break``  — short-circuit the request with an error response.
+    #                  Use when downstream cost / context exhaustion is
+    #                  worse than telling the agent to stop.
+    tool_loop_window: int = Field(
+        default=5,
+        ge=2,
+        le=50,
+        description=(
+            "v1.9-E (L3): how many of the most recent assistant tool_use "
+            "blocks to inspect for a loop. Default 5 covers the typical "
+            "Claude Code agent step depth without false-positiving on "
+            "legitimate same-tool repetition (e.g. iterating Read on "
+            "different files)."
+        ),
+    )
+    tool_loop_threshold: int = Field(
+        default=3,
+        ge=2,
+        le=50,
+        description=(
+            "v1.9-E (L3): how many *consecutive identical* tool calls "
+            "(same name + same args) trigger a loop verdict. Default 3 "
+            "catches the most common stuck patterns (Read same file 3x, "
+            "Bash same command 3x) while leaving headroom for "
+            "intentional repetition with intermediate observations."
+        ),
+    )
+    tool_loop_action: Literal["warn", "inject", "break"] = Field(
+        default="warn",
+        description=(
+            "v1.9-E (L3): action when a loop is detected. ``warn`` (default) "
+            "emits a log line only; ``inject`` adds a ``you-are-looping`` "
+            "system message reminder to the request; ``break`` returns an "
+            "error response. See FallbackChain comment for trade-offs."
+        ),
+    )
+    adaptive: bool = Field(
+        default=False,
+        description=(
+            "v1.9-C: enable health-based dynamic chain reordering for "
+            "this profile. When True, the engine consults its "
+            "AdaptiveAdjuster and may demote providers whose rolling-"
+            "window median latency or error rate exceeds the configured "
+            "thresholds (1.5x global median / 10% errors). Demotions are "
+            "debounced (30 s minimum between rank changes per provider) "
+            "so a transient blip cannot oscillate the chain. When False "
+            "(default), the static ``providers`` order is honored "
+            "verbatim — no observation overhead. Orthogonal to L5 "
+            "(binary HEALTHY/UNHEALTHY backend swap, planned for "
+            "v1.9-E phase 3): C handles the gradient case during normal "
+            "operation, L5 handles hard crashes."
+        ),
+    )
 
 
 # ---------------------------------------------------------------------------

coderouter/cost.py

@@ -0,0 +1,154 @@
+"""Cost calculation utilities (v1.9-D Cost-aware Dashboard).
+
+Pure functions for translating per-request token counts into USD
+spend, accounting for Anthropic's prompt-cache pricing model
+(``cache_read`` at 10% of normal input, ``cache_creation`` at 125%).
+
+Where this fits
+===============
+
+The engine's ``_emit_cache_observed`` site (v1.9-A) calls
+:func:`compute_cost_for_attempt` to enrich the ``cache-observed``
+log line with ``cost_usd`` + ``cost_savings_usd`` fields. The
+MetricsCollector then aggregates per-provider totals over the
+process lifetime, and the dashboard / ``coderouter stats --cost``
+TUI render those aggregates.
+
+Why a separate module
+=====================
+
+Pricing math is small, pure, and shared by:
+
+  * the engine's per-request cost calc
+  * the collector's snapshot rendering (recomputes a "what-if no
+    cache" total for the savings panel)
+  * the future ``coderouter stats --cost`` CLI
+
+Keeping it as a leaf module with no engine / collector imports
+prevents circular dependencies and makes the pricing semantics
+trivially testable in isolation.
+
+Anthropic pricing reference (verified 2026-04)
+==============================================
+
+For Sonnet / Opus / Haiku 4.x:
+
+  * Normal input  : ``input_tokens_per_million``         x 1.0
+  * Cache read    : ``input_tokens_per_million``         x 0.10
+  * Cache creation: ``input_tokens_per_million``         x 1.25
+  * Normal output : ``output_tokens_per_million``        x 1.0
+
+Tokens reported by the upstream:
+
+  * ``input_tokens`` — "fresh" input (cache reads / writes are
+    excluded from this count and reported via the cache fields).
+  * ``cache_read_input_tokens`` — served from prompt cache.
+  * ``cache_creation_input_tokens`` — written to prompt cache.
+  * ``output_tokens`` — completion.
+
+So a single response's billable cost is the sum of the four buckets
+billed at their respective rates. The "savings" figure is the
+counterfactual: what the operator *would have* paid without prompt
+caching, so it focuses on the cache_read tokens (those are the
+ones that got the 90% discount). cache_creation is a premium, not
+a savings, so it doesn't enter the savings figure even though it's
+in the cost calc.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from coderouter.config.schemas import CostConfig
+
+
+@dataclass(frozen=True)
+class CostBreakdown:
+    """Per-attempt cost components, all in USD.
+
+    All fields default to 0.0 so a free / unconfigured provider
+    yields a zero breakdown without callers having to special-case
+    None.
+
+    Fields
+        total_usd: full cost charged for this attempt (sum of the
+            four token buckets at their respective rates).
+        savings_usd: hypothetical "no-cache" delta — what the
+            operator *would have* paid for ``cache_read_input_tokens``
+            at full input rate, minus what they actually paid at
+            ``cache_read_discount`` rate. Always >= 0.
+        input_usd / output_usd / cache_read_usd / cache_creation_usd:
+            per-bucket breakdown for the dashboard's stacked bar
+            chart. ``input_usd`` is "fresh input only" (does not
+            include cache buckets); cache_read_usd / cache_creation_usd
+            are the post-discount / post-premium values.
+    """
+
+    total_usd: float = 0.0
+    savings_usd: float = 0.0
+    input_usd: float = 0.0
+    output_usd: float = 0.0
+    cache_read_usd: float = 0.0
+    cache_creation_usd: float = 0.0
+
+
+_PER_MILLION: float = 1_000_000.0
+
+
+def compute_cost_for_attempt(
+    cost_config: CostConfig | None,
+    *,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_input_tokens: int,
+    cache_creation_input_tokens: int,
+) -> CostBreakdown:
+    """Translate per-attempt token counts into a USD :class:`CostBreakdown`.
+
+    Returns a zero-filled breakdown when:
+      * ``cost_config`` is ``None`` (provider has no pricing
+        declared — typical for local models)
+      * Both ``input_tokens_per_million`` and ``output_tokens_per_million``
+        are unset (a partial declaration is permitted but the
+        resulting cost is whatever the set fields can compute)
+
+    Negative or zero token counts are accepted and contribute zero
+    cost — the engine never emits negatives, but this defensive
+    handling keeps a malformed log line from corrupting the
+    aggregate counters in the collector.
+    """
+    if cost_config is None:
+        return CostBreakdown()
+
+    input_rate = (cost_config.input_tokens_per_million or 0.0) / _PER_MILLION
+    output_rate = (cost_config.output_tokens_per_million or 0.0) / _PER_MILLION
+
+    safe_input = max(input_tokens, 0)
+    safe_output = max(output_tokens, 0)
+    safe_read = max(cache_read_input_tokens, 0)
+    safe_create = max(cache_creation_input_tokens, 0)
+
+    input_usd = safe_input * input_rate
+    output_usd = safe_output * output_rate
+    cache_read_usd = safe_read * input_rate * cost_config.cache_read_discount
+    cache_creation_usd = safe_create * input_rate * cost_config.cache_creation_premium
+
+    total_usd = input_usd + output_usd + cache_read_usd + cache_creation_usd
+
+    # Savings = what the operator would have paid at full input rate
+    # for the cache_read tokens, minus what they actually paid at
+    # the discounted rate. cache_creation is a *premium* (not a
+    # savings) so it doesn't enter the savings figure — including
+    # it would let a cache miss show up as "negative savings" which
+    # is semantically wrong and would confuse the dashboard.
+    full_rate_for_cache_read = safe_read * input_rate
+    savings_usd = full_rate_for_cache_read - cache_read_usd
+
+    return CostBreakdown(
+        total_usd=total_usd,
+        savings_usd=max(savings_usd, 0.0),
+        input_usd=input_usd,
+        output_usd=output_usd,
+        cache_read_usd=cache_read_usd,
+        cache_creation_usd=cache_creation_usd,
+    )

coderouter/data/model-capabilities.yaml

@@ -90,6 +90,61 @@ rules:
     capabilities:
       thinking: true
 
+  # ------------------------------------------------------------------
+  # Anthropic prompt caching — `cache_control` body field support (v1.9-B).
+  #
+  # Declares which (kind, model) pairs preserve the ``cache_control``
+  # marker end-to-end on the wire. The capability gate
+  # (``provider_supports_cache_control`` in coderouter/routing/capability.py)
+  # consults these declarations to decide whether to emit a
+  # ``capability-degraded reason=translation-lossy`` log when handing
+  # a cache_control-bearing request to the provider.
+  #
+  # Verification basis:
+  #   * api.anthropic.com (kind=anthropic, claude-* models):
+  #     verified live 2026-04-20 — 1321 tokens written on call 1,
+  #     1321 read on call 2. Native Anthropic shape passes through
+  #     verbatim, no translation hop loses the marker.
+  #   * LM Studio /v1/messages (kind=anthropic, qwen3.5-* / qwen3.6-*):
+  #     verified live 2026-04-27 in v1.8.4 — `cache_read_input_tokens: 280`
+  #     observed end-to-end through CodeRouter. LM Studio 0.4.12+ honors
+  #     the marker on its Anthropic-compatible endpoint.
+  #
+  # All entries are kind=anthropic. openai_compat upstreams have no wire
+  # equivalent for cache_control (the OpenAI Chat Completions schema does
+  # not carry it), so they intentionally stay undeclared — the gate's
+  # fallback maps undeclared + kind=openai_compat to False.
+  # ------------------------------------------------------------------
+
+  - match: "claude-opus-4-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
+  - match: "claude-sonnet-4-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
+  - match: "claude-haiku-4-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
+  # LM Studio /v1/messages exposes Qwen3.5 / Qwen3.6 with Anthropic-shaped
+  # responses including ``cache_read_input_tokens``. The provider declares
+  # ``kind: anthropic`` even though the underlying model is open-weights;
+  # the registry rule keys off the model name pattern.
+  - match: "qwen3.5-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
+  - match: "qwen3.6-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
   # ------------------------------------------------------------------
   # Claude Code suitability — agentic harness compatibility hint (v1.7-B).
   #