proof-engine-registry

Protocol, client, and reference server for the Proof Registry — the JSON-over-HTTPS layer that lets LLM wikis (and other tools) ask "is this claim already proven?" and either use the existing proof or commission a new one.

Spec: docs/registry-protocol.md.

Install

pip install proof-engine-registry

Config

~/.config/proof-engine/registries.toml

[[registry]]
name = "public"
url = "https://proofengine.info"

[[registry]]
name = "acme-internal"
url = "https://proofs.acme.com"
token_env = "ACME_PROOFS_TOKEN"
publish = true

Client

from proof_engine_registry import RegistryClient, load_registries
client = RegistryClient(load_registries())
hit = client.lookup("The sky is blue.")
if hit:
    print(hit.proof_url)

Self-host

proof-registry serve ./my-proofs --port 8080 --token-env MY_TOKEN

Useful flags:

Production deployment

The reference server uses plain stdlib HTTP and binds to 127.0.0.1 by default. Suitable for development and local team use. For public exposure over the open internet, front the server with a TLS-terminating reverse proxy (nginx, Caddy, Cloudflare, AWS ALB) and route only encrypted traffic from the proxy to the server. Bearer tokens MUST NOT travel the network in cleartext.

Embedding badges

Each proof has three badge representations:

• /proofs/SLUG/badge.svg — inline SVG, our own rendering. Self-contained, no third-party dependencies. Style is fixed.
• /proofs/SLUG/badge.json — structured payload (claim, verdict, confidence, doi, badge_svg_url) for tools that render their own UI.
• /proofs/SLUG/shields.json — shields.io endpoint format. Plug it into shields.io and pick any style:

[![proof](https://img.shields.io/endpoint?url=https://proofengine.info/proofs/SLUG/shields.json)](https://proofengine.info/proofs/SLUG/)

Style flexibility (?style=flat-square, ?style=for-the-badge, etc.) and CDN caching come from shields.io; we just emit the JSON.

Errors

JSON error responses follow RFC 7807 Problem Details:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://proofengine.info/errors/not-found",
  "status": 404,
  "title": "Resource not found",
  "detail": "no proof with that claim_hash",
  "code": "not_found"
}

The code field preserves the legacy short machine key for log-aggregation tooling. Full canonical-error table in the protocol spec.

Conformance

A protocol-version-aware conformance suite ships with the package:

cd packages/proof-engine-registry && python -m pytest tests/test_conformance.py -v

It runs against both the static-JSON emit and the reference server. Any third-party server claiming to speak the protocol can run the same suite.