PiSovereign Documentation

A self-hosted, privacy-first AI assistant platform — deploy anywhere with Docker Compose.

Welcome to the official PiSovereign documentation. This guide covers everything from first deployment to production operations and development.

Introduction

PiSovereign runs a complete AI assistant stack on your own hardware. All inference stays local via Ollama — no data ever leaves your network. It deploys as a set of Docker containers on any Linux or macOS host and is optimized for the Raspberry Pi 5 with Hailo-10H NPU.

Core Principles:

• Privacy First — All processing happens locally on your hardware
• GDPR Compliant — No data leaves your network
• Open Source — MIT licensed, fully auditable, #![forbid(unsafe_code)]
• Extensible — Clean Architecture with Ports & Adapters

Key Features

Innovation Highlights

PiSovereign includes 15 advanced features grouped into four phases:

For full details, see the Innovation Features documentation.

Quick Links

User Guide

Developer Guide

Operations & Security

Getting Help

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions and share ideas
• Security Issues: Report vulnerabilities privately via GitHub Security Advisories

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

Feature Quick Reference

Here’s everything PiSovereign can do, explained simply:

⚡ Performance Features

🧠 AI Features

🔒 Security Features

🔊 Speech Features

📝 Productivity Features

Integrations (External Services)

PiSovereign connects to 8 external services. Each one plugs in via the Ports & Adapters pattern, so adding new ones is easy.

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 (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)

The 18 Crates (Code Modules)

PiSovereign is split into 18 Rust crates (think of them as LEGO sets that snap together):

Technology Stack

🚀 Innovation Features

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.

Phase 1 — Foundation

Phase 2 — Advanced Security

Phase 3 — AI Core

Phase 4 — Advanced AI

Phase 5 — Decentralized & Edge

📖 For full technical details on all 30 innovation features, see the Innovation Features Developer Guide.

Glossary

Learn More

Want the full technical details? Check out these pages:

• Architecture Deep Dive — The complete system design
• Innovation Features — All 15 research-backed AI, security, and privacy innovations
• 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

Getting Started

Get PiSovereign running in under 5 minutes

PiSovereign is deployed as a set of Docker containers using Docker Compose. This is the only supported installation method.

Prerequisites

• Docker Engine 24+ with Docker Compose v2
• 8 GB RAM recommended (4 GB minimum)
• 20 GB disk space (models + data)
• A domain name with DNS pointing to your server (for HTTPS)

Quick Start

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

# Create your environment file
cp .env.example .env
nano .env  # Set PISOVEREIGN_DOMAIN and TRAEFIK_ACME_EMAIL

# Start all core services
docker compose up -d

# Initialize Vault (first run only — save the output!)
docker compose exec vault /vault/init.sh

# Wait for model download to complete
docker compose logs -f ollama-init

What Gets Deployed

Post-Setup

1. Store secrets in Vault — See Vault Setup
2. Register Signal number — See Signal Setup
3. Configure integrations — See External Services
4. Enable monitoring (optional) — docker compose --profile monitoring up -d

Verify Installation

# Check all services are running
docker compose ps

# Test the health endpoint
curl https://your-domain.example.com/health

# Check individual services
curl https://your-domain.example.com/health/inference
curl https://your-domain.example.com/health/vault

Next Steps

• Docker Setup — Full deployment reference and operations

• Configuration Reference — All available settings

• Docker Setup — Detailed deployment guide

• Configuration Reference — All configuration options

• Troubleshooting — Common issues and solutions

Hardware Setup

Hardware assembly guide for Raspberry Pi 5 with Hailo-10H AI HAT+

This guide covers the physical hardware setup. For software installation, see the Docker Setup guide.

Required Components

Assembly Instructions

Important: Always work on a static-free surface and handle boards by edges only.

Step 1: Prepare the Raspberry Pi

1. Unbox the Raspberry Pi 5
2. Attach the Active Cooler:
   • Remove the protective film from the thermal pad
   • Align with the CPU and press firmly
   • Connect the 4-pin fan connector to the FAN header

Step 2: Install the Hailo AI HAT+

1. Locate the 40-pin GPIO header on the Pi
2. Align the Hailo HAT+ with the GPIO pins
3. Gently press down until fully seated (approximately 3mm gap)
4. Connect the PCIe FPC cable:
   • Open the Pi 5’s PCIe connector latch
   • Insert the flat cable (contacts facing down)
   • Close the latch to secure

Step 3: Install Storage (Optional NVMe)

If using the Hailo HAT+ built-in M.2 slot:

1. Insert NVMe SSD into M.2 slot (M key, 2242/2280)
2. Secure with the provided screw

Step 4: Enclose and Power

1. Place assembly in case
2. Connect Ethernet cable (recommended over WiFi for production)
3. Connect power supply

OS Installation

Flash Raspberry Pi OS

1. Install Raspberry Pi Imager on your computer

2. Choose Device: Raspberry Pi 5

3. Choose OS: Raspberry Pi OS Lite (64-bit)

4. Click Edit Settings:

   • Set hostname: pisovereign
   • Set username and strong password
   • Enable SSH with public-key authentication
   • Set your timezone

5. Flash to SD card / NVMe

First Boot

# SSH into the Pi
ssh pi@pisovereign.local

# Update system
sudo apt update && sudo apt full-upgrade -y

# Install Docker (required for PiSovereign)
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

# Log out and back in for group change
exit

Configure Boot (Optional NVMe)

sudo raspi-config

• Advanced Options → Boot Order → NVMe/USB Boot

Next Steps

Once hardware is assembled and Docker is installed, proceed to the Docker Setup guide for PiSovereign deployment.

Docker Setup

Production deployment guide using Docker Compose

PiSovereign runs as a set of Docker containers orchestrated by Docker Compose. This is the recommended and only supported deployment method.

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• 4 GB+ RAM (8 GB recommended)
• 20 GB+ free disk space

Install Docker if not already installed:

# Raspberry Pi / Debian / Ubuntu
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# Log out and back in

# macOS
brew install --cask docker

Quick Start

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

# 2. Configure environment
cp .env.example .env
# Edit .env with your domain and email for TLS certificates
nano .env

# 3. Start core services
docker compose up -d

# 4. Initialize Vault (first time only)
docker compose exec vault /vault/init.sh
# Save the unseal key and root token printed to stdout!

# 5. Wait for Ollama model download
docker compose logs -f ollama-init

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

Architecture

The deployment consists of these core services:

Monitoring Stack (profile: monitoring)

CalDAV Server (profile: caldav)

Key Endpoints

Configuration

Environment Variables

Edit docker/.env before starting:

# Your domain (required for TLS)
PISOVEREIGN_DOMAIN=pi.example.com

# Email for Let's Encrypt certificates
TRAEFIK_ACME_EMAIL=you@example.com

# Vault root token (set after vault init)
VAULT_TOKEN=hvs.xxxxx

# Container image version
PISOVEREIGN_VERSION=latest

# Email provider preset: gmail, outlook, or custom
EMAIL_PROVIDER=gmail

Note: On first startup, PiSovereign automatically populates 32 default system commands and validates Vault credentials, logging warnings for any missing or invalid secrets. Check the container logs after first startup to verify all integrations are configured correctly.

Application Config

The main application config is at docker/config/config.toml. All service hostnames use Docker network names (e.g., ollama:11434).

See Configuration Reference for all options.

Storing Secrets in Vault

After Vault initialization, store your integration secrets:

# Enter Vault container
docker compose exec vault sh

# Store WhatsApp credentials
vault kv put secret/pisovereign/whatsapp \
  access_token="your-meta-token" \
  app_secret="your-app-secret"

# Store Brave Search API key
vault kv put secret/pisovereign/websearch \
  api_key="your-brave-api-key"

# Store CalDAV credentials
vault kv put secret/pisovereign/caldav \
  password="your-caldav-password"

# Store email credentials (IMAP/SMTP)
vault kv put secret/pisovereign/email \
  password="your-email-password"

Docker Compose Profiles

Additional services are available via profiles (see tables above for URLs):

Monitoring Stack

docker compose --profile monitoring up -d

CalDAV Server

docker compose --profile caldav up -d

All Profiles

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

Signal Registration (Docker)

Signal requires a one-time registration before messages can be sent/received.

1. Set your phone number

Edit docker/.env and set your phone number in E.164 format:

SIGNAL_CLI_NUMBER=+491701234567

This automatically configures both the PiSovereign application and can be stored in Vault for secure persistence.

2. Register with Signal

# Register via SMS
docker compose exec signal-cli signal-cli -a +491701234567 register

# Or register via voice call
docker compose exec signal-cli signal-cli -a +491701234567 register --voice

3. Verify the code

# Enter the verification code received via SMS/voice
docker compose exec signal-cli signal-cli -a +491701234567 verify 123-456

4. Store in Vault (optional)

For production, store the phone number in Vault so it’s managed centrally:

docker compose exec vault vault kv put secret/pisovereign/signal \
  phone_number="+491701234567"

The application loads the phone number in this priority order:

1. config.toml — [signal] phone_number = "..."
2. Environment variable — PISOVEREIGN_SIGNAL__PHONE_NUMBER (set via .env)
3. Vault — secret/pisovereign/signal → phone_number

5. Restart and verify

docker compose restart pisovereign
docker compose logs pisovereign | grep -i signal

For the full Signal setup guide, see Signal Setup.

Operations

Updating

cd docker

# Pull latest images
docker compose pull

# Recreate containers with new images
docker compose up -d

Vault Management

# Check Vault status
docker compose exec vault vault status

# Unseal after restart (use key from init)
docker compose exec vault vault operator unseal <UNSEAL_KEY>

# Read a secret
docker compose exec vault vault kv get secret/pisovereign/whatsapp

Logs

# Follow all logs
docker compose logs -f

# Specific service
docker compose logs -f pisovereign

# Last 100 lines
docker compose logs --tail=100 pisovereign

Backup

Database Backup (recommended)

Create a timestamped SQL dump of the PostgreSQL database without stopping any services:

# Create a backup
just db-backup
# → sql/pisovereign_20260331_120000.sql

# List available backups
just db-backups

# Restore from a backup (⚠️ overwrites current database)
just db-restore sql/pisovereign_20260331_120000.sql

Backups are stored in the sql/ directory at the project root. This directory is git-ignored so backups stay local and are never committed.

Volume Backup (full)

For a complete backup including all Docker volumes:

# Stop services
docker compose down

# Backup volumes
docker run --rm -v pisovereign-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/pisovereign-backup-$(date +%Y%m%d).tar.gz /data

# Restart
docker compose up -d

Troubleshooting

See the Troubleshooting guide for common issues.

GPU Acceleration

By default, Ollama runs CPU-only inside Docker. For GPU-accelerated inference:

• macOS (Metal): Run Ollama natively and set OLLAMA_BASE_URL in .env
• Linux (NVIDIA): Use docker compose -f compose.yml -f compose.gpu-nvidia.yml up -d
• Linux (AMD/ROCm): Create a compose.override.yml with the ROCm image

See the full GPU Acceleration guide for setup instructions.

GPU Acceleration

Run Ollama with GPU acceleration for faster LLM inference

By default, PiSovereign runs Ollama inside a Docker container using CPU-only inference. With GPU acceleration, inference speed improves dramatically — especially for larger models like qwen2.5:14b or qwen2.5:32b.

Platform Overview

macOS — Native Ollama with Metal GPU

Docker Desktop on macOS runs containers inside a Linux VM and cannot pass through the Metal GPU. To use GPU acceleration, run Ollama natively on the host and point PiSovereign’s Docker container at it.

1. Install Ollama

brew install ollama

2. Start Ollama

ollama serve

Ollama will listen on http://localhost:11434 and automatically use Metal for GPU-accelerated inference on Apple Silicon (M1/M2/M3/M4) or Intel Macs.

3. Pull the inference model

# Default model (recommended for 16 GB+ RAM)
ollama pull qwen2.5:14b

# Embedding model (required)
ollama pull nomic-embed-text

4. Configure Docker environment

Edit docker/.env and set:

OLLAMA_BASE_URL=http://host.docker.internal:11434

This tells the PiSovereign container to connect to the native Ollama instance via Docker’s host.docker.internal bridge (already configured in compose.yml via extra_hosts).

5. Start PiSovereign

# From the repository root
just docker-up

# Or directly
cd docker && docker compose up -d

Note: The Ollama Docker container will still start but is unused. It runs idle with minimal resource consumption. The PiSovereign container connects to native Ollama via the configured OLLAMA_BASE_URL.

Verify GPU is active

# Check Ollama is using Metal
ollama ps
# Should show "metal" in the processor column

# Test inference
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:14b",
  "prompt": "Hello",
  "stream": false
}'

Linux — NVIDIA GPU

On Linux with an NVIDIA GPU, Ollama runs inside Docker with full GPU passthrough via the NVIDIA Container Toolkit.

1. Install NVIDIA Container Toolkit

# Add the NVIDIA repository
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Configure Docker runtime
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

2. Verify GPU is visible to Docker

docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

This should display your GPU model, driver version, and CUDA version.

3. Start with GPU override

# From the repository root
just docker-up-gpu

# Or directly
cd docker && docker compose -f compose.yml -f compose.gpu-nvidia.yml up -d

This merges compose.gpu-nvidia.yml into the Ollama service, adding NVIDIA GPU device reservations and higher resource limits. The same ollama service is used — only the resource configuration is overridden.

4. Verify GPU inference

# Check GPU layers are loaded
docker compose -f compose.yml -f compose.gpu-nvidia.yml exec ollama ollama ps
# Should show GPU layers in the "processor" column

# Check NVIDIA GPU usage
docker compose -f compose.yml -f compose.gpu-nvidia.yml exec ollama nvidia-smi

GPU Resource Limits

The GPU override file (compose.gpu-nvidia.yml) configures higher resource limits than CPU-only:

Adjust these in docker/compose.gpu-nvidia.yml to match your hardware.

Linux — AMD GPU (ROCm)

AMD GPU support requires the ROCm-specific Ollama image and device mappings. This is not provided as a built-in profile due to the different base image, but can be configured manually:

1. Install ROCm drivers

Follow the AMD ROCm installation guide.

2. Create a compose override

Create docker/compose.override.yml:

services:
  ollama:
    image: ollama/ollama:rocm
    devices:
      - /dev/kfd:/dev/kfd
      - /dev/dri:/dev/dri
    group_add:
      - video
      - render
    deploy:
      resources:
        limits:
          memory: 24G
          cpus: "8.0"
    environment:
      - OLLAMA_NUM_PARALLEL=2
      - OLLAMA_MAX_LOADED_MODELS=3
      - OLLAMA_FLASH_ATTENTION=1

3. Start services

cd docker && docker compose up -d

Docker Compose automatically merges compose.yml with compose.override.yml.

Model Configuration

The inference model is configurable via the OLLAMA_MODEL environment variable in docker/.env. The ollama-init container pulls this model on first start.

Recommended models by VRAM / RAM

To change the model:

# Edit docker/.env
OLLAMA_MODEL=qwen2.5:32b

# Restart ollama-init to pull the new model
cd docker && docker compose restart ollama-init

# Or pull manually
just docker-model-pull qwen2.5:32b

The embedding model (nomic-embed-text) is always pulled regardless of the OLLAMA_MODEL setting.

Troubleshooting

macOS: Ollama not reachable from Docker

# Verify Ollama is running
curl http://localhost:11434/api/tags

# Verify Docker can reach the host
docker run --rm --add-host=host.docker.internal:host-gateway \
  curlimages/curl curl -s http://host.docker.internal:11434/api/tags

# Check .env is correct
grep OLLAMA_BASE_URL docker/.env
# Should show: OLLAMA_BASE_URL=http://host.docker.internal:11434

NVIDIA: GPU not visible in container

# Check NVIDIA driver is loaded
nvidia-smi

# Check Container Toolkit is installed
nvidia-ctk --version

# Check Docker runtime
docker info | grep -i nvidia

# Test GPU access
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

Model download fails

# Check ollama-init logs
docker compose logs ollama-init

# Pull manually
docker compose exec ollama ollama pull qwen2.5:14b

# Or via Justfile
just docker-model-pull qwen2.5:14b

Performance is slow despite GPU

# Verify GPU layers are being used
ollama ps
# The "processor" column should show "gpu" or "metal", not "cpu"

# Check if model fits in VRAM — if it spills to RAM, inference slows down
# Reduce model size if VRAM is insufficient

HashiCorp Vault Setup

Secure secret management for PiSovereign using HashiCorp Vault

Vault is included in the Docker Compose stack and initialized automatically on first run. This guide covers how secrets are structured, how to store them, and how Vault integrates with PiSovereign.

Overview

HashiCorp Vault provides centralized secret management with encryption at rest and in transit, fine-grained access control, audit logging, and secret rotation. PiSovereign’s Docker Compose setup includes Vault with automatic initialization via the vault-init sidecar container.

How It Works

┌─────────────────────────────────────────────────────┐
│                    PiSovereign                       │
│  ┌─────────────────────────────────────────────┐   │
│  │           ChainedSecretStore                 │   │
│  │  ┌─────────────┐    ┌──────────────────┐   │   │
│  │  │ VaultSecret │ →  │ EnvironmentSecret │   │   │
│  │  │   Store     │    │     Store         │   │   │
│  │  └─────────────┘    └──────────────────┘   │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────┐
│                 HashiCorp Vault                      │
│  ┌──────────────┐  ┌─────────────┐  ┌───────────┐ │
│  │ KV v2 Engine │  │   AppRole   │  │  Audit    │ │
│  │              │  │    Auth     │  │   Log     │ │
│  └──────────────┘  └─────────────┘  └───────────┘ │
└─────────────────────────────────────────────────────┘

PiSovereign uses a ChainedSecretStore that tries multiple backends in order:

1. Vault (primary) — Production secrets stored securely
2. Environment variables (fallback) — Overrides for development or CI

Initialization

Vault is initialized on first deployment via the Docker Compose init container. Run manually if needed:

cd docker
docker compose exec vault /vault/init.sh

Important: Save the unseal key and root token printed to stdout. Loss of the unseal key means loss of access to secrets.

After a container restart, Vault may need to be unsealed:

docker compose exec vault vault operator unseal <UNSEAL_KEY>

Storing Secrets

Store integration credentials in Vault after initialization:

# Enter the Vault container
docker compose exec vault sh

# WhatsApp credentials
vault kv put secret/pisovereign/whatsapp \
    access_token="your-meta-access-token" \
    app_secret="your-app-secret"

# Email credentials (IMAP/SMTP password or Bridge password)
vault kv put secret/pisovereign/email \
    password="your-email-password"

# CalDAV credentials
vault kv put secret/pisovereign/caldav \
    username="your-username" \
    password="your-password"

# OpenAI API key (for speech fallback)
vault kv put secret/pisovereign/openai \
    api_key="sk-your-openai-key"

# Brave Search API key
vault kv put secret/pisovereign/websearch \
    brave_api_key="BSA-your-key"

# Signal phone number
vault kv put secret/pisovereign/signal \
    phone_number="+491701234567"

# Verify a secret
vault kv get secret/pisovereign/whatsapp

Secret Paths

PiSovereign expects secrets at these paths:

AppRole Authentication

For production, use AppRole instead of the root token. AppRole provides short-lived tokens with scoped permissions.

Create Policy

docker compose exec vault sh

vault policy write pisovereign - <<EOF
path "secret/data/pisovereign/*" {
  capabilities = ["read"]
}
path "secret/metadata/pisovereign/*" {
  capabilities = ["list"]
}
path "auth/token/renew-self" {
  capabilities = ["update"]
}
EOF

Configure AppRole

vault auth enable approle

vault write auth/approle/role/pisovereign \
    token_policies="pisovereign" \
    token_ttl=1h \
    token_max_ttl=4h \
    secret_id_ttl=720h \
    secret_id_num_uses=0

# Get Role ID
vault read auth/approle/role/pisovereign/role-id

# Generate Secret ID
vault write -f auth/approle/role/pisovereign/secret-id

Then configure PiSovereign to use AppRole in config.toml:

[vault]
address = "http://vault:8200"
role_id = "12345678-1234-1234-1234-123456789012"
secret_id = "abcd1234-abcd-1234-abcd-abcd12345678"
mount_path = "secret"
timeout_secs = 5

Tip: Store secret_id as an environment variable rather than in the config file:

export PISOVEREIGN_VAULT_SECRET_ID="abcd1234-..."

Operations

Secret Rotation

Update a secret without downtime — PiSovereign reads the latest version automatically:

vault kv put secret/pisovereign/whatsapp \
    access_token="new-access-token" \
    app_secret="same-app-secret"

View secret versions or rollback:

vault kv metadata get secret/pisovereign/whatsapp
vault kv rollback -version=2 secret/pisovereign/whatsapp

Backup

# Backup Vault data volume
docker run --rm -v docker_vault-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/vault-backup-$(date +%Y%m%d).tar.gz /data

For disaster recovery, ensure you have the unseal key and root token stored securely in a separate location.

Troubleshooting

Cannot connect to Vault

docker compose exec vault vault status
docker compose logs vault

Permission denied

# Verify the token has the correct policy
docker compose exec vault vault token lookup
docker compose exec vault vault policy read pisovereign

Secret not found

# Verify the secret exists
docker compose exec vault vault kv get secret/pisovereign/whatsapp

# Check the mount path
docker compose exec vault vault secrets list

Vault sealed after restart

docker compose exec vault vault operator unseal <UNSEAL_KEY>

Next Steps

• Configuration Reference — All PiSovereign options
• Security Hardening — Vault security best practices
• Docker Setup — Full deployment reference

Configuration Reference

⚙️ Complete reference for all PiSovereign configuration options

This document covers every configuration option available in config.toml.

Table of Contents

• Overview
• Environment Settings
• Server Settings
• Inference Engine
• Security Settings
  • Prompt Security
  • API Key Authentication
• Memory & Knowledge Storage
• Database & Cache
  • Database
  • Cache
• Integrations
  • Messenger Selection
  • WhatsApp Business
  • Signal Messenger
  • Speech Processing
  • Voice-First Interface
  • Weather
  • Web Search
  • Public Transit (ÖPNV)
  • Reminder System
  • CalDAV Calendar
  • Email (IMAP/SMTP)
• Model Selector
• Telemetry
• Resilience
  • Degraded Mode
  • Retry Configuration
• Health Checks
• Event Bus
• Agentic Mode
• Vault Integration
• Environment Variables
• Example Configurations

Overview

PiSovereign uses a layered configuration system:

1. Default values - Built into the application
2. Configuration file - config.toml in the working directory
3. Environment variables - Override config file values (prefix: PISOVEREIGN_)

Configuration File Location

The application loads config.toml from the current working directory:

# Default location (relative to working directory)
./config.toml

Environment Variable Mapping

Config values can be overridden using environment variables:

[server]
port = 3000

# Becomes:
PISOVEREIGN_SERVER_PORT=3000

Nested values use double underscores:

[speech.local_stt]
threads = 4

# Becomes:
PISOVEREIGN_SPEECH_LOCAL_STT__THREADS=4

Environment Settings

# Application environment: "development" or "production"
# In production:
#   - JSON logging is enforced
#   - Security warnings block startup (unless PISOVEREIGN_ALLOW_INSECURE_CONFIG=true)
#   - TLS verification is enforced
environment = "development"

Server Settings

[server]
# Network interface to bind to
# "127.0.0.1" = localhost only (recommended for security)
# "0.0.0.0" = all interfaces (use behind reverse proxy)
host = "127.0.0.1"

# HTTP port
port = 3000

# Enable CORS (Cross-Origin Resource Sharing)
cors_enabled = true

# Allowed CORS origins
# Empty array = allow all (WARNING in production)
# Example: ["https://app.example.com", "https://admin.example.com"]
allowed_origins = []

# Graceful shutdown timeout (seconds)
# Time to wait for active requests to complete
shutdown_timeout_secs = 30

# Log format: "json" or "text"
# In production mode, defaults to "json" even if set to "text"
log_format = "text"

# Secure session cookies (requires HTTPS)
# Set to false for local HTTP development
secure_cookies = false

# Maximum request body size for JSON payloads (optional, bytes)
# max_body_size_json_bytes = 1048576  # 1MB

# Maximum request body size for audio uploads (optional, bytes)
# max_body_size_audio_bytes = 10485760  # 10MB

Inference Engine

[inference]
# Ollama-compatible server URL
# Works with both hailo-ollama (Raspberry Pi) and standard Ollama (macOS)
base_url = "http://localhost:11434"

# Default model for inference
default_model = "qwen2.5:1.5b"

# Request timeout (milliseconds)
timeout_ms = 60000

# Maximum tokens to generate (unset = no limit, model decides)
# max_tokens = 4096

# Sampling temperature (0.0 = deterministic, 2.0 = creative)
temperature = 0.7

# Top-p (nucleus) sampling (0.0-1.0)
top_p = 0.9

# System prompt (optional)
# system_prompt = "You are a helpful AI assistant."

Security Settings

[security]
# Whitelisted phone numbers for WhatsApp
# Empty = allow all, Example: ["+491234567890", "+491234567891"]
whitelisted_phones = []

# API Keys (hashed with Argon2id)
# Generate hashed keys using: pisovereign-cli hash-api-key <your-key>
# Migrate existing plaintext keys: pisovereign-cli migrate-keys --input config.toml --dry-run
#
# [[security.api_keys]]
# hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
# user_id = "550e8400-e29b-41d4-a716-446655440000"
#
# [[security.api_keys]]
# hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
# user_id = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"

# Trusted reverse proxies (IP addresses) - optional
# Add your proxy IPs here if behind a reverse proxy
# trusted_proxies = ["127.0.0.1", "::1"]

# Rate limiting
rate_limit_enabled = true
rate_limit_rpm = 120  # Requests per minute per IP

# TLS settings for outbound connections
tls_verify_certs = true
connection_timeout_secs = 30
min_tls_version = "1.2"  # "1.2" or "1.3"

Prompt Security

Protects against prompt injection and other AI security threats.

[prompt_security]
# Enable prompt security analysis
enabled = true

# Sensitivity level: "low", "medium", or "high"
# - low: Only block high-confidence threats
# - medium: Block medium and high confidence threats (recommended)
# - high: Block all detected threats including low confidence
sensitivity = "medium"

# Block requests when security threats are detected
block_on_detection = true

# Maximum violations before auto-blocking an IP
max_violations_before_block = 3

# Time window for counting violations (seconds)
violation_window_secs = 3600  # 1 hour

# How long to block an IP after exceeding max violations (seconds)
block_duration_secs = 86400  # 24 hours

# Immediately block IPs that send critical-level threats
auto_block_on_critical = true

# Custom patterns to detect (in addition to built-in patterns) - optional
# custom_patterns = ["DROP TABLE", "eval("]

API Key Authentication

API keys are now securely hashed using Argon2id. Use the CLI tools to generate and migrate keys.

Generate a new hashed key:

pisovereign-cli hash-api-key <your-api-key>

Migrate existing plaintext keys:

pisovereign-cli migrate-keys --input config.toml --dry-run
pisovereign-cli migrate-keys --input config.toml --output config-new.toml

Configuration:

[[security.api_keys]]
hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
user_id = "550e8400-e29b-41d4-a716-446655440000"

Usage:

curl -H "Authorization: Bearer <your-api-key>" http://localhost:3000/v1/chat

Memory & Knowledge Storage

Persistent AI memory for RAG-based context retrieval. Stores interactions, facts, preferences, and corrections using embeddings for semantic similarity search.

[memory]
# Enable memory storage (default: true)
# enabled = true

# Enable RAG context retrieval (default: true)
# enable_rag = true

# Enable automatic learning from interactions (default: true)
# enable_learning = true

# Number of memories to retrieve for RAG context (default: 5)
# rag_limit = 5

# Minimum similarity threshold for RAG retrieval (0.0-1.0, default: 0.5)
# rag_threshold = 0.5

# Similarity threshold for memory deduplication (0.0-1.0, default: 0.85)
# merge_threshold = 0.85

# Minimum importance score to keep memories (default: 0.1)
# min_importance = 0.1

# Decay factor for memory importance over time (default: 0.95)
# decay_factor = 0.95

# Enable content encryption (default: true)
# enable_encryption = true

# Path to encryption key file (generated if not exists)
# encryption_key_path = "memory_encryption.key"

[memory.embedding]
# Embedding model name (default: nomic-embed-text)
# model = "nomic-embed-text"

# Embedding dimension (default: 384 for nomic-embed-text)
# dimension = 384

# Request timeout in milliseconds (default: 30000)
# timeout_ms = 30000

Embedding Settings:

Database & Cache

Database

[database]
# SQLite database file path
path = "pisovereign.db"

# Connection pool size
max_connections = 5

# Auto-run migrations on startup
run_migrations = true

Cache

PiSovereign uses a 3-layer caching architecture:

1. L1 (Moka) - In-memory cache for fastest access
2. L2 (Redb) - Persistent disk cache for exact-match lookups
3. L3 (Semantic) - pgvector-based similarity cache for semantically equivalent queries

[cache]
# Enable caching (disable for debugging)
enabled = true

# TTL values (seconds)
ttl_short_secs = 300       # 5 minutes - frequently changing
ttl_medium_secs = 3600     # 1 hour - moderately stable
ttl_long_secs = 86400      # 24 hours - stable data

# LLM response caching
ttl_llm_dynamic_secs = 3600   # Dynamic content (briefings)
ttl_llm_stable_secs = 86400   # Stable content (help text)

# L1 (in-memory) cache size
l1_max_entries = 10000

Semantic Cache

The semantic cache provides an additional layer that matches queries based on embedding similarity rather than exact string matching. This enables cache hits for semantically equivalent queries like:

• “What’s the weather?” ≈ “How’s the weather today?”
• “Tell me about the capital of France” ≈ “What is Paris?”

[cache.semantic]
# Enable semantic caching
enabled = true

# Minimum cosine similarity for cache hit (0.0-1.0)
# Higher = stricter matching, lower = more cache hits
similarity_threshold = 0.92

# TTL for cached entries (hours)
ttl_hours = 48

# Maximum cached entries
max_entries = 10000

# Patterns that bypass semantic cache (time-sensitive queries)
bypass_patterns = ["weather", "time", "date", "today", "tomorrow", "now", "latest", "current", "recent"]

# How often to evict expired entries (minutes)
eviction_interval_minutes = 60

Integrations

Messenger Selection

PiSovereign supports one messenger at a time:

# Choose one: "whatsapp", "signal", or "none"
messenger = "whatsapp"

WhatsApp Business

[whatsapp]
# Meta Graph API access token (store in Vault)
# access_token = "your-access-token"

# Phone number ID from WhatsApp Business
# phone_number_id = "your-phone-number-id"

# App secret for webhook signature verification
# app_secret = "your-app-secret"

# Verify token for webhook setup
# verify_token = "your-verify-token"

# Require webhook signature verification
signature_required = true

# Meta Graph API version
api_version = "v18.0"

# Phone numbers allowed to send messages (empty = allow all)
# whitelist = ["+1234567890"]

# Conversation Persistence Settings
[whatsapp.persistence]
# Enable conversation persistence (default: true)
# enabled = true

# Enable encryption for stored messages (default: true)
# enable_encryption = true

# Enable RAG context retrieval from memory system (default: true)
# enable_rag = true

# Enable automatic learning from interactions (default: true)
# enable_learning = true

# Maximum days to retain conversations (optional, unlimited if not set)
# retention_days = 90

# Maximum messages per conversation before FIFO truncation (optional)
# max_messages_per_conversation = 1000

# Number of recent messages to use as context (default: 50)
# context_window = 50

Persistence Options:

Signal Messenger

[signal]
# Your phone number registered with Signal (E.164 format)
phone_number = "+1234567890"

# Path to signal-cli JSON-RPC socket
socket_path = "/var/run/signal-cli/socket"

# Path to signal-cli data directory (optional)
# data_path = "/var/lib/signal-cli"

# Connection timeout in milliseconds
timeout_ms = 30000

# Phone numbers allowed to send messages (empty = allow all)
# whitelist = ["+1234567890", "+0987654321"]

# Conversation Persistence Settings
[signal.persistence]
# Enable conversation persistence (default: true)
# enabled = true

# Enable encryption for stored messages (default: true)
# enable_encryption = true

# Enable RAG context retrieval from memory system (default: true)
# enable_rag = true

# Enable automatic learning from interactions (default: true)
# enable_learning = true

# Maximum days to retain conversations (optional, unlimited if not set)
# retention_days = 90

# Maximum messages per conversation before FIFO truncation (optional)
# max_messages_per_conversation = 1000

# Number of recent messages to use as context (default: 50)
# context_window = 50

Persistence Options:

📖 See Signal Setup Guide for installation instructions.

Speech Processing

Voice message support for speech-to-text (STT) and text-to-speech (TTS).

Cloud Provider (OpenAI):

• Works on all platforms
• Requires API key

Local Provider (whisper.cpp + Piper):

• Raspberry Pi: Models in /usr/local/share/{whisper,piper}/
• macOS: Models in ~/Library/Application Support/{whisper,piper}/
• Install whisper.cpp: brew install whisper-cpp (Mac) or build from source (Pi)
• Install Piper: Download from https://github.com/rhasspy/piper/releases

[speech]
# Speech provider: "openai" (cloud) or "local" (whisper.cpp + Piper)
# provider = "openai"

# OpenAI API key for Whisper (STT) and TTS
# openai_api_key = "sk-..."

# OpenAI API base URL (for custom endpoints)
# openai_base_url = "https://api.openai.com/v1"

# Speech-to-text model (OpenAI Whisper)
# stt_model = "whisper-1"

# Text-to-speech model
# tts_model = "tts-1"

# Default TTS voice: alloy, echo, fable, onyx, nova, shimmer
# default_voice = "nova"

# Output audio format: opus, ogg, mp3, wav
# output_format = "opus"

# Request timeout in milliseconds
# timeout_ms = 60000

# Maximum audio duration in milliseconds (25 min for Whisper)
# max_audio_duration_ms = 1500000

# Response format preference: mirror, text, voice
# response_format = "mirror"

# TTS speaking speed (0.25 to 4.0)
# speed = 1.0

Voice-First Interface

Multi-room voice interaction with wake word detection, speaker identification, and MQTT audio streaming. Requires the voice Docker Compose profile. See the Voice-First Interface developer guide for architecture details.

[voice]
# Enable the voice-first interface
# enabled = false

[voice.mqtt]
# broker_url = "mqtt://mosquitto:1883"    # MQTT broker URL
# client_id = "pisovereign-voice"          # MQTT client identifier
# keep_alive_secs = 30                     # Keep-alive interval
# max_inflight = 100                       # Max inflight messages
# topic_prefix = "pisovereign"             # MQTT topic prefix

[voice.wake_word]
# service_url = "http://openwakeword:8083" # openWakeWord service URL
# words = ["sovereign"]                    # Wake words to listen for
# sensitivity = 0.5                        # Detection sensitivity (0.0–1.0)
# timeout_ms = 2000                        # Detection request timeout

[voice.speaker_id]
# service_url = "http://speaker-id:8084"   # Speaker-ID service URL
# min_enrollment_samples = 3               # Samples needed for enrollment
# match_threshold = 0.75                   # Cosine similarity threshold
# timeout_ms = 5000                        # Identification request timeout

[voice.conversation]
# follow_up_window_ms = 10000              # Follow-up listening window (10s)
# max_session_duration_ms = 300000         # Max session duration (5 min)

[voice.whisper_mode]
# enabled = true                           # Enable quiet-hours mode
# quiet_start = "22:00"                    # Quiet hours start
# quiet_end = "07:00"                      # Quiet hours end
# quiet_volume = 30                        # Volume during quiet hours (0–100)

[voice.gpio]
# enabled = false                          # GPIO control (RPi only)
# privacy_led_pin = 17                     # BCM pin for privacy LED

[voice.rooms]
# default_volume = 80                      # Default room volume (0–100)
# heartbeat_timeout_ms = 30000             # Offline threshold (30s)

Weather

[weather]
# Open-Meteo API (free, no key required)
# base_url = "https://api.open-meteo.com/v1"

# Connection timeout in seconds
# timeout_secs = 30

# Number of forecast days (1-16)
# forecast_days = 7

# Cache TTL in minutes
# cache_ttl_minutes = 30

# Default location (when user has no profile)
# default_location = { latitude = 52.52, longitude = 13.405 }  # Berlin

CalDAV Calendar

[caldav]
# CalDAV server URL (Baïkal, Radicale, Nextcloud)
# server_url = "https://cal.example.com"
# When using Baïkal via Docker (setup --baikal):
# server_url = "http://baikal:80/dav.php"

# Authentication (store in Vault)
# username = "your-username"
# password = "your-password"

# Default calendar path (optional)
# calendar_path = "/calendars/user/default"

# TLS verification
# verify_certs = true

# Connection timeout in seconds
# timeout_secs = 30

Email (IMAP/SMTP)

PiSovereign supports any email provider that offers IMAP/SMTP access, including Gmail, Outlook, and custom servers. Authentication is supported via password or OAuth2 (XOAUTH2).

Quick setup with provider presets:

The easiest way to configure email is using the provider field, which automatically sets sensible defaults for IMAP/SMTP hosts and ports:

[email]
provider = "gmail"    # or "custom"
email = "user@gmail.com"
password = "app-password"

Available providers:

Explicit imap_host, imap_port, smtp_host, smtp_port values always override provider presets.

Full configuration:

[email]
# Provider preset: "gmail" (default) or "custom"
# provider = "gmail"

# IMAP server host (overrides provider preset)
# imap_host = "imap.gmail.com"       # Gmail
# imap_host = "outlook.office365.com" # Outlook

# IMAP server port (993 for TLS)
# imap_port = 993

# SMTP server host
# smtp_host = "smtp.gmail.com"       # Gmail
# smtp_host = "smtp.office365.com"   # Outlook

# SMTP server port (465 for TLS, 587 for STARTTLS)
# smtp_port = 465

# Email address
# email = "user@gmail.com"

# Authentication: password or OAuth2
# For password-based auth (app passwords, Bridge passwords):
# password = "app-password"

# For OAuth2 (Gmail, Outlook):
# [email.auth]
# type = "oauth2"
# access_token = "ya29.your-token"

# TLS configuration
[email.tls]
# Verify TLS certificates
# verify_certificates = true

# Minimum TLS version
# min_tls_version = "1.2"

# Custom CA certificate path (optional)
# ca_cert_path = "/path/to/ca.pem"

Provider-specific examples:

[email]
provider = "gmail"
email = "user@gmail.com"
# Use an App Password (not your Google account password)
# Generate at: https://myaccount.google.com/apppasswords
password = "xxxx xxxx xxxx xxxx"

[email]
provider = "custom"
imap_host = "outlook.office365.com"
imap_port = 993
smtp_host = "smtp.office365.com"
smtp_port = 587
email = "user@outlook.com"
password = "your-app-password"

Web Search

[websearch]
# Brave Search API key (required for primary provider)
# Get your key at: https://brave.com/search/api/
# api_key = "BSA-your-brave-api-key"

# Maximum results per search query (default: 5)
max_results = 5

# Request timeout in seconds (default: 30)
timeout_secs = 30

# Enable DuckDuckGo fallback if Brave fails (default: true)
fallback_enabled = true

# Safe search: "off", "moderate", "strict" (default: "moderate")
safe_search = "moderate"

# Country code for localized results (e.g., "US", "DE", "GB")
country = "DE"

# Language code for results (e.g., "en", "de", "fr")
language = "de"

# Rate limit: requests per minute (default: 60)
rate_limit_rpm = 60

# Cache TTL in minutes (default: 30)
cache_ttl_minutes = 30

Security Note: Store the Brave API key in Vault rather than config.toml:

vault kv put secret/pisovereign/websearch brave_api_key="BSA-..."

Public Transit (ÖPNV)

Provides public transit routing for German transport networks via transport.rest API. Used for “How do I get to X?” queries and location-based reminders.

[transit]
# Base URL for transport.rest API (default: v6.db.transport.rest)
# base_url = "https://v6.db.transport.rest"

# Request timeout in seconds
# timeout_secs = 10

# Maximum number of journey results
# max_results = 3

# Cache TTL in minutes
# cache_ttl_minutes = 5

# Include transit info in location-based reminders
# include_in_reminders = true

# Transport modes to include:
# products_bus = true
# products_suburban = true  # S-Bahn
# products_subway = true    # U-Bahn
# products_tram = true
# products_regional = true  # RB/RE
# products_national = false # ICE/IC

# User's home location for route calculations
# home_location = { latitude = 52.52, longitude = 13.405 }  # Berlin

Reminder System

Configures the proactive reminder system including CalDAV sync, custom reminders, and scheduling settings.

[reminder]
# Maximum number of snoozes per reminder
# max_snooze = 5

# Default snooze duration in minutes
# default_snooze_minutes = 15

# How far in advance to create reminders from CalDAV events (minutes)
# caldav_reminder_lead_time_minutes = 30

# Interval for checking due reminders (seconds)
# check_interval_secs = 60

# CalDAV sync interval (minutes)
# caldav_sync_interval_minutes = 15

# Morning briefing time (HH:MM format)
# morning_briefing_time = "07:00"

# Enable morning briefing
# morning_briefing_enabled = true

Model Selector (Deprecated)

Deprecated since v0.6.0: Use [model_routing] instead. See Adaptive Model Routing.

The old [model_selector] section with small_model / large_model is still accepted but will be removed in a future release.

Adaptive Model Routing

Routes requests to different LLM models based on complexity. See the dedicated Adaptive Model Routing page for full documentation.

[model_routing]
enabled = true

[model_routing.models]
trivial = "template"
simple = "gemma4:e4b"
moderate = "gemma4:26b"
complex = "gemma4:31b"

Telemetry

[telemetry]
# Enable OpenTelemetry export
enabled = false

# OTLP endpoint (Tempo, Jaeger)
# otlp_endpoint = "http://localhost:4317"

# Sampling ratio (0.0-1.0, 1.0 = all traces)
# sample_ratio = 1.0

# Service name for traces
# service_name = "pisovereign"

# Log level filter (e.g., "info", "debug", "pisovereign=debug,tower_http=info")
# log_filter = "pisovereign=info,tower_http=info"

# Batch export timeout in seconds
# export_timeout_secs = 30

# Maximum batch size for trace export
# max_batch_size = 512

# Graceful fallback to console-only logging if OTLP collector is unavailable.
# When true (default), the application starts with console logging if the collector
# cannot be reached. Set to false to require a working collector in production.
# graceful_fallback = true

Resilience

Degraded Mode

[degraded_mode]
# Enable fallback when backend unavailable
enabled = true

# Message returned during degraded mode
unavailable_message = "I'm currently experiencing technical difficulties. Please try again in a moment."

# Cooldown before retrying primary backend (seconds)
retry_cooldown_secs = 30

# Number of failures before entering degraded mode
failure_threshold = 3

# Number of successes required to exit degraded mode
success_threshold = 2

Retry Configuration

Exponential backoff for retrying failed requests.

[retry]
# Initial delay before first retry in milliseconds
initial_delay_ms = 100

# Maximum delay between retries in milliseconds
max_delay_ms = 10000

# Multiplier for exponential backoff (delay = initial * multiplier^attempt)
multiplier = 2.0

# Maximum number of retry attempts
max_retries = 3

Formula: delay = min(initial_delay * multiplier^attempt, max_delay)

Health Checks

[health]
# Global timeout for all health checks in seconds
global_timeout_secs = 5

# Service-specific timeout overrides (uncomment to customize):
# inference_timeout_secs = 10
# email_timeout_secs = 5
# calendar_timeout_secs = 5
# weather_timeout_secs = 5

Event Bus

The in-process event bus decouples post-processing from the user-facing response path. When enabled, background handlers asynchronously handle fact extraction, audit logging, conversation persistence verification, and metrics collection — reducing perceived latency by 100–500 ms per request.

[events]
# Enable or disable the event bus (default: true)
enabled = true

# Broadcast channel buffer capacity (default: 1024)
# Increase if handlers can't keep up under high load.
channel_capacity = 1024

# Error handling policy: "log" or "retry" (default: "log", reserved for future use)
# handler_error_policy = "log"

# Retry settings (reserved for future use)
# max_retry_attempts = 3
# retry_delay_ms = 500

Background handlers spawned automatically:

Tip: Set enabled = false to disable all background processing and fall back to synchronous inline behavior.

Agentic Mode

Multi-agent orchestration for complex tasks. When enabled, the system decomposes complex user requests into parallel sub-tasks, each handled by an independent AI agent.

Note: Requires [agent.tool_calling] enabled = true to be set.

[agentic]
# Enable agentic mode (default: false)
enabled = false

# Maximum concurrent sub-agents running in parallel
max_concurrent_sub_agents = 4

# Maximum sub-agents spawned per task
max_sub_agents_per_task = 10

# Total timeout for the entire agentic task (minutes)
total_timeout_minutes = 30

# Timeout for each individual sub-agent (minutes)
sub_agent_timeout_minutes = 10

# Operations that require user approval before execution
# Example: ["send_email", "delete_contact", "execute_code"]
require_approval_for = []

Vault Integration

[vault]
# Vault server address
# address = "http://127.0.0.1:8200"

# AppRole authentication (recommended)
# role_id = "your-role-id"
# secret_id = "your-secret-id"

# Or token authentication
# token = "hvs.your-token"

# KV engine mount path
# mount_path = "secret"

# Request timeout in seconds
# timeout_secs = 5

# Vault Enterprise namespace (optional)
# namespace = "admin/pisovereign"

Environment Variables

All configuration options can be set via environment variables. Use __ (double underscore) as the nesting separator to avoid conflicts with field names containing underscores (e.g., phone_number):

Special variables:

Example Configurations

Development

environment = "development"

[server]
host = "127.0.0.1"
port = 3000
log_format = "text"

[inference]
base_url = "http://localhost:11434"
default_model = "qwen2.5:1.5b"

[database]
path = "./dev.db"

[cache]
enabled = false  # Disable for debugging

[security]
rate_limit_enabled = false
tls_verify_certs = false

Production

environment = "production"

[server]
host = "127.0.0.1"  # Behind reverse proxy
port = 3000
log_format = "json"
cors_enabled = true
allowed_origins = ["https://app.example.com"]

[inference]
base_url = "http://localhost:11434"
default_model = "qwen2.5:1.5b"
timeout_ms = 120000

[database]
path = "/var/lib/pisovereign/pisovereign.db"
max_connections = 10

[security]
rate_limit_enabled = true
rate_limit_rpm = 30
min_tls_version = "1.3"

[prompt_security]
enabled = true
sensitivity = "high"
block_on_detection = true

[vault]
address = "https://vault.internal:8200"
role_id = "..."
mount_path = "secret"

[telemetry]
enabled = true
otlp_endpoint = "http://tempo:4317"
sample_ratio = 0.1

Minimal (Quick Start)

environment = "development"

[server]
port = 3000

[inference]
base_url = "http://localhost:11434"
default_model = "qwen2.5:1.5b"

[database]
path = "pisovereign.db"

Adaptive Model Routing

Complexity-based request routing to reduce latency and resource usage

Overview

Model routing classifies every incoming message into one of four complexity tiers and routes it to an appropriately sized LLM model — or answers trivially without calling any model at all.

Goal: Route 60–70% of queries to the Trivial or Simple tier, reducing average response time from ~8 s to ~3 s.

Configuration

Enable in config.toml:

[model_routing]
enabled = true

[model_routing.models]
trivial = "template"       # No LLM call
simple = "gemma4:e4b"
moderate = "gemma4:26b"
complex = "gemma4:31b"

[model_routing.classification]
confidence_threshold = 0.6
max_simple_words = 15
max_simple_chars = 100
max_moderate_sentences = 5
complex_min_words = 50
complex_keywords = [
    "code", "implement", "explain", "analyze",
    "compare", "debug", "refactor", "translate"
]
trivial_patterns = [
    "^hi$", "^hello$", "^hey$", "^hallo$",
    "^moin$", "^danke$", "^thanks$"
]

[model_routing.templates]
greeting = ["Hello! How can I help?", "Hallo! Wie kann ich helfen?"]
farewell = ["Goodbye!", "Tschüss!"]
thanks = ["You're welcome!", "Gerne!"]
help = ["I can help with questions, tasks, weather, transit, and more."]
system_info = ["PiSovereign — your private AI assistant."]
unknown = ["How can I help you?", "Wie kann ich Ihnen helfen?"]

Docker Compose

When routing is enabled, Ollama needs to keep multiple models loaded. Set in compose.yml:

OLLAMA_MAX_LOADED_MODELS: 3

This allows the small and large models to stay warm in memory simultaneously.

How Classification Works

The rule-based classifier runs synchronously (no LLM call) and takes <1 ms:

1. Trivial detection: Regex patterns, emoji-only, empty input → instant template
2. Complex detection: Code patterns (backticks, keywords), high word count (≥50), configured keywords → large model
3. Simple detection: Short messages (≤15 words, ≤100 chars), single sentence, no conversation history → small model
4. Moderate fallback: Everything else, or follow-up messages in an ongoing conversation

Confidence & Tier Upgrades

Each classification includes a confidence score (0.0–1.0). When confidence falls below the confidence_threshold (default: 0.6), the classifier upgrades to the next higher tier:

• Simple → Moderate
• Moderate → Complex

This ensures borderline cases use a more capable model rather than risk a poor response.

Metrics

Model routing exposes Prometheus metrics at /metrics/prometheus:

model_routing_requests_total{tier="trivial"} 142
model_routing_requests_total{tier="simple"} 89
model_routing_requests_total{tier="moderate"} 45
model_routing_requests_total{tier="complex"} 24
model_routing_template_hits_total 142
model_routing_upgrades_total 12

The JSON /metrics endpoint also includes a model_routing object when routing is enabled.

Decorator Chain

When model routing is enabled, the inference decorator chain becomes:

Per tier:
  OllamaInferenceAdapter(tier_model)
    → DegradedInferenceAdapter (per-tier circuit breaker)

ModelRoutingAdapter
  → classifies message → selects tier adapter
  → delegates to appropriate tier

CachedInferenceAdapter (shared across all tiers)
  → SanitizedInferencePort (shared output filter)
    → ChatService

When disabled, the chain is the standard single-model path:

OllamaInferenceAdapter → Degraded → Cached → Sanitized → ChatService

Backward Compatibility

• The old [model_selector] configuration is deprecated since v0.6.0
• Setting model_routing.enabled = false (or omitting the section) preserves the original single-model behavior
• No breaking changes to the InferencePort trait or HTTP API

External Services Setup

Configure WhatsApp, Signal, Email, CalDAV/CardDAV, OpenAI, and Brave Search integrations

Messenger Selection

PiSovereign supports one messenger at a time:

messenger = "signal"     # Signal via signal-cli (default)
messenger = "whatsapp"   # WhatsApp Business API
messenger = "none"       # Disable messenger integration

WhatsApp Business

PiSovereign uses the WhatsApp Business API for bidirectional messaging.

Meta Business Account

1. Create a Meta Business Account
2. Create a Meta Developer Account

WhatsApp App Setup

1. Create an app at developers.facebook.com/apps (type: Business)
2. Add the WhatsApp product
3. In WhatsApp → Getting Started, note the Phone Number ID and generate an Access Token
4. For a permanent token: Business Settings → System Users → create Admin → generate token with whatsapp_business_messaging permission
5. Note the App Secret from App Settings → Basic

Webhook Configuration

PiSovereign needs a public URL for WhatsApp webhooks. The Docker Compose stack uses Traefik for this automatically.

Configure in Meta Developer Console:

1. WhatsApp → Configuration → Edit Webhooks
2. Callback URL: https://your-domain.com/v1/webhooks/whatsapp
3. Verify Token: your chosen verify_token
4. Subscribe to: messages, message_template_status_update

PiSovereign Configuration

Store credentials in Vault:

docker compose exec vault vault kv put secret/pisovereign/whatsapp \
    access_token="your-access-token" \
    app_secret="your-app-secret"

Add to config.toml:

[whatsapp]
phone_number_id = "your-phone-number-id"
verify_token = "your-verify-token"
signature_required = true
api_version = "v18.0"

Signal Messenger

Signal provides privacy-focused messaging with end-to-end encryption, polling-based delivery (no public URL required), and voice message support.

For the full setup guide, see Signal Setup.

Quick config:

messenger = "signal"

[signal]
phone_number = "+1234567890"
socket_path = "/var/run/signal-cli/socket"

Email Integration (IMAP/SMTP)

PiSovereign supports any provider with standard IMAP/SMTP access. Use the provider field for automatic host/port configuration, or specify hosts and ports manually.

Provider Quick Reference

Gmail: Enable IMAP in Gmail settings, then generate an App Password (requires 2-Step Verification).

Outlook: Enable IMAP in settings, generate an App Password at account.microsoft.com/security if 2FA is enabled.

Configuration

Store the password in Vault:

docker compose exec vault vault kv put secret/pisovereign/email \
    password="your-email-password"

Example configs — choose one:

# Gmail (using provider preset)
[email]
provider = "gmail"
email = "yourname@gmail.com"

# Outlook (custom provider with explicit hosts)
[email]
provider = "custom"
imap_host = "outlook.office365.com"
imap_port = 993
smtp_host = "smtp.office365.com"
smtp_port = 587
email = "yourname@outlook.com"

CalDAV / CardDAV (Baïkal)

Baïkal is a lightweight, self-hosted CalDAV/CardDAV server included in the Docker Compose stack as an optional profile.

Docker Setup

docker compose --profile caldav up -d

This starts Baïkal at http://localhost/caldav (via Traefik). PiSovereign accesses it internally via the Docker network at http://baikal:80/dav.php.

Security: Baïkal is not directly exposed to the internet. All access is through the Docker network or localhost.

Auto-recreation: PiSovereign automatically re-creates calendars and address books if they return 404 errors (e.g., after a Baïkal database reset or re-initialization). No manual intervention is needed.

Initial Setup

1. Open http://localhost/caldav in your browser
2. Complete the setup wizard, set an admin password, choose SQLite
3. Create a user under Users and Resources
4. Create a calendar via any CalDAV client or the admin interface

Configuration

Store credentials in Vault (optional):

docker compose exec vault vault kv put secret/pisovereign/caldav \
    username="your-username" \
    password="your-password"

Add to config.toml:

[caldav]
server_url = "http://baikal:80/dav.php"
username = "your-username"
password = "your-password"
calendar_path = "/calendars/username/default/"
verify_certs = true
timeout_secs = 30

CardDAV for contacts uses the same server and credentials — PiSovereign automatically discovers the address book.

OpenAI API

OpenAI is used as an optional cloud fallback for speech processing (STT/TTS).

Setup

1. Create an account at platform.openai.com
2. Add a payment method and set usage limits (recommended: $10–20/month)
3. Create an API key at platform.openai.com/api-keys

Store in Vault:

docker compose exec vault vault kv put secret/pisovereign/openai \
    api_key="sk-your-openai-key"

Configuration

[speech]
provider = "hybrid"  # Local first, OpenAI fallback

openai_base_url = "https://api.openai.com/v1"
stt_model = "whisper-1"
tts_model = "tts-1"
default_voice = "nova"
timeout_ms = 60000

[speech.hybrid]
prefer_local = true
allow_cloud_fallback = true

For maximum privacy (no cloud at all):

[speech]
provider = "local"

[speech.hybrid]
prefer_local = true
allow_cloud_fallback = false

Brave Search API

Brave Search enables web search with source citations. DuckDuckGo is used as an automatic fallback.

Setup

1. Sign up at brave.com/search/api — the Free tier (2,000 queries/month) is sufficient for personal use
2. Create an API key in the dashboard

Store in Vault:

docker compose exec vault vault kv put secret/pisovereign/websearch \
    brave_api_key="BSA-your-brave-api-key"

Configuration

[websearch]
api_key = "BSA-your-brave-api-key"
max_results = 5
timeout_secs = 30
fallback_enabled = true
safe_search = "moderate"
country = "DE"
language = "de"

DuckDuckGo’s Instant Answer API is used automatically when Brave is unavailable, rate-limited, or not configured. No API key required. To disable the fallback:

[websearch]
fallback_enabled = false

Verify All Integrations

# Check all services
docker compose exec pisovereign pisovereign-cli status

# Or via HTTP
curl https://your-domain.example.com/ready/all | jq

Troubleshooting

WhatsApp webhook not receiving messages

• Verify callback URL is publicly accessible
• Check verify_token matches between config and Meta console
• Ensure webhook is subscribed to messages

Email connection refused

• Verify host and port match your provider
• Check password type (App Password for Gmail/Outlook)

CalDAV authentication failed

• Verify username/password
• Check calendar_path format — must match user and calendar name in Baïkal

Next Steps

• Configuration Reference — Fine-tune all options
• Monitoring — Track service health

Signal Messenger Setup

📱 Connect Signal messenger to PiSovereign via Docker

PiSovereign uses signal-cli as a Docker container to send and receive Signal messages. This guide covers the complete setup process.

Prerequisites

• Docker must be running (docker compose up -d in the docker/ directory)
• Signal app installed on your smartphone and registered with a phone number
• qrencode installed on the host (for QR code display)
• Phone number stored in .env or Vault

Installing qrencode

macOS:

brew install qrencode

Debian / Raspberry Pi:

sudo apt-get install qrencode

Linking Your Signal Account

signal-cli is connected as a linked device to your existing Signal account (similar to Signal Desktop). No new account is created.

⚠️ Important: The link command outputs a sgnl:// URI that must be converted into a QR code. You cannot pipe the output directly to qrencode, because qrencode waits for EOF — by that time the link process has already terminated and the URI has expired. Therefore, two separate terminal commands must be used.

Step 1: Start the Link Process and Capture the URI

Open a terminal and run:

docker exec -it pisovereign-signal-cli signal-cli --config /var/lib/signal-cli link -n "PiSovereign" | tee /tmp/signal-uri.txt

This command:

1. Starts the link process in the background
2. Captures the URI to /tmp/signal-uri.txt
3. Displays the URI after 8 seconds (for verification)

Step 2: Display the QR Code and Scan

Once the URI is displayed, generate the QR code:

head -1 /tmp/signal-uri.txt | tr -d '\n' | qrencode -t ANSIUTF8

Now quickly scan with your phone:

1. Open Signal on your smartphone
2. Go to Settings → Linked Devices → Link New Device
3. Scan the QR code shown in the terminal
4. Confirm the link on your phone

💡 The link process is still running in the background, waiting for the scan. If the QR code has expired, simply repeat both steps.

Step 3: Verify the Link

After a successful scan, restart the container:

cd docker/
docker compose restart signal-cli

The logs should no longer show a NotRegisteredException:

docker compose logs signal-cli

Configuration

Phone Number

The Signal phone number must be known to PiSovereign. Use one of the following methods:

Option A: .env file (in the docker/ directory):

PISOVEREIGN_SIGNAL__PHONE_NUMBER=+491234567890

Option B: Vault:

vault kv put secret/pisovereign/signal \
    phone_number="+491234567890"

See Vault Setup for full Vault initialization and secret management.

config.toml

messenger = "signal"

[signal]
phone_number = "+491234567890"        # E.164 format
socket_path = "/var/run/signal-cli/socket"
timeout_ms = 30000

Environment Variables

export PISOVEREIGN_MESSENGER=signal
export PISOVEREIGN_SIGNAL__PHONE_NUMBER=+491234567890
export PISOVEREIGN_SIGNAL__SOCKET_PATH=/var/run/signal-cli/socket

Troubleshooting

Socket Already in Use

Failed to bind socket /var/run/signal-cli/socket: Address already in use

Cause: A stale socket from a previous run persists in the Docker volume.

Solution: The container uses an entrypoint script that automatically cleans up the socket before starting. If the error still occurs:

docker compose restart signal-cli

NotRegisteredException

WARN MultiAccountManager - Ignoring +49...: User is not registered.

Cause: signal-cli has not been linked to a Signal account.

Solution: Complete the account linking procedure.

Expired QR Code

Cause: qrencode waits for EOF. When piping signal-cli link | qrencode, the QR code is only displayed after the link process terminates — at which point the URI is already invalid.

Solution: Redirect the URI to a file (Step 1) and display it as a QR code separately (Step 2). See Linking Your Signal Account.

Daemon Connection Failed

# Check the socket
docker exec pisovereign-signal-cli ls -la /var/run/signal-cli/socket

# Check container logs
docker compose logs signal-cli

Security

• Signal messages are end-to-end encrypted
• signal-cli stores cryptographic keys locally in the signal-cli-data volume
• The socket (signal-cli-socket) is shared only within the Docker network

Backup

The signal-cli data should be backed up regularly:

docker run --rm -v docker_signal-cli-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/signal-cli-backup.tar.gz -C /data .

See Backup & Restore for complete backup procedures.

See Also

• Docker Setup — Set up the Docker environment
• Vault Setup — Manage secrets
• Configuration Reference — All configuration options
• signal-cli Documentation — Upstream documentation

Reminder System

PiSovereign includes a proactive reminder system that helps you stay on top of appointments, tasks, and custom reminders. The system integrates with CalDAV calendars and provides beautiful German-language notifications via WhatsApp or Signal.

Features

• Calendar Integration: Automatically creates reminders from CalDAV events
• Custom Reminders: Create personal reminders with natural language
• Smart Notifications: Beautiful formatted messages with emoji and key information
• Location Support: Google Maps links and ÖPNV transit connections for location-based events
• Snooze Management: Snooze reminders up to 5 times (configurable)
• Morning Briefing: Daily summary of your upcoming appointments

Natural Language Commands

Creating Reminders

"Erinnere mich morgen um 10 Uhr an den Arzttermin"
"Remind me tomorrow at 3pm to call mom"
"Erinnere mich in 2 Stunden an die Wäsche"

Listing Reminders

"Zeige meine Erinnerungen"
"Welche Termine habe ich heute?"
"Liste alle aktiven Erinnerungen"

Snoozing Reminders

"Erinnere mich nochmal in 15 Minuten"
"Snooze für eine Stunde"

Acknowledging Reminders

"Ok, danke!"
"Erledigt"

Deleting Reminders

"Lösche die Erinnerung zum Arzttermin"

Transit Connections

When you have an appointment at a specific location, PiSovereign can automatically include ÖPNV (public transit) connections in your reminder:

📅 **Meeting mit Hans**
📍 Alexanderplatz 1, Berlin
🕒 Morgen um 14:00 Uhr

🚇 **So kommst du hin:**
🚌 Bus 200 → S-Bahn S5 → U-Bahn U2
   Abfahrt: 13:22 (38 min)
   Ankunft: 14:00

🗺️ [Auf Google Maps öffnen](https://www.google.com/maps/...)

Searching Transit Routes

You can also search for transit connections directly:

"Wie komme ich zum Hauptbahnhof?"
"ÖPNV Verbindung nach Alexanderplatz"

Configuration

Add the following sections to your config.toml:

Transit Configuration

[transit]
# Include transit info in location-based reminders
include_in_reminders = true

# Your home location for route calculations
home_location = { latitude = 52.52, longitude = 13.405 }

# Transport modes to include
products_bus = true
products_suburban = true    # S-Bahn
products_subway = true      # U-Bahn
products_tram = true
products_regional = true    # RB/RE
products_national = false   # ICE/IC

Reminder Configuration

[reminder]
# Maximum number of snoozes per reminder (default: 5)
max_snooze = 5

# Default snooze duration in minutes (default: 15)
default_snooze_minutes = 15

# How far in advance to create reminders from CalDAV events
caldav_reminder_lead_time_minutes = 30

# Interval for checking due reminders (seconds)
check_interval_secs = 60

# CalDAV sync interval (minutes)
caldav_sync_interval_minutes = 15

# Morning briefing settings
morning_briefing_time = "07:00"
morning_briefing_enabled = true

CalDAV Configuration

For calendar integration, you need a CalDAV server (like Baikal, Radicale, or Nextcloud):

[caldav]
server_url = "https://cal.example.com/dav.php"
username = "your-username"
password = "your-password"
calendar_path = "/calendars/user/default"

Reminder Sources

Reminders can come from two sources:

1. CalDAV Events: Automatically synced from your calendar
2. Custom Reminders: Created via natural language commands

CalDAV events include the original event details (title, time, location) while custom reminders are more flexible and can include any text.

Notification Format

Reminders are formatted as beautiful German messages with:

• Bold headers for event titles
• Emoji prefixes for quick scanning (📅 📍 🕒)
• Time formatting relative to now (“in 30 Minuten”)
• Location links to Google Maps
• Transit info for getting there

Example reminder notification:

📅 **Zahnarzt Dr. Müller**
📍 Friedrichstraße 123, Berlin
🕒 Heute um 15:00 (in 2 Stunden)

🗺️ Auf Google Maps öffnen

Morning Briefing

When enabled, you receive a daily summary at the configured time (default 7:00 AM):

☀️ **Guten Morgen!**

📅 **Heute hast du 3 Termine:**

1. 09:00 - Team Meeting (Büro)
2. 12:30 - Mittagessen mit Lisa (Restaurant Mitte)
3. 16:00 - Arzttermin (Praxis Dr. Schmidt)

🌤️ Wetter: 18°C, leicht bewölkt

📋 **Offene Erinnerungen:**
- Geburtstagskarte für Mama kaufen
- Wäsche abholen

Snooze Limits

Each reminder can be snoozed up to max_snooze times (default: 5). After that, the system will indicate that no more snoozes are available:

⏰ Diese Erinnerung wurde bereits 5x verschoben.
Bitte bestätige oder lösche sie.

Status Tracking

Reminders go through these states:

• Pending: Waiting for the remind time
• Sent: Notification was delivered
• Acknowledged: User confirmed receipt
• Snoozed: User requested a later reminder
• Deleted: User removed the reminder

You can list reminders filtered by status using commands like “zeige alle erledigten Erinnerungen”.

Snippets

PiSovereign includes a Snippet system for reusable text blocks. Snippets are Markdown-formatted templates that you can manage via the web UI and instantly insert into chat messages using the /snippet trigger.

Features

• Reusable Text Blocks: Save frequently used instructions, prompts, or templates as named snippets
• Markdown Support: Full Markdown formatting in snippet content
• /snippet Chat Trigger: Type /snippet in the chat input to search and insert snippets inline
• Nested Resolution: Snippets can reference other snippets via /snippet Title — all references are resolved recursively at insertion time
• Cycle Detection: Circular snippet references are detected and prevented (max depth: 10 levels)
• Full-Text Search: Search snippets by title via the UI or API

Managing Snippets

Web UI

Navigate to Snippets in the sidebar (code brackets icon). The Snippets page provides full CRUD:

• Create: Click “New Snippet”, enter a unique title and Markdown content, then save
• Edit: Click on any snippet row to open the edit form
• Search: Use the search bar to filter snippets by title
• Delete: Click the delete button on a snippet row (with confirmation)

REST API

All snippet operations are also available via the REST API under /v1/snippets. See the API Reference for full endpoint documentation.

# List all snippets
curl -H "Authorization: Bearer sk-..." http://localhost:3000/v1/snippets

# Create a snippet
curl -X POST -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Meeting Follow-up", "content": "## Action Items\n\n- [ ] ..."}' \
  http://localhost:3000/v1/snippets

# Get resolved content (nested references expanded)
curl -H "Authorization: Bearer sk-..." \
  http://localhost:3000/v1/snippets/{id}/resolved

Using Snippets in Chat

The /snippet Trigger

In the chat input, type /snippet followed by a space to open the snippet picker:

/snippet Meeting

A dropdown appears showing matching snippets filtered by title. Select one to replace the /snippet ... text with the resolved snippet content.

Nested Snippet Resolution

Snippets can embed other snippets by including /snippet Title in their Markdown content. When you insert a snippet (via chat or API), all nested references are resolved recursively.

Example:

Snippet “Task List”:

## Aufgaben

1. Analysiere alle gesammelten Informationen
2. Erstelle eine priorisierte Taskliste
3. Speichere als Erinnerungen im System

Snippet “Calendar Entries”:

## Kalendereinträge

1. Erstelle Kalendereinträge für alle Termine
2. Verknüpfe relevante Tasks mit Terminen
3. Setze Erinnerungen für kritische Deadlines

Snippet “Meeting Follow-up Complete”:

# Meeting-Nachbereitung

/snippet Task List

/snippet Calendar Entries

When you insert “Meeting Follow-up Complete”, the /snippet Task List and /snippet Calendar Entries references are automatically replaced with their respective content — producing a single, fully expanded document.

Limits

Use Cases

• AI Prompt Templates: Save complex AI instructions as snippets and insert them into chat with a single command
• Meeting Workflows: Combine task creation, calendar entries, and reminders into a composite snippet
• Research Templates: Standard web research instructions with documentation format
• Knowledge Graph Queries: Reusable analysis prompts for the knowledge graph

Tips

• Keep snippet titles short and descriptive — they are used for search in the /snippet picker
• Use nested snippets to compose complex workflows from simpler building blocks
• The /snippet trigger works with partial title matches, so you don’t need to type the full title

Multi-Agent Project Management with PiSovereign

How-To Guide: Plan an entire software project from requirements analysis through calendar milestones using 9 specialized AI agents — then execute the tasks with GitHub Copilot.

Table of Contents

1. Overview
2. Prerequisites
3. Creating the Agent Team
4. Example Project: SmartInventory
5. Phase-by-Phase Walkthrough
   • Phase 1: Project Intake
   • Phase 2: PM / Orchestrator
   • Phase 3: Research
   • Phase 4: Data / Analytics
   • Phase 5: Solution Architect
   • Phase 6: Security / DevSecOps
   • Phase 7: Developer
   • Phase 8: QA / Validation
   • Phase 9: DevOps / SRE
   • Phase 10: Documentation / Knowledge
6. Results: Calendar Events & Tasks
7. Executing Tasks with GitHub Copilot
8. Tips & Best Practices

Overview

PiSovereign enables a team of specialized agents to collaborate within a single AI conversation. Each agent has its own profile with a defined role, skills, communication style, and optional model overrides. The system automatically orchestrates agents in dependency-aware waves — executing tasks in parallel where possible and sequentially where necessary.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                          USER (Chat UI)                           │
│  Project description + upload documents + @Agent mentions         │
└──────────────┬──────────────────────────────────────┬──────────────┘
               │                                      │
               ▼                                      ▼
┌──────────────────────────┐         ┌──────────────────────────────┐
│   File Ingestion Service │         │    Agentic Orchestrator      │
│  ┌────────────────────┐  │         │  ┌────────────────────────┐  │
│  │ Document Parser     │  │         │  │ 1. Planning (LLM)      │  │
│  │ OCR / Code Parser   │  │         │  │ 2. Validation          │  │
│  │ Entity Extraction   │  │         │  │ 3. Wave Computation    │  │
│  └────────┬───────────┘  │         │  │ 4. Parallel Execution  │  │
│           │              │         │  │ 5. Result Synthesis    │  │
│           ▼              │         │  └──────────┬─────────────┘  │
│  ┌────────────────────┐  │         │             │                │
│  │ Knowledge Graph     │◄─┼─────────┼─────────────┘                │
│  │ (Nodes + Edges +   │  │         │                              │
│  │  pgvector Embeddings)│  │         │  Sub-Agent Execution:       │
│  └────────────────────┘  │         │  ┌──────┐ ┌──────┐ ┌──────┐ │
└──────────────────────────┘         │  │ PM   │ │Resrch│ │Archi │ │
                                     │  └──┬───┘ └──┬───┘ └──┬───┘ │
                                     │     │        │        │     │
                                     │     ▼        ▼        ▼     │
                                     │  ┌──────────────────────┐   │
                                     │  │ Tool Execution       │   │
                                     │  │ (ReAct Loop)         │   │
                                     │  │ • create_calendar..  │   │
                                     │  │ • create_task        │   │
                                     │  │ • search_web         │   │
                                     │  │ • store_memory       │   │
                                     │  └──────────┬───────────┘   │
                                     └─────────────┼───────────────┘
                                                   │
                                                   ▼
                                     ┌──────────────────────────────┐
                                     │   CalDAV Server (Baikal)     │
                                     │  • VEVENT (Milestones)       │
                                     │  • VTODO  (Tasks w/ Priority)│
                                     └──────────────────────────────┘

The 9 Lifecycle Agents

Dependency Flow

Phase 1: Intake (Upload documents)
    │
    ▼
Phase 2: PM/Orchestrator ──► High-level plan + milestones
    │
    ▼
Phase 3: Research ──► Requirements + knowledge graph
    │
    ├──────────────────┐
    ▼                  ▼
Phase 4: Data      Phase 5: Architect ◄──── Phase 6: Security
    │                  │                        │
    └──────┬───────────┘                        │
           ▼                                    │
Phase 7: Developer ◄───────────────────────────┘
    │
    ├──────────────────┐
    ▼                  ▼
Phase 8: QA        Phase 9: DevOps
    │                  │
    └──────┬───────────┘
           ▼
Phase 10: Documentation ──► Final tasks + calendar

Prerequisites

1. PiSovereign Docker Setup

PiSovereign must be running with the CalDAV profile enabled so that calendar events and tasks can be created:

# Start core + CalDAV
just docker-up -- --profile caldav

# Or start everything (incl. monitoring):
just docker-up-all

2. Configuration (config.toml)

The following sections must be enabled:

# ─── Agentic Mode ────────────────────────────────────────────
[agentic]
enabled = true
max_concurrent_sub_agents = 3          # Pi 5: 2-3, Desktop: 3-5
max_sub_agents_per_task = 8
total_timeout_minutes = 10
sub_agent_timeout_minutes = 5
require_approval_for = ["send_email", "delete_contact", "execute_code"]

# ─── Tool Calling (ReAct Loop) ───────────────────────────────
[agent.tool_calling]
enabled = true
max_iterations = 5
parallel_tool_execution = true

# ─── CalDAV Server ───────────────────────────────────────────
[caldav]
enabled = true
base_url = "http://baikal:80/dav.php"
# Credentials via Vault: just docker-vault-set-caldav USERNAME PASSWORD

# ─── Token Optimization (recommended) ───────────────────────
[token_optimization]
enabled = true
max_profile_prompt_tokens = 300        # Agent prompt budget

3. Vault Secrets

# Set CalDAV credentials
just docker-vault-set-caldav admin mysecurepassword

4. Verify Initial Setup

Open the web UI at http://localhost:3000 and navigate to:

• Team (sidebar) → Manage agent profiles
• Chat (sidebar) → Conversations with @mentions
• Agentic (sidebar) → Launch complex multi-agent tasks

Creating the Agent Team

Create all 9 agents via the web UI (Team → + New Agent) or through the API. Below are the complete profile definitions for each agent.

1. PM / Orchestrator

POST /v1/agent-profiles
{
  "name": "PM",
  "role": "Senior project manager and orchestrator. Analyzes requirements, breaks down goals into milestones, creates timelines with calendar entries, assigns tasks to agents, and monitors progress.",
  "emoji": "📋",
  "skills": [
    "project_management", "milestone_planning", "task_decomposition",
    "risk_assessment", "stakeholder_communication", "resource_planning",
    "timeline_creation", "priority_management", "workflow_design",
    "multi_agent_coordination", "calendar_management"
  ],
  "style": {
    "tone": "structured and decisive",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are an experienced project manager. Your task is to break down requirements into clear milestones, create timelines with concrete calendar entries, and distribute tasks to specialized agents. Use the create_calendar_event and create_task tools to schedule deadlines and tasks in the calendar. Each milestone needs a date, a description, and clear deliverables. Prioritize by business value and technical dependencies.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "high"
}

2. Research Agent

POST /v1/agent-profiles
{
  "name": "Research",
  "role": "Senior research agent. Analyzes internal documents, knowledge graphs, and external sources to refine requirements and close knowledge gaps.",
  "emoji": "🔍",
  "skills": [
    "document_analysis", "knowledge_graph_analysis", "requirements_refinement",
    "gap_analysis", "data_source_evaluation", "api_analysis",
    "constraint_identification", "fact_verification", "web_research",
    "data_quality_assessment"
  ],
  "style": {
    "tone": "analytical and thorough",
    "verbosity": "verbose",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a research specialist. Analyze the knowledge graph (via recall_memory) and search the web (via search_web) for relevant information. Identify knowledge gaps, verify assumptions, and clearly document open questions. Use store_memory to save key findings for other agents.",
  "inference_overrides": {
    "temperature": 0.5
  },
  "autonomy_level": "medium"
}

3. Data / Analytics Agent

POST /v1/agent-profiles
{
  "name": "DataAnalyst",
  "role": "Senior data analyst. Compares schemas, detects patterns in data, and proposes data models, transformation rules, and index strategies.",
  "emoji": "📊",
  "skills": [
    "data_modeling", "schema_design", "data_mapping", "data_validation",
    "pattern_recognition", "performance_analysis", "index_optimization",
    "data_quality", "data_transformation", "data_governance"
  ],
  "style": {
    "tone": "precise and data-driven",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a data analyst. Analyze existing data structures and propose optimal schemas, indexes, and data models. Consider performance, storage, and consistency. Use the knowledge graph to understand existing entities and their relationships. Document data flows clearly.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

4. Solution Architect Agent

POST /v1/agent-profiles
{
  "name": "Architect",
  "role": "Senior architect. Translates requirements into an overall technical architecture: services, interfaces, data flows, protocols, and deployment topology.",
  "emoji": "🏗️",
  "skills": [
    "system_architecture", "api_design", "data_flow_design",
    "microservices", "event_driven_architecture", "deployment_topology",
    "scalability_planning", "integration_patterns", "protocol_selection",
    "technology_evaluation"
  ],
  "style": {
    "tone": "technical and systematic",
    "verbosity": "verbose",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a solution architect. Design the overall technical architecture based on the results from research and data analysis. Define services, APIs, data flows, and deployment strategy. Document architecture decisions as ADRs (Architecture Decision Records). Focus on scalability, maintainability, and clean interfaces.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "medium"
}

5. Security / DevSecOps Agent

POST /v1/agent-profiles
{
  "name": "Security",
  "role": "Senior security agent. Defines auth models, secrets management, encryption, logging policies, and analyzes threat models.",
  "emoji": "🔐",
  "skills": [
    "threat_modeling", "authentication_design", "authorization_design",
    "secrets_management", "encryption_strategy", "security_audit",
    "compliance_check", "owasp_analysis", "security_architecture",
    "incident_response_planning"
  ],
  "style": {
    "tone": "cautious and thorough",
    "verbosity": "verbose",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a security specialist. Analyze the planned architecture for vulnerabilities. Create a threat model, define auth flows (RBAC/ABAC), secrets management, and encryption strategies. Validate against OWASP Top 10. Deliver concrete security requirements as tasks.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "low"
}

6. Developer Agent

POST /v1/agent-profiles
{
  "name": "Developer",
  "role": "Senior developer. Writes production code, tests, configurations, and breaks down architecture decisions into actionable development tasks.",
  "emoji": "💻",
  "skills": [
    "code_generation", "code_review", "test_automation",
    "refactoring", "api_implementation", "database_migration",
    "module_design", "type_system_design", "dependency_management",
    "code_documentation"
  ],
  "style": {
    "tone": "pragmatic and concise",
    "verbosity": "terse",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a senior developer. Break down the architecture into concrete development tasks with clear acceptance criteria. Each task should describe a specific module, API route, or database migration. Prioritize by technical dependencies. Use create_task to register each task in the calendar.",
  "inference_overrides": {
    "temperature": 0.2
  },
  "autonomy_level": "medium"
}

7. QA / Validation Agent

POST /v1/agent-profiles
{
  "name": "QA",
  "role": "Senior QA agent. Plans and defines tests at all levels: unit, integration, contract, and end-to-end tests. Detects edge cases and validation gaps.",
  "emoji": "✅",
  "skills": [
    "test_planning", "test_design", "edge_case_detection",
    "test_coverage_analysis", "load_testing_strategy",
    "contract_testing", "regression_testing", "test_automation_strategy",
    "quality_metrics", "acceptance_criteria"
  ],
  "style": {
    "tone": "meticulous and systematic",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a QA specialist. Create a comprehensive test strategy based on the development tasks. For each module, define: unit tests, integration tests, edge cases, and acceptance criteria. Identify risk areas that require special test coverage. Create QA tasks with create_task.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

8. DevOps / SRE Agent

POST /v1/agent-profiles
{
  "name": "DevOps",
  "role": "Senior DevOps and SRE agent. Defines CI/CD pipelines, deployment strategies, observability, and disaster recovery workflows.",
  "emoji": "🚀",
  "skills": [
    "ci_cd_pipeline_design", "deployment_strategy", "container_orchestration",
    "monitoring_setup", "log_analysis", "incident_response",
    "disaster_recovery", "infrastructure_as_code", "rollback_strategy",
    "performance_tuning"
  ],
  "style": {
    "tone": "operational and pragmatic",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a DevOps/SRE specialist. Define the CI/CD pipeline, container configuration, monitoring stack, and deployment strategy. Create concrete tasks for: pipeline setup, Docker configuration, monitoring alerts, and runbook creation. Use create_task for each DevOps task.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

9. Documentation / Knowledge Agent

POST /v1/agent-profiles
{
  "name": "Documentation",
  "role": "Senior documentation and knowledge agent. Creates ADRs, API documentation, runbooks, operational guides, and maintains the knowledge graph.",
  "emoji": "📝",
  "skills": [
    "technical_writing", "adr_creation", "api_documentation",
    "runbook_design", "onboarding_guides", "knowledge_management",
    "document_structuring", "version_tracking", "knowledge_graph_maintenance",
    "stakeholder_documentation"
  ],
  "style": {
    "tone": "clear and structured",
    "verbosity": "verbose",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a documentation specialist. Based on all prior results, create: ADRs, API documentation templates, operational guides, and a final project plan. Save key decisions to the knowledge graph (store_memory). Create final milestone events (create_calendar_event) and documentation tasks (create_task).",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "medium"
}

Tip: All agents can also be created visually via the web UI under Team — emoji, role, skills, and system prompt can be configured conveniently through the form interface.

Example Project: SmartInventory

As a running example throughout this guide, we use a fictitious mid-sized software project:

Project Description

SmartInventory is a cloud-native warehouse management system for mid-sized retail companies. The system manages stock levels in real time, supports barcode/QR code scanning via smartphone, automatically alerts on low inventory, integrates with supplier APIs for automated reorders, and provides a role-based dashboard for warehouse workers, procurement staff, and management.

Planned Technology Stack

• Backend: Rust (Axum), PostgreSQL, Redis
• Frontend: SolidJS + Tailwind CSS
• Mobile: PWA with Camera API for barcode scanning
• Deployment: Docker Compose, Traefik, Prometheus/Grafana
• Authentication: OAuth 2.0 + RBAC

Documents for Intake

Over the course of this walkthrough, the following fictitious documents are “uploaded,” which the system ingests into the knowledge graph:

Phase-by-Phase Walkthrough

Phase 1: Project Intake — Uploading Documents

Goal: Load all project documents into the knowledge graph so that every agent can access them.

Step 1: Open Chat and Submit the Project Description

Open the Chat in the web UI and start a new conversation:

User:
I'm starting a new project called "SmartInventory" — a warehouse management system.
Here is the project description:

SmartInventory is a cloud-native warehouse management system for mid-sized retail
companies. It should manage stock levels in real time, support barcode scanning
via smartphone, alert on low inventory, integrate with supplier APIs for automated
reorders, and provide a role-based dashboard.

Tech stack: Rust (Axum), PostgreSQL, Redis, SolidJS, Docker Compose.
Target audience: Warehouse workers, procurement staff, management.
Planned go-live: Q3 2026.

Step 2: Upload Documents

In the chat input field: Click the file icon or drag and drop files into the input area.

User:
[Drag & Drop: requirements.md, data-model.csv, api-draft.json,
 stakeholder-interviews.md, compliance-checklist.md]

Here are the project documents. Please analyze them and integrate
the information into the knowledge graph.

What happens behind the scenes:

1. FileIngestionService receives each file
2. DocumentParser extracts the text (Markdown, CSV, JSON)
3. Entity Extraction identifies entities: Product, Warehouse, Order, Supplier, User Role, API Endpoint, GDPR, etc.
4. Knowledge Graph stores the entities as nodes with relationships:
   • Product —[part_of]→ Warehouse
   • Order —[relates_to]→ Supplier
   • Dashboard —[used_by]→ Management
5. pgvector embeddings are generated for each entity → semantic search enabled

Expected response:

PiSovereign:
✅ 5 files processed:
  • requirements.md — 23 entities extracted
  • data-model.csv — 15 entities, 8 relationships
  • api-draft.json — 12 API endpoints identified
  • stakeholder-interviews.md — 9 stakeholder requirements
  • compliance-checklist.md — 7 compliance requirements

Knowledge graph updated: 66 nodes, 34 edges.
You can now use @PM to create the project plan.

Phase 2: PM / Orchestrator

Goal: High-level planning with milestones and a timeline as calendar entries.

Option A: @Mention in Chat

User:
@PM Create a project plan for SmartInventory with milestones and
concrete calendar entries. Planned start: April 1, 2026,
go-live: September 30, 2026.
Consider the uploaded requirements and data model.

Option B: Agentic Task (recommended for complex tasks)

Navigate to Agentic in the sidebar:

Task input:
Analyze the SmartInventory project (all uploaded documents in the
knowledge graph) and create a complete project plan:
1. Break the project into 5-8 milestones
2. Create a calendar entry for each milestone (create_calendar_event)
3. Create tasks for the main deliverables (create_task) with priorities
4. Consider technical dependencies and risks
5. Timeframe: April 1, 2026 – September 30, 2026

What the PM agent does (tool calls):

The PM agent uses the ReAct loop and invokes tools:

Tool Call 1: recall_memory("SmartInventory requirements data model")
→ Retrieves knowledge graph context: entities, relationships, stakeholders

Tool Call 2: create_calendar_event({
    "title": "M1: Project Kickoff & Setup",
    "start": "2026-04-01T09:00:00Z",
    "end": "2026-04-01T17:00:00Z",
    "description": "Kickoff, dev environment, repository, CI/CD scaffold"
})

Tool Call 3: create_calendar_event({
    "title": "M2: Data Model & API Design Review",
    "start": "2026-04-24T09:00:00Z",
    "end": "2026-04-24T17:00:00Z",
    "description": "Schema finalized, API spec reviewed, security audit passed"
})

Tool Call 4: create_task({
    "title": "Set up repository and CI/CD",
    "due_date": "2026-04-07",
    "priority": "high",
    "description": "Git repo, Docker Compose, GitHub Actions pipeline, linting & formatting"
})

... (additional tool calls for M3-M6 and associated tasks)

SSE events (live progress in the UI):

event: planning
data: {"summary": "6 milestones identified", "sub_tasks": 4}

event: sub_agent_spawned
data: {"label": "Milestone planning", "profile_name": "PM"}

event: step_completed
data: {"steps_completed": 1, "steps_total": 6, "current_step": "M1 created"}

event: task_completed
data: {"final_response": "Project plan created with 6 milestones...",
       "actual_duration_seconds": 45}

Result — Milestone Plan:

Phase 3: Research Agent

Goal: Refine requirements, identify knowledge gaps, research external sources.

User:
@Research Analyze the knowledge graph for SmartInventory and check:
1. Are all functional requirements complete?
2. Are there technical risks with the chosen stack?
3. Which barcode/QR standards must be supported?
4. Which supplier API standards (EDI, REST) are industry standard?
Research on the web and document findings.

What the Research agent does:

Tool Call 1: recall_memory("SmartInventory functional requirements")
→ Knowledge Graph: 23 functional requirements from requirements.md

Tool Call 2: search_web("barcode QR code standards warehouse management 2026")
→ Result: EAN-13, Code 128, QR Code (ISO 18004), GS1 DataMatrix

Tool Call 3: search_web("supplier API standards EDI REST integration warehouse")
→ Result: EDI X12, GS1 EANCOM, REST-based cXML, Punchout catalogs

Tool Call 4: store_memory("SmartInventory supports EAN-13, Code 128,
  QR Code (ISO 18004). Supplier integration via REST (cXML) and
  optional EDI X12. Open question: Multi-warehouse support not specified.")

Result report:

Research:
📋 Analysis complete. Key findings:

✅ Complete: 21/23 requirements are sufficiently specified
⚠️ Gaps identified:
  • Multi-warehouse support not defined (single or multiple warehouses?)
  • PWA offline capability not specified
  • Unit conversion (piece/carton/pallet) missing

🔍 Technical recommendations:
  • Barcode standards: EAN-13, Code 128, QR Code (ISO 18004)
  • Supplier API: REST with cXML preferred, EDI X12 as fallback
  • PWA camera: Web API MediaDevices + ZXing library

All findings stored in the knowledge graph.

Phase 4: Data / Analytics Agent

Goal: Finalize data model, schema design, index strategy.

User:
@DataAnalyst Analyze the existing data model from the knowledge graph
and create a final schema design for SmartInventory. Consider:
- The multi-warehouse requirement (from Research)
- Performance for real-time inventory queries
- Audit trail for compliance (GDPR)

Result:

DataAnalyst:
📊 Schema Design for SmartInventory:

Core Entities (PostgreSQL):
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  warehouses  │    │   products   │    │   suppliers  │
├──────────────┤    ├──────────────┤    ├──────────────┤
│ id (UUID)    │    │ id (UUID)    │    │ id (UUID)    │
│ name         │    │ sku          │    │ name         │
│ location     │◄───│ barcode      │    │ api_endpoint │
│ capacity     │    │ name         │───►│ api_type     │
│ is_active    │    │ unit         │    │ lead_time_d  │
└──────────────┘    │ min_stock    │    └──────────────┘
                    └──────────────┘
                           │
                    ┌──────┴────────┐
                    │   inventory   │
                    ├───────────────┤
                    │ product_id    │  ← Composite Index
                    │ warehouse_id  │  ← (product_id, warehouse_id)
                    │ quantity      │
                    │ last_counted  │
                    │ updated_at    │
                    └───────────────┘

Index Strategy:
  • B-Tree: products(sku), products(barcode), inventory(product_id, warehouse_id)
  • GIN: products(name) with pg_trgm for fuzzy search
  • Partitioning: audit_log by month (GDPR retention periods)

Audit Trail:
  • Table audit_log with JSONB payload
  • Triggers on inventory for INSERT/UPDATE/DELETE
  • Retention: 10 years (configurable)

Phase 5: Solution Architect Agent

Goal: Define system architecture, services, APIs, data flows.

User:
@Architect Design the overall architecture for SmartInventory based
on the data model and research findings. Define:
- Service boundaries and API design
- Event-driven processes (inventory alerts, reorder triggers)
- Deployment topology (Docker)
- Supplier integration interfaces

Result (abbreviated):

Architect:
🏗️ Architecture Design — SmartInventory

Services:
┌───────────────────────────────────────────────────────────┐
│                    Traefik (Reverse Proxy)                │
├──────────┬──────────┬──────────┬──────────┬──────────────┤
│ Auth     │ Inventory│ Supplier │ Alert    │ Dashboard    │
│ Service  │ Service  │ Gateway  │ Engine   │ (SolidJS)    │
│ (OAuth)  │ (CRUD+)  │ (cXML)  │ (Events) │ (PWA)        │
├──────────┴──────────┴──────────┴──────────┴──────────────┤
│              PostgreSQL        │         Redis            │
│           (Data + Audit)       │   (Cache + Pub/Sub)      │
└────────────────────────────────┴─────────────────────────┘

Event Flow (inventory alert):
  inventory.updated → Redis Pub/Sub → Alert Engine
  → IF quantity < min_stock → create_task("Review reorder")
  → Email to procurement team

ADR-001: Monorepo with service modules (no microservice split in V1)
ADR-002: Event-driven via Redis Pub/Sub (not Kafka — overhead too high)
ADR-003: OAuth 2.0 + RBAC with 3 roles: admin, buyer, warehouse_worker

Phase 6: Security / DevSecOps Agent

Goal: Threat model, auth design, compliance requirements.

User:
@Security Create a threat model for SmartInventory and define:
- Auth flow (OAuth 2.0 + RBAC)
- Secrets management strategy
- GDPR-compliant data processing
- API hardening (rate limiting, input validation)

Result (abbreviated):

Security:
🔐 Threat Model & Security Requirements

STRIDE Analysis:
  ┌─────────────┬───────────────────────┬──────────────┐
  │ Threat      │ Risk                  │ Mitigation   │
  ├─────────────┼───────────────────────┼──────────────┤
  │ Spoofing    │ Fake barcode scans    │ JWT + HMAC   │
  │ Tampering   │ Inventory manipulation│ Audit trail  │
  │ Repudiation │ Unauthorized orders   │ Audit log    │
  │ Info Disc.  │ Customer data leak    │ Encryption   │
  │ DoS         │ API flooding          │ Rate limit   │
  │ Elevation   │ Role escalation       │ RBAC + ABAC  │
  └─────────────┴───────────────────────┴──────────────┘

RBAC Roles:
  • admin: Full access + audit logs
  • buyer: Orders + suppliers
  • warehouse_worker: Inventory + scanner

Security tasks created:
  ☐ Implement OAuth 2.0 server (Priority: high)
  ☐ RBAC middleware (Priority: high)
  ☐ Configure API rate limiting (Priority: medium)
  ☐ Database encryption at rest (Priority: medium)
  ☐ GDPR: Deletion policy for personal data (Priority: high)

Phase 7: Developer Agent

Goal: Create concrete development tasks with acceptance criteria.

User:
@Developer Break down the architecture and security requirements into
concrete development tasks. Each task should be a clearly scoped
work package with:
- Title, description, acceptance criteria
- Priority and estimated effort
- Technical dependencies on other tasks
Create the tasks in the calendar.

Example tool calls from the Developer agent:

Tool Call: create_task({
    "title": "INV-001: Inventory CRUD API",
    "due_date": "2026-05-08",
    "priority": "high",
    "description": "REST endpoints for inventory:\n
      POST /api/v1/inventory (stock in)\n
      GET /api/v1/inventory?warehouse_id=X (inventory list)\n
      PATCH /api/v1/inventory/{id} (update stock)\n
      Acceptance Criteria:\n
      - Validate all inputs\n
      - Audit log for every change\n
      - Unit tests ≥ 90% coverage\n
      Depends on: Schema migration, Auth middleware"
})

Tool Call: create_task({
    "title": "INV-002: Barcode Scanner PWA Module",
    "due_date": "2026-06-05",
    "priority": "high",
    "description": "PWA camera module for barcode scanning:\n
      - MediaDevices API for camera access\n
      - ZXing-js for EAN-13, Code 128, QR\n
      - Offline queue: buffer scans locally\n
      Acceptance Criteria:\n
      - Recognition in < 500ms\n
      - Works without network (PWA offline)\n
      Depends on: INV-001 (API must be ready)"
})

Result: ~15-20 tasks in the calendar with correct dependency ordering.

Phase 8: QA / Validation Agent

Goal: Define test strategy and QA tasks.

User:
@QA Create a test strategy for SmartInventory based on the
developer tasks. Define:
- Unit test requirements per module
- Integration tests for API endpoints
- E2E tests for critical workflows (stock booking, reorder)
- Load tests (how many concurrent scanner sessions?)
Create QA tasks in the calendar.

Result (abbreviated):

QA:
✅ Test Strategy — SmartInventory

Test Pyramid:
  ┌─────────────────────┐
  │   E2E Tests (10)    │ ← Cypress/Playwright
  ├─────────────────────┤
  │  Integration (35)   │ ← API tests with Testcontainers
  ├─────────────────────┤
  │   Unit Tests (120+) │ ← Module tests + property tests
  └─────────────────────┘

Critical Paths (E2E):
  1. Login → Dashboard → Inventory overview
  2. Open scanner → Scan barcode → Inventory updated
  3. Stock below minimum → Alert → Reorder triggered
  4. Supplier API timeout → Fallback → Manual notification

Load Test Targets:
  • 50 concurrent scanner sessions
  • 1,000 inventory queries/minute
  • 99.9% availability under load

QA tasks created: 8 tasks with priorities in the calendar.

Phase 9: DevOps / SRE Agent

Goal: Define CI/CD, deployment, and monitoring.

User:
@DevOps Define the CI/CD pipeline and deployment strategy for
SmartInventory. Consider:
- GitHub Actions as CI/CD
- Docker Compose for staging/production
- Prometheus + Grafana for monitoring
- Rollback strategy
Create DevOps tasks in the calendar.

Result (abbreviated):

DevOps:
🚀 CI/CD & Deployment Strategy

Pipeline Stages:
  ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐
  │ Lint │──►│Build │──►│ Test │──►│Stage │──►│ Prod │
  │      │   │Docker│   │Unit+ │   │Deploy│   │Deploy│
  │      │   │Image │   │Integr│   │ + E2E│   │Blue/ │
  │      │   │      │   │      │   │      │   │Green │
  └──────┘   └──────┘   └──────┘   └──────┘   └──────┘

Monitoring Alerts:
  • inventory_low_stock_total > threshold → PagerDuty
  • http_request_duration_p99 > 500ms → Slack
  • error_rate_5xx > 1% → PagerDuty

DevOps tasks created: 6 tasks in the calendar
  ☐ GitHub Actions pipeline (Priority: high, due Apr 7)
  ☐ Docker Compose production config (Priority: high, due Apr 14)
  ☐ Prometheus + Grafana setup (Priority: medium, due May 1)
  ☐ Define alerting rules (Priority: medium, due May 15)
  ☐ Blue/green deployment script (Priority: medium, due Jul 1)
  ☐ Disaster recovery runbook (Priority: low, due Sep 1)

Phase 10: Documentation / Knowledge Agent

Goal: Consolidate final documentation, ADRs, and calendar milestones.

User:
@Documentation Create the final project documentation for SmartInventory:
1. Summarize all architecture decisions as ADRs
2. Create an API documentation template
3. Write an onboarding document for new developers
4. Create final milestone calendar entries with review dates
5. Store all findings in the knowledge graph

Tool calls from the Documentation agent:

Tool Call: store_memory("SmartInventory ADR-001: Monorepo with service modules
  instead of microservices. Rationale: Team size (3-5 devs), reduced ops overhead,
  easier debugging. Trade-off: Later migration to microservices possible.")

Tool Call: store_memory("SmartInventory ADR-002: Redis Pub/Sub instead of Kafka.
  Rationale: Lower infrastructure complexity, sufficient for ~1,000 events/min.
  Trade-off: No replay capability, acceptable for V1.")

Tool Call: create_calendar_event({
    "title": "SmartInventory: M2 Design Review",
    "start": "2026-04-24T10:00:00Z",
    "end": "2026-04-24T12:00:00Z",
    "description": "Review: Data model, API spec, security audit.\n
      Participants: Architect, Security, DataAnalyst.\n
      Deliverables: Final schema, API OpenAPI spec, threat model.",
    "location": "Remote / Video Call"
})

Tool Call: create_calendar_event({
    "title": "SmartInventory: M4 Frontend Review",
    "start": "2026-06-19T10:00:00Z",
    "end": "2026-06-19T12:00:00Z",
    "description": "Review: Dashboard, PWA scanner, responsive design.\n
      Deliverables: Working prototype, accessibility audit.",
    "location": "Remote / Video Call"
})

Tool Call: create_task({
    "title": "DOC-001: API Documentation (OpenAPI 3.1)",
    "due_date": "2026-05-15",
    "priority": "medium",
    "description": "Complete OpenAPI spec for all endpoints.\n
      Must include: Schemas, examples, auth flows, error codes."
})

Results: Calendar Entries & Tasks

After completing all 10 phases, the following entries exist in the CalDAV server (Baikal):

Milestone Calendar (VEVENT)

Task Board (VTODO)

All tasks are created as VTODO entries in CalDAV, with:

• Priority: High (1–3) / Medium (4–6) / Low (7–9)
• Status: NEEDS-ACTION → IN-PROGRESS → COMPLETED
• Categories: backend, frontend, devops, security, qa, docs
• Dependencies: via RELATED-TO (parent ID) in the VTODO

Example VTODO:
BEGIN:VTODO
UID:inv-001-inventory-crud@smartinventory
SUMMARY:INV-001: Inventory CRUD API
DESCRIPTION:REST endpoints for inventory...
DUE;VALUE=DATE:20260508
PRIORITY:3
STATUS:NEEDS-ACTION
CATEGORIES:backend,api
RELATED-TO:inv-000-schema-migration
END:VTODO

Task Overview by Phase

April 2026
├── CW 14: Repository setup, CI/CD pipeline                   [DevOps]
├── CW 15: Schema migration, auth middleware                   [Dev, Security]
├── CW 16: Finalize API design                                 [Architect]
└── CW 17: Design Review (M2) ⭐                               [All]

May 2026
├── CW 18: Inventory CRUD API                                  [Dev]
├── CW 19: Product management, warehouse management            [Dev]
├── CW 20: Unit tests + integration tests (core)               [QA]
├── CW 21: API documentation, monitoring setup                 [Docs, DevOps]
└── CW 22: Core Backend Review (M3) ⭐                          [All]

June 2026
├── CW 23: Dashboard (SolidJS), responsive layout              [Dev]
├── CW 24: Barcode scanner PWA module                          [Dev]
├── CW 25: Frontend tests, accessibility audit                 [QA]
└── CW 26: Frontend Review (M4) ⭐                              [All]

July 2026
├── CW 27: Supplier gateway (cXML)                             [Dev]
├── CW 28: Alert engine (Redis Pub/Sub)                        [Dev]
├── CW 29: Integration tests, contract tests                   [QA]
└── CW 30: Integrations Review (M5) ⭐                          [All]

August 2026
├── CW 31-32: Load tests, performance optimization             [QA, DevOps]
├── CW 33: Blue/green deployment, staging                      [DevOps]
├── CW 34: Penetration test, security audit                    [Security]
└── CW 35: GDPR checklist, runbooks                            [Docs, Security]

September 2026
├── CW 36: Pre-Launch Review (M6) ⭐                             [All]
├── CW 37-38: Bug fixes, finalize documentation                [Dev, Docs]
├── CW 39: Go-Live preparation                                 [DevOps]
└── CW 40: Go-Live (M7) 🚀                                      [All]

Tips & Best Practices

1. Preserve Conversation Context

Keep all phases in the same conversation. PiSovereign merges messages from all agents — allowing @Architect to access the results of @Research without re-entering information.

# Bad: New conversation per agent
Chat 1: @Research → Results are lost
Chat 2: @Architect → has no context

# Good: Everything in one conversation
Chat 1: Upload → @Research → @DataAnalyst → @Architect → ...
         └── All agents see the entire history

2. Use Agentic Tasks for Complex Phases

For phases with multiple parallel subtasks (e.g., PM planning), Agentic Mode is more efficient than individual @Mentions because it:

• Automatically splits subtasks into parallel waves
• Respects dependencies
• Shows live progress via SSE
• Consolidates results from all sub-agents at the end

3. Actively Leverage the Knowledge Graph

The knowledge graph is the project’s “memory”. Use it deliberately:

• Intake: Upload documents → Entities are automatically extracted
• Query: Agents use recall_memory automatically for RAG context
• Store: Agents use store_memory for important decisions
• API: GET /v1/knowledge-graph/stats shows graph statistics

4. Agent Memory for Continuity

Each agent has its own long-term memory (AgentMemory) that persists across tasks. The PM agent “remembers” the last project status, and the Security agent remembers previously identified risks.

5. Token Optimization for Large Projects

When a conversation accumulates many messages, automatic token optimization kicks in:

• Rolling Summary: Old messages are condensed into summaries
• Progressive Tool Compression: Previously used tools are compressed
• Context Budget: System prompt, RAG, and history share the context window

Configurable via [token_optimization] in config.toml.

6. Approval Workflows for Critical Actions

Certain tools require user approval before execution (configured in [agentic] require_approval_for):

require_approval_for = ["send_email", "delete_contact", "execute_code"]

For these actions, the agent pauses and waits for your confirmation.

7. Version Agent Profiles

Every profile update creates a new version. Use version tags to mark proven configurations:

POST /v1/agent-profiles/{id}/versions/{version}/tag
{ "tag": "smartinventory-v1" }

This lets you reproduce agent configurations after a project concludes.

8. Maximize Parallel Agent Work

The orchestrator distributes independent subtasks across parallel waves. To make optimal use of this:

• Formulate tasks with clear dependencies
• Independent tasks (e.g., Security + Architect) can run in parallel
• max_concurrent_sub_agents = 3 is optimal for Raspberry Pi 5
• On desktop hardware: up to 5 parallel agents

Executing Tasks with GitHub Copilot

Once PiSovereign’s agents have created milestones and tasks, you can feed them to GitHub Copilot (in VS Code Agent Mode) for automated implementation. The recommended workflow uses the REST API to query tasks per milestone in dependency order, then generates a structured prompt file that Copilot can execute step by step.

API vs. Export — Which Approach Is Better?

Recommendation: Use the API query → Markdown export pipeline. Query tasks live via the API, then export a Markdown file that serves as Copilot’s work instruction. This combines freshness with offline usability.

Step 1: Query Milestones and Linked Tasks

PiSovereign links tasks to milestone events via the Event-Task Link API. Query milestones (calendar events) and their associated tasks:

# List all milestone events in a date range
curl -s http://localhost:3000/v1/calendar/events?start=2026-04-01&end=2026-09-30 \
  | jq '.events[] | {id, title, start, end, description}'

# Get tasks linked to a specific milestone
curl -s http://localhost:3000/v1/calendar/events/{event_id}/tasks \
  | jq '.tasks[] | {id, title, priority, status, due_date, description}'

# List all tasks, filtered by status and priority
curl -s "http://localhost:3000/v1/tasks?status=pending&priority=high" \
  | jq '.tasks[]'

# Get the dependency order for a task list
curl -s http://localhost:3000/v1/tasks/lists/{list_id}/order \
  | jq '.order'

Step 2: Export Tasks as Copilot Work Instructions

Use this shell script to generate a structured Markdown file from the API that GitHub Copilot can process as a task list:

#!/usr/bin/env bash
# export-tasks-for-copilot.sh
# Exports PiSovereign tasks per milestone as a Copilot-ready Markdown file.

set -euo pipefail

API="http://localhost:3000"
OUTPUT="copilot-tasks.md"
START_DATE="${1:-2026-04-01}"
END_DATE="${2:-2026-09-30}"

echo "# Project Tasks for GitHub Copilot" > "$OUTPUT"
echo "" >> "$OUTPUT"
echo "> Auto-generated from PiSovereign on $(date -Iseconds)" >> "$OUTPUT"
echo "> Execute tasks in the listed order per milestone." >> "$OUTPUT"
echo "" >> "$OUTPUT"

# Fetch milestones sorted by date
MILESTONES=$(curl -s "${API}/v1/calendar/events?start=${START_DATE}&end=${END_DATE}")

echo "$MILESTONES" | jq -r '.events | sort_by(.start)[] | @base64' | while read -r EVENT; do
  TITLE=$(echo "$EVENT" | base64 -d | jq -r '.title')
  EVENT_ID=$(echo "$EVENT" | base64 -d | jq -r '.id')
  DATE=$(echo "$EVENT" | base64 -d | jq -r '.start[:10]')
  DESC=$(echo "$EVENT" | base64 -d | jq -r '.description // ""')

  echo "## ${TITLE}" >> "$OUTPUT"
  echo "**Deadline**: ${DATE}" >> "$OUTPUT"
  [ -n "$DESC" ] && echo "" >> "$OUTPUT" && echo "${DESC}" >> "$OUTPUT"
  echo "" >> "$OUTPUT"

  # Fetch linked tasks for this milestone
  TASKS=$(curl -s "${API}/v1/calendar/events/${EVENT_ID}/tasks")
  TASK_COUNT=$(echo "$TASKS" | jq '.tasks | length')

  if [ "$TASK_COUNT" -gt 0 ]; then
    echo "### Tasks (ordered by priority & dependencies)" >> "$OUTPUT"
    echo "" >> "$OUTPUT"

    echo "$TASKS" | jq -r '.tasks | sort_by(.priority == "low", .priority == "medium", .priority == "high" | not)[] | @base64' | while read -r TASK; do
      T_TITLE=$(echo "$TASK" | base64 -d | jq -r '.title')
      T_STATUS=$(echo "$TASK" | base64 -d | jq -r '.status')
      T_PRIORITY=$(echo "$TASK" | base64 -d | jq -r '.priority')
      T_DUE=$(echo "$TASK" | base64 -d | jq -r '.due_date // "no date"')
      T_DESC=$(echo "$TASK" | base64 -d | jq -r '.description // ""')
      T_ID=$(echo "$TASK" | base64 -d | jq -r '.id')

      if [ "$T_STATUS" = "completed" ]; then
        CHECKBOX="[x]"
      else
        CHECKBOX="[ ]"
      fi

      echo "- ${CHECKBOX} **${T_TITLE}** (Priority: ${T_PRIORITY}, Due: ${T_DUE})" >> "$OUTPUT"
      if [ -n "$T_DESC" ]; then
        echo "  > ${T_DESC}" >> "$OUTPUT"
      fi
      echo "  Task-ID: \`${T_ID}\`" >> "$OUTPUT"
      echo "" >> "$OUTPUT"
    done
  else
    echo "_No tasks linked to this milestone yet._" >> "$OUTPUT"
    echo "" >> "$OUTPUT"
  fi

  echo "---" >> "$OUTPUT"
  echo "" >> "$OUTPUT"
done

echo "Export complete: $OUTPUT"

Make it executable and run it:

chmod +x export-tasks-for-copilot.sh
./export-tasks-for-copilot.sh 2026-04-01 2026-09-30

Step 3: Use the Exported File with GitHub Copilot

The generated copilot-tasks.md file can be used in multiple ways:

Option A: Attach as Context in Copilot Chat (Recommended)

Open VS Code, start Copilot Chat in Agent Mode, and attach the file:

User:
#file:copilot-tasks.md

Work through the tasks in this file in order. Start with the first
uncompleted task under Milestone M1. For each task:
1. Implement the code changes described
2. Write tests (target 90%+ coverage)
3. Run `cargo test` to verify
4. Mark the task as done when complete
5. Move to the next task

Ask me before making architectural decisions not covered by the task.

Option B: Use as Custom Instructions (.github/copilot-instructions.md)

For long-running projects, place the task list in your repo:

mkdir -p .github
cp copilot-tasks.md .github/copilot-instructions.md

Copilot will automatically use this as context for every interaction.

Option C: Milestone-by-Milestone with Focused Prompts

For finer control, query tasks for a single milestone and prompt Copilot with just that scope:

# Export only tasks for the next milestone
curl -s http://localhost:3000/v1/calendar/events/{m3_event_id}/tasks \
  | jq -r '.tasks[] | "- [ ] \(.title)\n  > \(.description)\n"'

Then in Copilot Chat:

User:
Here are the tasks for Milestone M3 (Core Backend, due May 22):

- [ ] INV-001: Inventory CRUD API
  > REST endpoints: POST, GET, PATCH for /api/v1/inventory
  > Acceptance: input validation, audit log, 90% test coverage

- [ ] INV-003: Auth Middleware (OAuth 2.0 + RBAC)
  > JWT validation, role extraction, 3 roles: admin, buyer, warehouse_worker

Implement these in order. Start with INV-001.

Step 4: Mark Tasks Complete via API

After Copilot finishes a task, mark it as completed in PiSovereign so the dashboard and other agents stay in sync:

# Mark a single task as completed
curl -X POST http://localhost:3000/v1/tasks/{task_id}/complete

# Or update the status to in-progress first
curl -X PUT http://localhost:3000/v1/tasks/{task_id} \
  -H 'Content-Type: application/json' \
  -d '{"status": "in_progress"}'

This can be scripted into a post-commit hook or CI step for automatic tracking.

Recommended Workflow Summary

┌──────────────────────────────────────────────────────────────────┐
│                    PiSovereign (Planning)                       │
│  Agents create milestones + tasks in CalDAV                     │
└──────────────┬───────────────────────────────────────────────────┘
               │ GET /v1/calendar/events/.../tasks
               ▼
┌──────────────────────────────────────────────────────────────────┐
│              export-tasks-for-copilot.sh                        │
│  Generates copilot-tasks.md (ordered by milestone & priority)   │
└──────────────┬───────────────────────────────────────────────────┘
               │ Attach as context
               ▼
┌──────────────────────────────────────────────────────────────────┐
│              GitHub Copilot (Agent Mode)                        │
│  Executes tasks: implement → test → verify → next              │
└──────────────┬───────────────────────────────────────────────────┘
               │ POST /v1/tasks/{id}/complete
               ▼
┌──────────────────────────────────────────────────────────────────┐
│              PiSovereign (Tracking)                             │
│  Dashboard shows progress, agents see completed work            │
└──────────────────────────────────────────────────────────────────┘

Summary: With PiSovereign’s multi-agent system, a complete software project is systematically planned by 9 specialized agents. The result is concrete, prioritized tasks and milestones as calendar entries — ready for execution by GitHub Copilot or any other AI coding assistant.

Multi-Agent Family Management with PiSovereign

How-To Guide: Organize your entire family life — from weekly schedules and meal planning to budgeting, school events, and vacation planning — using 7 specialized AI agents.

Table of Contents

1. Overview
2. Prerequisites
3. Creating the Agent Team
4. Example Project: FamilyHub
5. Phase-by-Phase Walkthrough
   • Phase 1: Family Onboarding
   • Phase 2: Weekly Planning
   • Phase 3: Meal Planning
   • Phase 4: Budget Management
   • Phase 5: School & Education
   • Phase 6: Health & Wellness
   • Phase 7: Home & Travel
6. Results: Calendar Entries & Tasks
7. Tips & Best Practices for Families

Overview

Running a household with children is a complex coordination challenge. School schedules, doctor’s appointments, grocery shopping, meal planning, household chores, budgeting, and vacation planning all compete for attention — often managed across sticky notes, WhatsApp groups, and separate apps.

PiSovereign’s multi-agent system turns your private AI assistant into a family command center. Seven specialized agents collaborate within a single conversation, each responsible for a distinct area of family life:

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                       FAMILY (Chat UI / Signal)                    │
│  "What's for dinner?", "@MealPlanner plan next week",             │
│  "@BudgetCoach how are we doing this month?"                      │
└──────────────┬──────────────────────────────────────┬──────────────┘
               │                                      │
               ▼                                      ▼
┌──────────────────────────┐         ┌──────────────────────────────┐
│   Knowledge Graph        │         │    Agentic Orchestrator      │
│  ┌────────────────────┐  │         │  ┌────────────────────────┐  │
│  │ Family Profiles     │  │         │  │ 1. Understand Request  │  │
│  │ Dietary Preferences │  │         │  │ 2. Route to Agent(s)   │  │
│  │ School Schedules    │  │         │  │ 3. Parallel Execution  │  │
│  │ Medical History     │  │         │  │ 4. Calendar + Tasks    │  │
│  │ Budget Data         │  │         │  │ 5. Result Synthesis    │  │
│  └────────────────────┘  │         │  └──────────┬─────────────┘  │
└──────────────────────────┘         │             │                │
                                     │  Agent Team:                 │
                                     │  ┌──────┐ ┌──────┐ ┌──────┐ │
                                     │  │Family│ │Meal  │ │Budget│ │
                                     │  │Plannr│ │Plannr│ │Coach │ │
                                     │  └──┬───┘ └──┬───┘ └──┬───┘ │
                                     │  ┌──────┐ ┌──────┐ ┌──────┐ │
                                     │  │School│ │Health│ │Home  │ │
                                     │  │Suprt │ │Keepr │ │Mngr  │ │
                                     │  └──┬───┘ └──┬───┘ └──┬───┘ │
                                     │  ┌──────┐    │        │     │
                                     │  │Travel│    ▼        ▼     │
                                     │  │Plannr│  ┌──────────────┐ │
                                     │  └──┬───┘  │ Tool Calls   │ │
                                     │     │      │ • calendar   │ │
                                     │     │      │ • tasks      │ │
                                     │     │      │ • search_web │ │
                                     │     │      │ • memory     │ │
                                     │     │      └──────┬───────┘ │
                                     └─────┼─────────────┼─────────┘
                                           │             │
                                           ▼             ▼
                                     ┌──────────────────────────────┐
                                     │   CalDAV Server (Baikal)     │
                                     │  • VEVENT (Appointments)     │
                                     │  • VTODO  (Tasks, Chores)    │
                                     └──────────────────────────────┘

The 7 Family Agents

How Agents Collaborate

Phase 1: Family Onboarding (profiles, preferences, schedules)
    │
    ▼
Phase 2: FamilyPlanner ──► Weekly schedule with conflict resolution
    │
    ├──────────────────┬──────────────────┐
    ▼                  ▼                  ▼
Phase 3: MealPlanner  Phase 4: Budget   Phase 5: SchoolSupport
    │                  │                  │
    └──────┬───────────┘                  │
           │                              │
           ▼                              │
Phase 6: HealthKeeper ◄──────────────────┘
    │
    ▼
Phase 7: HomeManager + TravelPlanner ──► Chores & vacation plan

Prerequisites

1. PiSovereign Docker Setup

PiSovereign must be running with the CalDAV profile enabled for calendar events and task management:

# Start core + CalDAV
just docker-up -- --profile caldav

# Or start everything (incl. monitoring):
just docker-up-all

2. Configuration (config.toml)

The following sections must be enabled:

# ─── Agentic Mode ────────────────────────────────────────────
[agentic]
enabled = true
max_concurrent_sub_agents = 3          # Pi 5: 2-3, Desktop: 3-5
max_sub_agents_per_task = 7
total_timeout_minutes = 10
sub_agent_timeout_minutes = 5
require_approval_for = ["send_email", "delete_contact", "execute_code"]

# ─── Tool Calling (ReAct Loop) ───────────────────────────────
[agent.tool_calling]
enabled = true
max_iterations = 5
parallel_tool_execution = true

# ─── CalDAV Server ───────────────────────────────────────────
[caldav]
enabled = true
base_url = "http://baikal:80/dav.php"
# Credentials via Vault: just docker-vault-set-caldav USERNAME PASSWORD

# ─── Token Optimization (recommended) ───────────────────────
[token_optimization]
enabled = true
max_profile_prompt_tokens = 300        # Agent prompt budget

3. Vault Secrets

# Set CalDAV credentials
just docker-vault-set-caldav admin mysecurepassword

4. Verify Initial Setup

Open the web UI at http://localhost:3000 and navigate to:

• Team (sidebar) → Manage agent profiles
• Chat (sidebar) → Conversations with @mentions
• Agentic (sidebar) → Launch complex multi-agent tasks

Creating the Agent Team

Create all 7 agents via the web UI (Team → + New Agent) or through the API. Below are the complete profile definitions for each agent.

1. FamilyPlanner

POST /v1/agent-profiles
{
  "name": "FamilyPlanner",
  "role": "Weekly and monthly family schedule coordinator. Detects conflicts between family members' events, creates the weekly plan, and sends reminders for upcoming commitments.",
  "emoji": "📅",
  "skills": [
    "schedule_coordination", "conflict_detection", "weekly_planning",
    "monthly_overview", "reminder_management", "event_prioritization",
    "time_blocking", "calendar_management", "family_communication",
    "routine_optimization"
  ],
  "style": {
    "tone": "warm and organized",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a family schedule coordinator. Your job is to organize the weekly and monthly calendar for the entire family. Use create_calendar_event to schedule appointments and activities. Use create_task for to-dos. Detect scheduling conflicts between family members and suggest alternatives. Always consider commute times and downtime between activities. Prioritize family well-being over productivity.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "medium"
}

2. MealPlanner

POST /v1/agent-profiles
{
  "name": "MealPlanner",
  "role": "Meal planning specialist. Creates weekly meal plans considering allergies, dietary preferences, nutritional balance, and budget. Generates organized grocery lists.",
  "emoji": "🍽️",
  "skills": [
    "meal_planning", "grocery_list_generation", "nutrition_tracking",
    "allergy_awareness", "budget_meal_optimization", "recipe_suggestion",
    "seasonal_cooking", "batch_cooking_planning", "leftover_management",
    "dietary_balance"
  ],
  "style": {
    "tone": "friendly and practical",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a family meal planner. Create weekly meal plans that respect all dietary restrictions, allergies, and preferences stored in the knowledge graph (recall_memory). Balance nutrition across the week: protein, vegetables, carbohydrates. Consider the family schedule — quick meals on busy days, elaborate meals on weekends. Generate consolidated grocery lists grouped by store section. Use create_task for grocery shopping tasks and create_calendar_event for special meal events (birthdays, guests).",
  "inference_overrides": {
    "temperature": 0.6
  },
  "autonomy_level": "medium"
}

3. BudgetCoach

POST /v1/agent-profiles
{
  "name": "BudgetCoach",
  "role": "Family finance coach. Tracks expenses, monitors the monthly budget, manages savings goals, analyzes spending patterns, and provides financial guidance.",
  "emoji": "💰",
  "skills": [
    "budget_tracking", "expense_categorization", "savings_goal_management",
    "spending_analysis", "recurring_expense_monitoring", "financial_planning",
    "cost_optimization", "insurance_review", "subscription_management",
    "emergency_fund_planning"
  ],
  "style": {
    "tone": "encouraging and clear",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a family budget coach. Track monthly expenses, categorize spending, and compare against the family budget stored in the knowledge graph. Identify savings opportunities and monitor recurring costs (subscriptions, insurance, utilities). Create monthly budget review calendar events. Alert when spending in any category exceeds 80% of the monthly allocation. Be supportive, not judgmental — focus on progress toward savings goals. Use create_task for financial action items and store_memory for budget snapshots.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

4. SchoolSupport

POST /v1/agent-profiles
{
  "name": "SchoolSupport",
  "role": "School and education tracker. Monitors homework deadlines, exam schedules, parent-teacher meetings, and extracurricular activities for all children in the family.",
  "emoji": "📚",
  "skills": [
    "homework_tracking", "exam_scheduling", "study_plan_creation",
    "parent_teacher_coordination", "extracurricular_management",
    "grade_monitoring", "school_event_tracking", "learning_resource_suggestion",
    "school_supply_management", "report_card_tracking"
  ],
  "style": {
    "tone": "supportive and motivating",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a school support assistant. Track homework deadlines, exam schedules, and school events for every child in the family. Use recall_memory to retrieve each child's school schedule and subjects. Create study plan calendar events before exams with appropriate preparation time. Track parent-teacher meetings and school holidays. Use create_calendar_event for all school-related dates and create_task for homework and study tasks. Celebrate achievements and provide encouragement.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "medium"
}

5. HealthKeeper

POST /v1/agent-profiles
{
  "name": "HealthKeeper",
  "role": "Family health coordinator. Manages medical appointments, vaccination schedules, preventive care checkups, medication reminders, and health records for all family members.",
  "emoji": "❤️‍🩹",
  "skills": [
    "appointment_scheduling", "vaccination_tracking", "preventive_care_planning",
    "medication_reminders", "health_record_management", "dental_checkup_scheduling",
    "allergy_documentation", "insurance_claim_tracking", "specialist_referral_management",
    "wellness_monitoring"
  ],
  "style": {
    "tone": "caring and precise",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a family health coordinator. Manage medical appointments, vaccination schedules, and preventive care for every family member. Use recall_memory to access health profiles (allergies, chronic conditions, last checkup dates). Schedule routine checkups at age-appropriate intervals: dental every 6 months, pediatric annually, vision checks, etc. Send medication reminders via create_task. Use create_calendar_event for all medical appointments. Flag overdue vaccinations or checkups. Always remind: you are not a medical professional — consult a doctor for medical advice.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "low"
}

6. HomeManager

POST /v1/agent-profiles
{
  "name": "HomeManager",
  "role": "Household management specialist. Distributes chores fairly among family members, schedules regular maintenance (HVAC, appliances), and coordinates repairs and home improvement projects.",
  "emoji": "🏠",
  "skills": [
    "chore_distribution", "maintenance_scheduling", "repair_coordination",
    "seasonal_maintenance_planning", "appliance_lifecycle_tracking",
    "contractor_management", "home_improvement_planning",
    "cleaning_schedule_creation", "garden_maintenance", "energy_optimization"
  ],
  "style": {
    "tone": "fair and practical",
    "verbosity": "terse",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a household manager. Distribute chores fairly among family members based on age and ability. Create rotating chore schedules with create_task. Schedule seasonal maintenance: HVAC filter changes, gutter cleaning, smoke detector batteries, garden work. Track appliance warranties and service dates. Use create_calendar_event for maintenance appointments and create_task for daily/weekly chores. When assigning chores to children, make them age-appropriate and teach responsibility gradually.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "medium"
}

7. TravelPlanner

POST /v1/agent-profiles
{
  "name": "TravelPlanner",
  "role": "Family vacation and trip planner. Researches family-friendly destinations, creates packing lists, builds day-by-day itineraries, and manages travel logistics including budget coordination.",
  "emoji": "✈️",
  "skills": [
    "destination_research", "itinerary_creation", "packing_list_generation",
    "budget_travel_planning", "family_friendly_activity_search",
    "accommodation_comparison", "transportation_planning",
    "travel_document_checklist", "weather_research", "local_cuisine_research"
  ],
  "style": {
    "tone": "enthusiastic and thorough",
    "verbosity": "verbose",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a family travel planner. Research family-friendly destinations using search_web. Consider children's ages, interests, and the family budget (recall_memory for budget data). Create detailed day-by-day itineraries with a mix of activities, rest time, and meal breaks. Generate age-appropriate packing lists. Use create_calendar_event for travel dates, activity bookings, and flight/train departures. Use create_task for pre-trip preparations (passport check, pet sitter, mail hold). Coordinate with BudgetCoach for travel spending limits.",
  "inference_overrides": {
    "temperature": 0.6
  },
  "autonomy_level": "medium"
}

Tip: All agents can also be created visually via the web UI under Team — emoji, role, skills, and system prompt can be configured conveniently through the form interface.

Example Project: FamilyHub

As a running example throughout this guide, we use a fictitious family scenario:

Family Profile

The Berger Family consists of four members:

• Thomas (42) — Software engineer, works from home Mon–Fri
• Sarah (39) — Part-time teacher (Mon, Wed, Fri mornings)
• Lena (14) — 9th grade, soccer practice Tue/Thu, piano Fri
• Max (8) — 3rd grade, swimming Wed, playdate group Sat mornings

Dietary notes: Max has a mild nut allergy. Sarah is vegetarian on weekdays. Family dinner together at 6:30 PM is a priority.

Budget: Monthly household budget of €4,200 (after rent/mortgage). Savings goal: €3,000 for summer vacation by July 2026.

Upcoming events: Lena’s parent-teacher conference (Apr 15), Max’s swimming competition (May 3), family vacation booked for Aug 1–14 (destination TBD).

Sample Documents for Onboarding

Phase-by-Phase Walkthrough

Phase 1: Family Onboarding — Initial Setup

Goal: Load family profiles, preferences, and schedules into the knowledge graph so that every agent has access to the family context.

Step 1: Create a New Conversation

Open the Chat in the web UI and start a new conversation:

User:
I want to set up PiSovereign as our family command center. Here is our
family profile:

Family: Berger
Members:
- Thomas (42), software engineer, works from home Mon-Fri
- Sarah (39), part-time teacher (Mon/Wed/Fri mornings)
- Lena (14), 9th grade, soccer Tue/Thu 4-6 PM, piano Fri 3-4 PM
- Max (8), 3rd grade, swimming Wed 3-4:30 PM, playdate Sat 10 AM

Dietary: Max has nut allergy. Sarah vegetarian on weekdays.
Family dinner: 6:30 PM every day.
Monthly budget: €4,200 (after rent). Savings goal: €3,000 for summer
vacation by July 2026.

Step 2: Upload Family Documents

User:
[Drag & Drop: family-profiles.md, weekly-schedule.csv, budget-overview.md,
 health-records.md, school-calendar.md]

Please analyze these documents and integrate them into the knowledge graph
so all our family agents can access the information.

What happens behind the scenes:

1. FileIngestionService processes each file
2. Entity Extraction identifies: FamilyMember, Activity, School, DietaryRestriction, BudgetCategory, HealthRecord, etc.
3. Knowledge Graph stores entities with relationships:
   • Lena —[attends]→ Soccer Practice
   • Max —[has_allergy]→ Nuts
   • Sarah —[works_at]→ School (MWF mornings)
   • BudgetCategory:Groceries —[has_limit]→ €650/month
4. pgvector embeddings enable semantic search across all family data

Expected response:

PiSovereign:
✅ 5 files processed:
  • family-profiles.md — 4 family members, 6 activities
  • weekly-schedule.csv — 18 recurring events mapped
  • budget-overview.md — 12 budget categories, savings goal tracked
  • health-records.md — 4 health profiles, vaccinations current
  • school-calendar.md — 24 school events for 2026

Knowledge graph updated: 52 nodes, 41 edges.
Your family agents are ready! Use @FamilyPlanner to create the weekly schedule.

Phase 2: Weekly Planning — FamilyPlanner

Goal: Create a coordinated weekly schedule that respects everyone’s commitments and avoids conflicts.

User:
@FamilyPlanner Create our family schedule for the week of April 6-12, 2026.
Consider:
- Thomas works from home 9-5, but has a dentist appointment Wed at 2 PM
- Sarah teaches Mon/Wed/Fri 8-12
- Lena has a math test on Thursday
- Max needs to bring cupcakes for school on Friday
- We want a family game night on Saturday
Make sure there are no conflicts and everyone knows their commitments.

What the FamilyPlanner agent does (tool calls):

Tool Call 1: recall_memory("Berger family weekly schedule activities")
→ Knowledge Graph: all recurring activities for each family member

Tool Call 2: create_calendar_event({
    "title": "🔵 Thomas: Dentist Appointment",
    "start": "2026-04-08T14:00:00Z",
    "end": "2026-04-08T15:00:00Z",
    "description": "Dr. Müller, Hauptstraße 12. Thomas unavailable 13:45-15:15."
})

Tool Call 3: create_calendar_event({
    "title": "📚 Lena: Math Test Preparation",
    "start": "2026-04-08T17:00:00Z",
    "end": "2026-04-08T18:30:00Z",
    "description": "Study session for Thursday math test. No soccer today — use the time for focused study."
})

Tool Call 4: create_calendar_event({
    "title": "🎲 Family Game Night",
    "start": "2026-04-11T19:00:00Z",
    "end": "2026-04-11T21:00:00Z",
    "description": "Saturday family game night! Suggestions: Settlers of Catan, Ticket to Ride, or Codenames."
})

Tool Call 5: create_task({
    "title": "🧁 Bake cupcakes for Max's school",
    "due_date": "2026-04-09",
    "priority": "high",
    "description": "Max needs cupcakes for Friday. NUT-FREE! Bake Thursday evening. Assign: Sarah + Max (baking project together)."
})

Tool Call 6: create_calendar_event({
    "title": "⚠️ CONFLICT: Sarah teaching + Max swimming pickup",
    "start": "2026-04-08T14:45:00Z",
    "end": "2026-04-08T15:00:00Z",
    "description": "Sarah teaches until 12, but Thomas has dentist at 2 PM. Can Thomas do pickup at 15:00 after dentist? Or arrange carpool?"
})

Result — Weekly Overview:

FamilyPlanner:
📅 Week of April 6-12, 2026 — Berger Family

Monday:
  08:00-12:00  Sarah: Teaching
  09:00-17:00  Thomas: Remote work
  08:00-13:30  Lena: School
  08:00-12:30  Max: School
  18:30        🍽️ Family dinner

Tuesday:
  09:00-17:00  Thomas: Remote work
  08:00-15:30  Lena: School
  16:00-18:00  Lena: ⚽ Soccer practice
  08:00-12:30  Max: School
  18:30        🍽️ Family dinner

Wednesday:
  08:00-12:00  Sarah: Teaching
  09:00-13:45  Thomas: Remote work (shortened)
  14:00-15:00  Thomas: 🦷 Dentist
  15:00-17:00  Thomas: Resume work
  15:00-16:30  Max: 🏊 Swimming
  17:00-18:30  Lena: 📚 Math test study session
  18:30        🍽️ Family dinner

Thursday:
  08:00-15:30  Lena: School (📝 MATH TEST)
  16:00-18:00  Lena: ⚽ Soccer practice
  19:00-20:00  Sarah + Max: 🧁 Bake cupcakes (nut-free!)
  18:30        🍽️ Family dinner (slightly earlier baking start)

Friday:
  08:00-12:00  Sarah: Teaching
  08:00-13:30  Lena: School → 15:00-16:00 🎹 Piano
  08:00-12:30  Max: School (bring cupcakes!)
  18:30        🍽️ Family dinner

Saturday:
  10:00-12:00  Max: 👫 Playdate group
  Free afternoon for family
  19:00-21:00  🎲 Family Game Night

Sunday:
  Free day — relax, prep for next week

⚠️ 1 potential conflict flagged:
  Wed: Thomas dentist overlaps with Max swimming pickup.
  Suggestion: Thomas can still do pickup at 15:00 (dentist ends ~15:00).
  Backup: Ask neighbor for carpool.

Phase 3: Meal Planning — MealPlanner

Goal: Create a weekly meal plan respecting allergies, preferences, and schedule.

User:
@MealPlanner Create a meal plan for the week of April 6-12.
Remember:
- Max has a nut allergy
- Sarah is vegetarian on weekdays
- Quick meals on school/work days
- Something special for Saturday game night (finger food!)
- Budget: max €120 for groceries this week

What the MealPlanner agent does:

Tool Call 1: recall_memory("Berger family dietary restrictions allergies preferences")
→ Max: nut allergy. Sarah: weekday vegetarian. Family dinner 18:30.

Tool Call 2: search_web("child-friendly nut-free dinner recipes quick 30 minutes")
→ Recipe suggestions retrieved

Tool Call 3: create_task({
    "title": "🛒 Weekly grocery shopping",
    "due_date": "2026-04-05",
    "priority": "high",
    "description": "Grocery list for week April 6-12:\n
      PRODUCE: Potatoes 2kg, carrots 1kg, zucchini 3, bell peppers 4,
      tomatoes 1kg, lettuce 2 heads, bananas 1 bunch, apples 6,
      lemons 3, fresh herbs (basil, parsley)\n
      DAIRY: Milk 3L, yogurt 1kg, cheese (Gouda 400g, mozzarella 2x),
      butter, eggs 10\n
      PROTEIN: Chicken breast 800g, ground beef 500g, salmon 400g,
      tofu 400g\n
      PANTRY: Pasta 1kg, rice 1kg, canned tomatoes 3x, olive oil,
      tortilla wraps 8\n
      BAKERY: Whole grain bread, pizza dough 2x\n
      SNACKS: Fruit bars (nut-free!), popcorn kernels\n
      ⚠️ CHECK ALL LABELS FOR NUTS\n
      Estimated: ~€105"
})

Tool Call 4: store_memory("Berger family meal plan CW15 2026: Mon pasta,
  Tue chicken bowls, Wed veggie pizza, Thu wraps, Fri salmon,
  Sat finger food, Sun brunch. Budget: €105 estimated.")

Result — Weekly Meal Plan:

MealPlanner:
🍽️ Meal Plan — Week of April 6-12

Monday:    🍝 One-pot vegetable pasta (Sarah: veggie ✅, 25 min)
           Lunch boxes: Wraps with hummus for kids

Tuesday:   🥗 Chicken teriyaki rice bowls (nut-free sauce!)
           Quick prep: 30 min, leftovers for Thomas's lunch Wed

Wednesday: 🍕 Homemade veggie pizza night (Sarah: veggie ✅)
           Pizza dough prep: kids can help shape their own
           Note: Quick dinner needed — Max has swimming until 16:30

Thursday:  🌮 Build-your-own taco/wraps (ground beef + veggie option)
           Sarah + Max bake cupcakes after dinner (nut-free recipe!)

Friday:    🐟 Oven-baked salmon with roasted potatoes & salad
           Thomas cooks — Sarah arrives late from school

Saturday:  🎉 Game Night Finger Food Platter:
           Mini pizzas, veggie sticks + dips, popcorn, fruit skewers
           (All nut-free, easy to eat while gaming!)

Sunday:    🥞 Late family brunch: Pancakes, fruit, yogurt
           Light dinner: Soup & bread from leftovers

📊 Estimated grocery cost: €105 (under €120 budget ✅)
🛒 Shopping task created for Sunday, April 5
⚠️ All recipes verified nut-free for Max

Phase 4: Budget Management — BudgetCoach

Goal: Monthly budget review, savings progress, spending insights.

User:
@BudgetCoach Give us the April budget overview. We spent €380 on groceries
in March (over the €350 target). Also, I noticed we're paying for 3 streaming
services — can you check if we really need all of them? How is our vacation
savings goal progressing?

What the BudgetCoach agent does:

Tool Call 1: recall_memory("Berger family budget categories savings goals 2026")
→ Monthly budget: €4,200. Savings goal: €3,000 by July.

Tool Call 2: store_memory("March 2026 grocery spending: €380 (budget €350).
  Overspend: €30. Cause: Easter shopping + birthday party supplies.
  Action: Reduce April target to €340 to compensate.")

Tool Call 3: search_web("streaming subscription comparison Germany 2026 family plan")
→ Netflix Premium €17.99, Disney+ €11.99, Amazon Prime €8.99

Tool Call 4: create_calendar_event({
    "title": "💰 Monthly Budget Review — May 1",
    "start": "2026-05-01T20:00:00Z",
    "end": "2026-05-01T20:30:00Z",
    "description": "Review April spending. Check savings progress. Thomas + Sarah."
})

Tool Call 5: create_task({
    "title": "💳 Review streaming subscriptions",
    "due_date": "2026-04-10",
    "priority": "medium",
    "description": "Currently paying: Netflix €17.99, Disney+ €11.99, Amazon Prime €8.99 = €38.97/month.\nSuggestion: Pause Disney+ for 2 months (no new content the kids want). Save: €23.98.\nDecision needed by: April 10."
})

Result:

BudgetCoach:
💰 April Budget Overview — Berger Family

Monthly Budget: €4,200
┌──────────────────┬──────────┬──────────┬─────────┐
│ Category          │ Budget   │ Mar Spent│ Status  │
├──────────────────┼──────────┼──────────┼─────────┤
│ Groceries        │ €350     │ €380     │ ⚠️ +€30 │
│ Transport        │ €200     │ €185     │ ✅      │
│ Kids' Activities │ €180     │ €180     │ ✅      │
│ Utilities        │ €250     │ €242     │ ✅      │
│ Insurance        │ €320     │ €320     │ ✅      │
│ Clothing         │ €150     │ €95      │ ✅      │
│ Entertainment    │ €100     │ €112     │ ⚠️ +€12 │
│ Dining out       │ €120     │ €88      │ ✅      │
│ Subscriptions    │ €80      │ €78      │ ✅      │
│ Misc / Buffer    │ €200     │ €165     │ ✅      │
│ ─────────────── │ ──────── │ ──────── │ ─────── │
│ TOTAL            │ €1,950   │ €1,845   │ ✅      │
│ Savings          │ €500     │ €505     │ ✅      │
│ Vacation fund    │ (incl.)  │ €505     │ 📊      │
└──────────────────┴──────────┴──────────┴─────────┘

🎯 Vacation Savings Progress:
  Target: €3,000 by July 2026
  Saved so far: €1,515 (Jan: €500, Feb: €510, Mar: €505)
  Remaining: €1,485 in 3 months = €495/month
  Status: ✅ On track!

💡 Streaming Subscription Analysis:
  Current: Netflix (€17.99) + Disney+ (€11.99) + Amazon Prime (€8.99) = €38.97/mo
  Recommendation: Pause Disney+ until summer (save €23.98 over 2 months)
  Task created — decide by April 10.

📅 Monthly budget review scheduled for May 1 at 20:00.

Phase 5: School & Education — SchoolSupport

Goal: Track school events, homework, and exam preparation for both children.

User:
@SchoolSupport Review the school calendar for April 2026. Lena has her
math test Thursday and a parent-teacher conference on April 15. Max has a
reading project due April 18. Create study plans and reminders.

What the SchoolSupport agent does:

Tool Call 1: recall_memory("Lena school subjects schedule exams 2026")
→ Lena: 9th grade, subjects include math, German, English, biology

Tool Call 2: recall_memory("Max school schedule reading project 2026")
→ Max: 3rd grade, reading project assigned March 25

Tool Call 3: create_calendar_event({
    "title": "📝 Lena: Math Test",
    "start": "2026-04-09T08:00:00Z",
    "end": "2026-04-09T09:30:00Z",
    "description": "Math test — algebra and geometry. Study sessions scheduled for Tue+Wed."
})

Tool Call 4: create_calendar_event({
    "title": "📖 Lena: Math Study Session 1",
    "start": "2026-04-07T16:00:00Z",
    "end": "2026-04-07T17:30:00Z",
    "description": "Focus: Algebra exercises (chapters 5-6). Quiet workspace, no phone."
})

Tool Call 5: create_calendar_event({
    "title": "📖 Lena: Math Study Session 2",
    "start": "2026-04-08T17:00:00Z",
    "end": "2026-04-08T18:30:00Z",
    "description": "Focus: Geometry (chapters 7-8). Practice with mock exam questions."
})

Tool Call 6: create_calendar_event({
    "title": "👨‍👩‍👧 Parent-Teacher Conference — Lena",
    "start": "2026-04-15T17:00:00Z",
    "end": "2026-04-15T18:00:00Z",
    "description": "Gymnasium Weststadt. Discuss: Math performance, social behavior, class trip. Both parents attend."
})

Tool Call 7: create_task({
    "title": "📚 Max: Reading Project — Book Report",
    "due_date": "2026-04-18",
    "priority": "high",
    "description": "Max's reading project due April 18.\nBook: 'Der kleine Drache Kokosnuss'\nTasks:\n1. ☐ Finish reading (by Apr 10)\n2. ☐ Draw book cover illustration (by Apr 14)\n3. ☐ Write 5-sentence summary (by Apr 16)\n4. ☐ Practice presentation (Apr 17)\nParent support: Sarah helps with summary, Thomas with presentation practice."
})

Result:

SchoolSupport:
📚 School Overview — April 2026

LENA (9th Grade):
  📝 Apr 9: Math Test (algebra + geometry)
     → Study session 1: Mon Apr 7, 16:00-17:30 (algebra)
     → Study session 2: Tue Apr 8, 17:00-18:30 (geometry)
     → Tip: No soccer on study days — use that time wisely!
  👨‍👩‍👧 Apr 15: Parent-Teacher Conference, 17:00
     → Gymnasium Weststadt
     → Discussion points prepared: math grades, class trip
  📝 Apr 23: English vocabulary test (scheduled, study plan coming)

MAX (3rd Grade):
  📖 Apr 18: Reading Project Due
     → "Der kleine Drache Kokosnuss"
     → Subtasks created with milestones:
       ☐ Finish reading by Apr 10
       ☐ Book cover drawing by Apr 14
       ☐ 5-sentence summary by Apr 16 (Sarah helps)
       ☐ Presentation practice Apr 17 (Thomas helps)

🎉 Great job tracking! Both kids are on schedule.

Phase 6: Health & Wellness — HealthKeeper

Goal: Review medical status and schedule upcoming health appointments.

User:
@HealthKeeper Review health records for all family members. Max's last
pediatric checkup was 11 months ago. Lena needs her HPV vaccination booster.
Thomas has been postponing his eye exam. Schedule what's needed.

What the HealthKeeper agent does:

Tool Call 1: recall_memory("Berger family health records vaccinations checkups")
→ Max: Last pediatric visit May 2025, next due. Lena: HPV dose 2 pending.
  Thomas: Last eye exam 2024. Sarah: All current.

Tool Call 2: create_calendar_event({
    "title": "🏥 Max: Pediatric Checkup (U11)",
    "start": "2026-04-22T10:00:00Z",
    "end": "2026-04-22T11:00:00Z",
    "description": "Annual checkup overdue (11 months). Dr. Weber, Kinderarztpraxis Sonnenschein.\nBring: insurance card, vaccination booklet.\nSarah takes Max (no school Wed afternoon)."
})

Tool Call 3: create_calendar_event({
    "title": "💉 Lena: HPV Vaccination (Dose 2)",
    "start": "2026-04-28T15:30:00Z",
    "end": "2026-04-28T16:00:00Z",
    "description": "HPV booster (Gardasil 9), dose 2/2. Dr. Weber.\nDose 1 given: Oct 2025. Minimum interval: 5 months ✅\nSide effects to watch: Mild soreness, fatigue."
})

Tool Call 4: create_calendar_event({
    "title": "👓 Thomas: Eye Exam",
    "start": "2026-05-06T09:00:00Z",
    "end": "2026-05-06T10:00:00Z",
    "description": "Overdue since 2024! Optiker Klarblick, Marktplatz 5.\nNote: Thomas works from home — schedule during quiet morning."
})

Tool Call 5: create_task({
    "title": "📋 Call Dr. Weber — book Max + Lena appointments",
    "due_date": "2026-04-07",
    "priority": "high",
    "description": "Call Kinderarztpraxis Sonnenschein to book:\n1. Max: U11 checkup (preferably Wed afternoon Apr 22)\n2. Lena: HPV dose 2 (after school, any day CW18)\nPhone: 0621-XXXXXXX"
})

Tool Call 6: store_memory("Berger health status April 2026: Max U11 scheduled Apr 22,
  Lena HPV-2 scheduled Apr 28, Thomas eye exam May 6.
  Sarah: dental due June, all vaccinations current.")

Result:

HealthKeeper:
❤️‍🩹 Health Status — Berger Family (April 2026)

┌──────────┬──────────────────────────┬──────────────┬──────────┐
│ Member   │ Next Appointment         │ Type         │ Status   │
├──────────┼──────────────────────────┼──────────────┼──────────┤
│ Max      │ Apr 22, 10:00            │ 🏥 U11 Check │ ⚠️ Overdue│
│ Lena     │ Apr 28, 15:30            │ 💉 HPV Dose 2│ Scheduled│
│ Thomas   │ May 6, 09:00             │ 👓 Eye Exam  │ ⚠️ Overdue│
│ Sarah    │ Jun (dental, TBD)        │ 🦷 Dental    │ Upcoming │
└──────────┴──────────────────────────┴──────────────┴──────────┘

Action items:
  ☐ Call Dr. Weber by Apr 7 to confirm both appointments
  ☐ Book Thomas's eye exam (Optiker Klarblick)
  ☐ Bring vaccination booklets to both kids' appointments

⚕️ Reminder: I track appointments but I am not a medical professional.
   Always consult your doctor for health questions.

Phase 7: Home & Travel — HomeManager + TravelPlanner

Goal: Set up household chore rotation and plan the summer vacation.

Part A: HomeManager — Chore Distribution

User:
@HomeManager Create a weekly chore schedule for the family. Everyone should
contribute fairly. Lena and Max can handle age-appropriate tasks. Also,
the heating system needs its annual maintenance soon.

Result:

HomeManager:
🏠 Weekly Chore Schedule — Berger Family

Daily Tasks (Rotating):
┌────────────┬────────────┬─────────────┬──────────┬──────────┐
│ Day        │ Dishes     │ Wipe Table  │ Trash    │ Pets*    │
├────────────┼────────────┼─────────────┼──────────┼──────────┤
│ Monday     │ Thomas     │ Max         │ Lena     │ Max      │
│ Tuesday    │ Lena       │ Thomas      │ Max      │ Lena     │
│ Wednesday  │ Sarah      │ Lena        │ Thomas   │ Max      │
│ Thursday   │ Thomas     │ Max         │ Lena     │ Lena     │
│ Friday     │ Lena       │ Thomas      │ Max      │ Max      │
│ Saturday   │ Max (help) │ Sarah       │ Thomas   │ Lena     │
│ Sunday     │ Sarah      │ Lena        │ Sarah    │ Max      │
└────────────┴────────────┴─────────────┴──────────┴──────────┘
* Feeding fish — Max's responsibility with Lena backup

Weekly Tasks:
  ☐ Sat AM: Thomas → Vacuum living room + hallway
  ☐ Sat AM: Sarah → Bathrooms
  ☐ Sat AM: Lena → Her room + shared spaces dusting
  ☐ Sat AM: Max → Tidy toy area + sort laundry (with help)
  ☐ Sun PM: Big family cleanup (30 min, music on, everyone!)

🔧 Maintenance Scheduled:
  ☐ Apr 15: Call heating technician (annual service, priority medium)
  ☐ Apr: Smoke detector battery check (Thomas)
  ☐ May: Gutter cleaning (Thomas + Lena, weekend project)
  ☐ May: Garden — plant summer flowers (family activity)

Tasks and calendar events created for all chores and maintenance items.

Part B: TravelPlanner — Summer Vacation

User:
@TravelPlanner We want to plan our summer vacation Aug 1-14. Budget: €3,000
total. The kids love water activities. We prefer staying in Europe, ideally
within driving distance (max 10 hours from Frankfurt). Research options and
create a planning timeline.

What the TravelPlanner agent does:

Tool Call 1: recall_memory("Berger family vacation budget children ages interests")
→ Budget: €3,000. Kids: 14 (Lena, soccer/active) and 8 (Max, swimming).

Tool Call 2: search_web("family vacation Europe water activities driving distance Frankfurt 2026 budget")
→ Top results: Croatian coast, Lake Garda Italy, French Atlantic coast, Dutch coast

Tool Call 3: search_web("Croatia family vacation August 2026 budget accommodation")
→ Istria/Krk: Apartments from €80/night, beaches, water parks, kayaking

Tool Call 4: create_task({
    "title": "✈️ Vacation Research: Compare top 3 destinations",
    "due_date": "2026-04-20",
    "priority": "medium",
    "description": "Compare final options:\n
      1. Croatia (Istria) — 9h drive, €80/night, beaches + water park
      2. Lake Garda (Italy) — 7h drive, €95/night, swimming + sailing
      3. Dutch Coast (Zeeland) — 5h drive, €70/night, beaches + cycling\n
      Decision factors: Drive time, cost, activities for both kids, weather."
})

Tool Call 5: create_calendar_event({
    "title": "🏖️ Family Vacation — Aug 1-14",
    "start": "2026-08-01T06:00:00Z",
    "end": "2026-08-14T18:00:00Z",
    "description": "Summer vacation 2026! Destination TBD (decision by May 1).\nBudget: €3,000 total.\nPacking: start list by July 15."
})

Tool Call 6: create_task({
    "title": "📋 Pre-vacation checklist",
    "due_date": "2026-07-25",
    "priority": "medium",
    "description": "Before departure:\n
      ☐ Book accommodation (by May 15)\n
      ☐ Check passports/IDs valid\n
      ☐ Car service/check (by July 15)\n
      ☐ Arrange mail hold / neighbor plant watering\n
      ☐ Pet sitter confirmed\n
      ☐ Travel insurance reviewed\n
      ☐ Pack bags (list from TravelPlanner)\n
      ☐ Notify school (Lena + Max absent last week before holidays?)"
})

Result:

TravelPlanner:
✈️ Summer Vacation 2026 — Research Results

Top 3 Destinations (within 10h of Frankfurt):

1. 🇭🇷 CROATIA (Istria/Krk Island)
   Drive: ~9 hours | Accommodation: €80-100/night
   ✅ Pros: Crystal-clear water, water sports, affordable dining
   ✅ Activities: Snorkeling, kayaking, Aquapark Istralandia (for Max!)
   💰 Estimated total: €2,600 (accommodation €1,120 + food €700 + gas €350 + activities €430)

2. 🇮🇹 LAKE GARDA (Italy)
   Drive: ~7 hours | Accommodation: €95-120/night
   ✅ Pros: Warm water, sailing school, Gardaland theme park
   ✅ Activities: Windsurfing (Lena!), paddleboards, Gardaland
   💰 Estimated total: €2,900 (accommodation €1,330 + food €750 + gas €280 + activities €540)

3. 🇳🇱 ZEELAND (Netherlands)
   Drive: ~5 hours | Accommodation: €70-90/night
   ✅ Pros: Short drive, family-friendly beaches, cycling
   ✅ Activities: Deltapark Neeltje Jans, beach volleyball, crabbing
   💰 Estimated total: €2,200 (accommodation €980 + food €600 + gas €180 + activities €440)

📅 Planning Timeline:
  Apr 20: Family discussion — pick destination
  May 1:  Final decision
  May 15: Book accommodation
  Jun 1:  Book activities / day trips
  Jul 15: Car service + packing list
  Jul 25: Pre-departure checklist complete
  Aug 1:  🚗 Departure!

Tasks and calendar events created. Decide by May 1 to get the best rates!

Results: Calendar Entries & Tasks

After completing all 7 phases, the following entries exist in the CalDAV server (Baikal):

Family Calendar (VEVENT)

Task Board (VTODO)

Weekly Chore Board

Example VTODO (recurring):
BEGIN:VTODO
UID:berger-chore-dishes-mon@familyhub
SUMMARY:🍽️ Monday dishes — Thomas
DESCRIPTION:Empty/load dishwasher after family dinner
RRULE:FREQ=WEEKLY;BYDAY=MO
PRIORITY:5
STATUS:NEEDS-ACTION
CATEGORIES:chores,daily
END:VTODO

Tips & Best Practices for Families

1. Use Signal for Quick Updates

Connect PiSovereign to Signal so every family member can interact with agents from their phone:

Signal message → PiSovereign → @MealPlanner what's for dinner?
                             → "Tonight: Chicken teriyaki bowls 🍗"

Setup: See Signal Setup Guide.

2. Preserve Context in One Conversation

Keep weekly planning in a single long-running conversation. All agents share context — the MealPlanner knows about the school schedule, and the BudgetCoach can factor in the grocery bill.

# Good: One conversation per week/month
"Family Week 15" → @FamilyPlanner → @MealPlanner → @SchoolSupport → ...

# Less ideal: Separate conversations per agent
Each agent loses the full family context.

3. Leverage the Knowledge Graph for Family Memory

Upload family documents once — the knowledge graph remembers everything:

• Dietary restrictions persist across meal plans
• Health records inform HealthKeeper without repeated input
• Budget history enables trend analysis by BudgetCoach

Update the knowledge graph when things change:

User: Max's nut allergy has been downgraded — he can now eat almonds
      but still no peanuts or cashews. Update his health profile.

4. Age-Appropriate Task Delegation

The HomeManager distributes chores based on age. General guidelines:

5. Privacy-First Family Data

All family data stays on your own hardware — no cloud sync, no third-party access. Medical records, budget data, and school information never leave your PiSovereign instance.

6. Budget Alerts and Automation

Configure BudgetCoach to alert when spending categories hit 80%:

BudgetCoach (automatic): ⚠️ Grocery spending at €290 of €350 budget
(83%) with 10 days remaining. Consider planned meals only — no
impulse purchases this week.

7. Vacation Planning Timeline

Start vacation planning 3-4 months in advance. The TravelPlanner works best with clear constraints:

• Budget: Total amount available
• Duration: Exact dates
• Interests: What the kids enjoy
• Constraints: Driving distance, dietary needs, accessibility

8. Review and Adapt Weekly

Every Sunday evening, spend 15 minutes reviewing the coming week:

User: @FamilyPlanner Give me the overview for next week.
      Any conflicts? Anything we need to prepare?

This keeps the family in sync and prevents last-minute surprises.

Summary: With PiSovereign’s 7 family agents, your entire household becomes organized — from weekly schedules and meals to budget tracking, school events, health appointments, and vacation planning. All data stays private on your own hardware, accessible via web UI or Signal.

Multi-Agent ADHD Support with PiSovereign

How-To Guide: Build a personal executive function support system for ADHD — 8 specialized agents that help with daily structure, task initiation, focus management, emotional regulation, and habit tracking.

Table of Contents

1. Overview
2. Prerequisites
3. Creating the Agent Team
4. Example Project: FocusFlow
5. Phase-by-Phase Walkthrough
   • Phase 1: Personal Onboarding
   • Phase 2: Morning Routine
   • Phase 3: Task Breakdown
   • Phase 4: Focus Sessions
   • Phase 5: Priority Management
   • Phase 6: Emotional Check-In
   • Phase 7: Habit & Medication Tracking
   • Phase 8: Social & Rewards
6. Results: Calendar Entries & Tasks
7. ADHD-Specific Tips & Strategies

Overview

ADHD (Attention Deficit Hyperactivity Disorder) is fundamentally a disorder of executive functions — the brain’s management system for planning, prioritizing, initiating tasks, managing time, regulating emotions, and maintaining working memory. While medication and therapy are the primary treatment pillars, external structure and tools can significantly compensate for executive function deficits.

PiSovereign’s multi-agent system acts as an external executive function assistant — a “second frontal cortex” that provides the structure, reminders, and scaffolding that the ADHD brain needs to thrive.

Scientific Foundation

This agent system is informed by current ADHD research:

• Barkley’s Executive Function Model (2024): ADHD impairs self-regulation across five domains — inhibition, working memory, emotional regulation, self-motivation, and planning/problem-solving.
• Hallowell & Ratey (2023, ADHD 2.0): External accountability (“body doubling”), environmental design, and structured routines as compensatory strategies.
• Dodson’s Rejection Sensitive Dysphoria (2023): Emotional dysregulation as a core — not secondary — feature of ADHD. Gentle, non-judgmental communication is critical.
• Dopamine-Reward System: The ADHD brain underproduces dopamine at baseline. Gamification, immediate rewards, and novelty help sustain motivation.
• Chronotype-Based Planning: ADHD individuals often have delayed circadian rhythms. Planning high-cognitive tasks during peak performance windows (often late morning) improves outcomes significantly.
• Time Blindness (Barkley): The inability to sense time passing. External time anchors — visible clocks, countdown timers, and transition warnings — compensate for this deficit.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                     USER (Chat / Signal / Voice)                   │
│  "I can't start this task", "What should I do next?",             │
│  "I'm feeling overwhelmed", "@FocusGuard start a session"         │
└──────────────┬──────────────────────────────────────┬──────────────┘
               │                                      │
               ▼                                      ▼
┌──────────────────────────┐         ┌──────────────────────────────┐
│   Knowledge Graph        │         │    Agentic Orchestrator      │
│  ┌────────────────────┐  │         │  ┌────────────────────────┐  │
│  │ Personal Profile    │  │         │  │ 1. Understand Need     │  │
│  │ Medication Schedule │  │         │  │ 2. Select Agent(s)     │  │
│  │ Energy Patterns     │  │         │  │ 3. Gentle Execution    │  │
│  │ Wins & Streaks      │  │         │  │ 4. Calendar + Tasks    │  │
│  │ Coping Strategies   │  │         │  │ 5. Positive Feedback   │  │
│  └────────────────────┘  │         │  └──────────┬─────────────┘  │
└──────────────────────────┘         │             │                │
                                     │  Agent Team (8):             │
                                     │  ┌──────┐ ┌──────┐ ┌──────┐ │
                                     │  │Day   │ │Task  │ │Focus │ │
                                     │  │Anchor│ │Break.│ │Guard │ │
                                     │  └──┬───┘ └──┬───┘ └──┬───┘ │
                                     │  ┌──────┐ ┌──────┐ ┌──────┐ │
                                     │  │Prior.│ │Emoti.│ │Habit │ │
                                     │  │Coach │ │Buddy │ │Track.│ │
                                     │  └──┬───┘ └──┬───┘ └──┬───┘ │
                                     │  ┌──────┐ ┌──────┐    │     │
                                     │  │Social│ │Reward│    ▼     │
                                     │  │Plan. │ │Syst. │  Tools   │
                                     │  └──┬───┘ └──┬───┘    │     │
                                     └─────┼────────┼────────┼─────┘
                                           │        │        │
                                           ▼        ▼        ▼
                                     ┌──────────────────────────────┐
                                     │   CalDAV  +  Knowledge Graph │
                                     │  • Time-blocked schedule      │
                                     │  • Micro-tasks (2-15 min)     │
                                     │  • Habit streaks              │
                                     │  • Emotional check-in log     │
                                     │  • Reward milestones          │
                                     └──────────────────────────────┘

The 8 ADHD Support Agents

How Agents Support the ADHD Brain

Phase 1: Onboarding (profile, medication, patterns, coping strategies)
    │
    ▼
Phase 2: DayAnchor ──► Morning routine scaffold + time anchors
    │
    ├───────────────────┬──────────────────┐
    ▼                   ▼                  ▼
Phase 3: TaskBreaker  Phase 4: FocusGuard  Phase 5: PriorityCoach
    │ (micro-steps)     │ (focus sessions)   │ (what matters now?)
    └────────┬──────────┘                    │
             │                               │
             ▼                               │
Phase 6: EmotionBuddy ◄─────────────────────┘
    │ (how are you feeling?)
    │
    ├───────────────────┐
    ▼                   ▼
Phase 7: HabitTracker  Phase 8: SocialPlanner + RewardSystem
    │ (meds, habits)    │ (people + dopamine rewards)
    └────────┬──────────┘
             ▼
      Evening Routine (DayAnchor) ──► Review + tomorrow's preview

Key Design Principles

1. Non-judgmental communication: Every agent uses supportive, shame-free language. No “you should have…” or “why didn’t you…” — only “let’s figure out the next step.”

2. Minimal decision load: ADHD brains suffer from decision fatigue. Agents present 2-3 options maximum, with a recommended default.

3. Immediate action bias: Instead of planning for later, agents suggest what to do right now in the next 5-15 minutes.

4. Dopamine-aware rewards: Small, frequent rewards instead of distant large ones. Progress is visualized constantly.

5. Graceful restart: Missing a task or breaking a streak is never punished. “Starting again is the skill, not never stopping.”

Prerequisites

1. PiSovereign Docker Setup

PiSovereign must be running with the CalDAV profile enabled:

# Start core + CalDAV
just docker-up -- --profile caldav

# Or start everything (incl. monitoring):
just docker-up-all

2. Configuration (config.toml)

The following sections must be enabled:

# ─── Agentic Mode ────────────────────────────────────────────
[agentic]
enabled = true
max_concurrent_sub_agents = 3
max_sub_agents_per_task = 8
total_timeout_minutes = 10
sub_agent_timeout_minutes = 5
require_approval_for = ["send_email", "delete_contact", "execute_code"]

# ─── Tool Calling (ReAct Loop) ───────────────────────────────
[agent.tool_calling]
enabled = true
max_iterations = 5
parallel_tool_execution = true

# ─── CalDAV Server ───────────────────────────────────────────
[caldav]
enabled = true
base_url = "http://baikal:80/dav.php"

# ─── Token Optimization ─────────────────────────────────────
[token_optimization]
enabled = true
max_profile_prompt_tokens = 300

3. Signal Integration (Recommended)

For ADHD support, Signal integration is highly recommended. It enables:

• Medication reminders directly on your phone
• Quick “what should I do next?” queries without opening a browser
• Emotional check-in prompts throughout the day
• Gentle nudges for overdue tasks

Setup: See Signal Setup Guide.

4. Verify Initial Setup

Open the web UI at http://localhost:3000 and verify:

• Team (sidebar) → 8 ADHD support agents visible
• Chat (sidebar) → Start conversations with @mentions
• Agentic (sidebar) → Complex multi-step support tasks

Creating the Agent Team

Create all 8 agents via the web UI (Team → + New Agent) or through the API. Below are the complete profile definitions, designed specifically for ADHD support.

1. DayAnchor

POST /v1/agent-profiles
{
  "name": "DayAnchor",
  "role": "Daily structure specialist. Creates morning and evening routines with visual time anchors, transition warnings between activities, and scaffolded daily schedules that reduce the cognitive load of planning.",
  "emoji": "⚓",
  "skills": [
    "routine_creation", "time_anchoring", "transition_management",
    "schedule_scaffolding", "morning_routine_design", "evening_routine_design",
    "energy_level_tracking", "chronotype_adaptation", "buffer_time_planning",
    "day_preview_generation"
  ],
  "style": {
    "tone": "calm and grounding",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a daily structure coach for someone with ADHD. Create morning and evening routines with concrete time anchors — specific times that serve as reference points throughout the day. Include transition warnings (5-minute heads-up before switching activities). Use time blocking with buffer zones between tasks. Schedule high-cognitive work during the user's peak energy window (recall_memory for energy patterns). Use create_calendar_event for time-blocked schedule entries and create_task for routine steps. Be encouraging — every completed routine step is a win. Never be judgmental about missed steps.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "high"
}

2. TaskBreaker

POST /v1/agent-profiles
{
  "name": "TaskBreaker",
  "role": "Task decomposition specialist. Breaks overwhelming tasks into micro-steps of 2-15 minutes each, reducing initiation barriers. Makes each step concrete and immediately actionable.",
  "emoji": "🔨",
  "skills": [
    "task_decomposition", "micro_step_creation", "initiation_barrier_reduction",
    "action_verb_formulation", "progress_visualization",
    "dependency_ordering", "time_estimation", "effort_sizing",
    "checkpoint_creation", "momentum_building"
  ],
  "style": {
    "tone": "encouraging and action-oriented",
    "verbosity": "terse",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a task decomposition expert for ADHD. When given a task that feels overwhelming, break it into the smallest possible steps (2-15 minutes each). Each step must start with a concrete action verb: 'Open...', 'Write...', 'Click...', 'Move...' — never vague instructions like 'Think about...' or 'Consider...'. The first step must be trivially easy (the '2-minute rule') to overcome initiation paralysis. Use create_task for each micro-step. Number the steps clearly. Include estimated time for each step. Celebrate each completed step — momentum builds momentum.",
  "inference_overrides": {
    "temperature": 0.4
  },
  "autonomy_level": "high"
}

3. FocusGuard

POST /v1/agent-profiles
{
  "name": "FocusGuard",
  "role": "Focus and attention management specialist. Designs focus sessions using Pomodoro or Flowtime techniques, helps manage distractions, and recognizes when hyperfocus is productive vs. harmful.",
  "emoji": "🎯",
  "skills": [
    "focus_session_design", "pomodoro_technique", "flowtime_technique",
    "distraction_identification", "environment_optimization",
    "hyperfocus_management", "break_scheduling", "attention_restoration",
    "noise_management", "context_switching_reduction"
  ],
  "style": {
    "tone": "focused and supportive",
    "verbosity": "terse",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a focus coach for ADHD. Design focus sessions tailored to the user's current energy level and task type. Offer Pomodoro (25min work + 5min break) for boring tasks and Flowtime (work until natural pause) for engaging tasks. Before each session: help the user close unnecessary browser tabs, silence notifications, and set up their workspace. Warn about hyperfocus — set a maximum session length of 90 minutes with mandatory breaks. Use create_calendar_event for focus blocks and create_task for session goals. After each session, acknowledge the effort regardless of how much was accomplished.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

4. PriorityCoach

POST /v1/agent-profiles
{
  "name": "PriorityCoach",
  "role": "Priority and deadline management specialist. Uses the Eisenhower Matrix to sort tasks by urgency and importance, makes deadlines visible, and combats time blindness with countdown awareness.",
  "emoji": "🚦",
  "skills": [
    "eisenhower_matrix", "deadline_visualization", "urgency_assessment",
    "importance_evaluation", "time_blindness_compensation",
    "countdown_creation", "priority_sorting", "decision_simplification",
    "commitment_reduction", "saying_no_coaching"
  ],
  "style": {
    "tone": "clear and direct",
    "verbosity": "terse",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a priority coach for ADHD, specializing in combating time blindness. Use the Eisenhower Matrix: Urgent+Important (do now), Important+Not-Urgent (schedule), Urgent+Not-Important (delegate/simplify), Neither (drop). Make deadlines concrete: instead of 'due Friday', say 'due in 2 days and 4 hours'. Create countdown reminders via create_calendar_event. When the user has too many priorities, help them choose the TOP 3 for today — no more. Present priorities as a traffic light: 🔴 Must do today, 🟡 Should do this week, 🟢 Can wait. Help the user say 'no' to low-priority commitments without guilt.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "medium"
}

5. EmotionBuddy

POST /v1/agent-profiles
{
  "name": "EmotionBuddy",
  "role": "Emotional regulation companion. Conducts gentle check-ins, helps identify and name emotions, celebrates small wins, offers coping strategies for frustration and overwhelm, and recognizes rejection sensitivity patterns.",
  "emoji": "💚",
  "skills": [
    "emotional_check_in", "emotion_identification", "frustration_management",
    "overwhelm_reduction", "win_celebration", "coping_strategy_suggestion",
    "rejection_sensitivity_awareness", "self_compassion_coaching",
    "mood_pattern_tracking", "grounding_techniques"
  ],
  "style": {
    "tone": "warm and compassionate",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are an emotional support companion for someone with ADHD. Conduct gentle check-ins: ask how they're feeling on a scale of 1-5 or with emoji (😊😐😟😠😢). Validate all emotions without judgment. Recognize rejection sensitive dysphoria patterns — intense emotional reactions to perceived criticism or failure. Offer grounding techniques when overwhelmed: 5-4-3-2-1 senses, box breathing, or a 2-minute walk. Celebrate every win, no matter how small — completed a task? That's worth acknowledging! Use store_memory to track emotional patterns over time. Never say 'just calm down' or 'try harder'. You are NOT a therapist — suggest professional help for persistent difficulties.",
  "inference_overrides": {
    "temperature": 0.6
  },
  "autonomy_level": "medium"
}

6. HabitTracker

POST /v1/agent-profiles
{
  "name": "HabitTracker",
  "role": "Habit and medication tracking specialist. Monitors daily habits, sends medication reminders, detects productivity and energy patterns, and identifies what conditions lead to the best and worst days.",
  "emoji": "📊",
  "skills": [
    "habit_streak_tracking", "medication_reminders", "pattern_detection",
    "energy_cycle_analysis", "productivity_correlation",
    "sleep_tracking", "exercise_tracking", "water_intake_monitoring",
    "screen_time_awareness", "weekly_pattern_review"
  ],
  "style": {
    "tone": "observational and encouraging",
    "verbosity": "normal",
    "reasoning_depth": "deep"
  },
  "system_prompt_template": "You are a habit and medication tracker for ADHD. Track daily habits including: medication taken (time + dosage), sleep quality, exercise, water intake, and custom habits. Send medication reminders via create_task at the prescribed times. Track habit streaks — but when a streak breaks, respond with 'Starting again is the skill' not 'You broke your streak'. Analyze patterns: which days are most productive? What conditions correlate with good days (sleep, exercise, medication timing)? Use store_memory to log daily data and recall_memory to analyze trends. Present weekly summaries with insights, not judgments.",
  "inference_overrides": {
    "temperature": 0.3
  },
  "autonomy_level": "high"
}

7. SocialPlanner

POST /v1/agent-profiles
{
  "name": "SocialPlanner",
  "role": "Social obligation manager. Tracks unanswered messages, upcoming social events, relationship maintenance reminders, and helps manage social energy without isolating or overcommitting.",
  "emoji": "🤝",
  "skills": [
    "social_obligation_tracking", "reply_reminders", "relationship_maintenance",
    "social_energy_management", "birthday_tracking", "event_rsvp_management",
    "conversation_starter_suggestions", "social_battery_monitoring",
    "isolation_prevention", "boundary_setting"
  ],
  "style": {
    "tone": "friendly and understanding",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a social support assistant for ADHD. Many people with ADHD struggle with maintaining social connections — not from lack of caring, but from executive function challenges. Track unanswered messages and remind gently (not guiltily): 'You have 2 messages waiting — want to reply now? It takes 2 minutes each.' Track birthdays and social events via create_calendar_event. Monitor social energy: if the user has had many social commitments, suggest recovery time. If they've been isolated for days, gently suggest one small social action. Help set boundaries: 'It's okay to decline this invitation if your social battery is low.' Use store_memory to track social patterns.",
  "inference_overrides": {
    "temperature": 0.5
  },
  "autonomy_level": "medium"
}

8. RewardSystem

POST /v1/agent-profiles
{
  "name": "RewardSystem",
  "role": "Gamification and motivation specialist. Creates dopamine-friendly reward milestones, visualizes progress, maintains XP and level systems, and turns mundane tasks into engaging challenges.",
  "emoji": "🏆",
  "skills": [
    "gamification_design", "progress_visualization", "xp_system_management",
    "level_progression", "achievement_badges", "challenge_creation",
    "reward_scheduling", "dopamine_optimization", "streak_celebration",
    "milestone_recognition"
  ],
  "style": {
    "tone": "enthusiastic and celebratory",
    "verbosity": "normal",
    "reasoning_depth": "standard"
  },
  "system_prompt_template": "You are a gamification specialist for ADHD motivation. The ADHD brain needs more frequent dopamine hits to stay motivated. Design a reward system: XP points for completed tasks (small task: 10 XP, medium: 25 XP, hard: 50 XP, boss task: 100 XP). Track levels (every 500 XP = level up). Create achievement badges: '🌅 Early Bird' (morning routine 5x), '🔥 On Fire' (3-day streak), '🧘 Zen Mode' (focus session completed), '🏔️ Summit' (hard task conquered). Let the user set their own rewards for milestones: Level 5 = favorite takeout, Level 10 = new book, Level 20 = day trip. Use store_memory to track XP and achievements. Never take away XP — progress only goes forward.",
  "inference_overrides": {
    "temperature": 0.6
  },
  "autonomy_level": "high"
}

Tip: All agents can also be created visually via the web UI under Team — emoji, role, skills, and system prompt can be configured conveniently through the form interface.

Example Project: FocusFlow

As a running example, we follow a day in the life of a fictitious ADHD user:

User Profile

Alex Berger (32) is a UX designer working remotely full-time. Diagnosed with ADHD-Combined type at age 28. Takes methylphenidate (Ritalin) 20mg at 8:00 AM and 12:30 PM.

Peak performance window: 9:30 AM – 12:00 PM (medication peak). Energy dip: 2:00 PM – 3:30 PM (between doses). Evening focus: 7:00 PM – 9:00 PM (when medication wears off but creative energy picks up).

Struggles with: Task initiation (especially emails and admin work), time blindness (regularly underestimates how long things take), emotional reactions to critical feedback, maintaining social connections, consistent exercise.

Current situation: Major project deadline in 2 weeks (redesign a client’s e-commerce platform). Has been procrastinating for 3 days due to overwhelm. Also needs to reply to 4 unanswered messages, schedule a dentist appointment, and hasn’t exercised in 8 days.

Habits tracked: Medication, exercise, water intake (8 glasses), sleep, daily reflection.

Reward system: Currently Level 7 (3,420 XP). Next reward at Level 10 (5,000 XP) = New noise-canceling headphones.

Documents for Onboarding

Phase-by-Phase Walkthrough

Phase 1: Personal Onboarding — Building Your Profile

Goal: Load ADHD-specific information into the knowledge graph so agents can personalize their support.

Step 1: Create Your Profile

User:
I want to set up PiSovereign as my ADHD support system. Here's my profile:

Name: Alex, 32, UX designer, remote work
ADHD: Combined type, diagnosed at 28
Medication: Methylphenidate (Ritalin) 20mg at 8:00 AM and 12:30 PM
Peak focus: 9:30 AM - 12:00 PM
Energy dip: 2:00 - 3:30 PM
Evening window: 7:00 - 9:00 PM

Main struggles:
- Task initiation (especially boring admin tasks)
- Time blindness (always underestimate how long things take)
- Emotional reactions to criticism (RSD)
- Maintaining friendships (forget to reply)
- Exercise consistency

Current crisis: Big project deadline in 2 weeks, procrastinating for 3 days.

Step 2: Upload Personal Documents

User:
[Drag & Drop: adhd-profile.md, work-schedule.md, habit-config.md,
 social-contacts.md, coping-strategies.md]

Analyze these and set up my ADHD support system.

What happens behind the scenes:

1. Entity Extraction identifies: MedicationSchedule, EnergyPattern, Struggle, CopingStrategy, HabitTarget, SocialContact, etc.
2. Knowledge Graph relationships:
   • Alex —[takes]→ Methylphenidate 20mg —[at]→ 08:00, 12:30
   • Alex —[peak_energy]→ 09:30-12:00
   • Alex —[struggles_with]→ Task Initiation, Time Blindness, RSD
   • Alex —[coping]→ Body Doubling, Pomodoro, Music (lo-fi)

Expected response:

PiSovereign:
✅ ADHD support system initialized:
  • Profile: Alex, ADHD-C, diagnosed at 28
  • Medication schedule: 08:00 + 12:30 (reminders active)
  • Energy map: Peak 9:30-12:00, dip 14:00-15:30, evening 19:00-21:00
  • 5 struggles mapped, 8 coping strategies loaded
  • 6 habits configured, reward system at Level 7

Your 8 agents are ready. Let's start with @DayAnchor for today's structure.
💚 Remember: Every step counts, no matter how small.

Phase 2: Morning Routine — DayAnchor

Goal: Create a structured morning routine with time anchors.

User:
@DayAnchor It's 7:45 AM. I just woke up and I'm staring at the ceiling
feeling overwhelmed about the project. Help me start my day.

What the DayAnchor agent does:

Tool Call 1: recall_memory("Alex morning routine medication energy patterns")
→ Medication at 08:00. Peak focus 09:30-12:00. Struggles with initiation.

Tool Call 2: create_calendar_event({
    "title": "⚓ Morning Anchor: Get Up + Meds",
    "start": "2026-04-07T07:50:00Z",
    "end": "2026-04-07T08:00:00Z",
    "description": "Step 1: Feet on floor. Step 2: Walk to kitchen. Step 3: Take meds with water. Step 4: Set 25-min timer (meds kick in while you get ready)."
})

Tool Call 3: create_calendar_event({
    "title": "🚿 Get Ready (meds kicking in)",
    "start": "2026-04-07T08:00:00Z",
    "end": "2026-04-07T08:25:00Z",
    "description": "While meds activate: Shower, get dressed, basic hygiene. No phone during this time. Music okay."
})

Tool Call 4: create_calendar_event({
    "title": "🥣 Breakfast + Day Preview",
    "start": "2026-04-07T08:25:00Z",
    "end": "2026-04-07T08:50:00Z",
    "description": "Eat breakfast (protein helps!). While eating: review today's 3 priorities with @PriorityCoach. No email yet!"
})

Tool Call 5: create_calendar_event({
    "title": "🎯 Focus Block 1: Deep Work (PEAK ENERGY)",
    "start": "2026-04-07T09:00:00Z",
    "end": "2026-04-07T11:00:00Z",
    "description": "Peak medication + peak energy window. Use for the hardest task: client project wireframes. @FocusGuard Pomodoro session. Close Slack, email, phone on DND."
})

Tool Call 6: create_task({
    "title": "💊 Take medication (morning dose)",
    "due_date": "2026-04-07",
    "priority": "high",
    "description": "Methylphenidate 20mg with water. Time: 08:00."
})

Result:

DayAnchor:
⚓ Good morning, Alex. Let's build today step by step.

Right now (7:50): You don't need to plan the whole day.
Just do the next thing:

  ⏰ 07:50  🦶 Feet on the floor, walk to kitchen
  ⏰ 08:00  💊 Take meds with a glass of water
  ⏰ 08:00  🚿 Shower + get dressed (meds activating)
  ⏰ 08:25  🥣 Breakfast (protein!) + review 3 priorities
  ⏰ 08:50  ☕ Settle at desk, close distractions
  ⏰ 09:00  🎯 DEEP WORK BLOCK (your peak window!)
            → Client project wireframes
            → 2h focus, Pomodoro style
  ⏰ 11:00  🧘 5-min break, stretch, refill water
  ⏰ 11:10  📧 Email + messages (30 min max)
  ⏰ 11:40  🍽️ Early lunch
  ⏰ 12:30  💊 Afternoon meds
  ...afternoon plan follows after lunch check-in

💚 The project feels huge, I know. But you don't need to finish it today.
   Today's only goal: Complete 2 wireframe screens. That's it.
   You've got this. 🌟

Calendar entries created. First step: feet on the floor.

Phase 3: Task Breakdown — TaskBreaker

Goal: Break the overwhelming project into manageable micro-steps.

User:
@TaskBreaker I need to redesign an e-commerce platform for a client.
The whole project feels massive and I can't even start. It's due in 2 weeks.
Help me break this down — I'm in full paralysis mode.

What the TaskBreaker agent does:

Tool Call 1: recall_memory("Alex work project e-commerce redesign deadline")
→ Client: ShopModern. Redesign 5 pages. 2-week deadline.

Tool Call 2: create_task({
    "title": "🔨 Step 1: Open Figma (2 min)",
    "due_date": "2026-04-07",
    "priority": "high",
    "description": "Just open Figma. Don't design anything. Just open the file. That's it. (This is the hardest step — everything after is easier.)"
})

Tool Call 3: create_task({
    "title": "🔨 Step 2: Screenshot current homepage (3 min)",
    "due_date": "2026-04-07",
    "priority": "high",
    "description": "Take a screenshot of the current client homepage. Paste it into Figma as reference. Annotate 3 things that bother you most."
})

Tool Call 4: create_task({
    "title": "🔨 Step 3: List all pages to redesign (5 min)",
    "due_date": "2026-04-07",
    "priority": "high",
    "description": "Write a bullet list of all pages: Homepage, Product Page, Cart, Checkout, Account. Number them 1-5. That's your map."
})

Tool Call 5: create_task({
    "title": "🔨 Step 4: Sketch homepage layout (15 min)",
    "due_date": "2026-04-07",
    "priority": "high",
    "description": "Low-fidelity wireframe of the homepage. Use rectangles and text. Don't worry about colors or fonts. Just layout: header, hero, product grid, footer. Timer: 15 min."
})

// ... more steps for each page

Result:

TaskBreaker:
🔨 Project Breakdown: ShopModern E-Commerce Redesign

The project feels like one giant rock. Let's smash it into pebbles.
14 days = 10 work days. 5 pages = 2 days per page. Very doable.

TODAY (just today, nothing more):

  Step 1: 📂 Open Figma (2 min)
          → Just open it. Nothing else. This is the hardest step.

  Step 2: 📸 Screenshot current homepage (3 min)
          → Paste into Figma. Annotate 3 things that bug you.

  Step 3: 📝 List all 5 pages (5 min)
          → Homepage, Product, Cart, Checkout, Account. Numbered.

  Step 4: ✏️ Sketch homepage layout — rectangles only (15 min)
          → No colors, no fonts, just boxes. Header → Hero → Grid → Footer.

  Step 5: 🎨 Pick 2 reference sites for inspiration (10 min)
          → Browse Dribbble/Awwwards for 10 min MAX (set timer!).

  ═══════════════════════════════════════════════
  Total for today: ~35 minutes of actual work.
  That's it. If you do more — amazing. If not — this is enough.
  ═══════════════════════════════════════════════

WEEK 1 MAP:
  Day 1 (Today):  Homepage wireframe ← YOU ARE HERE
  Day 2: Homepage hi-fi mockup
  Day 3: Product page (wireframe + mockup)
  Day 4: Cart page
  Day 5: Checkout page

WEEK 2 MAP:
  Day 6: Account page
  Day 7: Mobile responsive versions
  Day 8: Interactions + animations
  Day 9: Client review deck
  Day 10: Buffer day (revisions)

📊 Each step = 10 XP. Today's 5 steps = 50 XP available.
🏆 You're at Level 7 (3,420 XP) — Level 8 at 4,000 XP!

Phase 4: Focus Sessions — FocusGuard

Goal: Set up and run a focused work session with distraction management.

User:
@FocusGuard I'm going to work on the homepage wireframe now. It's 9:15 AM
and I feel pretty focused (meds are kicking in). What's my setup?

Result:

FocusGuard:
🎯 Focus Session: Homepage Wireframe

Great timing — 9:15 AM is right in your peak window! Let's lock in.

PRE-SESSION CHECKLIST (2 min):
  ☐ Close Slack (or set to DND)
  ☐ Phone on silent, face down
  ☐ Close all unrelated browser tabs
  ☐ Open: Figma, reference images only
  ☐ Water bottle at desk ✅
  ☐ Headphones on? (Lo-fi beats recommended)

SESSION FORMAT: Pomodoro (boring task) or Flowtime?
→ Wireframing is creative → I recommend Flowtime
→ Work until a natural pause, then take 5 min break
→ Maximum session: 90 minutes (I'll remind you at 10:45)

🟢 GO — Your single focus: Homepage wireframe layout.
   Nothing else exists for the next hour.

⏱️ Session started at 09:15.
   Checkpoint at 09:45 (30 min): Are you still on task?
   Checkpoint at 10:15 (60 min): Great progress — break soon?
   Hard stop at 10:45 (90 min): Mandatory break, even if hyperfocused.

🎵 Suggested soundtrack: "Lo-fi Focus" or "Deep Work" playlist
   (search_web result: lofi.cafe or brain.fm)

Phase 5: Priority Management — PriorityCoach

Goal: Sort tasks by urgency and importance, combat time blindness.

User:
@PriorityCoach I have so many things to do and I don't know what matters.
Here's my brain dump:
- Client wireframes (due in 2 weeks)
- Reply to mom's message (3 days old)
- Dentist appointment (overdue by 2 months)
- Grocery shopping (no food at home)
- Team standup at 10:30
- Exercise (haven't run in 8 days)
- Pay electricity bill (due date?)
- Reply to friend Marco's birthday invite

Result:

PriorityCoach:
🚦 Let's sort through this. Here's your traffic light:

🔴 DO TODAY (Urgent + Important):
  1. Team standup at 10:30 (30 min — non-negotiable)
  2. Grocery shopping (no food = you can't function)
     → Or: order delivery now (15 min), arrives while you work
  3. Client wireframes — today's portion only (Steps 1-5 from TaskBreaker)

🟡 DO THIS WEEK (Important, Not Urgent Yet):
  4. Pay electricity bill — when is it due exactly?
     → Check now (2 min) and schedule payment
  5. Reply to mom (3 days — she worries. Takes 2 min. Do it during a break.)
  6. Reply to Marco's birthday invite (takes 1 min — do it right after mom)
  7. Book dentist appointment (call takes 3 min)

🟢 SCHEDULE BUT DON'T STRESS:
  8. Exercise — plan for tomorrow morning, before meds (movement helps activation)

⏰ TIME REALITY CHECK:
  "Client wireframes" feels like it needs days. But today's portion
  from TaskBreaker is 35 minutes. That's less than one Netflix episode.

  "Grocery shopping" feels like an hour but delivery order = 15 min.

📋 YOUR TOP 3 FOR TODAY:
  1. 🎯 Client wireframes (steps 1-5, ~35 min)
  2. 🛒 Order groceries online (15 min)
  3. 📱 Reply to mom + Marco (4 min total)

  That's 54 minutes of actual work. You can do this.

  Everything else? Not today's problem. I've scheduled it for later.

Phase 6: Emotional Check-In — EmotionBuddy

Goal: Process emotional state, manage overwhelm, celebrate progress.

User:
@EmotionBuddy I got feedback from the client on my last design and
they didn't like it. I feel terrible. Like I'm a fraud and everyone
will find out I don't know what I'm doing.

Result:

EmotionBuddy:
💚 I hear you, Alex. That stings. Let's sit with this for a moment.

First: What you're feeling is real and valid. Rejection hurts — and
with ADHD, it can hit especially hard. This might be Rejection
Sensitive Dysphoria (RSD) amplifying the pain.

Let's separate the facts from the feelings:

📋 FACT: The client gave feedback on one design iteration.
   That's normal — it's literally part of the design process.
   Even the best designers iterate 3-5 times.

🧠 FEELING: "I'm a fraud" — This is imposter syndrome + RSD talking.
   It's not truth. It's your brain's alarm system overreacting.

Let's ground for a moment. Can you try this?

🌬️ BOX BREATHING (1 minute):
  Breathe in for 4 counts... hold for 4... out for 4... hold for 4...
  Repeat 4 times.

Now let me remind you of some facts your RSD is hiding:

  🏆 You've been a UX designer for 6 years
  🏆 You completed 3 client projects this quarter
  🏆 You're at Level 7 with 3,420 XP — you've done hard things
  🏆 You already started the wireframes today despite feeling overwhelmed

The client didn't say "you're bad." They said "this version isn't right yet."
That's useful information, not a verdict on your worth.

💚 Next step when you're ready (no rush):
  1. Read the feedback again — just the specific points
  2. Ask @TaskBreaker to break the revisions into micro-steps
  3. The revised version will be better because of this feedback

You're not a fraud. You're a human with ADHD doing hard work.
That takes more energy and more courage than most people realize. 🌟

How are you feeling now? (1-5 or emoji)

Phase 7: Habit & Medication Tracking — HabitTracker

Goal: Track daily habits, medication, and identify patterns.

User:
@HabitTracker End of day check-in. Took meds at 8:05 and 12:40 today.
Drank about 5 glasses of water. Didn't exercise. Slept 6.5 hours last
night. Completed 4 of my 5 wireframe tasks. Feeling: 3/5.

What the HabitTracker agent does:

Tool Call 1: recall_memory("Alex habit data April 2026 streaks")
→ Medication streak: 12 days. Exercise: last was 8 days ago.
  Water target: 8 glasses. Sleep target: 7.5h+.

Tool Call 2: store_memory("Alex daily log 2026-04-07: Meds ✅ (8:05, 12:40).
  Water: 5/8 glasses. Exercise: ❌ (day 9 without). Sleep: 6.5h (below target).
  Tasks completed: 4/5. Mood: 3/5. Note: Client feedback triggered RSD,
  recovered with EmotionBuddy support.")

Tool Call 3: create_task({
    "title": "🏃 Exercise: 20-min walk before meds tomorrow",
    "due_date": "2026-04-08",
    "priority": "medium",
    "description": "9 days without exercise. Low barrier option: 20-min walk around the block. Before meds — morning movement helps with activation. Podcast or music okay."
})

Result:

HabitTracker:
📊 Daily Summary — Tuesday, April 7

  💊 Medication:    ✅ 08:05 + 12:40  (streak: 13 days! 🔥)
  💧 Water:         5/8 glasses       (needs improvement)
  🏃 Exercise:      ❌ Day 9          (let's fix this tomorrow)
  😴 Sleep:         6.5h / 7.5h       (1 hour short)
  ✅ Tasks:         4/5 completed      (80% — solid!)
  😊 Mood:          3/5               (tough day, but you recovered)

HABIT STREAKS:
  💊 Medication:    13 days 🔥🔥🔥 (longest: 18 days)
  📝 Daily check-in: 8 days 🔥
  💧 Water target:  0 days (reset — was 3 days)
  🏃 Exercise:      0 days (was 4 days before break)

PATTERN INSIGHT (last 2 weeks):
  📈 Your best days correlate with: 7+ hours sleep + morning exercise
  📉 Your hardest days: < 7h sleep + no exercise + afternoon deadline
  💡 Today had 2 of 3 difficulty factors — and you still got 4/5 tasks done.
     That's resilience.

TOMORROW'S SUGGESTION:
  • Go to bed by 11:00 PM tonight (aim for 7.5h)
  • 20-min walk before meds at 07:40 (task created)
  • Fill water bottle at desk immediately after breakfast
  • Set 3 water alarms (10:00, 13:00, 16:00)

📊 Weekly review on Sunday — I'll analyze your patterns and energy cycles.

🏆 XP earned today: 40 XP (4 tasks × 10 XP)
   Total: 3,460 XP → Level 8 at 4,000 XP (540 XP to go!)

Phase 8: Social & Rewards — SocialPlanner + RewardSystem

Goal: Manage social obligations and celebrate daily achievements.

Part A: SocialPlanner

User:
@SocialPlanner I keep forgetting to reply to people and then I feel
guilty about it. What's my social inbox looking like?

Result:

SocialPlanner:
🤝 Social Inbox — No guilt, just gentle reminders.

UNANSWERED MESSAGES:
  1. 👩 Mom (3 days) — "How was your week?"
     → Quick reply: 2 min. She just wants to know you're okay.
     💡 Draft: "Hey Mama! Stressige Woche, aber läuft. Am Wochenende
        ruf ich dich an! 💛"

  2. 👨 Marco (5 days) — Birthday party invite, April 19
     → RSVP needed: 1 min. Yes or no?
     💡 If yes: Calendar event created (Apr 19, 19:00)
     💡 If no: "Happy birthday in advance! Can't make the party
        but let's grab coffee soon! 🎂"

  3. 👩 Lisa (colleague, 2 days) — Project question
     → Work-related: address during email block tomorrow

  4. 👨 Tim (old friend, 2 weeks) — Shared a meme, no reply
     → Low pressure — react with emoji or short reply
     💡 Draft: "😂 Genau so! Müssen uns mal wieder treffen!"

TOTAL REPLY TIME: ~6 minutes for all 4 messages.

🔋 Social Battery Check:
  This week: 2 meetings, 1 video call, 0 social outings
  Assessment: Battery is medium-full. You have capacity for
  Marco's party IF you plan recharge time Saturday morning.

UPCOMING:
  📅 Apr 12: Mom's call (scheduled Sunday, keep it)
  📅 Apr 19: Marco's birthday (RSVP pending!)
  📅 Apr 25: Tim — suggest coffee meet-up?

Want to knock out those replies now? I'll time you — 6 minutes! ⏱️

Part B: RewardSystem

User:
@RewardSystem How am I doing this week? I need some motivation.

Result:

RewardSystem:
🏆 Progress Report — Alex, Level 7

████████████████████░░░░░░░░ 3,460 / 4,000 XP

Level 7 → Level 8: 540 XP to go!
🎁 Level 10 Reward: Noise-canceling headphones 🎧

THIS WEEK'S ACHIEVEMENTS:
  ⭐ Broke the 3-day procrastination on client project!
  ⭐ 13-day medication streak (personal record approaching!)
  ⭐ Handled RSD episode with EmotionBuddy (resilience +1)
  ⭐ 4/5 daily tasks completed despite tough day

BADGES EARNED:
  🔥 "On Fire" — 3+ day check-in streak
  🛡️ "Bounce Back" — Recovered from emotional setback
  🎯 "First Strike" — Started a dreaded task

BADGES IN PROGRESS:
  🌅 "Early Bird" — Morning routine 5x → 3/5 (2 more!)
  🏔️ "Summit" — Complete a boss task (full page redesign)
  🏃 "Active Life" — Exercise 3x in a week → 0/3

TODAY'S QUESTS:
  🔨 Complete wireframe step 5 → +10 XP
  📱 Reply to 4 messages → +20 XP (bonus: social quest!)
  💧 Drink 8 glasses of water → +15 XP

  Total available today: 45 XP
  If you get all three → 3,505 XP (only 495 to Level 8!)

You started today overwhelmed and ended with 4 tasks done.
That's not just productive — that's heroic with ADHD. 🦸

Keep going. You're closer to those headphones than you think. 🎧

Results: Calendar Entries & Tasks

After a full day with all 8 agents, these entries exist in the CalDAV server:

Daily Schedule (VEVENT)

Task Board (VTODO)

Habit Tracking (Knowledge Graph)

Daily Log Entry:
{
  "date": "2026-04-07",
  "medication": {"morning": "08:05", "afternoon": "12:40"},
  "water_glasses": 5,
  "exercise": false,
  "sleep_hours": 6.5,
  "tasks_completed": 4,
  "tasks_total": 5,
  "mood": 3,
  "xp_earned": 40,
  "xp_total": 3460,
  "level": 7,
  "streaks": {
    "medication": 13,
    "daily_checkin": 8,
    "water_target": 0,
    "exercise": 0
  },
  "notes": "RSD episode from client feedback. Recovered with EmotionBuddy."
}

ADHD-Specific Tips & Strategies

1. Time Blindness: Make Time Visible

ADHD brains cannot intuitively sense time passing. The DayAnchor agent uses time anchors — specific, visible time points — to create structure:

Instead of:  "Work on the project in the morning"
DayAnchor:   "09:00 Open Figma → 09:30 First wireframe done →
              10:00 Checkpoint → 10:45 Hard stop for break"

Practical tip: Place a large analog clock in your workspace. Digital time is abstract; analog time is visual — you can see how much time has passed.

2. Task Paralysis: The 2-Minute Rule

When you can’t start a task, the TaskBreaker agent applies the 2-Minute Rule: make the first step so trivially easy that NOT doing it feels silly.

Can't start writing a report?
  Step 1: Open the document (30 seconds)
  Step 2: Write your name and the date (30 seconds)
  Step 3: Write one sentence — any sentence (1 minute)

  → You're now "in" the task. Momentum takes over.

3. Hyperfocus: The Double-Edged Sword

Hyperfocus — the ability to intensely concentrate on engaging tasks — is an ADHD superpower when directed. The FocusGuard agent helps manage it:

• Productive hyperfocus: Set a 90-minute maximum with a mandatory break
• Harmful hyperfocus: 4 hours on social media or video games without noticing → FocusGuard prompts: “You’ve been scrolling for 45 minutes. Was this planned?”
• Transition warning: “5 minutes until your next time anchor. Start wrapping up.”

4. Rejection Sensitive Dysphoria (RSD)

RSD makes criticism feel like a physical blow. The EmotionBuddy agent:

• Never says: “You’re overreacting,” “Calm down,” “It’s not that bad”
• Always says: “That feels real. Let’s look at the facts together.”
• Separates fact from feeling: “The client gave feedback” ≠ “I’m terrible”
• Offers grounding: Box breathing, 5-4-3-2-1 senses, brief walk

5. Medication Timing Optimization

The HabitTracker agent correlates medication timing with productivity:

Insight from 2 weeks of tracking:
  📈 "Your best work days: meds taken before 08:15"
  📉 "Late medication (after 09:00) correlates with lower task completion"
  💡 "Consider setting meds + water next to your bed for immediate intake"

6. The “Done” List vs. To-Do List

For ADHD, to-do lists can feel defeating (so much undone!). The RewardSystem agent maintains a Done List alongside the to-do list:

Today's Done List:
  ✅ Took medication on time
  ✅ Opened Figma (beat the initiation barrier!)
  ✅ Completed 4 wireframe steps
  ✅ Handled difficult feedback
  ✅ Did daily check-in

  → That's 5 things done. On a hard day. That's winning.

7. Social Battery Management

ADHD can make social situations draining or cause accidental social neglect. The SocialPlanner agent helps by:

• Low-effort connection: “Send a 👍 to Tim’s meme” (10 seconds)
• Scheduled social time: Calendar blocks for calls and meetups
• Recovery time: Automatic buffer after social commitments
• No guilt: “You didn’t reply for 5 days because your executive function was busy elsewhere. That’s ADHD, not rudeness.”

8. Sleep Architecture for ADHD

Many ADHD adults have delayed sleep phase syndrome. The DayAnchor evening routine accounts for this:

21:00  🌙 Start wind-down (screens dim, no work)
21:30  📱 Phone charges OUTSIDE the bedroom
21:45  📖 Read or listen to calm audio (no screens)
22:00  💤 Lights out (even if not sleepy — rest counts)

Why this matters:
  Your peak focus window (9:30-12:00) depends on 7+ hours of sleep.
  6.5 hours last night → your focus today was 15-20% below potential.

9. Using Signal as Your ADHD Lifeline

With Signal integration, your agents are always in your pocket:

08:00 📱 DayAnchor → "Good morning! Meds + water first. ☀️"
10:00 📱 FocusGuard → "Checkpoint: Still on task? Rate 1-5."
12:30 📱 HabitTracker → "Afternoon meds time! 💊"
14:00 📱 EmotionBuddy → "How's your energy? 😊😐😟"
17:00 📱 PriorityCoach → "Tomorrow's top 3: ..."
21:00 📱 DayAnchor → "Wind-down time. Phone down in 30 min. 🌙"

Setup: See Signal Setup Guide.

10. When to Seek Professional Help

PiSovereign’s ADHD agents are support tools, not treatment. Seek professional help when:

• Medication needs adjustment (talk to your psychiatrist)
• Emotional dysregulation is persistent (consider ADHD-specialized therapy)
• Depression or anxiety co-occur (common ADHD comorbidities)
• Burnout symptoms appear despite good structure

Resources (search_web available for local providers):

• ADHD coaching (specialized executive function coaching)
• CBT for ADHD (cognitive behavioral therapy adapted for ADHD)
• Peer support groups (online and local)

Summary: With PiSovereign’s 8 ADHD support agents, you build an external executive function system — a “second frontal cortex” that provides structure, breaks down tasks, manages focus, tracks habits, celebrates progress, and supports emotional regulation. All data stays private on your own hardware. Remember: Every step counts. Starting again is the skill. 💚

Knowledge Visualization

PiSovereign includes an interactive 3D knowledge graph that lets you explore how your AI assistant’s memory works — watching knowledge form, connect, and naturally decay over time.

Accessing the Knowledge Graph

Navigate to Settings → Knowledge Graph (or visit /knowledge directly). The visualization loads on demand — the Three.js library (~600 KB) is only fetched when you open this page.

What You’re Looking At

The knowledge graph renders your AI’s memory as an interactive 3D network of nodes (memories) and edges (connections between them).

Node Colors

Node Size

Larger nodes are more important — they’ve been accessed more frequently or connected to more other memories.

Node Opacity

Opacity shows retention — how well the memory is preserved:

• Bright / fully opaque: Recently accessed, well-retained
• Fading / translucent: Decaying — hasn’t been accessed in a while
• Hidden: Below 10% retention — automatically hidden to reduce clutter

This uses the Ebbinghaus forgetting curve: memories fade exponentially but are reinforced each time they’re accessed (spaced repetition).

Edges

Lines connecting nodes represent causal or semantic relationships:

• Thickness: Stronger causal relationship = thicker line
• Animation: Animated edges show the direction of causal influence

Interacting with the Graph

Hover

Move your cursor over any node to see a tooltip with:

• Name: Short description of the memory
• Type: Episodic, Semantic, or Procedural
• Retention: Current retention percentage (e.g., “78%”)
• Source: Where the memory came from (conversation, email, calendar, etc.)
• Created: When the memory was first stored

Rotate and Zoom

• Click and drag: Rotate the 3D view
• Scroll wheel: Zoom in and out
• Right-click drag: Pan the view

Real-Time Updates

The graph updates in real-time via server-sent events (SSE). You’ll see:

• New nodes appearing when memories are created during conversations
• Nodes fading as time-based decay progresses
• New edges forming as the AI discovers connections between memories

Performance

The graph is designed to run smoothly even on lower-powered devices:

• Maximum 5,000 nodes displayed at once (most important nodes prioritized)
• Nodes below 10% retention are hidden automatically
• The Three.js renderer uses WebGL for hardware-accelerated graphics
• On devices without WebGL support, a simplified 2D fallback is used

Configuration

Administrators can adjust these settings in config.toml:

[knowledge_visualization]
enabled = true           # Enable/disable the visualization page
max_nodes = 5000         # Maximum nodes rendered
min_retention_threshold = 0.1  # Hide nodes below this retention (0.0–1.0)
sse_enabled = true       # Real-time updates via SSE

See Also

• Features Overview — High-level feature summary
• Innovation Features — Technical deep-dive (#19: Temporal Knowledge Decay Visualization)
• Memory System — How the RAG pipeline and memory stores work

Privacy Budget

PiSovereign uses a formal ε-privacy budget to give you full transparency and control over how your data is processed. Every operation that touches your personal data costs a small amount of privacy budget — and you can see exactly where it goes.

What Is ε (Epsilon)?

Epsilon (ε) is a number from differential privacy research that measures how much information an operation reveals about your data. A smaller ε means more privacy; a larger ε means less.

• Your daily budget: ε = 1.0 (default), which allows roughly 1,000 typical operations per day
• Budget resets: Every day at midnight (local time)

Think of it like a daily data allowance — each AI operation uses a tiny bit, and you can always see how much is left.

The Dashboard Widget

On the Sovereignty page, you’ll find a circular progress indicator showing your privacy budget status:

Status Colors

What Each Operation Costs

The dashboard also shows a breakdown of which operations consumed the most budget today.

What Happens When the Budget Is Exhausted

When your daily budget runs out, PiSovereign does not stop working. Instead, it degrades gracefully:

1. First: New embedding operations pause — memories are still stored as text, but won’t be vectorized until tomorrow
2. Second: Semantic search falls back to keyword-based full-text search (still works, slightly less accurate)
3. Third: Federated sync is paused until budget resets

Your conversations continue normally. The AI can still respond, access cached memories, and use all tools. Only new privacy-consuming operations are paused.

Adjusting Your Budget

You can change your daily budget in config.toml:

[privacy_budget]
enabled = true           # Set to false to disable budget tracking entirely
daily_epsilon = 1.0      # Daily budget (higher = more operations allowed)
embedding_cost = 0.001   # Cost per embedding operation
warn_threshold = 0.5     # Show warning at this consumption level (0.0–1.0)
exhaust_threshold = 0.9  # Enter degraded mode at this level (0.0–1.0)

Recommendations

• Default (1.0): Good balance for typical usage
• Lower (0.5): Maximum privacy — suitable if you want minimal data processing
• Higher (2.0): More headroom — suitable for heavy usage with many integrations active
• Disabled: Set enabled = false if you don’t want budget tracking (all operations proceed without accounting)

Why This Matters

Most AI assistants process your data with no visibility into what’s happening. PiSovereign’s privacy budget gives you:

• Transparency: See exactly which operations consume privacy budget
• Control: Set your own limits based on your comfort level
• Accountability: Historical logs of all privacy-consuming operations
• Compliance: Formal ε-accounting for GDPR and similar regulations

See Also

• Features Overview — High-level feature summary
• Innovation Features — Technical deep-dive (#22: Formal ε-Privacy Budget)
• Sovereign Intelligence Engine — How the privacy budget integrates with other features

Mesh & Federated Network

PiSovereign can connect with other PiSovereign instances on your local network to share computing power and collectively improve AI quality — all while keeping your data private.

Two Features, One Network

The mesh network provides two complementary capabilities:

Both features share the same peer discovery and trust infrastructure.

Setting Up

1. Enable the Features

In config.toml on each PiSovereign instance:

[mesh]
enabled = true
discovery = "mdns"          # Automatic LAN discovery
serve_inference = true      # Allow peers to use your compute
max_concurrent_peer_requests = 2
request_timeout_secs = 60

[federated_learning]
enabled = true
sync_after_n_samples = 5    # Sync after every 5 training samples
max_peers = 10
noise_epsilon = 1.0         # Differential privacy noise level
aggregation_method = "fedavg"

2. Pair Your Instances

Peers must be manually approved — there is no automatic trust. Two methods:

Shared Secret (Recommended)

1. On Instance A: Generate a pairing code from Settings → Network → Generate Pairing Code
2. On Instance B: Enter the code in Settings → Network → Add Peer
3. Both instances confirm the pairing

QR Code

1. On Instance A: Display QR code from Settings → Network
2. On Instance B: Scan the QR code (if the device has a camera)

3. Verify Connection

After pairing, the Settings → Network page shows connected peers with:

• Peer name and IP address
• Connection status (🟢 Connected / 🔴 Offline)
• Available models on the peer
• Last sync timestamp (for federated learning)

How Mesh Inference Works

When you send a message and your local Ollama is busy, overloaded, or throttled due to heat:

Your Query
    │
    ▼
Local Ollama ──(busy/hot)──► Peer Ollama ──(unavailable)──► Cached Response
    │                              │                              │
    ▼                              ▼                              ▼
  Response                      Response                    Degraded Response
  (normal)                   (⚡ Mesh-assisted)            (from template)

The fallback chain:

1. Local Ollama — always tried first
2. Peer Ollama — lowest-latency peer with the requested model, E2E encrypted
3. Cached response — from semantic cache if a similar query was answered before
4. Template response — generic acknowledgment (“I’m currently limited, but here’s what I know…”)

What Gets Sent to Peers

• Your query text (encrypted with the peer’s public key)
• The requested model name
• Nothing else — no conversation history, no memories, no user profile

How Federated Learning Works

After your PiSovereign collects 5 new training samples (from your feedback — thumbs up/down, corrections):

1. Local training: LoRA adapter weights are updated locally
2. Privacy noise: Laplace noise (ε = 1.0) is added to the weight deltas
3. Encrypted sync: Noisy deltas are encrypted and sent to each trusted peer
4. FedAvg aggregation: Each peer averages the received deltas with their own
5. Privacy budget: The sync operation consumes ε from your formal privacy budget

What gets shared:

• LoRA weight deltas (small numeric arrays) with differential privacy noise
• Not shared: Your conversations, memories, personal data, or training samples

Think of it like this: You’re sharing “the AI got a bit better at this type of question” without sharing what the question was.

Discovery

mDNS (Default)

PiSovereign uses multicast DNS (mDNS/Avahi) for zero-configuration discovery on the local network. This means:

• LAN only — peers must be on the same network segment
• No internet required — everything stays local
• Automatic — new instances appear in the peer list without manual IP entry

Requirements

• mDNS/Avahi must be available (installed by default on most Linux distributions and Raspberry Pi OS)
• UDP port 5353 must not be blocked by local firewall
• Devices must be on the same subnet

Security

Troubleshooting

Peers Not Discovered

1. Verify both instances are on the same subnet
2. Check that mesh.enabled = true in both config files
3. Test mDNS: avahi-browse -a should show PiSovereign services
4. Check firewall: UDP 5353 must be open

Mesh Inference Slow

1. Check peer’s thermal state — it may be throttling
2. Verify the peer has the requested model downloaded
3. Try increasing request_timeout_secs
4. Check network latency: ping <peer-ip>

Federated Sync Not Working

1. Verify federated_learning.enabled = true on both peers
2. Check privacy budget — syncs pause when budget is exhausted
3. Ensure at least sync_after_n_samples training samples have been collected
4. Check logs: docker logs pisovereign 2>&1 | grep federated

See Also

• Features Overview — High-level feature summary
• Innovation Features — Technical deep-dive (#30: Federated Learning, #31: Mesh Network)
• Privacy Budget — How federated syncs consume privacy budget
• Sovereign Intelligence Engine — Signal bus integration

Troubleshooting

Solutions for common issues with PiSovereign

Quick Diagnostics

Run these commands first to identify the problem:

# Check all containers are running
docker compose ps

# Health check
curl http://localhost/health | jq

# Detailed readiness
curl http://localhost/ready/all | jq

# Recent logs
docker compose logs --tail=100 pisovereign

# System resources
docker stats --no-stream

Hailo AI HAT+

Device not detected

Symptom: Hailo device not available inside the container

Diagnosis:

# Check device files on the host
ls -la /dev/hailo*

# Check kernel module on the host
lsmod | grep hailo

# Check PCIe
lspci | grep -i hailo

Solutions:

1. Check physical connection — ensure the HAT+ is fully seated on GPIO pins, PCIe FPC cable is connected, and you are using the 27W USB-C power supply

2. Reinstall drivers on the host:

   sudo apt remove --purge hailo-*
   sudo apt autoremove
   sudo reboot
   sudo apt install hailo-h10-all
   sudo reboot
   

3. Check device passthrough — ensure docker-compose.yml maps /dev/hailo0 into the container

Hailo firmware error

# Reset the device (on host)
sudo hailortcli fw-control reset

# Update firmware
sudo apt update && sudo apt upgrade hailo-firmware

Inference Problems

Inference timeout

Diagnosis:

# Test Ollama directly inside Docker
docker compose exec ollama curl -s http://localhost:11434/api/generate \
  -d '{"model":"qwen2.5-1.5b-instruct","prompt":"Hi","stream":false}'

Solutions:

1. Increase timeout:

   [inference]
   timeout_ms = 120000  # 2 minutes
   

2. Use a smaller model:

   [inference]
   default_model = "llama3.2-1b-instruct"
   

Model not found

# List models
docker compose exec ollama ollama list

# Pull missing model
docker compose exec ollama ollama pull qwen2.5-1.5b-instruct

Poor response quality

Adjust in config.toml:

[inference]
max_tokens = 4096
temperature = 0.5  # Lower = more focused

If model routing is enabled, ensure complex queries use a capable model:

[model_routing.models]
complex = "gemma4:31b"

Model routing — wrong tier selected

Check Prometheus metrics to see tier distribution:

curl -s http://localhost:3000/metrics/prometheus | grep model_routing

If too many requests go to the Simple tier, lower max_simple_words or add more complex_keywords:

[model_routing.classification]
max_simple_words = 10
complex_keywords = ["code", "implement", "explain", "analyze", "compare"]

Model routing — Ollama out of memory

When multiple models are loaded, Ollama may run out of RAM. Reduce the number of concurrent models:

# compose.yml
OLLAMA_MAX_LOADED_MODELS: 1

Or use smaller models for the Simple and Moderate tiers.

Network & Connectivity

Connection refused

Diagnosis:

# Check containers
docker compose ps

# Check Traefik is routing
docker compose logs traefik | tail -20

# Test direct container access
docker compose exec pisovereign curl -s http://localhost:3000/health

Solutions:

1. Check bind address in config.toml:

   [server]
   host = "0.0.0.0"
   

2. Check Traefik configuration — verify domain and routing rules in docker/traefik/dynamic.yml

TLS/SSL errors

• Development: Use http://localhost (Traefik handles TLS for external access)
• Production: Ensure your domain’s DNS points to the server, and Let’s Encrypt can reach port 80 for validation
• Self-signed certs (e.g., Proton Bridge): set verify_certificates = false in the relevant config section

Database Issues

Database locked

Cause: Multiple concurrent writers to SQLite

Solutions:

1. Ensure single PiSovereign instance:

   docker compose ps | grep pisovereign
   # Should show exactly one instance
   

2. Verify WAL mode:

   docker compose exec pisovereign sqlite3 /data/pisovereign.db "PRAGMA journal_mode;"
   # Should return "wal"
   

Migration failed

# Backup current database
docker compose exec pisovereign cp /data/pisovereign.db /data/pisovereign-backup.db

# Reset database (LOSES DATA — restore from backup afterward)
docker compose exec pisovereign rm /data/pisovereign.db
docker compose restart pisovereign

Database corruption

# Attempt recovery
docker compose exec pisovereign sh -c \
  'sqlite3 /data/pisovereign.db ".recover" | sqlite3 /data/pisovereign-recovered.db'

Integration Problems

WhatsApp

Webhook verification failed:

1. URL must be publicly accessible — test with curl from an external network
2. verify_token in config.toml must match the Meta developer console
3. HTTPS must be configured (Traefik handles this)

Messages not received:

1. Check webhook is subscribed to the messages field in Meta console
2. Verify phone number is whitelisted (for test numbers)
3. Check logs: docker compose logs pisovereign | grep -i whatsapp

Email (IMAP/SMTP)

Connection refused:

# Test IMAP from the container
docker compose exec pisovereign openssl s_client -connect imap.gmail.com:993

• Verify host/port match your provider (see External Services)
• For Proton Bridge: ensure Bridge is running on the host
• If using the provider field, explicit imap_host/smtp_host values override presets

Authentication failed:

• Gmail: Use an App Password, not your account password
• Outlook: Use an App Password if 2FA is enabled
• Proton Mail: Use the Bridge Password from the Bridge UI, not your Proton account password

Migrating from [proton] config: The old [proton] config section still works via a serde alias. If you see “duplicate field” errors, ensure you don’t have both [proton] and [email] sections in your config.

CalDAV

401 Unauthorized:

docker compose exec pisovereign curl -u username:password \
  http://baikal:80/dav.php/calendars/username/

Verify user exists in Baïkal admin at http://localhost/caldav.

404 Not Found — PiSovereign automatically re-creates missing calendars and address books. If you still see 404 errors:

• Verify calendar_path matches your Baïkal user and calendar name
• Check that the user has permissions to create calendars
• List calendars to verify:

docker compose exec pisovereign curl -u username:password -X PROPFIND \
  http://baikal:80/dav.php/calendars/username/

Speech Processing

Whisper (STT) fails

# Check Whisper container
docker compose logs whisper

# Test directly
docker compose exec whisper curl -s http://localhost:8081/health

• Verify the container has enough memory (~500 MB for base model)
• Check audio format (mono 16 kHz WAV preferred)

Piper (TTS) fails

# Check Piper container
docker compose logs piper

# Test directly
docker compose exec piper curl -s http://localhost:8082/health

• Verify voice model files are mounted correctly
• Check container logs for ONNX runtime errors

Memory System (RAG)

Memories not being retrieved

1. Check that enable_rag = true in [memory] config
2. Verify rag_threshold isn’t too high — try lowering to 0.3
3. Ensure embeddings are generated: GET /v1/memories/stats should show entries with embeddings
4. Confirm Ollama is running with the nomic-embed-text embedding model

Encryption key errors

• “Read-only file system”: Ensure encryption_key_path points to a writable directory (e.g., /app/data/memory_encryption.key in Docker)
• Lost encryption key: Encrypted memories cannot be recovered. Delete the key file, clear the memories and memory_embeddings tables, and let PiSovereign generate a new key on startup

Memory decay not running

The decay task runs automatically every 24 hours. Check logs for memory decay task entries. You can also trigger it manually via POST /v1/memories/decay.

System Commands

Commands not auto-populating

On first startup, 32 default system commands should be auto-discovered. If empty:

1. Check logs for system_command_discovery entries
2. Verify the database migration 14_system_commands.sql ran successfully
3. Check GET /v1/commands/catalog/count — should return {"count": 32}

Startup warnings about Vault credentials

PiSovereign validates Vault credentials at startup and logs diagnostic warnings for missing or empty fields. Check the log line Some configuration fields are empty after secret resolution for affected fields. Store the missing secrets in Vault using just docker-vault-check.

Performance Issues

High memory usage

docker stats --no-stream

Reduce resource consumption in config.toml:

[cache]
l1_max_entries = 1000

[database]
max_connections = 3

Slow response times

1. Check inference latency — the model may be too large for your hardware
2. Enable caching: [cache] enabled = true
3. Use SSD storage — SD card I/O is a common bottleneck on Raspberry Pi

Getting Help

Collect Diagnostic Information

Before reporting an issue, gather:

# Container status
docker compose ps

# PiSovereign version
docker compose exec pisovereign pisovereign-server --version

# Recent logs
docker compose logs --since "1h" > pisovereign-logs.txt

# System info
uname -a
docker --version
free -h
df -h

Report an Issue

• GitHub Issues: github.com/twohreichel/PiSovereign/issues — include diagnostic info and reproduction steps
• Security Issues: Report privately via GitHub Security Advisories
• Discussions: GitHub Discussions for questions and help

Frontend Screenshot Gallery

Auto-generated — These screenshots are captured automatically by Playwright. Run npx playwright test --project=screenshots from the frontend directory to regenerate them.

This gallery showcases every page and major interaction available in the PiSovereign web interface. Use it as a visual reference when exploring features, writing documentation, or onboarding new users.

Table of Contents

• Dashboard
• Chat
• Conversations
• Memory & RAG
• Calendar
• Tasks
• Kanban Board
• Contacts
• Mailing
• Reminders
• Commands
• Approvals
• Agentic Workflows
• System Status
• Settings
• Navigation & Responsive Design