# NeuroBrix System Audit: Hardcoded Values & Fallbacks

**Last Updated: February 2026**

This report identifies 100% of the hardcoded constants, default fallbacks, and embedded business logic found in the NeuroBrix Runtime. It provides an architectural roadmap to migrate these to a purely data-driven model using the NBX Container as the sole Source of Truth (SoT).

**Note:** Many items listed here have been RESOLVED as of February 2026. See Section 5 for resolution status.

---

## 1. CLI Entry Point: `src/neurobrix/cli.py`

**STATUS: ✅ RESOLVED** — All defaults now provided by `runtime/defaults.json` (generated by `forge/importer/builder.py`).

| Variable / Logic | Previous Hardcode | Current Implementation (Feb 2026) | Source of Truth |
| :--- | :--- | :--- | :--- |
| **Inference Steps** | Default: `4` | Read from `defaults.json` (`num_inference_steps`) | `runtime/defaults.json` |
| **CFG Scale** | Default: `3.5` | Read from `defaults.json` (`guidance_scale`) | `runtime/defaults.json` |
| **Height** | Default: `1024` | Computed: `sample_size × vae_scale_factor` | `defaults.json` (generated by importer) |
| **Width** | Default: `1024` | Computed: `sample_size × vae_scale_factor` | `defaults.json` (generated by importer) |
| **Pixel Norm** | `(img - min) / (max - min)` | In VAE decoder graph (`output_range` in `defaults.json`) | `runtime/defaults.json` + graph.json |

**Note:** The file `neurobrix.py` was deleted in February 2026 package restructure. CLI is now `src/neurobrix/cli.py` (pip-installable).

---

## 2. Orchestrator: `src/neurobrix/core/runtime/executor.py`

**STATUS: ✅ MOSTLY RESOLVED** — CFG externalized, dtype from Prism, synthesis declarative.

| Logic / Variable | Previous Hardcode | Current Implementation (Feb 2026) | Source of Truth |
| :--- | :--- | :--- | :--- |
| **CFG Formula** | `uncond + scale * (cond - uncond)` | Externalized to `src/neurobrix/core/cfg/cfg_executor.py` | `topology.json` (cfg strategy) |
| **Negative Prompt** | Default: `""` | Read from `defaults.json` (`negative_prompt`) | `runtime/defaults.json` |
| **VAE Scaling** | `latents / scaling_factor` | In VAE decoder graph as `aten::div` node | `graph.json` |
| **Output Port Fallback** | `["output_0", "sample", "output"]` | Handled by `src/neurobrix/core/runtime/resolution/` | `topology.json` (interface.outputs) |
| **Synthesis Logic** | Hardcoded `global.height/width` | Declarative resolver in `src/neurobrix/core/runtime/resolution/input_synthesizer.py` | `runtime/variables.json` |
| **Dtype Fallback** | Default: `torch.float16` | ✅ From Prism solver (hardware profile) | Hardware YAML → Prism allocation |

**Note:** CFG is now a separate module (`cfg_executor.py`) that handles both batch expansion and guidance application.

---

## 3. Kernel Adapter: `src/neurobrix/kernels/adapter.py`

**STATUS: ✅ RESOLVED** — All op attributes now come from `graph.json`.

| Kernel Parameter | Previous Hardcode | Current Implementation (Feb 2026) | Source of Truth |
| :--- | :--- | :--- | :--- |
| **Epsilon (eps)** | ❌ Default: `1e-5` (broke SDXL) | ✅ Read from `op.attributes.eps` in `graph.json` | `graph.json` (trace system) |
| **Groups (GN)** | ❌ Default: `32` | ✅ Read from `op.attributes.num_groups` | `graph.json` |
| **Softmax Dim** | ❌ Default: `-1` | ✅ Read from `op.attributes.dim` | `graph.json` |
| **GEMM Alpha/Beta** | ❌ Default: `1.0` | ✅ Read from `op.attributes.alpha/beta` | `graph.json` |
| **Triton Tile Size** | `BLOCK_SIZE` caps (e.g., 1024) | Static kernel design (not tunable yet) | Future: Hardware profile |

**Note:** The epsilon fix was critical — SDXL uses `eps=1e-6` while most models use `1e-5`. Hardcoded defaults caused incorrect normalization.

---

## 4. Engine & Solver: `src/neurobrix/core/runtime/graph_executor.py` & `src/neurobrix/core/prism/solver.py`

**STATUS: ✅ MOSTLY RESOLVED** — Dtype centralized, VRAM safety margin configurable, shard logic data-driven.

| Variable | Previous Hardcode | Current Implementation (Feb 2026) | Source of Truth |
| :--- | :--- | :--- | :--- |
| **Dtype Mappings** | Internal dicts | ✅ Centralized in `src/neurobrix/core/dtype/converter.py` | Shared registry |
| **Safety Margin** | Default: `0.85` (VRAM) | Configurable via hardware profile | `config/hardware/*.yml` |
| **Shard Logic** | Regex `block[_.](\d+)` | ✅ Data-driven from `topology.json` shard_map | NeuroTax standard |
| **KV Cache Sizing** | ❌ Used `max_position_embeddings` (28× overestimate) | ✅ Uses `max_tokens + prompt_margin` from `defaults.json` | `runtime/defaults.json` |

**Note:** The KV cache fix was critical for LLM models. Janus-Pro-7B was allocating 18GB KV cache instead of 660MB because it used `max_position_embeddings=16384` instead of `max_tokens=576`.

---

## Strategic Roadmap for Perfection

**Status as of February 2026:**

1.  **✅ Attribute Enforcement (Zero Fallback):**
    *   COMPLETED: `adapter.py` reads `eps`, `num_groups`, and `dim` from `graph.json` attributes. No fallbacks used.
2.  **✅ Mathematical Externalization:**
    *   COMPLETED: CFG formula moved to `src/neurobrix/core/cfg/cfg_executor.py`. VAE scaling embedded in decoder graph.
3.  **✅ Topology-Driven CLI:**
    *   COMPLETED: `src/neurobrix/cli.py` reads all defaults from `runtime/defaults.json` (generated by importer from model metadata).
4.  **⚠️ Hardware-Informed Kernels:**
    *   PARTIALLY DONE: Triton kernels use `src/neurobrix/kernels/classification.py` for op routing. `BLOCK_SIZE` still static (not profile-driven).

---

## 5. Resolution Status (February 2026)

### What Was Fixed

| Category | Issue | Resolution | Impact |
| :--- | :--- | :--- | :--- |
| **CLI Defaults** | Hardcoded steps, CFG, resolution | All read from `defaults.json` | Zero CLI hardcodes |
| **CFG Logic** | Embedded in executor | Externalized to `cfg_executor.py` | Clean separation |
| **Dtype Flow** | Fallback to fp16 | From Prism via hardware profile | Correct precision per GPU |
| **Op Attributes** | Hardcoded eps, groups, dim | Read from `graph.json` | Fixed SDXL (eps=1e-6) |
| **KV Cache** | 28× overestimate | Uses `max_tokens` not `max_position_embeddings` | 660MB vs 18GB |
| **VAE Scaling** | Hardcoded division | In graph as `aten::div` | Data-driven |
| **Resolution** | Hardcoded 1024px | Computed: `sample_size × vae_scale_factor` | Correct for Sana (32x), SDXL (8x) |

### What Remains

| Category | Issue | Current State | Priority |
| :--- | :--- | :--- | :--- |
| **Triton Tiling** | Static `BLOCK_SIZE` | Not profile-driven | Low (performance, not correctness) |
| **Shard Regex** | Legacy regex in some paths | Mostly data-driven | Low (NeuroTax enforces naming) |

### Known Hardcodes (See CLAUDE.md Section 17)

The following hardcodes were identified during audit and documented in CLAUDE.md:

| File | Line | Hardcode | Impact | Status |
|------|------|----------|--------|--------|
| `native_dispatcher.py` | 176-179 | Gemma2/Llama hidden_size | LLM inference | ⚠️ TODO |
| `graph_executor.py` | 244, 395 | `vae_scale = 8` | Sana (needs 32) | ⚠️ TODO |
| `iterative_process.py` | 568 | `max_length = 512` fallback | Sana (needs 300) | ⚠️ TODO |

### Architecture Changes (February 2026)

1. **Package Restructure**: `neurobrix` is now pip-installable (`pip install neurobrix`)
   - Source: `src/neurobrix/` (core/, kernels/, nbx/, config/)
   - CLI: `neurobrix` command (not `python neurobrix.py`)
   - Imports: `from neurobrix.core.*` (not `from core.*`)

2. **Forge Extraction**: Build/trace system separated from runtime
   - Entry: `forge/forge.py` (snap, build, trace, publish)
   - Zero coupling: forge has no imports from neurobrix.core/
   - Communication via files only (.nbx, .cache/graphs/)

3. **Registry System**: neurobrix.es + hub.neurobrix.es
   - Commands: `neurobrix import org/model`, `neurobrix list`, `neurobrix remove`
   - Cache: `~/.neurobrix/cache/` (runtime reads here), `~/.neurobrix/store/` (.nbx downloads)

### Lessons Learned

1. **ZERO FALLBACK Principle**: System must crash explicitly if data is missing, not silently default
2. **Data-Driven Everything**: All values must come from NBX container (manifest, defaults, graph, topology)
3. **Separation of Concerns**: Runtime (neurobrix.core/) has ZERO imports from build/trace (forge/)
4. **Cache Architecture**: `.nbx` is transport only, runtime ALWAYS reads from `.cache/models/`
