agentpause 0.2.0__tar.gz → 0.2.1__tar.gz

{agentpause-0.2.0/src/agentpause.egg-info → agentpause-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpause
-Version: 0.2.0
+Version: 0.2.1
 Summary: Predictive scheduling for autonomous LLM agents: suspend gracefully before rate limits, resume without losing work.
 Author: Andrea Lelio Ciampolillo
 License: MIT
@@ -40,6 +40,21 @@ plugin for self-hosted runtimes (llama.cpp, vLLM).
 | End-to-end A/B (thinking models, 4B/8B) | recovery **54×–93× faster**; total task time −19% |
 
 Reproduce them yourself with a free key: `python scripts/benchmark_groq.py`.
+Live run (2026-07-08, Groq free tier, 12 steps, ~1k-token context,
+refill-aware waiting enabled):
+
+|  | reactive baseline | agentpause |
+|---|---|---|
+| 429 errors suffered | 7 | **0** |
+| steps redone | 7 | **0** |
+| tokens re-sent (waste) | 12,520 | **0** |
+| wall-clock | 79 s | 145 s* |
+
+\* zero waste costs some waiting. Refill-aware math already cuts most waits
+from ~50 s to ~10 s; the residue is a benchmark artifact (condition B starts
+right after A has drained the shared TPM window) plus the safety cap when a
+late-task call needs nearly the whole bucket. Waste is money on paid tiers —
+waiting is free.
 
 > Status: **early alpha (0.1)**. Core components, the high-level
 > `PredictiveScheduler` API, the LiteLLM adapter (any provider), the LangGraph

{agentpause-0.2.0 → agentpause-0.2.1}/README.md

@@ -17,6 +17,21 @@ plugin for self-hosted runtimes (llama.cpp, vLLM).
 | End-to-end A/B (thinking models, 4B/8B) | recovery **54×–93× faster**; total task time −19% |
 
 Reproduce them yourself with a free key: `python scripts/benchmark_groq.py`.
+Live run (2026-07-08, Groq free tier, 12 steps, ~1k-token context,
+refill-aware waiting enabled):
+
+|  | reactive baseline | agentpause |
+|---|---|---|
+| 429 errors suffered | 7 | **0** |
+| steps redone | 7 | **0** |
+| tokens re-sent (waste) | 12,520 | **0** |
+| wall-clock | 79 s | 145 s* |
+
+\* zero waste costs some waiting. Refill-aware math already cuts most waits
+from ~50 s to ~10 s; the residue is a benchmark artifact (condition B starts
+right after A has drained the shared TPM window) plus the safety cap when a
+late-task call needs nearly the whole bucket. Waste is money on paid tiers —
+waiting is free.
 
 > Status: **early alpha (0.1)**. Core components, the high-level
 > `PredictiveScheduler` API, the LiteLLM adapter (any provider), the LangGraph

{agentpause-0.2.0 → agentpause-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentpause"
-version = "0.2.0"
+version = "0.2.1"
 description = "Predictive scheduling for autonomous LLM agents: suspend gracefully before rate limits, resume without losing work."
 readme = "README.md"
 requires-python = ">=3.9"

{agentpause-0.2.0 → agentpause-0.2.1}/src/agentpause/__init__.py

@@ -15,12 +15,13 @@ from .errors import (
 from .breaker import CircuitBreaker, CircuitOpenError
 from .estimator import Estimator
 from .fallback import FallbackBackend
+from .refill import RegimeDetector
 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"
+__version__ = "0.2.1"
 
 __all__ = [
     "PredictiveScheduler",
@@ -37,6 +38,7 @@ __all__ = [
     "FallbackBackend",
     "CircuitBreaker",
     "CircuitOpenError",
+    "RegimeDetector",
     "AgentPauseError",
     "RateLimitHit",
     "TelemetryError",

{agentpause-0.2.0 → agentpause-0.2.1}/src/agentpause/adapters/langgraph.py

@@ -97,6 +97,7 @@ class AgentPauseGuard:
         wait_threshold_s: float = 15.0,
         sleep_fn: Callable[[float], None] = time.sleep,
         async_sleep_fn: Optional[Callable[[float], Any]] = None,
+        chunk_s: float = 10.0,
         max_resumes: int = 100,
     ) -> None:
         self.telemetry = telemetry
@@ -107,6 +108,7 @@ class AgentPauseGuard:
         self.wait_threshold_s = wait_threshold_s
         self.sleep_fn = sleep_fn
         self.async_sleep_fn = async_sleep_fn
+        self.chunk_s = chunk_s
         self.max_resumes = max_resumes
 
     # -- internals -----------------------------------------------------------
@@ -144,8 +146,11 @@ class AgentPauseGuard:
             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)
+                # reset is imminent: sleeping beats a suspend/resume cycle.
+                # Sleep in chunks and re-read: if the bucket refills sooner,
+                # resume sooner (and the samples feed regime detection).
+                wait_s = d.wait_seconds or budget.reset_seconds or 1.0
+                self.sleep_fn(min(wait_s, self.chunk_s) + 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.
@@ -177,7 +182,8 @@ class AgentPauseGuard:
             if d.action == "continue":
                 return
             if d.action == "wait":
-                delay = (budget.reset_seconds or 1.0) + 0.5
+                wait_s = d.wait_seconds or budget.reset_seconds or 1.0
+                delay = min(wait_s, self.chunk_s) + 0.5
                 if self.async_sleep_fn is not None:
                     await self.async_sleep_fn(delay)
                 else:

{agentpause-0.2.0 → agentpause-0.2.1}/src/agentpause/adapters/litellm.py

@@ -71,11 +71,23 @@ _INSTALL_HINT = ("The LiteLLM adapter needs the 'litellm' package. "
                  "Install it with:  pip install agentpause[litellm]")
 
 
+def _enable_headers() -> None:
+    """Ask litellm to surface provider response headers.
+
+    Without this flag litellm does NOT populate
+    ``_hidden_params["additional_headers"]`` — telemetry would be blind.
+    (Found in the field on the very first real-provider run.)
+    """
+    import litellm
+    litellm.return_response_headers = True
+
+
 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
+    _enable_headers()
     return completion
 
 
@@ -84,6 +96,7 @@ def _default_acompletion() -> Callable[..., Any]:
         from litellm import acompletion
     except ImportError as exc:  # pragma: no cover - depends on environment
         raise ImportError(_INSTALL_HINT) from exc
+    _enable_headers()
     return acompletion
 
 

agentpause-0.2.1/src/agentpause/adapters/openai_compat.py

@@ -0,0 +1,206 @@
+"""Direct adapter for OpenAI-compatible providers (Groq, OpenAI, ...).
+
+Reads rate-limit headers straight from the HTTP response — no middle layer.
+Born in the field: litellm currently drops provider response headers
+(BerriAI/litellm#11749), which blinds telemetry. This adapter talks to the
+provider's ``/chat/completions`` endpoint directly, so the headers the
+scheduler needs are always there.
+
+    from agentpause.adapters.openai_compat import OpenAICompatAdapter
+
+    adapter = OpenAICompatAdapter.for_model("groq/llama-3.1-8b-instant")
+    sched = PredictiveScheduler(backend=adapter.backend,
+                                telemetry=adapter.budget,
+                                count_tokens=adapter.count_tokens)
+
+Works with any provider exposing the OpenAI chat API: pass ``base_url`` and
+the env var holding the key, or use :meth:`for_model` for known prefixes.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from ..errors import BackendError, RateLimitHit, TelemetryError
+from ..refill import RegimeDetector
+from ..risk import Budget
+from .litellm import _parse_reset
+
+__all__ = ["OpenAICompatAdapter"]
+
+KNOWN_PROVIDERS = {
+    "groq": ("https://api.groq.com/openai/v1", "GROQ_API_KEY"),
+    "openai": ("https://api.openai.com/v1", "OPENAI_API_KEY"),
+}
+
+
+def _default_post(url: str, headers: Dict[str, str], payload: Dict[str, Any]):
+    """Perform the HTTP POST; returns (status, response_headers, json_body)."""
+    import httpx
+    r = httpx.post(url, headers=headers, json=payload, timeout=120.0)
+    try:
+        body = r.json()
+    except Exception:
+        body = {}
+    return r.status_code, dict(r.headers), body
+
+
+class OpenAICompatAdapter:
+    """Backend + telemetry via the provider's raw HTTP API.
+
+    Args:
+        model: model name as the PROVIDER knows it (e.g. ``llama-3.1-8b-instant``).
+        base_url: API root, e.g. ``https://api.groq.com/openai/v1``.
+        api_key: literal key, or None to read it from ``api_key_env``.
+        api_key_env: environment variable holding the key.
+        post_fn: transport, injectable for tests:
+            ``(url, headers, payload) -> (status, headers, json)``.
+        fallback_remaining / max_age_s / clock: as in the LiteLLM adapter.
+        **request_kwargs: extra payload fields sent on every call.
+    """
+
+    def __init__(
+        self,
+        model: str,
+        base_url: str,
+        api_key: Optional[str] = None,
+        api_key_env: str = "OPENAI_API_KEY",
+        post_fn: Optional[Callable[..., Tuple[int, Dict[str, str], Dict[str, Any]]]] = None,
+        fallback_remaining: Optional[int] = None,
+        max_age_s: float = 10.0,
+        clock: Callable[[], float] = time.monotonic,
+        **request_kwargs: Any,
+    ) -> None:
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        key = api_key if api_key is not None else os.environ.get(api_key_env)
+        if not key:
+            raise TelemetryError(f"No API key: set {api_key_env} or pass api_key=...")
+        self._auth = {"Authorization": f"Bearer {key}",
+                      "Content-Type": "application/json"}
+        self._post = post_fn if post_fn is not None else _default_post
+        self.fallback_remaining = fallback_remaining
+        self.max_age_s = max_age_s
+        self._clock = clock
+        self.request_kwargs = request_kwargs
+        self._budget: Optional[Budget] = None
+        self._read_at: Optional[float] = None
+        # D8: refill-regime detection from ping-to-ping samples
+        self.detector = RegimeDetector()
+        self._prev_ping: Optional[Tuple[float, int, float]] = None
+
+    @classmethod
+    def for_model(cls, model: str, **kwargs: Any) -> "OpenAICompatAdapter":
+        """Build from a prefixed model string: ``groq/...``, ``openai/...``,
+        or a bare OpenAI model name like ``gpt-4o-mini``."""
+        prefix, _, rest = model.partition("/")
+        if rest and prefix in KNOWN_PROVIDERS:
+            base_url, env = KNOWN_PROVIDERS[prefix]
+            return cls(rest, base_url=base_url, api_key_env=env, **kwargs)
+        base_url, env = KNOWN_PROVIDERS["openai"]
+        return cls(model, base_url=base_url, api_key_env=env, **kwargs)
+
+    # -- the callables the scheduler wants -------------------------------------
+
+    def backend(self, messages: List[Dict[str, str]]) -> Tuple[str, int]:
+        body = self._call(messages, **self.request_kwargs)
+        self._prev_ping = None      # a real call breaks the sampling chain
+        reply = (body.get("choices") or [{}])[0].get("message", {}).get("content") or ""
+        used = int(body.get("usage", {}).get("total_tokens") or 0)
+        return reply, used
+
+    def telemetry(self) -> int:
+        return self.budget().remaining_tokens
+
+    def budget(self) -> Budget:
+        if not self._is_fresh():
+            self.ping()
+        if self._budget is not None:
+            regime = self.detector.regime
+            if regime != "unknown":
+                self._budget.refill_regime = regime
+            return self._budget
+        if self.fallback_remaining is not None:
+            return Budget(remaining_tokens=self.fallback_remaining)
+        raise TelemetryError(
+            "Provider sent no rate-limit headers; set fallback_remaining=... "
+            "to proceed with a fixed assumption."
+        )
+
+    def ping(self) -> None:
+        """1-token call whose only purpose is fresh rate-limit headers.
+
+        Consecutive pings with no real call in between are exactly the
+        no-traffic samples the regime detector needs: it observes whether
+        ``remaining`` rises between them (continuous bucket) or stays flat
+        (fixed window).
+        """
+        prev = self._prev_ping
+        self._call([{"role": "user", "content": "ping"}], max_tokens=1)
+        b, t = self._budget, self._read_at
+        if b is None or t is None:
+            return
+        implied = 0.0
+        if b.limit_tokens is not None and (b.reset_seconds or 0) > 0:
+            implied = (b.limit_tokens - b.remaining_tokens) / b.reset_seconds
+        if prev is not None:
+            self.detector.feed(dt=t - prev[0],
+                               dr=b.remaining_tokens - prev[1],
+                               implied_rate=prev[2])
+        self._prev_ping = (t, b.remaining_tokens, implied)
+
+    def count_tokens(self, text: str) -> int:
+        return max(1, len(text) // 4)
+
+    # -- internals ---------------------------------------------------------------
+
+    def _is_fresh(self) -> bool:
+        return (self._read_at is not None
+                and (self._clock() - self._read_at) <= self.max_age_s)
+
+    def _call(self, messages: List[Dict[str, str]], **extra: Any) -> Dict[str, Any]:
+        status, headers, body = self._post(
+            f"{self.base_url}/chat/completions",
+            self._auth,
+            {"model": self.model, "messages": messages, **extra},
+        )
+        self._absorb(headers)
+        if status == 429:
+            ra = headers.get("retry-after")
+            raise RateLimitHit(retry_after=float(ra) if ra else None)
+        if 500 <= status <= 599:
+            raise BackendError(f"provider returned {status}", retriable=True)
+        if status >= 400:
+            raise BackendError(f"provider returned {status}: {str(body)[:200]}")
+        return body
+
+    def _absorb(self, headers: Dict[str, str]) -> None:
+        h = {str(k).lower(): v for k, v in headers.items()}
+
+        def grab(*names: str) -> Optional[str]:
+            for n in names:
+                if n in h:
+                    return h[n]
+            return None
+
+        tokens = grab("x-ratelimit-remaining-tokens",
+                      "anthropic-ratelimit-tokens-remaining")
+        if tokens is None:
+            return                      # no telemetry in this response
+        limit = grab("x-ratelimit-limit-tokens", "anthropic-ratelimit-tokens-limit")
+        reset = grab("x-ratelimit-reset-tokens", "anthropic-ratelimit-tokens-reset")
+        requests_ = grab("x-ratelimit-remaining-requests",
+                         "anthropic-ratelimit-requests-remaining")
+        in_ = grab("anthropic-ratelimit-input-tokens-remaining")
+        out = grab("anthropic-ratelimit-output-tokens-remaining")
+        self._budget = Budget(
+            remaining_tokens=int(float(tokens)),
+            remaining_requests=int(float(requests_)) if requests_ is not None else None,
+            reset_seconds=_parse_reset(reset) if reset is not None else None,
+            remaining_input_tokens=int(float(in_)) if in_ is not None else None,
+            remaining_output_tokens=int(float(out)) if out is not None else None,
+            limit_tokens=int(float(limit)) if limit is not None else None,
+        )
+        self._read_at = self._clock()

{agentpause-0.2.0 → agentpause-0.2.1}/src/agentpause/estimator.py

@@ -62,12 +62,17 @@ class Estimator:
         return max(self.min_estimate, self.base_estimate(input_tokens) + self.epsilon())
 
     def sigma(self, fallback_estimate: int) -> float:
-        """Std. dev. of realized consumption.
+        """Std. dev. of the estimation RESIDUALS (realized − base estimate).
+
+        Raw consumption trends upward as the context grows; measuring its
+        spread would mistake systematic growth for uncertainty and inflate
+        the safety margin (and the waits) enormously. The residuals absorb
+        the trend, so their spread is the honest uncertainty of the estimate.
 
         Falls back to a fraction of the current estimate until enough samples
         exist (< 4), so early decisions stay prudent.
         """
-        h = self._realized
+        h = self._all_errors
         if len(h) >= 4:
             mean = sum(h) / len(h)
             return (sum((x - mean) ** 2 for x in h) / len(h)) ** 0.5

agentpause-0.2.1/src/agentpause/refill.py

@@ -0,0 +1,75 @@
+"""Online detection of the provider's refill regime (D8).
+
+Two refill physics exist behind rate limits:
+
+* **continuous token bucket** — tokens trickle back at a steady rate
+  (Groq, OpenAI): refill-aware waits are exact;
+* **fixed window** — nothing returns until a boundary instant, then the
+  whole budget at once: the only safe wait is the full reset.
+
+Nobody documents which one a provider uses, but it can be *measured*:
+take two telemetry readings with no real call in between and look at the
+slope of ``remaining``. Rising at roughly the header-implied rate →
+continuous. Flat (or nibbled slightly by the pings themselves) → fixed.
+
+The detector votes on each valid sample pair and reports the majority of
+the recent votes; with insufficient evidence it says ``unknown``, and the
+caller stays conservative (full-reset waits).
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Deque
+
+__all__ = ["RegimeDetector"]
+
+
+class RegimeDetector:
+    """Classify the refill regime from (Δt, Δremaining) observations.
+
+    Args:
+        min_gap_s: sample pairs closer than this are noise and are ignored.
+        window: how many recent votes participate in the majority.
+        min_votes: evidence required before leaving ``unknown``.
+    """
+
+    CONTINUOUS_RATIO = 0.5   # observed/implied rate above this → continuous
+    FIXED_RATIO = 0.1        # below this → fixed window
+
+    def __init__(self, min_gap_s: float = 2.0, window: int = 3,
+                 min_votes: int = 2) -> None:
+        self.min_gap_s = min_gap_s
+        self.min_votes = min_votes
+        self._votes: Deque[str] = deque(maxlen=window)
+
+    def feed(self, dt: float, dr: float, implied_rate: float) -> None:
+        """Record one observation.
+
+        Args:
+            dt: seconds between the two readings (no real call in between).
+            dr: change in remaining tokens over that gap.
+            implied_rate: ``(limit - remaining) / reset_seconds`` at the
+                first reading — what a continuous bucket would refill at.
+        """
+        if dt < self.min_gap_s or implied_rate <= 0:
+            return
+        ratio = (dr / dt) / implied_rate
+        if ratio >= self.CONTINUOUS_RATIO:
+            self._votes.append("continuous")
+        elif ratio <= self.FIXED_RATIO:
+            self._votes.append("fixed")
+        # ambiguous ratios cast no vote
+
+    @property
+    def regime(self) -> str:
+        """``"continuous"``, ``"fixed"``, or ``"unknown"`` (be conservative)."""
+        if len(self._votes) < self.min_votes:
+            return "unknown"
+        cont = sum(1 for v in self._votes if v == "continuous")
+        fixed = len(self._votes) - cont
+        if cont > fixed:
+            return "continuous"
+        if fixed > cont:
+            return "fixed"
+        return "unknown"

{agentpause-0.2.0 → agentpause-0.2.1}/src/agentpause/risk.py

@@ -52,6 +52,12 @@ class Budget:
             input and output separately (Anthropic does).
         remaining_output_tokens: output-token budget, if reported separately —
             a reasoning-heavy agent can drain this while input budget abounds.
+        limit_tokens: the bucket capacity (TPM limit). Together with
+            ``reset_seconds`` it yields the refill rate, enabling
+            refill-aware waits.
+        refill_regime: ``"continuous"`` / ``"fixed"`` / None, as measured by
+            :class:`~agentpause.refill.RegimeDetector`. Fixed-window providers
+            get full-reset waits regardless of the refill math.
     """
 
     remaining_tokens: int
@@ -59,6 +65,8 @@ class Budget:
     reset_seconds: Optional[float] = None
     remaining_input_tokens: Optional[int] = None
     remaining_output_tokens: Optional[int] = None
+    limit_tokens: Optional[int] = None
+    refill_regime: Optional[str] = None
 
 
 @dataclass
@@ -69,6 +77,38 @@ class Decision:
     budget: Budget
     estimated: int
     sigma: float
+    wait_seconds: Optional[float] = None   # suggested wait, when action == "wait"
+
+
+_WAIT_BUFFER = 1.15     # wait 15% longer than the bare refill math suggests
+
+
+def _refill_wait(budget: Budget, needed: float) -> Optional[float]:
+    """Seconds until the bucket holds ``needed`` tokens, from headers alone.
+
+    Token buckets refill continuously; the refill rate falls out of the
+    headers with no extra assumptions:
+
+        rate = (limit - remaining) / reset_seconds
+
+    so the wait for a deficit is ``deficit / rate`` (buffered, and capped at
+    the full reset — never wait longer than a guaranteed-full bucket).
+    Returns None when the headers don't allow the math.
+    """
+    if budget.reset_seconds is None:
+        return None
+    if budget.refill_regime == "fixed":
+        return budget.reset_seconds      # nothing trickles back: wait it out
+    if budget.limit_tokens is None or budget.reset_seconds <= 0:
+        return budget.reset_seconds
+    missing = budget.limit_tokens - budget.remaining_tokens
+    if missing <= 0:
+        return budget.reset_seconds
+    rate = missing / budget.reset_seconds
+    deficit = needed - budget.remaining_tokens
+    if deficit <= 0:
+        return 0.5
+    return min(budget.reset_seconds, deficit / rate * _WAIT_BUFFER)
 
 
 def decide(
@@ -100,12 +140,21 @@ def decide(
     output_fit = (budget.remaining_output_tokens is None or estimated_output is None
                   or estimated_output <= budget.remaining_output_tokens)
     if tokens_fit and requests_fit and input_fit and output_fit:
-        action = "continue"
-    elif budget.reset_seconds is not None and budget.reset_seconds <= wait_threshold_s:
-        action = "wait"
-    else:
-        action = "checkpoint"
-    return Decision(action=action, budget=budget, estimated=estimated, sigma=sigma)
+        return Decision("continue", budget, estimated, sigma)
+    # compute the ACTUAL wait needed, then compare THAT to the threshold:
+    # a bucket full in 50s may hold enough for the next call after 10s
+    wait_s: Optional[float] = None
+    if budget.reset_seconds is not None:
+        if not tokens_fit and requests_fit and input_fit and output_fit:
+            # pure token deficit: wait only until the bucket refills enough
+            wait_s = _refill_wait(budget, needed=estimated + k * sigma)
+        else:
+            # requests or split dimensions exhausted: refill rate unknown,
+            # stay conservative and wait out the full reset
+            wait_s = budget.reset_seconds
+    if wait_s is not None and wait_s <= wait_threshold_s:
+        return Decision("wait", budget, estimated, sigma, wait_seconds=wait_s)
+    return Decision("checkpoint", budget, estimated, sigma)
 
 
 @dataclass

{agentpause-0.2.0 → agentpause-0.2.1/src/agentpause.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpause
-Version: 0.2.0
+Version: 0.2.1
 Summary: Predictive scheduling for autonomous LLM agents: suspend gracefully before rate limits, resume without losing work.
 Author: Andrea Lelio Ciampolillo
 License: MIT
@@ -40,6 +40,21 @@ plugin for self-hosted runtimes (llama.cpp, vLLM).
 | End-to-end A/B (thinking models, 4B/8B) | recovery **54×–93× faster**; total task time −19% |
 
 Reproduce them yourself with a free key: `python scripts/benchmark_groq.py`.
+Live run (2026-07-08, Groq free tier, 12 steps, ~1k-token context,
+refill-aware waiting enabled):
+
+|  | reactive baseline | agentpause |
+|---|---|---|
+| 429 errors suffered | 7 | **0** |
+| steps redone | 7 | **0** |
+| tokens re-sent (waste) | 12,520 | **0** |
+| wall-clock | 79 s | 145 s* |
+
+\* zero waste costs some waiting. Refill-aware math already cuts most waits
+from ~50 s to ~10 s; the residue is a benchmark artifact (condition B starts
+right after A has drained the shared TPM window) plus the safety cap when a
+late-task call needs nearly the whole bucket. Waste is money on paid tiers —
+waiting is free.
 
 > Status: **early alpha (0.1)**. Core components, the high-level
 > `PredictiveScheduler` API, the LiteLLM adapter (any provider), the LangGraph

{agentpause-0.2.0 → agentpause-0.2.1}/src/agentpause.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/agentpause/breaker.py
 src/agentpause/errors.py
 src/agentpause/estimator.py
 src/agentpause/fallback.py
+src/agentpause/refill.py
 src/agentpause/retry.py
 src/agentpause/risk.py
 src/agentpause/scheduler.py
@@ -18,6 +19,7 @@ src/agentpause.egg-info/top_level.txt
 src/agentpause/adapters/__init__.py
 src/agentpause/adapters/langgraph.py
 src/agentpause/adapters/litellm.py
+src/agentpause/adapters/openai_compat.py
 tests/test_async.py
 tests/test_breaker.py
 tests/test_estimator.py
@@ -26,7 +28,10 @@ tests/test_io_tpm.py
 tests/test_langgraph_adapter.py
 tests/test_litellm_adapter.py
 tests/test_money_and_hooks.py
+tests/test_openai_compat.py
 tests/test_quantile.py
+tests/test_refill_wait.py
+tests/test_regime.py
 tests/test_risk.py
 tests/test_robustness.py
 tests/test_scheduler.py

agentpause-0.2.1/tests/test_openai_compat.py

@@ -0,0 +1,98 @@
+"""Behavioral contract for the direct OpenAI-compatible adapter.
+
+Exists because litellm currently drops provider response headers
+(BerriAI/litellm#11749): telemetry must not depend on a middle layer.
+All tests inject a fake transport — offline, no keys.
+"""
+
+import pytest
+
+from agentpause import BackendError, PredictiveScheduler, RateLimitHit, StateStore
+from agentpause.adapters.openai_compat import OpenAICompatAdapter
+
+HEADERS = {
+    "x-ratelimit-remaining-tokens": "5000",
+    "x-ratelimit-remaining-requests": "12",
+    "x-ratelimit-reset-tokens": "7.66s",
+}
+BODY = {"choices": [{"message": {"content": "hello"}}], "usage": {"total_tokens": 42}}
+
+
+class FakePost:
+    def __init__(self, status=200, headers=None, body=None):
+        self.status, self.headers = status, HEADERS if headers is None else headers
+        self.body = BODY if body is None else body
+        self.calls = []
+
+    def __call__(self, url, headers, payload):
+        self.calls.append((url, payload))
+        return self.status, self.headers, self.body
+
+
+def make_adapter(post, **kw):
+    return OpenAICompatAdapter("m", base_url="https://api.example.com/v1",
+                               api_key="k", post_fn=post, **kw)
+
+
+def test_backend_returns_reply_and_tokens():
+    post = FakePost()
+    a = make_adapter(post)
+    assert a.backend([{"role": "user", "content": "hi"}]) == ("hello", 42)
+    url, payload = post.calls[0]
+    assert url.endswith("/chat/completions")
+    assert payload["model"] == "m"
+
+
+def test_budget_parsed_from_real_http_headers():
+    a = make_adapter(FakePost())
+    b = a.budget()                       # pings once
+    assert b.remaining_tokens == 5000
+    assert b.remaining_requests == 12
+    assert b.reset_seconds == pytest.approx(7.66)
+
+
+def test_backend_refreshes_budget_no_extra_ping():
+    post = FakePost()
+    a = make_adapter(post)
+    a.backend([{"role": "user", "content": "hi"}])
+    assert a.telemetry() == 5000
+    assert len(post.calls) == 1
+
+
+def test_429_maps_to_rate_limit_hit():
+    post = FakePost(status=429, headers=dict(HEADERS, **{"retry-after": "9"}))
+    a = make_adapter(post)
+    with pytest.raises(RateLimitHit) as exc:
+        a.backend([{"role": "user", "content": "hi"}])
+    assert exc.value.retry_after == 9.0
+
+
+def test_5xx_is_retriable_4xx_is_not():
+    a = make_adapter(FakePost(status=503))
+    with pytest.raises(BackendError) as exc:
+        a.backend([])
+    assert exc.value.retriable is True
+    a = make_adapter(FakePost(status=400))
+    with pytest.raises(BackendError) as exc:
+        a.backend([])
+    assert exc.value.retriable is False
+
+
+def test_for_model_maps_known_prefixes(monkeypatch):
+    monkeypatch.setenv("GROQ_API_KEY", "k1")
+    monkeypatch.setenv("OPENAI_API_KEY", "k2")
+    g = OpenAICompatAdapter.for_model("groq/llama-3.1-8b-instant")
+    assert g.base_url == "https://api.groq.com/openai/v1"
+    assert g.model == "llama-3.1-8b-instant"
+    o = OpenAICompatAdapter.for_model("gpt-4o-mini")
+    assert o.base_url == "https://api.openai.com/v1"
+
+
+def test_scheduler_integration(tmp_path):
+    a = make_adapter(FakePost())
+    sched = PredictiveScheduler(backend=a.backend, telemetry=a.budget,
+                                store=StateStore(str(tmp_path)))
+    with sched.session("t") as s:
+        s.add_user("q")
+        assert s.next_action().action == "continue"
+        assert s.call() == "hello"

agentpause-0.2.1/tests/test_refill_wait.py

@@ -0,0 +1,77 @@
+"""Behavioral contract for D7: refill-aware waiting.
+
+Providers with token-bucket limits refill CONTINUOUSLY: waiting for the full
+window reset is wasteful. From the headers alone we can derive the refill
+rate — (limit - remaining) / reset_seconds — and wait only until the bucket
+holds enough for the NEXT call (plus a safety buffer).
+
+Live-benchmark motivation (2026-07-08, Groq): full-reset waits cost 162s
+wall-clock vs 78s for the reactive baseline; refill-aware waits close the gap.
+"""
+
+import pytest
+
+from agentpause import Budget, decide
+
+
+def test_wait_is_proportional_to_the_deficit():
+    # bucket: 6000 cap, 1000 left, full in 50s → refill rate 100 tok/s
+    b = Budget(remaining_tokens=1000, reset_seconds=50.0, limit_tokens=6000)
+    # need 2000 (estimated+k·sigma≈2000) → deficit 1000 → 10s × 1.15 buffer
+    d = decide(b, estimated=1800, sigma=100.0, k=2.0)
+    assert d.action == "wait"
+    assert d.wait_seconds == pytest.approx((2000 - 1000) / 100.0 * 1.15)
+
+
+def test_wait_never_exceeds_full_reset():
+    b = Budget(remaining_tokens=0, reset_seconds=50.0, limit_tokens=6000)
+    d = decide(b, estimated=1_000_000, sigma=0.0,   # absurd need
+               wait_threshold_s=60.0)               # generous threshold
+    assert d.action == "wait"
+    assert d.wait_seconds == 50.0                   # capped at the reset
+
+
+def test_long_effective_wait_still_checkpoints():
+    """Refill math says 48s but the threshold is 15s → suspend, don't idle."""
+    b = Budget(remaining_tokens=0, reset_seconds=50.0, limit_tokens=6000)
+    d = decide(b, estimated=5000, sigma=0.0, wait_threshold_s=15.0)
+    assert d.action == "checkpoint"
+
+
+def test_short_effective_wait_beats_a_long_reset():
+    """The 2026-07-08 benchmark case: full reset 50s, but the next call only
+    needs ~10s of refill — with refill-aware math we wait instead of idling."""
+    b = Budget(remaining_tokens=1000, reset_seconds=50.0, limit_tokens=6000)
+    d = decide(b, estimated=1800, sigma=100.0, k=2.0, wait_threshold_s=15.0)
+    assert d.action == "wait"
+    assert d.wait_seconds < 15.0
+
+
+def test_without_limit_header_falls_back_to_full_reset():
+    b = Budget(remaining_tokens=100, reset_seconds=8.0)
+    d = decide(b, estimated=1000, sigma=100.0)
+    assert d.action == "wait"
+    assert d.wait_seconds == 8.0
+
+
+def test_exhausted_requests_wait_the_full_reset():
+    """RPM refill rate is unknown: stay conservative on that dimension."""
+    b = Budget(remaining_tokens=100_000, remaining_requests=0,
+               reset_seconds=8.0, limit_tokens=200_000)
+    d = decide(b, estimated=100, sigma=10.0)
+    assert d.action == "wait"
+    assert d.wait_seconds == 8.0
+
+
+def test_continue_carries_no_wait():
+    b = Budget(remaining_tokens=100_000, limit_tokens=200_000, reset_seconds=30.0)
+    d = decide(b, estimated=100, sigma=10.0)
+    assert d.action == "continue"
+    assert d.wait_seconds is None
+
+
+def test_checkpoint_carries_no_wait():
+    b = Budget(remaining_tokens=10, reset_seconds=300.0, limit_tokens=6000)
+    d = decide(b, estimated=1000, sigma=100.0, wait_threshold_s=15.0)
+    assert d.action == "checkpoint"
+    assert d.wait_seconds is None

agentpause-0.2.1/tests/test_regime.py

@@ -0,0 +1,98 @@
+"""Behavioral contract for D8: online refill-regime detection + chunked waits.
+
+Two refill physics exist in the wild:
+* continuous token bucket (Groq, OpenAI): tokens trickle back — refill-aware
+  waits are exact;
+* fixed window: nothing refills until a boundary instant, then everything —
+  refill math would under-wait there.
+
+The detector classifies the regime from observation alone: consecutive
+telemetry readings with no real call in between. Rising remaining ≈ implied
+rate → continuous; flat → fixed; not enough data → unknown (conservative).
+Chunked waiting supplies those samples for free while ALSO letting the agent
+resume as soon as the bucket actually holds enough.
+"""
+
+import pytest
+
+from agentpause import Budget, decide
+from agentpause.adapters.langgraph import AgentPauseGuard
+from agentpause.refill import RegimeDetector
+
+
+# -- the detector ---------------------------------------------------------------
+
+def test_unknown_until_enough_votes():
+    d = RegimeDetector()
+    assert d.regime == "unknown"
+    d.feed(dt=10.0, dr=1000, implied_rate=100.0)   # one vote is not enough
+    assert d.regime == "unknown"
+
+
+def test_rising_remaining_means_continuous():
+    d = RegimeDetector()
+    d.feed(dt=10.0, dr=950, implied_rate=100.0)    # ~95% of implied rate
+    d.feed(dt=10.0, dr=1020, implied_rate=100.0)
+    assert d.regime == "continuous"
+
+
+def test_flat_remaining_means_fixed_window():
+    d = RegimeDetector()
+    d.feed(dt=10.0, dr=0, implied_rate=100.0)
+    d.feed(dt=10.0, dr=-11, implied_rate=100.0)    # pings nibble a few tokens
+    assert d.regime == "fixed"
+
+
+def test_short_gaps_and_zero_rates_are_ignored():
+    d = RegimeDetector(min_gap_s=2.0)
+    d.feed(dt=0.5, dr=500, implied_rate=100.0)     # gap too short: noise
+    d.feed(dt=10.0, dr=500, implied_rate=0.0)      # no implied rate: unusable
+    assert d.regime == "unknown"
+
+
+def test_ambiguous_ratios_do_not_vote():
+    d = RegimeDetector()
+    d.feed(dt=10.0, dr=300, implied_rate=100.0)    # 30%: neither clearly
+    d.feed(dt=10.0, dr=300, implied_rate=100.0)
+    assert d.regime == "unknown"
+
+
+# -- regime drives the wait math ---------------------------------------------------
+
+def test_fixed_regime_waits_the_full_reset():
+    """Same numbers that would give a ~10s refill wait — but the provider is
+    fixed-window, so the only safe wait is the full reset."""
+    b = Budget(remaining_tokens=1000, reset_seconds=12.0, limit_tokens=6000,
+               refill_regime="fixed")
+    d = decide(b, estimated=1800, sigma=100.0, k=2.0, wait_threshold_s=15.0)
+    assert d.action == "wait"
+    assert d.wait_seconds == 12.0
+
+
+def test_continuous_regime_keeps_refill_math():
+    b = Budget(remaining_tokens=1000, reset_seconds=50.0, limit_tokens=6000,
+               refill_regime="continuous")
+    d = decide(b, estimated=1800, sigma=100.0, k=2.0)
+    assert d.action == "wait"
+    assert d.wait_seconds == pytest.approx(1000 / 100.0 * 1.15)
+
+
+# -- chunked waiting in the guard ----------------------------------------------------
+
+def test_guard_sleeps_in_chunks_and_resumes_early():
+    """A 40s computed wait must not be one blind sleep: cap at chunk_s and
+    re-read — if the bucket refills sooner, the agent resumes sooner."""
+    budget = Budget(remaining_tokens=0, reset_seconds=14.0, limit_tokens=200_000)
+    sleeps = []
+
+    def fake_sleep(s):
+        sleeps.append(s)
+        if len(sleeps) == 2:                 # refilled after ~2 chunks
+            budget.remaining_tokens = 150_000
+
+    guard = AgentPauseGuard(telemetry=lambda: budget,
+                            interrupt_fn=lambda p: None,
+                            sleep_fn=fake_sleep, chunk_s=5.0)
+    guard.check([{"role": "user", "content": "q " * 50}])
+    assert len(sleeps) == 2                  # resumed at the SECOND re-read
+    assert all(s <= 5.5 for s in sleeps)     # never a blind long sleep