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

llm_waterfall/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Experiential Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_waterfall/__init__.py

@@ -0,0 +1,53 @@
+"""llm-waterfall: stateless LLM failover across an ordered chain of backends.
+
+Capacity errors (throttling, transient 5xx, timeouts) spill to the next backend; real client
+errors raise immediately. Every call returns which backend served it, token usage, USD cost, and
+the full attempt trail.
+"""
+
+from llm_waterfall.classify import is_capacity_error, outcome_for
+from llm_waterfall.pricing import ModelPrice, cost_usd, price_for
+from llm_waterfall.types import (
+    Attempt,
+    Backend,
+    ChatMaxTokensField,
+    ChatRequest,
+    ChatResponse,
+    ChatResult,
+    CompletionResult,
+    EmbeddingResult,
+    EmbeddingsUnsupported,
+    Message,
+    RetryPolicy,
+    TokenUsage,
+    ToolCallingUnsupported,
+    VerifyResult,
+    WaterfallExhausted,
+)
+from llm_waterfall.waterfall import Waterfall
+
+__version__ = "0.1.4"
+
+__all__ = [
+    "Attempt",
+    "Backend",
+    "ChatMaxTokensField",
+    "ChatRequest",
+    "ChatResponse",
+    "ChatResult",
+    "CompletionResult",
+    "EmbeddingResult",
+    "EmbeddingsUnsupported",
+    "Message",
+    "ModelPrice",
+    "RetryPolicy",
+    "TokenUsage",
+    "ToolCallingUnsupported",
+    "VerifyResult",
+    "Waterfall",
+    "WaterfallExhausted",
+    "cost_usd",
+    "is_capacity_error",
+    "outcome_for",
+    "price_for",
+]

llm_waterfall/adapters/__init__.py

@@ -0,0 +1,36 @@
+"""Adapter registry: map a Backend's provider name to its adapter class.
+
+Adapter modules import at module scope (they gate their SDK imports internally, so this package
+imports with zero SDKs installed); only the SDKs themselves are lazy.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from llm_waterfall.adapters.anthropic import AnthropicAdapter
+from llm_waterfall.adapters.aws_mantle import AwsMantleAdapter
+from llm_waterfall.adapters.azure_openai import AzureOpenAIAdapter
+from llm_waterfall.adapters.base import Adapter
+from llm_waterfall.adapters.bedrock import BedrockAdapter
+from llm_waterfall.adapters.openai import OpenAIAdapter
+from llm_waterfall.types import PROVIDERS, Backend
+
+_ADAPTERS: dict[str, Callable[[Backend], Adapter]] = {
+    "bedrock": BedrockAdapter,
+    "openai": OpenAIAdapter,
+    "anthropic": AnthropicAdapter,
+    "azure_openai": AzureOpenAIAdapter,  # real; construction validates endpoint/api_version
+    "aws_mantle": AwsMantleAdapter,  # stub: raises NotImplementedError at construction
+}
+
+
+def build_adapter(backend: Backend) -> Adapter:
+    """Construct the adapter for `backend`. Unimplemented providers fail here, fast."""
+    try:
+        factory = _ADAPTERS[backend.provider]
+    except KeyError:
+        raise ValueError(
+            f"unknown provider {backend.provider!r}; expected one of {', '.join(PROVIDERS)}"
+        ) from None
+    return factory(backend)

llm_waterfall/adapters/anthropic.py

@@ -0,0 +1,105 @@
+"""Anthropic direct-API adapter. Reads ANTHROPIC_API_KEY from the environment."""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, cast
+
+from llm_waterfall.adapters.base import missing_sdk_error
+from llm_waterfall.types import (
+    Backend,
+    ChatRequest,
+    ChatResponse,
+    EmbeddingsUnsupported,
+    Message,
+    TokenUsage,
+    ToolCallingUnsupported,
+)
+
+if TYPE_CHECKING:
+    from anthropic import Anthropic
+    from anthropic.types import MessageParam
+
+
+class AnthropicAdapter:
+    """Claude via the direct Anthropic Messages API."""
+
+    def __init__(self, backend: Backend) -> None:
+        self.backend = backend
+        self._client: Anthropic | None = None
+        self._lock = threading.Lock()
+
+    def _get_client(self) -> Anthropic:
+        if self._client is None:
+            with self._lock:
+                if self._client is None:
+                    try:
+                        import httpx
+                        from anthropic import Anthropic
+                    except ModuleNotFoundError as exc:
+                        raise missing_sdk_error("anthropic", "anthropic") from exc
+
+                    # max_retries=0: the waterfall owns retry policy. Granular httpx.Timeout so
+                    # a dead endpoint fails over after connect_timeout_s, not read_timeout_s.
+                    self._client = Anthropic(
+                        max_retries=0,
+                        timeout=httpx.Timeout(
+                            self.backend.read_timeout_s,
+                            connect=self.backend.connect_timeout_s,
+                        ),
+                    )
+        return self._client
+
+    def complete(
+        self,
+        system: str,
+        messages: list[Message],
+        *,
+        temperature: float | None,
+        max_tokens: int,
+    ) -> tuple[str, TokenUsage]:
+        """One Messages API call; system is a top-level arg (Anthropic-native)."""
+        api_messages = [
+            cast("MessageParam", {"role": m.role, "content": m.content}) for m in messages
+        ]
+        client_messages = self._get_client().messages
+        # Claude 4.7+ rejects sampling params; only forward temperature when explicitly set.
+        if temperature is None:
+            response = client_messages.create(
+                model=self.backend.model,
+                system=system,
+                messages=api_messages,
+                max_tokens=max_tokens,
+            )
+        else:
+            response = client_messages.create(
+                model=self.backend.model,
+                system=system,
+                messages=api_messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+        text = "".join(block.text for block in response.content if block.type == "text")
+        usage = TokenUsage(
+            input_tokens=response.usage.input_tokens,
+            output_tokens=response.usage.output_tokens,
+        )
+        return text, usage
+
+    def complete_chat(self, request: ChatRequest) -> ChatResponse:
+        """Direct Anthropic structured mapping is not implemented yet."""
+        del request
+        raise ToolCallingUnsupported(
+            "the anthropic adapter does not yet map OpenAI-compatible tool calls; "
+            "put an openai, azure_openai, or bedrock backend in the chain"
+        )
+
+    def embed_model_id(self) -> str | None:
+        """Anthropic has no embeddings API."""
+        return None
+
+    def embed(self, texts: list[str]) -> tuple[list[list[float]], TokenUsage]:
+        raise EmbeddingsUnsupported(
+            "Anthropic has no embeddings API; put a bedrock or openai backend in the chain "
+            "for embeddings (the waterfall skips this backend for embed calls)."
+        )

llm_waterfall/adapters/aws_mantle.py

@@ -0,0 +1,47 @@
+"""AWS Mantle adapter — stub that fails at construction.
+
+TODO: implement against the Bedrock Mantle client (`anthropic.AnthropicBedrockMantle` — the
+Messages-API Bedrock endpoint) with `aws_region=backend.region`, credentials via
+`boto3.Session(profile_name=backend.profile)`, `max_retries=0`, and the backend's timeouts.
+Model ids take an `anthropic.` prefix. Classification already covers its error shapes (the
+anthropic SDK exception types + botocore codes).
+
+Failing in `__init__` (not at call time) is deliberate: an unimplemented rung must break
+`Waterfall(...)` construction loudly, never abort a live call mid-chain.
+"""
+
+from __future__ import annotations
+
+from llm_waterfall.types import Backend, ChatRequest, ChatResponse, Message, TokenUsage
+
+
+class AwsMantleAdapter:
+    """Not implemented yet; constructing one fails fast with the workaround."""
+
+    backend: Backend  # satisfies the Adapter protocol; never assigned (init raises)
+
+    def __init__(self, backend: Backend) -> None:
+        raise NotImplementedError(
+            "the aws_mantle adapter is not implemented yet; use a 'bedrock' backend for AWS "
+            "traffic, or contribute the adapter (see the TODO in "
+            "llm_waterfall/adapters/aws_mantle.py)."
+        )
+
+    def complete(
+        self,
+        system: str,
+        messages: list[Message],
+        *,
+        temperature: float | None,
+        max_tokens: int,
+    ) -> tuple[str, TokenUsage]:
+        raise NotImplementedError  # pragma: no cover - unreachable (init raises)
+
+    def complete_chat(self, request: ChatRequest) -> ChatResponse:
+        raise NotImplementedError  # pragma: no cover - unreachable (init raises)
+
+    def embed(self, texts: list[str]) -> tuple[list[list[float]], TokenUsage]:
+        raise NotImplementedError  # pragma: no cover - unreachable (init raises)
+
+    def embed_model_id(self) -> str | None:
+        raise NotImplementedError  # pragma: no cover - unreachable (init raises)

llm_waterfall/adapters/azure_openai.py

@@ -0,0 +1,71 @@
+"""Azure OpenAI adapter: the OpenAI wire mapping behind an AzureOpenAI client.
+
+Requests route by DEPLOYMENT name (`Backend.deployment`, defaulting to `Backend.model`); the key
+is read from AZURE_OPENAI_API_KEY. Construction fails fast when `endpoint`/`api_version` are
+missing — a misconfigured rung must break `Waterfall(...)`, not a live call mid-chain.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from llm_waterfall.adapters.base import missing_sdk_error
+from llm_waterfall.adapters.openai import OpenAIAdapter
+from llm_waterfall.types import Backend, EmbeddingsUnsupported, TokenUsage
+
+if TYPE_CHECKING:
+    from openai import OpenAI
+
+
+class AzureOpenAIAdapter(OpenAIAdapter):
+    """GPT-5.x Azure deployments; embeddings via an Azure embedding deployment."""
+
+    def __init__(self, backend: Backend) -> None:
+        if not backend.endpoint:
+            raise ValueError(
+                "azure_openai backends need endpoint= (e.g. https://<resource>.openai.azure.com)"
+            )
+        if not backend.api_version:
+            raise ValueError("azure_openai backends need api_version= (e.g. 2024-12-01-preview)")
+        # Validated non-None copies (the dataclass fields stay Optional for other providers).
+        self._azure_endpoint: str = backend.endpoint
+        self._api_version: str = backend.api_version
+        super().__init__(backend)
+
+    def _get_client(self) -> OpenAI:
+        if self._client is None:
+            with self._lock:
+                if self._client is None:
+                    try:
+                        import httpx
+                        from openai import AzureOpenAI
+                    except ModuleNotFoundError as exc:
+                        raise missing_sdk_error("openai", "azure") from exc
+
+                    # Same policy as every adapter: the waterfall owns retries; bound connects.
+                    self._client = AzureOpenAI(
+                        azure_endpoint=self._azure_endpoint,
+                        api_version=self._api_version,
+                        max_retries=0,
+                        timeout=httpx.Timeout(
+                            self.backend.read_timeout_s,
+                            connect=self.backend.connect_timeout_s,
+                        ),
+                    )
+        return self._client
+
+    def _request_model(self) -> str:
+        # Azure routes by deployment name, not the base model id.
+        return self.backend.deployment or self.backend.model
+
+    def embed_model_id(self) -> str | None:
+        # Azure embeddings need their own deployment; there is no meaningful default.
+        return self.backend.embed_model
+
+    def embed(self, texts: list[str]) -> tuple[list[list[float]], TokenUsage]:
+        if self.backend.embed_model is None:
+            raise EmbeddingsUnsupported(
+                "this azure_openai backend has no embed_model= (an Azure embedding deployment); "
+                "the waterfall skips it for embed calls"
+            )
+        return super().embed(texts)

llm_waterfall/adapters/base.py

@@ -0,0 +1,51 @@
+"""The Adapter protocol every provider backend implements.
+
+An adapter owns exactly one backend's SDK client and wire mapping. It raises its SDK's native
+exceptions — classification (capacity vs client error) happens centrally in
+`llm_waterfall.classify`, and the failover loop in `llm_waterfall.waterfall` owns retry policy.
+Adapters must not retry internally.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from llm_waterfall.types import Backend, ChatRequest, ChatResponse, Message, TokenUsage
+
+
+def missing_sdk_error(package: str, extra: str) -> ModuleNotFoundError:
+    """A ModuleNotFoundError that tells the user which extra installs the missing SDK."""
+    return ModuleNotFoundError(
+        f"the '{package}' package is required for this backend; "
+        f'install it with: pip install "llm-waterfall[{extra}]"'
+    )
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """One backend's completion + embedding implementation."""
+
+    backend: Backend
+
+    def complete(
+        self,
+        system: str,
+        messages: list[Message],
+        *,
+        temperature: float | None,
+        max_tokens: int,
+    ) -> tuple[str, TokenUsage]:
+        """Run one completion; return (text, usage). Raises the SDK's native errors."""
+        ...
+
+    def complete_chat(self, request: ChatRequest) -> ChatResponse:
+        """Run one structured tool-calling completion."""
+        ...
+
+    def embed(self, texts: list[str]) -> tuple[list[list[float]], TokenUsage]:
+        """Embed texts; return (vectors, usage). Raises EmbeddingsUnsupported if N/A."""
+        ...
+
+    def embed_model_id(self) -> str | None:
+        """The model embed() resolves to (None if unsupported) — owns embed attribution."""
+        ...