rotapool

Async resource pool with inline health feedback, automatic cooldown, and retry -- for API keys, proxies, GPU workers, or anything that can rate-limit you or go down.

rotapool is designed for resources where every call is also useful health evidence. Instead of relying on a separate prober, callers signal whether the selected resource should stay healthy, cool down temporarily, or be disabled.

Designed for AI coding agents. rotapool exposes machine-readable usage notes via agent-readable, including operation contracts, do/don't rules, anti-patterns, and failure modes.

npx skills add zydo/skills --skill agent-readable

Install

pip install rotapool
# or
uv add rotapool

Requires Python 3.10+. Zero runtime dependencies. Optional extras: pip install "rotapool[agent]" for agent-readable, pip install "rotapool[prometheus]" for a Prometheus collector over pool.stats(). A runnable scrape is in examples/prometheus_pool.py.

Quick Start

import httpx

from rotapool import CooldownResource, DisableResource, Pool, Resource

pool = Pool(
    resources=[
        Resource(resource_id="key-1", value="sk-aaa"),
        Resource(resource_id="key-2", value="sk-bbb"),
        Resource(resource_id="key-3", value="sk-ccc"),
    ],
    max_attempts=3,
    cooldown_table=(30.0, 120.0, 300.0, 600.0),
)

@pool.use()
async def call_upstream(resource, url, payload):
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            url,
            headers={"Authorization": f"Bearer {resource.value}"},
            json=payload,
        )

    if resp.status_code == 429:
        raise CooldownResource(reason="rate limited")
    if resp.status_code == 401:
        raise DisableResource(reason="invalid key")

    return resp.json()

result = await call_upstream("https://api.example.com/v1/chat", {"prompt": "hi"})

Runnable versions of this (no httpx) and of the Prometheus extra live in examples/.

Documentation

• Usage guide covers pool initialization, @pool.use(), direct pool.run(), resource types, accepted operation shapes, and observability.
• Behavior guide explains selection strategies, cooldown escalation, retry behavior, in-flight cancellation, cancellation discrimination, admin control, and metrics (snapshot(), stats(), optional Prometheus collector).
• API reference documents Pool, Resource, snapshot(), stats(), admin methods, exceptions, and the optional Prometheus collector.
• Pitfalls and testing lists common anti-patterns, cancellation gotchas, test commands, and license information.
• Changelog lists released versions.
• examples/ has runnable scripts: basic_usage.py (use() / run()), prometheus_pool.py (optional scrape).

Core Concepts

• Each Pool owns a set of Resource[T] objects. T can be a bearer token, proxy URL, browser session, GPU worker, client object, or any other value.
• Each run() attempt receives one selected Resource.
• Raising CooldownResource marks that resource temporarily unavailable and retries elsewhere when possible.
• Raising DisableResource removes that resource from selection until enable() is called.
• Any other exception is treated as caller or business failure, not resource failure, and propagates.
• @pool.use() is a decorator convenience over pool.run().

Testing

uv sync --all-extras
uv run pytest --cov

See pitfalls and testing for pip-based setup and additional notes.

License

MIT