A teenager-friendly guide to PiSovereign’s architecture and features
What is PiSovereign? It’s your own private AI assistant that runs on your computer (or a Raspberry Pi) instead of sending your data to the cloud. Think of it as having ChatGPT, but it lives in your house and keeps all your conversations private.
This page explains all the cool stuff PiSovereign can do using simple terms and real-world comparisons.
PiSovereign is organized like a well-run school where each department has clear responsibilities and rules about who talks to whom.
┌─────────────────────────────────────────────────────────────┐
│ 🖥️ PRESENTATION (What you see and interact with) │
│ Web UI, REST API, Command Line │
├─────────────────────────────────────────────────────────────┤
│ 🔌 INFRASTRUCTURE (The plumbing) │
│ Database, Cache, Secrets, Metrics │
├─────────────────────────────────────────────────────────────┤
│ 🔗 INTEGRATION (Connections to the outside world) │
│ WhatsApp, Signal, Email, Calendar, Weather, Transit │
├─────────────────────────────────────────────────────────────┤
│ 🧠 AI (The smart stuff) │
│ LLM Inference, Speech-to-Text, Text-to-Speech │
├─────────────────────────────────────────────────────────────┤
│ ⚙️ APPLICATION (Business logic) │
│ Services, Use Cases, Rules │
├─────────────────────────────────────────────────────────────┤
│ 💎 DOMAIN (Core rules and data) │
│ Entities, Value Objects, Commands │
└─────────────────────────────────────────────────────────────┘
The Golden Rule: Inner layers never depend on outer layers. The Domain layer doesn’t care if you’re using WhatsApp or a CLI — it just knows about messages and conversations.
Pattern Real-World Analogy What It Does
Clean Architecture A school with separate buildings for classes, admin, and sports Keeps code organized so the AI brain doesn’t need to know about databases Ports & Adapters Universal phone charger that fits any outlet Different services (WhatsApp, Email) plug in without changing the core code Decorator Chain Matryoshka (Russian nesting) dolls Each layer wraps the previous one, adding features like caching or sanitization Dependency Injection LEGO bricks that snap together Easy to swap real services for test versions without rewriting code Event-Driven Waiter who takes your order while the kitchen cooks Background tasks run without making you wait for responses Circuit Breaker Electrical fuse that prevents house fires When a service fails repeatedly, stop trying and use a backup plan Multi-Layer Cache Sticky notes (fast) + notebook (permanent) Frequently used data stays in memory; everything else on disk
Here’s everything PiSovereign can do, explained simply:
Feature What It Does Real-World Analogy Why It’s Cool
Adaptive Model Routing Sends easy questions to small, fast AI; hard questions to bigger AI Express checkout vs. full-service lane at the grocery store 4× faster for simple questionsSemantic Caching Remembers similar questions you asked before, even if worded differently A teacher who remembers “What’s 2+2?” and “Two plus two equals?” are the same question No waiting for repeat questions Multi-Layer Cache Stores answers in fast memory + disk backup Sticky notes on your desk (fast) + a notebook in your drawer (permanent) Under 1ms for cached answers In-Process Event Bus Handles background work (saving memories, logging) without slowing your reply A restaurant where the waiter takes your order while another waiter clears tables 100-500ms saved per message Proactive Pre-Computation Prepares common answers before you ask A friend who checks the weather before your camping trip Instant morning briefings Predictive Pre-Caching Learns your patterns and generates answers before you ask A barista who starts your regular order when you walk in Bayesian prediction, thermal-aware Template Responder Answers trivial questions instantly without using AI Automated phone menu for simple requests Under 10ms for “Hello!” HDC Vector Pre-Filter Uses 10,000-bit binary vectors to speed up memory search A card catalog that narrows down which shelf to check 80% fewer floating-point operations
Feature What It Does Real-World Analogy Why It’s Cool
ReAct Agent (Tool Calling) AI can use 18 tools: check weather, search web, read calendar, send emails An assistant who can look things up instead of just guessing AI acts , not just talks Per-Request Tool Selection Users pick which tools the AI may use per message; tools discovered dynamically from backend Choosing which apps to open before asking Siri Full control without frontend changes when adding new tools Multi-Agent Orchestration Multiple AIs work together on complex tasks A group project where each person handles their specialty Parallel work = faster results RAG Memory System Remembers your preferences, name, and past conversations A personal diary that the AI actually reads “Hey, I remember you like dark mode!” Fact Extraction Automatically pulls important facts from conversations Highlighting key points in a textbook Never forgets important stuff Complexity Classification Figures out how hard a question is before answering A teacher deciding if it’s a pop quiz or a final exam Right-sized AI for every question Affective Computing Detects your emotional state from text and voice, adjusts tone A friend who notices when you’re stressed and speaks gently Frustrated? Patient tone. Curious? Enthusiastic answers Self-Evolving Prompts AI’s own instructions improve over time from your feedback A teacher who rewrites their lesson plan after every class Thompson Sampling + security guardrails Neuroplastic Routing Model selection learns your preferences after 50 chats A DJ who learns what music you like at different times LinUCB bandit, gets better every day Embodied Context Memories are linked to rooms — kitchen questions get kitchen memories Your brain remembering things by where you learned them Method of Loci for AI Dream Mode Autonomous nightly processing that consolidates memories, discovers cross-domain patterns, and generates hypotheses while you sleep Your brain replaying and reorganizing memories during sleep NREM/REM cycles, dream journal, proactive “Did you know?” insights
Feature What It Does Real-World Analogy Why It’s Cool
Prompt Injection Defense Blocks 60+ patterns of attempts to trick the AI A bouncer checking IDs at a club entrance Stops “ignore your instructions” attacks Output Sanitization Hides sensitive info (passwords, credit cards, emails) from responses A TV censor bleeping out swear words PII protection with 17 detection patterns Context Sanitization Cleans external data (web results, tool outputs) before feeding to AI Airport security scanning luggage Blocks hidden malicious instructions Secret Management Stores API keys and passwords in a secure vault A safe with a combination lock Secrets never appear in logs Encryption at Rest Encrypts your memories and conversations on disk A locked diary with a key only you have XChaCha20-Poly1305 encryption Rate Limiting Prevents abuse by limiting requests per minute A “take a number” system at a deli counter Auto-cleanup of old entries HMAC Tool Receipts Signs tool results to detect tampering A wax seal on a medieval letter Cryptographic proof nothing was changed Immune System AI attacks itself daily to find weaknesses, auto-patches them A vaccine — controlled exposure to build immunity Self-healing security, 20 attacks/day ZK Decision Proofs Cryptographic proof that AI followed the rules without revealing how Proving you’re over 18 without showing your birthday Merkle-tree proofs for compliance audits Privacy Budget Visible daily ε-budget for all data operations, auto-degrades when spent A phone data plan — you see usage and it throttles at the limit World’s first user-visible AI privacy budget
Feature What It Does Real-World Analogy Why It’s Cool
Speech-to-Text (STT) Converts voice messages to text A court stenographer Local processing via Whisper Text-to-Speech (TTS) Reads responses aloud An audiobook narrator Piper voices for natural speech Hybrid Provider Falls back to OpenAI if local processing fails Having a backup phone charger 99.9% uptime even when hardware struggles
Feature What It Does Real-World Analogy Why It’s Cool
Snippets Reusable Markdown text blocks with /snippet chat trigger and nested resolution Copy-paste templates, but smarter — they auto-expand Compose complex AI prompts from building blocks @Agent Mentions Type @ in chat to mention specialized AI agents inline Tagging someone in a group chat Route questions to the right expert AI Reminders Natural language reminders in English and German with CalDAV sync A personal assistant who never forgets “Erinnere mich morgen um 10 Uhr” Tasks & Task Lists Full task management with priorities, due dates, and calendar linking A smart to-do list that syncs with your calendar Organize, prioritize, and track progress Morning Briefing Daily summary of weather, calendar, emails, and tasks A personal news anchor for your day One command, full overview
PiSovereign connects to 8 external services. Each one plugs in via the Ports & Adapters pattern, so adding new ones is easy.
Service What You Can Do Example Commands
WhatsApp Send and receive messages via WhatsApp Cloud API “Send Mom: Don’t forget the groceries!” Signal Private encrypted messaging via signal-cli “Message my Signal group: meeting at 5pm” Calendar (CalDAV) View, create, and manage events on any CalDAV server “What’s on my calendar this week?” Contacts (CardDAV) Look up phone numbers and emails “What’s Sarah’s email address?” Email (IMAP/SMTP) Read inbox, search, draft, and send emails “Any new emails from GitHub?” Weather (Open-Meteo) Current conditions and 7-day forecast “Will it rain tomorrow in Berlin?” Web Search (Brave/DDG) Search the internet privately “Search for vegan pasta recipes” Transit (HAFAS) German public transport schedules “Next train from Munich to Hamburg?”
Here’s what happens when you ask “What’s the weather tomorrow?”:
1. 📱 You send message via Web UI / WhatsApp / Signal
│
▼
2. 🚦 Adaptive Model Routing classifies complexity
│ → "weather question" = Simple tier
│
▼
3. 💾 Check Semantic Cache
│ → Similar question asked before? Return cached answer!
│ → No hit? Continue...
│
▼
4. 🧠 ReAct Agent decides to use the weather tool
│ → Calls Open-Meteo API
│ → Sanitizes the result (removes any hidden tricks)
│
▼
5. 🤖 Small AI model (gemma4:e4b) formats the response
│
▼
6. 📤 Output Sanitizer checks for leaked secrets
│
▼
7. 💬 Response sent back to you: "Tomorrow: 18°C, partly cloudy"
│
▼
8. 📝 Event Bus (background): Save to cache, extract facts, log metrics
Total time: ~500ms (vs. 5-8 seconds without optimizations)
PiSovereign is split into 18 Rust crates (think of them as LEGO sets that snap together):
Layer Crate One-Line Description
Domain domainCore rules: what is a message, user, conversation? Application applicationBusiness logic: how do we handle a chat request? AI ai_coreOllama LLM inference and model routing AI ai_speechSpeech-to-text and text-to-speech Infrastructure infrastructureDatabase, cache, secrets, metrics adapters Integration integration_whatsappWhatsApp Cloud API connector Integration integration_signalSignal messenger via signal-cli Integration integration_caldavCalDAV calendar protocol Integration integration_carddavCardDAV contacts protocol Integration integration_emailIMAP/SMTP email Integration integration_weatherOpen-Meteo weather API Integration integration_websearchBrave Search + DuckDuckGo fallback Integration integration_transitGerman public transit (HAFAS) Presentation presentation_httpREST API with Axum web framework Presentation presentation_cliCommand-line interface Presentation presentation_webSolidJS web frontend
Category Technology Why We Use It
Language Rust 2024 Fast, safe, no garbage collector pauses Async Runtime Tokio Handle thousands of requests concurrently Web Framework Axum Type-safe, fast HTTP handling Frontend SolidJS + Tailwind CSS Reactive UI without React’s overhead Database PostgreSQL + pgvector SQL + vector similarity search Cache Moka (memory) + Redb (disk) Multi-layer for speed + persistence LLM Ollama Run AI models locally, no cloud needed Secrets HashiCorp Vault Enterprise-grade secret storage Containers Docker Compose Easy deployment with profiles Observability Prometheus + Grafana + Loki Metrics, dashboards, logs
PiSovereign includes 30 research-backed innovation features that go far beyond any self-hosted AI assistant. Connected through a unified Sovereign Intelligence Engine signal bus, these features work together — thermal state from the energy monitor pauses pre-caching, affective state modulates cognitive load, and the immune system protects evolving prompts.
Feature What It Does Real-World Analogy Why It’s Cool
Ebbinghaus Decay Knowledge Graphs Memories fade naturally using forgetting curves (R = e^(-t/S)), and strengthen with each recall How your brain remembers: study more = remember longer AI memory feels genuinely human-like Differential Privacy Analytics Adds mathematical noise to analytics so individual interactions can’t be identified Blurring faces in a photo — you can see the crowd but not who’s who ε-differential privacy, even for local data Cognitive Load-Adaptive Response Shaping Detects cognitive capacity from 5 signals (circadian rhythm, duration, latency, complexity, multitasking) and shapes responses into bullet points, narrative, or TL;DR-first A friend who reads the room — tired? Bullet points. Curious? Deep dive 3 response formats, auto-selected Digital Sovereignty Score Real-time 0–100 score showing how private your setup actually is A credit score, but for privacy Actionable recommendations to improve
Feature What It Does Real-World Analogy Why It’s Cool
Post-Quantum Cryptography (PQC) Uses ML-KEM-768 + ML-DSA-65 algorithms that resist quantum computer attacks A lock that even a supercomputer from the future can’t pick First self-hosted AI with NIST PQC Adversarial Self-Audit Immune System Daily automated red-team attacks with immediate auto-hardening of prompt defense patterns via hot-reload A vaccine — controlled exposure builds antibodies automatically Self-healing security, 20 attacks/day Homomorphic Semantic Search Searches your memories without ever decrypting them Finding a book in a locked library without opening it Zero-knowledge RAG — world-first Zero-Knowledge Decision Proofs Cryptographic Merkle-tree proofs that AI followed rules — without revealing internal state Proving you’re over 18 without showing your birthday SHA-256 proofs for compliance audits
Feature What It Does Real-World Analogy Why It’s Cool
Neuromorphic Memory Three-store memory like the human brain: episodic (recent), semantic (facts), procedural (habits) Short-term memory → long-term memory → muscle memory AI forms genuine understanding, not just retrieval Causal Reasoning Engine Answers “why” and “what if” questions using Structural Causal Models A detective who follows cause-and-effect chains, not just clues Goes beyond correlational RAG Local Continual Learning (LoRA) AI improves over time from your feedback without data leaving your device A tutor who remembers your learning style Privacy-preserving personalization Bayesian Self-Optimization Automatically tunes system parameters for best performance on your hardware A car that adjusts its own engine settings for the road you’re driving on Hands-free performance tuning Affective Computing Detects emotional state from text + voice prosody, subtly adjusts response tone A friend who notices when you’re stressed and speaks gently 5 emotional states, 7-day memory Self-Evolving Prompt Optimization Prompt variants evolve over time via Thompson Sampling and mutation A writer who drafts 5 versions and keeps the one readers liked most Automatic security guardrails Neuroplastic Model Routing LinUCB contextual bandit learns which AI model works best for you A DJ who quickly learns your music taste for different moods Gets better with every conversation
Feature What It Does Real-World Analogy Why It’s Cool
Multi-Agent Swarm Multiple specialized AIs collaborate on complex tasks (researcher, planner, executor, critic) A team of specialists working together on a project Rust type-system safety guarantees Cross-Modal Reasoning Fusion Searches across chat, email, calendar, and voice simultaneously Asking “who mentioned the deadline?” and getting results from email AND chat Unified embeddings across all modalities Edge Model Distillation Creates custom AI models optimized for your specific hardware and usage patterns Custom-tailored clothing vs. off-the-rack Faster inference, lower power usage Explainable AI with Counterfactuals Shows why AI made each decision, plus what would have happened otherwise “I chose fast model. Slow model: 3× slower, 10% more precise” EU AI Act transparency compliance Predictive Cognitive Pre-Caching Learns your daily patterns and pre-generates answers before you ask A barista who starts your regular order when you walk in Bayesian prediction, thermal-aware Temporal Knowledge Decay Visualization Interactive 3D WebGL knowledge graph showing memory decay in real-time Watching your AI’s thoughts glow and fade like stars Three.js, Ebbinghaus decay formula
Feature What It Does Real-World Analogy Why It’s Cool
Sovereign Mesh Network Trusted PiSovereign instances share compute power — if your AI is busy, a friend’s helps Neighbors sharing a generator during a power outage mDNS discovery, mTLS encryption Federated Sovereign Learning Multiple instances learn together without sharing any raw data Study group where everyone shares notes, but nobody reads each other’s diaries LoRA sync with differential privacy Energy-Aware Inference Scheduling Monitors thermal state and optionally carbon intensity, adjusts AI workload accordingly A smart thermostat for your AI — runs heavy tasks when cool Pi 5 sysfs, RAPL, Docker adapters Quantum-Inspired Approximate Search (HDC) 10,000-bit binary vectors make memory search blazing fast on edge hardware A speed-reader who scans summaries before reading full articles ARM NEON optimized, 80% fewer FLOPs Formal ε-Privacy Budget Visible daily privacy budget — you see how much is consumed and it auto-degrades A data plan for your privacy — shows usage and throttles at the limit World’s first user-visible AI privacy budget Embodied Context Anchoring Memories linked to physical rooms — kitchen questions recall kitchen memories Your brain remembering where you read something Method of Loci for AI, 1.5× RAG boost
📖 For full technical details on all 30 innovation features, see the Innovation Features Developer Guide .
Term Simple Definition
LLM Large Language Model — the AI brain that generates text RAG Retrieval-Augmented Generation — giving the AI context from your memories Embedding Converting text to numbers so computers can measure similarity Inference The process of the AI generating a response Port An interface (contract) that says “I need X capability” Adapter A concrete implementation that fulfills a port’s contract Decorator A wrapper that adds behavior to something without changing it Circuit Breaker Pattern that stops calling a failing service to let it recover Signal Bus A pub/sub message highway connecting all innovation features Contextual Bandit A machine learning algorithm that learns the best action for each situation Thompson Sampling A strategy for choosing between options that balances trying new things vs. using what works Federated Learning Multiple AI instances learning together by sharing model updates, never raw data mDNS Multicast DNS — automatic zero-config device discovery on local networks Merkle Tree A cryptographic data structure that proves data integrity with minimal disclosure HDC Hyperdimensional Computing — brain-inspired computing with very large binary vectors Affective Computing Detecting and responding to human emotions via text, voice, and physiological signals Event Bus A message highway where components publish and subscribe to events STT/TTS Speech-to-Text / Text-to-Speech CalDAV/CardDAV Calendar / Contact protocols (like HTTP for calendars) HAFAS German public transit API standard
Want the full technical details? Check out these pages: