runfence 0.1.0__py3-none-any.whl

agentleash/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .budget import Budget, Usage
+from .errors import BudgetExceeded, Cancelled, DeadlineExceeded, RunStopped
+from .scope import RunScope, run_scope
+
+__version__ = "0.1.0"
+__all__ = ["Budget", "Usage", "RunScope", "run_scope", "RunStopped",
+           "Cancelled", "DeadlineExceeded", "BudgetExceeded"]

agentleash/budget.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Usage:
+    """What a run has spent so far."""
+
+    tokens: int = 0
+    usd: float = 0.0
+
+    def add(self, tokens: int = 0, usd: float = 0.0) -> None:
+        if tokens < 0 or usd < 0:
+            raise ValueError("usage cannot decrease")
+        self.tokens += tokens
+        self.usd += usd
+
+
+@dataclass(frozen=True)
+class Budget:
+    """A ceiling for one run. None means no limit for that dimension."""
+
+    tokens: int | None = None
+    usd: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.tokens is not None and self.tokens <= 0:
+            raise ValueError("token budget must be positive")
+        if self.usd is not None and self.usd <= 0:
+            raise ValueError("cost budget must be positive")
+
+    def exceeded_by(self, usage: Usage) -> str | None:
+        if self.tokens is not None and usage.tokens > self.tokens:
+            return f"token budget spent: {usage.tokens} > {self.tokens}"
+        if self.usd is not None and usage.usd > self.usd:
+            return f"cost budget spent: ${usage.usd:.4f} > ${self.usd:.2f}"
+        return None
+
+    @property
+    def unlimited(self) -> bool:
+        return self.tokens is None and self.usd is None

agentleash/errors.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+
+class RunStopped(Exception):
+    """Base for every reason a run was stopped by the scope rather than by finishing."""
+
+    def __init__(self, message: str, *, elapsed: float, tokens: int, usd: float) -> None:
+        super().__init__(message)
+        self.elapsed = elapsed
+        self.tokens = tokens
+        self.usd = usd
+
+
+class Cancelled(RunStopped):
+    """cancel() was called."""
+
+
+class DeadlineExceeded(RunStopped):
+    """The wall-clock deadline passed."""
+
+
+class BudgetExceeded(RunStopped):
+    """The token or cost budget was spent."""

agentleash/scope.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Callable
+from typing import Any
+
+from .budget import Budget, Usage
+from .errors import BudgetExceeded, Cancelled, DeadlineExceeded
+
+
+class RunScope:
+    """A boundary around one agent run: it can be stopped, and it stops for real.
+
+    Abandoning an async generator does not stop work the generator started; those tasks
+    keep running, and for an agent that means live model calls that still cost money.
+    Work spawned through this scope is cancelled with it, and anything left behind is
+    reported rather than ignored.
+    """
+
+    def __init__(self, deadline: float | None = None, budget: Budget | None = None) -> None:
+        if deadline is not None and deadline <= 0:
+            raise ValueError("deadline must be positive")
+        self.deadline = deadline
+        self.budget = budget or Budget()
+        self.usage = Usage()
+        self.leaked: list[str] = []
+        self._started: float | None = None
+        self._stop = asyncio.Event()
+        self._reason = ""
+        self._children: set[asyncio.Task[Any]] = set()
+        self._known: set[asyncio.Task[Any]] = set()
+
+    # ---- lifecycle -------------------------------------------------------
+
+    async def __aenter__(self) -> RunScope:
+        self._started = time.monotonic()
+        self._known = set(asyncio.all_tasks())
+        return self
+
+    async def __aexit__(self, *exc: object) -> bool:
+        for task in list(self._children):
+            if not task.done():
+                task.cancel()
+        if self._children:
+            await asyncio.gather(*self._children, return_exceptions=True)
+        strays = [t for t in asyncio.all_tasks()
+                  if t not in self._known and t not in self._children
+                  and not t.done() and t is not asyncio.current_task()]
+        self.leaked = [t.get_name() for t in strays]
+        return False
+
+    # ---- controls --------------------------------------------------------
+
+    def spawn(self, coro: Any) -> asyncio.Task[Any]:
+        """Run child work inside the scope so cancelling the scope cancels it too."""
+        task = asyncio.ensure_future(coro)
+        self._children.add(task)
+        task.add_done_callback(self._children.discard)
+        return task
+
+    def cancel(self, reason: str = "cancelled by caller") -> None:
+        """Stop the run. Safe to call from another task."""
+        self._reason = reason
+        self._stop.set()
+
+    @property
+    def elapsed(self) -> float:
+        return 0.0 if self._started is None else time.monotonic() - self._started
+
+    @property
+    def remaining(self) -> float | None:
+        return None if self.deadline is None else self.deadline - self.elapsed
+
+    def record(self, tokens: int = 0, usd: float = 0.0) -> None:
+        """Add usage and stop the run if that puts it over budget."""
+        self.usage.add(tokens=tokens, usd=usd)
+        breach = self.budget.exceeded_by(self.usage)
+        if breach:
+            raise self._stopped(BudgetExceeded, breach)
+
+    # ---- consumption -----------------------------------------------------
+
+    async def stream(
+        self,
+        source: AsyncIterator[Any],
+        usage: Callable[[Any], dict[str, Any]] | None = None,
+    ) -> AsyncIterator[Any]:
+        """Yield from `source` while enforcing cancellation, deadline and budget.
+
+        The deadline is applied to each wait for the next item rather than wrapped
+        around the yields, because a timeout that fires while a generator is suspended
+        is delivered to whoever happens to be running it.
+        """
+        iterator = source.__aiter__()
+        waiter = asyncio.ensure_future(self._stop.wait())
+        try:
+            while True:
+                left = self.remaining
+                if left is not None and left <= 0:
+                    raise self._stopped(DeadlineExceeded, f"deadline of {self.deadline}s passed")
+                step = asyncio.ensure_future(iterator.__anext__())
+                done, _ = await asyncio.wait({step, waiter}, timeout=left,
+                                             return_when=asyncio.FIRST_COMPLETED)
+                if waiter in done:
+                    step.cancel()
+                    await asyncio.gather(step, return_exceptions=True)
+                    raise self._stopped(Cancelled, self._reason)
+                if step not in done:
+                    step.cancel()
+                    await asyncio.gather(step, return_exceptions=True)
+                    raise self._stopped(DeadlineExceeded, f"deadline of {self.deadline}s passed")
+                try:
+                    item = step.result()
+                except StopAsyncIteration:
+                    return
+                if usage is not None:
+                    self.record(**usage(item))
+                yield item
+        finally:
+            waiter.cancel()
+            closer = getattr(source, "aclose", None)
+            if closer is not None:
+                await closer()
+
+    # ---- internals -------------------------------------------------------
+
+    def _stopped(self, kind: type, message: str):
+        return kind(message, elapsed=self.elapsed, tokens=self.usage.tokens, usd=self.usage.usd)
+
+
+def run_scope(deadline: float | None = None, tokens: int | None = None,
+              usd: float | None = None) -> RunScope:
+    """A scope with a deadline in seconds and optional token and cost ceilings."""
+    return RunScope(deadline=deadline, budget=Budget(tokens=tokens, usd=usd))

runfence-0.1.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: runfence
+Version: 0.1.0
+Summary: Cancel, deadline and budget limits for agent runs that actually stop the work
+Author: Naveen
+License: MIT
+Project-URL: Homepage, https://github.com/Chenjigaram/agentleash
+Project-URL: Source, https://github.com/Chenjigaram/agentleash
+Keywords: agents,llm,cancellation,timeout,budget,asyncio,adk,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# agentleash
+
+Cancel, deadline and budget limits for agent runs — that actually stop the work.
+
+Every agent framework hands you an async generator of events. When you stop consuming
+it, the work it started **keeps running**. Model calls keep streaming, tools keep
+executing, and you keep paying. `break` does not mean stop.
+
+```python
+from agentleash import run_scope, Cancelled
+
+scope = run_scope(deadline=30, tokens=50_000, usd=0.25)
+
+async with scope:
+    try:
+        async for event in scope.stream(runner.run_async(...)):
+            handle(event)
+    except Cancelled:
+        ...          # scope.cancel() was called, from anywhere
+```
+
+`scope.stream()` takes any async iterator, so it works with whatever framework produced
+it. There is no adapter to install and nothing to register.
+
+## What it costs to get this wrong
+
+Cancelling a real streaming run against `llama-3.3-70b`, two runs on different days:
+
+| | Wall clock | Events |
+|---|---|---|
+| Run to completion | 262.3s / 42.6s | 1369 / 1366 |
+| `scope.cancel()` at 1.5s | **1.8s / 1.5s** | 1 |
+
+The completion time swings with provider load, which is the point: you cannot predict
+how long a run will take, so the ceiling has to be enforced rather than assumed. No
+framework tasks were left alive after cancelling in either run.
+
+Reproduce it with `examples/live_cancel.py`, or see the mechanism with no API key at all:
+
+```bash
+python examples/stop_means_stop.py
+```
+
+```
+  break + aclose()      -> tools that still finished: ['search', 'summarise', 'draft']
+  inside a run_scope    -> tools that still finished: none
+  anything left behind? no
+```
+
+## Limits
+
+```python
+scope = run_scope(
+    deadline=30,        # seconds of wall clock for the whole run
+    tokens=50_000,      # stop once this many tokens are spent
+    usd=0.25,           # stop once this much money is spent
+)
+```
+
+Usage has to come from somewhere, so tell the scope how to read it off an event:
+
+```python
+async for event in scope.stream(source, usage=lambda e: {"tokens": e.usage.total_tokens}):
+    ...
+```
+
+Stopping raises, and the exception carries what was spent:
+
+```python
+except BudgetExceeded as stopped:
+    log.warning("stopped after %.1fs and %d tokens", stopped.elapsed, stopped.tokens)
+```
+
+`Cancelled`, `DeadlineExceeded` and `BudgetExceeded` all derive from `RunStopped`.
+
+## Work started inside the scope
+
+Anything spawned through the scope is cancelled with it:
+
+```python
+async with run_scope(deadline=10) as scope:
+    scope.spawn(background_tool())
+    async for event in scope.stream(source):
+        ...
+```
+
+Anything spawned *outside* it cannot be cancelled by it — but it is reported rather
+than ignored:
+
+```python
+print(scope.leaked)   # names of tasks still running when the scope closed
+```
+
+That list is the honest answer to "did my framework clean up?", and it is usually the
+first thing you want to know when a run refuses to die.
+
+## Why this exists
+
+Stopping an agent is unsolved across the ecosystem, not in one framework:
+
+- google/adk-python — 52 reactions across its three top cancellation issues, the oldest
+  open since August 2025, with three community PRs unmerged
+- langchain-ai/langgraph — 25 open issues mentioning cancel, interrupt or abort; the
+  most discussed is about cancellation losing state that was not yet checkpointed
+- strands-agents — 21 open issues on the same theme
+
+## What it does not do
+
+- It cannot cancel work a framework spawned as an orphan task. Nothing outside that
+  framework can. It detects and reports those instead, in `scope.leaked`.
+- It does not price tokens. Pass `usd` yourself, from your provider's numbers or a
+  library like `tokencost`.
+- Verified against the OpenAI Agents SDK on real streaming traffic. Google ADK exposes
+  the same async-generator shape and is expected to work, but is **not yet tested**.
+
+## Install
+
+```bash
+pip install agentleash
+```
+
+No dependencies. Python 3.11+ (it uses `asyncio.timeout` semantics and modern task APIs).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```

runfence-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agentleash/__init__.py,sha256=kC80U4ue00VX9NKyP7qZnZErDSFz7q1MbvRCEYX_HRY,339
+agentleash/budget.py,sha256=OVRCLrt2f45DeOMXLllQGY0CZd07DdTWzsIbd9oBmXY,1278
+agentleash/errors.py,sha256=akXPSAEHUg9kSWCYKGYI2IFKbYOm14L4SM1vOHKb4t8,587
+agentleash/scope.py,sha256=jU8Iw_5MmNVPaeUAu935kyEzgQwJM-lIfkVTBjDIkys,5553
+runfence-0.1.0.dist-info/licenses/LICENSE,sha256=oUiz9FNjnv2M-ecIoc0YgMMunLGtJnC4s2lvuAtItL8,1063
+runfence-0.1.0.dist-info/METADATA,sha256=6Z7WvRGvZiG4UxGTh3eU1bouGIcPcK3PQRMRp_dNCnQ,4902
+runfence-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+runfence-0.1.0.dist-info/top_level.txt,sha256=bipzVBWbdpNk567_g8c_qRQW0xYyjWLa_08fPU7ZuGg,11
+runfence-0.1.0.dist-info/RECORD,,

runfence-0.1.0.dist-info/WHEEL

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

runfence-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naveen
+
+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.

runfence-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentleash