runcycles/cycles-spring-boot-starter

cycles-spring-boot-starter feels like a serious, well-scoped integration rather than a thin wrapper. The core idea is useful: give Java/Spring teams a drop-in @Cycles annotation that reserves budget before an AI/LLM operation runs, commits actual usage afterward, and releases the reservation on failure. That maps nicely onto how Spring teams already think about cross-cutting concerns, so the starter has a natural place in an enterprise codebase where cost, risk, and tool-action limits matter.

The README is one of the stronger parts of the repo. It does not just show a happy-path annotation example; it explains the reserve/execute/commit/release lifecycle, denial behavior, ALLOW_WITH_CAPS, SpEL variables, subject scoping, idempotency, retries, dry runs, and error handling. I also like that it calls out real Spring constraints directly: self-invocation through AOP proxies, nested @Cycles calls, and the ThreadLocal/WebFlux limitation. Those are exactly the kinds of edge cases that would otherwise surprise adopters in production.

The implementation signals are encouraging too. The repo has CI, publish, Scorecard, Dependabot automation, Apache-2.0 licensing, security/contribution/community files, a demo Spring client, and a published release history with v0.2.1 as the latest release. The test story looks unusually transparent: TEST_COVERAGE_GAPS.md reports 14 test classes, 240 test methods, and roughly 90-95% estimated coverage, while still listing remaining gaps instead of pretending everything is done. That is a strong trust signal for budget-governance code.

The main opportunity is adoption clarity. Since this is early and still has only 1 star and 1 fork, I would make the first-run path even more concrete: a short “run the demo locally” section, a minimal Docker Compose setup for the Cycles server plus demo app, and one copy-paste Spring AI or OpenAI service example would help people test the value quickly. The remaining test gaps are mostly low priority, but I’d prioritize an end-to-end Spring context test with MockWebServer and a concurrency/thread-isolation test because reservation correctness is the product. Overall, this is a polished and credible starter for a young project, especially because it documents both the happy path and the operational traps.