How selfhoster-sh/pisynapse works
piSynapse is a self-hosted personal AI assistant whose main workflow takes a user’s chat turn through intent and memory retrieval, local-model response/tool calling, optional verification, and persistence. Tool dispatch fans out to calendar, email, notes, tasks, and weather services; separate branches provide search, accounts/settings, and media features. The excerpts and source index establish the main chat, LLM, tools, and storage links; some feature wiring is documented only in the README, so those links are cited there.
Main entry points: routers/chat.py Chat API · llm/chat.py LLM Bridge · dispatcher.py Tool Dispatcher · ui.js Web UI and PWA
Components 22
User Experience
- Web UI and PWA
static/ui.js - Chat API
routers/chat.py - Voice and Images
routers/media.py - Hybrid Search
retrieval.py
Conversation Intelligence
- Intent Routing
llm/intent.py - Memory and Context
prompt.py - LLM Bridge
llm/chat.py - Request Payloads
llm/payload.py - Local LLM
Tools and Integrations
- Tool Definitions
tools/definitions.py - Tool Dispatcher
tools/dispatcher.py - Tool Verification
tool_verification.py - Calendar
calendar_ops.py - Email
mail.py - Notes
nextcloud_notes.py - Tasks
nextcloud_tasks.py - Weather
weather.py
Identity and Storage
- Accounts and Auth
auth.py - Admin and Settings
routers/admin.py - SQLite Store
db.py - Runtime Configuration
config.py
Other components
- User
Connections 29
- User → Web UI and PWA: uses
- Web UI and PWA → Chat API: sends turns
- Chat API → Intent Routing: classifies
routers/chat.py - Chat API → Hybrid Search: retrieves history
routers/chat.py - Chat API → Memory and Context: builds context
routers/chat.py - Chat API → LLM Bridge: requests reply
routers/chat.py - LLM Bridge → Request Payloads: builds request
llm/chat.py - Request Payloads → Tool Definitions: adds schemas
llm/payload.py - LLM Bridge → Local LLM: calls model
- LLM Bridge → Tool Dispatcher: routes tool calls
llm/chat.py - Tool Dispatcher → Calendar: invokes
tools/dispatcher.py - Tool Dispatcher → Email: invokes
tools/dispatcher.py - Tool Dispatcher → Notes: invokes
tools/dispatcher.py - Tool Dispatcher → Tasks: invokes
tools/dispatcher.py - Tool Dispatcher → Weather: invokes
tools/dispatcher.py - LLM Bridge → Tool Verification: verifies calls
llm/chat.py - Chat API → SQLite Store: persists turns
routers/chat.py - Hybrid Search → SQLite Store: queries sessions
retrieval.py - Memory and Context → SQLite Store: loads context
prompt.py - Voice and Images → User: accepts uploads
- Web UI and PWA → Hybrid Search: searches sessions
- Web UI and PWA → Voice and Images: submits media
- Web UI and PWA → Accounts and Auth: signs in
- Admin and Settings → Accounts and Auth: manages users
routers/admin.py - Admin and Settings → SQLite Store: updates records
routers/admin.py - Chat API → Accounts and Auth: checks identity
routers/chat.py - Chat API → SQLite Store: loads sessions
routers/chat.py - LLM Bridge → Calendar: uses calendar context
llm/chat.py - Runtime Configuration → LLM Bridge: configures backend
config.py