1# Nakshatra — Build Instructions
2
3## What this project is
4
5Nakshatra is the **L2 inference engine** in a four-project architecture. One layer in the stack — not the whole system. Read `docs/four-project-architecture.md` first if you have not already; it is the source of truth for project boundaries.
6
7In short:
8- **Neuron (L1)** — chain & economic substrate. `~/neuron/` (`fthrvi/neuron`, not yet pushed). PAUSED at the project level; extracted from prithvi on 2026-05-14.
9- **Nakshatra (L2)** — *this repo*. Patched llama.cpp + worker daemon + sub-GGUF tooling + gRPC chain protocol.
10- **Sthambha (L3)** — peer registry, pillar daemon, identity, layer cache, planner (`plan_split` shipped 2026-05-14), network fabric (designed). `~/sthambha/` (`fthrvi/sthambha`).
11- **Prithvi (L4)** — the agent / being / consciousness. `fthrvi/prithvi` on home PC.
12
13## What goes here, what does not
14
15**Belongs in Nakshatra:**
16- llama.cpp loader + graph builder patches
17- Worker daemon (`experiments/v0.0/worker_daemon.cpp`)
18- Python gRPC worker (`scripts/worker.py`)
19- Sub-GGUF generation (`partial_gguf.py`)
20- Chain orchestration client (`scripts/client.py`)
21- Streaming KV reuse, per-token routing, latency / vendor-portability
22
23**Does NOT belong in Nakshatra:**
24- Peer registry, identity, pillar daemon, model/layer cache, fabric → Sthambha
25- Consciousness, voice, gateway, OpenAI-compatible API → Prithvi
26- Substrate chain / NRN tokenomics / wallet / receipts → **Neuron** at `~/neuron/`. Still PAUSED at the project level; returns alongside Sthambha fabric Mode C. Don't add code that imports chain modules.
27
28If a feature wants to do registry / identity / cache work, it is Sthambha-shaped — flag it as such rather than absorbing it here. Nakshatra stays an inference engine.
29
30## Key reference docs (read in this order)
31
321. `docs/four-project-architecture.md` — architectural decision (2026-05-08), project boundaries, migration plan.
332. `docs/north-star.md` — L1-L4 long vision.
343. `docs/petals-architecture.md` — v0.1 spec (the contract we shipped against).
354. `docs/v0.1-implementation-plan.md` — milestones M1-M7 (all green).
365. `docs/petals-deep-read.md` — Petals comparison + design rationale.
37
38If a v0.1 design decision conflicts with `north-star.md`, v0.1 wins (per the doc's own §"Why this doc exists").
39
40## Cluster
41
425 machines: home PC (Linux + RX 9070 XT) + 4 lab Macs (mac3-2, mentorings-imac-pro, mac4, bishwa). Plain `ssh <hostname>` works via `~/.ssh/config`. See `~/.claude/projects/-Users-bishwanathbastola-nakshatra/memory/nakshatra_cluster_hosts.md` for usernames + Tailscale IPs.
43
44## Patterns
45
46- Use `lsof -ti:PORT | xargs kill -9` to kill workers, NOT `pkill -f scripts/worker.py` (the pkill pattern matches its own command line and self-terminates).
47- Linux home PC needs `loginctl enable-linger prithvi` so workers survive SSH disconnect.
48- Streaming KV reuse: first step `keep_kv=false`, subsequent steps `keep_kv=true` with `start_pos=prefix_length`.
49- Sub-GGUFs declare layer ranges via `nakshatra.layer_range_start/end` metadata; `partial_gguf.py` is the canonical generator.
50