# BoundGraph
**The zero-trust, cost-bounded runtime engine for multi-agent AI systems.**
BoundGraph governs the exact execution span between when a reasoning engine proposes an action and when a state change commits to the system. It transforms volatile, expensive prompt loops into bounded, auditable, enterprise-grade software execution.
---
## Why BoundGraph
Standard agent frameworks accumulate full conversation transcripts across steps, causing token cost to grow quadratically with the number of steps:
```
Standard Agent Cost: Σ P_i ≈ n·S + (n²/2)·(ō + r̄) → O(n²)
```
BoundGraph enforces strict context admission per step, forcing cost to scale linearly instead:
```
BoundGraph Harness Cost: Σ P_i ≤ n · (s_max + k·ō + k·c) → O(n)
```
Beyond cost, BoundGraph treats every model output as an untrusted proposal rather than a command — no state change reaches your systems without a deterministic, signed evidence check.
---
## The Three Foundation Laws
Every agent, tool, and execution step in a BoundGraph runtime strictly adheres to three mathematical bounds:
### Law I — Authority (Security)
Permissions can only shrink along an execution path: `G₁ ⊑ G₂`. Grants may be attenuated, never widened, and never inherited from ambient surroundings. Permission expansion happens only through explicit, human-gated or policy-checked escalation hooks.
### Law II — Context (Cost Complexity)
A step receives only the exact context tokens (`Γ`) it declares as necessary. Tool execution results are returned as high-density, AST/log-sliced summaries called **Condensates** (`κ`). Input context is truncated once verified Evidence is reached.
### Law III — Evidence (Trust & Verifiability)
Model output is treated strictly as a **Proposal** (`ω`) — never as ground truth. No state change commits based on probabilistic output. A step commits only upon receiving signed **Evidence** (`ε`) from a deterministic checker or statistical quorum.
---
## Architecture
A BoundGraph Step is the tuple `S = (Γ, ω, G, κ, ε, λ)`, executed through a closed-loop, zero-trust pipeline:
```
┌─────────────────────────────────────────────────────┐
│ LAYER 1: UNIFIED INFERENCE ROUTER │
│ (Model speculation / provider failover) │
└───────────────────────┬───────────────────────────────┘
│ Proposes Work Order (ω)
▼
┌─────────────────────────────────────────────────────┐
│ LAYER 2: GRANT COMPILER & GATE │
│ (Statically infers & clamps Grant G) │
└───────────────────────┬───────────────────────────────┘
│ Approved Grant G
▼
┌─────────────────────────────────────────────────────┐
│ LAYER 3: ZERO-TRUST SANDBOX RUNTIME │
│ (Firecracker MicroVM / Wasm sandbox) │
└───────────────────────┬───────────────────────────────┘
│ Raw Output Stream
▼
┌─────────────────────────────────────────────────────┐
│ LAYER 4: SEMANTIC CONTEXT SLICER │
│ (Produces size-capped Condensate κ) │
└───────────────────────┬───────────────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ LAYER 5: DETERMINISTIC CHECKER ENGINE │
│ (Emits signed Evidence ε → Append-only Ledger λ) │
└─────────────────────────────────────────────────────┘
```
---
## Core Primitives
| Work Order | `ω` | Typed declaration of intended effect, tool calls, and requested permissions | Immutable |
| Grant | `G` | Finite set of scoped permission atoms (e.g. `fs:read:src/*`, `net:egress:api.com`) | Immutable |
| Context | `Γ` | The exact admitted token window provided to a reasoner call | Immutable |
| Condensate | `κ` | AST-preserved, size-capped (`c ≪ r̄`) high-density summary of execution results | Immutable |
| Evidence | `ε` | Signed verification verdict produced by a model-free deterministic checker | Immutable |
| Ledger Entry | `λ` | Audit log record capturing token cost, grant attenuation, evidence, and timing | Append-only |
---
## Multi-Agent Combinators
Complex multi-agent topologies are composed using law-preserving algebraic combinators:
- **`seq(a, b)`** — Sequential. Step `b` executes after step `a`. Context passes strictly as a Condensate (`κ_a`). Grants are evaluated independently against the root authority.
- **`par(a, b)`** — Parallel. Steps execute concurrently if and only if their permission sets are proven statically disjoint:
```
W(G_a) ∩ R(G_b) = ∅ ∧ R(G_a) ∩ W(G_b) = ∅ ∧ W(G_a) ∩ W(G_b) = ∅
```
- **`route(r, [a₁..aₙ])`** — Dynamic route. Router model `r` selects an execution branch within a pre-computed static authority envelope `E = G_a₁ ∪ ... ∪ G_aₙ`.
- **`repair(a, v, k)`** — Bounded repair. Caps retry loops at `k` attempts. Prevents quadratic context buildup by resetting input context to base `Γ` plus the latest Condensate `κ` on each attempt.
---
## Conformance Profiles
BoundGraph defines three independently adoptable conformance profiles, letting adopters ramp up incrementally:
| **A** | Accounted | Emits append-only Ledger Entries (`λ`) for token cost, latency, and reasoning-step telemetry |
| **B** | Attenuated | Requires explicit Grants (`G`) on every edge; commits strictly require deterministic Evidence (`ε`) |
| **C** | Isolated | Enforces hardware virtualization (Firecracker MicroVM / Wasm) and journal replayability |
> **Recommended for production:** Profiles A + B + C together deliver the full guarantee set of all three Foundation Laws.
---
## Install
### Python
```console
$ pip install boundgraph
```
Wheels need no Rust toolchain. One `abi3` wheel per platform covers CPython 3.11 and everything after it, for Linux (`x86_64`, `aarch64`), macOS (Apple silicon and Intel) and Windows (`x86_64`); free-threaded wheels are built separately for 3.14t, because a free-threaded interpreter has no stable ABI to target. Anywhere else, `pip` builds from the source distribution and does need a toolchain.
```python
import boundgraph as bg
```
### Rust
```console
$ cargo add boundgraph
```
`boundgraph` is a facade over the layers, and contains no logic of its own — the types are the same types, so depending on it and on a layer directly is not a conflict. The default is `compile` plus `runtime`; every other layer is a feature:
```toml
boundgraph = { version = "0.1", features = ["full"] }
```
| *(always)* | `boundgraph-core` | The primitives: `ω`, `Γ`, `κ`, `ε`, `λ` |
| *(always)* | `boundgraph-grant` | The permission lattice behind Law I |
| *(always)* | `boundgraph-ir` | The Flow IR and the `.bg` file format |
| `compile` | `boundgraph-compile` | Layer 2: Flow → Plan |
| `runtime` *(default)* | `boundgraph-runtime` | The step lifecycle, budgets, recovery |
| `router` | `boundgraph-router` | Layer 1: the inference router |
| `sandbox` | `boundgraph-sandbox` | Layer 3: grants as capabilities |
| `slice` | `boundgraph-slice` | Layer 4: the semantic context slicer |
| `check` | `boundgraph-check` | Layer 5: checkers and evidence signing |
| `ledger` | `boundgraph-ledger` | `λ`: the hash chain, its sinks, and replay |
| `cli` | `boundgraph-cli` | The `bg` commands, as a library |
`full` turns on every layer at its own defaults. The three heaviest options stay outside it: `ledger-sqlite`, `ledger-otel`, and `sandbox-wasm`.
### The `bg` command line
```console
$ cargo install boundgraph-cli
```
---
## Status
**v0.1.0.** All 17 features and 101 user stories are implemented — `docs/TRACKER.md` is the per-story record, and `docs/ARCHITECTURE.md` is the specification they were written against (`v1.0`). The Flow IR is at `v1.4`.
Pre-1.0, so the API may still change. What will not change quietly is the IR: a `.bg` file names the IR version it was written against, and a build that cannot read it says so rather than guessing.