# LLMHosts.com

> Turn your home GPU into production AI infrastructure accessible from anywhere.

## Project Identity

- **Name**: LLMHosts.com
- **Repository**: LookNoHandsMom/LLMHosts.com (private)
- **Status**: active — Phase 5 marketplace complete: #303, #311, #313, #314 merged; #304–#308 and #305 closed. **GitHub is SSOT** for all tasks and state; another AI dev can pick up from repo + GitHub alone. Handoff: `docs/SSOT-AND-HANDOFF.md`.
- **Product stance**: All SaaS, all pay models; no open source. Conversion and profitability are the bar. See `docs/plans/2026-02-27-all-saas-all-pay.md` and `docs/marketing/2026-02-27-saas-conversion-profitability-playbook.md`.
- **Stack**: Python 3.12 + FastAPI (proxy), Next.js 16 + TypeScript (frontend), SQLite/Prisma
- **Deploy**: Docker Compose + Pangolin/Traefik (self-hosted), GitHub Actions CI

## Architecture

### Overview

```
User → Pangolin/Traefik (TLS, CrowdSec WAF)
           ├── /v1/* /health /docs /admin → llmhosts:4000 (FastAPI proxy)
           └── /* catch-all              → llmhosts-frontend:3000 (Next.js)
```

### Key Components

| Component | Location | Purpose |
|-----------|----------|---------|
| FastAPI proxy | `llmhosts/proxy/` | OpenAI + Anthropic compatible API |
| Three-tier router | `llmhosts/router/` | kNN <15ms → ModernBERT <50ms → Qwen-0.5B <500ms |
| vCache | `llmhosts/cache/` | Verified semantic cache (hash + namespace + adaptive) |
| CLI | `llmhost/cli.py` | `llmhosts serve`, `llmhosts tunnel`, `llmhosts keys`, `llmhosts doctor` |
| Next.js frontend | `frontend/` | Landing, pricing, auth, dashboard, billing (Stripe) |
| Hive.CEO | `hive/` + `.hive/` | Embedded AI agent system, admin at `/admin/hive/` |
| Auth | `frontend/src/` | Auth.js v5 (NextAuth), Prisma + SQLite |
| Marketplace | `llmhosts/marketplace/`, `frontend` devices/marketplace | Catalog, router, billing, reputation, Stripe Connect |
| Monitoring | `monitoring/` | Prometheus + Grafana + Loki + AlertManager (T-12) |

### Data Flow

```
Request → Traefik → FastAPI → BackendDispatcher
                                 ├── Router (PII detection → IslandRun privacy enforcement)
                                 ├── Cache (vCache semantic lookup)
                                 ├── Marketplace (remote devices via tunnel URL when catalog enabled)
                                 └── Backend (Ollama / vLLM / remote)
```

## Framework Integration

This project uses the **Aut-O** development framework (`/home/dev/projects/admin/aut-o.com/`).

### Active Tenets

- **GitHub SSOT** — all state in issues, PRs, Actions
- **TDD** — tests first, 2,413+ backend + 808 frontend + 29 E2E passing
- **Security by default** — PII detection before routing, OWASP headers, HSTS preload
- **Autonomous execution** — research → plan → execute → validate → ship
- **Zero debt** — no warnings, no TODOs, no skipped tests

### Quality Gates

- Zero ruff/mypy/eslint warnings
- All tests pass (pytest + vitest + playwright)
- `✅ Verification Gate (T-13, P-005)` CI check passes (branch protection required)
- No PII in logs or responses
- GitHub issue linked to every PR

## Session Start Protocol

1. **Sync from GitHub**:
   ```bash
   gh issue list --state open --limit 20
   gh pr list --state open
   gh project item-list 5 --owner LookNoHandsMom --limit 20
   gh run list --limit 5
   ```
2. **Read** `CLAUDE.md` for commands and architecture detail
3. **Read** `MEMORY.md` (auto-memory) for gotchas and session history
4. **Orient**: `git log --oneline -10` + `git status`
5. **Execute**: highest-priority open issue

## Commands

### Backend (Python)

| Command | Purpose |
|---------|---------|
| `pip install -e ".[dev]"` | Install with dev tools |
| `llmhosts serve` | Run proxy server |
| `ruff check .` | Lint |
| `ruff format .` | Format |
| `mypy llmhosts/ --ignore-missing-imports` | Type check |
| `pytest tests/ -v` | All backend tests |
| `pytest tests/test_router.py -v` | Single file |
| `python -m build --wheel --outdir dist/` | Build wheel |

### Frontend (Next.js — run from `frontend/`)

| Command | Purpose |
|---------|---------|
| `npm install` | Install dependencies |
| `npm run dev` | Dev server (localhost:3000) |
| `npm run build` | Production build |
| `npm run lint` | ESLint |
| `npm run test` | Vitest unit tests |
| `npm run test:e2e` | Playwright E2E |
| `npx prisma migrate dev` | Apply DB migrations |
| `npx prisma generate` | Regenerate client |
| `npx prisma studio` | Browse database |

## Environment

### Requirements

- Python 3.12+
- Node.js 20+
- Docker + Docker Compose

### Local Setup

```bash
pip install -e ".[dev]"
cd frontend && npm install && npx prisma migrate dev
llmhosts serve
```

### Production (Docker)

```bash
# With external Pangolin proxy (this server):
docker compose -f docker-compose.prod.yml -f docker-compose.external-proxy.yml up -d

# Standalone with built-in Traefik:
docker compose -f docker-compose.prod.yml up -d
```

### Key Environment Variables

| Variable | Purpose | Required |
|----------|---------|----------|
| `NEXTAUTH_SECRET` | NextAuth signing key | yes |
| `NEXTAUTH_URL` | Full frontend URL | yes |
| `DATABASE_URL` | Prisma database path | yes (default: `file:/data/llmhosts.db`) |
| `NEXT_PUBLIC_API_URL` | FastAPI proxy URL | yes |
| `RESEND_API_KEY` | Email (verification, reset) | yes in prod |
| `STRIPE_SECRET_KEY` | Stripe billing | yes in prod |
| `LLMHOST_SECURITY_REQUIREAUTH` | Enable API key auth | prod: true |

## Conventions

### Code Style

- **Python**: ruff lint+format, mypy strict, async/await everywhere, Pydantic v2
- **TypeScript**: strict mode, ESLint, Prettier, kebab-case files, PascalCase components
- **Database**: snake_case columns, Prisma migrations only (never manual SQL)

### Git Workflow

- Branch from `main`: `feature/<id>-<desc>` or `fix/<id>-<desc>`
- Conventional commits: `feat(scope):`, `fix(scope):`, `docs:`, `chore:`, `refactor:`, `test:`
- Squash merge to main (linear history)
- PRs required — no direct push to main (branch protection enforced)
- Link PRs to issues: `Closes #<number>` in PR body

### Testing

- Backend: pytest, `asyncio_mode = "auto"`, ASGI transport (no real server)
- Frontend: Vitest for unit, Playwright for E2E (localhost:3000)
- Target: 80%+ coverage on critical paths
- Run all: `pytest tests/ -v && cd frontend && npm test && npm run test:e2e`
- **E2E master plan**: `docs/testing/MASTER-E2E-PLAN.md` — full capability index, Round 1 (Alienware-first), Round 2 (Mac Mini, multi-GPU, large GPU), gap analysis; execution: `docs/testing/P5-full-test-guide.md`. GitHub is SSOT for test issues and status.

## Key Files

- `CLAUDE.md` — full architecture, commands, patterns (Claude Code)
- `AGENTS.md` — this file (universal cross-tool grounding)
- `docs/testing/MASTER-E2E-PLAN.md` — E2E strategy, capability index, rounds, gap analysis (Feb 2026)
- `docs/testing/P5-full-test-guide.md` — P5 execution (site + Alienware battery + recap)
- `docs/plans/2026-02-27-gpu-remit-and-user-control.md` — GPU remit, read-only access, user control, per-GPU opt-in; OpenClaw = optional leverage, we build our own solution
- `docs/plans/2026-02-27-all-saas-all-pay.md` — All SaaS, all pay; no open source; conversion/profitability bar
- `docs/planning/OpenClaw-gaps-and-leverage.md` — 20-search table, entry points, gaps vs optional leverage; we build our own
- `docs/marketing/2026-02-27-saas-conversion-profitability-playbook.md` — Conversion benchmarks, levers, AI SaaS context; 100-search research (Feb 2026)
- `pyproject.toml` — Python build, ruff/mypy config, pytest settings
- `docker-compose.prod.yml` — production deployment
- `docker-compose.external-proxy.yml` — override for Pangolin/Traefik setups
- `frontend/prisma/schema.prisma` — database schema
- `llmhosts/proxy/dispatcher.py` — BackendDispatcher with Router integration
- `llmhosts/router/engine.py` — Router with privacy enforcement + PII detection
- `deferred/` — items blocked on human action (scan each session)

## Hive.CEO — Embedded Agent System

`hive/` package + `.hive/` state directory. Admin panel at `/admin/hive/`.

- All agent code changes go through GitHub PRs (human approval required)
- Progressive enhancement — LLMHosts works fully without it
- **Naming discipline**: "Hive.CEO" = embedded agent system. "Hive Mode" = Phase 3 GPU pooling. Never conflate.

Key files: `.hive/identity.md`, `.hive/soul.md`, `.hive/config.yaml`, `.hive/memory/`, `hive/agents/`

## GitHub SSOT

All project state lives in GitHub. **For handoff to another AI or dev instance:** read `docs/SSOT-AND-HANDOFF.md` first, then `gh issue list --state open` and issue #325.
- **Issues**: feature requests, bugs, tasks (labeled by priority, epic, type)
- **Pull Requests**: all changes via PRs with linked issues
- **Actions**: CI (Verification Gate must pass before merge)
- **Projects**: "LLMHosts.com Roadmap" board #5 (Phase, Priority, Size, Epic, Milestone). Use Board view (Status), Table view (Phase/Priority/Size/Epic), saved filter "Conversion" (label:conversion), "E2E" (label:e2e-test). All work in micro-verbosity issues; master playbook #325.

### Phase 5 (Marketplace) — current state
- **Merged**: #303 (foundation a–h), #311 (prepaid credits #306), #313 (operator agreement #304), #314 (load test #307 + probes/uptime/reputation #308). Buyer dashboard (#305) delivered on main (usage push, internal usage API, GET usage, /dashboard/marketplace).
- **Closed issues**: #290, #304, #305, #306, #307, #308. Epic #290 closed (marketplace auto-removal merged in PR #430).
- **Sync**: `gh issue list --state open` and `gh pr list --state open`; `gh project item-list 5 --owner LookNoHandsMom` for board.

## Crash Recovery

If context is lost or a session starts fresh:
1. Read `AGENTS.md` (this file) and `CLAUDE.md`
2. `gh issue list --state open --limit 20` — active backlog
3. `gh pr list --state open` — work in progress
4. `git log --oneline -10` — recent changes
5. `gh run list --limit 5` — CI health
6. Resume highest-priority incomplete task
