eerful

eerful is a Python reference implementation of the Enhanced Evaluation Receipts (EER) protocol — a way to make non-deterministic LLM evaluation verifiable, and to use that verifiability as a hard gate on agent execution. The architecture is cheap exploration, verified gating. Generation agents run freely against cheap models. A hard attested gate using TEE-hosted graders physically blocks any output from reaching an executor without valid receipts. Each receipt commits to an evaluator bundle (criteria + prompt + model) stored on 0G Storage, the input hash, and a signed attestation from a TeeML inference run. Verification is a deterministic seven-step check anyone can run: bundle hash, input commitment, signature, provider attestation, freshness, signer authorization, and policy match. Principal policies declare what passes. A paper-trading policy might require N=1 receipt; a live-capital policy requires N=4 from distinct attestation providers — so an attacker has to compromise four independent TEEs to slip past the gate, not one. The diversity rule isn't decorative; it's the architectural reason defense-in-depth becomes legible. The headline demo is tool-call poisoning. A malicious payload is visibly injected into an agent's tool response on screen; the agent obediently produces a compromised output; the gate refuses with the detail string visible (REFUSE_SCORE / REFUSE_BUNDLE_MISMATCH) before the executor ever sees the trade. The rails physically refusing under attack is the demo, not a narration of it. The narrow insight underneath all of this: TEE attestation only buys you something where the underlying compute is non-deterministic. Training is mostly deterministic — attesting it is theater. Evaluation is where the entropy and the trust assumptions actually live. eerful is just that distillation.

Python end-to-end. The protocol layer is a small set of Pydantic models — EnhancedReceipt, EvaluatorBundle, PrincipalPolicy — with canonical JSON encoding so independent runs of the encoder produce byte-identical output. The verifier (eerful.verify) decomposes the spec's verification algorithm into seven separately testable functions; each tampering mode has a corresponding failing-test fixture, including an RTMR3-collision case backing the executor's provider-category enforcement. Inference runs through 0G's TeeML via the broker SDK. eerful.zg.compute wraps it and captures the response, chatID, signer signature, and provider attestation report. Storage runs through 0G Storage for content-addressed evaluator bundles and attestation reports, plus a self-hosted 0G Storage KV node for receipt indexing — KV has no public endpoint, so a small VPS runs the node configured to monitor the demo's stream_ids. The executor (eerful.executor.evaluate_gate) is the load-bearing piece. It takes a principal policy and a list of receipts, runs the seven-step verification on each, enforces N-of-distinct-providers, checks bundle category against the policy's accepted_compose_hashes (with a canonical-set hash bound into chain composition), and either passes output downstream or refuses with a structured detail string. Operational glue: a bridge_init() helper centralizes 0G client setup across the smoke-testnet runner, the demo driver, and a bundle inspector, returning a BridgeInitStatus dataclass so callers can branch cleanly on partial setup. A --score-test CLI flag iterates grader prompts against calibration sets (5 known-bad + 5 known-good per grader, locked once each hits ≥9/10). What we punted: full chain verification of TDX quotes against Intel roots and GPU attestation against NVIDIA's API. v1 ships a correct partial verifier (structure + pubkey binding) with chain-to-vendor-roots documented as future work. The rails enforce N=4 against any policy that requires it — so when four distinct signers don't yet exist in the ecosystem, the gate refuses, and that refusal is the architecture working as designed.