Metadata-Version: 2.4
Name: boundgraph
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Compilers
Classifier: Typing :: Typed
Summary: The bounded, cost-bounded runtime engine for multi-agent AI systems.
Keywords: agents,llm,sandbox,capabilities,runtime,boundgraph
Author: BoundGraph
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/BoundGraphOrg/boundgraph/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/BoundGraphOrg/boundgraph/tree/main/docs
Project-URL: Homepage, https://github.com/BoundGraphOrg/boundgraph
Project-URL: Issues, https://github.com/BoundGraphOrg/boundgraph/issues
Project-URL: Repository, https://github.com/BoundGraphOrg/boundgraph

# 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

| Primitive | Symbol | Role | Mutability |
|---|---|---|---|
| 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:

| Profile | Name | Guarantees |
|---|---|---|
| **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"] }
```

| Feature | Crate | Layer |
|---|---|---|
| *(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.


