# CONTEXT.md -- LLMHosts.com

## META
- created: 2026-02-14
- purpose: Project classification and context for AI agent build adaptation
- consumed-by: Get-er-DONE Nature Awareness Protocol, Meta-Orchestrator Handoff Protocol
- format: SurfContext ARDS v2.0 compatible

---

## Project Classification

- Nature: Software Product
- Scope: Medium
- Origin: Greenfield
- Regulatory: Light (GDPR -- PII-aware routing, data consent, user data deletion)
- Speed: Standard
- Certainty: High

---

## Project Identity

- **Name**: LLMHosts.com / Your Personal AI Cloud
- **Tagline**: Your hardware. Real AI infrastructure. From anywhere.
- **Type**: CLI tool + SaaS platform (all SaaS, all pay)
- **Distribution**: pip install llmhosts (tiered: core, smart, full) + Docker + npx (Phase 2)
- **License**: FSL-1.1-Apache-2.0. Converts to Apache 2.0 after 2028-02-24.

## Target Users

- Developers who own GPUs (RTX 3090/4090, Apple Silicon) and spend $50-200+/mo on AI tools
- 4 personas: Solo Dev Sarah, Team Lead Tomas, Privacy-First Priya, Enterprise Eva
- See: docs/business/personas-jtbd.md

## Core Value Proposition

One command turns a home GPU into production AI infrastructure accessible from anywhere. Three-tier intelligent router. Verified semantic cache. Real-time savings dashboard. Paid cloud intelligence.

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Language | Python 3.12+ |
| Inference | Ollama (primary), vLLM (upgrade path), exo (LAN-only) |
| Proxy | LiteLLM core (OpenAI + Anthropic format) |
| Router | Three-tier: kNN embedding + ModernBERT + Qwen2.5-0.5B Q4 |
| Cache | vCache verified semantic (exact hash -> entity namespace -> vCache adaptive) |
| Tunnel | Self-hosted LLMHosts Relay (primary, Rust binary in pip wheel), Tailscale / Cloudflare fallback |
| Frontend | Next.js 14+, shadcn/ui, Tailwind CSS (dark-first) |
| Database | SQLite (local), PostgreSQL (SaaS) |
| CI/CD | GitHub Actions |
| Container | Docker, Docker Compose |
| Monitoring | Prometheus + Grafana |

## Business Model

| Tier | Price | Key Features |
|------|-------|-------------|
| Free | $0 | Full proxy + router + cache + dashboard, 1 device (localhost) |
| Pro | $19/mo | Cloud cost intelligence, global router, multi-device mesh (5), tunnel coordination |
| Team | $49/seat/mo | Hive Mode, RBAC, shared configs, team cache, 25 devices |
| Enterprise | $50/user/mo | SOC2, SLA, audit logs, SSO, unlimited devices |

## Architecture Decisions

- ADR-001: Three-tier hybrid router (kNN + ModernBERT + Qwen-0.5B)
- ADR-002: Ollama-primary inference, vLLM as upgrade path
- ADR-003: LiteLLM + Anthropic dialect API proxy
- ADR-004: Self-hosted LLMHosts Relay (primary), Tailscale/Cloudflare fallback (Phase 2)
- ADR-005: Next.js + shadcn/ui frontend
- ADR-006: Model Context Protocol (MCP) for tools
- ADR-007: Docker Compose (dev) + K3s (scale)
- ADR-008: Tiered pip install (core ~50MB, smart ~150MB, full ~2GB)

## Build Phases

| Phase | Scope | Timeline |
|-------|-------|----------|
| Phase 1 | Core: proxy, rule-router, kNN router, cache, dashboard, CLI | Weeks 1-6 |
| Phase 2 | Tunnel, cloud dashboard, multi-device, ModernBERT router | Weeks 7-12 |
| Phase 3 | Hive Mode, Qwen router, vLLM integration, RBAC | Weeks 13-18 |
| Phase 4 | Enterprise, self-evolution (deferred) | Weeks 19-24 |

## Key Constraints

1. Container-first: Docker for dev, test, CI. Pip install for user distribution.
2. OpenAI + Anthropic compatible APIs as universal interface
3. PII-aware privacy routing, WireGuard encrypted mesh, audit logging
4. Less than 1 minute from pip install llmhosts to first value
5. Self-evolution DEFERRED to Phase 4
6. All SaaS, all pay — paid data intelligence
7. Honest savings: real baselines, routing transparency, 30-50% typical

## Hive.CEO -- Embedded Agent System

LLMHosts.com includes the Hive.CEO embedded self-aware agent layer (v1.0).

| Component | Path | Purpose |
|-----------|------|---------|
| Agent Identity | .hive/identity.md | What LLMHosts is, architecture, key facts (versioned, evolves) |
| Agent Soul | .hive/soul.md | Behavioral guidelines, values, tone |
| Agent Config | .hive/config.yaml | Model providers, agent settings, approval rules, feature flags |
| Codebase Map | .hive/codebase-map.json | Auto-generated module graph (gitignored) |
| Capabilities | .hive/capabilities.md | What agents CAN do |
| Constraints | .hive/constraints.md | What agents CANNOT do |
| Evolution Log | .hive/evolution-log.md | Record of pivots and identity changes |
| Memory | .hive/memory/ | Institutional memory (patterns, incidents, decisions) |
| Backlog | .hive/backlog/items/ | Agent-managed improvement backlog |
| Skills | .hive/skills/ | Agent-generated automation |
| Metrics | .hive/metrics/ | Health snapshots and trends (gitignored) |
| Agent Runtime | hive/ | Python package: 5 agents, admin panel, providers, GitHub client |
| Admin Panel | /admin/hive/ | Dashboard, Kanban, Chat, Approval Queue, Activity Log, Config |

**NOTE: Hive.CEO (embedded agent system) is DIFFERENT from Hive Mode (social compute sharing, Phase 3).** Hive.CEO lives inside the app as a management layer. Hive Mode is a user-facing feature for GPU pooling.

## Key Documents

| Document | Path |
|----------|------|
| PRD | docs/business/prd.md |
| System Architecture | docs/architecture/system-architecture.md |
| OpenAPI Spec | docs/architecture/openapi.yaml |
| Implementation Blueprint | docs/architecture/implementation-blueprint.md |
| Test Strategy | docs/architecture/test-strategy.md |
| Design System | docs/architecture/design-system.md |
| Component Inventory | docs/architecture/component-inventory.md |
| Wireframes | docs/architecture/wireframes/ |
| User Flows | docs/architecture/user-flows.md |
| Threat Model | docs/architecture/threat-model.md |
| Financial Model | docs/knowledge-base/financial-model.md |
| Competitive Analysis | docs/business/competitive-analysis.md |
| Hive Prompt | /home/dev/projects/IdeaFactory.DEV/prompts/Hive/hive.md |
| Hive Knowledge Base | /home/dev/projects/IdeaFactory.DEV/prompts/Hive/knowledge-base/ |
| Confidence Assessments | docs/confidence-assessment/ |
