Release version 1.1.0: Introduced a high-level API for zero-boilerplate integration with the Capsules class, @capsules.audit() decorator, and capsules.current() context variable. Added FastAPI integration with three read-only endpoints. Included 33 new tests and ensured no existing files were modified. Updated documentation and examples to reflect new features.

Author: bradleygauthier

CHANGELOG.md

@@ -7,6 +7,27 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.1.0] - 2026-03-07
+
+High-level API for zero-boilerplate integration. One class, one decorator, one context variable.
+
+### Added
+
+- **`Capsules` class** — single entry point that owns storage, chain, and seal. Zero-config default (`Capsules()` uses SQLite), PostgreSQL via URL string, or custom storage backend via `storage=` kwarg.
+- **`@capsules.audit()` decorator** — wraps any async or sync function with automatic Capsule creation, sealing, and storage. Supports `type`, `tenant_from`, `tenant_id`, `trigger_from`, `source`, `domain`, and `swallow_errors` parameters.
+- **`capsules.current()` context variable** — access and enrich the active Capsule during execution (set model, confidence, session, resources, summary).
+- **`mount_capsules()` FastAPI integration** — mount three read-only endpoints (`GET /`, `GET /{id}`, `GET /verify`) onto any FastAPI application. FastAPI is not a hard dependency.
+- **33 new tests** (23 audit + 10 FastAPI) — init variants, success/failure paths, swallow/propagate errors, tenant extraction, trigger extraction, source, context variable enrichment, sync support, timing, type resolution, FastAPI routes.
+
+### Design Principles
+
+- **Zero new dependencies** — uses only stdlib (`contextvars`, `logging`, `inspect`, `functools`). FastAPI import is guarded.
+- **Additive only** — no existing files modified. All 361 existing tests pass unchanged.
+- **Never blocks user code** — capsule errors are swallowed by default (`swallow_errors=True`). Decorated function's return value, exceptions, and timing are preserved exactly.
+- **Progressively enrichable** — start with just the decorator, add `current()` enrichment later.
+
+---
+
 ## [1.0.0] - 2026-03-07
 
 Initial public release of the Capsule Protocol Specification (CPS) v1.0 reference implementation.
@@ -42,4 +63,5 @@ Initial public release of the Capsule Protocol Specification (CPS) v1.0 referenc
 
 ---
 
+[1.1.0]: https://github.com/quantumpipes/capsule/releases/tag/v1.1.0
 [1.0.0]: https://github.com/quantumpipes/capsule/releases/tag/v1.0.0

README.md

@@ -2,7 +2,9 @@
 
 # Capsule Protocol Specification (CPS)
 
-**Tamper-evident audit records for AI operations.**
+**Know what your AI did, why it did it, and who approved it — with cryptographic proof.**
+
+*Tamper-evident audit records for AI operations.*
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python](https://img.shields.io/badge/Python-3.11+-3776AB.svg)](https://www.python.org/)
@@ -141,6 +143,83 @@ result = await chain.verify()
 assert result.valid
 ```
 
+### What a Sealed Capsule Looks Like
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "type": "agent",
+  "trigger": {
+    "source": "deploy-bot",
+    "request": "Deploy service v2.4 to production"
+  },
+  "reasoning": {
+    "options_considered": ["Deploy v2.4", "Rollback to v2.3", "Do nothing"],
+    "selected_option": "Deploy v2.4",
+    "confidence": 0.92
+  },
+  "authority": { "type": "human_approved", "approver": "ops-lead" },
+  "execution": {
+    "tool_calls": [{ "tool": "kubectl_apply", "success": true, "duration_ms": 3200 }]
+  },
+  "outcome": { "status": "success", "summary": "Deployed v2.4 to prod-us-east" },
+  "hash": "4cb02d65...",
+  "signature": "a3f8b2c1...",
+  "previous_hash": "7d2e9f41...",
+  "sequence": 42
+}
+```
+
+Six sections. Hashed with SHA3-256. Signed with Ed25519. Chained to the previous record. Reasoning captured *before* execution.
+
+### High-Level API
+
+The fastest way to add audit trails to any Python application. One class, one decorator.
+
+```bash
+pip install qp-capsule[storage]
+```
+
+```python
+from qp_capsule import Capsules
+
+capsules = Capsules()  # SQLite, zero config
+
+@capsules.audit(type="agent")
+async def run_agent(task: str, *, site_id: str):
+    cap = capsules.current()
+    cap.reasoning.model = "gpt-4o"
+    cap.reasoning.confidence = 0.92
+
+    result = await llm.complete(task)
+    cap.outcome.summary = f"Generated {len(result.text)} chars"
+    return result
+
+# Every call is now audited with a sealed Capsule.
+# If capsule creation fails, your function still works normally.
+await run_agent("Write a summary", site_id="tenant-123")
+```
+
+**PostgreSQL:**
+
+```python
+capsules = Capsules("postgresql://user:pass@localhost/mydb")
+```
+
+**FastAPI integration** — three read-only endpoints for inspecting the audit chain:
+
+```python
+from qp_capsule.integrations.fastapi import mount_capsules
+
+app = FastAPI()
+mount_capsules(app, capsules, prefix="/api/v1/capsules")
+# GET /api/v1/capsules/         — List (paginated, filterable)
+# GET /api/v1/capsules/{id}     — Get by ID
+# GET /api/v1/capsules/verify   — Verify chain integrity
+```
+
+See [High-Level API docs](./docs/high-level-api.md) for the full guide.
+
 ---
 
 ## Install
@@ -207,6 +286,7 @@ Capsule ships with SQLite and PostgreSQL storage. To build your own backend, imp
 
 | Document | Audience |
 |---|---|
+| [High-Level API](./docs/high-level-api.md) | Developers |
 | [Getting Started](./docs/getting-started.md) | Developers |
 | [Architecture](./docs/architecture.md) | Developers, Auditors |
 | [API Reference](./docs/api.md) | Developers |

docs/api.md

@@ -3,11 +3,12 @@ title: "API Reference"
 description: "Complete API reference for Capsule: every class, method, parameter, and type."
 date_modified: "2026-03-07"
 ai_context: |
-  Complete Python API reference for the qp-capsule package. Covers Capsule model
+  Complete Python API reference for the qp-capsule package v1.1.0. Covers Capsule model
   (6 sections, 8 CapsuleTypes), Seal (seal, verify, verify_with_key, compute_hash),
   CapsuleChain (add, verify, seal_and_store), CapsuleStorageProtocol (7 methods),
-  CapsuleStorage (SQLite), PostgresCapsuleStorage (multi-tenant), and exception hierarchy.
-  All signatures verified against source.
+  CapsuleStorage (SQLite), PostgresCapsuleStorage (multi-tenant), exception hierarchy,
+  and the v1.1.0 high-level API: Capsules class, @audit() decorator, current() context
+  variable, and mount_capsules() FastAPI integration. All signatures verified against source.
 ---
 
 # API Reference
@@ -20,6 +21,9 @@ ai_context: |
 
 ```python
 from qp_capsule import (
+    # High-Level API (v1.1.0+)
+    Capsules,
+
     # Capsule Model
     Capsule, CapsuleType,
     TriggerSection, ContextSection,
@@ -43,6 +47,9 @@ from qp_capsule import (
     # Exceptions
     CapsuleError, SealError, ChainError, StorageError,
 )
+
+# FastAPI Integration (optional, requires fastapi)
+from qp_capsule.integrations.fastapi import mount_capsules
 ```
 
 ---
@@ -495,8 +502,116 @@ asyncio.run(main())
 
 ---
 
+## Capsules (High-Level API)
+
+> **Added in v1.1.0.**
+
+Single entry point that owns storage, chain, and seal internally.
+
+<!-- VERIFIED: src/qp_capsule/audit.py:130-216 -->
+
+```python
+class Capsules:
+    def __init__(
+        self,
+        url: str | None = None,
+        *,
+        storage: CapsuleStorageProtocol | None = None,
+    )
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str \| None` | `None` | `None` = SQLite default; `"postgresql://..."` = PostgreSQL; other string = SQLite at path |
+| `storage` | `CapsuleStorageProtocol \| None` | `None` | Custom storage backend (overrides `url`) |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `storage` | `CapsuleStorageProtocol` | The underlying storage backend |
+| `chain` | `CapsuleChain` | The hash chain instance |
+| `seal` | `Seal` | The Ed25519 sealing instance |
+
+### Methods
+
+**`current() -> Capsule`**
+Get the active Capsule inside an `@audit()` decorated function. Raises `RuntimeError` if called outside.
+
+**`async close() -> None`**
+Release storage backend resources.
+
+**`audit(*, type, tenant_from=None, tenant_id=None, trigger_from=0, source=None, domain="agents", swallow_errors=True) -> Callable`**
+Decorator factory. See below.
+
+---
+
+## @capsules.audit() Decorator
+
+<!-- VERIFIED: src/qp_capsule/audit.py:218-389 -->
+
+Wraps any async or sync function with automatic Capsule creation, sealing, and storage.
+
+```python
+@capsules.audit(type="agent", tenant_from="site_id")
+async def run_agent(task: str, *, site_id: str):
+    cap = capsules.current()
+    cap.reasoning.model = "gpt-4o"
+    result = await llm.complete(task)
+    return result
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `type` | `str \| CapsuleType` | *(required)* | Capsule type |
+| `tenant_from` | `str \| None` | `None` | Kwarg name to extract `tenant_id` from |
+| `tenant_id` | `str \| Callable \| None` | `None` | Static string or `(args, kwargs) -> str` |
+| `trigger_from` | `str \| int \| None` | `0` | Arg name or position for `trigger.request` |
+| `source` | `str \| None` | `None` | Static `trigger.source` (default: function qualname) |
+| `domain` | `str` | `"agents"` | Capsule domain |
+| `swallow_errors` | `bool` | `True` | If `True`, capsule failures are logged and swallowed |
+
+**Guarantees:**
+- Return value is never modified
+- Exceptions are always re-raised
+- Timing is not measurably affected
+- Capsule errors never block the decorated function (when `swallow_errors=True`)
+
+---
+
+## mount_capsules() (FastAPI Integration)
+
+<!-- VERIFIED: src/qp_capsule/integrations/fastapi.py:36-113 -->
+
+```python
+from qp_capsule.integrations.fastapi import mount_capsules
+
+mount_capsules(app, capsules, prefix="/api/v1/capsules")
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `app` | `FastAPI` | *(required)* | FastAPI application |
+| `capsules` | `Capsules` | *(required)* | Initialized `Capsules` instance |
+| `prefix` | `str` | `"/api/v1/capsules"` | URL prefix |
+
+**Endpoints added:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `{prefix}/` | List capsules (query: `limit`, `offset`, `type`, `tenant_id`) |
+| GET | `{prefix}/verify` | Verify chain integrity (query: `tenant_id`) |
+| GET | `{prefix}/{capsule_id}` | Get capsule by ID (404 if missing) |
+
+FastAPI is not a hard dependency. Raises `CapsuleError` if not installed.
+
+**Security note:** These endpoints are read-only and do not add authentication. Protect them with your application's auth middleware in production.
+
+---
+
 ## Related Documentation
 
+- [High-Level API Guide](./high-level-api.md) — Full walkthrough with examples
 - [Getting Started](./getting-started.md) — Quick introduction with minimal code
 - [Architecture](./architecture.md) — How these components fit together
 - [Security Evaluation](./security.md) — Cryptographic guarantees

docs/getting-started.md

@@ -170,8 +170,82 @@ Reasoning is captured **before** execution. This provides contemporaneous eviden
 
 ---
 
+## Tamper Detection
+
+This is what makes Capsule different from logging. Seal a Capsule, tamper with it, and watch verification catch it:
+
+<!-- VERIFIED: src/qp_capsule/seal.py:338-385 -->
+
+```python
+from qp_capsule import Capsule, Seal, CapsuleType, TriggerSection
+
+capsule = Capsule(
+    type=CapsuleType.AGENT,
+    trigger=TriggerSection(source="test", request="Original request"),
+)
+
+seal = Seal()
+seal.seal(capsule)
+
+# Verification passes
+assert seal.verify(capsule)
+print("Before tampering: VALID")
+
+# Now tamper with the content
+capsule.trigger.request = "Altered request"
+
+# Verification FAILS — the hash no longer matches the content
+assert not seal.verify(capsule)
+print("After tampering:  INVALID — tamper detected")
+```
+
+**Expected output:**
+
+```
+Before tampering: VALID
+After tampering:  INVALID — tamper detected
+```
+
+The hash was computed from the original content. When the content changed, the hash no longer matched. No log rotation, no admin privilege, no database access can make a tampered Capsule pass verification.
+
+---
+
+## High-Level API (v1.1.0+)
+
+For most integrations, the high-level API is the fastest path. One class, one decorator:
+
+```bash
+pip install qp-capsule[storage]
+```
+
+<!-- VERIFIED: src/qp_capsule/audit.py:130-216 -->
+
+```python
+from qp_capsule import Capsules
+
+capsules = Capsules()
+
+@capsules.audit(type="agent")
+async def run_agent(task: str):
+    cap = capsules.current()
+    cap.reasoning.model = "gpt-4o"
+    cap.reasoning.confidence = 0.92
+    result = await llm.complete(task)
+    cap.outcome.summary = f"Generated {len(result.text)} chars"
+    return result
+
+await run_agent("Write a summary of Q1 results")
+```
+
+The decorator handles Capsule creation, sealing, chaining, and storage automatically. If capsule creation fails, your function still works normally.
+
+See [High-Level API](./high-level-api.md) for the full guide.
+
+---
+
 ## What's Next
 
+- [High-Level API](./high-level-api.md) — `Capsules`, `@audit`, `current()`, FastAPI integration
 - [Architecture](./architecture.md) — Deep dive on the 6-section model, cryptographic sealing, and hash chain
 - [API Reference](./api.md) — Every class, method, and parameter
 - [Security Evaluation](./security.md) — Cryptographic guarantees for security teams