# 🎯 Icarus Phase 1 Completion Instructions

**To:** Socrates 🧠  
**From:** Wadsworth 📋 (validation report)  
**Date:** 2026-04-25  
**Status:** Hard fork 85% complete, 4 blocking items remain

---

## ✅ What's Done

| Task | Status | Evidence |
|------|--------|----------|
| Hard fork copy | ✅ Complete | 29 Python files in `icarus/core/` |
| Import rewrite | ✅ Complete | `icarus.core.*` pattern active |
| Production isolation | ✅ Complete | Zero `from family_assistant` imports |
| Cleanup | ✅ Complete | `.env`, `pycache`, `.pyc` removed |
| Symlinks | ✅ Complete | None found |

---

## 🔴 Blocking Issues (Phase 1 Incomplete)

### Issue 1: DATA_DIR Fallback Path
**Location:** `icarus/core/config.py`
**Problem:** Default fallback still points to `.family_assistant`
**Fix:**
```python
# CHANGE FROM:
DATA_DIR = Path(os.environ.get("DATA_DIR", Path.home() / ".family_assistant"))

# CHANGE TO:
DATA_DIR = Path(os.environ.get("DATA_DIR", Path.home() / ".icarus"))
```

---

### Issue 2: Package Metadata
**Location:** `icarus/core/pyproject.toml`
**Problem:** Still references `family-assistant` package name
**Fix:**
```toml
# CHANGE FROM:
[project]
name = "family-assistant"

# CHANGE TO:
[project]
name = "icarus"
```

Also update any `[tool.setuptools]` or `[project.scripts]` entries.

---

### Issue 3: Model Gate Integration (CRITICAL)
**Location:** All Ollama call sites
**Problem:** Model gate not imported or called
**Files to instrument:**
- `appointment_parser.py`
- `intent_engine.py`
- `family_brain.py`
- Any other LLM call sites

**Fix pattern:**
```python
# At top of file:
from icarus.core.utils.model_gate import validate_ollama_request

# Before every Ollama call:
validate_ollama_request(model_name)  # Raises if model not allowed

# Then proceed with ollama.chat() or ollama.embed()
```

**Updated Allowed Models (Director Override):**
```python
ALLOWED_MODELS = [
    # Primary (8B class for M4 16GB target)
    "llama3.1:8b",
    "llama3.1:8b-instruct-q4_K_M",
    "qwen2.5:7b",
    "qwen2.5:7b-instruct-q4_0",
    "qwen2.5-coder:7b",
    
    # Utility (3B class for fast tasks)
    "llama3.2:3b",
    "qwen2.5:3b",
    "phi3:mini",
]
```

**Model Selection Strategy:**
- Complex extraction, JSON, briefing → 8B
- Spam filtering, fast tasks → 3B

---

### Issue 4: Staging Config Module
**Location:** Create `icarus/core/config/staging.py`
**Problem:** Staging-specific config doesn't exist
**Create new file:**

```python
"""Icarus Staging Configuration — Completely Isolated."""
import os
from pathlib import Path

# Environment
ICARUS_ENV = "staging"
ICARUS_VERSION = "0.0.1"

# Data paths (isolated from production)
DATA_DIR = Path(os.environ.get("DATA_DIR", Path.home() / ".icarus/staging"))
CHROMA_DB_PATH = DATA_DIR / "chroma"
RADICALE_DATA_DIR = DATA_DIR / "radicale"
EMAIL_CACHE_DIR = DATA_DIR / "email_cache"
UNDO_STACK_PATH = DATA_DIR / "undo_stack.jsonl"

# Ollama (Gaming PC via Tailscale)
# Updated: 8B models cleared for M4 16GB simulation
OLLAMA_BASE_URL = os.environ.get(
    "OLLAMA_BASE_URL",
    "http://matt-pc.tail864e81.ts.net:11434"
)

# Model selection strategy:
# - 8B class: Complex extraction, JSON, briefing generation
# - 3B class: Spam filtering, fast summarization
OLLAMA_PRIMARY_MODEL = os.environ.get("OLLAMA_PRIMARY_MODEL", "llama3.1:8b")
OLLAMA_UTILITY_MODEL = os.environ.get("OLLAMA_UTILITY_MODEL", "llama3.2:3b")
OLLAMA_EMBED_MODEL = os.environ.get("OLLAMA_EMBED_MODEL", "nomic-embed-text")

# Telegram (test bot — NOT production)
TELEGRAM_BOT_TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")
TELEGRAM_CHAT_ID_FAMILY = os.environ.get("TELEGRAM_CHAT_ID_FAMILY")
TELEGRAM_CHAT_ID_MATT = "8386527252"

# Gmail (test account — NOT family account)
GMAIL_USER = os.environ.get("GMAIL_USER", "icarus.test.staging@gmail.com")
GMAIL_APP_PASSWORD = os.environ.get("GMAIL_APP_PASSWORD")
IMAP_SERVER = "imap.gmail.com"

# Webhook (staging secret)
WEBHOOK_SECRET = os.environ.get("WEBHOOK_SECRET")

# Radicale (test calendar — port 5233)
RADICALE_HOST = os.environ.get("RADICALE_HOST", "127.0.0.1")
RADICALE_PORT = int(os.environ.get("RADICALE_PORT", "5233"))
RADICALE_URL = f"http://{RADICALE_HOST}:{RADICALE_PORT}"

# API (staging — port 8001)
API_HOST = os.environ.get("API_HOST", "0.0.0.0")
API_PORT = int(os.environ.get("API_PORT", "8001"))
DEBUG = os.environ.get("DEBUG", "true").lower() == "true"

# Timezone
CHICAGO_TZ = "America/Chicago"
```

---

## 🎯 Phase 1 Completion Criteria

Verify before declaring Phase 1 complete:

```bash
# Run these checks from services/icarus/

# 1. No family_assistant references (should return 0)
grep -r "from family_assistant\." core/
grep -r "import family_assistant" core/

# 2. DATA_DIR fallback is .icarus (not .family_assistant)
grep "DATA_DIR" core/config.py

# 3. Model gate imported
grep -r "from icarus.core.utils.model_gate" core/
grep -r "validate_ollama_request" core/

# 4. Staging config exists
ls core/config/staging.py

# 5. Package name updated
grep "^name" core/pyproject.toml | grep -v "family"
```

---

## 🚀 Phase 2 Trigger

After all checks pass:

1. **Create api.py entry point:**
```python
# icarus/core/api.py
from fastapi import FastAPI
import os

assert os.environ.get("ICARUS_ENV") == "staging"

app = FastAPI(title="Icarus", version="0.0.1")

@app.get("/health")
async def health():
    return {"status": "ok", "env": "icarus-staging"}
```

2. **Test locally:**
```bash
cd /home/hoffmann_admin/.openclaw/workspace/services/icarus
source staging.env
python3 -c "from icarus.core.api import app; print('Import OK')"
```

3. **Wadsworth will:**
   - Create systemd service file
   - Coordinate with Matt for sudo deployment
   - Verify `curl https://icarus-test.hoffdesk.com/health` returns 200

---

## Summary

| Item | Status | Time Estimate |
|------|--------|---------------|
| DATA_DIR fallback | 🔴 Blocking | 5 min |
| Package metadata | 🔴 Blocking | 10 min |
| Model gate integration | 🔴 Blocking | 30 min |
| Staging config | 🔴 Blocking | 20 min |
| **Total remaining** | | **~1 hour** |

**Execute. Report back when checks pass.**

---

*Questions: @mention Wadsworth in The Hoffmann Board*