agentpause 0.2.0__py3-none-any.whl

agentpause/__init__.py

@@ -0,0 +1,46 @@
+"""agentpause — predictive scheduling for autonomous LLM agents.
+
+Suspend an agent gracefully *before* it hits a provider rate limit, and resume
+it without redoing work. The core works on any provider (cloud or local); true
+KV-cache warm start is an optional plugin for self-hosted runtimes.
+"""
+
+from .errors import (
+    AgentPauseError,
+    BackendError,
+    CheckpointError,
+    RateLimitHit,
+    TelemetryError,
+)
+from .breaker import CircuitBreaker, CircuitOpenError
+from .estimator import Estimator
+from .fallback import FallbackBackend
+from .retry import RetryPolicy
+from .risk import Budget, Decision, RiskModel, decide, should_checkpoint
+from .state import Checkpoint, StateStore
+from .scheduler import PredictiveScheduler, Session
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "PredictiveScheduler",
+    "Session",
+    "Estimator",
+    "RiskModel",
+    "Budget",
+    "Decision",
+    "decide",
+    "should_checkpoint",
+    "Checkpoint",
+    "StateStore",
+    "RetryPolicy",
+    "FallbackBackend",
+    "CircuitBreaker",
+    "CircuitOpenError",
+    "AgentPauseError",
+    "RateLimitHit",
+    "TelemetryError",
+    "CheckpointError",
+    "BackendError",
+    "__version__",
+]

agentpause/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""Provider adapters: turn real LLM providers into the two callables
+(backend, telemetry) that :class:`agentpause.PredictiveScheduler` expects.
+
+Adapters are optional — the core has zero dependencies. Import them
+explicitly, e.g.::
+
+    from agentpause.adapters.litellm import LiteLLMAdapter
+"""

agentpause/adapters/langgraph.py

@@ -0,0 +1,205 @@
+"""LangGraph adapter: predictive suspension inside any graph.
+
+`LangGraph <https://github.com/langchain-ai/langgraph>`_ persists state with a
+checkpointer and can pause a run with ``interrupt()`` — but it decides
+*reactively*: it saves after each node and crashes (or retries) when the
+provider returns 429. This adapter adds the missing *predictive* gate.
+
+Usage — drop a guard into the node that calls the LLM::
+
+    from agentpause.adapters.langgraph import AgentPauseGuard
+
+    guard = AgentPauseGuard(telemetry=adapter.telemetry)  # e.g. from LiteLLMAdapter
+
+    def agent_node(state):
+        guard.check(state["messages"])          # ← may pause the graph HERE
+        reply = llm.invoke(state["messages"])
+        guard.record(state["messages"], reply.usage_metadata["total_tokens"])
+        return {"messages": state["messages"] + [reply]}
+
+When the estimated cost of the next call does not fit the remaining budget,
+``check()`` calls LangGraph's ``interrupt()``: the run pauses cleanly and the
+configured checkpointer persists it. Resume it later with
+``graph.invoke(Command(resume=True), config)``.
+
+Design notes
+------------
+* **Fresh telemetry on every pass.** On resume LangGraph re-executes the node
+  from the top, so ``check()`` runs again and re-reads the budget — a value
+  serialized before the pause is stale by definition. If the budget is
+  *still* too low, the guard interrupts again rather than letting the call
+  fail with a 429.
+* ``interrupt_fn`` is injectable so the guard is fully testable offline;
+  by default it lazily imports ``langgraph.types.interrupt``.
+* The guard owns an :class:`~agentpause.estimator.Estimator`; feed it with
+  ``record()`` after each real call so ε and σ adapt to the workload.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+from ..estimator import Estimator
+from ..risk import Budget, decide
+
+__all__ = ["AgentPauseGuard"]
+
+# text -> token count
+TokenCounter = Callable[[str], int]
+
+
+def _default_token_counter(text: str) -> int:
+    """Rough offline token estimate (~4 chars/token). Replace via ``count_tokens``."""
+    return max(1, len(text) // 4)
+
+
+def _default_interrupt() -> Callable[[Any], Any]:
+    try:
+        from langgraph.types import interrupt
+    except ImportError as exc:  # pragma: no cover - depends on environment
+        raise ImportError(
+            "The LangGraph adapter needs the 'langgraph' package. "
+            "Install it with:  pip install agentpause[langgraph]"
+        ) from exc
+    return interrupt
+
+
+class AgentPauseGuard:
+    """The predictive gate for a LangGraph node.
+
+    Args:
+        telemetry: callable ``() -> remaining_tokens`` reading the rate-limit
+            window (e.g. ``LiteLLMAdapter(...).telemetry``).
+        estimator: cost estimator (defaults to a fresh :class:`Estimator`).
+        count_tokens: text->token counter (defaults to ~4 chars/token).
+        safety_k: safety factor; higher suspends earlier.
+        interrupt_fn: the pause primitive. Defaults to LangGraph's
+            ``interrupt`` (imported lazily); tests inject a fake.
+        wait_threshold_s: if the budget does not fit but the provider window
+            resets within this many seconds, the guard *sleeps in place*
+            instead of interrupting the graph — a short pause is cheaper than
+            a suspend/resume cycle. Requires telemetry that reports
+            ``reset_seconds`` (e.g. ``LiteLLMAdapter(...).budget``).
+        sleep_fn: how to wait (defaults to ``time.sleep``; tests inject a fake).
+        max_resumes: how many resume/wait passes with a still-too-low budget
+            are tolerated per ``check()`` call — a loop bound, not a policy;
+            each pass re-reads telemetry.
+    """
+
+    def __init__(
+        self,
+        telemetry: Callable[[], "int | Budget"],
+        estimator: Optional[Estimator] = None,
+        count_tokens: Optional[TokenCounter] = None,
+        safety_k: float = 2.0,
+        interrupt_fn: Optional[Callable[[Any], Any]] = None,
+        wait_threshold_s: float = 15.0,
+        sleep_fn: Callable[[float], None] = time.sleep,
+        async_sleep_fn: Optional[Callable[[float], Any]] = None,
+        max_resumes: int = 100,
+    ) -> None:
+        self.telemetry = telemetry
+        self.estimator = estimator if estimator is not None else Estimator()
+        self.count_tokens = count_tokens if count_tokens is not None else _default_token_counter
+        self.safety_k = safety_k
+        self._interrupt = interrupt_fn
+        self.wait_threshold_s = wait_threshold_s
+        self.sleep_fn = sleep_fn
+        self.async_sleep_fn = async_sleep_fn
+        self.max_resumes = max_resumes
+
+    # -- internals -----------------------------------------------------------
+
+    def _input_tokens(self, messages: List[Dict[str, str]]) -> int:
+        return sum(self.count_tokens(m.get("content") or "") for m in messages)
+
+    def _interrupt_call(self, payload: Any) -> Any:
+        if self._interrupt is None:
+            self._interrupt = _default_interrupt()
+        return self._interrupt(payload)
+
+    # -- the predictive gate ---------------------------------------------------
+
+    def check(self, messages: List[Dict[str, str]]) -> None:
+        """Pause the graph if the next LLM call would not fit the budget.
+
+        Reads telemetry fresh on every pass (both the token/TPM and, when
+        reported, the request/RPM dimension). Three outcomes:
+
+        * ``continue`` — returns, the node proceeds to the LLM call.
+        * ``wait`` — the window resets within ``wait_threshold_s``: the guard
+          sleeps in place and re-checks, without pausing the whole graph.
+        * ``checkpoint`` — calls ``interrupt()``: the node aborts and the
+          checkpointer persists the run. On resume the node re-executes and
+          only proceeds once the (freshly read) budget fits.
+        """
+        input_tokens = self._input_tokens(messages)
+        for _ in range(self.max_resumes):
+            raw = self.telemetry()
+            budget = raw if isinstance(raw, Budget) else Budget(remaining_tokens=int(raw))
+            estimated = self.estimator.estimate(input_tokens)
+            sigma = self.estimator.sigma(estimated)
+            d = decide(budget, estimated, sigma, self.safety_k, self.wait_threshold_s)
+            if d.action == "continue":
+                return
+            if d.action == "wait":
+                # reset is imminent: sleeping beats a suspend/resume cycle
+                self.sleep_fn((budget.reset_seconds or 1.0) + 0.5)
+                continue
+            # interrupt() raises on the first pass (the node aborts here);
+            # on a resume pass it RETURNS, and the loop re-reads telemetry.
+            self._interrupt_call({
+                "reason": "predicted_rate_limit",
+                "remaining": budget.remaining_tokens,
+                "remaining_requests": budget.remaining_requests,
+                "reset_seconds": budget.reset_seconds,
+                "estimated": estimated,
+                "sigma": round(sigma, 1),
+                "safety_k": self.safety_k,
+            })
+
+    async def acheck(self, messages: List[Dict[str, str]]) -> None:
+        """Async twin of :meth:`check`, for async LangGraph nodes.
+
+        Same three outcomes; the ``wait`` pause uses ``asyncio.sleep`` (or the
+        injected ``async_sleep_fn``) so the event loop is never blocked.
+        """
+        import asyncio
+
+        input_tokens = self._input_tokens(messages)
+        for _ in range(self.max_resumes):
+            raw = self.telemetry()
+            budget = raw if isinstance(raw, Budget) else Budget(remaining_tokens=int(raw))
+            estimated = self.estimator.estimate(input_tokens)
+            sigma = self.estimator.sigma(estimated)
+            d = decide(budget, estimated, sigma, self.safety_k, self.wait_threshold_s)
+            if d.action == "continue":
+                return
+            if d.action == "wait":
+                delay = (budget.reset_seconds or 1.0) + 0.5
+                if self.async_sleep_fn is not None:
+                    await self.async_sleep_fn(delay)
+                else:
+                    await asyncio.sleep(delay)
+                continue
+            self._interrupt_call({
+                "reason": "predicted_rate_limit",
+                "remaining": budget.remaining_tokens,
+                "remaining_requests": budget.remaining_requests,
+                "reset_seconds": budget.reset_seconds,
+                "estimated": estimated,
+                "sigma": round(sigma, 1),
+                "safety_k": self.safety_k,
+            })
+
+    # -- learning ---------------------------------------------------------------
+
+    def record(self, messages: List[Dict[str, str]], used: int) -> None:
+        """Feed the estimator with the real consumption of a completed call.
+
+        Args:
+            messages: the input that was sent to the LLM.
+            used: total tokens the provider reports for the call.
+        """
+        self.estimator.record(self._input_tokens(messages), used)

agentpause/adapters/litellm.py

@@ -0,0 +1,338 @@
+"""LiteLLM adapter: one adapter, every provider.
+
+`LiteLLM <https://github.com/BerriAI/litellm>`_ exposes 100+ LLM providers
+(OpenAI, Groq, Anthropic, local servers, ...) behind a single
+``completion()`` call, and surfaces each provider's rate-limit response
+headers. This adapter turns that into the two callables the scheduler needs:
+
+    from agentpause import PredictiveScheduler
+    from agentpause.adapters.litellm import LiteLLMAdapter
+
+    adapter = LiteLLMAdapter(model="groq/llama-3.1-8b-instant")
+    sched = PredictiveScheduler(backend=adapter.backend, telemetry=adapter.telemetry)
+
+Design notes
+------------
+* **Telemetry is read from response headers** (``x-ratelimit-remaining-tokens``),
+  which providers attach to every reply — so each ``backend()`` call refreshes
+  the budget reading for free.
+* **The telemetry ping.** A budget value serialized in a checkpoint goes stale
+  (the window resets while the agent sleeps). So when ``telemetry()`` is asked
+  for a value and has no *fresh* reading, it performs a deliberately tiny
+  1-token call just to read the headers again. Cost: ~a dozen tokens and one
+  round-trip — negligible next to a wrong suspend/resume decision.
+* ``completion_fn`` is injectable so the adapter is fully testable offline;
+  by default it lazily imports ``litellm.completion``.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from ..errors import BackendError, RateLimitHit, TelemetryError
+from ..risk import Budget
+
+__all__ = ["LiteLLMAdapter", "TelemetryError", "RateLimitHit"]
+
+
+def _parse_reset(value: str) -> Optional[float]:
+    """Convert provider reset values to seconds-from-now.
+
+    Handles duration strings ('7.66s', '2m59.56s', '450ms' — OpenAI/Groq
+    style) and RFC 3339 timestamps ('2026-07-07T21:04:05Z' — Anthropic style).
+    """
+    if not value:
+        return None
+    text = str(value).strip()
+    # RFC 3339 timestamp → seconds until that instant (never negative)
+    if "T" in text and "-" in text:
+        try:
+            from datetime import datetime, timezone
+            dt = datetime.fromisoformat(text.replace("Z", "+00:00"))
+            return max(0.0, (dt - datetime.now(timezone.utc)).total_seconds())
+        except ValueError:
+            return None
+    m = re.fullmatch(
+        r"(?:(\d+)h)?(?:(\d+)m(?!s))?(?:([\d.]+)\s*(ms|s)?)?",
+        text,
+    )
+    if not m or not any(m.groups()):
+        return None
+    hours = int(m.group(1) or 0)
+    minutes = int(m.group(2) or 0)
+    number = float(m.group(3) or 0)
+    seconds = number / 1000 if m.group(4) == "ms" else number
+    return hours * 3600 + minutes * 60 + seconds
+
+
+_INSTALL_HINT = ("The LiteLLM adapter needs the 'litellm' package. "
+                 "Install it with:  pip install agentpause[litellm]")
+
+
+def _default_completion() -> Callable[..., Any]:
+    try:
+        from litellm import completion
+    except ImportError as exc:  # pragma: no cover - depends on environment
+        raise ImportError(_INSTALL_HINT) from exc
+    return completion
+
+
+def _default_acompletion() -> Callable[..., Any]:
+    try:
+        from litellm import acompletion
+    except ImportError as exc:  # pragma: no cover - depends on environment
+        raise ImportError(_INSTALL_HINT) from exc
+    return acompletion
+
+
+def _default_token_counter() -> Callable[..., int]:
+    try:
+        from litellm import token_counter
+    except ImportError as exc:  # pragma: no cover - depends on environment
+        raise ImportError(_INSTALL_HINT) from exc
+    return token_counter
+
+
+class LiteLLMAdapter:
+    """Backend + telemetry for any LiteLLM-supported provider.
+
+    Args:
+        model: LiteLLM model string, e.g. ``"groq/llama-3.1-8b-instant"``
+            or ``"gpt-4o-mini"``.
+        completion_fn: the function performing the call. Defaults to
+            ``litellm.completion`` (imported lazily); tests inject a fake.
+        remaining_header: response header holding the remaining token budget.
+        fallback_remaining: value ``telemetry()`` returns if the provider
+            sends no budget header. ``None`` (default) raises
+            :class:`TelemetryError` instead, so the problem is never silent.
+        max_age_s: how long a header reading stays "fresh". Older readings
+            trigger a telemetry ping.
+        clock: time source (injectable for tests). Defaults to
+            ``time.monotonic``.
+        **completion_kwargs: extra arguments forwarded to every completion
+            call (e.g. ``temperature=0.2``).
+    """
+
+    def __init__(
+        self,
+        model: str,
+        completion_fn: Optional[Callable[..., Any]] = None,
+        acompletion_fn: Optional[Callable[..., Any]] = None,
+        token_counter_fn: Optional[Callable[..., int]] = None,
+        remaining_header: str = "x-ratelimit-remaining-tokens",
+        requests_header: str = "x-ratelimit-remaining-requests",
+        reset_header: str = "x-ratelimit-reset-tokens",
+        fallback_remaining: Optional[int] = None,
+        max_age_s: float = 10.0,
+        clock: Callable[[], float] = time.monotonic,
+        **completion_kwargs: Any,
+    ) -> None:
+        self.model = model
+        self._completion = completion_fn
+        self._acompletion = acompletion_fn
+        self._token_counter = token_counter_fn
+        self.remaining_header = remaining_header.lower()
+        self.requests_header = requests_header.lower()
+        self.reset_header = reset_header.lower()
+        self.fallback_remaining = fallback_remaining
+        self.max_age_s = max_age_s
+        self._clock = clock
+        self.completion_kwargs = completion_kwargs
+        self._remaining: Optional[int] = None
+        self._remaining_input: Optional[int] = None
+        self._remaining_output: Optional[int] = None
+        self._remaining_requests: Optional[int] = None
+        self._reset_seconds: Optional[float] = None
+        self._read_at: Optional[float] = None
+
+    # -- the two callables the scheduler wants --------------------------------
+
+    def backend(self, messages: List[Dict[str, str]]) -> Tuple[str, int]:
+        """Perform the LLM call; returns ``(reply_text, total_tokens_used)``.
+
+        Every real call doubles as a telemetry reading: the provider's
+        rate-limit headers ride along with the response.
+        """
+        response = self._call(messages=messages, **self.completion_kwargs)
+        self._absorb_headers(response)
+        reply = response.choices[0].message.content or ""
+        used = int(response.usage.total_tokens)
+        return reply, used
+
+    def telemetry(self) -> int:
+        """Remaining tokens in the provider's rate-limit window.
+
+        Answers from the last response's headers if that reading is still
+        fresh (younger than ``max_age_s``); otherwise performs a tiny
+        1-token ping to read the headers again. Never trusts old numbers —
+        a stale budget is how agents crash mid-task.
+        """
+        if not self._is_fresh():
+            self.ping()
+        if self._remaining is not None:
+            return self._remaining
+        if self.fallback_remaining is not None:
+            return self.fallback_remaining
+        raise TelemetryError(
+            f"No '{self.remaining_header}' header in the provider response. "
+            "Either the provider does not expose token budgets, or the header "
+            "name differs (set remaining_header=...), or set "
+            "fallback_remaining=... to proceed with a fixed assumption."
+        )
+
+    async def abackend(self, messages: List[Dict[str, str]]) -> Tuple[str, int]:
+        """Async twin of :meth:`backend` (uses ``litellm.acompletion``)."""
+        response = await self._acall(messages=messages, **self.completion_kwargs)
+        self._absorb_headers(response)
+        reply = response.choices[0].message.content or ""
+        used = int(response.usage.total_tokens)
+        return reply, used
+
+    async def atelemetry(self) -> int:
+        """Async twin of :meth:`telemetry` (the ping, if needed, is async)."""
+        if not self._is_fresh():
+            await self.aping()
+        if self._remaining is not None:
+            return self._remaining
+        if self.fallback_remaining is not None:
+            return self.fallback_remaining
+        raise TelemetryError(
+            f"No '{self.remaining_header}' header in the provider response."
+        )
+
+    async def abudget(self) -> Budget:
+        """Async twin of :meth:`budget`."""
+        return Budget(
+            remaining_tokens=await self.atelemetry(),
+            remaining_requests=self._remaining_requests,
+            reset_seconds=self._reset_seconds,
+            remaining_input_tokens=self._remaining_input,
+            remaining_output_tokens=self._remaining_output,
+        )
+
+    def count_tokens(self, text: str) -> int:
+        """Per-model token count via litellm, with a safe heuristic fallback.
+
+        Wire it into the scheduler for a much more accurate input estimate::
+
+            PredictiveScheduler(..., count_tokens=adapter.count_tokens)
+        """
+        try:
+            if self._token_counter is None:
+                self._token_counter = _default_token_counter()
+            return int(self._token_counter(model=self.model, text=text))
+        except Exception:
+            return max(1, len(text) // 4)   # ~4 chars/token heuristic
+
+    def budget(self) -> Budget:
+        """The full telemetry reading: tokens (TPM), requests (RPM), reset time.
+
+        Same freshness policy as :meth:`telemetry` (stale reading → tiny ping).
+        Pass this to the scheduler to unlock the three-valued decision
+        (``continue`` / ``wait`` / ``checkpoint``)::
+
+            sched = PredictiveScheduler(backend=adapter.backend,
+                                        telemetry=adapter.budget)
+        """
+        return Budget(
+            remaining_tokens=self.telemetry(),
+            remaining_requests=self._remaining_requests,
+            reset_seconds=self._reset_seconds,
+            remaining_input_tokens=self._remaining_input,
+            remaining_output_tokens=self._remaining_output,
+        )
+
+    # -- internals -------------------------------------------------------------
+
+    def ping(self) -> None:
+        """Issue a deliberately tiny call whose only purpose is fresh headers."""
+        response = self._call(
+            messages=[{"role": "user", "content": "ping"}],
+            max_tokens=1,
+        )
+        self._absorb_headers(response)
+
+    async def aping(self) -> None:
+        """Async twin of :meth:`ping`."""
+        response = await self._acall(
+            messages=[{"role": "user", "content": "ping"}],
+            max_tokens=1,
+        )
+        self._absorb_headers(response)
+
+    async def _acall(self, **kwargs: Any) -> Any:
+        if self._acompletion is None:
+            self._acompletion = _default_acompletion()
+        try:
+            return await self._acompletion(model=self.model, **kwargs)
+        except Exception as exc:
+            self._map_provider_error(exc)
+            raise
+
+    def _map_provider_error(self, exc: Exception) -> None:
+        """Translate provider exceptions into agentpause's typed errors.
+
+        429 → RateLimitHit (with retry-after when reported).
+        5xx / timeouts → BackendError(retriable=True): transient infrastructure.
+        Anything else propagates unchanged (4xx = request problem, not retriable).
+        """
+        status = getattr(exc, "status_code", None)
+        if status == 429 or exc.__class__.__name__ == "RateLimitError":
+            headers = getattr(exc, "headers", None) or {}
+            ra = headers.get("retry-after") if hasattr(headers, "get") else None
+            raise RateLimitHit(retry_after=float(ra) if ra is not None else None) from exc
+        if (status is not None and 500 <= int(status) <= 599) or exc.__class__.__name__ in (
+            "Timeout", "APITimeoutError", "APIConnectionError", "ServiceUnavailableError",
+            "InternalServerError",
+        ):
+            raise BackendError(f"transient provider failure: {exc}", retriable=True) from exc
+
+    def _call(self, **kwargs: Any) -> Any:
+        if self._completion is None:
+            self._completion = _default_completion()
+        try:
+            return self._completion(model=self.model, **kwargs)
+        except Exception as exc:
+            self._map_provider_error(exc)
+            raise
+
+    def _is_fresh(self) -> bool:
+        return (
+            self._read_at is not None
+            and (self._clock() - self._read_at) <= self.max_age_s
+        )
+
+    def _absorb_headers(self, response: Any) -> None:
+        """Extract the budget reading from headers.
+
+        Recognizes OpenAI/Groq-style names (``x-ratelimit-remaining-tokens``)
+        and Anthropic-style names (``anthropic-ratelimit-tokens-remaining``,
+        with separate input/output dimensions) automatically.
+        """
+        headers = getattr(response, "_hidden_params", {}).get("additional_headers", {})
+        tokens: Optional[str] = None
+        input_tokens: Optional[str] = None
+        output_tokens: Optional[str] = None
+        requests_: Optional[str] = None
+        reset: Optional[str] = None
+        for key, raw in headers.items():
+            k = str(key).lower()
+            # litellm may prefix provider headers, e.g. "llm_provider-x-ratelimit-..."
+            if k.endswith("input-tokens-remaining"):
+                input_tokens = raw
+            elif k.endswith("output-tokens-remaining"):
+                output_tokens = raw
+            elif k.endswith(self.remaining_header) or k.endswith("ratelimit-tokens-remaining"):
+                tokens = raw
+            elif k.endswith(self.requests_header) or k.endswith("requests-remaining"):
+                requests_ = raw
+            elif k.endswith(self.reset_header) or k.endswith("ratelimit-tokens-reset"):
+                reset = raw
+        self._read_at = self._clock()
+        self._remaining = int(float(tokens)) if tokens is not None else None
+        self._remaining_input = int(float(input_tokens)) if input_tokens is not None else None
+        self._remaining_output = int(float(output_tokens)) if output_tokens is not None else None
+        self._remaining_requests = int(float(requests_)) if requests_ is not None else None
+        self._reset_seconds = _parse_reset(reset) if reset is not None else None

agentpause/breaker.py

@@ -0,0 +1,88 @@
+"""Lightweight circuit breaker: stop hammering a failing provider.
+
+Retries handle *transient* glitches; the breaker handles *persistent* ones.
+After ``failure_threshold`` consecutive infrastructure failures the circuit
+opens: calls fail fast (raising :class:`CircuitOpenError`) without touching
+the provider, until a cooldown expires and a single probe call is allowed
+through (half-open). A successful probe closes the circuit again.
+
+Wrap any backend — it stays a plain ``messages -> (reply, tokens)`` callable:
+
+    from agentpause import CircuitBreaker
+
+    guarded = CircuitBreaker(adapter.backend, failure_threshold=5, cooldown_s=300)
+    sched = PredictiveScheduler(backend=guarded, telemetry=adapter.budget)
+
+Only infrastructure failures count (rate limits, retriable 5xx): a 4xx means
+the request is broken — no amount of cooling down will fix it, so it never
+trips the breaker.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable, Dict, List, Optional, Tuple
+
+from .errors import AgentPauseError, BackendError, RateLimitHit
+
+__all__ = ["CircuitBreaker", "CircuitOpenError"]
+
+Backend = Callable[[List[Dict[str, str]]], Tuple[str, int]]
+
+
+class CircuitOpenError(AgentPauseError):
+    """The circuit is open: the provider is presumed down, call not attempted."""
+
+
+class CircuitBreaker:
+    """Wrap a backend with a CLOSED → OPEN → HALF_OPEN state machine.
+
+    Args:
+        backend: the callable to protect.
+        failure_threshold: consecutive infrastructure failures that open
+            the circuit.
+        cooldown_s: how long the circuit stays open before allowing a probe.
+        clock: time source (injectable for tests).
+    """
+
+    def __init__(
+        self,
+        backend: Backend,
+        failure_threshold: int = 5,
+        cooldown_s: float = 300.0,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.backend = backend
+        self.failure_threshold = failure_threshold
+        self.cooldown_s = cooldown_s
+        self._clock = clock
+        self._failures = 0
+        self._opened_at: Optional[float] = None
+
+    @property
+    def state(self) -> str:
+        if self._opened_at is None:
+            return "closed"
+        if self._clock() - self._opened_at >= self.cooldown_s:
+            return "half_open"
+        return "open"
+
+    def __call__(self, messages: List[Dict[str, str]]) -> Tuple[str, int]:
+        state = self.state
+        if state == "open":
+            raise CircuitOpenError(
+                f"circuit open after {self._failures} consecutive failures; "
+                f"retry after the cooldown ({self.cooldown_s:.0f}s)"
+            )
+        try:
+            result = self.backend(messages)
+        except (RateLimitHit, BackendError) as exc:
+            if isinstance(exc, BackendError) and not exc.retriable:
+                raise               # request problem: never trips the breaker
+            self._failures += 1
+            if state == "half_open" or self._failures >= self.failure_threshold:
+                self._opened_at = self._clock()   # (re)open, cooldown restarts
+            raise
+        self._failures = 0
+        self._opened_at = None      # any success closes the circuit
+        return result