S.I.R.I.U.S: Reductionist Local Assistant Pipeline

Summary

S.I.R.I.U.S. is a reductionist personal assistant. No cloud, no AI models, no complex integrations. Just: parse intent, store data, display results. Built entirely in Python, it runs locally on your machine with zero external dependencies beyond FastAPI and Pydantic.

The core idea: simplicity reveals what matters. Remove features, keep value.

Highlights

• Minimal stack: FastAPI + Uvicorn + Pydantic + SQLite
• Local persistence: All data lives on disk, always available
• Real-time updates: WebSocket-driven dashboard with Alpine.js
• Deterministic parsing: Regex-based commands, no surprises
• Instant startup: ~50ms from launch to ready
• Zero cloud dependency: No API keys, no network required for core function

Architecture

Four Core Components

main.py - API Core

• FastAPI application server
• REST endpoints for command submission
• WebSocket hub for real-time dashboard updates
• Serves frontend assets dynamically

parser.py - Intent Recognition

• Pydantic validators sanitize input
• Regex routing detects command type
• Structured command objects for downstream processing
• Fast-fail with clear error messages

storage.py - Data Layer

• SQLite connection and schema management
• CRUD operations for transactions and events
• Simple queries, indexed for speed
• Local persistence, always accessible

public/index.html - Live Dashboard

• Alpine.js for reactive UI updates
• WebSocket client receives live data streams
• Command input form with immediate feedback
• Displays parsed commands and stored results

How It Works

1. User submits command: spend: 25.50 groceries
2. Parser validates: Regex matches spend:, extracts amount and category
3. Storage persists: SQLite writes transaction to local database
4. Dashboard updates: WebSocket broadcasts new entry in real-time

Supported Commands

Financial Tracking

1
2

spend: 25.50 groceries
income: 5000 salary

Calendar Events

1
2

cal: 2025-03-15 Project deadline
cal: 2025-04-20 Team meeting

Parser validates format, stores to database, broadcasts updates via WebSocket.

Design Decisions

Local-First Over Cloud

• Data lives on disk under your control
• No network latency, no vendor lock-in
• Simpler mental model: what you see is what you have
• ACID guarantees from SQLite

Text Parsing Over AI

• Deterministic regex beats LLM unpredictability
• Commands fail fast with clear error messages
• No hallucinations, no surprise behavior
• Speed: regex ~microseconds, LLM calls ~seconds

SQLite Over External Database

• Single file to backup, no deployment complexity
• ACID compliance for data integrity
• Suitable for personal-scale tracking
• Query anytime without network

Technical Notes

Command Flow

Input → Parser (Pydantic + Regex) → Validator → Storage (SQLite) → WebSocket → Dashboard

Error Handling

• Input validation before database write
• Strict schema enforcement
• Clear failure messages to user
• Atomic transactions prevent partial state

WebSocket Pattern

• Single broadcaster for all clients
• Parsed commands trigger updates
• No polling, low latency
• Scales to multiple UI instances

Challenges Addressed

• Data privacy: Everything local, no surveillance
• Simplicity: Stripped to essentials, nothing unnecessary
• Reliability: SQLite ACID, deterministic parsing
• Accessibility: Text commands anyone can type
• Speed: Instant startup, no initialization delays

Technical Stack

Frontend: HTML + Alpine.js (5KB min)
Backend: FastAPI (async, fast)
Database: SQLite (file-based, zero config)
Validation: Pydantic (strict type checking)
Protocol: WebSockets (real-time updates)

Getting Started

1. Install Dependencies

1

pip install fastapi uvicorn pydantic

2. Run the Engine

1

python main.py

Starts at http://127.0.0.1:8000

3. Run Tests

1
2

python test.parser.py     # Test parsing rules
python test.pipeline.py   # Test full end-to-end flow

Role & Contributions

• Designed the local-first architecture
• Built FastAPI core and WebSocket integration
• Implemented Pydantic-based parser with regex routing
• Created SQLite schema and query layer
• Authored Alpine.js dashboard UI
• Wrote comprehensive test suite

Outcomes

• Lightweight, deployable personal assistant
• Low memory footprint, instant startup
• Data sovereignty: no cloud dependency
• Clear, extensible command protocol
• Foundation for adding more command types

Future Directions

• Query interface for searching historical data
• Export to CSV for analysis
• Dashboard statistics and trends
• More command protocols (habits, notes, time tracking)
• Mobile web version (responsive design)

Repository

• GitHub: https://github.com/Devjosef/S.I.R.I.U.S.
• Status: Active development
• License: Open source