Features at a Glance
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.
How It’s Built (Architecture)
PiSovereign is organized like a well-run school where each department has clear responsibilities and rules about who talks to whom.
The Layer Cake
┌─────────────────────────────────────────────────────────────┐
│ 🖥️ 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.
Architecture Patterns Explained
| 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 |
Feature Quick Reference
Here’s everything PiSovereign can do, explained simply:
⚡ Performance Features
| 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 questions |
| Semantic 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 |
| Template Responder | Answers trivial questions instantly without using AI | Automated phone menu for simple requests | Under 10ms for “Hello!” |
🧠 AI Features
| 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 |
| 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 |
🔒 Security Features
| 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 |
🔊 Speech Features
| 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 |
Integrations (External Services)
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 |
|---|---|---|
| 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?” |
How a Request Flows Through the System
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 (gemma3:1b) 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)
The 18 Crates (Code Modules)
PiSovereign is split into 18 Rust crates (think of them as LEGO sets that snap together):
| Layer | Crate | One-Line Description |
|---|---|---|
| Domain | domain | Core rules: what is a message, user, conversation? |
| Application | application | Business logic: how do we handle a chat request? |
| AI | ai_core | Ollama LLM inference and model routing |
| AI | ai_speech | Speech-to-text and text-to-speech |
| Infrastructure | infrastructure | Database, cache, secrets, metrics adapters |
| Integration | integration_whatsapp | WhatsApp Cloud API connector |
| Integration | integration_signal | Signal messenger via signal-cli |
| Integration | integration_caldav | CalDAV calendar protocol |
| Integration | integration_carddav | CardDAV contacts protocol |
| Integration | integration_email | IMAP/SMTP email |
| Integration | integration_weather | Open-Meteo weather API |
| Integration | integration_websearch | Brave Search + DuckDuckGo fallback |
| Integration | integration_transit | German public transit (HAFAS) |
| Presentation | presentation_http | REST API with Axum web framework |
| Presentation | presentation_cli | Command-line interface |
| Presentation | presentation_web | SolidJS web frontend |
Technology Stack
| 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 |
Glossary
| 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 |
| 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 |
Learn More
Want the full technical details? Check out these pages:
- Architecture Deep Dive — The complete system design
- Tool Calling (ReAct Agent) — How the AI uses tools
- Memory System — RAG and long-term memory
- Model Routing — Complexity-based AI selection
- Security Hardening — All security measures
- API Reference — REST API documentation