PiSovereign

Warning

This project is under active development. Use at your own risk. Breaking changes may occur without notice.

A self-hosted, privacy-first AI assistant platform with advanced AI reasoning, post-quantum security, and privacy-preserving analytics — deploy anywhere with Docker Compose.

PiSovereign runs a complete AI assistant stack on your own hardware. All inference stays local via Ollama — no data ever leaves your network. Interact through Signal, WhatsApp, or the HTTP API, and connect it to your calendar, email, contacts, weather, transit, and web search. With 30 research-backed innovation features — including neuromorphic memory, causal reasoning, affective computing, federated sovereign learning, a sovereign mesh network, zero-knowledge decision proofs, self-evolving prompt optimization, and a real-time digital sovereignty score — PiSovereign is the most advanced self-hosted AI platform available. Optimized for the Raspberry Pi 5 with Hailo-10H NPU but runs on any Docker-capable machine with sufficient resources.

Full Documentation

Features

Core Platform

• 100% Local Inference — LLM via Ollama with dynamic model routing by complexity
• Docker Compose Deployment — Single-command setup for all services
• Signal & WhatsApp — Bidirectional messaging with voice message support
• Voice Processing — Local STT (whisper.cpp) and TTS (Piper), optional OpenAI cloud fallback
• Calendar & Contacts — CalDAV/CardDAV integration (Baïkal, Radicale, Nextcloud)
• Email — IMAP/SMTP with any provider (Gmail, Outlook)
• Weather & Transit — Open-Meteo forecasts, German public transit routing (HAFAS)
• Web Search — Brave Search with automatic DuckDuckGo fallback
• Persistent Memory — RAG-based memory with embeddings, decay, and XChaCha20 encryption
• Dream Mode — Biologically-inspired nightly processing with NREM/REM cycles for autonomous memory consolidation, pattern discovery, and hypothesis generation
• Reminders & Morning Briefings — Natural language scheduling in English and German
• Snippets — Reusable Markdown text blocks with /snippet chat trigger, nested resolution, and full CRUD API
• Vault Secrets — HashiCorp Vault for runtime credential management
• Observability — Prometheus, Grafana, Loki, and OpenTelemetry
• GDPR Compliant — All processing happens on your hardware

Innovation Features

PiSovereign goes beyond standard self-hosted AI assistants with 30 research-backed innovation features — no other platform comes close:

🔬 Sovereign Intelligence Engine

All innovation features communicate through a unified pub/sub signal bus (SovereignIntelligenceEngine), enabling emergent cross-feature intelligence — e.g., thermal state from the energy monitor automatically pauses pre-caching, or affective state modulates cognitive load estimation.

🧠 Advanced AI

• Neuromorphic Memory Architecture — Three-store hippocampal model (episodic, semantic, procedural) with automatic consolidation during low-usage periods
• Causal Reasoning Engine — Structural Causal Models with do-calculus for "why" and "what if" questions beyond correlational RAG
• Local Continual Learning (LoRA) — Privacy-preserving model personalization via LoRA adapters with Elastic Weight Consolidation to prevent catastrophic forgetting
• Cognitive Load-Adaptive Response Shaping — 5-signal estimation (circadian, duration, latency, complexity, multitask) that shapes responses into 3 formats: bullet points, narrative, or TL;DR-first
• Predictive Cognitive Pre-Caching — Bayesian prediction engine that pre-generates answers before the user asks, with thermal-aware scheduling and event-driven invalidation
• Dream Mode — Autonomous nightly cognitive processing inspired by human sleep: alternating NREM (memory consolidation, archival, deduplication) and REM (cross-domain pattern detection, hypothesis generation, proactive "Did you know?" insights) cycles with a full dream journal audit trail
• Automated Self-Sanitation — Dream-integrated self-healing phase (NREM → SANIT → REM) with six subsystems: LLM-assisted memory hygiene, knowledge graph integrity checking, adversarial defense evolution, config drift correction, quality regression detection, and behavioral anomaly monitoring — quarantined memories auto-purge after a configurable TTL
• Affective Computing — Detects emotional state from text + voice prosody, subtly modulates response tone (patient, calm, enthusiastic) with 7-day half-life persistence
• Self-Evolving Prompt Optimization — Prompt variants evolve through Thompson Sampling and Bayesian mutation with automatic red-team security guardrails
• Neuroplastic Model Routing — LinUCB contextual bandit replaces static rules, learning optimal model selection per user after 50 interactions
• Embodied Context Anchoring — Spatial memory links memories to physical rooms for location-weighted RAG retrieval (1.5× boost)
• Bayesian Self-Optimization — Automatic tuning of system parameters (cache TTL, similarity thresholds, rate limits) via Gaussian Process surrogate models
• Multi-Agent Swarm — Specialized micro-agents (researcher, planner, executor, critic) with Rust type-system-verified safety invariants
• Cross-Modal Reasoning Fusion — Unified embeddings across chat, email, calendar, contacts, and voice for cross-modal semantic queries
• Edge Model Distillation — Hardware-specific model optimization pipeline using teacher-student distillation, optimized for each user's actual usage patterns
• Explainable AI Dashboard — Full decision provenance with causal counterfactual explanations: "I chose model A; model B would have been 3× slower but 10% more precise"

🔒 Advanced Security

• Post-Quantum Cryptography (PQC) — ML-KEM-768 key encapsulation and ML-DSA-65 digital signatures alongside existing ChaCha20-Poly1305
• Adversarial Self-Audit Immune System — Daily automated red-team attacks (20 variants across 8 categories) with auto-hardening of the Aho-Corasick pattern set via hot-reload
• Zero-Knowledge Decision Proofs — SHA-256 Merkle-tree proofs over all tool execution decision traces with selective disclosure for compliance audits
• Homomorphic Semantic Search — Cosine similarity on encrypted embeddings without decryption for zero-knowledge RAG

📊 Privacy & Analytics

• Formal ε-Budget Accounting — User-visible daily privacy budget (ε = 1.0/day) with automatic degradation when exhausted — embeddings stop, memories persist as text
• Temporal Knowledge Decay Visualization — Interactive Three.js WebGL knowledge graph showing real-time Ebbinghaus memory decay, node types, and causal edges with hover tooltips
• Ebbinghaus Decay Knowledge Graphs — Forgetting curves (R = e^(-t/S)) with spaced repetition and temporal knowledge versioning
• Differential Privacy Analytics — Formal ε-differential privacy (Laplace/Gaussian mechanisms) for all internal analytics and learning signals
• Digital Sovereignty Score & Dashboard — Real-time 0–100 privacy posture score across data locality, encryption, secret management, and network isolation

🌐 Decentralized & Edge

• Sovereign Mesh Network — Peer-to-peer inference fallback via LAN mDNS discovery with mTLS encryption; altruistic compute sharing between trusted instances
• Federated Sovereign Learning — LoRA weight synchronization between opt-in peers with differential privacy (ε = 1.0, δ = 10⁻⁵) — no raw data ever exchanged
• Energy-Aware Inference Scheduling — Abstract thermal/carbon monitoring with platform-specific adapters (Pi 5 sysfs, RAPL, Docker stats) and optional carbon-intensity-aware deferral
• Quantum-Inspired Approximate Search (HDC) — 10,000-bit hyperdimensional binary vector pre-filter for pgvector with automatic fallback when recall drops below 90%

Security

PiSovereign is built with a defense-in-depth security architecture:

Layer	Mechanism	Purpose
Input	Prompt injection detection	Block malicious prompts before they reach the LLM
Output	PII/credential redaction	Strip emails, phones, API keys, passwords from AI responses
RAG	Context sanitization	Redact sensitive data from retrieved memories before prompt injection
Network	Ollama network isolation	Internal-only Docker network prevents LLM data exfiltration
Auth	Argon2id API keys	Hashed API key authentication (plaintext rejected at startup)
Secrets	HashiCorp Vault	Runtime credential retrieval — secrets never touch config files
Transport	TLS 1.2+ enforcement	Enforced minimum TLS version for all outbound connections
Storage	ChaCha20-Poly1305	Encrypted conversation persistence with per-user key derivation
PQC	ML-KEM-768 + ML-DSA-65	Post-quantum key encapsulation and digital signatures (NIST-standardized)
Red Team	Autonomous adversarial testing	Continuous OWASP LLM Top 10 attack simulation with auto-updated defenses
Homomorphic	Encrypted vector search	Cosine similarity on encrypted embeddings — plaintext never in DB
Privacy	ε-Differential privacy	Formal privacy guarantees on all internal analytics and learning signals
Memory	secrecy::SecretString	Automatic zeroization of credentials on drop
Headers	HSTS, CSP, X-Frame-Options	Security headers on every HTTP response
Rate limiting	Per-IP throttling	Configurable RPM with automatic cleanup
Audit	Structured tracing	Every security event (redaction, injection, block) is logged
Code	#![forbid(unsafe_code)]	Enforced across all workspace crates
Validation	Startup security checks	Production startup blocked on critical security misconfigurations
Immune System	Auto-hardening prompt defense	Daily adversarial self-audit with immediate Aho-Corasick pattern hot-reload
ZK Proofs	Merkle-tree decision verification	SHA-256 proofs over all tool execution traces with selective disclosure
Privacy Budget	Formal ε-accounting	Daily ε = 1.0 budget with automatic degradation when exhausted
Mesh E2E	Peer-to-peer encrypted inference	mTLS + per-request encryption for mesh and federated sync

Quick Start

# 1. Clone
git clone https://github.com/twohreichel/PiSovereign.git
cd PiSovereign/docker

# 2. Configure
cp .env.example .env
nano .env  # Set your domain and email for TLS

# 3. Deploy
docker compose up -d

# 4. Initialize Vault (first time only — save the printed unseal key!)
docker compose exec vault /vault/init.sh

PiSovereign is now running at https://your-domain.example.com.

Post-Setup

# Store integration secrets in Vault
docker compose exec vault vault kv put secret/pisovereign/whatsapp \
  access_token="..." app_secret="..."

# Register Signal number (see docs for details)
docker compose exec signal-cli signal-cli -a +49170... register

# Or copy existing local signal-cli config into Docker
just docker-signal-copy-config

# Enable monitoring (optional)
docker compose --profile monitoring up -d

# Verify
curl https://your-domain.example.com/health

Architecture

                        ┌─────────────┐
                        │ Mesh Peers  │
                        │ (mDNS/mTLS) │
                        └──────┬──────┘
┌──────────────────────────────┼───────────────────────┐
│                   Traefik (TLS + PQC)                │
├──────────┬──────────┬──────────┬──────────┬──────────┤
│  PiSov-  │  Ollama  │ Signal-  │ Whisper  │  Piper   │
│  ereign  │  (LLM)   │   CLI    │  (STT)   │  (TTS)   │
├──────────┴──────────┴──────────┴──────────┴──────────┤
│  SovereignIntelligenceEngine · Signal Bus · 30 AI    │
│  Features · Mesh · Federated Learning · ZK Proofs    │
├──────────────────────────────────────────────────────┤
│                   Vault (Secrets)                     │
├──────────────────────────────────────────────────────┤
│            Docker Compose Network                    │
│    (+ isolated Ollama · Red Team · DP Analytics)     │
└──────────────────────────────────────────────────────┘

Docker Compose Profiles

Profile	Services
(core)	PiSovereign, Traefik, Vault, Ollama, Signal-CLI, Whisper, Piper
monitoring	Prometheus, Grafana, Loki, Promtail, Node Exporter, OTel Collector
caldav	Baïkal CalDAV/CardDAV server

# Core only
docker compose up -d

# Everything
docker compose --profile monitoring --profile caldav up -d

Documentation

Guide	Description
Getting Started	5-minute Docker deployment
Hardware Setup	Raspberry Pi 5 + Hailo-10H assembly
Docker Setup	Detailed deployment and operations guide
Configuration	All config.toml options
External Services	WhatsApp, Signal, email, CalDAV, search setup
Innovation Features	All 15 research-backed AI, security, and privacy innovations
Architecture	Clean Architecture overview
API Reference	REST API with OpenAPI spec
Monitoring	Grafana dashboards and alerting

Development

# Install just task runner
cargo install just

# Run all lints
just lint

# Run tests
just test

# Build release
just build-release

# Full quality check
just quality

Storage Requirements

Full deployment with all AI models and Docker images. Actual sizes vary by platform (arm64/amd64).

AI Models (Ollama)

Model	Role	Size
gemma4:31b	Complex inference (code, analysis, creative writing)	~9.1 GB
gemma4:26b	Moderate tasks (multi-turn conversations)	~6.0 GB
gemma4:e4b	Simple tasks (short factual queries)	~3.0 GB
nomic-embed-text	Embedding / RAG	~274 MB
Models total		~18.4 GB

Docker Images (Core)

Image	Service	Size
ollama/ollama:latest	LLM inference engine	~2.5 GB
pgvector/pgvector:pg17	PostgreSQL + pgvector	~430 MB
traefik:v3.2	Reverse proxy	~170 MB
hashicorp/vault:1.15	Secret store	~350 MB
PiSovereign (built)	Application server	~350 MB
Whisper (built)	Speech-to-text	~1.5 GB
Piper (built)	Text-to-speech	~500 MB
Signal-CLI (built)	Signal messenger	~400 MB
Core images total		~6.2 GB

Docker Images (Optional Profiles)

Image	Profile	Size
prom/prometheus:latest	monitoring	~280 MB
grafana/grafana:latest	monitoring	~450 MB
grafana/loki:latest	monitoring	~120 MB
grafana/promtail:latest	monitoring	~200 MB
prom/node-exporter:latest	monitoring	~25 MB
otel/opentelemetry-collector-contrib:latest	monitoring	~300 MB
ckulka/baikal:nginx	caldav	~90 MB
Sandbox (built)	sandbox	~150 MB
Optional images total		~1.9 GB

Summary

Component	Disk Space
AI models (all 4)	~13.3 GB
Docker images (core)	~6.2 GB
Docker images (all optional profiles)	~1.6 GB
Database + application data	~100 MB (initial)
Total (core)	~19.5 GB
Total (everything)	~21.5 GB

Note: RAM requirements depend on OLLAMA_MAX_LOADED_MODELS. With adaptive model routing enabled (default: 3 models loaded), expect 8–12 GB RAM for the Ollama container on CPU, or equivalent VRAM on GPU.

Support

If you find PiSovereign useful, consider sponsoring the project.

License

MIT © Andreas Reichel