Scaffold: fork of Chambers architecture, renamed to Boardroom Map

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-06 13:10:25 -05:00
commit 1dde915540
48 changed files with 4025 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Boardroom Map — a private document-review panel for your DGX Sparks
+
+Boardroom Map is a StartOS service (`.s9pk`) that lets you **drop confidential
+documents in and have a panel of local LLMs review them** on your NVIDIA DGX
+Sparks. You pick the models and the personas (lenses), and how many reviews to
+run; each reviewer writes a report, and an optional **local lead reviewer**
+synthesizes them into one consolidated report. There is **no frontier model and
+no cloud API key** — in the default air-gapped mode the documents and reviews
+never leave your hardware.
+
+It is a sibling of [Nightshift](../nightshift) and reuses the same control-plane
+pattern (a GPU-free orchestrator on StartOS driving the Sparks over SSH), but
+with the swarm, the git blackboard, and the Claude overseer removed and replaced
+by an on-demand **document-review pipeline**.
+
+## Architecture
+
+```
+StartOS box (control plane, no GPU)            DGX Spark(s)
+┌────────────────────────────────────┐         ┌───────────────────────────────┐
+│ FastAPI web UI + job runner         │  SSH    │ per-job Docker network        │
+│  • inbox (drop documents)           │ ───────▶│   (──internal in airgapped)   │
+│  • extract text (PDF/DOCX/TXT/MD)   │  rsync  │  ┌─────────┐  ┌────────────┐  │
+│  • plan model "waves"               │ ───────▶│  │ vLLM(s) │◀─│ LiteLLM     │  │
+│  • launch reviewer containers       │         │  └─────────┘  │ router      │  │
+│  • pull reports, synthesize, wipe   │◀─────── │  ┌──────────────┐  ▲         │  │
+│  • reports saved here only          │  rsync  │  │ reviewer ×N  │──┘         │  │
+└────────────────────────────────────┘         │  │ (read-only,  │            │  │
+                                                │  │  sandboxed)  │            │  │
+                                                │  └──────────────┘            │  │
+                                                └───────────────────────────────┘
+```
+
+- **Reviewers** are one-shot, read-only, hardened containers (non-root,
+  `--cap-drop ALL`, read-only rootfs, no docker socket). In air-gapped mode they
+  sit on an `--internal` network and can reach only the model proxy.
+- **Waves:** the job runner serves models in waves bounded by
+  `maxConcurrentModels`, so a panel can span more models than fit in GPU memory
+  at once.
+- **Confidentiality:** documents are extracted to text on the StartOS box; only
+  text crosses to the Sparks, and it is wiped from the Sparks after the job.
+
+## Repo layout
+
+```
+startos/            StartOS package definition (TypeScript / start-sdk)
+  manifest/ main.ts interfaces.ts versions/ file-models/ actions/
+orchestrator/       The control-plane app (Python)
+  app.py            FastAPI UI + JSON API
+  jobs.py           the job runner (extract → serve waves → review → synthesize)
+  serving.py        vLLM + LiteLLM router on the Sparks, in waves
+  reviewers.py      launch the reviewer panel
+  synthesis.py      the local lead reviewer
+  extraction.py     PDF/DOCX/TXT/MD → text (on the StartOS box)
+  preflight.py      probe models before launching reviewers
+  spark_client.py   SSH/rsync helpers
+  bm_config.py      config defaults (mirrors startos/file-models/config.ts)
+sandbox/            reviewer image (built ON the Spark, not packed in the s9pk)
+  grader_agent.py reviewer.Dockerfile build.sh
+openclaw/           what each Spark needs provisioned (OpenClaw's job)
+```
+
+## Build
+
+Same path as Nightshift — GitHub CI (`.github/workflows/build.yml`) or a local
+build with `start-cli` (see the s9pk-build-on-mac recipe). The vLLM and reviewer
+images are built **on the Sparks**, not packed into the `.s9pk`.
+
+```
+npm ci && npm run check && npm run build   # type-check + bundle
+make                                        # pack the .s9pk (needs start-cli)
+```
+
+## Status
+
+v0.1 — source complete, `tsc`-clean and Python-syntax-clean. Not yet validated
+against live Sparks. See `openclaw/OPENCLAW_SPEC.md` for the Spark-side
+provisioning (HF model pre-pull is required for air-gapped runs).