runcycles/cycles-client-python

runcycles/cycles-client-python is a notably polished Python SDK, especially for a project created only in March 2026. It has the pieces maintainers and adopters usually look for: Apache-2.0 licensing, PyPI packaging as runcycles, typed public exports, a detailed README, runnable examples, a changelog, issue templates, CODEOWNERS, Dependabot, Scorecard, publish automation, and CI. The repo also shows active maintenance, with recent dependency/security workflow updates and a v0.4.1 release in May 2026. Even though the repo currently has no stars, the engineering maturity is much higher than that signal suggests.

The strongest part is the API design. The SDK supports both direct client usage and a decorator-first workflow, which is a good fit for AI agent budget enforcement because developers can wrap high-risk functions without rewriting the whole application. The reserve -> execute -> commit/release lifecycle is well documented, and the README does a good job explaining failure behavior, dry runs, overage policies, nested decorator caveats, streaming reservations, async support, response metadata, and typed exceptions. The examples directory is also strong: OpenAI, Anthropic, LangChain, FastAPI, streaming, async, decorator, and basic usage examples give users multiple paths into the library.

The test and quality posture is excellent. The project uses ruff, strict mypy, pytest, coverage thresholds, and contract tests against an OpenAPI fixture. Tests cover decorator behavior, lifecycle handling, retries, streaming, responses, validation, exceptions, models, config, context, and live-server integration. The AUDIT.md is unusually thorough and gives confidence that the Python client matches the Cycles protocol surface.

The main constructive feedback is about discoverability and onboarding. The README is comprehensive, but it is also long and dense; a shorter “first five minutes” path near the top would help new users understand the minimum viable setup before encountering advanced topics like direct debit events, nested decorators, or overage policies. The project also depends on the broader Cycles server/protocol ecosystem, so a simple architecture diagram or “what must be running locally” section would reduce friction.

Also, because this SDK targets budget and governance controls, a security model page covering API key scope, tenant boundaries, idempotency expectations, and failure-mode recommendations would strengthen trust for production adopters. Overall, this is a well-engineered SDK with strong docs, real tests, and a clear niche; its next challenge is less code quality and more simplifying the adoption story for first-time users.