# Plan: Finalize dev-env Setup

## Goal
Complete the reproducible Python dev environment setup so all four capability pillars (web/desktop/AI-ML, Wan2.1 video, faster-whisper STT, Kokoro/Dia TTS) can run locally. The `run_all.sh` should start FastAPI (port 8080) and Ollama (port 11434) and both respond to health checks.

## Current State (2026-11-04)
- **12 files** in `dev-env/` (10 starter + `setup_env.sh`, `requirements.txt`, `run_all.sh`, `stop_all.sh`, `SETUP.md`, `REPORT.md`)
- `.venv/` exists with **lightweight packages installed**: fastapi, uvicorn, pydantic, numpy, Pillow, tqdm, soundfile, huggingface-hub — `fastapi_app.py` imports OK
- **ML packages missing**: torch, transformers, diffusers, accelerate, faster-whisper
- `requirements.txt` contains **PLACEHOLDER hashes** (not real SHA256)
- `setup_env.sh` uses `--require-hashes` unconditionally → fails on placeholders
- `--generate-hashes` aborted during torch wheel download (~906 MB stalled at ~95 MB)
- Network: `files.pythonhosted.org` resolves but large wheels stall/fail midway
- Ollama running at `localhost:11434` with models phi3.5, dolphin-cb26, qwen3-embedding:0.6b
- No GPU (`nvidia-smi` not found) → CPU-only mode
- Git: branch `dev-env-multimodal-setup` pushed to origin

## Constraints
- No root/sudo (script enforces this)
- `--require-hashes` must work OR be skipped for placeholder entries
- CPU-only (no CUDA), ~48 GB disk free
- All Hugging Face downloads must use pinned revision SHA (no `trust_remote_code`)
- All `torch.load` must use `weights_only=True` (already verified)
- API keys (`DEV_ENV_API_KEY`, `HF_TOKEN`) sourced only from env vars

## Tasks

### 1. Fix `setup_env.sh` for hash-less install path
**Location**: `dev-env/setup_env.sh:137-138`
- Detect if `requirements.txt` contains placeholder hashes (`PLACEHOLDER_REPLACE_ME_64_HEX_CHARS`)
- If placeholders present: run `pip install -r requirements.txt` **without** `--require-hashes`
- If real hashes present: keep current `--require-hashes` behavior
- Add flag `--skip-hashes` to explicitly force hash-less install

### 2. Install ML packages
- Run fixed `setup_env.sh` (or `pip install` directly) to install: torch 2.5.1 (CPU wheel), transformers 4.46.3, diffusers 0.31.0, accelerate 1.4.0, faster-whisper 1.1.1
- Use background process with retry logic for network stalls
- Verify imports: `python -c "import torch, transformers, diffusers, accelerate, faster_whisper"`

### 3. Test `run_all.sh` startup
- Execute `./run_all.sh` from `dev-env/`
- Verify FastAPI health endpoint: `curl -H "Api-Key: <DEV_ENV_API_KEY>" http://127.0.0.1:8080/health`
- Verify Ollama: `curl http://127.0.0.1:11434/api/tags`
- Both must respond within 10 seconds

### 4. Verify starter scripts run (smoke test)
- `python starter/web/fastapi_app.py` — starts without error
- `python starter/desktop/tkinter_app.py` — window opens (headless OK)
- `python starter/scripts/ai_ml_starter.py` — inference loop runs on CPU
- `python starter/stt/whisper_starter.py` — loads faster-whisper small
- `python starter/tts/kokoro_starter.py` — loads Kokoro-82M
- GPU-dependent scripts (wan21_starter.py, dia_starter.py) marked as skipped in CPU mode

## Validation
- [ ] `setup_env.sh` runs to completion without errors
- [ ] All 14 packages from `requirements.txt` appear in `pip list`
- [ ] ML imports succeed in `.venv`
- [ ] `run_all.sh` starts both services and health checks pass
- [ ] `stop_all.sh` cleanly stops both services
- [ ] Security: no root execution, no `trust_remote_code=True`, all `torch.load(weights_only=True)`

## Rollback
- If ML packages fail: keep lightweight packages, document CPU-only limitations in `SETUP.md`
- If `run_all.sh` fails: check port conflicts (8080, 11434), verify `DEV_ENV_API_KEY` is set
- Git: current branch `dev-env-multimodal-setup` is safe; no changes to main branch

## Open Questions
1. Should we generate real SHA256 hashes for `requirements.txt` after successful install (for future reproducibility)?
   - *Recommendation*: Yes — run `pip hash` on installed wheels post-install and update `requirements.txt`
2. Should `--skip-hashes` be the default when placeholders detected, or require explicit flag?
   - *Recommendation*: Auto-detect placeholders → auto-skip (safer UX, explicit `--require-hashes` still works for real hashes)
3. Timeout/retry policy for background pip installs?
   - *Recommendation*: 30 min per package, 3 retries, exponential backoff

## Acceptance Criteria
- `./setup_env.sh` completes in < 30 min (including ML packages)
- `./run_all.sh` starts both services; health checks return 200
- All 5 CPU starter scripts execute without import errors
- No security findings (root, trust_remote_code, shell=True, missing weights_only)