coderouter-cli 2.7.0__py3-none-any.whl → 2.7.1__py3-none-any.whl

coderouter/config/capability_registry.py

@@ -115,6 +115,20 @@ class RegistryCapabilities(BaseModel):
             "startup check)."
         ),
     )
+    tool_choice: bool | None = Field(
+        default=None,
+        description=(
+            "S2 (shim): does the upstream honor a forced Anthropic "
+            "``tool_choice`` (``{type: any}`` / ``{type: tool}``) on the "
+            "wire? When True, the fallback engine's ``tool_choice_action`` "
+            "leaves the request untouched. ``None`` (default) = no opinion "
+            "→ the gate falls back to ``provider.kind == 'anthropic'``. "
+            "``False`` hard-disables even on an anthropic-kind provider "
+            "(useful when a specific model regresses). Independent from "
+            "``providers.yaml capabilities.tool_choice`` (explicit "
+            "per-provider opt-in, highest precedence)."
+        ),
+    )
     cache_control: bool | None = Field(
         default=None,
         description=(
@@ -201,6 +215,7 @@ class ResolvedCapabilities:
     max_context_tokens: int | None = None
     claude_code_suitability: Literal["ok", "degraded"] | None = None
     cache_control: bool | None = None
+    tool_choice: bool | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -253,6 +268,7 @@ class CapabilityRegistry:
         resolved_max_ctx: int | None = None
         resolved_suitability: Literal["ok", "degraded"] | None = None
         resolved_cache_control: bool | None = None
+        resolved_tool_choice: bool | None = None
 
         thinking_locked = False
         reasoning_locked = False
@@ -260,6 +276,7 @@ class CapabilityRegistry:
         max_ctx_locked = False
         suitability_locked = False
         cache_control_locked = False
+        tool_choice_locked = False
 
         for rule in self._rules:
             if not rule.kind_matches(kind):
@@ -285,6 +302,9 @@ class CapabilityRegistry:
             if not cache_control_locked and caps.cache_control is not None:
                 resolved_cache_control = caps.cache_control
                 cache_control_locked = True
+            if not tool_choice_locked and caps.tool_choice is not None:
+                resolved_tool_choice = caps.tool_choice
+                tool_choice_locked = True
             if (
                 thinking_locked
                 and reasoning_locked
@@ -292,6 +312,7 @@ class CapabilityRegistry:
                 and max_ctx_locked
                 and suitability_locked
                 and cache_control_locked
+                and tool_choice_locked
             ):
                 break
 
@@ -302,6 +323,7 @@ class CapabilityRegistry:
             max_context_tokens=resolved_max_ctx,
             claude_code_suitability=resolved_suitability,
             cache_control=resolved_cache_control,
+            tool_choice=resolved_tool_choice,
         )
 
     # ------------------------------------------------------------------

coderouter/config/schemas.py

@@ -43,6 +43,18 @@ class Capabilities(BaseModel):
     # 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
+    # S2 (shim): Anthropic's ``tool_choice`` forcing modes (``{type: any}``
+    # / ``{type: tool, name: ...}``). Only a subset of backends honor a
+    # forced tool_choice on the wire; openai_compat translation drops it.
+    # This narrow per-model flag mirrors ``thinking`` / ``prompt_cache``:
+    # when unset (None), the capability gate falls back to the registry and
+    # then to a ``kind == "anthropic"`` heuristic (see
+    # ``coderouter/routing/capability.py``). Motivation: let the fallback
+    # engine's ``tool_choice_action`` emulate forced tool calls via a
+    # system-prompt directive on backends that would otherwise silently
+    # ignore the field. Backward compatible — None leaves v2.x behavior
+    # untouched (no gate, no emulation).
+    tool_choice: bool | None = None
     # 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"
@@ -706,6 +718,72 @@ class FallbackChain(BaseModel):
         ),
     )
 
+    # --- S2 (shim): tool_choice capability gate + emulation -----------------
+    #
+    # Anthropic clients (Claude Code, SDKs) can pin the model to a specific
+    # tool with ``tool_choice: {type: "tool", name: "X"}`` or force *some*
+    # tool with ``{type: "any"}``. Native Anthropic honors this; most
+    # openai_compat backends silently ignore it after translation, so the
+    # model may answer with plain text where the client expected a tool
+    # call. This knob decides what the fallback engine does when a forced
+    # tool_choice request is routed to a provider that does not support it
+    # (per ``provider_supports_tool_choice``):
+    #
+    #   * ``off``     — no detection / no mutation / no log. Backward-compat
+    #                   default (identical to pre-shim behavior).
+    #   * ``warn``    — emit a ``capability-degraded`` log line only; the
+    #                   request is sent unchanged.
+    #   * ``emulate`` — strip the ``tool_choice`` field and inject an English
+    #                   directive into the system prompt instructing the
+    #                   model to call the requested tool. Best-effort
+    #                   forcing for backends without native support. The
+    #                   original request object is left untouched so a later
+    #                   capable provider in the chain still receives the real
+    #                   ``tool_choice``.
+    tool_choice_action: Literal["off", "warn", "emulate"] = Field(
+        default="off",
+        description=(
+            "S2 (shim): action when a request carries a forced "
+            "``tool_choice`` (``{type: any}`` or ``{type: tool}``) and the "
+            "target provider does not support it. ``off`` (default) leaves "
+            "the request unchanged. ``warn`` emits a ``capability-degraded`` "
+            "log only. ``emulate`` strips ``tool_choice`` and injects a "
+            "system-prompt directive to coax the model into calling the "
+            "tool. Per-provider — capable providers are never mutated."
+        ),
+    )
+
+    # --- S3 (shim): cache_control strip -------------------------------------
+    #
+    # By default cache_control markers are simply lost during Anthropic →
+    # OpenAI translation and the ``capability-degraded`` gate logs it
+    # (v0.5-B, observability only). Some strict openai_compat backends,
+    # however, 400 when an unexpected ``cache_control`` key rides along on a
+    # content block (rather than silently ignoring it). ``strip`` proactively
+    # removes those keys from a deep copy of the request before dispatch to
+    # a non-supporting provider, so the marker never reaches the wire.
+    #
+    #   * ``off``   — legacy behavior: leave the request as-is and rely on
+    #                 the existing ``capability-degraded`` observability log.
+    #   * ``strip`` — deep-copy the request and remove every ``cache_control``
+    #                 key from system / tools / message blocks before sending
+    #                 to a non-supporting provider; emit a
+    #                 ``cache-control-stripped`` log with the marker count.
+    #                 Does NOT emit a tokens-saved event (this is not token
+    #                 savings, just a wire-compatibility strip).
+    cache_control_action: Literal["off", "strip"] = Field(
+        default="off",
+        description=(
+            "S3 (shim): action when a request carries ``cache_control`` "
+            "markers and the target provider does not support them. ``off`` "
+            "(default) keeps legacy behavior (marker dropped in translation, "
+            "``capability-degraded`` log only). ``strip`` removes the "
+            "``cache_control`` keys from a deep copy before dispatch and "
+            "emits a ``cache-control-stripped`` log. Per-provider — capable "
+            "providers are never mutated."
+        ),
+    )
+
     @model_validator(mode="after")
     def _check_context_budget_thresholds_ordered(self) -> FallbackChain:
         """v2.0-F (mE): cross-field sanity of the context-budget ratios.

coderouter/ingress/anthropic_routes.py

@@ -38,6 +38,8 @@ from coderouter.routing import (
     NoProvidersAvailableError,
 )
 from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.token_estimation import extract_text_from_anthropic_request
+from coderouter.token_estimation_accurate import count_tokens, is_accuracy_available
 from coderouter.translation import (
     AnthropicRequest,
     AnthropicStreamEvent,
@@ -316,6 +318,112 @@ async def messages(
     return anth_resp.model_dump(exclude_none=True)
 
 
+def _resolve_count_tokens_tokenizer_path(
+    config: Any, profile: str | None
+) -> str | None:
+    """S1 (shim): best-effort resolve a local tokenizer.json for counting.
+
+    Routing for ``count_tokens`` is not a full chain resolution — we only
+    need *a* representative tokenizer for the profile the request would use.
+    We take the first provider of the resolved profile (or the default
+    profile) and return its ``tokenizer_path`` when declared. Any resolution
+    hiccup (unknown profile, empty chain, stub config in tests) returns
+    ``None``, which makes :func:`count_tokens` fall back to the char/4
+    heuristic — a graceful degrade rather than an error.
+    """
+    try:
+        chosen = profile or config.default_profile
+        chain_cfg = config.profile_by_name(chosen)
+        for pname in getattr(chain_cfg, "providers", []) or []:
+            pconf = next((p for p in config.providers if p.name == pname), None)
+            if pconf is not None:
+                tok = getattr(pconf, "tokenizer_path", None)
+                if tok:
+                    return tok
+                # First provider resolved but declares no tokenizer — stop
+                # here (don't scan the whole chain for an unrelated one).
+                return None
+    except (AttributeError, KeyError, ValueError, TypeError):
+        return None
+    return None
+
+
+@router.post("/messages/count_tokens", response_model=None)
+async def count_tokens_route(
+    payload: dict[str, Any],
+    request: Request,
+    x_coderouter_profile: str | None = Header(default=None, alias=_PROFILE_HEADER),
+    x_coderouter_mode: str | None = Header(default=None, alias=_MODE_HEADER),
+) -> dict[str, Any]:
+    """Anthropic ``POST /v1/messages/count_tokens`` — local token estimate.
+
+    Mirrors Anthropic's count_tokens endpoint: the request body has the
+    same shape as ``/v1/messages`` (minus the ``max_tokens`` requirement)
+    and the response is ``{"input_tokens": N}``. CodeRouter answers this
+    entirely locally — there is no upstream round-trip — using the same
+    text-extraction the language-tax / context-budget guards use, feeding
+    an accurate local tokenizer when the routed provider declares one and
+    the ``accuracy`` extra is installed, otherwise the char/4 heuristic.
+
+    Validation is deliberately looser than :class:`AnthropicRequest` (no
+    ``max_tokens`` needed): ``model`` and a non-empty ``messages`` list are
+    required, everything else optional. Profile selection follows the same
+    body > profile-header > mode-header precedence as ``/messages`` so the
+    tokenizer resolves against the provider the real request would hit.
+    """
+    config = request.app.state.config
+
+    if not isinstance(payload, dict):
+        raise HTTPException(status_code=400, detail="request body must be a JSON object")
+
+    messages = payload.get("messages")
+    if not isinstance(messages, list) or not messages:
+        raise HTTPException(
+            status_code=400,
+            detail="'messages' is required and must be a non-empty list",
+        )
+    if "model" not in payload:
+        raise HTTPException(status_code=400, detail="'model' is required")
+
+    # Profile selection — body field wins over header, mode header last
+    # (same policy as /messages). Kept minimal: we only need the profile to
+    # pick a representative tokenizer, so an unknown mode/profile degrades
+    # to the default rather than 400'ing the count.
+    profile = payload.get("profile") or x_coderouter_profile
+    if profile is None and x_coderouter_mode:
+        try:
+            profile = config.resolve_mode(x_coderouter_mode)
+        except (KeyError, AttributeError):
+            profile = None
+
+    # Combine system + messages (+ tool JSON length) into one text blob and
+    # count. tools contribute their JSON length as a coarse proxy for the
+    # schema tokens Anthropic would bill.
+    text = extract_text_from_anthropic_request(
+        system=payload.get("system"),
+        messages=messages,
+    )
+    tools = payload.get("tools")
+    if isinstance(tools, list) and tools:
+        with contextlib.suppress(TypeError, ValueError):
+            text = f"{text}\n{json.dumps(tools, ensure_ascii=False)}"
+
+    tokenizer_path = _resolve_count_tokens_tokenizer_path(config, profile)
+    input_tokens = count_tokens(text, tokenizer_path=tokenizer_path)
+    # Report the method count_tokens *actually* used: the accurate backend
+    # only engages when a path is declared AND the optional ``tokenizers``
+    # dependency is importable (see token_estimation_accurate). Otherwise
+    # count_tokens transparently falls back to char/4 — so we must too, or
+    # the log would misreport a heuristic count as tokenizer-accurate.
+    method = "tokenizer" if (tokenizer_path and is_accuracy_available()) else "heuristic"
+
+    logger.info(
+        "count-tokens-served",
+        extra={"method": method, "input_tokens": input_tokens},
+    )
+    return {"input_tokens": input_tokens}
+
+
 async def _anthropic_sse_iterator(
     engine: FallbackEngine, anth_req: AnthropicRequest
 ) -> AsyncIterator[str]:

coderouter/logging.py

@@ -129,6 +129,7 @@ CapabilityDegradedReason = Literal[
     "provider-does-not-support",
     "translation-lossy",
     "non-standard-field",
+    "unsupported-backend",
 ]
 """Why a capability was degraded.
 
@@ -142,6 +143,10 @@ CapabilityDegradedReason = Literal[
 - ``non-standard-field``: upstream emits a field that is not in the spec
   the ingress speaks, so we strip it on the response-side boundary.
   v0.5-C reasoning field.
+- ``unsupported-backend``: the request asks for a semantic the target
+  backend does not honor (S2 forced ``tool_choice``); with action
+  ``warn`` the request is sent unchanged, with ``emulate`` a separate
+  ``tool-choice-emulated`` line records the substituted directive.
 """
 
 

coderouter/routing/capability.py

@@ -38,6 +38,7 @@ Design decisions
 from __future__ import annotations
 
 import logging
+from typing import Any
 
 from coderouter.config.capability_registry import (
     CapabilityRegistry,
@@ -63,13 +64,17 @@ __all__ = [
     "CapabilityRegistry",
     "ResolvedCapabilities",
     "anthropic_request_has_cache_control",
+    "anthropic_request_has_forced_tool_choice",
     "anthropic_request_requires_thinking",
     "check_claude_code_chain_suitability",
+    "emulate_tool_choice",
     "get_default_registry",
     "log_capability_degraded",
     "provider_supports_cache_control",
     "provider_supports_thinking",
+    "provider_supports_tool_choice",
     "reset_default_registry",
+    "strip_cache_control",
     "strip_thinking",
 ]
 
@@ -308,6 +313,218 @@ def anthropic_request_has_cache_control(request: AnthropicRequest) -> bool:
     return False
 
 
+# ---------------------------------------------------------------------------
+# S2 (shim): tool_choice capability gate + emulation
+#
+# Anthropic's ``tool_choice`` forces the model to call a tool: ``{type:
+# "any"}`` (call *some* provided tool) or ``{type: "tool", name: "X"}``
+# (call the named tool). Native Anthropic honors this on the wire; most
+# openai_compat backends silently ignore it after Anthropic → OpenAI
+# translation, so the model can answer with plain text where the client
+# expected a tool call. The gate here answers "does this provider honor a
+# forced tool_choice?" with the same 3-tier resolution as the other v0.5
+# gates. The fallback engine's ``tool_choice_action`` uses the answer to
+# either warn or emulate the forcing via a system-prompt directive.
+#
+# ``auto`` / ``none`` / absent tool_choice never trips the gate — only the
+# forcing modes matter (a non-forced choice loses nothing meaningful in
+# translation).
+# ---------------------------------------------------------------------------
+
+
+def provider_supports_tool_choice(
+    provider: ProviderConfig,
+    *,
+    registry: CapabilityRegistry | None = None,
+) -> bool:
+    """Does this provider honor a forced Anthropic ``tool_choice``?
+
+    Resolution order (mirrors :func:`provider_supports_cache_control`):
+        1. If ``provider.capabilities.tool_choice`` is True → True
+           (explicit per-provider opt-in from providers.yaml — highest
+           precedence).
+        2. Consult the capability registry for an explicit
+           ``tool_choice: true|false`` declaration on this
+           ``(kind, model)``. A registry value of ``False`` hard-disables
+           the capability even on a provider whose ``kind`` would normally
+           pass.
+        3. Fall back to the heuristic ``kind == "anthropic"`` — native
+           ``/v1/messages`` passthrough forwards ``tool_choice`` verbatim,
+           whereas openai_compat translation drops the forcing semantics.
+
+    This routine does not inspect the request — it's a per-provider
+    capability. Combine with :func:`anthropic_request_has_forced_tool_choice`
+    in the engine to decide whether to warn / emulate. The ``registry``
+    kwarg is for tests; production callers pass nothing.
+    """
+    if provider.capabilities.tool_choice:
+        return True
+    resolved = _resolve(provider, registry)
+    if resolved.tool_choice is True:
+        return True
+    if resolved.tool_choice is False:
+        return False
+    return provider.kind == "anthropic"
+
+
+def anthropic_request_has_forced_tool_choice(request: AnthropicRequest) -> bool:
+    """True iff the request forces a tool call via ``tool_choice``.
+
+    Anthropic's ``tool_choice.type`` is one of ``auto`` / ``none`` /
+    ``any`` / ``tool``. Only ``any`` (force *some* tool) and ``tool``
+    (force the named tool) are "forcing" modes that a non-supporting
+    backend would silently ignore. ``auto`` / ``none`` / a missing field
+    return False — there is nothing to emulate.
+    """
+    choice = request.tool_choice
+    if not isinstance(choice, dict):
+        return False
+    return choice.get("type") in ("any", "tool")
+
+
+# English directive templates injected into the system prompt when
+# emulating a forced tool_choice on a non-supporting backend. Kept as
+# module constants so tests can assert the exact text and operators can
+# grep for it.
+_EMULATE_TOOL_DIRECTIVE = (
+    '\n\nIMPORTANT: You MUST respond by calling the tool named "{name}". '
+    "Do not respond with plain text."
+)
+_EMULATE_ANY_DIRECTIVE = (
+    "\n\nIMPORTANT: You MUST respond by calling one of the provided tools. "
+    "Do not respond with plain text."
+)
+
+
+def _inject_system_directive(system: Any, directive: str) -> str | list[dict[str, Any]]:
+    """Append ``directive`` to an Anthropic ``system`` field.
+
+    Handles both wire shapes:
+        - ``str`` (short form) → returns ``system + directive`` (a new
+          ``str``; ``None`` is treated as empty).
+        - ``list[dict]`` (block form) → returns a new list with the
+          directive appended as a trailing ``text`` block, so existing
+          blocks (including any ``cache_control`` markers) are untouched.
+    """
+    if system is None:
+        return directive
+    if isinstance(system, str):
+        return system + directive
+    if isinstance(system, list):
+        return [*system, {"type": "text", "text": directive}]
+    # Unexpected shape — fall back to a fresh string so we never lose the
+    # forcing directive (the original object is left untouched upstream).
+    return directive
+
+
+def emulate_tool_choice(request: AnthropicRequest) -> AnthropicRequest:
+    """Return a copy of ``request`` with tool_choice emulated in the prompt.
+
+    Used by the fallback engine's ``tool_choice_action: "emulate"`` path.
+    The returned request has (1) its ``tool_choice`` field removed and (2)
+    an English directive appended to ``system`` instructing the model to
+    call the requested tool. The directive text differs for ``type ==
+    "tool"`` (names the tool) vs ``type == "any"`` (any provided tool).
+
+    The original request is NOT mutated — the engine iterates a fallback
+    chain and a later capable provider must still receive the real
+    ``tool_choice``. Like :func:`strip_thinking`, the CodeRouter-internal
+    ``profile`` / ``anthropic_beta`` fields are preserved.
+
+    No-op-safe: when the request carries no forced tool_choice this still
+    returns a deep copy (callers gate on
+    :func:`anthropic_request_has_forced_tool_choice` first, so this is
+    just defensive).
+    """
+    choice = request.tool_choice if isinstance(request.tool_choice, dict) else {}
+    ctype = choice.get("type")
+    if ctype == "tool":
+        name = choice.get("name", "")
+        directive = _EMULATE_TOOL_DIRECTIVE.format(name=name)
+    else:  # "any" (or defensive fallback)
+        directive = _EMULATE_ANY_DIRECTIVE
+
+    dumped = request.model_dump()
+    dumped.pop("tool_choice", None)
+    dumped["system"] = _inject_system_directive(request.system, directive)
+    emulated = AnthropicRequest.model_validate(dumped)
+    emulated.profile = request.profile
+    emulated.anthropic_beta = request.anthropic_beta
+    return emulated
+
+
+# ---------------------------------------------------------------------------
+# S3 (shim): cache_control strip
+#
+# The v0.5-B gate (above) is observability-only — it logs that cache_control
+# will be lost in translation but never mutates the request, because most
+# openai_compat backends simply ignore the unknown key. Some strict backends
+# 400 instead. ``strip_cache_control`` proactively removes every
+# ``cache_control`` key from a deep copy of the request so the marker never
+# reaches such a backend. Returns ``(request, markers_removed)`` so the
+# engine can log the count. The original request is not mutated (a later
+# capable provider must still receive the markers).
+# ---------------------------------------------------------------------------
+
+
+def _strip_cache_control_from_blocks(blocks: Any) -> int:
+    """Remove ``cache_control`` from each dict block in ``blocks`` in place.
+
+    Returns the number of keys removed. Non-list / non-dict entries are
+    ignored. Mutates the dicts in the given list (the caller passes a deep
+    copy's containers).
+    """
+    removed = 0
+    if not isinstance(blocks, list):
+        return 0
+    for block in blocks:
+        if isinstance(block, dict) and "cache_control" in block:
+            del block["cache_control"]
+            removed += 1
+    return removed
+
+
+def strip_cache_control(request: AnthropicRequest) -> tuple[AnthropicRequest, int]:
+    """Return ``(copy, markers_removed)`` with all cache_control keys gone.
+
+    Walks the same three locations as
+    :func:`anthropic_request_has_cache_control` — ``system`` blocks,
+    ``tools[*]`` (where the marker rides via ``extra="allow"``), and each
+    list-form ``messages[*].content`` — and removes every ``cache_control``
+    key from a deep copy. The original request is untouched so the fallback
+    chain can hand the real markers to a later capable provider.
+
+    ``markers_removed`` is the total count across all three locations,
+    surfaced by the engine in the ``cache-control-stripped`` log. When the
+    request carried no markers this returns ``(copy, 0)``.
+    """
+    dumped = request.model_dump()
+    removed = 0
+
+    # system blocks (list form only — the str short form can't carry it).
+    removed += _strip_cache_control_from_blocks(dumped.get("system"))
+
+    # tool definitions — cache_control arrives via extra="allow".
+    tools = dumped.get("tools")
+    if isinstance(tools, list):
+        for tool in tools:
+            if isinstance(tool, dict) and "cache_control" in tool:
+                del tool["cache_control"]
+                removed += 1
+
+    # message content blocks (list form only).
+    messages = dumped.get("messages")
+    if isinstance(messages, list):
+        for msg in messages:
+            if isinstance(msg, dict):
+                removed += _strip_cache_control_from_blocks(msg.get("content"))
+
+    stripped = AnthropicRequest.model_validate(dumped)
+    stripped.profile = request.profile
+    stripped.anthropic_beta = request.anthropic_beta
+    return stripped, removed
+
+
 # ---------------------------------------------------------------------------
 # v1.7-B: claude_code_suitability startup check
 #