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.
@@ -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
+