# NeuroBrix System - Project Overview & Rules

## 1. Core Philosophy: ZERO Principles
- **ZERO HARDCODE:** NEVER hardcode dimensions, paths, keys, or values. All values derived from NBX container.
- **ZERO FALLBACK:** System must CRASH explicitly if data is missing. No silent defaults.
- **ZERO SEMANTIC:** Runtime has NO domain knowledge ("image", "latent", "vae"). Only tensors and axes.
- **ZERO DEFER:** When a problem is detected, fix it NOW — even if it's outside your current scope. Accumulating problems creates compound problems. Never leave a known issue for later.
- **Source of Truth:** The `.nbx` container is the ONLY source of truth.

## 2. System Separation (CRITICAL)

```
PUBLIC — neurobrix package (src/neurobrix/)
  Dev:     PYTHONPATH=src python -m neurobrix <command>
  Install: pip install neurobrix → neurobrix <command>
  Commands: run, info, inspect, validate, import, list, remove, clean, hub
  Cache: ~/.neurobrix/ (store/ + cache/)
  Deep reference: src/neurobrix/CLAUDE.md

PRIVATE — NeuroBrix Forge (forge/)
  Entry point: python forge/forge.py <command>
  Commands: snap, build, trace, publish, local
  NO pip install — self-contained (FORGE_ROOT in sys.path)
  Cache: .cache/ (graphs/, models/)
  Deep reference: forge/CLAUDE.md
```

**ZERO COUPLING:** forge/ has zero imports from neurobrix.*. neurobrix has zero imports from forge/. Communication is via files only (.nbx in models/).

## 3. NBX File vs Cache Architecture

**The `.nbx` file is ONLY for transport/packaging. Runtime NEVER reads from `.nbx` directly.**

```
BUILD:   forge/forge.py build → Creates .nbx (zip archive)
IMPORT:  .nbx → Extracted to ~/.neurobrix/cache/<model_name>/
RUNTIME: Always reads from ~/.neurobrix/cache/<model_name>/
```

**Cache files are generated, NOT editable.** Fix at source (forge/importer/ or forge/tracer/), rebuild.

| Cache File | Fix Location |
|------------|--------------|
| `defaults.json`, `manifest.json`, `variables.json`, `weights/` | forge/importer/ |
| `graph.json`, `topology.json` | `forge/forge.py trace` |

## 4. CLI Commands Reference

### Run
```bash
neurobrix run --model PixArt-Sigma-XL-2-1024-MS --hardware v100-32g --prompt "A sunset" --steps 10
neurobrix run --model deepseek-moe-16b-chat --hardware c4140-4xv100-custom-nvlink --prompt "Hello"
PYTHONPATH=src python -m neurobrix run --model ... --hardware ... --prompt ...  # Dev mode
```

### Registry & Model Management
```bash
neurobrix hub [--category IMAGE] [--search sana]
neurobrix import sana/1600m-1024 [--no-keep]
neurobrix list [--store]
neurobrix remove 1600m-1024 [--store|--all]
neurobrix clean [--store|--cache|--all] [-y]
```

### Forge Commands (Private)
```bash
python forge/forge.py snap --name PixArt-alpha/PixArt-Sigma-XL-2-1024-MS
python forge/forge.py build --snapshot-path /path/to/snapshot --family image [--overwrite]
python forge/forge.py trace --family llm --model deepseek-moe-16b-chat
python forge/forge.py local models/image/FLUX.2-dev/model.nbx [--overwrite]
NEUROBRIX_API_TOKEN=nbx_... python forge/forge.py publish model.nbx --org sana --name 1600m-1024 --category IMAGE
```

### Families
- `image` - Diffusion (PixArt, Sana, Janus, FLUX)
- `llm` - Language models (DeepSeek, Llama, Mistral)
- `audio` - Audio (Whisper)
- `video` - Video (CogVideoX)

### Hardware Profiles
- `v100-32g` / `v100-32g-2` / `v100-32g-3` - Single V100 32GB
- `v100-16g` - Single V100 16GB
- `c4140-4xv100-custom-nvlink` - 4x V100 NVLink cluster
- `v100-32g-x2-nvlink` - 2x V100 32GB NVLink
- `c4140-4xv100-16GB-nvlink` - 4x V100 16GB NVLink
- Location: `src/neurobrix/config/hardware/` (neurobrix) + `forge/config/hardware/` (forge)

## 5. Workflow Protocol

```
Trace:   forge/forge.py trace   → .cache/graphs/
Build:   forge/forge.py build   → models/*.nbx
Publish: forge/forge.py publish → MinIO (internal, presigned PUT, ~580 MB/s)
Local:   forge/forge.py local   → ~/.neurobrix/cache/ (dev shortcut)
Import:  neurobrix import       → hub.neurobrix.es signed URL → ~/.neurobrix/cache/
Run:     neurobrix run          → RuntimeExecutor from topology.json
```

### Registry Architecture
```
neurobrix.es (Next.js + PostgreSQL, 10.0.0.39:3000)
  Publish: forge → presigned PUT → MinIO (10.0.0.36:9000)
  Download: user → hub.neurobrix.es → Cloudflare → HAProxy → MinIO
  Auth: NEUROBRIX_API_TOKEN=nbx_... (Bearer token)
  Security: OPNsense ACL restricts hub.neurobrix.es to /neurobrix/ path only
```

## 6. Code Hygiene Rules (MANDATORY)

### ZERO DEAD CODE Principle
1. **Unused Functions:** Delete functions that are no longer called
2. **Unused Parameters:** Remove function parameters that aren't used
3. **Unused Imports:** Remove imports that aren't referenced
4. **Dead Branches:** Remove if/else branches that can never execute
5. **Commented Code:** Delete commented-out code (use git history)
6. **Unused Flags:** Remove CLI flags, env vars, or config options that aren't used
7. **Obsolete Files:** Delete files that are no longer part of the system
8. **Never Leave "TODO: Remove" Comments:** Remove it NOW.

## 7. Output Convention

**TOUJOURS generer les images de test dans la RACINE du projet** (`/home/mlops/NeuroBrix_System/`), pas dans `/tmp/`.

## 8. Modification Tracking

**All code modifications MUST be logged in `MODIFICATIONS.md`** at the project root.

## 9. Refactoring History (Phases 12-18, Jan-Feb 2026)

- Config wrappers removed: use `core/config/hardware.py` and `core/config/family.py` directly
- Trace: `forge/forge.py trace` (forge/tracer/ is 100% independent of core/)
- Forge: unified CLI (`forge/forge.py snap|build|trace|publish`)
- Package: `pip install neurobrix`, hatchling backend
- Registry: neurobrix.es API, MinIO storage
- Separation: forge/ ZERO imports from neurobrix.*, cache split (`.cache/` = forge, `~/.neurobrix/` = neurobrix)
- CFG: `cfg_executor.py` + `strategy.py` → `cfg/engine.py` (unified CFGEngine)
- Bricks: `core/module/cache/factory.py` (StateCacheFactory), `core/module/text/processor.py` (TextProcessor)
- SDPA: Direct `F.scaled_dot_product_attention` call (no decomposed path, no upcast flag)

## 10. Deep Technical References

For deep technical details, see the component-specific CLAUDE.md files:
- **neurobrix runtime:** `src/neurobrix/CLAUDE.md` — runtime architecture, dtype flow, memory management, CompiledSequence, Prism, autoregressive flow, kernels, KV cache
- **forge (trace/build):** `forge/CLAUDE.md` — TorchDispatchMode trace mechanism, 3-phase architecture, vendor isolation, hardware constraints, debugging guide
