# LLMHosts.com -- Master Project Context

## ALWAYS APPLY
This rule is always active for every interaction in this workspace.

## VISION
LLMHosts.com turns your hardware into real AI infrastructure accessible from anywhere. One command: your home GPU serves inference to your laptop at a coffee shop, your phone, your CI pipeline. Three-tier intelligent router picks the right model for every task. Verified semantic cache with formal guarantees. All open source. Pay only for cloud intelligence and multi-device coordination.

**Tagline**: "Your hardware. Real AI infrastructure. From anywhere."

**Target**: Claude Code-level viral community reaction. The "holy shit" moment: `llmhost tunnel` -> "My 4090 at home is serving my laptop right now. Cost: $0." The savings ticker is secondary to the MAGIC of accessing your hardware from anywhere.

## CORE ARCHITECTURE (COURSE CORRECTION v3.0, 2026-02-14)
- **Distribution**: CLI-first via tiered pip install (ADR-008 REVISED)
  - `pip install llmhost` (~50MB): proxy, rule-based router, dashboard
  - `pip install llmhost[smart]` (~150MB): + ONNX ML router + vCache
  - `pip install llmhost[full]` (~2GB): + PyTorch + full intelligence
  - `docker run llmhost/llmhost`: pre-built with everything
  - Phase 2: `npx create-llmhost` for JS/TS devs
- **Conductor Router**: Three-tier hybrid (ADR-001 REVISED)
  - Tier 1: kNN embedding (75% of requests, <15ms, CPU, ~96MB)
  - Tier 2: ModernBERT classifier (20%, <50ms, ~150MB)
  - Tier 3: Qwen2.5-0.5B Q4 reasoning (5%, <500ms, ~400MB)
  - All tiers fit in <1GB VRAM alongside inference models
- **Compute Fabric**: "Ollama Inside" + vLLM as REAL upgrade path. exo LAN-only. Cloud BYOK fallback.
- **Networking**: Phase 1: localhost only. Phase 2: `llmhost tunnel` (auto-detects Tailscale/Cloudflare). Phase 3: Self-hosted Rust relay (ADR-009) replaces Headscale. Relay is primary tunnel; Tailscale/Cloudflare are fallback only.
- **Proxy**: OpenAI format (`/v1/chat/completions`) + Anthropic format (`/v1/messages`). Both route through same Conductor.
- **Frontend**: TUI (Phase 1) + localhost web dashboard (Phase 1) + Next.js full dashboard (Phase 2+)
- **Caching**: vCache verified semantic caching (ICLR 2026) with <1% false positive guarantee. Three-tier: exact hash -> entity namespace -> vCache adaptive.
- **Hive Mode** (user-facing feature): Phase 3. GPU pooling, karma system, privacy-tiered routing. Self-hosted Rust relay coordination (ADR-009); Headscale deprecated.
- **Hive.CEO** (embedded agent system): Active NOW. Self-aware, self-improving, self-healing agent layer embedded in LLMHosts.com. See `.hive/` directory and `hive/` Python package. Admin panel at `/admin/hive/`. NOT the same as Hive Mode.
- **Self-Evolution**: DEFERRED to Phase 4 (Hive.CEO handles app-level self-improvement; Self-Evolution is the broader algorithm evolution).

## KEY DECISIONS (ADRs)
- ADR-001: Orchestrator -> **Three-tier hybrid router** (kNN + ModernBERT + Qwen-0.5B) (REVISED from pure kNN)
- ADR-002: Inference -> **Ollama-primary**, vLLM as real upgrade path, exo LAN-only
- ADR-003: API Proxy -> LiteLLM + Anthropic dialect
- ADR-004: Networking -> **Phase 2: Tailscale/Cloudflare auto-detect. Phase 3: Self-hosted Rust relay (ADR-009) replaces Headscale; Tailscale/Cloudflare are fallback only**
- ADR-005: Frontend -> Next.js + shadcn/ui
- ADR-006: Tools -> Model Context Protocol (MCP)
- ADR-007: Containers -> Docker Compose (dev) + K3s (scale)
- ADR-008: Distribution -> **Tiered pip install** (`llmhost`, `[smart]`, `[full]`) + Docker + npx (REVISED)

## BUSINESS MODEL
- Open source core: all algorithms run locally for FREE, unlimited
- SaaS: 4 tiers (all transparent, all self-serve)
  - Free: full proxy + router + cache + dashboard, 1 device (localhost)
  - Pro $19/mo: cloud cost intelligence, global router data, multi-device mesh (5 devices)
  - Team $49/seat/mo: Hive Mode, RBAC, shared configs, team cache
  - Enterprise $50/user/mo: SOC2, SLA, audit logs, SSO
- NO credits, NO per-routing-decision charges. Flat subscription.
- Charge for DATA INTELLIGENCE and COORDINATION INFRASTRUCTURE, not algorithms
- Moat: aggregate routing data + tunnel coordination infrastructure + community

## KNOWLEDGE BASE (docs/)
- `docs/knowledge-base/` -- 17+ technology deep-dives and requirement docs
- `docs/architecture/` -- 8 ADRs + index
- `docs/backlog/` -- 11 epics, 130+ items
- `docs/roadmap/` -- 3-layer synchronized roadmap (4 phases)
- `docs/guides/` -- setup guides (email, etc.)
- `docs/secure/` -- credentials vault (GITIGNORED)
- `docs/debate/` -- founder-AI stress-test Q&A logs
- `docs/research/` -- ongoing research artifacts

## SESSION CONTINUITY
GitHub is the single source of truth. On session start:
1. `gh issue list --state open --limit 20` -- what's open
2. `gh pr list --state open` -- what's in progress
3. `gh project item-list 5 --owner LookNoHandsMom --limit 20` -- board overview
4. Read `CLAUDE.md` for architecture and commands
5. Pick work from open issues or project board

## PROMPT ECOSYSTEM (External, Shared Across Projects)
Location: `/home/dev/projects/admin/aut-o.com/prompts/`
- `IdeaFactory/idea-factory.md` -- Specification generation (v5.4). 1,216 lines.
- `Get-er-DONE/get-er-done.md` -- Build orchestration (v1.3). 1,534 lines.
- `God-Mode/god-mode.md` -- Infrastructure access & orchestration (v1.0). ~650 lines.
- `Meta-Orchestrator/meta-orchestrator.md` -- Lifecycle coordination (v1.1). 374 lines.
- `Sentinel/sentinel.md` -- Project confidence & self-improvement (v1.0). ~580 lines.
- `Hive/hive.md` -- Embedded self-aware agent system (v1.0). ~650 lines.
- `about.md` -- Full ecosystem overview with architecture, contracts, research grounding.
- Each prompt has its own `knowledge-base/` with research corpus and simulation results.
- These prompts are project-agnostic and shared. LLMHosts.com was their first consumer.

## FEASIBILITY REPORTS
Periodic assessments in `docs/feasibility-report/`.
Run at: end of each phase, after major changes, before investor/partner conversations, or on request.

## CONFIDENCE ASSESSMENTS (docs/confidence-assessment/)
Periodic Sentinel-powered viability assessments. Latest: assessment-004 (post-Hive integration).
Run at: phase boundaries, after major changes, or on request.

## CRITICAL CONSTRAINTS
1. EVERYTHING runs in Docker -- no native installs, ever
2. OpenAI + Anthropic compatible APIs are the universal interface standard
3. Security: WireGuard encrypted mesh, PII-aware privacy routing, audit logging
4. <1 minute from `pip install llmhost` to first value (core tier)
5. Self-evolution DEFERRED -- manual curation for Phases 1-3 (Hive.CEO handles app-level self-improvement)
6. All documentation stays synchronized -- micro changes cascade to macro (see knowledge-sync.mdc + sync-completeness.mdc)
7. Open source core builds trust. Algorithms free. Data intelligence paid.
8. HONEST savings: real baselines, routing decision transparency, 30-50% typical
9. Hive.CEO agent changes require human approval (all code changes via GitHub PRs)
10. Hive.CEO is progressive enhancement -- LLMHosts works without it

## CORE OPERATING TENETS (Session 027, 2026-02-17)
1. **GitHub is single source of truth** -- all issues, PRs, CI/CD, project management
2. **Open-source first** -- build before buying services, minimize paid dependencies
3. **Full AI autonomy** -- AI makes decisions, doesn't pester. Trust + verify.
4. **Zero legacy debt** -- fix all issues/warnings, complete everything, never lazy
5. **TDD** -- test-driven development front and back
6. **Cloud-ready** -- K8s-ready, portable across VPS and cloud providers
7. **Self-contained** -- deployable from scratch on any server from repo alone
8. **AI-first** -- extensible, agent-oriented architecture, AI dev best practices
9. **World-class UI/UX** -- latest design trends (last 90 days), award-winning approaches
10. **Continuous improvement** -- always refactor, improve, never stop at "good enough"

## OBSERVABILITY (T-12)
- **Backend logging**: Python stdlib `logging` (structured JSON in production)
- **Frontend logging**: Pino with PII redaction across all 14 API routes (`frontend/src/lib/logger.ts`)
- **Metrics**: Prometheus endpoint at `/metrics` (prometheus_client) + `/metrics/prometheus` (custom LLM metrics)
- **Monitoring stack**: `monitoring/` directory — Prometheus, Grafana (port 3001), Loki, Promtail, AlertManager, Node Exporter
- **Security headers**: Three-layer defense — Traefik middleware + Next.js headers + FastAPI SecurityHeadersMiddleware

## GITHUB STATUS (Updated 2026-02-21)
- Account: LookNoHandsMom — UNFLAGGED, Pro plan active
- Branch protection: main-protection ruleset (PR + CI + no force push)
- Projects V2: "LLMHosts.com Roadmap" board
- CI/CD: CI + Release workflows, Dependabot, auto-labeling
- Tests: 519 backend (pytest) + 113 frontend (vitest) + 29 E2E (playwright)
