Skip to content

Commit 861d18a

Browse files
bradleygauthierbradleygauthier
committed
Document ecosystem: capsule-go and capsule-litellm
README: restructure implementations section into Reference Implementations (this repo) and Ecosystem Libraries (separate repos). Add Quick Start sections for Go verification and LiteLLM integration alongside existing Python and TypeScript. Update footer links to include all four languages. docs/README.md: add Ecosystem Libraries section documenting capsule-go (Go verifier) and capsule-litellm (LiteLLM callback). docs/architecture.md: add Ecosystem section with ASCII diagram showing protocol, reference impls, ecosystem libs, and integrations. Document capsule-go (verification-only design, use cases) and capsule-litellm (prompt hashing, swallow_errors, two-line integration).
1 parent a1b92a4 commit 861d18a

3 files changed

Lines changed: 140 additions & 24 deletions

File tree

‎README.md‎

Lines changed: 76 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -121,14 +121,10 @@ The **Capsule Protocol Specification (CPS)** defines the complete protocol:
121121
|---|---|
122122
| [CPS v1.0](./spec/) | Record structure, canonical serialization, sealing algorithm, hash chain rules |
123123
| [URI Scheme](./spec/uri-scheme.md) | `capsule://` content-addressable references |
124-
| [Conformance Suite](./conformance/) | 16 golden test vectors for cross-language verification |
124+
| [Conformance Suite](./conformance/) | 16 golden vectors (valid) + 15 negative vectors (invalid) |
125125

126126
The specification is language-agnostic. Any implementation that passes the conformance suite can seal and verify Capsules produced by any other.
127127

128-
```
129-
Language A (seal) ──→ Canonical JSON + SHA3-256 + Ed25519 ──→ Language B (verify) ✓
130-
```
131-
132128
---
133129

134130
## Example Capsule
@@ -164,16 +160,32 @@ See more examples in [`examples/`](./examples/).
164160

165161
---
166162

167-
## Reference Implementations
163+
## Implementations
164+
165+
### Reference Implementations
166+
167+
These live in this repository and define correct behavior for each language.
168168

169169
| Language | Status | Install | Source |
170170
|---|---|---|---|
171-
| **Python** | v1.3.0 (stable) | `pip install qp-capsule` | [`reference/python/`](./reference/python/) |
172-
| **TypeScript** | v0.0.1 (conformant, 16/16 fixtures) | `npm install @quantumpipes/capsule` | [`reference/typescript/`](./reference/typescript/) |
173-
| Go | Separate repo (planned) | — | [quantumpipes/capsule-go](https://github.com/quantumpipes/capsule-go) |
174-
| Rust | Separate repo (planned) | — | [quantumpipes/capsule-rust](https://github.com/quantumpipes/capsule-rust) |
171+
| **Python** | v1.3.0 — create, seal, verify, chain, store, CLI | `pip install qp-capsule` | [`reference/python/`](./reference/python/) |
172+
| **TypeScript** | v0.0.1 — create, seal, verify, chain | `npm install @quantumpipes/capsule` | [`reference/typescript/`](./reference/typescript/) |
173+
174+
### Ecosystem Libraries
175+
176+
These extend the protocol to new languages and frameworks.
177+
178+
| Library | Purpose | Install | Source |
179+
|---|---|---|---|
180+
| **[capsule-go](https://github.com/quantumpipes/capsule-go)** | Verify Capsules in Go | `go get github.com/quantumpipes/capsule-go` | [quantumpipes/capsule-go](https://github.com/quantumpipes/capsule-go) |
181+
| **[capsule-litellm](https://github.com/quantumpipes/capsule-litellm)** | Automatic audit trail for LiteLLM | `pip install capsule-litellm` | [quantumpipes/capsule-litellm](https://github.com/quantumpipes/capsule-litellm) |
182+
| capsule-rust | Verify Capsules in Rust | — | Planned |
183+
184+
All implementations must pass the [conformance suite](./conformance/). The specification is the source of truth.
175185

176-
All reference implementations must pass the [conformance suite](./conformance/). The specification is the source of truth; implementations follow.
186+
```
187+
Language A (seal) ──→ Canonical JSON + SHA3-256 + Ed25519 ──→ Language B (verify) ✓
188+
```
177189

178190
### Quick Start (Python)
179191

@@ -197,23 +209,47 @@ seal.seal(capsule)
197209
assert seal.verify(capsule)
198210
```
199211

200-
### CLI
212+
### Quick Start (Go — Verification)
201213

202-
The Python package includes a CLI for verification, inspection, and key management:
214+
```bash
215+
go get github.com/quantumpipes/capsule-go
216+
```
217+
218+
```go
219+
import capsule "github.com/quantumpipes/capsule-go"
220+
221+
// Verify a capsule's hash integrity
222+
valid := capsule.VerifyHash(capsuleDict, expectedHash)
223+
224+
// Verify an Ed25519 signature
225+
valid := capsule.VerifySignature(hashHex, signatureHex, publicKeyHex)
226+
227+
// Verify an entire chain (structural + cryptographic)
228+
errs := capsule.VerifyChainFull(sealedCapsules)
229+
```
230+
231+
The Go library is verification-only by design. Seal in any language, verify in Go — infrastructure tooling, CI gates, and audit pipelines can validate Capsules without a full SDK.
232+
233+
### Quick Start (LiteLLM Integration)
203234

204235
```bash
205-
capsule verify chain.json # Structural verification
206-
capsule verify --full --db capsules.db # + SHA3-256 recomputation
207-
capsule verify --signatures --json chain.json # + Ed25519, JSON output
208-
capsule inspect --db capsules.db --seq 47 # Full 6-section display
209-
capsule keys info # Epoch history
210-
capsule keys rotate # Rotate to new key (no downtime)
211-
capsule hash document.pdf # SHA3-256 of any file
236+
pip install capsule-litellm
212237
```
213238

214-
Exit codes: `0` = pass, `1` = fail, `2` = error. Designed for CI/CD gates: `capsule verify --quiet && deploy`.
239+
```python
240+
import litellm
241+
from capsule_litellm import CapsuleLogger
215242

216-
See the [Python reference documentation](./reference/python/) for the full guide.
243+
litellm.callbacks = [CapsuleLogger()]
244+
245+
# Every LLM call now produces a sealed Capsule automatically
246+
response = litellm.completion(
247+
model="gpt-4o",
248+
messages=[{"role": "user", "content": "Deploy service v2.4"}],
249+
)
250+
```
251+
252+
Two lines of code. Every `litellm.completion()` and `litellm.acompletion()` call produces a sealed, hash-chained Capsule with the model identity, SHA3-256 prompt hash, token metrics, and latency — without touching your application code.
217253

218254
### Quick Start (TypeScript)
219255

@@ -241,7 +277,23 @@ await seal(capsule, privateKey);
241277
console.log(await verify(capsule, await publicKey)); // true
242278
```
243279

244-
See the [TypeScript reference documentation](./reference/typescript/) for the full guide.
280+
### CLI
281+
282+
The Python package includes a CLI for verification, inspection, and key management:
283+
284+
```bash
285+
capsule verify chain.json # Structural verification
286+
capsule verify --full --db capsules.db # + SHA3-256 recomputation
287+
capsule verify --signatures --json chain.json # + Ed25519, JSON output
288+
capsule inspect --db capsules.db --seq 47 # Full 6-section display
289+
capsule keys info # Epoch history
290+
capsule keys rotate # Rotate to new key (no downtime)
291+
capsule hash document.pdf # SHA3-256 of any file
292+
```
293+
294+
Exit codes: `0` = pass, `1` = fail, `2` = error. Designed for CI/CD gates: `capsule verify --quiet && deploy`.
295+
296+
See the [Python reference documentation](./reference/python/) for the full guide.
245297

246298
---
247299

@@ -294,7 +346,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md). Protocol changes go through the [CPS c
294346

295347
**∀ action: ∃ capsule**
296348

297-
An open protocol · Reference implementations in [Python](./reference/python/) and [TypeScript](./reference/typescript/) · [Conformance suite](./conformance/) for any language
349+
An open protocol · [Python](./reference/python/) · [TypeScript](./reference/typescript/) · [Go](https://github.com/quantumpipes/capsule-go) · [LiteLLM](https://github.com/quantumpipes/capsule-litellm) · [Conformance suite](./conformance/) for any language
298350

299351
[Specification](./spec/) · [Conformance](./conformance/) · [Security Policy](./SECURITY.md) · [Patent Grant](./PATENTS.md)
300352

‎docs/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,12 @@ Each reference implementation has its own documentation:
3030
|---|---|
3131
| [Python](../reference/python/docs/) | API reference, getting started, high-level API |
3232
| [TypeScript](../reference/typescript/) | README with API reference, quick start, conformance status |
33+
34+
## Ecosystem Libraries
35+
36+
These extend the protocol to additional languages and frameworks. Each lives in its own repository.
37+
38+
| Library | What It Does | Repository |
39+
|---|---|---|
40+
| **capsule-go** | Verify Capsules in Go. Canonical JSON serialization, SHA3-256 hashing, Ed25519 signature verification, and structural/cryptographic chain verification. Passes all 16 golden vectors. Verification-only by design — seal in any language, verify in Go. | [quantumpipes/capsule-go](https://github.com/quantumpipes/capsule-go) |
41+
| **capsule-litellm** | Automatic Capsule creation for every LLM call through LiteLLM. Two lines to add. Captures model identity, SHA3-256 prompt hash (not the prompt itself), token counts, latency, and errors. Sync and async. | [quantumpipes/capsule-litellm](https://github.com/quantumpipes/capsule-litellm) |

‎docs/architecture.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -460,13 +460,68 @@ capsule hash document.pdf # SHA3-256 of any file
460460

461461
---
462462

463+
## Ecosystem
464+
465+
The Capsule Protocol is implemented across languages and frameworks. The specification and conformance suite live in this repository. Ecosystem libraries extend the protocol to new runtimes.
466+
467+
```
468+
┌─────────────────────────────────────────────────────────────────────┐
469+
│ Capsule Protocol (CPS v1.0) │
470+
│ spec/ · conformance/ · 16 golden vectors │
471+
├──────────────────────┬──────────────────────┬───────────────────────┤
472+
│ Reference Impls │ Ecosystem Libs │ Integrations │
473+
│ (this repo) │ (separate repos) │ (separate repos) │
474+
├──────────────────────┼──────────────────────┼───────────────────────┤
475+
│ Python (qp-capsule) │ Go (capsule-go) │ LiteLLM │
476+
│ create + seal │ verify only │ (capsule-litellm) │
477+
│ verify + chain │ canonical JSON │ auto-seal LLM calls │
478+
│ store + CLI │ SHA3 + Ed25519 │ prompt hash, tokens │
479+
│ │ chain verification │ sync + async │
480+
│ TypeScript │ │ │
481+
│ create + seal │ Rust (planned) │ │
482+
│ verify + chain │ │ │
483+
└──────────────────────┴──────────────────────┴───────────────────────┘
484+
```
485+
486+
### capsule-go — Verification in Go
487+
488+
[`quantumpipes/capsule-go`](https://github.com/quantumpipes/capsule-go) is a Go library for verifying Capsules. It implements canonical JSON serialization (CPS Section 2), SHA3-256 hashing (Section 3.1), Ed25519 signature verification (Section 3.2), and chain verification at all three levels (Section 7.5). It passes all 16 golden conformance vectors.
489+
490+
The library is verification-only by design. Infrastructure tooling, CI/CD gates, Kubernetes admission controllers, and audit pipelines can validate Capsules sealed by any language without pulling in a full creation SDK. Dependencies are `crypto/ed25519` (stdlib) and `golang.org/x/crypto/sha3`.
491+
492+
```go
493+
import capsule "github.com/quantumpipes/capsule-go"
494+
495+
valid := capsule.VerifyHash(capsuleDict, expectedHash) // content integrity
496+
valid := capsule.VerifySignature(hash, sig, pubKey) // Ed25519 authenticity
497+
errs := capsule.VerifyChainFull(sealedCapsules) // structural + cryptographic
498+
```
499+
500+
### capsule-litellm — Automatic Audit Trail for LLM Calls
501+
502+
[`quantumpipes/capsule-litellm`](https://github.com/quantumpipes/capsule-litellm) is a LiteLLM callback that creates a sealed, hash-chained Capsule for every LLM call. Two lines to integrate. No application code changes.
503+
504+
Each Capsule records the model, a SHA3-256 hash of the prompt (the prompt itself is never stored), token counts, latency, and success or failure status. Supports both `litellm.completion()` and `litellm.acompletion()`. Errors in capsule creation are swallowed by default so they never interrupt the LLM call path.
505+
506+
```python
507+
import litellm
508+
from capsule_litellm import CapsuleLogger
509+
510+
litellm.callbacks = [CapsuleLogger()]
511+
# Every LLM call now produces a sealed Capsule
512+
```
513+
514+
---
515+
463516
## Related Documentation
464517

465518
- [Why Capsules](./why-capsules.md) — The case for cryptographic AI memory
466519
- [Security Evaluation](./security.md) — Cryptographic guarantees for CISOs
467520
- [Compliance Mapping](./compliance/) — Regulatory framework alignment
468521
- [CPS Specification](../spec/) — Protocol rules for SDK authors
469522
- [Python Reference](../reference/python/) — Python API reference and quickstart
523+
- [Go Verifier](https://github.com/quantumpipes/capsule-go) — Verify Capsules in Go
524+
- [LiteLLM Integration](https://github.com/quantumpipes/capsule-litellm) — Auto-seal LLM calls
470525

471526
---
472527

0 commit comments

Comments
 (0)