runcycles 0.2.3

Rust client for the Cycles budget-management protocol — deterministic spend control for AI agents and LLM workflows
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

//! RAII guard usage.
//!
//! Demonstrates using the `ReservationGuard` for automatic lifecycle
//! management, including caps checking and commit-by-ownership.

use runcycles::models::*;
use runcycles::{CyclesClient, Error};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = CyclesClient::builder("my-api-key", "http://localhost:7878")
        .tenant("acme")
        .build();

    // Reserve returns an RAII guard
    let guard = match client
        .reserve(
            ReservationCreateRequest::builder()
                .subject(Subject {
                    tenant: Some("acme".into()),
                    ..Default::default()
                })
                .action(Action::new("llm.completion", "gpt-4o"))
                .estimate(Amount::usd_microcents(5000))
                .build(),
        )
        .await
    {
        Ok(guard) => guard,
        Err(Error::BudgetExceeded { message, .. }) => {
            println!("Budget exceeded: {message}");
            return Ok(());
        }
        Err(e) => return Err(e.into()),
    };

    println!("Reserved: {}", guard.reservation_id());
    println!("Decision: {:?}", guard.decision());

    // Check caps for soft constraints
    if guard.is_capped() {
        if let Some(caps) = guard.caps() {
            println!("Max tokens: {:?}", caps.max_tokens);
            if !caps.is_tool_allowed("web_search") {
                println!("web_search is not allowed under caps");
            }
        }
    }

    // Simulate work...

    // Commit consumes the guard (compile-time double-commit prevention)
    guard
        .commit(
            CommitRequest::builder()
                .actual(Amount::usd_microcents(3200))
                .metrics(CyclesMetrics {
                    tokens_input: Some(100),
                    tokens_output: Some(200),
                    ..Default::default()
                })
                .build(),
        )
        .await?;

    // guard.commit(...) here would be a COMPILE ERROR

    Ok(())
}