# Master Plan v15 (Web Summary)

This page is a **human-readable snapshot** of the Monkey‑Head‑Project / HueyOS master plan as it exists today.
It’s written to be:

- readable by humans,
- linkable from the website,
- and stable enough to survive “site refactors” without becoming a blank page.

> Canonical references: the HueyOS / Monkey‑Head‑Project repositories on GitHub.

---

## 1) What Huey is

**Huey** is an offline‑first lab partner: a modular robotics shell with a local compute core that can run, reason, and log decisions without relying on cloud services.

The project’s public-facing software stack and documentation is referred to as **HueyOS**.

---

## 2) System architecture (high level)

Huey is designed as a single “core node” orchestrating four GPU‑based districts:

- **CPU = Overseer / Orchestrator**
- **4× GPU districts** (Spark / Volt / Zap / Watt) = primary parallel compute

Districts are intentionally treated as semi-independent “regions” to support governance separation, auditability, and modular scaling.

---

## 3) Canonical hardware baseline (current target)

The baseline is intentionally uniform across nodes so a build can be replicated:

- **CPU:** Intel Core i9‑14900K  
- **Motherboard:** ASUS TUF Gaming Z790‑PLUS WiFi  
- **Memory:** DDR5 (DDR4 minimum supported for non‑core lab tech)
- **GPUs:** 4 total (1 per district), 2019+ required, 2020+ preferred  
  - recommended minimum VRAM: **16 GB per GPU** (64 GB total)  
  - absolute minimum VRAM: **12 GB per GPU** (not recommended)
- **Storage:** “Honeycomb” approach built around **RAID 10 NVMe**
- **Power:** minimum **2 PSUs**, **3–4 preferred**, and an eventual “per‑GPU PSU” model for the prototype

Cooling is treated as a first‑class subsystem (see below).

---

## 4) Cooling + physical shell

The Robotics V3 shell is layered and salvage‑driven:

- base platform on casters
- lower housing for the core compute
- mid structure + upper housing for the GPU districts
- top section: animatronic monkey head + microphone

Cooling direction:

- CPU uses a custom liquid loop (reservoir + pump)
- GPU liquid cooling planned (full or augmented), integrated into overall loop
- target coolant volume: ~4L once fully online

---

## 5) HueyPulse (always‑on subcontroller)

HueyPulse is the “heartbeat” subsystem that remains online even when the main node is down.

Responsibilities:

- thermal monitoring
- pump control
- sensor polling / logging
- basic actuation safety

HueyPulse is intended to be backed by a **UPS** to maintain continuity during power loss.

---

## 6) Governance model (Cloud Pyramid)

Huey’s internal decision structure is modeled as a distributed government:

- **Parliament**
- **Presidency**
- **Supreme Court**
- 4 GPU districts (Spark / Volt / Zap / Watt)

Each district hosts a population of AI “citizens”, with quota/token budgeting per cycle.
Decisions are tracked for auditability (append-only logs + indexing).

---

## 7) Software stack snapshot

- Debian 14 “Forky” (migration from Debian 13 “Trixie”)
- Python 3.12–3.14 range (current work often on 3.13)
- custom low-latency Huey kernel (6.17+ lineage)
- orchestration: PyGPT‑net, Ollama backend, Whisper for STT (where applicable)
- memory + governance logs: append-only JSON + SQLite indexes

---

## 8) Roadmap philosophy

This project is intentionally a **roadmap** as much as it is a build:

- open-source
- modular + replicable
- heavy emphasis on documentation that explains not just *what*, but *why*

---

## Status note

This is a living plan. The “final” layout decisions (PSU placement, exact cooling routing, final GPU SKU selection) are intentionally deferred until the acquisition phase.