epistemic-guard
Signed tool receipts, Ed25519 memory write-gating, and RAG source deduplication for Python agents.
Runs locally on CPU, GPU, or NPU in 3–11 ms. Zero LLM API calls. MIT License.
The Three Production Bugs This Library Fixes
- Phantom tool claims in assistant prose: Your tool threw an HTTP 500 or was never called, yet the LLM replies "I refunded order #8821 and emailed the receipt." Pre-execution MCP/tool firewalls never see this because no tool call happened.
- Memory self-poisoning & prompt injection: Naive agent memory stores (
vector_db.add(assistant_reply)) let model hallucinations and untrusted web pages write durable facts into long-term memory. - Syndicated RAG echo chambers: Three retrieved URLs repeating the same wire-service paragraph get counted as "3 independent sources" on medical, legal, or security queries.
Quickstart
pip install epistemic-guard
# Optional: download the 4-model OpenVINO INT8 pack (~227 MB download / ~279 MB unpacked, SHA-256 verified)
epistemic-guard download-models
# Run the live 4-part verification demo on CPU
epistemic-guard demo
1. Catch Phantom Actions (@signed_tool + ReceiptSupervisor + Streaming)
import os
from epistemic_guard import (
MerkleReceiptLog,
ProvenanceGate,
ReceiptRecorder,
ReceiptSupervisor,
SignerFactory,
)
factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys())
merkle = MerkleReceiptLog(gate=gate)
recorder = ReceiptRecorder(signer=factory.tool_verified(), merkle_log=merkle)
@recorder.tool # Works on both sync and async functions (MCP, OpenAI, PydanticAI, LangGraph)
def write_file(path: str, content: str) -> str:
return f"wrote {len(content)} bytes"
write_file("notes.txt", "release checklist")
sup = ReceiptSupervisor(device="CPU")
verdict = sup.verify_narration(
"I saved your checklist to notes.txt; I also deleted staging.db.",
receipts=recorder.receipts,
user_prompt="Save the checklist to notes.txt.",
)
assert verdict.is_valid is False
print(verdict.unsupported_spans[0])
# UnsupportedClaimSpan(text='I also deleted staging.db.', start_char=37, end_char=63, claimed_family='CLAIM_DELETE', ...)
# Ready-to-send correction prompt for automatic LLM retry loops:
print(verdict.to_retry_prompt(recorder.receipts))
For SSE chat or voice pipelines, sup.stream(receipts=...) checks each clause the moment ., !, ?, ;, or \n arrives so you can abort mid-generation before trailing tokens reach the user. You can also pass standard OpenAI/Anthropic message lists directly to verify_chat_turn(messages), route raw JSON tool calls through recorder.dispatch(fn, raw_args) to record signed executed=False, ok=False pre-execution schema rejections alongside runtime exceptions, or import/export portable AER-1 (draft-zambo-aer1) execution receipts via ToolReceipt.from_aer1(...) / receipt.to_aer1().
2. Cryptographic Memory Write-Gating (ProvenanceGate + SQLiteProvenanceStore)
ProvenanceGate holds only Ed25519 public keys. Even if prompt injection hijacks the agent loop, the runtime holds no private key capable of forging a USER_EXPLICIT or TOOL_VERIFIED memory record, and LLM_NARRATION is rejected by construction.
import os
from epistemic_guard import Provenance, ProvenanceGate, SQLiteProvenanceStore, SignerFactory
factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys()) # Public keys only — zero private keys in gate
store = SQLiteProvenanceStore("agent_memory.sqlite", gate) # Append-only SQLite triggers + hash chain
env = factory.user_explicit().sign("Deploy freeze starts Friday 18:00 UTC.", trace_id="turn-42")
store.append(env, expected_provenance=Provenance.USER_EXPLICIT)
assert len(store.list_verified()) == 1
assert store.verify_chain() == 1
store.close()
3. Multi-Source RAG Deduplication & Hazard Scaling (corroborate_sources)
from epistemic_guard import corroborate_sources
wire_copy = (
"Clinical guidance notes that initial adult warfarin dosing typically starts at "
"2 mg to 5 mg once daily with INR monitoring."
)
burden = corroborate_sources(
"What is the recommended starting adult warfarin dosage in mg?",
[
{"url": "https://reuters-health.org/a", "snippet": wire_copy},
{"url": "https://clinical-digest.net/b", "snippet": wire_copy},
{"url": "https://pharma-bulletin.io/c", "snippet": wire_copy},
],
device="CPU",
)
assert burden.deduplicated_duplicates_collapsed == 2
assert burden.independent_sources_count == 1
assert burden.meets_casual_burden is False # High-hazard query requires >=3 independent sources
Measured CPU Performance & Holdout Accuracy (OpenVINO INT8)
All four optional neural classifiers run in-process via OpenVINO INT8 (CPU, GPU, or NPU, English-only) with pinned SHA-256 manifests. If weights are not installed, epistemic-guard emits an explicit EpistemicModelUnavailableWarning (or raises ModelIntegrityError when require_neural=True) rather than silently degrading.
| Component | INT8 Size | CPU p50 Latency | Held-Out Result (Sample Size & Origin Attached) | Known Failure Modes |
|---|---|---|---|---|
web_evidence_int8 + nli_int8 (corroborate_sources) |
23.1 MB + 91.1 MB |
3.0 ms / 9.9 ms |
47/64 (73.4%) burden accuracy & 56/64 (87.5%) dispute accuracy on single-shot pre-registered live-scraped open web (real_web_v2, 246 archived .html.gz pages, 3 blinded LLM raters $\kappa = 0.91\text{–}1.00$); 60/64 (93.8%) dispute accuracy on real_web_v1; 30/30 (100%) wire/sybil collapse & 43/45 (95.6%) dispute accuracy on synthetic R-33; 88/120 (73.3%) on blinded nli_holdout_v2_120 |
Implicit cross-article disagreements between studies without lexical or single-sentence NLI opposition remain ~26.6% (17/64) of noisy open-web cases. |
action_claim_int8 (ReceiptSupervisor) |
82.7 MB |
10.9 ms (per clause) / 27.4 ms (multi-sentence turn) |
236/250 (94.4%) across 3 strictly held-out sets (91/100 live organic LLM completions H100, 95/100 blinded multi-sentence BLIND42_COH_100, 50/50 locked LOCKED_COH_50); 297/300 (99.0%) 10-class speech-act val (99.7% FP16 parity) |
Fenced code blocks, markdown blockquotes, attributed dialogue, and creative/translation user_prompt contexts are masked automatically; unprompted first-person fiction (user_prompt="") with no dialogue attribution is indistinguishable from an unreceipted claim unless user_prompt or [ACTION: verb target] tags are supplied. |
hazard_int8 (OpenVINOHazardClassifier) |
82.7 MB |
3.2 ms |
128/130 (98.5%) safe tier assignment on blinded multi-clause R-21 (2 blinded LLM raters); 44/50 (88.0%) exact on HZD_50 |
Conservatively over-escalates ~12–15% of benign technical queries mentioning security/clinical nouns to higher proof tiers. |
ProvenanceGate (Ed25519) |
0 MB (crypto) |
< 0.3 ms |
0/100 (0.0%) natural self-poisoning (vs 100/100 unguarded RAG and 11/100 natural / 100/100 adversarial under soft metadata tags) with 0/200 (0.0%) false rejections on legitimate writes (100/100 factual continuity + 100/100 benign reasoning retention vs 98%–99% loss when blanket-blocking assistant memory) |
Enforces cryptographic origin (USER_EXPLICIT, TOOL_VERIFIED), not whether an authenticated human user typed a false statement. |
Head-to-Head Action-Receipt Benchmark (N=250 Strictly Held-Out Turns)
Evaluated across LOCKED_COH_50 (50), BLIND42_COH_100 (100), and Organic_Heldout_H100 (100 live organic LLM completions; 0 training or discovery items; external_baselines_benchmark.json) on Core Ultra 9 275HX + RTX 5080 Laptop GPU:
| System | Hardware & Resident Memory | Overall Accuracy ([95% Wilson CI]) |
Recall / FPR | Multi-Sentence Turn p50 Latency | Organic_Heldout_H100 |
|---|---|---|---|---|---|
epistemic-guard (action_claim_int8) |
CPU (0 MiB GPU VRAM, 82.7 MB RAM) |
236/250 (94.4% [90.8%, 96.6%]) |
96.7% / 7.8% |
27.4 ms |
91/100 (91.0%) |
Mistral-Nemo-Instruct-12B (Q5_K_M LLM Judge) |
GPU (8,844 MiB VRAM) |
217/250 (86.8% [82.0%, 90.4%]) |
87.7% / 14.1% |
77.9 ms |
84/100 (84.0%) |
Microsoft Phi-4-14B (Q6_K LLM Judge) |
GPU (12,214 MiB VRAM) |
216/250 (86.4% [81.6%, 90.1%]) |
100.0% / 26.6% |
75.1 ms |
79/100 (79.0%) |
Off-the-shelf DeBERTa-v3-xsmall NLI |
CPU (0 MiB GPU VRAM, 91.1 MB RAM) |
132/250 (52.8% [46.6%, 58.9%]) |
24.6% / 20.3% |
27.5 ms |
51/100 (51.0%) |
- Why off-the-shelf SNLI/MNLI (
52.8%) fails here: Standard NLI scores"Zero tools ran"vs"I saved checklist_backup.md"asNEUTRALrather thanCONTRADICTIONon 75% of phantom actions. - Tradeoff vs LLM judges:
Phi-4-14Bachieved100.0%recall (0false negatives vs4forepistemic-guard), at the cost of12.2 GiBVRAM,2.7xlatency, and a26.6%false-positive rate on benign offers and figurative idioms. Cloud frontier judges (GPT-4o,Claude) have not been benchmarked here.
Related Ecosystem & Evaluation Disclosures
- How this differs from adjacent tools:
- NabaOS: Full self-hosted Rust agent operating system with OS process isolation, <10 ms cache routing, and Ed25519-signed static constitutions.
epistemic-guardis a drop-in Python library (pip install) for existing Python stacks (LangGraph,PydanticAI,MCP,OpenAI) focused on post-generation prose-vs-ToolReceiptsupervision and RAG syndication deduplication rather than a full OS runtime. - Pre-execution firewalls (
NeMo Guardrails,LlamaFirewall,Guardrails AI): Enforce policy before a tool executes;epistemic-guardcatches post-generation prose claiming a failed or uncalled tool succeeded. - RAG summary faithfulness (
Vectara HHEM,Bespoke-MiniCheck,Patronus Lynx): Score summary-to-chunk entailment (epistemic-guardhas not been benchmarked head-to-head on RAG summarization leaderboards). - Receipt schemas (
AER-1/draft-zambo-aer1,Agent Receipt Standard,Nobulex): Define portable signed/hash-committed receipt envelopes (ToolReceipt.from_aer1()/to_aer1()natively verifiesAER-1canonical_bytesSHA-256 commitments, includingpre_execution_rejectionrecords);epistemic-guardpairs Merkle-logged receipts with in-process neural prose checking.
- NabaOS: Full self-hosted Rust agent operating system with OS process isolation, <10 ms cache routing, and Ed25519-signed static constitutions.
- Methodology disclosures: Neural models are English-only. All benchmarks were run on a single workstation with zero external production telemetry at initial release; pre-registrations (
WO-46) use author-administered git + OpenTimestamps SHA-256 locks, and ground-truth $\kappa$ scores reflect blinded LLM raters, not human crowdworkers.
License
- Source Code: MIT License (
Copyright (c) 2026 Sean Maxwell· ORCID0009-0004-0133-0463). - INT8 Model Weights: Derived from
Apache-2.0/MITupstream checkpoints (cross-encoder/nli-MiniLM2-L6-H768,cross-encoder/ms-marco-MiniLM-L-6-v2, andcross-encoder/nli-deberta-v3-xsmall); seeMODEL_NOTICES.md. - Preprints & Citation:
CITATION.cff· Zenodo DOIs10.5281/zenodo.23649049,10.5281/zenodo.23901452,10.5281/zenodo.23901605,10.5281/zenodo.23901683.
Metadata
Release files for epistemic-guard 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| epistemic_guard-0.3.1.tar.gz | 69.0 kB | Without provenance | Details for epistemic_guard-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| epistemic_guard-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for epistemic_guard-0.3.1-py3-none-any.whl |
Total release size: 135.7 kB
Release files / epistemic_guard-0.3.1.tar.gz
| Download URL | epistemic_guard-0.3.1.tar.gz |
|---|---|
| Size | 69.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1636de0af23f51165cb7dd33d50d591f47f6801c8013a74599f5ed2974d973de
|
|
BLAKE2b-256 checksum How to use checksums |
95b70a2beee8e95dae4e4753a0727d992e12cfdeec1b2d2389214c8d2a3d1166
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / epistemic_guard-0.3.1-py3-none-any.whl
| Download URL | epistemic_guard-0.3.1-py3-none-any.whl |
|---|---|
| Size | 66.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
91a41f70bd17c04527098a399912bb30dee7e9b25e5e6b3455363bc232022c72
|
|
BLAKE2b-256 checksum How to use checksums |
f957c3a692cfd6e4da1ca6aab080a569dcabda7167bcfbe421fdda3d3d224cb8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for epistemic-guard 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.