Skip to content

About

Autonomous local-first desktop companion with cryptographic provenance memory and grounded receipt supervision

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

673 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Project Lucca

Ed25519 provenance memory, clause-level tool-receipt supervision, and hazard-scaled RAG corroboration — built inside a local-first Windows neurosymbolic agent testbed.


Two Ways to Use Project Lucca

1. Standalone Verification Library (epistemic-guard, MIT License)

Runs on Linux, macOS, and Windows (CPU, GPU, or NPU in 3–11 ms, zero LLM calls, zero UI/audio/WSL2/Docker dependencies):

pip install epistemic-guard
epistemic-guard demo
import os
from epistemic_guard import (
    MerkleReceiptLog,
    Provenance,
    ProvenanceGate,
    ReceiptRecorder,
    ReceiptSupervisor,
    SQLiteProvenanceStore,
    SignerFactory,
    corroborate_sources,
)

# 1. RFC 8032 Ed25519 domain-separated provenance signing & append-only SQLite write gate
factory = SignerFactory.from_master_key(os.urandom(32))
gate = ProvenanceGate(factory.public_keys())
store = SQLiteProvenanceStore(":memory:", gate)

signed_record = factory.user_explicit().sign("Deploy freeze starts Friday 18:00 UTC.", trace_id="tr-01")
store.append(signed_record, expected_provenance=Provenance.USER_EXPLICIT)
assert store.verify_chain() == 1

# 2. @signed_tool receipts + clause-level & streaming supervision (with character spans + retry prompt)
merkle = MerkleReceiptLog(gate=gate)
recorder = ReceiptRecorder(signer=factory.tool_verified(), merkle_log=merkle)


@recorder.tool
def write_file(path: str, content: str) -> str:
    return f"wrote {len(content)} bytes"


write_file("notes.txt", "release checklist")
supervisor = ReceiptSupervisor(device="CPU", warn_on_missing=False)
verdict = supervisor.verify_narration(
    "I saved your summary to notes.txt; I also deleted backup.sql.",
    receipts=recorder.receipts,
    user_prompt="Save the summary to notes.txt.",
)
assert verdict.is_valid is False  # catches unexecuted backup.sql deletion clause

# 3. Multi-source RAG syndication deduplication & hazard-scaled corroboration
burden = corroborate_sources(
    "Why should honey never be fed to infants younger than twelve months?",
    [
        {
            "url": "https://www.cdc.gov/botulism/infant-honey.html",
            "title": "Infant Botulism Prevention",
            "content_preview": "Honey should never be fed to infants younger than 12 months because Clostridium botulinum spores cause infant botulism.",
        },
        {
            "url": "https://www.nhs.uk/baby/weaning/foods-to-avoid/",
            "title": "Foods to Avoid Giving Babies",
            "content_preview": "Babies under 1 year old must not eat honey due to the risk of infant botulism toxin.",
        },
        {
            "url": "https://www.mayoclinic.org/infant-health/honey",
            "title": "Infant Honey Safety",
            "content_preview": "Avoid giving honey to infants under twelve months; Clostridium spores can cause infant botulism.",
        },
    ],
    device="CPU",
    warn_on_missing=False,
)
assert burden.meets_casual_burden is True
store.close()

2. Full Local-First Desktop Companion (src/lucca/)

# 1. Verify environment, GPU/OpenVINO devices, and model SHA-256 manifest pins
uv run python -m lucca.core.env_check

# 2. Run static architecture gates (40/40) and unit test suite
uv run pytest tests/test_static_gates.py
uv run pytest

# 3. Launch multi-process companion supervisor (UI + Core + Senses + Sandbox)
uv run python -m lucca.main

System Architecture

flowchart LR
    User(["Voice / Text Input"]) --> Senses["Senses Process<br/>Whisper ASR + DeBERTa NLI"]
    Senses --> Router["OpenVINO Intent Router<br/>REFLEX / ACT / FULL_LOOP (M=4)"]
    Router --> Brain["Local GGUF Brain<br/>llama-server (Gemma-4 Q6_K)"]
    Router --> Symbolic["Symbolic Lobes<br/>MicroScheme + Z3 + SymPy + CEGIS"]
    Brain <--> Sandbox["Isolated Docker Sandbox<br/>19 Native Tools + Scrapling Web"]
    Sandbox --> Burden["2D Evidentiary Burden Gate<br/>Relevance + Shingle Dedup + Hazard"]
    Burden --> Brain
    Brain --> Supervisor["Clause-Level Receipt Supervisor<br/>OpenVINO NPU/CPU + ToolReceipts"]
    Supervisor --> Memory["Ed25519 Provenance Memory<br/>SQLite-vec + Belnap Bilattice"]
    Supervisor --> Output(["Verified Speech / UI Output"])
Loading

Four Core Engineering Pillars

  1. Cryptographic Provenance Memory (src/lucca/memory/): Long-term memory writes require domain-separated RFC 8032 Ed25519 signatures verified by a public-key-only ProvenanceGate. Unverified assistant prose cannot self-certify into durable factual memory, while BelnapLatentInvestigator tracks 4-valued paraconsistent truth states (TRUE, FALSE, BOTH, NEITHER) and fails closed on UNCERTAIN NLI verdicts.
  2. Clause-Level Receipt Supervision (src/lucca/sandbox/): Assistant responses are split into syntactic clauses and scored by an OpenVINO classifier (models/action_claim_verifier_ov, 0 MB GPU VRAM) paired with deterministic ToolReceipt set verification and [ACTION: ...] Structured Output Action Contracts (SOAC), blocking unexecuted tool fabrications before speech synthesis or memory commit.
  3. 2D Hazard-Scaled Open-Web Evidentiary Burden (src/lucca/core/proof_policy.py, walton_schemes/): Open-web ResearchTool dossiers pass through OpenVINO passage-relevance filtering (web_relevance.py), shingle/SimHash + bidirectional NLI syndication deduplication (dedup.py), and multi-clause hazard lattice pooling (proof_policy_hazard_v3_ov + ConformalGuard). Required independent corroboration scales with query hazard (LOW -> 1, MEDIUM -> 2, HIGH -> 3 independent eTLD+1 publishers), and cross-source contradictions inject structured conflict disclosure metadata (Arm D).
  4. Bicameral Symbolic & Sandboxed Execution (src/lucca/reasoning/, src/lucca/core/): Procedural rules induced during offline consolidation (ConsolidationEngine) are quarantined behind Z3 SMT safety checks, require an Ed25519-signed OperatorApprovalToken to promote to ACTIVE, and demote on a 1-strike user correction. File, shell, math, and web tools execute inside a memory-clamped WSL2 Docker container.

See Unified System Architecture Specification for the full 4-process IPC contract (199 reachable modules in src/lucca/, 8/8 Import-Linter boundary contracts).


Hardware Tiers (Full Desktop Companion)

VRAM scales with the selected GGUF model at ctx=32768 (q1_vram_nvidia_smi_evidence.json). An Intel AI Boost NPU is optional; OpenVINO automatically uses the NPU when present (6.58 ms mean web-burden gate latency) and falls back to OpenVINO CPU when absent (16.92 ms mean on Core Ultra 9 275HX, r06_gate_latency_npu_vs_cpu.json).

Model Tier (Q6_K GGUF) Recommended dGPU VRAM Resident VRAM (ctx=32768) Recommended System RAM Notes
Gemma-4-E2B 4–6 GB+ ~2.7 GiB 16 GB Compact low-latency local companion
Gemma-4-E4B 6–8 GB+ ~4.8–5.0 GiB 16 GB Balanced everyday voice & tool tier
Gemma-4-12B 12 GB+ ~10.9 GiB 16–24 GB Primary dense reasoning & coding tier
Gemma-4-26B-A4B MoE 12–16 GB ~11.5 GiB 32 GB+ --cpu-moe --moe-cache-mib 7680 expert offload
  • OS (Full Companion): Windows 11 64-bit with WSL2 (4.5 GB .wslconfig cap) and Docker CE, Python 3.12+ via uv.
  • Cross-Platform (epistemic-guard): Linux, macOS, or Windows (Python 3.10+, CPU/GPU/NPU, MIT License).

Empirical Evaluation Summary

All active benchmarks below were executed against live llama-server GGUF models, isolated SQLite stores, or archived live-web HTML corpora on local workstation silicon (RTX 5080 Laptop GPU, Core Ultra 9 275HX). Pre-registered holdouts (G4 v3, G5, G6, and WO-46 real_web_v2) enforce a strict lock -> corpus -> results OpenTimestamps + origin/main commit chain.

Evaluation Suite Experimental Setup Key Result (Author-Measured, [95% Wilson CI]) Evidence Artifacts
Multi-Session Memory Poisoning Resistance (N=300) 5-arm ablation (100 natural confabulations, 100 benign reasoning, 100 adversarial user falsehoods; 1,500 live E4B turns; blinded LLM-rater IRR $\kappa = 0.9206$) 0/100 (0.0% [0.0%, 4.6%]) poisoning on natural confabulations vs 100/100 (100.0%) Naive RAG ($p = 4.16 \times 10^{-23}$) and 11/100 (11.0%) Passive Soft Tagging ($p = 9.77 \times 10^{-4}$); 100/100 Cohort A factual continuity & 100/100 Cohort B benign reasoning retention (0/200 false rejections vs 98%–99% continuity loss from blanket assistant-memory blocking) memory_poisoning_v3_300_results.json, wo39_live_4models_rebench.json
Contrastive Companion Recall, Receipt Introspection & Abstention (N=300) 300 items (100 seeded recall, 100 receipt introspection, 100 abstention) $\times$ 3 arms (900 live E4B turns; blinded LLM-rater $\kappa = 1.0000$) Recall: 100/100 (100.0% [95.4%, 100.0%]) vs 2/100 (2.0%) Bare LLM and 85/100 (85.0%) Hybrid RAG ($p_{\text{HB}} = 3.05 \times 10^{-4}$); Receipt Introspection: 100/100 (100.0%); Abstention: 100/100 (100.0%) contrastive_v2_300_results.json, contrastive_v2_300_results_REPORT.md
Clause-Level Action-Claim Supervision & Intent Routing (N=379 Held-Out + N=540 Blind/Locked + 100 Live E2E) 3 zero-VRAM OpenVINO classifiers (action_claim_verifier_ov, proof_policy_hazard_ov, router_intent_ov) across strictly held-out supervision splits, Blind-390, SHA-256 locked Holdout-150, and 4-model live orchestrator • Strictly Held-Out Supervision (N=379): 243/249 (97.6%) on W751_W1000_26B_Heldout, 98/100 (98.0%) on Organic_Heldout_H100, 29/30 (96.7%) on Implicit_ZeroVerb_IMP30 (vs 88.8% / 91.0% / 50.0% internal regex baseline wo40_regex_v3_0; pooled discovery+heldout N=2,022 is 99.3%)
• Locked Holdout (N=150): 145/150 (96.7% [92.4%, 98.6%]) single-pass (50/50 coherence, 50/50 hazard, 45/50 -> 50/50 router post-fix)
• Live 4-Model E2E (N=100): 100/100 (100.0%) grounding, 98/100 (98.0%) task completion
wo42_large_sample_2020_report.json, wo42_locked_holdout_150_report.json, wo42_live_4model_summary.json
Structured Output Action Contract (SOAC, 720 Live Turns) 120 held-out prompts on 26B-A4B across Natural, SOAC, and SOAC+GBNF (6.82 µs parser; dual blinded LLM-rater $\kappa = 1.0000$) 0/120 (0.0% [0.0%, 3.9%]) unframed prose action leakage across v1 SOAC, v2 SOAC, and v2 SOAC+GBNF (100% [ACTION: ...] frame coupling) paper2_v1_v2_semantic_audit_720.json
4-Arm Web Evidentiary Burden & Conflict Disclosure (N=132 Items, 2,640 Live Turns) 132 disjoint items $\times$ 4 arms (A bare, B full policy, C generic tip, D structured contract without legal phrasing) $\times$ 5 Gemma-4 models at ctx=32768; 3 non-Google LLM judge families (Qwen3.8-27B, Phi-4-14B, Nemotron-3.5-30B-A3B) Disputed Conflict Disclosure (660 turns, $\min\kappa = 0.6983$): 164/165 (99.4% [98.2%, 100.0%]) Arm D vs 85/165 (51.5%) Arm C (+47.9 pp, $p = 0.0001$, 79:0 discordant) and 61/165 (37.0%) Arm A; Faithful Substantive Answering: 648/660 (98.2%) Arm D vs 612/660 (92.7%) Arm C ($p = 0.0001$); Nominal-Met Over-Hedging (D3 $\min\kappa = 0.8811$): 18/330 (5.5%) Arm D vs 24/330 (7.3%) Arm C and 47/330 (14.2%) Arm A GATE_G4v3.md, g4_live_v3_report.json
Multi-Clause Hazard (N=130), Sybil Dedup (N=45), & Out-of-Sample Live Open-Web Scrapling (N=64 v2) Author-administered OpenTimestamps holdouts: disjoint proof_policy_hazard_v3_ov (N=130); fresh Domain Set B wire/sybil dedup (N=45); single-shot live ResearchTool/Scrapling real_web_v2 (N=64 fresh queries, 246 .html.gz pages, dual blinded LLM-rater $\kappa = 0.9107$–$1.0000$) • Multi-Clause Hazard (N=130): 126/130 (96.9% [92.4%, 98.8%]) conservative safe (119/130 [91.5%] strict 3-class, 0/45 benign false escalations to HIGH)
• Sybil / Wire Dedup (N=45): False corroboration cut 38/45 (84.4%) -> 3/45 (6.7% [2.3%, 17.9%])
• Live Open-Web real_web_v2 (N=64, WO-46): 46/64 (71.9% [59.9%, 81.4%]) burden decision accuracy (up from 39/64 [60.9%] on historical v1), 56/64 (87.5% [77.2%, 93.5%]) dispute accuracy (3.6% [2/55] FPR vs 24.0% in v1), 32/39 (82.1%) sufficient-evidence utility pass (12.5% [2/16] low-hazard over-hedge), 56/64 (87.5%) within-1 source count (29/64 [45.3%] exact, MAE = 0.72), 55/64 (85.9%) safe hazard
real_web_v2_report.json, r21_hazard_holdout_report.json, r33_sybil_dedup_report.json, r32_real_web_v1_report.json
OpenVINO CPU NLI Cross-Encoder (N=120 Hard Paraphrase Holdout & N=100 pairs_v1) DeBERTa-v3-xsmall vs MiniLM-L6 (0 MB VRAM, 20.47 ms p50 / 26.70 ms p95) Out-of-sample nli_holdout_v2_120: 82/120 (68.3% [59.6%, 76.0%]) vs 67/120 (55.8%) MiniLM-L6 ($p = 0.0107$; 40.0% [16/40] entailment recall at 100.0% precision); pairs_v1: 91/100 (91.0% [83.8%, 95.2%]) nli_verifier_v2_report.json
LongMemEval Temporal Memory (N=30), Live Rule Induction (52 Turns), & Symbolic/Coding Suites LongMemEval (12B), organic IN-D Z3 rule induction (12B), Sealed Parametric Neurosymbolic Suite (v139), Docker HumanEval/HumanEval+ (N=164), GSM-Symbolic (N=100), MATH-500 (N=500) • LongMemEval: 21/30 (70.0% [52.1%, 83.3%]) vs 7/30 (23.3%) context truncation ($p = 0.000122$, 8.1 ms retrieval)
• Z3 Rule Induction: 8/8 held-out recall (0.14 ms), 0/8 misfires
• Sealed Neurosymbolic (v139): 15/15 (100.0%) on 26B/12B/E4B (14/15 on E2B)
• Coding & Math (12B): 155/164 (94.5%) HumanEval, 150/164 (91.5%) HumanEval+, 94/100 (94.0%) GSM-Symbolic, 429/500 (85.8%) strict / 451/500 (90.2%) lenient MATH-500 Fresh
longmemeval_pipeline_12B_1791794644.json, in_d_live_baseline_wo39.json, RESULTS.md
Static Architecture & Hygiene Gates Zero-Any in public APIs, LOC ceilings, NLI fail-closed enforcement, 100% module reachability, anti-contamination, zero ruff/mypy errors 40/40 static gates passed, 8/8 Import-Linter contracts kept tests/test_static_gates.py, .importlinter

Research Preprints & Technical Documentation


Scope & Residual Engineering Boundaries

  • Single-workstation & self-administered evaluation disclosure: All latency, VRAM, and accuracy metrics in this repository are author-measured on a single local workstation (RTX 5080 Laptop GPU, Core Ultra 9 275HX, Windows 11) with zero external production telemetry. Pre-registered holdouts (G4 v3, G5, G6, WO-46) use git + OpenTimestamps SHA-256 locks administered by the author, and inter-rater reliability ($\kappa$) reflects blinded LLM raters (including cross-family non-Google judges on G4 v3), not human crowdworkers. Several live evaluation suites include community uncensored ("Heretic") GGUF weights specifically to stress-test whether deterministic ProvenanceGate and ReceiptSupervisor checks still hold when upstream RLHF safety refusals are absent. Full harness scripts, frozen .html.gz corpora, and detached .ots proofs are provided in REPRODUCING.md for external replication.
  • English-only neural classifiers & empirical error bounds: All OpenVINO neural classifiers (action_claim, hazard, router_intent, nli) are trained and evaluated on English text and operate as empirical runtime filters rather than formal completeness proofs:
    • Action-claim supervision (wo42_large_sample_2020_report.json): Across strictly held-out splits (N=379), misses (5/143 [3.5%] FN, 4/236 [1.7%] FP) occur on zero-verb indirect state-consequence phrasing and un-fenced walkthrough prose (6/471 [1.3%] FN and 9/1,551 [0.6%] FP across pooled discovery+heldout N=2,022).
    • Fail-closed NLI clustering (nli_verifier_v2_report.json): All NLI consumers fail closed on UNCERTAIN/NEUTRAL verdicts (100% entailment precision, 40.0% [16/40] recall on low-lexical-overlap paraphrases), conservatively withholding ambiguous paraphrases rather than merging unverified claims.
    • Unfiltered open-web retrieval (real_web_v2_report.json): Upgrading query simplification, eTLD+1 candidate diversity, OpenVINO passage-relevance filtering, and prohibitive consensus normalization raised single-shot live Scrapling burden accuracy from 39/64 (60.9%) (v1) to 46/64 (71.9%) (v2), dispute accuracy from 42/64 (65.6%) to 56/64 (87.5%), and within-1 source count from 45/64 (70.3%) to 56/64 (87.5%). Residual errors (18/64: 11 false burden passes and 7 conservative over-hedges) arise primarily when a scientific debate is summarized implicitly without explicit controversy markers (3/9 live dispute recall) or when a borderline technical query classifies 1 tier below HIGH (46/64 strict 3-class vs 55/64 conservative safe hazard).
  • Platform footprint: The 4-process voice/UI/Docker desktop stack requires Windows 11 + WSL2, whereas epistemic-guard provides the standalone verification gates on Linux, macOS, and Windows CPU/GPU/NPU.

License

About

Autonomous local-first desktop companion with cryptographic provenance memory and grounded receipt supervision

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages