Icarus — Sovereign Document Intelligence Platform

Status: Phase 6.1 Active — Document routing, vision extraction, calendar integration
Source: Evolution from family_assistant v1.0 (superseded)
Sovereign Stack: Local vision models (qwen3-vl:8b), Radicale calendar, Event Graph

Architecture

Document (image/PDF/text)
    ↓
Vision Pipeline (qwen3-vl:8b on Gaming PC via Tailscale)
    ↓
Document Classification
    ├── calendar_event → Briefing + [🗓️ Add to Calendar] → Radicale
    ├── coordination → Event Graph (for HBM Week Brief)
    └── info → Brief only
    ↓
Family Routing (inference_rules.yaml — deterministic patterns)
    ↓
Briefing Generation (8B LLM — phi4:14b or cloud fallback)
    ↓
Action Buttons → Telegram bot

Components

Vision Pipeline

• Model: qwen3-vl:8b via Gaming PC (Tailscale)
• Input: Images, PDFs, screenshots, forwarded emails
• Output: Structured extraction (dates, times, names, context)
• Fallback: Hybrid PDF parsing (text first, vision fallback)

Document Classification

• calendar_event: Specific time + venue → Calendar + Event Graph
• coordination: Dates, no specific time → Event Graph only (for HBM planning)
• info: No actionable dates → Brief only

Family Routing

• Rules: YAML-based (inference_rules.yaml)
• Pattern matching: Grade-based, name-based, parent/role-based
• Confidence scoring: Deterministic pre-match → LLM fallback
• Target members: sully, harper, aundrea, matt

Event Graph

• Storage: SQLite (briefing_events table)
• Schema: document_id, type, dates, assigned_to, child, context, confidence
• Purpose: Phase 7 HBM — Week Brief generation, coordination tracking
• Query: /api/event_graph/recent for dashboard

Briefing Generation

• Model: phi4:14b (local) or glm-5.1 (cloud fallback)
• Output: Title, summary, key_details, deadlines, actions, category
• Action buttons: [🗓️ Add to Calendar] [✏️ Edit Details]
• Confirmation flow: Success → edit/delete options

Calendar Integration

• Backend: Radicale CalDAV (self-hosted)
• Conflict detection: Overlap detection with grace period
• Resolution: LLM-suggested splits, reassignments

API Endpoints

Document Processing

• POST /document/upload — Accept image/PDF, return document_id
• POST /document/process — Run vision extraction
• GET /document/{id}/status — Processing status
• GET /document/{id}/briefing — Generated briefing card

Event Graph

• GET /api/event_graph/recent — Recent documents for dashboard

Calendar Actions

• POST /calendar/add — Create Radicale event (from briefing button)
• GET /calendar/conflicts — Detect overlapping events

Environment Setup

Production (Port 8000)

• Endpoint: icarus.hoffdesk.com
• Data: ~/.icarus/production/
• Models: Gaming PC via Tailscale

Staging (Port 8001)

• Endpoint: icarus-test.hoffdesk.com
• Data: ~/.icarus/staging/
• Models: Gaming PC (3B for speed, 7B+ for quality)

Cloudflare Routing

# config.yml — specific before wildcard
ingress:
  - hostname: icarus-test.hoffdesk.com
    service: http://localhost:8001
  - hostname: "*.hoffdesk.com"
    service: http://localhost:8000

Model Configuration

Telegram Bot

• Production: @hoffdesk_bot
• Staging: @IcarusTestBot (t.me/IcarusTestBot)

Commands:
- Upload document → Vision extraction → Briefing with action buttons
- Click [🗓️ Add to Calendar] → Radicale event + confirmation

Phase Status

Sovereign Constraints

• Local-first: Vision models on Gaming PC via Tailscale
• No cloud default: API calls only for overflow/fallback
• Self-hosted calendar: Radicale, not Google/Apple
• No OAuth: App passwords, session cookies
• Data ownership: SQLite + flat files, not SaaS

Related Repos

• family-assistant — Legacy v1.0 (superseded by Icarus)
• hoffdesk-config — Agent coordination + shared specs
• costco-route — Standalone shopping optimizer

File Structure

icarus/
├── core/
│   ├── api.py              # FastAPI endpoints
│   ├── pipeline.py         # Vision → Classification → Routing
│   ├── briefing/           # Briefing generation
│   ├── calendar/            # Radicale integration (calendar_sync.py)
│   ├── db/                  # Event Graph (SQLite)
│   ├── handlers/            # Telegram callbacks
│   ├── vision/              # PDF/image processing
│   ├── prompts/             # LLM prompts (text files)
│   ├── config/              # Environment configs
│   └── family.yaml.example  # Family routing config
├── jobs/                    # Scheduled tasks (daily briefing, premarket)
├── templates/               # HTML templates (system state dashboard)
├── config/families/         # Family YAML configs
├── appliance/               # Deployment scripts
└── tests/                   # Unit + integration tests

Last updated: 2026-04-28 by Socrates