agentpause 0.2.0__py3-none-any.whl

agentpause/scheduler.py

@@ -0,0 +1,336 @@
+"""The high-level, provider-agnostic scheduler API.
+
+This is the piece users actually touch. It ties the pure components
+(:class:`~agentpause.estimator.Estimator`, the risk rule,
+:class:`~agentpause.state.StateStore`) into a small workflow:
+
+    sched = PredictiveScheduler(backend=..., telemetry=...)
+    with sched.session("task-1") as s:      # resumes automatically if a checkpoint exists
+        for question in questions[s.step:]:  # skip steps already done before a suspend
+            s.add_user(question)
+            if s.should_suspend():           # predictive check, before the call
+                s.checkpoint()
+                break
+            reply = s.call()                 # perform the LLM call, record consumption
+        else:
+            s.complete()                     # task finished: drop the checkpoint
+
+``backend`` and ``telemetry`` are injected callables, so the scheduler depends on
+no particular provider. Adapters (LiteLLM, LangGraph, per-provider telemetry)
+supply them; tests supply stubs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .errors import BackendError, RateLimitHit
+from .estimator import Estimator
+from .retry import RetryPolicy
+from .risk import Budget, Decision, decide, should_checkpoint
+from .state import Checkpoint, StateStore
+
+# messages -> (reply_text, tokens_used)
+Backend = Callable[[List[Dict[str, str]]], Tuple[str, int]]
+# async variant: messages -> awaitable (reply_text, tokens_used)
+AsyncBackend = Callable[[List[Dict[str, str]]], "Any"]
+# () -> remaining tokens (int) or a full Budget reading
+Telemetry = Callable[[], "int | Budget"]
+# 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)
+
+
+class Session:
+    """A single resumable agent run, bound to a ``session_id``."""
+
+    def __init__(self, scheduler: "PredictiveScheduler", session_id: str) -> None:
+        self._sched = scheduler
+        self.session_id = session_id
+        cp = scheduler.store.load(session_id)
+        self.resumed = cp is not None and cp.step > 0
+        self._cp = cp if cp is not None else Checkpoint(session_id=session_id)
+
+    # -- read-only view -----------------------------------------------------
+
+    @property
+    def step(self) -> int:
+        return self._cp.step
+
+    @property
+    def messages(self) -> List[Dict[str, str]]:
+        return self._cp.messages
+
+    @property
+    def total_tokens_used(self) -> int:
+        return self._cp.total_tokens_used
+
+    # -- building the conversation -----------------------------------------
+
+    def add_message(self, role: str, content: str) -> None:
+        self._cp.messages.append({"role": role, "content": content})
+
+    def add_user(self, content: str) -> None:
+        self.add_message("user", content)
+
+    def add_system(self, content: str) -> None:
+        self.add_message("system", content)
+
+    # -- the predictive decision -------------------------------------------
+
+    def _input_tokens(self) -> int:
+        return sum(self._sched.count_tokens(m["content"]) for m in self._cp.messages)
+
+    def _read_budget(self) -> Budget:
+        """Read telemetry fresh; accept a plain int (legacy) or a Budget."""
+        raw = self._sched.telemetry()
+        return raw if isinstance(raw, Budget) else Budget(remaining_tokens=int(raw))
+
+    def should_suspend(self) -> bool:
+        """True if the next call would not safely fit the remaining budget.
+
+        Telemetry is read fresh on every call — never from the checkpoint —
+        because a serialized budget value goes stale after a window reset.
+        Considers both the token budget (TPM) and, when reported, the
+        request budget (RPM).
+        """
+        return self.next_action().action != "continue"
+
+    def next_action(self) -> Decision:
+        """The full three-valued decision: ``continue`` / ``wait`` / ``checkpoint``.
+
+        ``wait`` means the budget does not fit but the provider window resets
+        within ``wait_threshold_s`` — sleeping briefly beats a suspend/resume
+        cycle. The returned :class:`Decision` carries the budget reading and
+        the estimate for logging.
+        """
+        budget = self._read_budget()
+        input_tokens = self._input_tokens()
+        estimated = self._sched.estimator.estimate(input_tokens)
+        sigma = self._sched.estimator.sigma(estimated)
+        if self._sched.quantile is not None:
+            upper = self._sched.estimator.upper_estimate(input_tokens, self._sched.quantile)
+            if upper is not None:
+                # the quantile bound already covers the tail: no extra margin
+                estimated, sigma = upper, 0.0
+        d = decide(budget, estimated, sigma,
+                   self._sched.safety_k, self._sched.wait_threshold_s,
+                   estimated_input=input_tokens,
+                   estimated_output=self._sched.estimator.max_tokens)
+        # monetary hard constraint: money does not reset by waiting,
+        # so an overrun always means checkpoint — never wait
+        price = self._sched.price_per_1k_tokens
+        remaining_money = self._sched.money_remaining
+        if price is not None and remaining_money is not None:
+            estimated_cost = estimated / 1000.0 * price
+            if estimated_cost > remaining_money:
+                d = Decision(action="checkpoint", budget=budget,
+                             estimated=estimated, sigma=sigma)
+        self._sched._emit("decision", {
+            "action": d.action, "estimated": estimated,
+            "remaining_tokens": budget.remaining_tokens,
+            "session_id": self.session_id, "step": self.step,
+        })
+        return d
+
+    # -- performing a step --------------------------------------------------
+
+    def call(self) -> str:
+        """Perform the LLM call, record consumption, advance the step.
+
+        An unexpected 429 (:class:`~agentpause.errors.RateLimitHit`) is
+        retried per the scheduler's :class:`~agentpause.retry.RetryPolicy`,
+        and each hit adapts the safety factor upward (the prediction was too
+        optimistic). If retries run out the error propagates — and the session
+        state is left UNTOUCHED, so a checkpoint/resume stays clean.
+        """
+        input_tokens = self._input_tokens()
+        retry = self._sched.retry
+        attempt = 0
+        while True:
+            try:
+                reply, used = self._sched.backend(self._cp.messages)
+                break
+            except RateLimitHit as hit:
+                self._sched._register_rate_limit_hit()
+                if attempt >= retry.max_retries:
+                    raise
+                delay = hit.retry_after if hit.retry_after is not None else retry.delay(attempt)
+                self._sched._emit("retry", {"attempt": attempt + 1, "delay_s": delay})
+                retry.sleep_fn(delay)
+                attempt += 1
+            except BackendError as err:
+                # transient infrastructure failures (5xx) deserve a retry;
+                # request problems (4xx) do not — retrying wastes budget
+                if not err.retriable or attempt >= retry.max_retries:
+                    raise
+                delay = retry.delay(attempt)
+                self._sched._emit("retry", {"attempt": attempt + 1, "delay_s": delay})
+                retry.sleep_fn(delay)
+                attempt += 1
+        # state mutations happen only after a successful call
+        self._record_success(input_tokens, used, reply)
+        return reply
+
+    def _record_success(self, input_tokens: int, used: int, reply: str) -> None:
+        self._sched.estimator.record(input_tokens, used)
+        self._cp.total_tokens_used += used
+        self._cp.step += 1
+        self.add_message("assistant", reply)
+        if self._sched.price_per_1k_tokens is not None:
+            self._sched.money_spent += used / 1000.0 * self._sched.price_per_1k_tokens
+        self._sched._emit("step_completed", {
+            "session_id": self.session_id, "step": self._cp.step,
+            "tokens_used": used, "money_spent": self._sched.money_spent,
+        })
+
+    async def acall(self) -> str:
+        """Async twin of :meth:`call`: same rule, same retry, same guarantees.
+
+        Requires the scheduler to be built with ``async_backend=...``
+        (e.g. ``LiteLLMAdapter(...).abackend``).
+        """
+        if self._sched.async_backend is None:
+            raise RuntimeError(
+                "acall() needs an async backend: "
+                "PredictiveScheduler(..., async_backend=adapter.abackend)"
+            )
+        input_tokens = self._input_tokens()
+        retry = self._sched.retry
+        attempt = 0
+        while True:
+            try:
+                reply, used = await self._sched.async_backend(self._cp.messages)
+                break
+            except RateLimitHit as hit:
+                self._sched._register_rate_limit_hit()
+                if attempt >= retry.max_retries:
+                    raise
+                delay = hit.retry_after if hit.retry_after is not None else retry.delay(attempt)
+                await retry.asleep(delay)
+                attempt += 1
+            except BackendError as err:
+                if not err.retriable or attempt >= retry.max_retries:
+                    raise
+                await retry.asleep(retry.delay(attempt))
+                attempt += 1
+        self._record_success(input_tokens, used, reply)
+        return reply
+
+    # -- persistence --------------------------------------------------------
+
+    def checkpoint(self) -> str:
+        """Serialize the logical state so the run can resume later."""
+        return self._sched.store.save(self._cp)
+
+    def complete(self) -> None:
+        """Mark the task finished and drop its checkpoint."""
+        self._sched.store.clear(self.session_id)
+
+    # -- context manager ----------------------------------------------------
+
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        return False  # never suppress exceptions
+
+
+class PredictiveScheduler:
+    """Factory and configuration holder for :class:`Session` runs.
+
+    Args:
+        backend: callable ``messages -> (reply, tokens_used)`` performing the LLM call.
+        telemetry: callable ``() -> remaining_tokens`` reading the rate-limit window.
+        store: where checkpoints live (defaults to ``.agentpause/`` on disk).
+        estimator: cost estimator (defaults to a fresh :class:`Estimator`).
+        count_tokens: text->token counter (defaults to a ~4 chars/token heuristic).
+        safety_k: safety factor; higher suspends earlier.
+        wait_threshold_s: if the window resets within this many seconds,
+            ``next_action()`` returns ``wait`` instead of ``checkpoint``.
+        retry: how to wait-and-retry on unexpected 429s (see
+            :class:`~agentpause.retry.RetryPolicy`).
+        k_bump: how much ``safety_k`` grows after each unexpected 429 —
+            the hit is feedback that the estimates run optimistic.
+        k_max: ceiling for the adaptive safety factor.
+        price_per_1k_tokens: model price, for the monetary hard constraint.
+        money_budget: spending cap for this scheduler. When the estimated
+            next step would overrun it, the decision is ``checkpoint`` —
+            never ``wait``, because money does not reset with the window.
+        on_event: observability hook ``(event_name, info_dict) -> None``.
+            Events: ``decision``, ``step_completed``, ``rate_limit_hit``,
+            ``retry``. Exceptions inside the hook are swallowed — telemetry
+            must never take down the agent.
+        quantile: when set (e.g. ``0.95``) and enough history exists, the
+            decision uses the empirical q-quantile of past estimation errors
+            instead of the ``k·sigma`` margin — statistically honest with
+            heavy-tailed consumption. Falls back to ``k·sigma`` until
+            8 steps are recorded.
+    """
+
+    def __init__(
+        self,
+        backend: Optional[Backend],
+        telemetry: Telemetry,
+        store: Optional[StateStore] = None,
+        estimator: Optional[Estimator] = None,
+        count_tokens: Optional[TokenCounter] = None,
+        safety_k: float = 2.0,
+        wait_threshold_s: float = 15.0,
+        retry: Optional[RetryPolicy] = None,
+        k_bump: float = 0.25,
+        k_max: float = 4.0,
+        async_backend: Optional[AsyncBackend] = None,
+        price_per_1k_tokens: Optional[float] = None,
+        money_budget: Optional[float] = None,
+        on_event: Optional[Callable[[str, Dict[str, Any]], None]] = None,
+        quantile: Optional[float] = None,
+    ) -> None:
+        if backend is None and async_backend is None:
+            raise ValueError("Provide backend=, async_backend=, or both.")
+        self.backend = backend
+        self.async_backend = async_backend
+        self.telemetry = telemetry
+        self.store = store if store is not None else StateStore()
+        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.wait_threshold_s = wait_threshold_s
+        self.retry = retry if retry is not None else RetryPolicy()
+        self.k_bump = k_bump
+        self.k_max = k_max
+        self.rate_limit_hits = 0
+        self.price_per_1k_tokens = price_per_1k_tokens
+        self.money_budget = money_budget
+        self.money_spent = 0.0
+        self.on_event = on_event
+        self.quantile = quantile
+
+    @property
+    def money_remaining(self) -> Optional[float]:
+        if self.money_budget is None:
+            return None
+        return self.money_budget - self.money_spent
+
+    def _emit(self, name: str, info: Dict[str, Any]) -> None:
+        """Fire the observability hook; never let it break the run."""
+        if self.on_event is not None:
+            try:
+                self.on_event(name, info)
+            except Exception:
+                pass
+
+    def _register_rate_limit_hit(self) -> None:
+        """A 429 slipped through: count it and grow the safety margin."""
+        self.rate_limit_hits += 1
+        self.safety_k = min(self.safety_k + self.k_bump, self.k_max)
+        self._emit("rate_limit_hit", {"total_hits": self.rate_limit_hits,
+                                      "safety_k": self.safety_k})
+
+    def session(self, session_id: str) -> Session:
+        """Start (or resume) a run identified by ``session_id``."""
+        return Session(self, session_id)

agentpause/state.py

@@ -0,0 +1,99 @@
+"""Logical checkpoint store: the source of truth for suspend/resume.
+
+This is the part that works on *any* provider, cloud or local, because it only
+serializes application-level state — messages, step counter, and idempotency
+keys — never model internals. (True KV-cache warm start lives in an optional
+plugin and is not required here.)
+
+Writes are atomic: the manifest is written to a temporary file and renamed, so a
+crash mid-write can never corrupt a previous checkpoint.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+
+from .errors import CheckpointError
+
+
+@dataclass
+class Checkpoint:
+    """A resumable snapshot of an agent session."""
+
+    session_id: str
+    step: int = 0
+    messages: List[Dict[str, str]] = field(default_factory=list)
+    idempotency_keys: List[str] = field(default_factory=list)
+    total_tokens_used: int = 0
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    def new_idempotency_key(self, action: str) -> str:
+        """Register and return a fresh idempotency key for a side-effecting action."""
+        key = f"{action}:{uuid.uuid4().hex[:8]}"
+        self.idempotency_keys.append(key)
+        return key
+
+    def has_run(self, key: str) -> bool:
+        """Whether an action key was already executed before a checkpoint."""
+        return key in self.idempotency_keys
+
+
+class StateStore:
+    """Persists and restores :class:`Checkpoint` objects as JSON files."""
+
+    def __init__(self, directory: str = ".agentpause") -> None:
+        self.directory = directory
+        try:
+            os.makedirs(directory, exist_ok=True)
+        except OSError as exc:
+            raise CheckpointError(
+                f"Cannot create checkpoint directory '{directory}': {exc}"
+            ) from exc
+
+    def _path(self, session_id: str) -> str:
+        safe = session_id.replace(os.sep, "_")
+        return os.path.join(self.directory, f"{safe}.json")
+
+    def save(self, cp: Checkpoint) -> str:
+        """Atomically persist a checkpoint; returns the file path."""
+        path = self._path(cp.session_id)
+        payload = {
+            "checkpoint_id": uuid.uuid4().hex,
+            "created_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+            "state": asdict(cp),
+        }
+        tmp = path + ".tmp"
+        try:
+            with open(tmp, "w", encoding="utf-8") as f:
+                json.dump(payload, f, indent=2, ensure_ascii=False)
+            os.replace(tmp, path)  # atomic on POSIX and Windows
+        except OSError as exc:
+            raise CheckpointError(
+                f"Cannot write checkpoint '{path}': {exc}"
+            ) from exc
+        return path
+
+    def load(self, session_id: str) -> Optional[Checkpoint]:
+        """Restore a checkpoint, or return None if none exists."""
+        path = self._path(session_id)
+        if not os.path.exists(path):
+            return None
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            return Checkpoint(**data["state"])
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            raise CheckpointError(
+                f"Cannot read checkpoint '{path}' (corrupted?): {exc}"
+            ) from exc
+
+    def clear(self, session_id: str) -> None:
+        """Delete a session's checkpoint (e.g., after successful completion)."""
+        path = self._path(session_id)
+        if os.path.exists(path):
+            os.remove(path)

agentpause-0.2.0.dist-info/METADATA

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: agentpause
+Version: 0.2.0
+Summary: Predictive scheduling for autonomous LLM agents: suspend gracefully before rate limits, resume without losing work.
+Author: Andrea Lelio Ciampolillo
+License: MIT
+Keywords: llm,agents,rate-limiting,checkpointing,scheduler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == "litellm"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Dynamic: license-file
+
+# 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 (OpenAI, Anthropic, Groq) or local — because
+it only serializes application-level state. True KV-cache warm start is an optional
+plugin for self-hosted runtimes (llama.cpp, vLLM).
+
+## Measured results (from the accompanying research)
+
+| Experiment | Result |
+|---|---|
+| Simulation, 300 runs/config | reactive baseline crashes up to 100% → predictive **0%** (k=4), token waste −80% |
+| Real provider (Groq free, 6K TPM) | multi-window task completed with **zero 429 errors** |
+| vs LangGraph's MemorySaver (200 runs) | LangGraph: 7.8 × 429/run, 9,239 tokens wasted; predictive: **0 and 0** |
+| 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`.
+
+> Status: **early alpha (0.1)**. Core components, the high-level
+> `PredictiveScheduler` API, the LiteLLM adapter (any provider), the LangGraph
+> adapter, runnable examples, and a full test suite are in place; the optional
+> KV-cache plugin is next.
+
+## Quick example
+
+```python
+from agentpause import PredictiveScheduler
+
+sched = PredictiveScheduler(backend=my_llm_call, telemetry=my_rate_limit_reader)
+
+with sched.session("task-1") as s:      # resumes automatically if interrupted before
+    for question in questions[s.step:]:  # skip steps finished before a suspend
+        s.add_user(question)
+        if s.should_suspend():           # predictive check, *before* the call
+            s.checkpoint()
+            break                        # stop cleanly; rerun to resume
+        reply = s.call()
+    else:
+        s.complete()                     # task done: drop the checkpoint
+```
+
+`backend` is any callable `messages -> (reply, tokens_used)`; `telemetry` is any
+callable `() -> remaining_tokens`. See `examples/quickstart.py` for a runnable demo
+(no API keys needed) that suspends mid-task and resumes on the next run.
+
+## Real providers via LiteLLM
+
+The LiteLLM adapter supplies both callables for 100+ providers (OpenAI, Groq,
+Anthropic, local servers, ...), reading the budget from each response's
+rate-limit headers and refreshing stale readings with a tiny telemetry ping:
+
+```python
+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)
+```
+
+Install with `pip install -e ".[litellm]"`; see `examples/litellm_groq.py`.
+To validate against your own provider (frontier models included):
+`python scripts/validate_provider.py gpt-4o-mini`.
+
+Rate-limit headers by provider (defaults target the OpenAI-style names):
+
+| Provider | remaining tokens | remaining requests | reset |
+|---|---|---|---|
+| OpenAI | `x-ratelimit-remaining-tokens` | `x-ratelimit-remaining-requests` | `x-ratelimit-reset-tokens` (`1s`, `6m0s`) |
+| Groq | `x-ratelimit-remaining-tokens` | `x-ratelimit-remaining-requests` | `x-ratelimit-reset-tokens` (`7.66s`, `2m59.56s`) |
+| Anthropic | `anthropic-ratelimit-tokens-remaining` | `anthropic-ratelimit-requests-remaining` | RFC 3339 timestamp — set `remaining_header=` etc. |
+
+Header names differ? Override them: `LiteLLMAdapter(model=..., remaining_header="...", requests_header="...", reset_header="...")`.
+
+## Beyond tokens: RPM and wait-vs-suspend
+
+Telemetry can be richer than a token count. `adapter.budget` reports all
+three dimensions providers expose — remaining tokens (TPM), remaining
+requests (RPM), and seconds until the window resets — and unlocks the
+three-valued decision:
+
+```python
+sched = PredictiveScheduler(backend=adapter.backend, telemetry=adapter.budget)
+
+d = session.next_action()   # "continue" | "wait" | "checkpoint"
+```
+
+`wait` fires when the budget does not fit **but** the window resets within
+`wait_threshold_s` (default 15 s): a short in-place pause is cheaper than a
+full suspend/resume cycle. Exhausted requests (RPM = 0) block the call even
+with plenty of tokens left. Plain-int telemetry keeps working unchanged.
+
+## Async
+
+Every entry point has an async twin — same rules, same guarantees, never
+blocks the event loop:
+
+```python
+adapter = LiteLLMAdapter(model="groq/llama-3.1-8b-instant")
+sched = PredictiveScheduler(backend=None, async_backend=adapter.abackend,
+                            telemetry=adapter.telemetry)
+reply = await session.acall()          # retry/backoff via asyncio.sleep
+await guard.acheck(state["messages"])  # async LangGraph nodes
+```
+
+For sharper input estimates, wire the per-model tokenizer:
+`PredictiveScheduler(..., count_tokens=adapter.count_tokens)` (falls back to
+the ~4 chars/token heuristic if the tokenizer is unavailable).
+
+## When prediction fails anyway
+
+Estimates are statistical — a 429 can still slip through. agentpause survives
+it instead of crashing:
+
+- **typed errors**: everything derives from `AgentPauseError`
+  (`RateLimitHit`, `TelemetryError`, `CheckpointError`, `BackendError`);
+- **retry with backoff**: unexpected 429s are retried (provider `retry-after`
+  honored, else exponential backoff — see `RetryPolicy`);
+- **hits are feedback**: each one bumps `safety_k` up (capped at `k_max`),
+  so the scheduler grows more cautious on workloads it underestimates;
+- **clean failure**: a failed call leaves the session state untouched —
+  no phantom steps, resumes stay consistent.
+
+## LangGraph integration
+
+`AgentPauseGuard` adds the predictive gate to any LangGraph node — LangGraph
+persists reactively (after nodes), the guard pauses *before* the call that
+would hit the rate limit, via LangGraph's own `interrupt()` + checkpointer:
+
+```python
+from agentpause.adapters.langgraph import AgentPauseGuard
+
+guard = AgentPauseGuard(telemetry=adapter.telemetry)   # e.g. from LiteLLMAdapter
+
+def agent_node(state):
+    guard.check(state["messages"])       # pauses the graph here if needed
+    reply = llm.invoke(state["messages"])
+    guard.record(state["messages"], reply.usage_metadata["total_tokens"])
+    ...
+```
+
+Resume the paused thread with `graph.invoke(Command(resume=True), config)`.
+On resume the guard re-reads telemetry fresh — never from the checkpoint.
+Install with `pip install -e ".[langgraph]"`; see `examples/langgraph_quickstart.py`.
+
+## Why
+
+Current agent frameworks persist state *reactively*: they checkpoint after a step
+completes and crash when the provider returns HTTP 429. `agentpause` adds a
+*predictive* layer that estimates the next step's cost, compares it against the
+remaining rate-limit budget, and suspends cleanly before the error — then resumes
+from the exact step.
+
+This library is the engineering counterpart of the research preprint *"A
+Resource-Aware Predictive Scheduler for Autonomous LLM Agents"*.
+
+## Components (v0.1)
+
+| Module | Role |
+|--------|------|
+| `PredictiveScheduler` / `Session` | the high-level API: `session()`, `should_suspend()`, `call()`, `checkpoint()` |
+| `Estimator` | predicts next-step token cost with a moving-average error correction (ε) and tracks σ |
+| `should_checkpoint` / `RiskModel` | the suspension rule (`remaining < estimated + k·σ`) and a diagnostic risk score |
+| `Budget` / `decide` | three-dimensional telemetry (TPM, RPM, reset time) and the three-valued rule: continue / wait / checkpoint |
+| `StateStore` / `Checkpoint` | atomic logical checkpointing with idempotency keys — works on any provider |
+| `adapters.litellm.LiteLLMAdapter` | backend + telemetry for any LiteLLM-supported provider (headers → budget, stale reading → 1-token ping) |
+| `adapters.langgraph.AgentPauseGuard` | predictive gate for LangGraph nodes: `check()` interrupts the graph before the fatal call, `record()` trains the estimator |
+
+## Install (from source, during development)
+
+```bash
+git clone https://github.com/<user>/agentpause
+cd agentpause
+pip install -e ".[dev]"
+pytest
+```
+
+## Roadmap
+
+- [x] Core components + test suite
+- [x] `PredictiveScheduler` high-level API (`session()`, `should_suspend()`, `call()`)
+- [x] Runnable quickstart example (no keys)
+- [x] LiteLLM adapter (works with any provider)
+- [x] LangGraph adapter (interrupt + checkpointer)
+- [ ] Optional KV-cache plugin for llama.cpp / vLLM (true warm start)
+
+## License
+
+MIT

agentpause-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+agentpause/__init__.py,sha256=SWYii0FaKN2Matip07Hz8yB6Ll1gkPn--qAsR2rINfM,1178
+agentpause/breaker.py,sha256=PNoFs00OYl1SpGENXFexQtpFJWeFGibxpZCy_tLMw7w,3245
+agentpause/errors.py,sha256=Sdh1OxjT0BltHE0_52jIgDAm6TohQ1TPOqcF9c9qo_8,2154
+agentpause/estimator.py,sha256=9LUT04ax1EXMRJFTdL61_iyGnn2RSMpSLdSmmPhoyHU,4252
+agentpause/fallback.py,sha256=YG0Nh-_LQBhbPMZH6pLmEEHJjyVPm2D0NXMuq3_nHA0,2950
+agentpause/retry.py,sha256=owFuhBhPxBad3xqNzGRDbZZEh40V7KrXJ38AYYADCrU,2205
+agentpause/risk.py,sha256=iidzZ10us2psexdSVuE-xgGxi085vbjcU_k4T8Ou4ek,5301
+agentpause/scheduler.py,sha256=EzE7aoQFEnrCXu6rumK-MuiC0qfyy6Fg-RNFGIX75Nc,14755
+agentpause/state.py,sha256=h_xtUPgpBgoriT0BaMb34A-c5IgO4ouygxpXalodjx4,3549
+agentpause/adapters/__init__.py,sha256=QkTxXuIRFGgGHEzK7fgCht4UpOSdkPQ9rGc4Y6-sIpE,298
+agentpause/adapters/langgraph.py,sha256=a5OER-WZYYgM6cKiy0wZPeVZiGtOEjkSU7hvgESMEuQ,9114
+agentpause/adapters/litellm.py,sha256=lqIFjgUkVFJtRWk0QYo2cJ8qfar1FHIfGnePqs344Lo,14403
+agentpause-0.2.0.dist-info/licenses/LICENSE,sha256=y3bmzJXJEc-s1EaKom6LLx0ZAd2qHVPbhGRycwVArSk,1075
+agentpause-0.2.0.dist-info/METADATA,sha256=QcW71ehy_3CwoZKzxUNpN3Bwu5DnBdhQxAxA1Eur--c,9305
+agentpause-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agentpause-0.2.0.dist-info/top_level.txt,sha256=EWK3W-1VLkr7fmVAAS_Mkpt3SvkO9MjHrw-bI6huKzo,11
+agentpause-0.2.0.dist-info/RECORD,,

agentpause-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+