From 5317c379aeb43131d11d0ea8c0807543b0cfafa5 Mon Sep 17 00:00:00 2001 From: Albert Mavashev Date: Sat, 2 May 2026 19:38:58 -0400 Subject: [PATCH] docs(profile): dedupe and tighten the bottom half of README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cuts 354 → 206 lines (-42%) by collapsing overlapping sections. No content removed in spirit; ~5 sections that all answered the same question merged into one each. What changed: - "What is Cycles?" + "What is Runcycles?" + "Quick mental model" + "The ecosystem" → single "## What this is" section. A first-time reader doesn't need the same definition four ways. - "Typical use cases" + "Who Runcycles is for" + "Where Runcycles fits" + "When to use Runcycles" → single "## Who it's for" section. Same reader question answered in one place. - "## How it works" tightened — the diagram + Try-it snippets at the top already showed this; the section now references the diagram and states the loop in one sentence. - "## What Runcycles enforces" converted from 5 sub-headings into a bulleted list. Same content, ~3x denser. - "## Status" gained a CHANGELOG link so it's load-bearing instead of decorative. What was dropped (deliberately): - Mid-page "👉 Learn more: runcycles.io" CTA at line 131 — it sat before 220 more lines of content, reading as a false page-end. - Web3 / EVM / "blockchain transactions" mentions in "Where Runcycles fits" + the defensive "Web3 is one surface area, not a requirement" one-liner. Not active product positioning; reads as holdover. - Wrong docs URL on the old "Learn more" line (runcycles.github.io/docs → fixed to the canonical runcycles.io). What was kept verbatim or near-verbatim: - Top half (lines 1-130): badges, hook, value-prop bullets, CTA links, architecture diagram, GIF demo, Try-it MCP+Python snippets, full Start-here repo list. Untouched. - "Why Runcycles exists" — distinct motivation, kept as-is (slightly tightened from 11 short lines to 2 paragraphs). - "What Runcycles is not" — orthogonal differentiator, useful, kept. - "Design principles" — short and load-bearing, kept verbatim. --- profile/README.md | 202 +++++++--------------------------------------- 1 file changed, 27 insertions(+), 175 deletions(-) diff --git a/profile/README.md b/profile/README.md index 272c8dd..502fb0e 100644 --- a/profile/README.md +++ b/profile/README.md @@ -126,184 +126,54 @@ New to Cycles? Start with the protocol, then choose the implementation surface y ### Demos - [cycles-runaway-demo](https://github.com/runcycles/cycles-runaway-demo) — self-contained demo showing a runaway agent failure mode and Runcycles stopping it -- [cycles-agent-action-authority-demo](https://github.com/runcycles/cycles-agent-action-authority-demo) — self-contained demo showing Cycles stopping agent performing next email, CRM action +- [cycles-agent-action-authority-demo](https://github.com/runcycles/cycles-agent-action-authority-demo) — self-contained demo showing Cycles stopping an agent performing the next email or CRM action -👉 Learn more: **[runcycles.io](https://runcycles.io)** +--- ## Why Runcycles exists -Autonomous systems do not fail like traditional software. - -They loop. -They retry. -They fan out across tools and models. -They continue after partial failure. -They create costs and side effects that are difficult to predict in advance. - -Traditional controls like rate limits, timeouts, and quotas help manage **velocity**. - -They do not reliably bound **total exposure**. - -Runcycles exists to enforce bounded execution under real production conditions. - -## What is Cycles? - -**Cycles** is a protocol for deterministic exposure accounting in autonomous systems. +Autonomous systems do not fail like traditional software. They loop, retry, fan out across tools and models, continue after partial failure, and create costs and side effects that are difficult to predict. -It defines: +Traditional controls — rate limits, timeouts, quotas — manage **velocity**. They do not reliably bound **total exposure**. Runcycles is the runtime layer that does. -- reserve → commit / release semantics -- hierarchical scopes for budgets and policy inheritance -- idempotent behavior under retries and concurrency -- shadow evaluation before hard enforcement -- portable invariants across runtimes and languages +## What this is -Cycles is protocol-first and runtime-agnostic. +**Cycles** is an open, language-agnostic protocol for deterministic exposure accounting in autonomous systems. It defines reserve → commit / release semantics, hierarchical scopes, idempotency under retries, and shadow evaluation before hard enforcement. -## What is Runcycles? +**Runcycles** is the production implementation: a runtime that enforces Cycles semantics over real failure modes — long-running agent loops, tool-calling workflows, retries, crashes, and concurrency. -Runcycles is a production runtime that enforces Cycles semantics. - -It is built for systems with: - -- long-running agent loops -- tool-calling workflows -- multi-step decision systems -- normal retries, crashes, and concurrency - -Runcycles turns Cycles from a specification into something you can deploy. +Think of it as a **budget authority for autonomous execution**: the layer that decides whether an action may proceed, how much exposure to reserve for it, and how that usage is reconciled afterward. Not a billing dashboard, not a workflow engine, not a rate limiter. ## How it works -At a high level, Runcycles enforces a simple pattern: +The diagram above shows the synchronous loop. In one sentence: the SDK reserves estimated exposure with the Cycles runtime *before* the agent's action runs, executes only on `ALLOW`, then commits actual usage or releases the reservation. -1. **Declare intent** -2. **Reserve exposure** -3. **Execute** -4. **Commit actual usage or release the remainder** - -This makes it possible to: - -- stop work before budgets are exceeded -- avoid double-spend under retries -- reconcile actual vs estimated usage -- enforce limits across parent and child scopes -- observe and tune policies before blocking production traffic +This makes it possible to stop work before budgets are exceeded, avoid double-spend under retries, reconcile actual vs estimated usage, enforce limits across parent and child scopes, and run policies in shadow before blocking production traffic. ## What Runcycles enforces -### Deterministic reserve → commit control - -Reserve exposure before execution. -Commit actual usage after execution. -Release unused reservation when work is canceled or costs less than expected. - -### Hierarchical budgeting - -Apply budgets across scopes such as: - -- tenant -- workspace -- app -- workflow -- agent -- toolset - -A request can be evaluated against both local limits and inherited parent limits. Run-level budgets can be modeled through workflow or agent scope patterns where needed. - -### Idempotency under retries and concurrency - -Runcycles is built for real failure modes: - -- duplicate requests -- worker crashes -- partial retries -- concurrent execution -- delayed commits - -### Shadow mode and progressive rollout - -Simulate, observe, and tune policies before turning on hard enforcement. - -### Failure-aware enforcement - -Runcycles is designed for systems where retries, crashes, partial completion, and concurrency are normal operating conditions. - -## Typical use cases +- **Deterministic reserve → commit control** — reserve before execution, commit actual usage after, release on cancel or under-spend +- **Hierarchical budgeting** across `tenant / workspace / app / workflow / agent / toolset` scopes, with inherited parent limits +- **Idempotency under retries and concurrency** — duplicate requests, worker crashes, partial retries, delayed commits all behave correctly +- **Shadow mode and progressive rollout** — simulate and tune policies before turning on hard enforcement +- **Failure-aware enforcement** — designed for systems where crashes and partial completion are normal -Runcycles is useful when you need deterministic control over systems that: +## Who it's for -- call LLMs repeatedly or recursively -- invoke tools with external cost or side effects -- execute background jobs or long-lived workflows -- operate across tenants with separate budgets -- need hard boundaries around autonomous execution -- must distinguish observation from enforcement - -## Who Runcycles is for - -Runcycles is for teams building autonomous systems that can create meaningful cost, side effects, or operational risk. - -Typical users include: +Teams building autonomous systems that can create meaningful cost, side effects, or operational risk: - **AI platform teams** enforcing tenant and workload budgets - **Agent developers** building looped or tool-calling workflows -- **Spring AI / JVM teams** adding hard budget limits to production systems -- **SaaS teams** needing multi-tenant usage isolation and controls -- **Infrastructure engineers** handling retries, concurrency, and partial failure safely +- **Spring AI / JVM teams** adding hard budget limits to production +- **SaaS operators** needing multi-tenant usage isolation - **Gateway builders** adding reservation and commit semantics to AI traffic -Runcycles is most useful when you need more than rate limits or dashboards — you need **pre-execution budget enforcement**. - -## Quick mental model - -Think of Runcycles as a **budget authority for autonomous execution**. - -Not a billing dashboard. -Not a workflow engine. -Not a rate limiter. - -It is the runtime layer that decides whether an action may proceed, how much exposure is reserved for it, and how that usage is reconciled afterward. - -## The ecosystem - -### Cycles Protocol -The open, language-agnostic specification for exposure accounting, reservations, commits, releases, scopes, and invariants. - -### Runcycles Runtime -A production implementation that enforces Cycles semantics efficiently. - -### SDKs and clients -Client libraries for integrating Cycles into applications and runtimes. - -Current implementation focus includes: - -- [Python](https://github.com/runcycles/cycles-client-python) -- [Rust](https://github.com/runcycles/cycles-client-rust) -- [TypeScript Node.js / Next.js](https://github.com/runcycles/cycles-client-typescript) -- [Java / Spring Boot](https://github.com/runcycles/cycles-spring-boot-starter) +It governs anything that creates cost, risk, or irreversible side effects — LLM and inference calls, external APIs, database writes, message dispatch, payments, deployments, workflow fan-out. -Additional language clients can be added without changing the protocol. - -## Where Runcycles fits - -Runcycles integrates with systems that produce cost, risk, or irreversible side effects, including: - -- LLM and inference calls -- external APIs -- database writes -- message dispatch -- payments -- deployments -- workflow fan-out -- EVM and other blockchain transactions - -Web3 is one surface area, not a requirement. +Use it when you need hard spend boundaries, pre-execution budget checks, retry-safe accounting, tenant-aware limits, hierarchical policy control, or progressive rollout from shadow to enforcement. **If all you need is request throttling or usage analytics, Runcycles is not the right tool.** ## What Runcycles is not -Runcycles is not: - - a billing system - a token or rewards engine - an observability-only dashboard @@ -311,27 +181,10 @@ Runcycles is not: - a generic workflow scheduler - an AI safety silver bullet -Its purpose is specific: - -**make autonomous exposure explicit, bounded, and enforceable.** - -## When to use Runcycles - -Use Runcycles when your system needs: - -- hard spend boundaries -- pre-execution budget checks -- retry-safe accounting -- tenant-aware limits -- hierarchical policy control -- progressive rollout from shadow mode to enforcement - -If all you need is request throttling or simple usage analytics, Runcycles is probably not the right tool. +Its purpose is specific: **make autonomous exposure explicit, bounded, and enforceable.** ## Design principles -Runcycles is built around a few core ideas: - - **account before enforce** - **reserve before execute** - **commit actuals, release remainder** @@ -342,13 +195,12 @@ Runcycles is built around a few core ideas: ## Status -Runcycles is under active development. - -The protocol is stabilizing through real implementation work and will evolve with strong compatibility discipline as it moves toward v1. +Runcycles is under active development. The protocol is stabilizing through real implementation work and will evolve with strong compatibility discipline as it moves toward v1. See [CHANGELOG.md](https://github.com/runcycles/cycles-server/blob/main/CHANGELOG.md) on `cycles-server` for the current release cadence. ## Learn more -- [Cycles Manifesto](./MANIFESTO.md) -- [Cycles Docs and API Reference](https://runcycles.github.io/docs) +- **[runcycles.io](https://runcycles.io)** — full documentation, API reference, integration guides +- [Cycles Manifesto](./MANIFESTO.md) — the longer "why" +- [ARCHITECTURE.md](https://github.com/runcycles/.github/blob/main/ARCHITECTURE.md) — full system diagram with admin server, dashboard, state store, and event bus -If you are building autonomous systems and need deterministic control over exposure, Runcycles is the runtime layer for that job. +If you're building autonomous systems and need deterministic control over exposure, Runcycles is the runtime layer for that job.