sturdytools 0.1.0__py3-none-any.whl

sturdytools/__init__.py

@@ -0,0 +1,17 @@
+"""Retries, timeouts, rate limits and circuit breakers for AI agent tools."""
+
+from .breaker import CircuitBreaker
+from .core import error_message, sturdy
+from .errors import CircuitOpenError, ToolTimeout
+from .ratelimit import RateLimiter
+
+__all__ = [
+    "sturdy",
+    "CircuitBreaker",
+    "RateLimiter",
+    "ToolTimeout",
+    "CircuitOpenError",
+    "error_message",
+]
+
+__version__ = "0.1.0"

sturdytools/breaker.py

@@ -0,0 +1,88 @@
+"""A small circuit breaker.
+
+After ``failure_threshold`` failures in a row the breaker opens and calls are
+rejected right away, without touching the failing service. Once
+``reset_after`` seconds have passed, a single trial call is let through. If it
+works the breaker closes again; if it fails the breaker stays open for another
+``reset_after`` seconds.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Callable
+
+from .errors import CircuitOpenError
+
+CLOSED = "closed"
+OPEN = "open"
+HALF_OPEN = "half_open"
+
+
+class CircuitBreaker:
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        reset_after: float = 30.0,
+        clock: Callable[[], float] = time.monotonic,
+    ):
+        if failure_threshold < 1:
+            raise ValueError("failure_threshold must be at least 1")
+        if reset_after <= 0:
+            raise ValueError("reset_after must be positive")
+        self.failure_threshold = failure_threshold
+        self.reset_after = reset_after
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._state = CLOSED
+        self._failures = 0
+        self._opened_at = 0.0
+        self._trial_running = False
+
+    @property
+    def state(self) -> str:
+        return self._state
+
+    def before_call(self) -> None:
+        """Raise CircuitOpenError if the call should not go through."""
+        with self._lock:
+            if self._state == CLOSED:
+                return
+            waited = self._clock() - self._opened_at
+            if self._state == OPEN and waited >= self.reset_after:
+                self._state = HALF_OPEN
+            if self._state == HALF_OPEN and not self._trial_running:
+                self._trial_running = True
+                return
+            raise CircuitOpenError(retry_in=max(0.0, self.reset_after - waited))
+
+    def record_success(self) -> None:
+        with self._lock:
+            self._state = CLOSED
+            self._failures = 0
+            self._trial_running = False
+
+    def record_failure(self) -> None:
+        with self._lock:
+            self._trial_running = False
+            if self._state == HALF_OPEN:
+                self._open()
+                return
+            self._failures += 1
+            if self._failures >= self.failure_threshold:
+                self._open()
+
+    def reset(self) -> None:
+        """Close the breaker by hand, for example after fixing the service."""
+        self.record_success()
+
+    def _open(self) -> None:
+        self._state = OPEN
+        self._opened_at = self._clock()
+
+    def __repr__(self) -> str:
+        return (
+            f"CircuitBreaker(state={self._state!r}, failures={self._failures}, "
+            f"failure_threshold={self.failure_threshold}, reset_after={self.reset_after:g})"
+        )

sturdytools/core.py

@@ -0,0 +1,269 @@
+"""The ``sturdy`` decorator."""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import functools
+import inspect
+import logging
+import random
+import threading
+import time
+from typing import Any, Callable, Optional, Tuple, Type, Union
+
+from .breaker import CircuitBreaker
+from .errors import CircuitOpenError, ToolTimeout
+from .ratelimit import RateLimiter, as_limiter
+
+logger = logging.getLogger("sturdytools")
+
+_MISSING = object()
+
+ErrorTypes = Union[Type[BaseException], Tuple[Type[BaseException], ...]]
+OnError = Union[str, Callable[[str, BaseException, int], Any]]
+
+
+def error_message(tool_name: str, exc: BaseException, attempts: int) -> str:
+    """Turn a failure into a short message a language model can act on."""
+    if isinstance(exc, CircuitOpenError):
+        return (
+            f"Error: the tool '{tool_name}' is paused after repeated failures. "
+            f"It can be tried again in about {exc.retry_in:.0f} seconds. "
+            "Use another approach or tell the user it is unavailable."
+        )
+    tries = f"{attempts} attempt" + ("" if attempts == 1 else "s")
+    return (
+        f"Error: the tool '{tool_name}' failed after {tries} "
+        f"({type(exc).__name__}: {exc}). "
+        "Check the arguments, try a different approach, or tell the user it is unavailable."
+    )
+
+
+class _Policy:
+    """Everything the sync and async wrappers share."""
+
+    def __init__(
+        self,
+        name: str,
+        retries: int,
+        retry_on: ErrorTypes,
+        backoff: float,
+        max_backoff: float,
+        fallback: Any,
+        on_error: OnError,
+        on_retry: Optional[Callable[[int, BaseException, float], Any]],
+    ):
+        self.name = name
+        self.retries = retries
+        self.retry_on = retry_on
+        self.backoff = backoff
+        self.max_backoff = max_backoff
+        self.fallback = fallback
+        self.on_error = on_error
+        self.on_retry = on_retry
+
+    def is_transient(self, exc: BaseException) -> bool:
+        return isinstance(exc, self.retry_on)
+
+    def retry_delay(self, attempt: int, exc: BaseException) -> Optional[float]:
+        """Seconds to wait before the next attempt, or None to stop."""
+        if attempt > self.retries or not self.is_transient(exc):
+            return None
+        ceiling = min(self.max_backoff, self.backoff * (2 ** (attempt - 1)))
+        delay = ceiling / 2 + random.uniform(0, ceiling / 2)
+        logger.warning(
+            "tool %r failed on attempt %d (%s: %s), retrying in %.2fs",
+            self.name, attempt, type(exc).__name__, exc, delay,
+        )
+        if self.on_retry is not None:
+            self.on_retry(attempt, exc, delay)
+        return delay
+
+    def give_up(self, exc: BaseException, attempts: int, args: tuple, kwargs: dict) -> Any:
+        """Final failure: use the fallback, return a message, or raise."""
+        if self.fallback is not _MISSING:
+            logger.warning("tool %r failed, using fallback (%s: %s)", self.name, type(exc).__name__, exc)
+            if callable(self.fallback):
+                return self.fallback(*args, **kwargs)
+            return self.fallback
+        if self.on_error == "message":
+            return error_message(self.name, exc, attempts)
+        if callable(self.on_error):
+            return self.on_error(self.name, exc, attempts)
+        raise exc
+
+
+def _update_breaker(breaker: Optional[CircuitBreaker], policy: _Policy, exc: BaseException) -> None:
+    if breaker is None:
+        return
+    # Only temporary errors say the service is unhealthy. A bad argument from
+    # the model, for example, means the service answered, so it counts as up.
+    if policy.is_transient(exc):
+        breaker.record_failure()
+    else:
+        breaker.record_success()
+
+
+def _run_with_timeout(fn: Callable, args: tuple, kwargs: dict, timeout: Optional[float], name: str) -> Any:
+    if timeout is None:
+        return fn(*args, **kwargs)
+
+    # Python cannot stop a running thread, so a call that times out keeps
+    # running in the background. The thread is a daemon so it never blocks exit.
+    ctx = contextvars.copy_context()
+    box: dict = {}
+
+    def target() -> None:
+        try:
+            box["value"] = ctx.run(fn, *args, **kwargs)
+        except BaseException as exc:  # handed back to the caller below
+            box["error"] = exc
+
+    worker = threading.Thread(target=target, name=f"sturdytools-{name}", daemon=True)
+    worker.start()
+    worker.join(timeout)
+    if worker.is_alive():
+        raise ToolTimeout(name, timeout)
+    if "error" in box:
+        raise box["error"]
+    return box["value"]
+
+
+async def _await_with_timeout(coro: Any, timeout: Optional[float], name: str) -> Any:
+    if timeout is None:
+        return await coro
+    task = asyncio.ensure_future(coro)
+    try:
+        done, _ = await asyncio.wait({task}, timeout=timeout)
+    except asyncio.CancelledError:
+        task.cancel()
+        raise
+    if not done:
+        task.cancel()
+        raise ToolTimeout(name, timeout)
+    return task.result()
+
+
+def sturdy(
+    func: Optional[Callable] = None,
+    *,
+    timeout: Optional[float] = None,
+    retries: int = 0,
+    retry_on: ErrorTypes = (Exception,),
+    backoff: float = 0.5,
+    max_backoff: float = 8.0,
+    rate_limit: Union[str, RateLimiter, None] = None,
+    breaker: Union[CircuitBreaker, bool, None] = None,
+    fallback: Any = _MISSING,
+    on_error: OnError = "raise",
+    on_retry: Optional[Callable[[int, BaseException, float], Any]] = None,
+) -> Any:
+    """Make a tool function survive slow, flaky or failing dependencies.
+
+    Works on plain and async functions and keeps the original name, docstring
+    and signature, so agent frameworks still see the same tool.
+
+    Args:
+        timeout: seconds before one attempt is abandoned with ToolTimeout.
+        retries: extra attempts after the first one fails.
+        retry_on: errors that count as temporary. Only these are retried and
+            counted by the breaker. Anything else goes straight to the final step.
+        backoff: base wait before the first retry. It doubles each time, with
+            random jitter, up to ``max_backoff``.
+        rate_limit: ``"5/s"``, ``"60/min"`` or a shared RateLimiter.
+        breaker: a CircuitBreaker (share one across tools that use the same
+            service), or True for a default one per tool.
+        fallback: value to return when the tool gives up. If callable it is
+            called with the tool's arguments.
+        on_error: what to do when the tool gives up and there is no fallback.
+            ``"raise"`` re-raises the error, ``"message"`` returns a short error
+            text the model can read, and a callable ``(name, error, attempts)``
+            returns whatever you like.
+        on_retry: called as ``(attempt, error, delay)`` before each retry.
+    """
+    if retries < 0:
+        raise ValueError("retries must be zero or more")
+    if timeout is not None and timeout <= 0:
+        raise ValueError("timeout must be positive")
+    if backoff < 0 or max_backoff < 0:
+        raise ValueError("backoff values must be zero or more")
+    if not (on_error in ("raise", "message") or callable(on_error)):
+        raise ValueError("on_error must be 'raise', 'message' or a callable")
+
+    limiter = as_limiter(rate_limit)
+    if breaker is True:
+        breaker = CircuitBreaker()
+    elif breaker is False:
+        breaker = None
+
+    def decorate(fn: Callable) -> Callable:
+        name = getattr(fn, "__name__", "tool")
+        policy = _Policy(name, retries, retry_on, backoff, max_backoff, fallback, on_error, on_retry)
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                attempt = 0
+                while True:
+                    try:
+                        if breaker is not None:
+                            breaker.before_call()
+                    except CircuitOpenError as exc:
+                        result = policy.give_up(exc, attempt, args, kwargs)
+                        return await result if inspect.isawaitable(result) else result
+                    attempt += 1
+                    if limiter is not None:
+                        await limiter.acquire_async()
+                    try:
+                        value = await _await_with_timeout(fn(*args, **kwargs), timeout, name)
+                    except Exception as exc:
+                        _update_breaker(breaker, policy, exc)
+                        delay = policy.retry_delay(attempt, exc)
+                        if delay is not None:
+                            await asyncio.sleep(delay)
+                            continue
+                        result = policy.give_up(exc, attempt, args, kwargs)
+                        return await result if inspect.isawaitable(result) else result
+                    if breaker is not None:
+                        breaker.record_success()
+                    return value
+
+            wrapper = async_wrapper
+        else:
+
+            @functools.wraps(fn)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                attempt = 0
+                while True:
+                    try:
+                        if breaker is not None:
+                            breaker.before_call()
+                    except CircuitOpenError as exc:
+                        return policy.give_up(exc, attempt, args, kwargs)
+                    attempt += 1
+                    if limiter is not None:
+                        limiter.acquire()
+                    try:
+                        value = _run_with_timeout(fn, args, kwargs, timeout, name)
+                    except Exception as exc:
+                        _update_breaker(breaker, policy, exc)
+                        delay = policy.retry_delay(attempt, exc)
+                        if delay is not None:
+                            time.sleep(delay)
+                            continue
+                        return policy.give_up(exc, attempt, args, kwargs)
+                    if breaker is not None:
+                        breaker.record_success()
+                    return value
+
+            wrapper = sync_wrapper
+
+        wrapper.breaker = breaker  # type: ignore[attr-defined]
+        wrapper.limiter = limiter  # type: ignore[attr-defined]
+        return wrapper
+
+    if func is not None:
+        return decorate(func)
+    return decorate

sturdytools/errors.py

@@ -0,0 +1,22 @@
+"""Exceptions raised by sturdytools."""
+
+from __future__ import annotations
+
+
+class ToolTimeout(TimeoutError):
+    """A tool call ran longer than its time limit."""
+
+    def __init__(self, tool_name: str, seconds: float):
+        self.tool_name = tool_name
+        self.seconds = seconds
+        super().__init__(f"tool '{tool_name}' took longer than {seconds:g}s")
+
+
+class CircuitOpenError(RuntimeError):
+    """Calls are paused because the tool failed too many times in a row."""
+
+    def __init__(self, retry_in: float):
+        self.retry_in = retry_in
+        super().__init__(
+            f"calls are paused after repeated failures, next try allowed in {retry_in:.1f}s"
+        )

sturdytools/ratelimit.py

@@ -0,0 +1,99 @@
+"""A thread safe token bucket that works from sync and async code."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from typing import Callable, Optional
+
+_UNITS = {
+    "s": 1.0,
+    "sec": 1.0,
+    "second": 1.0,
+    "m": 60.0,
+    "min": 60.0,
+    "minute": 60.0,
+    "h": 3600.0,
+    "hr": 3600.0,
+    "hour": 3600.0,
+}
+
+
+class RateLimiter:
+    """Allow at most ``rate`` calls every ``per`` seconds.
+
+    ``burst`` is how many calls may go through back to back after a quiet
+    period. The default of 1 spaces calls evenly, which is the safest choice
+    for APIs with strict limits.
+
+    One limiter can be shared by several tools that call the same API.
+    """
+
+    def __init__(
+        self,
+        rate: float,
+        per: float = 1.0,
+        burst: int = 1,
+        clock: Callable[[], float] = time.monotonic,
+    ):
+        if rate <= 0 or per <= 0:
+            raise ValueError("rate and per must be positive")
+        if burst < 1:
+            raise ValueError("burst must be at least 1")
+        self.rate = rate
+        self.per = per
+        self.burst = burst
+        self._fill_per_second = rate / per
+        self._clock = clock
+        self._tokens = float(burst)
+        self._last = clock()
+        self._lock = threading.Lock()
+
+    @classmethod
+    def parse(cls, spec: str, burst: int = 1) -> "RateLimiter":
+        """Build a limiter from text such as ``"5/s"``, ``"60/min"`` or ``"1000/hour"``."""
+        try:
+            count, unit = spec.replace(" ", "").lower().split("/")
+            if unit not in _UNITS and unit.endswith("s"):
+                unit = unit[:-1]  # "minutes" -> "minute"
+            return cls(float(count), per=_UNITS[unit], burst=burst)
+        except (ValueError, KeyError):
+            raise ValueError(
+                f"could not read rate limit {spec!r}; use a form like '5/s', '60/min' or '1000/hour'"
+            ) from None
+
+    def reserve(self) -> float:
+        """Take one slot and return how many seconds the caller must wait for it."""
+        with self._lock:
+            now = self._clock()
+            refill = (now - self._last) * self._fill_per_second
+            self._tokens = min(float(self.burst), self._tokens + refill)
+            self._last = now
+            self._tokens -= 1.0
+            if self._tokens >= 0:
+                return 0.0
+            return -self._tokens / self._fill_per_second
+
+    def acquire(self) -> None:
+        """Block until a call is allowed."""
+        wait = self.reserve()
+        if wait > 0:
+            time.sleep(wait)
+
+    async def acquire_async(self) -> None:
+        """Wait, without blocking the event loop, until a call is allowed."""
+        wait = self.reserve()
+        if wait > 0:
+            await asyncio.sleep(wait)
+
+    def __repr__(self) -> str:
+        return f"RateLimiter(rate={self.rate:g}, per={self.per:g}, burst={self.burst})"
+
+
+def as_limiter(value: Optional[object]) -> Optional[RateLimiter]:
+    if value is None or isinstance(value, RateLimiter):
+        return value
+    if isinstance(value, str):
+        return RateLimiter.parse(value)
+    raise TypeError("rate_limit must be a string like '5/s' or a RateLimiter")

sturdytools-0.1.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: sturdytools
+Version: 0.1.0
+Summary: Retries, timeouts, rate limits and circuit breakers for AI agent tools
+Author: Meenal Asesh
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ai-with-md/sturdytools
+Project-URL: Issues, https://github.com/ai-with-md/sturdytools/issues
+Keywords: ai agents,llm,tool calling,function calling,mcp,retry,timeout,circuit breaker,rate limit,resilience
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# sturdytools
+
+Retries, timeouts, rate limits and circuit breakers for the tools an AI agent calls.
+
+[![PyPI](https://img.shields.io/pypi/v/sturdytools)](https://pypi.org/project/sturdytools/)
+[![tests](https://github.com/ai-with-md/sturdytools/actions/workflows/tests.yml/badge.svg)](https://github.com/ai-with-md/sturdytools/actions/workflows/tests.yml)
+![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+An agent is only as reliable as its tools. A search API that drops one request in fifty, a database that hangs, or a service that hits its rate limit can end an agent run, or put a raw stack trace in front of the user. Most of these failures are temporary, and the rest can be handled if the model gets a clear message it can act on.
+
+sturdytools is one decorator that handles this for any Python function, sync or async, with no dependencies.
+
+```python
+from sturdytools import sturdy
+
+@sturdy(timeout=10, retries=3, rate_limit="5/s", on_error="message")
+def search_orders(customer_id: str) -> list:
+    """Find recent orders for a customer."""
+    return orders_api.search(customer_id)
+```
+
+If the API drops a connection, the call is retried with backoff. If it hangs, the attempt is abandoned after 10 seconds. If it still fails after 3 retries, the model gets a short message instead of an exception:
+
+```
+Error: the tool 'search_orders' failed after 4 attempts (ConnectionError: connection reset by peer).
+Check the arguments, try a different approach, or tell the user it is unavailable.
+```
+
+[![Demo: a plain tool crashes, the wrapped tool retries, times out, and stops calling a service that is down](https://raw.githubusercontent.com/ai-with-md/sturdytools/main/docs/demo.png)](https://github.com/ai-with-md/sturdytools/blob/main/examples/flaky_tools_demo.py)
+
+## Install
+
+```bash
+pip install sturdytools
+```
+
+Python 3.9 or newer. No other packages are needed.
+
+## What it does
+
+| Option | What it does | Default |
+|---|---|---|
+| `timeout` | Seconds before one attempt is abandoned with `ToolTimeout` | none |
+| `retries` | Extra attempts after the first one fails | 0 |
+| `retry_on` | Errors that count as temporary. Only these are retried | `Exception` |
+| `backoff`, `max_backoff` | Wait before the first retry, doubling each time with jitter, up to the cap | 0.5s, 8s |
+| `rate_limit` | `"5/s"`, `"60/min"`, `"1000/hour"`, or a shared `RateLimiter` | none |
+| `breaker` | A `CircuitBreaker`, or `True` for one per tool | none |
+| `fallback` | Value to return when the tool gives up. If callable, it gets the tool's arguments | none |
+| `on_error` | `"raise"`, `"message"`, or your own function `(name, error, attempts)` | `"raise"` |
+| `on_retry` | Called as `(attempt, error, delay)` before each retry, for logging or metrics | none |
+
+Each call goes through the same steps:
+
+1. If the circuit breaker is open, stop right away.
+2. Wait for the rate limiter.
+3. Run the tool with the time limit.
+4. If it raised a temporary error and retries are left, wait and go back to step 1.
+5. Otherwise use the fallback, return a message, or raise, depending on the settings.
+
+The wrapper keeps the original function name, docstring and signature, which is what agent frameworks read to build the tool description for the model. Put `@sturdy` closest to the function, under your framework's tool decorator.
+
+## Works with MCP servers and LangChain
+
+The wrapper keeps the function's name, docstring and signature, so frameworks build the same tool description as before. Put `@sturdy` under the framework's decorator, closest to the function:
+
+```python
+from mcp.server.mcpserver import MCPServer
+from sturdytools import sturdy
+
+server = MCPServer("weather")
+
+@server.tool()
+@sturdy(timeout=10, retries=2, on_error="message")
+async def get_weather(city: str) -> str:
+    """Current weather for a city."""
+    ...
+```
+
+```python
+from langchain_core.tools import tool
+from sturdytools import sturdy
+
+@tool
+@sturdy(timeout=10, retries=2, rate_limit="5/s", on_error="message")
+def search_orders(customer_id: str) -> list:
+    """Find recent orders for a customer."""
+    ...
+```
+
+Checked with mcp 2.3 and langchain-core 1.8, for sync and async tools: the tool schema and description are unchanged, retries happen inside the tool call, and a tool that gives up returns the error message to the model as its result.
+
+## Sharing limits and breakers across tools
+
+Several tools often call the same API. Give them one rate limiter and one breaker, so they respect the same limit and stop together when the service is down.
+
+```python
+from sturdytools import CircuitBreaker, RateLimiter, sturdy
+
+crm_limit = RateLimiter.parse("10/s")
+crm_breaker = CircuitBreaker(failure_threshold=5, reset_after=30)
+
+@sturdy(retries=2, rate_limit=crm_limit, breaker=crm_breaker, on_error="message")
+def get_account(account_id: str) -> dict:
+    ...
+
+@sturdy(retries=2, rate_limit=crm_limit, breaker=crm_breaker, on_error="message")
+def list_contacts(account_id: str) -> list:
+    ...
+```
+
+After 5 temporary failures in a row, both tools stop calling the service for 30 seconds and tell the model it is paused. Then one trial call goes through. If it works, normal calls resume.
+
+## Async tools
+
+The same decorator works on `async def` functions. Timeouts cancel the task, and the rate limiter and retries wait without blocking the event loop.
+
+```python
+@sturdy(timeout=5, retries=2, fallback=lambda city: "weather unavailable")
+async def get_weather(city: str) -> str:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(WEATHER_URL, params={"q": city})
+        response.raise_for_status()
+        return response.text
+```
+
+## Choosing what to retry
+
+Retrying everything is rarely right. If the model passed a bad argument, retrying the same call wastes time and money. Limit retries to errors that are actually temporary:
+
+```python
+@sturdy(retries=3, retry_on=(ConnectionError, TimeoutError), on_error="message")
+def lookup_invoice(invoice_id: str) -> dict:
+    ...
+```
+
+Here a `KeyError` for an unknown invoice goes straight back to the model as a message, so it can correct itself, and it does not count against the circuit breaker.
+
+## Try it
+
+```bash
+python examples/flaky_tools_demo.py
+```
+
+The [demo](https://github.com/ai-with-md/sturdytools/blob/main/examples/flaky_tools_demo.py) uses a fake weather service that drops connections, hangs, and then goes down, and prints what a plain tool and a wrapped tool do in each case. No API keys are needed.
+
+## How it compares
+
+- **[tenacity](https://github.com/jd/tenacity)** and **[stamina](https://github.com/hynek/stamina)** are excellent general retry libraries. If retries are all you need, use one of them.
+- sturdytools is narrower and aimed at agent tools: timeouts, retries, rate limits, a circuit breaker and a fallback in one decorator, plus an error message written for the model, so a failing tool becomes something the agent can reason about instead of a crash.
+- Agent frameworks have their own retry options (LangChain's `with_retry`, retry policies on LangGraph nodes). Those retry a whole step. sturdytools works on the single tool function, so it behaves the same in any framework, or in none.
+
+## Limits
+
+- Python cannot stop a running thread. When a sync tool times out, the caller gets `ToolTimeout` right away, but the original call keeps running in a background thread until it finishes on its own. For tools that can hang for a long time, prefer async, where the task is cancelled, or set a timeout in the client library as well.
+- Rate limits and breakers live in memory, per process. Several workers calling the same API each keep their own count.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run on Python 3.10, 3.12 and 3.13 on every push.
+
+## License
+
+MIT

sturdytools-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sturdytools/__init__.py,sha256=n6vfG-Z5np54pgducgS491nz1vX3dOW7BvAzleKMz84,397
+sturdytools/breaker.py,sha256=511rwpfoNPSnVy0ehMvtoeGId2RNy0_nigx9dZYxhqM,2797
+sturdytools/core.py,sha256=gOo7q1O5QQvSPFYI6OtX_QcqABy2-4GY7WrbhSw1Nqs,10449
+sturdytools/errors.py,sha256=XmshilrjadcaTq9q4y8kdWGK4ZC7UzBb-zh8WqGVHRw,686
+sturdytools/ratelimit.py,sha256=8I77WSIQdzp5mLB--PeRvj5gebbpr7VyuiDKRBgooDQ,3199
+sturdytools-0.1.0.dist-info/licenses/LICENSE,sha256=HS_Pp1J0NNKF4niTKA1MdskkGwByEasM-oJb8NcpaGE,1069
+sturdytools-0.1.0.dist-info/METADATA,sha256=v2wyDhbVFpDVZ14-VI2P4L_nzTarzNH8XRTFbMStdQc,8764
+sturdytools-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sturdytools-0.1.0.dist-info/top_level.txt,sha256=ey8UcFOvSpYBJq1QI0Bm3d0XAO-iT7V-X3yChhY3YpM,12
+sturdytools-0.1.0.dist-info/RECORD,,

sturdytools-0.1.0.dist-info/WHEEL

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

sturdytools-0.1.0.dist-info/licenses/LICENSE

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

sturdytools-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sturdytools