# 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
```yaml
# config.yml — specific before wildcard
ingress:
  - hostname: icarus-test.hoffdesk.com
    service: http://localhost:8001
  - hostname: "*.hoffdesk.com"
    service: http://localhost:8000
```

---

## Model Configuration

| Task | Local (Gaming PC) | Cloud Fallback |
|------|-------------------|----------------|
| Vision extraction | qwen3-vl:8b | — |
| Document classification | phi3:mini | qwen2.5:7b |
| Briefing generation | phi4:14b | glm-5.1 |
| Conflict resolution | llama3.1:8b | kimi-k2.5 |

---

## 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

| Phase | Status | Features |
|-------|--------|----------|
| Phase 5 | ✅ Complete | Vision pipeline, routing rules |
| Phase 6.1 | ✅ Complete | Document Intelligence, Event Graph persistence |
| Phase 6.2 | Planned | IMAP Ingress (iCloud) |
| Phase 6.3 | Planned | Drop Zone share sheet |
| Phase 6.4 | Planned | Finance Intelligence |
| Phase 7 | Planned | HBM — Hierarchical Briefing Model |
| Phase 8 | Planned | Silent Observer (ambient coordination) |

---

## 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*