world-model-optimizer 0.2.0__py3-none-any.whl

llm_waterfall/pricing.py

@@ -0,0 +1,110 @@
+"""Per-model token pricing → USD cost.
+
+Provider-agnostic: prices are keyed by a normalized model id (routing prefixes like Bedrock's
+`us.anthropic.` are stripped before lookup), so the same Opus 4.8 row covers the direct API and
+Bedrock. Prices are USD per 1M tokens; an unknown model costs 0.0 and `price_for` returns None so
+callers can surface "cost unavailable" rather than silently under-reporting. Per-call overrides are
+passed explicitly — there is no global mutable registry.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+from pydantic import BaseModel
+
+from llm_waterfall.types import TokenUsage
+
+# Bedrock appends a snapshot date and/or version to the model id, e.g.
+# `claude-haiku-4-5-20251001-v1:0` or `claude-opus-4-6-v1`. Strip them so the lookup key matches
+# the undated table rows (`claude-haiku-4-5`). Only applied to `claude-*` ids.
+_BEDROCK_SUFFIX = re.compile(r"(-\d{8})?(-v\d+)?(:\d+)?$")
+
+
+class ModelPrice(BaseModel):
+    """USD per 1,000,000 tokens, split by input/output."""
+
+    input_per_mtok: float
+    output_per_mtok: float
+
+
+# Keyed by normalized model id (see `_normalize`). USD per 1M tokens.
+#
+# Completion prices verified 2026-07-01 against the live vendor pricing pages (Claude via
+# platform.claude.com models overview; OpenAI GPT-5.x Standard tier, short context). Embedding
+# prices are long-stable list prices; treat as approximate.
+_PRICES: dict[str, ModelPrice] = {
+    # --- Anthropic / Bedrock (Claude) ---
+    "claude-fable-5": ModelPrice(input_per_mtok=10.0, output_per_mtok=50.0),
+    "claude-mythos-5": ModelPrice(input_per_mtok=10.0, output_per_mtok=50.0),
+    "claude-opus-4-8": ModelPrice(input_per_mtok=5.0, output_per_mtok=25.0),
+    "claude-opus-4-7": ModelPrice(input_per_mtok=5.0, output_per_mtok=25.0),
+    "claude-opus-4-6": ModelPrice(input_per_mtok=5.0, output_per_mtok=25.0),
+    "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-sonnet-5": ModelPrice(input_per_mtok=3.0, output_per_mtok=15.0),
+    "claude-sonnet-4-6": 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),
+    # --- OpenAI / Azure OpenAI (GPT-5.x; Azure deployments reuse the base model's price) ---
+    "gpt-5.5": ModelPrice(input_per_mtok=5.0, output_per_mtok=30.0),
+    "gpt-5.5-pro": ModelPrice(input_per_mtok=30.0, output_per_mtok=180.0),
+    "gpt-5.4": ModelPrice(input_per_mtok=2.5, output_per_mtok=15.0),
+    "gpt-5.4-mini": ModelPrice(input_per_mtok=0.75, output_per_mtok=4.5),
+    "gpt-5.4-nano": ModelPrice(input_per_mtok=0.2, output_per_mtok=1.25),
+    # Azure-hosted OSS deployments (qwen3-coder, agentworld, ...) are deliberately absent:
+    # a $0 placeholder row would defeat the price_for()->None "cost unavailable" contract.
+    # Supply their negotiated rates per Waterfall via the `prices` override.
+    # --- Embeddings (output tokens are always 0 for embed calls) ---
+    "text-embedding-3-small": ModelPrice(input_per_mtok=0.02, output_per_mtok=0.0),
+    "text-embedding-3-large": ModelPrice(input_per_mtok=0.13, output_per_mtok=0.0),
+    "amazon.titan-embed-text-v2:0": ModelPrice(input_per_mtok=0.02, output_per_mtok=0.0),
+}
+
+
+def _normalize(model: str) -> str:
+    """Strip provider/region routing prefixes so one row covers a model across providers.
+
+    Bedrock ids look like `us.anthropic.claude-opus-4-8`; the direct API uses `claude-opus-4-8`.
+    We drop a leading region segment (`us.`/`eu.`/...) and an `anthropic.` vendor segment, but keep
+    `amazon.titan-...` (its `amazon.` is part of the canonical model id, not a routing prefix).
+    """
+    normalized = model.strip()
+    region_prefixes = ("us.", "eu.", "apac.", "us-gov.", "global.", "jp.", "au.", "ca.")
+    for prefix in region_prefixes:
+        if normalized.startswith(prefix):
+            normalized = normalized[len(prefix) :]
+            break
+    if normalized.startswith("anthropic."):
+        normalized = normalized[len("anthropic.") :]
+    if normalized.startswith("claude-"):
+        # Drop a trailing Bedrock snapshot date / version (`-20251001-v1:0`, `-v1`) so dated
+        # inference-profile ids match the undated table rows.
+        normalized = _BEDROCK_SUFFIX.sub("", normalized)
+    return normalized
+
+
+def price_for(model: str, prices: Mapping[str, ModelPrice] | None = None) -> ModelPrice | None:
+    """The price row for `model` (after normalization), or None if unknown.
+
+    `prices` are per-caller overrides consulted before the static table; they are never merged
+    into it, so one Waterfall's overrides can't leak into another's.
+    """
+    key = _normalize(model)
+    if prices is not None:
+        override = prices.get(key) or prices.get(model)
+        if override is not None:
+            return override
+    return _PRICES.get(key)
+
+
+def cost_usd(
+    model: str, usage: TokenUsage, prices: Mapping[str, ModelPrice] | None = None
+) -> float:
+    """USD cost of `usage` on `model`. Unknown models cost 0.0 (`price_for` detects that)."""
+    price = price_for(model, prices)
+    if price is None:
+        return 0.0
+    return (
+        usage.input_tokens * price.input_per_mtok + usage.output_tokens * price.output_per_mtok
+    ) / 1_000_000

llm_waterfall/types.py

@@ -0,0 +1,295 @@
+"""Public value types: backends, messages, per-call results, and errors.
+
+`Backend` is a frozen dataclass (positional-friendly, hashable, safely shared across threads);
+results are pydantic models so callers get validation and `.model_dump()` for persistence.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+Role = Literal["user", "assistant"]
+ChatMaxTokensField = Literal["max_completion_tokens", "max_tokens"]
+
+PROVIDERS = ("openai", "anthropic", "azure_openai", "bedrock", "aws_mantle")
+
+
+class Message(BaseModel):
+    """One chat turn. The system prompt is a separate `complete()` param, not a message."""
+
+    role: Role
+    content: str
+
+
+@dataclass(frozen=True)
+class Backend:
+    """One (provider, model, credentials) rung of the waterfall.
+
+    Credentials come from the environment (API keys) or, for Bedrock, a named AWS profile —
+    `profile` maps to `boto3.Session(profile_name=...)`, so one chain can span multiple accounts.
+    """
+
+    provider: str  # one of PROVIDERS
+    model: str
+    profile: str | None = None  # bedrock: named AWS profile
+    region: str | None = None  # bedrock
+    endpoint: str | None = None  # azure base URL / custom OpenAI base_url
+    deployment: str | None = None  # azure
+    api_version: str | None = None  # azure
+    embed_model: str | None = None  # None → provider default
+    embed_dim: int | None = None
+    connect_timeout_s: float = 15.0
+    # Generous read timeout: reasoning models can legitimately generate for minutes, and a
+    # mid-generation cutoff wastes the whole call — but a stalled connection must still raise
+    # (and thus fail over) instead of hanging forever.
+    read_timeout_s: float = 600.0
+    chat_max_tokens_field: ChatMaxTokensField = "max_completion_tokens"
+
+    def __post_init__(self) -> None:
+        if self.provider not in PROVIDERS:
+            raise ValueError(
+                f"unknown provider {self.provider!r}; expected one of {', '.join(PROVIDERS)}"
+            )
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """How many times to walk the whole chain before giving up.
+
+    `rounds=1` (default) is pure failover: one attempt per backend, no sleeping. Higher values
+    wrap around — sleep with capped exponential backoff, then restart at the primary — so a long
+    unattended run survives the whole chain throttling at once. The sleep is call-local; the
+    waterfall stays stateless.
+    """
+
+    rounds: int = 1
+    backoff_base_s: float = 15.0
+    backoff_max_s: float = 120.0
+
+    def __post_init__(self) -> None:
+        if self.rounds < 1:
+            raise ValueError("RetryPolicy.rounds must be >= 1")
+
+    def backoff_before_round(self, round_index: int) -> float:
+        """Seconds to sleep before round `round_index` (1-based; round 1 never sleeps)."""
+        if round_index <= 1:
+            return 0.0
+        return min(self.backoff_base_s * 2 ** (round_index - 2), self.backoff_max_s)
+
+
+class TokenUsage(BaseModel):
+    """Raw token counts for one call (pricing converts to USD per 1M tokens)."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+AttemptOutcome = Literal["ok", "capacity_error", "client_error", "unsupported"]
+
+
+class Attempt(BaseModel):
+    """One backend try within a call — the unit of the trace the waterfall returns."""
+
+    provider: str
+    model: str
+    outcome: AttemptOutcome
+    latency_s: float
+    error: str | None = None
+    error_type: str | None = None  # exception class name
+
+
+class CompletionResult(BaseModel):
+    """A completion plus attribution: which backend served it, what it cost, the full path."""
+
+    text: str
+    model_used: str
+    provider_used: str
+    usage: TokenUsage = Field(default_factory=TokenUsage)
+    cost_usd: float = 0.0
+    attempts: list[Attempt] = Field(default_factory=list)
+
+
+JsonObject = dict[str, JsonValue]
+
+
+class ChatFunctionCall(BaseModel):
+    """Function name plus its JSON-encoded arguments in an assistant tool call."""
+
+    name: str
+    arguments: str
+
+
+class ChatToolCall(BaseModel):
+    """One OpenAI-compatible assistant tool call."""
+
+    id: str
+    type: Literal["function"] = "function"
+    function: ChatFunctionCall
+
+
+class ChatMessage(BaseModel):
+    """One structured chat turn, including tool calls and tool results."""
+
+    model_config = ConfigDict(extra="allow")
+
+    role: Literal["system", "developer", "user", "assistant", "tool"]
+    content: JsonValue = None
+    tool_calls: list[ChatToolCall] | None = None
+    tool_call_id: str | None = None
+
+
+class ChatFunctionDefinition(BaseModel):
+    """Function schema advertised to a tool-calling model."""
+
+    name: str
+    description: str = ""
+    parameters: JsonObject = Field(default_factory=dict)
+    strict: bool | None = None
+
+
+class ChatTool(BaseModel):
+    """One OpenAI-compatible function tool definition."""
+
+    type: Literal["function"] = "function"
+    function: ChatFunctionDefinition
+
+
+class ChatRequest(BaseModel):
+    """Provider-neutral structured chat request used by agent runtimes.
+
+    Known tool-calling fields are validated explicitly. ``extra="allow"`` preserves newer
+    OpenAI-compatible request fields emitted by an agent SDK without weakening the typed core.
+    Providers call :meth:`provider_payload` to force a non-streaming request for the framed pi
+    transport and to stamp their own routed model/deployment.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    messages: list[ChatMessage] = Field(default_factory=list)
+    model: str | None = None
+    tools: list[ChatTool] | None = None
+    tool_choice: JsonValue = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+    max_completion_tokens: int | None = None
+    stream: bool = False
+    stream_options: JsonObject | None = None
+
+    def provider_payload(
+        self,
+        model: str,
+        *,
+        max_tokens_field: ChatMaxTokensField = "max_completion_tokens",
+    ) -> JsonObject:
+        """Return the non-streaming wire payload for a provider-routed model."""
+        payload = self.model_dump(mode="json", exclude_none=True)
+        payload["model"] = model
+        payload["stream"] = False
+        payload.pop("stream_options", None)
+        if max_tokens_field == "max_tokens":
+            alternate = payload.pop("max_completion_tokens", None)
+            if alternate is not None and "max_tokens" not in payload:
+                payload["max_tokens"] = alternate
+        else:
+            alternate = payload.pop("max_tokens", None)
+            if alternate is not None and "max_completion_tokens" not in payload:
+                payload["max_completion_tokens"] = alternate
+        return payload
+
+
+class ChatUsage(BaseModel):
+    """OpenAI-compatible structured completion usage."""
+
+    model_config = ConfigDict(extra="allow")
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+
+
+class ChatChoice(BaseModel):
+    """One structured completion choice."""
+
+    model_config = ConfigDict(extra="allow")
+
+    index: int = 0
+    message: ChatMessage
+    finish_reason: str | None = None
+
+
+class ChatResponse(BaseModel):
+    """Structured completion returned to the agent runtime."""
+
+    model_config = ConfigDict(extra="allow")
+
+    choices: list[ChatChoice]
+    usage: ChatUsage | None = None
+    model: str | None = None
+
+    def token_usage(self) -> TokenUsage:
+        """Project provider usage onto the waterfall's canonical counters."""
+        if self.usage is None:
+            return TokenUsage()
+        return TokenUsage(
+            input_tokens=self.usage.prompt_tokens,
+            output_tokens=self.usage.completion_tokens,
+        )
+
+    def wire_payload(self) -> JsonObject:
+        """Serialize the response back to the OpenAI-compatible pi bridge."""
+        return self.model_dump(mode="json", exclude_none=True)
+
+
+class ChatResult(BaseModel):
+    """A structured completion plus waterfall attribution and failover history."""
+
+    response: ChatResponse
+    model_used: str
+    provider_used: str
+    usage: TokenUsage = Field(default_factory=TokenUsage)
+    cost_usd: float = 0.0
+    attempts: list[Attempt] = Field(default_factory=list)
+
+
+class EmbeddingResult(BaseModel):
+    """Embedding vectors plus the same attribution as `CompletionResult`."""
+
+    vectors: list[list[float]]
+    model_used: str
+    provider_used: str
+    usage: TokenUsage = Field(default_factory=TokenUsage)
+    cost_usd: float = 0.0
+    attempts: list[Attempt] = Field(default_factory=list)
+
+
+class VerifyResult(BaseModel):
+    """Outcome of one backend's cheap credential/model ping."""
+
+    ok: bool
+    provider: str
+    model: str
+    detail: str = ""
+
+
+class WaterfallExhausted(RuntimeError):
+    """Every backend in every round was capacity-constrained. Carries the full attempt trail."""
+
+    def __init__(self, message: str, attempts: list[Attempt]) -> None:
+        super().__init__(message)
+        self.attempts = attempts
+
+
+class EmbeddingsUnsupported(NotImplementedError):
+    """Raised by adapters whose provider has no embeddings API; the waterfall skips them."""
+
+
+class ToolCallingUnsupported(NotImplementedError):
+    """Raised by adapters without structured tool-calling support; the waterfall skips them."""
+
+
+def normalize_messages(messages: Sequence[Message | Mapping[str, str]]) -> list[Message]:
+    """Coerce caller messages (typed or raw dicts) into the canonical `Message` list."""
+    return [m if isinstance(m, Message) else Message.model_validate(dict(m)) for m in messages]

llm_waterfall/waterfall.py

@@ -0,0 +1,255 @@
+"""The Waterfall: walk an ordered backend chain, spilling only on capacity errors.
+
+Per call: try each backend in order. A capacity error (throttling, transient 5xx, timeout) spills
+to the next backend; a client error (bad request, auth, validation) raises immediately — failing
+over on those would mask a real bug behind a different model's answer. Success returns a result
+attributed to the backend that actually served (model, provider, cost) plus the full attempt
+trail. When every backend in every round is capacity-constrained, `WaterfallExhausted` carries
+that trail.
+
+Stateless by design: a `Waterfall` is immutable after construction, results are return values
+(never side-channel logs), and the only mutable state is each adapter's lazily-built SDK client,
+guarded by a per-adapter lock — one instance is safe to share across a thread pool.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import Callable, Mapping, Sequence
+from typing import Literal, TypeVar
+
+from llm_waterfall.adapters import build_adapter
+from llm_waterfall.adapters.base import Adapter
+from llm_waterfall.classify import outcome_for
+from llm_waterfall.pricing import ModelPrice, cost_usd
+from llm_waterfall.types import (
+    Attempt,
+    Backend,
+    ChatRequest,
+    ChatResult,
+    CompletionResult,
+    EmbeddingResult,
+    EmbeddingsUnsupported,
+    Message,
+    RetryPolicy,
+    TokenUsage,
+    ToolCallingUnsupported,
+    VerifyResult,
+    WaterfallExhausted,
+    normalize_messages,
+)
+
+T = TypeVar("T")
+
+# Module-level indirection so tests can observe/skip real sleeping.
+_sleep = time.sleep
+
+_DEFAULT_RETRY = RetryPolicy()
+
+_PING_MESSAGES = [Message(role="user", content="ping")]
+
+
+class Waterfall:
+    """An immutable, thread-safe failover chain over `Backend`s."""
+
+    def __init__(
+        self,
+        backends: Sequence[Backend],
+        *,
+        retry: RetryPolicy = _DEFAULT_RETRY,
+        prices: Mapping[str, ModelPrice] | None = None,
+        adapter_factory: Callable[[Backend], Adapter] = build_adapter,
+    ) -> None:
+        if not backends:
+            raise ValueError("Waterfall needs at least one backend")
+        self._backends = tuple(backends)
+        self._retry = retry
+        self._prices = dict(prices) if prices else None
+        # Adapters built eagerly (cheap — SDK clients inside are still lazy), so the tuple is
+        # immutable and there is no shared registry to guard at call time.
+        self._adapters = tuple(adapter_factory(b) for b in self._backends)
+
+    @property
+    def backends(self) -> tuple[Backend, ...]:
+        return self._backends
+
+    def complete(
+        self,
+        system: str = "",
+        messages: Sequence[Message | Mapping[str, str]] = (),
+        *,
+        temperature: float | None = None,
+        max_tokens: int = 4096,
+    ) -> CompletionResult:
+        """Run one completion down the chain.
+
+        `temperature=None` means "don't send" — current reasoning models (Claude 4.7+, GPT-5.x)
+        reject non-default sampling params, so omission is the only safe default.
+        """
+        msgs = normalize_messages(messages)
+
+        def attempt(adapter: Adapter) -> tuple[str, TokenUsage]:
+            return adapter.complete(system, msgs, temperature=temperature, max_tokens=max_tokens)
+
+        text, usage, backend, _, attempts = self._run(attempt, unsupported=None)
+        return CompletionResult(
+            text=text,
+            model_used=backend.model,
+            provider_used=backend.provider,
+            usage=usage,
+            cost_usd=cost_usd(backend.model, usage, self._prices),
+            attempts=attempts,
+        )
+
+    def complete_chat(self, request: ChatRequest) -> ChatResult:
+        """Run one structured tool-calling completion down the chain."""
+
+        def attempt(adapter: Adapter):  # noqa: ANN202 - inferred from Adapter.complete_chat
+            response = adapter.complete_chat(request)
+            return response, response.token_usage()
+
+        response, usage, backend, _, attempts = self._run(
+            attempt, unsupported=ToolCallingUnsupported
+        )
+        return ChatResult(
+            response=response,
+            model_used=backend.model,
+            provider_used=backend.provider,
+            usage=usage,
+            cost_usd=cost_usd(backend.model, usage, self._prices),
+            attempts=attempts,
+        )
+
+    def embed(self, texts: Sequence[str]) -> EmbeddingResult:
+        """Embed `texts` down the same chain; backends with no embeddings API are skipped.
+
+        Failover assumes the chain shares ONE embedding space: vectors from different embedding
+        models are not comparable, so a chain mixing embed models can silently poison a retrieval
+        index if rungs alternate mid-corpus. Keep `embed_model` consistent across rungs (e.g. the
+        same Titan model behind several AWS profiles), or embed through a single-backend chain.
+        """
+        text_list = list(texts)
+
+        def attempt(adapter: Adapter) -> tuple[list[list[float]], TokenUsage]:
+            return adapter.embed(text_list)
+
+        vectors, usage, backend, adapter, attempts = self._run(
+            attempt, unsupported=EmbeddingsUnsupported
+        )
+        # Attribute to the model that actually embedded — the serving adapter is the single
+        # source of truth for how it resolved backend.embed_model.
+        embed_model = adapter.embed_model_id() or backend.model
+        return EmbeddingResult(
+            vectors=vectors,
+            model_used=embed_model,
+            provider_used=backend.provider,
+            usage=usage,
+            cost_usd=cost_usd(embed_model, usage, self._prices),
+            attempts=attempts,
+        )
+
+    def verify(self) -> list[VerifyResult]:
+        """One cheap completion per backend. Reports failures, never raises.
+
+        The ping budget is 256 tokens, not 1: reasoning models (GPT-5.x) spend output tokens on
+        internal reasoning first and return 400 when the cap is hit before any visible text — a
+        1-token ping would mark a perfectly healthy backend as broken.
+        """
+        results: list[VerifyResult] = []
+        for backend, adapter in zip(self._backends, self._adapters, strict=True):
+            try:
+                adapter.complete("", _PING_MESSAGES, temperature=None, max_tokens=256)
+            except Exception as exc:  # noqa: BLE001 - verify reports failure, never raises
+                results.append(
+                    VerifyResult(
+                        ok=False, provider=backend.provider, model=backend.model, detail=str(exc)
+                    )
+                )
+            else:
+                results.append(
+                    VerifyResult(ok=True, provider=backend.provider, model=backend.model)
+                )
+        return results
+
+    def _run(
+        self,
+        attempt: Callable[[Adapter], tuple[T, TokenUsage]],
+        *,
+        unsupported: type[Exception] | None,
+    ) -> tuple[T, TokenUsage, Backend, Adapter, list[Attempt]]:
+        """The failover loop shared by complete() and embed(). All state is call-local."""
+        attempts: list[Attempt] = []
+        last_capacity_exc: Exception | None = None
+        for round_index in range(1, self._retry.rounds + 1):
+            backoff = self._retry.backoff_before_round(round_index)
+            if backoff > 0:
+                # Jittered, and never above the configured cap — callers size outer timeouts
+                # from backoff_max_s. The jitter span is reserved BELOW the cap: capping after
+                # adding jitter would collapse every concurrent caller onto exactly
+                # backoff_max_s once exponential backoff saturates, synchronizing the very
+                # retries jitter exists to spread.
+                span = 0.34 * backoff
+                base = min(backoff, self._retry.backoff_max_s - span)
+                _sleep(base + random.uniform(0, span))  # noqa: S311 - jitter
+            capacity_this_round = False
+            for backend, adapter in zip(self._backends, self._adapters, strict=True):
+                start = time.monotonic()
+                try:
+                    payload, usage = attempt(adapter)
+                except (EmbeddingsUnsupported, ToolCallingUnsupported) as exc:
+                    if unsupported is None or not isinstance(exc, unsupported):
+                        raise
+                    # Not a failure: this backend just has no embeddings API. Recorded and
+                    # skipped without counting toward exhaustion.
+                    attempts.append(self._attempt(backend, "unsupported", start, exc))
+                    continue
+                except Exception as exc:
+                    outcome = outcome_for(exc)
+                    attempts.append(self._attempt(backend, outcome, start, exc))
+                    if outcome == "client_error":
+                        raise  # a real error — never mask it behind a fallback
+                    last_capacity_exc = exc
+                    capacity_this_round = True
+                    continue  # capacity-constrained: spill to the next backend
+                attempts.append(self._attempt(backend, "ok", start, None))
+                return payload, usage, backend, adapter, attempts
+            if not capacity_this_round:
+                # Nothing transient happened this round (every backend was skipped as
+                # unsupported) — further rounds and backoff sleeps can't change the outcome.
+                break
+        if last_capacity_exc is None:
+            # Only reachable when every backend was statically unsupported; further retries
+            # cannot change that, so preserve the feature-specific configuration error.
+            if unsupported is EmbeddingsUnsupported:
+                raise EmbeddingsUnsupported(
+                    "no backend in this chain supports embeddings; add a bedrock or openai "
+                    "backend (anthropic has no embeddings API)."
+                )
+            if unsupported is ToolCallingUnsupported:
+                raise ToolCallingUnsupported(
+                    "no backend in this chain supports structured tool calling; add an openai, "
+                    "azure_openai, or bedrock backend."
+                )
+            raise AssertionError("waterfall ended without a result or capacity error")
+        message = (
+            f"every backend was capacity-constrained after {len(attempts)} attempts "
+            f"across {self._retry.rounds} round(s)"
+        )
+        raise WaterfallExhausted(message, attempts) from last_capacity_exc
+
+    @staticmethod
+    def _attempt(
+        backend: Backend,
+        outcome: Literal["ok", "capacity_error", "client_error", "unsupported"],
+        start: float,
+        exc: Exception | None,
+    ) -> Attempt:
+        return Attempt(
+            provider=backend.provider,
+            model=backend.model,
+            outcome=outcome,
+            latency_s=time.monotonic() - start,
+            error=str(exc) if exc is not None else None,
+            error_type=type(exc).__name__ if exc is not None else None,
+        )