# LLMHosts.com -- Hive Identity

## META
- created: 2026-02-14
- last-evolved: 2026-02-14
- evolution-version: 1
- hive-version: 1.0

## WHAT THIS APP IS
LLMHosts.com turns your hardware into real AI infrastructure accessible from anywhere. CLI-first tool: `pip install llmhosts && llmhosts serve` gives you a three-tier intelligent router (kNN + ModernBERT + Qwen-0.5B), verified semantic caching (vCache), and OpenAI + Anthropic compatible proxy on your hardware. `llmhosts tunnel` makes your home GPU accessible from your laptop at a coffee shop. Open source core with paid data intelligence tier ($19/mo Pro).

## ARCHITECTURE SUMMARY
- **Proxy**: FastAPI-based, OpenAI + Anthropic API compatible via LiteLLM
- **Router**: Three-tier hybrid (kNN via FAISS + all-MiniLM-L6-v2, ModernBERT classifier, Qwen2.5-0.5B reasoning)
- **Cache**: vCache verified semantic cache (exact hash + entity namespace + adaptive threshold)
- **Discovery**: Ollama auto-discovery + hardware detection + tunnel detection
- **Tunnel**: Tailscale/Cloudflare auto-detect for remote access
- **Dashboard**: TUI (textual/rich) + web dashboard (React, Phase 2+)
- **CLI**: Click-based -- `llmhosts serve`, `llmhosts tunnel`, `llmhosts keys`, `llmhosts doctor`
- **Distribution**: PyPI (tiered: core ~50MB, smart ~150MB, full ~2GB)

## KEY FACTS
- Language: Python 3.10+
- Framework: FastAPI + Click
- Database: aiosqlite (Phase 1), PostgreSQL (Phase 2+)
- Deployment: Docker Compose (dev), PyPI (distribution)
- Test framework: pytest + pytest-asyncio
- CI: GitHub Actions (ruff, mypy, pytest, Docker build)
- Package manager: pip / hatch
- License: MIT

## CURRENT FOCUS
Phase 1 implementation: project skeleton is complete (Step 1 of 22-step blueprint). Next steps are config system, Ollama discovery, BYOK key vault, proxy engine, router, and cache.

## KNOWN DEBT
- All CLI commands are stubs (not yet implemented)
- No actual proxy/router/cache implementation yet
- Config system is placeholder (returns defaults)
- No test coverage beyond skeleton validation

## PIVOT HISTORY
- 2026-02-14: Course correction v3.0 -- restored three-tier hybrid router (was simplified), added `llmhosts tunnel` as killer feature, replaced GPTCache with vCache, fixed monetization (flat $19/mo, not credits)
