{"id":47978183,"url":"https://github.com/runcycles/cycles-client-rust","last_synced_at":"2026-04-06T12:00:45.970Z","repository":{"id":348246086,"uuid":"1197044024","full_name":"runcycles/cycles-client-rust","owner":"runcycles","description":"Rust client for Cycles — runtime budget authority for AI agents","archived":false,"fork":false,"pushed_at":"2026-04-02T20:29:58.000Z","size":180,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T10:58:48.971Z","etag":null,"topics":["ai-agents","ai-governance","anthropic","cost-control","cycles-client","cycles-protocol","openai","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runcycles.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"AUDIT.md","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T09:24:01.000Z","updated_at":"2026-04-02T20:23:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/runcycles/cycles-client-rust","commit_stats":null,"previous_names":["runcycles/cycles-client-rust"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/runcycles/cycles-client-rust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runcycles%2Fcycles-client-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runcycles%2Fcycles-client-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runcycles%2Fcycles-client-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runcycles%2Fcycles-client-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runcycles","download_url":"https://codeload.github.com/runcycles/cycles-client-rust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runcycles%2Fcycles-client-rust/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31397056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-governance","anthropic","cost-control","cycles-client","cycles-protocol","openai","rust"],"created_at":"2026-04-04T10:58:50.458Z","updated_at":"2026-04-04T10:58:50.958Z","avatar_url":"https://github.com/runcycles.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Crates.io](https://img.shields.io/crates/v/runcycles)](https://crates.io/crates/runcycles)\n[![docs.rs](https://img.shields.io/docsrs/runcycles)](https://docs.rs/runcycles)\n[![CI](https://github.com/runcycles/cycles-client-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/runcycles/cycles-client-rust/actions)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)\n[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](https://github.com/runcycles/cycles-client-rust/actions)\n\n# Cycles Rust Client\n\nRust client for the [Cycles](https://runcycles.io) budget-management protocol — deterministic spend control for AI agents and LLM workflows.\n\nCycles provides concurrency-safe spend and action control for autonomous agent\nruntimes. This crate implements the reserve-execute-commit lifecycle with an\nidiomatic Rust API built around RAII guards and ownership semantics.\n\n## Installation\n\n```toml\n[dependencies]\nruncycles = \"0.2\"\n```\n\n## Quick Start — Automatic Lifecycle (`with_cycles`)\n\nLike Python's `@cycles` decorator or TypeScript's `withCycles`. Reserve, execute,\nand commit/release are handled automatically:\n\n```rust,no_run\nuse runcycles::{CyclesClient, with_cycles, WithCyclesConfig, models::*};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), runcycles::Error\u003e {\n    let client = CyclesClient::builder(\"my-api-key\", \"http://localhost:7878\")\n        .tenant(\"acme\")\n        .build();\n\n    let reply = with_cycles(\n        \u0026client,\n        WithCyclesConfig::new(Amount::tokens(1000))\n            .action(\"llm.completion\", \"gpt-4o\")\n            .subject(Subject { tenant: Some(\"acme\".into()), ..Default::default() }),\n        |ctx| async move {\n            // ctx.caps, ctx.decision, ctx.reservation_id available\n            let result = call_llm(\"Hello\").await;\n            Ok((result, Amount::tokens(42)))   // (return_value, actual_cost)\n        },\n    ).await?;\n    // On success → auto-commits. On error → auto-releases.\n\n    println!(\"LLM said: {reply}\");\n    Ok(())\n}\n# async fn call_llm(_: \u0026str) -\u003e String { \"hi\".into() }\n```\n\n## Manual Control — RAII Guard\n\nFor streaming, multi-step workflows, or when you need full control:\n\n```rust,no_run\nuse runcycles::{CyclesClient, Error, models::*};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Error\u003e {\n    let client = CyclesClient::builder(\"my-api-key\", \"http://localhost:7878\")\n        .tenant(\"acme\")\n        .build();\n\n    // Reserve budget — returns an RAII guard\n    let guard = client.reserve(\n        ReservationCreateRequest::builder()\n            .subject(Subject { tenant: Some(\"acme\".into()), ..Default::default() })\n            .action(Action::new(\"llm.completion\", \"gpt-4o\"))\n            .estimate(Amount::usd_microcents(5000))\n            .build()\n    ).await?;\n\n    // Check caps if decision is AllowWithCaps\n    if let Some(caps) = guard.caps() {\n        println!(\"max_tokens: {:?}\", caps.max_tokens);\n    }\n\n    // ... perform the guarded operation ...\n\n    // Commit actual spend (consumes the guard — cannot double-commit)\n    guard.commit(\n        CommitRequest::builder()\n            .actual(Amount::usd_microcents(3200))\n            .build()\n    ).await?;\n\n    Ok(())\n}\n```\n\n## Design\n\nThe Rust client is not a port — it is designed from the ground up around Rust's\ntype system and ownership model:\n\n| Feature | How |\n|---------|-----|\n| **No double-commit** | `commit(self)` consumes the guard — compile error to reuse |\n| **No forgotten reservations** | `#[must_use]` warns if guard is ignored |\n| **Auto-cleanup** | `Drop` does best-effort release via `tokio::spawn` |\n| **Type-safe IDs** | `ReservationId`, `IdempotencyKey` newtypes prevent mixups |\n| **Forward-compatible** | `#[non_exhaustive]` enums for protocol evolution |\n| **Zero mapper code** | `serde` with `rename_all` handles wire format natively |\n\n### RAII Guard\n\nThe `ReservationGuard` gives manual control over the lifecycle. It holds a live\nreservation and auto-extends TTL via a background heartbeat. The guard IS the\ncontext — no thread-locals or task-locals needed.\n\n```rust,no_run\n# use runcycles::{CyclesClient, Error, models::*};\n# async fn example(client: CyclesClient) -\u003e Result\u003c(), Error\u003e {\nlet guard = client.reserve(/* ... */\n# ReservationCreateRequest::builder()\n#     .subject(Subject { tenant: Some(\"acme\".into()), ..Default::default() })\n#     .action(Action::new(\"llm.completion\", \"gpt-4o\"))\n#     .estimate(Amount::usd_microcents(5000))\n#     .build()\n).await?;\n\n// The guard provides all context\nguard.reservation_id();  // \u0026ReservationId\nguard.decision();        // Decision::Allow or AllowWithCaps\nguard.caps();            // Option\u003c\u0026Caps\u003e\nguard.is_capped();       // bool\nguard.affected_scopes(); // \u0026[String]\n\n// Commit or release (both consume `self`)\nguard.commit(CommitRequest::builder().actual(Amount::usd_microcents(3200)).build()).await?;\n// guard.commit(...) here would be a COMPILE ERROR\n# Ok(())\n# }\n```\n\n### Low-Level Client\n\nFor full control, use the client methods directly:\n\n```rust,no_run\n# use runcycles::{CyclesClient, models::*};\n# async fn example(client: CyclesClient) -\u003e Result\u003c(), runcycles::Error\u003e {\nlet resp = client.create_reservation(\u0026ReservationCreateRequest::builder()\n    .subject(Subject { tenant: Some(\"acme\".into()), ..Default::default() })\n    .action(Action::new(\"llm.completion\", \"gpt-4o\"))\n    .estimate(Amount::usd_microcents(5000))\n    .build()\n).await?;\n\nif resp.decision.is_allowed() {\n    let id = resp.reservation_id.unwrap();\n    // ... do work ...\n    client.commit_reservation(\u0026id, \u0026CommitRequest::builder()\n        .actual(Amount::usd_microcents(3200))\n        .build()\n    ).await?;\n}\n# Ok(())\n# }\n```\n\n## Error Handling\n\nErrors use pattern matching:\n\n```rust,no_run\nuse runcycles::Error;\n\n# fn example(err: Error) {\nmatch err {\n    Error::BudgetExceeded { message, .. } =\u003e {\n        println!(\"Budget exceeded: {}\", message);\n    }\n    Error::Api { status, code, .. } =\u003e {\n        println!(\"API error ({}): {:?}\", status, code);\n    }\n    Error::Transport(e) =\u003e {\n        println!(\"Network error: {}\", e);\n    }\n    _ =\u003e {}\n}\n# }\n```\n\n## Configuration\n\n### From code\n\n```rust,no_run\n# use runcycles::CyclesClient;\nlet client = CyclesClient::builder(\"my-api-key\", \"http://localhost:7878\")\n    .tenant(\"acme\")\n    .workspace(\"production\")\n    .connect_timeout(std::time::Duration::from_secs(2))\n    .read_timeout(std::time::Duration::from_secs(5))\n    .retry_enabled(true)\n    .retry_max_attempts(5)\n    .build();\n```\n\n### From environment\n\n```rust,no_run\n# use runcycles::{CyclesClient, CyclesConfig};\n// Reads CYCLES_BASE_URL, CYCLES_API_KEY, CYCLES_TENANT, etc.\nlet config = CyclesConfig::from_env().expect(\"missing env vars\");\nlet client = CyclesClient::new(config);\n```\n\n## Features\n\n| Feature | Default | Description |\n|---------|---------|-------------|\n| `rustls-tls` | Yes | Use rustls for TLS |\n| `native-tls` | No | Use platform-native TLS |\n| `blocking` | No | Synchronous blocking client |\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruncycles%2Fcycles-client-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruncycles%2Fcycles-client-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruncycles%2Fcycles-client-rust/lists"}