Add comprehensive integration examples for Cycles Python client

[amavashev]

Summary

This PR adds a complete suite of runnable examples demonstrating how to integrate the runcycles client into real-world Python applications. The examples cover decorator-based budget management, streaming workflows, and integrations with popular frameworks and LLM providers.

Key Changes

• New example files in examples/ directory:

  • openai_integration.py – Guard OpenAI chat completions with budget checks, caps-aware token limiting, and cost tracking
  • anthropic_integration.py – Protect Anthropic Messages API calls with per-tool-call budget tracking for agentic workflows
  • streaming_usage.py – Demonstrate the reserve → stream → commit pattern for streaming responses with accurate cost calculation
  • fastapi_integration.py – Show middleware-based preflight checks, dependency injection, per-tenant budget isolation, and exception handling
  • langchain_integration.py – Custom callback handler that wraps each LLM call in a Cycles reservation for budget-aware agents and chains
  • README.md – Documentation and quick-start guide for all examples

• Updated main README.md – Added "Examples" section with a table linking to all example files and their descriptions

Notable Implementation Details

• Decorator pattern: Examples use the @cycles decorator for clean, declarative budget management with estimate/actual cost functions
• Error handling: Demonstrates proper handling of BudgetExceededError and CyclesProtocolError with appropriate HTTP status codes
• Streaming support: Shows how to reserve budget upfront, stream responses, and commit actual costs after completion
• Framework integration:
  • FastAPI middleware for preflight budget checks and per-tenant isolation
  • LangChain callback handler for automatic budget tracking across chain/agent operations
• Async support: Examples include both sync and async patterns where applicable
• Metrics tracking: All examples demonstrate how to capture and report detailed metrics (tokens, latency, model version, custom fields)
• Caps enforcement: Shows how to respect budget authority caps (e.g., max_tokens) when making API calls

All examples include clear documentation, environment variable configuration, and are ready to run with minimal setup.

https://claude.ai/code/session_019RuDwakEwtZDbEMYNvesUF