chipgraph 0.1.0__py3-none-any.whl

chipgraph/adapters/llm/__init__.py

@@ -0,0 +1,58 @@
+"""LLM providers for the API runtime, and the guard every call goes through.
+
+- `FakeProvider` (`fake`): deterministic scripted replies for tests and CI; never a network call.
+- `AnthropicProvider` (`anthropic`, `anthropic-compatible`): the Anthropic Messages API, at
+  Anthropic or at another `base_url` (e.g. GLM); needs the extra `chipgraph[llm]`.
+- `GuardedProvider`: wraps any provider with the 'nda' rule, a run `Ledger` (token and cost
+  accounting against a `RunBudget`) and retry with backoff (`RetryPolicy`).
+"""
+
+from __future__ import annotations
+
+from chipgraph.adapters.llm._budget import (
+    DEFAULT_PRICES,
+    Ledger,
+    ModelPrice,
+    ModelUsage,
+    RunBudget,
+    Usage,
+    price_for,
+)
+from chipgraph.adapters.llm._errors import (
+    BudgetExceeded,
+    LlmError,
+    NdaBlocked,
+    ProviderConfigError,
+    ProviderError,
+    RetriesExhausted,
+)
+from chipgraph.adapters.llm._nda import ensure_nda_allowed
+from chipgraph.adapters.llm._retry import RetryPolicy, call_with_retry, is_retryable
+from chipgraph.adapters.llm.anthropic import AnthropicProvider, anthropic_compatible
+from chipgraph.adapters.llm.fake import FakeProvider, count_tokens
+from chipgraph.adapters.llm.guard import GuardedProvider
+
+__all__ = [
+    "DEFAULT_PRICES",
+    "AnthropicProvider",
+    "BudgetExceeded",
+    "FakeProvider",
+    "GuardedProvider",
+    "Ledger",
+    "LlmError",
+    "ModelPrice",
+    "ModelUsage",
+    "NdaBlocked",
+    "ProviderConfigError",
+    "ProviderError",
+    "RetriesExhausted",
+    "RetryPolicy",
+    "RunBudget",
+    "Usage",
+    "anthropic_compatible",
+    "call_with_retry",
+    "count_tokens",
+    "ensure_nda_allowed",
+    "is_retryable",
+    "price_for",
+]

chipgraph/adapters/llm/_budget.py

@@ -0,0 +1,173 @@
+"""Token and cost accounting for a run: prices, the `Usage` summary, and the `Ledger`."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from chipgraph.adapters.llm._errors import BudgetExceeded
+from chipgraph.core.contracts import Budget
+from chipgraph.core.plugin_api.types import LlmResponse
+
+
+class ModelPrice(BaseModel):
+    """What a model costs, in USD per million input and output tokens."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    input_per_mtok: float = Field(ge=0, description="USD per 1M input tokens.")
+    output_per_mtok: float = Field(ge=0, description="USD per 1M output tokens.")
+
+    def cost_usd(self, input_tokens: int, output_tokens: int) -> float:
+        """The cost of one call with these token counts."""
+        return (input_tokens * self.input_per_mtok + output_tokens * self.output_per_mtok) / 1e6
+
+
+DEFAULT_PRICES: Mapping[str, ModelPrice] = {
+    "claude-opus-5-5": ModelPrice(input_per_mtok=4.0, output_per_mtok=20.0),
+    "claude-sonnet-5-5": ModelPrice(input_per_mtok=2.0, output_per_mtok=10.0),
+    # Haiku 5.5 is $0.10 / $0.50 up to 100k prompt tokens and $0.50 / $2.50 above; one
+    # flat price cannot show both, so this is the higher one: a budget cap stays safe.
+    "claude-haiku-5-5": ModelPrice(input_per_mtok=0.5, output_per_mtok=2.5),
+    "claude-opus-4-5": ModelPrice(input_per_mtok=5.0, output_per_mtok=25.0),
+    "claude-opus-4-1": ModelPrice(input_per_mtok=15.0, output_per_mtok=75.0),
+    "claude-opus-4": ModelPrice(input_per_mtok=15.0, output_per_mtok=75.0),
+    "claude-sonnet-4-5": ModelPrice(input_per_mtok=3.0, output_per_mtok=15.0),
+    "claude-sonnet-4": ModelPrice(input_per_mtok=3.0, output_per_mtok=15.0),
+    "claude-haiku-4-5": ModelPrice(input_per_mtok=1.0, output_per_mtok=5.0),
+    "claude-3-5-haiku": ModelPrice(input_per_mtok=0.8, output_per_mtok=4.0),
+}
+"""Base list prices (no prompt caching, no batch discount) of the Claude models known when
+this table was written. Newer models, GLM and self-hosted models are not listed: pass a
+table of your own (e.g. `{**DEFAULT_PRICES, "glm-x": ModelPrice(...)}`) to price them."""
+
+_DATE_SUFFIX = re.compile(r"-\d{8}$")
+
+
+def price_for(model: str, prices: Mapping[str, ModelPrice]) -> ModelPrice | None:
+    """The price of `model`: an exact entry, else the entry without a `-YYYYMMDD` suffix."""
+    if model in prices:
+        return prices[model]
+    return prices.get(_DATE_SUFFIX.sub("", model))
+
+
+class ModelUsage(BaseModel):
+    """Usage of one model within a run."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    calls: int = Field(default=0, ge=0, description="Completed calls.")
+    input_tokens: int = Field(default=0, ge=0, description="Input tokens of those calls.")
+    output_tokens: int = Field(default=0, ge=0, description="Output tokens of those calls.")
+    cost_usd: float | None = Field(
+        default=0.0, description="Cost in USD, or None when the model has no known price."
+    )
+
+
+class Usage(BaseModel):
+    """A running summary of a run's LLM usage: calls, tokens and cost, in total and per model.
+
+    `cost_usd` sums the calls whose model has a known price; `unpriced_calls` counts the
+    others, whose tokens are still counted.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    calls: int = Field(default=0, ge=0, description="Completed calls.")
+    input_tokens: int = Field(default=0, ge=0, description="Input tokens of all calls.")
+    output_tokens: int = Field(default=0, ge=0, description="Output tokens of all calls.")
+    cost_usd: float = Field(default=0.0, ge=0, description="Cost of the priced calls, in USD.")
+    unpriced_calls: int = Field(default=0, ge=0, description="Calls of models with no price.")
+    per_model: dict[str, ModelUsage] = Field(default={}, description="Usage by model id.")
+
+    @property
+    def total_tokens(self) -> int:
+        """Input plus output tokens."""
+        return self.input_tokens + self.output_tokens
+
+    def add(
+        self, model: str, input_tokens: int, output_tokens: int, price: ModelPrice | None
+    ) -> Usage:
+        """A new summary with one more call of `model` added."""
+        cost = price.cost_usd(input_tokens, output_tokens) if price is not None else None
+        before = self.per_model.get(model, ModelUsage())
+        after = ModelUsage(
+            calls=before.calls + 1,
+            input_tokens=before.input_tokens + input_tokens,
+            output_tokens=before.output_tokens + output_tokens,
+            cost_usd=None if cost is None or before.cost_usd is None else before.cost_usd + cost,
+        )
+        return Usage(
+            calls=self.calls + 1,
+            input_tokens=self.input_tokens + input_tokens,
+            output_tokens=self.output_tokens + output_tokens,
+            cost_usd=self.cost_usd + (cost or 0.0),
+            unpriced_calls=self.unpriced_calls + (cost is None),
+            per_model={**self.per_model, model: after},
+        )
+
+
+class RunBudget(BaseModel):
+    """Limits for a run: total tokens and/or USD. A limit left as None is not enforced."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    max_tokens: int | None = Field(default=None, ge=1, description="Input + output tokens.")
+    max_usd: float | None = Field(
+        default=None, gt=0, allow_inf_nan=False, description="Cost of priced calls, USD."
+    )
+
+    @classmethod
+    def from_budget(cls, budget: Budget) -> Self:
+        """The run budget of a rule's `Budget` (its `tokens` cap)."""
+        return cls(max_tokens=budget.tokens)
+
+
+class Ledger:
+    """Accounts every response of a run against its `RunBudget`.
+
+    One ledger may be shared by several providers so that they spend one budget. The
+    check runs before a call starts: once the budget is spent, no further call starts.
+    A call already in flight is still accounted, so the last call may overshoot a limit.
+    Calls of unpriced models count towards `max_tokens` but not `max_usd`.
+    """
+
+    def __init__(
+        self,
+        budget: RunBudget | None = None,
+        prices: Mapping[str, ModelPrice] | None = None,
+    ) -> None:
+        self.budget = budget if budget is not None else RunBudget()
+        self.prices: Mapping[str, ModelPrice] = prices if prices is not None else DEFAULT_PRICES
+        self._usage = Usage()
+
+    @property
+    def usage(self) -> Usage:
+        """The usage so far."""
+        return self._usage
+
+    def check(self) -> None:
+        """Raise `BudgetExceeded` if the budget is already spent."""
+        max_tokens, max_usd = self.budget.max_tokens, self.budget.max_usd
+        used = self._usage
+        if max_tokens is not None and used.total_tokens >= max_tokens:
+            raise BudgetExceeded(
+                f"token budget spent: {used.total_tokens} of {max_tokens} tokens used "
+                f"in {used.calls} calls"
+            )
+        if max_usd is not None and used.cost_usd >= max_usd:
+            raise BudgetExceeded(
+                f"USD budget spent: ${used.cost_usd:.4f} of ${max_usd:.4f} used "
+                f"in {used.calls} calls"
+            )
+
+    def record(self, response: LlmResponse) -> Usage:
+        """Account `response` and return the new usage."""
+        price = price_for(response.model, self.prices)
+        self._usage = self._usage.add(
+            response.model, response.input_tokens, response.output_tokens, price
+        )
+        return self._usage

chipgraph/adapters/llm/_errors.py

@@ -0,0 +1,50 @@
+"""Errors raised by LLM providers and by the `GuardedProvider` wrapper."""
+
+from __future__ import annotations
+
+
+class LlmError(Exception):
+    """Base class of every error raised by the LLM adapters."""
+
+
+class ProviderConfigError(LlmError):
+    """A provider cannot run as configured: missing extra, missing key variable, bad option."""
+
+
+class ProviderError(LlmError):
+    """A provider call failed.
+
+    `retryable` is true for transient failures only (HTTP 429 and 5xx, timeouts,
+    connection errors); a 4xx other than 429 is never retryable. `retry_after_s` carries
+    the server's `retry-after` hint, if it sent one.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retryable: bool,
+        status: int | None = None,
+        retry_after_s: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.retryable = retryable
+        self.status = status
+        self.retry_after_s = retry_after_s
+
+
+class RetriesExhausted(LlmError):
+    """Every try of a call failed with a retryable error; `last_error` is the final one."""
+
+    def __init__(self, message: str, *, tries: int, last_error: BaseException) -> None:
+        super().__init__(message)
+        self.tries = tries
+        self.last_error = last_error
+
+
+class NdaBlocked(LlmError):
+    """A request labeled 'nda' was refused before any call, because the model is not local."""
+
+
+class BudgetExceeded(LlmError):
+    """The run's token or USD budget is spent; the call was not started."""

chipgraph/adapters/llm/_nda.py

@@ -0,0 +1,30 @@
+"""The 'nda' rule: data labeled 'nda' only ever goes to a local (self-hosted) model."""
+
+from __future__ import annotations
+
+from chipgraph.adapters.llm._errors import NdaBlocked
+from chipgraph.core.config.models import DataCfg
+from chipgraph.core.plugin_api.types import LlmRequest
+
+
+def ensure_nda_allowed(
+    provider: str, local: bool, request: LlmRequest, data: DataCfg | None = None
+) -> None:
+    """Raise `NdaBlocked` if `request` carries 'nda' and may not go to `provider`.
+
+    A request labeled 'nda' is allowed only when the provider is local and, when a
+    profile's `data` section is given, its `nda_model` is 'local' (DESIGN 9, 12.6).
+    """
+    if "nda" not in request.labels:
+        return
+    if not local:
+        raise NdaBlocked(
+            f"request is labeled 'nda' and provider {provider!r} is not local; 'nda' data "
+            "only goes to a self-hosted model (set local: 'true' on such a provider)"
+        )
+    if data is not None and data.nda_model != "local":
+        raise NdaBlocked(
+            f"request is labeled 'nda' and the profile sets data.nda_model to "
+            f"{data.nda_model!r}; set it to 'local' to send 'nda' data to local provider "
+            f"{provider!r}"
+        )

chipgraph/adapters/llm/_retry.py

@@ -0,0 +1,85 @@
+"""Retry with exponential backoff and jitter, for transient provider failures only."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from collections.abc import Awaitable, Callable
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from chipgraph.adapters.llm._errors import ProviderError, RetriesExhausted
+
+Sleep = Callable[[float], Awaitable[None]]
+"""An async sleep, `asyncio.sleep` by default; injectable for tests."""
+
+Rand = Callable[[], float]
+"""A uniform random number in [0, 1), `random.random` by default; injectable for tests."""
+
+
+class RetryPolicy(BaseModel):
+    """How many times to try a call and how long to wait between tries.
+
+    The wait before retry `n` (1-based) is drawn from `[c/2, c]` with
+    `c = min(max_delay_s, base_delay_s * 2 ** (n - 1))` ("equal jitter"), and never less
+    than the server's `retry-after` hint (itself capped at `max_delay_s`).
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    max_tries: int = Field(default=4, ge=1, description="Tries in total, the first included.")
+    base_delay_s: float = Field(default=1.0, ge=0, description="Ceiling of the first wait.")
+    max_delay_s: float = Field(default=30.0, ge=0, description="Largest wait between tries.")
+
+    @model_validator(mode="after")
+    def _check_delays(self) -> Self:
+        if self.max_delay_s < self.base_delay_s:
+            raise ValueError("max_delay_s must be at least base_delay_s")
+        return self
+
+    def delay_s(self, retry: int, rand: float, retry_after_s: float | None = None) -> float:
+        """The wait before retry number `retry` (1-based), given a random draw `rand`."""
+        ceiling = min(self.max_delay_s, self.base_delay_s * 2.0 ** (retry - 1))
+        delay = ceiling / 2 + rand * ceiling / 2
+        if retry_after_s is not None:
+            delay = max(delay, min(retry_after_s, self.max_delay_s))
+        return delay
+
+
+def is_retryable(exc: BaseException) -> bool:
+    """True for transient failures: a retryable `ProviderError`, a timeout, a lost connection."""
+    if isinstance(exc, ProviderError):
+        return exc.retryable
+    return isinstance(exc, TimeoutError | ConnectionError)
+
+
+async def call_with_retry[T](
+    call: Callable[[], Awaitable[T]],
+    policy: RetryPolicy,
+    *,
+    sleep: Sleep = asyncio.sleep,
+    rand: Rand = random.random,
+    before_try: Callable[[], None] | None = None,
+) -> T:
+    """Await `call()`, retrying transient failures under `policy`.
+
+    `before_try` runs before every try (e.g. a budget check) and may raise to stop.
+    A non-retryable error propagates at once; when every try failed with a retryable
+    error, `RetriesExhausted` is raised from the last one.
+    """
+    for attempt in range(1, policy.max_tries + 1):
+        if before_try is not None:
+            before_try()
+        try:
+            return await call()
+        except Exception as exc:
+            if not is_retryable(exc):
+                raise
+            if attempt == policy.max_tries:
+                raise RetriesExhausted(
+                    f"gave up after {attempt} tries: {exc}", tries=attempt, last_error=exc
+                ) from exc
+            retry_after = exc.retry_after_s if isinstance(exc, ProviderError) else None
+            await sleep(policy.delay_s(attempt, rand(), retry_after))
+    raise AssertionError("unreachable: max_tries >= 1")  # pragma: no cover

chipgraph/adapters/llm/anthropic.py

@@ -0,0 +1,247 @@
+"""`AnthropicProvider`: the Anthropic Messages API, for `anthropic` and `anthropic-compatible`.
+
+`anthropic-compatible` is the same Messages API served at another `base_url`, e.g. GLM's
+Anthropic-compatible endpoint or a self-hosted gateway (DECISIONS D24). The SDK is the
+optional extra `chipgraph[llm]` and is imported only when the first call is made.
+
+Configuration comes from `models.providers.<name>` in the profile, all values strings:
+
+- `base_url`: the API endpoint; required for `anthropic-compatible`. For `anthropic` it
+  defaults to Anthropic's own endpoint (the `ANTHROPIC_BASE_URL` variable is not read).
+- `api_key_env`: the *name* of the environment variable holding the key, never the key
+  itself. Defaults to `ANTHROPIC_API_KEY` for `anthropic`; required for
+  `anthropic-compatible`, so an Anthropic key is never sent to another endpoint by default.
+- `auth`: `x-api-key` (default) sends the key as `x-api-key`; `bearer` as
+  `Authorization: Bearer`.
+- `local`: `"true"` only for a self-hosted endpoint; only then may it see 'nda' data.
+- `timeout_s`: request timeout in seconds (default 600).
+
+The SDK's own retries are turned off: retry belongs to `GuardedProvider`.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import re
+from collections.abc import Mapping
+from types import ModuleType
+from typing import TYPE_CHECKING, Any
+
+from chipgraph.adapters.llm._errors import LlmError, ProviderConfigError, ProviderError
+from chipgraph.adapters.llm._nda import ensure_nda_allowed
+from chipgraph.core.config.models import ModelsCfg
+from chipgraph.core.plugin_api.types import LlmRequest, LlmResponse
+
+if TYPE_CHECKING:
+    import httpx2
+
+ANTHROPIC_BASE_URL = "https://api.anthropic.com"
+DEFAULT_KEY_ENV = "ANTHROPIC_API_KEY"
+DEFAULT_TIMEOUT_S = 600.0
+
+_KEYS = frozenset({"base_url", "api_key_env", "auth", "local", "timeout_s"})
+_ENV_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_BOOLS = {"true": True, "false": False}
+_AUTHS = frozenset({"x-api-key", "bearer"})
+
+
+def _import_sdk() -> ModuleType:
+    try:
+        return importlib.import_module("anthropic")
+    except ImportError as exc:
+        raise ProviderConfigError(
+            "the anthropic provider needs the 'anthropic' package, which is not installed; "
+            "install the extra: pip install 'chipgraph[llm]' (or uv sync --extra llm)"
+        ) from exc
+
+
+class AnthropicProvider:
+    """Completes `LlmRequest`s through the Anthropic Messages API (see the module docstring).
+
+    Construction only validates the configuration; the SDK import, the `base_url` and key
+    requirements are checked at the first `complete`, so an unconfigured instance (as the
+    plugin registry makes) is harmless. `env` defaults to `os.environ`; `http_client` is
+    passed to the SDK (tests inject one with a mock transport).
+    """
+
+    def __init__(
+        self,
+        config: Mapping[str, str] | None = None,
+        *,
+        name: str = "anthropic",
+        compatible: bool = False,
+        env: Mapping[str, str] | None = None,
+        http_client: httpx2.AsyncClient | None = None,
+    ) -> None:
+        config = dict(config or {})
+        unknown = sorted(set(config) - _KEYS)
+        if unknown:
+            raise ProviderConfigError(
+                f"provider {name!r}: unknown option(s) {unknown}; known: {sorted(_KEYS)}"
+            )
+        self.name = name
+        self.compatible = compatible
+        self.base_url = config.get("base_url") or None
+        key_env = config.get("api_key_env") or (None if compatible else DEFAULT_KEY_ENV)
+        if key_env is not None and not _ENV_NAME.fullmatch(key_env):
+            # Never echo the value: it may be a key pasted in by mistake.
+            raise ProviderConfigError(
+                f"provider {name!r}: api_key_env must be the name of an environment "
+                "variable (letters, digits, '_'), not the key itself"
+            )
+        self.api_key_env = key_env
+        self.auth = config.get("auth", "x-api-key")
+        if self.auth not in _AUTHS:
+            raise ProviderConfigError(
+                f"provider {name!r}: auth must be one of {sorted(_AUTHS)}, got {self.auth!r}"
+            )
+        local = config.get("local", "false").strip().lower()
+        if local not in _BOOLS:
+            raise ProviderConfigError(
+                f"provider {name!r}: local must be 'true' or 'false', got {local!r}"
+            )
+        self.local = _BOOLS[local]
+        try:
+            self.timeout_s = float(config.get("timeout_s", DEFAULT_TIMEOUT_S))
+        except ValueError:
+            raise ProviderConfigError(
+                f"provider {name!r}: timeout_s must be a number of seconds"
+            ) from None
+        self._env = env
+        self._http_client = http_client
+        self._sdk: ModuleType | None = None
+        self._client: Any = None
+
+    @classmethod
+    def from_models(
+        cls,
+        models: ModelsCfg,
+        name: str,
+        *,
+        compatible: bool | None = None,
+        env: Mapping[str, str] | None = None,
+        http_client: httpx2.AsyncClient | None = None,
+    ) -> AnthropicProvider:
+        """The provider configured by `models.providers[name]`.
+
+        `compatible` defaults to true for any name other than 'anthropic'.
+        """
+        return cls(
+            models.providers.get(name, {}),
+            name=name,
+            compatible=name != "anthropic" if compatible is None else compatible,
+            env=env,
+            http_client=http_client,
+        )
+
+    def _get_client(self) -> tuple[ModuleType, Any]:
+        if self._client is not None and self._sdk is not None:
+            return self._sdk, self._client
+        sdk = _import_sdk()
+        where = f"models.providers.{self.name}"
+        if self.compatible and self.base_url is None:
+            raise ProviderConfigError(
+                f"provider {self.name!r}: anthropic-compatible needs {where}.base_url"
+            )
+        if self.api_key_env is None:
+            raise ProviderConfigError(
+                f"provider {self.name!r}: set {where}.api_key_env to the name of the "
+                "environment variable holding the API key"
+            )
+        env = self._env if self._env is not None else os.environ
+        key = env.get(self.api_key_env, "")
+        if not key:
+            raise ProviderConfigError(
+                f"provider {self.name!r}: environment variable {self.api_key_env} is not set; "
+                f"it should hold the API key ({where}.api_key_env)"
+            )
+        # SDK v2 sends `api_key` as `Authorization: Bearer`, v1 as `x-api-key`. Set the header
+        # explicitly (and drop the Bearer one) so `auth = "x-api-key"` is the same on the wire
+        # under both; `auth_token` is Bearer in both.
+        credential: dict[str, Any] = (
+            {"api_key": key, "default_headers": {"x-api-key": key, "Authorization": sdk.Omit()}}
+            if self.auth == "x-api-key"
+            else {"auth_token": key}
+        )
+        self._client = sdk.AsyncAnthropic(
+            **credential,
+            base_url=self.base_url or ANTHROPIC_BASE_URL,
+            timeout=self.timeout_s,
+            max_retries=0,
+            http_client=self._http_client,
+        )
+        self._sdk = sdk
+        return sdk, self._client
+
+    async def complete(self, request: LlmRequest) -> LlmResponse:
+        ensure_nda_allowed(self.name, self.local, request)
+        system = "\n\n".join(m.content for m in request.messages if m.role == "system")
+        messages = [
+            {"role": m.role, "content": m.content} for m in request.messages if m.role != "system"
+        ]
+        if not messages:
+            raise LlmError(f"provider {self.name!r}: a request needs a user or assistant message")
+        sdk, client = self._get_client()
+        kwargs: dict[str, Any] = {
+            "model": request.model,
+            "max_tokens": request.max_tokens,
+            "messages": messages,
+        }
+        if system:
+            kwargs["system"] = system
+        try:
+            message = await client.messages.create(**kwargs)
+        except sdk.APIStatusError as exc:
+            status = exc.status_code
+            raise ProviderError(
+                f"provider {self.name!r}: HTTP {status}: {exc.message}",
+                retryable=status == 429 or status >= 500,
+                status=status,
+                retry_after_s=_retry_after(exc.response.headers.get("retry-after")),
+            ) from exc
+        except sdk.APIConnectionError as exc:  # includes APITimeoutError
+            raise ProviderError(
+                f"provider {self.name!r}: {type(exc).__name__}: {exc.message}", retryable=True
+            ) from exc
+        except sdk.AnthropicError as exc:
+            raise ProviderError(f"provider {self.name!r}: {exc}", retryable=False) from exc
+        return _to_response(message, request.model)
+
+
+def _retry_after(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        seconds = float(value)
+    except ValueError:
+        return None  # an HTTP date: ignored, the backoff applies
+    return seconds if seconds >= 0 else None
+
+
+def _to_response(message: Any, requested_model: str) -> LlmResponse:
+    text = "".join(block.text for block in message.content if block.type == "text")
+    usage = message.usage
+    # Cache writes and reads are input tokens too; count them all against the budget.
+    input_tokens = (
+        usage.input_tokens
+        + (usage.cache_creation_input_tokens or 0)
+        + (usage.cache_read_input_tokens or 0)
+    )
+    return LlmResponse(
+        text=text,
+        input_tokens=input_tokens,
+        output_tokens=usage.output_tokens,
+        model=message.model or requested_model,
+    )
+
+
+def anthropic_compatible(
+    config: Mapping[str, str] | None = None,
+    *,
+    name: str = "anthropic-compatible",
+    env: Mapping[str, str] | None = None,
+    http_client: httpx2.AsyncClient | None = None,
+) -> AnthropicProvider:
+    """An `AnthropicProvider` for an Anthropic-compatible endpoint (the entry-point factory)."""
+    return AnthropicProvider(config, name=name, compatible=True, env=env, http_client=http_client)