sturdytools 0.1.0__tar.gz

sturdytools-0.1.0/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/PKG-INFO

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

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

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sturdytools"
+version = "0.1.0"
+description = "Retries, timeouts, rate limits and circuit breakers for AI agent tools"
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Meenal Asesh"}]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["ai agents", "llm", "tool calling", "function calling", "mcp", "retry", "timeout", "circuit breaker", "rate limit", "resilience"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Framework :: AsyncIO",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/ai-with-md/sturdytools"
+Issues = "https://github.com/ai-with-md/sturdytools/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sturdytools-0.1.0/setup.cfg

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

sturdytools-0.1.0/src/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-0.1.0/src/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})"
+        )