Capsule Protocol — Python Reference Implementation

The canonical implementation of the Capsule Protocol Specification (CPS).

Install

pip install qp-capsule

Quick Start

from qp_capsule import Capsule, Seal, CapsuleType, TriggerSection

capsule = Capsule(
    type=CapsuleType.AGENT,
    trigger=TriggerSection(
        source="deploy-bot",
        request="Deploy service v2.4 to production",
    ),
)

seal = Seal()
seal.seal(capsule)
assert seal.verify(capsule)

With Hash Chain

from qp_capsule import Capsule, Seal, CapsuleChain, CapsuleStorage, CapsuleType, TriggerSection

storage = CapsuleStorage()
chain = CapsuleChain(storage)
seal = Seal()

capsule = Capsule(
    type=CapsuleType.AGENT,
    trigger=TriggerSection(source="deploy-bot", request="Deploy v2.4"),
)

capsule = await chain.seal_and_store(capsule, seal)

result = await chain.verify()
assert result.valid

High-Level API

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

await run_agent("Write a summary", site_id="tenant-123")

FastAPI Integration

from qp_capsule.integrations.fastapi import mount_capsules

app = FastAPI()
mount_capsules(app, capsules, prefix="/api/v1/capsules")

Conformance

This implementation passes all 16 golden test vectors:

cd reference/python
make test-golden

Documentation

Development

cd reference/python
pip install -e ".[dev,storage]"
make test          # 350 tests, 100% coverage
make lint          # ruff check
make typecheck     # mypy strict
make test-golden   # Conformance tests only
make test-all      # lint + typecheck + test + golden

License

Apache License 2.0 with additional patent grant.