agentpause 0.2.0__tar.gz

agentpause-0.2.0/LICENSE

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

agentpause-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,190 @@
+# 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/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentpause"
+version = "0.2.0"
+description = "Predictive scheduling for autonomous LLM agents: suspend gracefully before rate limits, resume without losing work."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Andrea Lelio Ciampolillo" }]
+keywords = ["llm", "agents", "rate-limiting", "checkpointing", "scheduler"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+litellm = ["litellm>=1.40"]
+langgraph = ["langgraph>=0.2"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]
+testpaths = ["tests"]

agentpause-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentpause-0.2.0/src/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-0.2.0/src/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
+"""