# LLMHosts.com -- Full PM Roadmap

## META
- layer: 3 of 3 (Full PM)
- synced_with: executive.md, detailed.md
- last_updated: 2026-02-22
- version: 4.0 (STATUS SYNC)

## USER STORIES BY EPIC

### Epic: Onboarding (CLI-First, Tiered Install)
| ID | User Story | Acceptance Criteria | Phase | Priority |
|----|-----------|-------------------|-------|----------|
| US-OB-01 | As a developer, I want a lightweight core install | `pip install llmhosts` (~50MB) in <1 min, Python 3.10+ | 1 | P0 |
| US-OB-01a | As a developer, I want ML routing intelligence | `pip install llmhosts[smart]` (~150MB, ONNX) in <3 min | 1 | P0 |
| US-OB-01b | As a power user, I want full intelligence | `pip install llmhosts[full]` (~2GB, PyTorch) | 1 | P1 |
| US-OB-02 | As a developer, I want one command to start | `llmhosts serve` starts proxy (OpenAI + Anthropic) on :4000 in <5s | 1 | P0 |
| US-OB-03 | As a user, I want Ollama auto-discovered | Detects Ollama, lists models, within 10s | 1 | P0 |
| US-OB-04 | As a user, I want to add cloud API keys | `llmhosts keys add openai <key>` validates + stores encrypted | 1 | P0 |
| US-OB-05 | As a user, I want model recommendations | `llmhosts suggest-models` + tier upgrade suggestions | 1 | P1 |
| US-OB-06 | As a user, I want Docker alternative | `docker run --gpus all llmhost/llmhost` works | 1 | P1 |
| US-OB-07 | As a user, I want my GPU from anywhere | `llmhosts tunnel` auto-detects Tailscale/Cloudflare, HTTPS in <30s | 2 | P0 |
| US-OB-08 | As a JS/TS dev, I want easy setup | `npx create-llmhosts` scaffolds docker-compose + config | 2 | P1 |
| US-OB-09 | As a user, I want an account | Web signup for cloud dashboard, multi-device, Pro tier | 2 | P1 |

### Epic: Conductor (Three-Tier Hybrid Router)
| ID | User Story | Acceptance Criteria | Phase | Priority |
|----|-----------|-------------------|-------|----------|
| US-CB-01 | As a user, I want intelligent fit-for-purpose routing | Three-tier: kNN (75%, <15ms) + ModernBERT (20%, <50ms) + Qwen-0.5B (5%, <500ms) | 1 (rule+kNN), 2 (full) | P0 |
| US-CB-02 | As a user, I want to set model preferences | Preferences respected as Tier 0 overrides | 2 | P1 |
| US-CB-03 | As a user, I want to see WHY a model was chosen | Tier, model, reason, confidence, alternatives in metadata | 2 | P1 |
| US-CB-04 | As a user, I want routing to improve over time | Router trained on usage + feedback, measurably better | 2-3 | P1 |
| US-CB-05 | As a user, I want my feedback to matter | Thumbs up/down feeds into kNN + ModernBERT retraining | 2 | P1 |
| US-CB-06 | As a GPU-less user, I want affordable AI | Router picks cheapest GOOD ENOUGH cloud API | 1 | P0 |
| US-CB-07 | As a user, I want latency-aware routing | Interactive -> fastest, batch -> cheapest | 1 | P0 |
| US-CB-08 | As a user, I want privacy-aware routing | PII detected -> local only, never cloud/Hive | 2 | P0 |
| US-CB-09 | As a user, I want OpenAI + Anthropic tools to work | Proxy: `/v1/chat/completions` + `/v1/messages` | 1 | P0 |

### Epic: Compute Fabric (Ollama Inside + GPU From Anywhere)
| ID | User Story | Acceptance Criteria | Phase | Priority |
|----|-----------|-------------------|-------|----------|
| US-CF-01 | As a user, I want Ollama enhanced not replaced | Discovers existing Ollama, wraps it, zero re-download | 1 | P0 |
| US-CF-02 | As a user, I want to see all devices | Dashboard shows all devices (local + tunnel + LAN) | 2 | P0 |
| US-CF-03 | As a user, I want my home GPU from my laptop | `llmhosts tunnel` -> HTTPS URL -> laptop uses home GPU | 2 | P0 |
| US-CF-04 | As a user, I want LAN GPUs pooled | mDNS discovery, auto-pool LAN instances | 2 | P1 |
| US-CF-05 | As a user, I want large model across LAN GPUs | exo splits across 2+ LAN GPUs | 2 | P1 |
| US-CF-06 | As a user, I want cloud as fallback | BYOK cloud API used when local insufficient | 1 | P0 |
| US-CF-07 | As a power user, I want higher throughput | vLLM opt-in with prefix caching, dashboard comparison | 2 | P1 |
| US-CF-08 | As a user, I want multi-device mesh | Desktop + laptop + VPS as one compute pool | 2 | P0 |

### Epic: Caching (vCache Verified Semantic Cache)
| ID | User Story | Acceptance Criteria | Phase | Priority |
|----|-----------|-------------------|-------|----------|
| US-CA-01 | As a user, I want cached responses with guaranteed accuracy | vCache <1% false positive, formally verified | 1 | P0 |
| US-CA-02 | As a user, I want no cross-domain confusion | Entity namespace: "Python sort" != "JS sort" in cache | 1 | P0 |
| US-CA-03 | As a user, I want per-tier cache stats | Dashboard: exact hits, namespace hits, semantic hits, FP rate | 1 | P1 |
| US-CA-04 | As a user, I want cache management | Clear by namespace, set max size, configure delta | 1 | P1 |
| US-CA-05 | As a vLLM user, I want prefix caching | System prompt + multi-turn prefix cached | 2 | P1 |

### Epic: Frontend / Dashboard
| ID | User Story | Acceptance Criteria | Phase | Priority |
|----|-----------|-------------------|-------|----------|
| US-FE-01 | As a user, I want HONEST real-time savings | Real baseline comparison, not strawman. 30-50% typical. | 1 | P0 |
| US-FE-02 | As a user, I want to see routing decisions | Per-request: tier, model, reason, confidence, cost | 1 | P0 |
| US-FE-03 | As a user, I want a terminal dashboard | TUI with live stats, routing log, cache per tier | 1 | P0 |
| US-FE-04 | As a user, I want web dashboard | localhost + cloud-hosted (paid) with real-time updates | 1 | P0 |
| US-FE-05 | As a user, I want model catalog | All models with router intelligence stats | 2 | P1 |
| US-FE-06 | As a user, I want gamification | Badges, streaks, savings milestones | 3 | P2 |
| US-FE-07 | As a user, I want chat interface | Web chat with streaming, routing visible per message | 2 | P1 |
| US-FE-08 | As an admin, I want management | Admin panel: users, nodes, tickets, health | 3 | P1 |

### Epic: GPU-as-API (Added v4.0)
| ID | User Story | Acceptance Criteria | Phase | Priority | Status |
|----|-----------|-------------------|-------|----------|--------|
| US-GA-01 | As a user, I want one command to share my GPU | `llmhosts up` starts proxy + tunnel + auth + register | 3 | P0 | **DONE** (#223) |
| US-GA-02 | As a user, I want to authenticate my CLI | Device Code Flow (RFC 8628) with browser approval | 3 | P0 | **DONE** (#224) |
| US-GA-03 | As a user, I want my device tracked | Registration, heartbeat, health visible in dashboard | 3 | P0 | **DONE** (#225) |
| US-GA-04 | As a user, I want API calls routed to my GPU | Relay forwards `/v1/chat/completions` to device tunnel | 3 | P0 | **DONE** (#226) |
| US-GA-05 | As a user, I want one API key everywhere | Frontend-issued keys work in CLI and relay | 3 | P0 | **DONE** (#227) |
| US-GA-06 | As a user, I want docs to get started | Architecture guide, auth flow, quick-start | 3 | P1 | **DONE** (#228) |

### Epic: Hive Mode
| ID | User Story | Acceptance Criteria | Phase | Priority |
|----|-----------|-------------------|-------|----------|
| US-HM-01 | As a user, I want to create a Hive | `llmhosts hive join <code>`, self-hosted Rust relay coordination (ADR-009; Headscale deprecated) | 3 | P1 |
| US-HM-02 | As a member, I want to control sharing | Per-node toggle, time schedule | 3 | P0 |
| US-HM-03 | As a member, I want friends GPUs when mine is off | Route to Hive member node, whole-model routing | 3 | P1 |
| US-HM-04 | As a member, I want fair sharing | Karma: contributed vs consumed | 3 | P1 |
| US-HM-05 | As a member, I want my secrets private | PII/sensitive NEVER leaves my nodes | 3 | P0 |

### Epic: Security
| ID | User Story | Acceptance Criteria | Phase | Priority |
|----|-----------|-------------------|-------|----------|
| US-SEC-01 | As a user, I want encrypted access | Tailscale/Cloudflare + WireGuard for Hive | 2/3 | P0 |
| US-SEC-02 | As a user, I want secure key storage | Encrypted at rest, decrypted only at use | 1 | P0 |
| US-SEC-03 | As a user, I want PII protection | Detection + local-only routing enforced | 2 | P1 |
| US-SEC-04 | As a user, I want audit trail | All requests logged with routing decisions | 1 | P1 |
| US-SEC-05 | As enterprise, I want SOC2 | Documentation at Enterprise tier | 3 | P1 |

### Epic: Email & Operations
| ID | User Story | Acceptance Criteria | Phase | Priority |
|----|-----------|-------------------|-------|----------|
| US-EM-01 | As a user, I want quick support | support@ AI auto-reply in 5 min | 3 | P1 |
| US-EM-02 | As admin, I want escalation | AI unresolved ticket in admin dashboard | 3 | P1 |
| US-EM-03 | As a user, I want transactional emails | Signup, billing, alerts via no-reply@ | 2 | P0 |

---

## DEFINITION OF DONE (Per Epic)

### Onboarding (CLI-First, Tiered)
- [ ] `pip install llmhosts` (core) succeeds on Python 3.10+ in <1 minute
- [ ] `pip install llmhosts[smart]` adds ML router + vCache in <3 minutes
- [ ] `llmhosts serve` starts proxy (both API dialects) + dashboard in <5 seconds
- [ ] `llmhosts tunnel` creates HTTPS endpoint in <30 seconds
- [ ] Docker alternative works with GPU passthrough
- [ ] `llmhosts doctor` verifies all components

### Conductor (Three-Tier Router)
- [ ] Rule-based Tier 0 routes correctly 95%+ of deterministic cases
- [ ] kNN Tier 1 handles 75% of requests in <15ms
- [ ] ModernBERT Tier 2 adds +10% accuracy for complex routing
- [ ] Qwen-0.5B Tier 3 handles edge cases in <500ms
- [ ] Total router VRAM <1GB alongside inference model
- [ ] Both OpenAI and Anthropic API formats work

### Compute Fabric (Ollama Inside + Tunnel)
- [ ] Ollama discovered with zero configuration
- [ ] `llmhosts tunnel` works with Tailscale OR Cloudflare
- [ ] Multi-device mesh connects laptop to desktop transparently
- [ ] vLLM opt-in shows measurable throughput improvement
- [ ] LAN nodes discovered via mDNS
- [ ] Cloud fallback activates automatically

### Caching (vCache)
- [ ] vCache false positive rate <1% (formally verified)
- [ ] Entity namespace prevents cross-domain false positives
- [ ] 25-50% overall cache hit rate
- [ ] Per-tier metrics visible in dashboard

### Hive Mode
- [ ] Hive creation, invitation, management works
- [ ] Karma tracks contribution vs consumption accurately
- [ ] Privacy routing prevents sensitive prompts from leaving owner's node
- [ ] ~~Headscale ACLs enforced~~ Relay access control enforced (Noise NK + JWT, ADR-009)

---

## TESTING STRATEGY

### Phase 1: Unit + Manual
- Unit tests for CLI, API endpoints (both dialects), cache tiers (pytest)
- Manual testing on 3+ hardware configs (NVIDIA, AMD, CPU-only)
- CI tests all three pip tiers + Docker
- vCache false positive rate monitoring from day 1

### Phase 2: Integration + A/B
- Full routing pipeline: request -> cache -> three-tier-route -> respond
- A/B: rule-based vs full three-tier router quality
- Tunnel testing across 5+ network configurations
- Multi-device mesh testing

### Phase 3: Load + Security
- 1,000 concurrent users simulation
- Security penetration testing
- Hive Mode privacy verification
- Relay access control testing (ADR-009; Headscale deprecated)

### Phase 4: Production
- Canary deployments for router updates
- Continuous monitoring + alerting
- Performance benchmarks

---

## SPRINT PLANNING GUIDANCE

### Sprint Duration: 2 weeks
### Sprint Capacity (1 developer): 8-10 items (mix P0/P1), 1 spike max
### Time allocation: 70% building, 20% testing, 10% docs
### Phase gates are GO/NO-GO decisions, not calendar dates
