epistemic-guard 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- epistemic_guard-0.3.0/.gitignore +154 -0
- epistemic_guard-0.3.0/LICENSE +21 -0
- epistemic_guard-0.3.0/MODEL_NOTICES.md +29 -0
- epistemic_guard-0.3.0/PKG-INFO +185 -0
- epistemic_guard-0.3.0/README.md +132 -0
- epistemic_guard-0.3.0/pyproject.toml +79 -0
- epistemic_guard-0.3.0/src/epistemic_guard/__init__.py +152 -0
- epistemic_guard-0.3.0/src/epistemic_guard/cli.py +215 -0
- epistemic_guard-0.3.0/src/epistemic_guard/corroboration.py +746 -0
- epistemic_guard-0.3.0/src/epistemic_guard/exceptions.py +31 -0
- epistemic_guard-0.3.0/src/epistemic_guard/hazard.py +240 -0
- epistemic_guard-0.3.0/src/epistemic_guard/integrations.py +260 -0
- epistemic_guard-0.3.0/src/epistemic_guard/models.py +297 -0
- epistemic_guard-0.3.0/src/epistemic_guard/nli.py +182 -0
- epistemic_guard-0.3.0/src/epistemic_guard/provenance.py +342 -0
- epistemic_guard-0.3.0/src/epistemic_guard/py.typed +0 -0
- epistemic_guard-0.3.0/src/epistemic_guard/schemas.py +225 -0
- epistemic_guard-0.3.0/src/epistemic_guard/store.py +304 -0
- epistemic_guard-0.3.0/src/epistemic_guard/supervision.py +810 -0
- epistemic_guard-0.3.0/src/epistemic_guard/web_filters.py +1071 -0
- epistemic_guard-0.3.0/tests/test_epistemic_guard.py +552 -0
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
.Python
|
|
11
|
+
build/
|
|
12
|
+
develop-eggs/
|
|
13
|
+
dist/
|
|
14
|
+
downloads/
|
|
15
|
+
eggs/
|
|
16
|
+
.eggs/
|
|
17
|
+
lib/
|
|
18
|
+
lib64/
|
|
19
|
+
parts/
|
|
20
|
+
sdist/
|
|
21
|
+
var/
|
|
22
|
+
wheels/
|
|
23
|
+
*.egg-info/
|
|
24
|
+
.installed.cfg
|
|
25
|
+
*.egg
|
|
26
|
+
|
|
27
|
+
# Virtual environments
|
|
28
|
+
.env
|
|
29
|
+
.venv
|
|
30
|
+
.venv-voice/
|
|
31
|
+
env/
|
|
32
|
+
venv/
|
|
33
|
+
ENV/
|
|
34
|
+
|
|
35
|
+
# OpenVINO & model caches
|
|
36
|
+
var/cache/
|
|
37
|
+
openvino_cache/
|
|
38
|
+
*.blob
|
|
39
|
+
|
|
40
|
+
# ChromaDB local state
|
|
41
|
+
var/chroma/
|
|
42
|
+
chroma_data/
|
|
43
|
+
|
|
44
|
+
# Unit test / coverage reports
|
|
45
|
+
.pytest_cache/
|
|
46
|
+
.coverage
|
|
47
|
+
htmlcov/
|
|
48
|
+
|
|
49
|
+
# User-specific & local IDE / workspace assistant files
|
|
50
|
+
.idea/
|
|
51
|
+
.vscode/
|
|
52
|
+
.agents/
|
|
53
|
+
GEMINI.md
|
|
54
|
+
.DS_Store
|
|
55
|
+
*.swp
|
|
56
|
+
*.bak
|
|
57
|
+
|
|
58
|
+
# Property-based testing / static-analysis caches
|
|
59
|
+
.hypothesis/
|
|
60
|
+
.grimp_cache/
|
|
61
|
+
.import_linter_cache/
|
|
62
|
+
.mypy_cache/
|
|
63
|
+
.ruff_cache/
|
|
64
|
+
|
|
65
|
+
# Model weights (pinned via models/MANIFEST.json, never committed)
|
|
66
|
+
models/*.gguf
|
|
67
|
+
models/*.bin
|
|
68
|
+
models/*.safetensors
|
|
69
|
+
models/tts/
|
|
70
|
+
|
|
71
|
+
# Runtime state — production DB lives under LUCCA_HOME (C:\ProjectLucca\data)
|
|
72
|
+
data/memory.sqlite
|
|
73
|
+
data/memory.sqlite-wal
|
|
74
|
+
data/memory.sqlite-shm
|
|
75
|
+
|
|
76
|
+
# Ad-hoc scrape samples and cookie jars from search-provider probes
|
|
77
|
+
data/*.html
|
|
78
|
+
data/*cookies*.txt
|
|
79
|
+
|
|
80
|
+
# Research papers (referenced by arXiv ID in docs/specs; not vendored)
|
|
81
|
+
docs/*.pdf
|
|
82
|
+
docs/**/*.pdf
|
|
83
|
+
!docs/paper.pdf
|
|
84
|
+
!docs/papers/*.pdf
|
|
85
|
+
!docs/seed_paper/*.pdf
|
|
86
|
+
!papers/**/*.pdf
|
|
87
|
+
|
|
88
|
+
# Local logs
|
|
89
|
+
logs/*.log
|
|
90
|
+
logs/*.wav
|
|
91
|
+
|
|
92
|
+
# Ephemeral hardware test run reports
|
|
93
|
+
logs/test_reports/rag_tier2_*.json
|
|
94
|
+
logs/test_reports/soak_memory_growth_*.json
|
|
95
|
+
logs/test_reports/compound_benchmark_*.json
|
|
96
|
+
logs/test_reports/compound_failure_battery_*.json
|
|
97
|
+
*.checkpoint.json
|
|
98
|
+
logs/test_reports/*_test/
|
|
99
|
+
|
|
100
|
+
# Showcase bundle
|
|
101
|
+
showcase/
|
|
102
|
+
|
|
103
|
+
# Scratch directory
|
|
104
|
+
scratch*/
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
# local caches and binary state (added 2026-10-24)
|
|
108
|
+
*.sqlite
|
|
109
|
+
*.pyc
|
|
110
|
+
|
|
111
|
+
PITCH_EMAIL.txt
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
models/verifier_minilm/
|
|
115
|
+
OpenRouter Chat*.json
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
# WO-41/WO-42 OpenVINO NPU and PyTorch fine-tuned model directories
|
|
119
|
+
models/*_ov/
|
|
120
|
+
models/*_pt/
|
|
121
|
+
models/epistemic_guard_int8/
|
|
122
|
+
models/**/*.pt
|
|
123
|
+
models/**/*.bin
|
|
124
|
+
models/**/*.safetensors
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
# External benchmark corpora & local training/scratch worksheets (WO-43 Phase 1.1)
|
|
128
|
+
data/benchmarks/ConceptARC/
|
|
129
|
+
data/benchmarks/arc_agi_1/
|
|
130
|
+
data/benchmarks/arc_agi_2/
|
|
131
|
+
data/benchmarks/cruxeval/
|
|
132
|
+
data/benchmarks/livecodebench/
|
|
133
|
+
data/benchmarks/swe_bench_lite/
|
|
134
|
+
data/benchmarks/nli_eval/
|
|
135
|
+
data/benchmarks/runs/
|
|
136
|
+
data/benchmarks/turn_latency/
|
|
137
|
+
data/benchmarks/supervision_heldout/*_train.jsonl
|
|
138
|
+
data/benchmarks/supervision_heldout/wo41_*
|
|
139
|
+
|
|
140
|
+
# Ephemeral and archived test reports / local discussions
|
|
141
|
+
discussions/
|
|
142
|
+
logs/archive/
|
|
143
|
+
logs/test_reports/comparative_four_tier/
|
|
144
|
+
logs/test_reports/full_uncurated/
|
|
145
|
+
logs/test_reports/rebench_master_v140/
|
|
146
|
+
logs/test_reports/personhood/in_d_report_*.json
|
|
147
|
+
logs/test_reports/aime_sympy_diagnostic_*.json
|
|
148
|
+
logs/test_reports/concept_arc_*.json
|
|
149
|
+
logs/test_reports/cruxeval_input_*.json
|
|
150
|
+
logs/test_reports/e2e_voice_tooling_integration_*.json
|
|
151
|
+
logs/test_reports/minilm_finetuned_side_by_side.json
|
|
152
|
+
logs/test_reports/ml_vs_regex_head_to_head.json
|
|
153
|
+
logs/test_reports/ood_*.json
|
|
154
|
+
logs/test_reports/wo41_*
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sean Maxwell
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Model Weights & Third-Party Notices
|
|
2
|
+
|
|
3
|
+
All Python source code in `epistemic-guard` is licensed under the **MIT License** (see [`LICENSE`](LICENSE)).
|
|
4
|
+
|
|
5
|
+
When optional OpenVINO INT8 neural weights are downloaded via `epistemic_guard.download_models()` (`epistemic-guard download-models`), the fine-tuned and quantized OpenVINO IR weights derive from the following permissive (`Apache-2.0`) upstream base checkpoints:
|
|
6
|
+
|
|
7
|
+
## 1. `action_claim_int8` & `hazard_int8`
|
|
8
|
+
- **Upstream Base Checkpoint:** [`cross-encoder/nli-MiniLM2-L6-H768`](https://huggingface.co/cross-encoder/nli-MiniLM2-L6-H768) (Sentence-Transformers / Nils Reimers & UKP Lab, TU Darmstadt; distilled from Microsoft MiniLMv2 / RoBERTa).
|
|
9
|
+
- **Upstream License:** Apache License 2.0 (`Apache-2.0`).
|
|
10
|
+
- **Modifications by Sean Maxwell (2026):**
|
|
11
|
+
- `action_claim_int8`: Fine-tuned 10-class classification head and transformer layers on `(user_request, assistant_clause)` speech-act pairs, exported to static `[1, 192]` OpenVINO IR, and quantized to INT8 via NNCF SmoothQuant + Fast Bias Correction.
|
|
12
|
+
- `hazard_int8`: Fine-tuned 5-class classification head and transformer layers with 5:1 asymmetric ordinal cost-weighted risk loss, exported to static `[1, 64]` OpenVINO IR, and quantized to INT8 via NNCF.
|
|
13
|
+
|
|
14
|
+
## 2. `web_evidence_int8`
|
|
15
|
+
- **Upstream Base Checkpoint:** [`cross-encoder/ms-marco-MiniLM-L-6-v2`](https://huggingface.co/cross-encoder/ms-marco-MiniLM-L-6-v2) (Sentence-Transformers / Nils Reimers; based on Microsoft MiniLM).
|
|
16
|
+
- **Upstream License:** Apache License 2.0 (`Apache-2.0`).
|
|
17
|
+
- **Modifications by Sean Maxwell (2026):**
|
|
18
|
+
- Replaced single-logit ranking head with a 3-class `(query, passage) -> {CORROBORATES, IRRELEVANT, DISPUTES}` head, fine-tuned across all 6 transformer layers on disjoint open-web search/passage pairs, exported to static `[1, 192]` OpenVINO IR, and quantized to INT8 via NNCF.
|
|
19
|
+
|
|
20
|
+
## 3. `nli_int8`
|
|
21
|
+
- **Upstream Base Checkpoint:** [`cross-encoder/nli-deberta-v3-xsmall`](https://huggingface.co/cross-encoder/nli-deberta-v3-xsmall) (Sentence-Transformers / Nils Reimers, `Apache-2.0`; fine-tuned from [`microsoft/deberta-v3-xsmall`](https://huggingface.co/microsoft/deberta-v3-xsmall), `MIT`).
|
|
22
|
+
- **Upstream License:** Apache License 2.0 (`Apache-2.0`) / MIT License (`MIT`).
|
|
23
|
+
- **Modifications by Sean Maxwell (2026):**
|
|
24
|
+
- Exported 3-class `(premise, hypothesis) -> {contradiction, entailment, neutral}` cross-encoder to static `[1, 128]` OpenVINO IR and quantized to INT8 via NNCF SmoothQuant + Fast Bias Correction.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
Licensed under the Apache License, Version 2.0 (the "License"); you may obtain a copy of the Apache-2.0 License at:
|
|
29
|
+
https://www.apache.org/licenses/LICENSE-2.0
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: epistemic-guard
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Signed tool receipts, Ed25519 memory write-gating, and RAG source deduplication for Python agents (CPU/NPU, zero LLM calls)
|
|
5
|
+
Project-URL: Repository, https://github.com/AlienatedAliens/ProjectLucca/tree/main/packages/epistemic-guard
|
|
6
|
+
Project-URL: Issues, https://github.com/AlienatedAliens/ProjectLucca/issues
|
|
7
|
+
Author: Sean Maxwell
|
|
8
|
+
License: MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2026 Sean Maxwell
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
25
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
26
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
27
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
28
|
+
SOFTWARE.
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Keywords: agents,ed25519,guardrails,mcp,openvino,provenance,rag,tool-calling
|
|
31
|
+
Classifier: Development Status :: 4 - Beta
|
|
32
|
+
Classifier: Intended Audience :: Developers
|
|
33
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
34
|
+
Classifier: Programming Language :: Python :: 3
|
|
35
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
36
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
38
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
39
|
+
Classifier: Topic :: Security :: Cryptography
|
|
40
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
41
|
+
Requires-Python: >=3.10
|
|
42
|
+
Requires-Dist: cryptography>=42.0.0
|
|
43
|
+
Requires-Dist: numpy>=1.26.0
|
|
44
|
+
Requires-Dist: openvino>=2025.0.0
|
|
45
|
+
Requires-Dist: pydantic>=2.7.0
|
|
46
|
+
Requires-Dist: tokenizers>=0.19.0
|
|
47
|
+
Provides-Extra: dev
|
|
48
|
+
Requires-Dist: import-linter>=2.0.0; extra == 'dev'
|
|
49
|
+
Requires-Dist: mypy>=1.11.0; extra == 'dev'
|
|
50
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
51
|
+
Requires-Dist: ruff>=0.6.0; extra == 'dev'
|
|
52
|
+
Description-Content-Type: text/markdown
|
|
53
|
+
|
|
54
|
+
# `epistemic-guard`
|
|
55
|
+
|
|
56
|
+
**Signed tool receipts, Ed25519 memory write-gating, and RAG source deduplication for Python agents.**
|
|
57
|
+
Runs locally on CPU, GPU, or NPU in **3–11 ms**. Zero LLM API calls. MIT License.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## The Three Production Bugs This Library Fixes
|
|
62
|
+
|
|
63
|
+
1. **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.
|
|
64
|
+
2. **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.
|
|
65
|
+
3. **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.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Quickstart
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
pip install epistemic-guard
|
|
73
|
+
|
|
74
|
+
# Optional: download the 4-model OpenVINO INT8 pack (~227 MB download / ~279 MB unpacked, SHA-256 verified)
|
|
75
|
+
epistemic-guard download-models
|
|
76
|
+
|
|
77
|
+
# Run the live 4-part verification demo on CPU
|
|
78
|
+
epistemic-guard demo
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### 1. Catch Phantom Actions (`@signed_tool` + `ReceiptSupervisor` + Streaming)
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
import os
|
|
85
|
+
from epistemic_guard import (
|
|
86
|
+
MerkleReceiptLog,
|
|
87
|
+
ProvenanceGate,
|
|
88
|
+
ReceiptRecorder,
|
|
89
|
+
ReceiptSupervisor,
|
|
90
|
+
SignerFactory,
|
|
91
|
+
)
|
|
92
|
+
|
|
93
|
+
factory = SignerFactory.from_master_key(os.urandom(32))
|
|
94
|
+
gate = ProvenanceGate(factory.public_keys())
|
|
95
|
+
merkle = MerkleReceiptLog(gate=gate)
|
|
96
|
+
recorder = ReceiptRecorder(signer=factory.tool_verified(), merkle_log=merkle)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
@recorder.tool # Works on both sync and async functions (MCP, OpenAI, PydanticAI, LangGraph)
|
|
100
|
+
def write_file(path: str, content: str) -> str:
|
|
101
|
+
return f"wrote {len(content)} bytes"
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
write_file("notes.txt", "release checklist")
|
|
105
|
+
|
|
106
|
+
sup = ReceiptSupervisor(device="CPU")
|
|
107
|
+
verdict = sup.verify_narration(
|
|
108
|
+
"I saved your checklist to notes.txt; I also deleted staging.db.",
|
|
109
|
+
receipts=recorder.receipts,
|
|
110
|
+
user_prompt="Save the checklist to notes.txt.",
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
assert verdict.is_valid is False
|
|
114
|
+
print(verdict.unsupported_spans[0])
|
|
115
|
+
# UnsupportedClaimSpan(text='I also deleted staging.db.', start_char=37, end_char=63, claimed_family='CLAIM_DELETE', ...)
|
|
116
|
+
|
|
117
|
+
# Ready-to-send correction prompt for automatic LLM retry loops:
|
|
118
|
+
print(verdict.to_retry_prompt(recorder.receipts))
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
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)`.
|
|
122
|
+
|
|
123
|
+
### 2. Cryptographic Memory Write-Gating (`ProvenanceGate` + `SQLiteProvenanceStore`)
|
|
124
|
+
|
|
125
|
+
`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.
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
import os
|
|
129
|
+
from epistemic_guard import Provenance, ProvenanceGate, SQLiteProvenanceStore, SignerFactory
|
|
130
|
+
|
|
131
|
+
factory = SignerFactory.from_master_key(os.urandom(32))
|
|
132
|
+
gate = ProvenanceGate(factory.public_keys()) # Public keys only — zero private keys in gate
|
|
133
|
+
store = SQLiteProvenanceStore("agent_memory.sqlite", gate) # Append-only SQLite triggers + hash chain
|
|
134
|
+
|
|
135
|
+
env = factory.user_explicit().sign("Deploy freeze starts Friday 18:00 UTC.", trace_id="turn-42")
|
|
136
|
+
store.append(env, expected_provenance=Provenance.USER_EXPLICIT)
|
|
137
|
+
|
|
138
|
+
assert len(store.list_verified()) == 1
|
|
139
|
+
assert store.verify_chain() == 1
|
|
140
|
+
store.close()
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### 3. Multi-Source RAG Deduplication & Hazard Scaling (`corroborate_sources`)
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
from epistemic_guard import corroborate_sources
|
|
147
|
+
|
|
148
|
+
wire_copy = (
|
|
149
|
+
"Clinical guidance notes that initial adult warfarin dosing typically starts at "
|
|
150
|
+
"2 mg to 5 mg once daily with INR monitoring."
|
|
151
|
+
)
|
|
152
|
+
burden = corroborate_sources(
|
|
153
|
+
"What is the recommended starting adult warfarin dosage in mg?",
|
|
154
|
+
[
|
|
155
|
+
{"url": "https://reuters-health.org/a", "snippet": wire_copy},
|
|
156
|
+
{"url": "https://clinical-digest.net/b", "snippet": wire_copy},
|
|
157
|
+
{"url": "https://pharma-bulletin.io/c", "snippet": wire_copy},
|
|
158
|
+
],
|
|
159
|
+
device="CPU",
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
assert burden.deduplicated_duplicates_collapsed == 2
|
|
163
|
+
assert burden.independent_sources_count == 1
|
|
164
|
+
assert burden.meets_casual_burden is False # High-hazard query requires >=3 independent sources
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Measured CPU Performance & Holdout Accuracy (OpenVINO INT8)
|
|
170
|
+
|
|
171
|
+
All four optional neural classifiers run in-process via OpenVINO INT8 (`CPU`, `GPU`, or `NPU`) 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.
|
|
172
|
+
|
|
173
|
+
| Component | INT8 Size | CPU p50 Latency | Locked Holdout Result | Known Failure Modes |
|
|
174
|
+
| :--- | :---: | :---: | :--- | :--- |
|
|
175
|
+
| **`ProvenanceGate` (Ed25519)** | `0 MB` (crypto) | `< 0.3 ms` | `0/100 (0.0%)` natural self-poisoning vs `100/100` in unguarded RAG | Does not fact-check false statements explicitly asserted by an authenticated human user (`USER_EXPLICIT`). |
|
|
176
|
+
| **`action_claim_int8`** (`ReceiptSupervisor`) | `82.7 MB` | `10.9 ms` | `50/50 (100.0%)` on `LOCKED_COH_50`; `99.0%` 10-class speech-act accuracy (`99.7%` FP16 parity) | Fenced code blocks, markdown blockquotes, attributed quotes/dialogue, and creative/translation `user_prompt` contexts are masked automatically; unprompted first-person fiction (`user_prompt=""`) with no dialogue attribution should pass `user_prompt` or use `[ACTION: verb target]` tags. |
|
|
177
|
+
| **`hazard_int8`** (`OpenVINOHazardClassifier`) | `82.7 MB` | `3.2 ms` | `128/130 (98.5%)` safe tier assignment on multi-clause `R-21`; `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. |
|
|
178
|
+
| **`web_evidence_int8` + `nli_int8`** (`corroborate_sources`) | `23.1 MB` + `91.1 MB` | `3.0 ms` / `9.9 ms` | `30/30 (100.0%)` wire/sybil collapse & `43/45 (95.6%)` dispute accuracy on `R-33`; `60/64 (93.8%)` dispute accuracy on `real_web_v1`; `47/64 (73.4%)` burden accuracy & `56/64 (87.5%)` dispute accuracy on single-shot open web (`real_web_v2`); `88/120 (73.3%)` 3-class NLI (`99.2%` FP32 parity) | Implicit cross-article contradictions lacking lexical or single-sentence NLI opposition remain ~26.6% of open-web error cases (`17/64` on `real_web_v2`). |
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## License
|
|
183
|
+
|
|
184
|
+
- **Source Code:** [MIT License](LICENSE) (`Copyright (c) 2026 Sean Maxwell`).
|
|
185
|
+
- **INT8 Model Weights:** Derived from `Apache-2.0` / `MIT` upstream checkpoints (`cross-encoder/nli-MiniLM2-L6-H768`, `cross-encoder/ms-marco-MiniLM-L-6-v2`, and `cross-encoder/nli-deberta-v3-xsmall`); see [`MODEL_NOTICES.md`](MODEL_NOTICES.md).
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# `epistemic-guard`
|
|
2
|
+
|
|
3
|
+
**Signed tool receipts, Ed25519 memory write-gating, and RAG source deduplication for Python agents.**
|
|
4
|
+
Runs locally on CPU, GPU, or NPU in **3–11 ms**. Zero LLM API calls. MIT License.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## The Three Production Bugs This Library Fixes
|
|
9
|
+
|
|
10
|
+
1. **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.
|
|
11
|
+
2. **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.
|
|
12
|
+
3. **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.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Quickstart
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
pip install epistemic-guard
|
|
20
|
+
|
|
21
|
+
# Optional: download the 4-model OpenVINO INT8 pack (~227 MB download / ~279 MB unpacked, SHA-256 verified)
|
|
22
|
+
epistemic-guard download-models
|
|
23
|
+
|
|
24
|
+
# Run the live 4-part verification demo on CPU
|
|
25
|
+
epistemic-guard demo
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### 1. Catch Phantom Actions (`@signed_tool` + `ReceiptSupervisor` + Streaming)
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
import os
|
|
32
|
+
from epistemic_guard import (
|
|
33
|
+
MerkleReceiptLog,
|
|
34
|
+
ProvenanceGate,
|
|
35
|
+
ReceiptRecorder,
|
|
36
|
+
ReceiptSupervisor,
|
|
37
|
+
SignerFactory,
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
factory = SignerFactory.from_master_key(os.urandom(32))
|
|
41
|
+
gate = ProvenanceGate(factory.public_keys())
|
|
42
|
+
merkle = MerkleReceiptLog(gate=gate)
|
|
43
|
+
recorder = ReceiptRecorder(signer=factory.tool_verified(), merkle_log=merkle)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@recorder.tool # Works on both sync and async functions (MCP, OpenAI, PydanticAI, LangGraph)
|
|
47
|
+
def write_file(path: str, content: str) -> str:
|
|
48
|
+
return f"wrote {len(content)} bytes"
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
write_file("notes.txt", "release checklist")
|
|
52
|
+
|
|
53
|
+
sup = ReceiptSupervisor(device="CPU")
|
|
54
|
+
verdict = sup.verify_narration(
|
|
55
|
+
"I saved your checklist to notes.txt; I also deleted staging.db.",
|
|
56
|
+
receipts=recorder.receipts,
|
|
57
|
+
user_prompt="Save the checklist to notes.txt.",
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
assert verdict.is_valid is False
|
|
61
|
+
print(verdict.unsupported_spans[0])
|
|
62
|
+
# UnsupportedClaimSpan(text='I also deleted staging.db.', start_char=37, end_char=63, claimed_family='CLAIM_DELETE', ...)
|
|
63
|
+
|
|
64
|
+
# Ready-to-send correction prompt for automatic LLM retry loops:
|
|
65
|
+
print(verdict.to_retry_prompt(recorder.receipts))
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
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)`.
|
|
69
|
+
|
|
70
|
+
### 2. Cryptographic Memory Write-Gating (`ProvenanceGate` + `SQLiteProvenanceStore`)
|
|
71
|
+
|
|
72
|
+
`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.
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
import os
|
|
76
|
+
from epistemic_guard import Provenance, ProvenanceGate, SQLiteProvenanceStore, SignerFactory
|
|
77
|
+
|
|
78
|
+
factory = SignerFactory.from_master_key(os.urandom(32))
|
|
79
|
+
gate = ProvenanceGate(factory.public_keys()) # Public keys only — zero private keys in gate
|
|
80
|
+
store = SQLiteProvenanceStore("agent_memory.sqlite", gate) # Append-only SQLite triggers + hash chain
|
|
81
|
+
|
|
82
|
+
env = factory.user_explicit().sign("Deploy freeze starts Friday 18:00 UTC.", trace_id="turn-42")
|
|
83
|
+
store.append(env, expected_provenance=Provenance.USER_EXPLICIT)
|
|
84
|
+
|
|
85
|
+
assert len(store.list_verified()) == 1
|
|
86
|
+
assert store.verify_chain() == 1
|
|
87
|
+
store.close()
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### 3. Multi-Source RAG Deduplication & Hazard Scaling (`corroborate_sources`)
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
from epistemic_guard import corroborate_sources
|
|
94
|
+
|
|
95
|
+
wire_copy = (
|
|
96
|
+
"Clinical guidance notes that initial adult warfarin dosing typically starts at "
|
|
97
|
+
"2 mg to 5 mg once daily with INR monitoring."
|
|
98
|
+
)
|
|
99
|
+
burden = corroborate_sources(
|
|
100
|
+
"What is the recommended starting adult warfarin dosage in mg?",
|
|
101
|
+
[
|
|
102
|
+
{"url": "https://reuters-health.org/a", "snippet": wire_copy},
|
|
103
|
+
{"url": "https://clinical-digest.net/b", "snippet": wire_copy},
|
|
104
|
+
{"url": "https://pharma-bulletin.io/c", "snippet": wire_copy},
|
|
105
|
+
],
|
|
106
|
+
device="CPU",
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
assert burden.deduplicated_duplicates_collapsed == 2
|
|
110
|
+
assert burden.independent_sources_count == 1
|
|
111
|
+
assert burden.meets_casual_burden is False # High-hazard query requires >=3 independent sources
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Measured CPU Performance & Holdout Accuracy (OpenVINO INT8)
|
|
117
|
+
|
|
118
|
+
All four optional neural classifiers run in-process via OpenVINO INT8 (`CPU`, `GPU`, or `NPU`) 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.
|
|
119
|
+
|
|
120
|
+
| Component | INT8 Size | CPU p50 Latency | Locked Holdout Result | Known Failure Modes |
|
|
121
|
+
| :--- | :---: | :---: | :--- | :--- |
|
|
122
|
+
| **`ProvenanceGate` (Ed25519)** | `0 MB` (crypto) | `< 0.3 ms` | `0/100 (0.0%)` natural self-poisoning vs `100/100` in unguarded RAG | Does not fact-check false statements explicitly asserted by an authenticated human user (`USER_EXPLICIT`). |
|
|
123
|
+
| **`action_claim_int8`** (`ReceiptSupervisor`) | `82.7 MB` | `10.9 ms` | `50/50 (100.0%)` on `LOCKED_COH_50`; `99.0%` 10-class speech-act accuracy (`99.7%` FP16 parity) | Fenced code blocks, markdown blockquotes, attributed quotes/dialogue, and creative/translation `user_prompt` contexts are masked automatically; unprompted first-person fiction (`user_prompt=""`) with no dialogue attribution should pass `user_prompt` or use `[ACTION: verb target]` tags. |
|
|
124
|
+
| **`hazard_int8`** (`OpenVINOHazardClassifier`) | `82.7 MB` | `3.2 ms` | `128/130 (98.5%)` safe tier assignment on multi-clause `R-21`; `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. |
|
|
125
|
+
| **`web_evidence_int8` + `nli_int8`** (`corroborate_sources`) | `23.1 MB` + `91.1 MB` | `3.0 ms` / `9.9 ms` | `30/30 (100.0%)` wire/sybil collapse & `43/45 (95.6%)` dispute accuracy on `R-33`; `60/64 (93.8%)` dispute accuracy on `real_web_v1`; `47/64 (73.4%)` burden accuracy & `56/64 (87.5%)` dispute accuracy on single-shot open web (`real_web_v2`); `88/120 (73.3%)` 3-class NLI (`99.2%` FP32 parity) | Implicit cross-article contradictions lacking lexical or single-sentence NLI opposition remain ~26.6% of open-web error cases (`17/64` on `real_web_v2`). |
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## License
|
|
130
|
+
|
|
131
|
+
- **Source Code:** [MIT License](LICENSE) (`Copyright (c) 2026 Sean Maxwell`).
|
|
132
|
+
- **INT8 Model Weights:** Derived from `Apache-2.0` / `MIT` upstream checkpoints (`cross-encoder/nli-MiniLM2-L6-H768`, `cross-encoder/ms-marco-MiniLM-L-6-v2`, and `cross-encoder/nli-deberta-v3-xsmall`); see [`MODEL_NOTICES.md`](MODEL_NOTICES.md).
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "epistemic-guard"
|
|
3
|
+
version = "0.3.0"
|
|
4
|
+
description = "Signed tool receipts, Ed25519 memory write-gating, and RAG source deduplication for Python agents (CPU/NPU, zero LLM calls)"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = { file = "LICENSE" }
|
|
7
|
+
authors = [{ name = "Sean Maxwell" }]
|
|
8
|
+
requires-python = ">=3.10"
|
|
9
|
+
keywords = [
|
|
10
|
+
"agents",
|
|
11
|
+
"mcp",
|
|
12
|
+
"tool-calling",
|
|
13
|
+
"ed25519",
|
|
14
|
+
"provenance",
|
|
15
|
+
"rag",
|
|
16
|
+
"openvino",
|
|
17
|
+
"guardrails",
|
|
18
|
+
]
|
|
19
|
+
classifiers = [
|
|
20
|
+
"Development Status :: 4 - Beta",
|
|
21
|
+
"Intended Audience :: Developers",
|
|
22
|
+
"License :: OSI Approved :: MIT License",
|
|
23
|
+
"Programming Language :: Python :: 3",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"Programming Language :: Python :: 3.13",
|
|
28
|
+
"Topic :: Security :: Cryptography",
|
|
29
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
30
|
+
]
|
|
31
|
+
dependencies = [
|
|
32
|
+
"pydantic>=2.7.0",
|
|
33
|
+
"cryptography>=42.0.0",
|
|
34
|
+
"numpy>=1.26.0",
|
|
35
|
+
"openvino>=2025.0.0",
|
|
36
|
+
"tokenizers>=0.19.0",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[project.optional-dependencies]
|
|
40
|
+
dev = [
|
|
41
|
+
"pytest>=8.0.0",
|
|
42
|
+
"import-linter>=2.0.0",
|
|
43
|
+
"ruff>=0.6.0",
|
|
44
|
+
"mypy>=1.11.0",
|
|
45
|
+
]
|
|
46
|
+
|
|
47
|
+
[project.scripts]
|
|
48
|
+
epistemic-guard = "epistemic_guard.cli:main"
|
|
49
|
+
|
|
50
|
+
[project.urls]
|
|
51
|
+
Repository = "https://github.com/AlienatedAliens/ProjectLucca/tree/main/packages/epistemic-guard"
|
|
52
|
+
Issues = "https://github.com/AlienatedAliens/ProjectLucca/issues"
|
|
53
|
+
|
|
54
|
+
[build-system]
|
|
55
|
+
requires = ["hatchling"]
|
|
56
|
+
build-backend = "hatchling.build"
|
|
57
|
+
|
|
58
|
+
[tool.hatch.build.targets.wheel]
|
|
59
|
+
packages = ["src/epistemic_guard"]
|
|
60
|
+
|
|
61
|
+
[tool.hatch.build.targets.sdist]
|
|
62
|
+
include = [
|
|
63
|
+
"/src",
|
|
64
|
+
"/tests",
|
|
65
|
+
"/LICENSE",
|
|
66
|
+
"/MODEL_NOTICES.md",
|
|
67
|
+
"/README.md",
|
|
68
|
+
]
|
|
69
|
+
|
|
70
|
+
[tool.pytest.ini_options]
|
|
71
|
+
testpaths = ["tests"]
|
|
72
|
+
|
|
73
|
+
[tool.mypy]
|
|
74
|
+
strict = true
|
|
75
|
+
|
|
76
|
+
[[tool.mypy.overrides]]
|
|
77
|
+
module = ["openvino.*", "tokenizers.*"]
|
|
78
|
+
ignore_missing_imports = true
|
|
79
|
+
|