## Synthèse — Architecture d'Exécution NeuroBrix 2026

(Version professionnelle, stable, sans spéculation — mise à jour février 2026)

### 1. Positionnement technique

NeuroBrix est un runtime multihardware et multivendor, conçu pour exécuter des modèles IA modernes avec une approche déterministe, sans fallback implicite, en appliquant la Zero Fallback Policy sur l'ensemble du pipeline.

**NeuroBrix est désormais un package pip-installable** (`pip install neurobrix`), séparé du système de forge. Le système est divisé en deux parties distinctes :

- **PUBLIC** — Package `neurobrix` : Runtime d'exécution, CLI utilisateur (`neurobrix run`)
- **PRIVATE** — Forge : Outils de construction (`forge/forge.py build`, `trace`, `publish`)

Son rôle est de :
- analyser les modèles,
- produire un graphe interne maître (NBX Graph),
- générer un `topology.json` fidèle,
- répartir les opérations entre moteurs d'exécution (Compiled, Native, Triton),
- garantir la compatibilité totale avec tous les modèles modernes.

### 2. Topology Generation — Méthode validée

**ONNX n'est PAS utilisé dans NeuroBrix.** Le système trace directement au niveau PyTorch.

La seule méthode garantissant un `topology.json` 100% correct est :

1. **Tracer le modèle directement au niveau PyTorch**

En capturant :
- la séquence exacte des opérations,
- les shapes,
- les attributs,
- les dépendances entre tensors,
- les branches dynamiques (si elles existent).

2. **Construire le NBX Graph (graphe interne normalisé)**

Avec la terminologie NeuroTax, indépendante de tout framework.

3. **Générer le `topology.json` depuis le NBX Graph**

Cette méthode est 100% fiable, reproductible, déterministe.

**Système de trace** : `forge/tracer/` (anciennement `trace/`) — système complètement séparé du runtime.

### 3. Exécution — Architecture NeuroBrix 2026

NeuroBrix offre **3 modes d'exécution** :

#### 3.1. Mode "compiled" (DÉFAUT)

**CompiledSequenceV2 + DtypeEngine AMP**

- **Zero overhead** : Aucune lookup de dictionnaire pendant l'exécution
- **Arena-based** : TensorArena avec slots entiers pour accès O(1)
- **AMP (Automatic Mixed Precision)** : Implémente les règles d'autocast PyTorch
  - FP32 ops : `pow`, `rsqrt`, `softmax`, `sum`, `layer_norm`, etc.
  - FP16 ops : `mm`, `bmm`, `conv2d`, `linear`, etc.
  - Promote ops : Promotion automatique pour opérations mixtes
- **Liveness analysis** : Libération automatique de la mémoire des tenseurs morts
- **Closure-based resolvers** : Résolution d'inputs via références capturées

**Fichiers** :
- `src/neurobrix/core/runtime/graph/compiled_sequence.py` — CompiledSequenceV2
- `src/neurobrix/core/dtype/engine.py` — DtypeEngine (règles AMP)
- `src/neurobrix/core/runtime/graph_executor.py` — Intégration

**Performance** :
- ~75% plus rapide que le mode séquentiel
- Utilisation GPU 80-95% (vs 40-60% en mode debug)
- Source de vérité : PyTorch `aten/src/ATen/autocast_mode.h`

#### 3.2. Mode "native" (--seq_aten)

**SequentialDispatcher — Mode debug PyTorch ATen**

- Exécution séquentielle via dict lookups
- Utilisé pour le débogage et la validation
- Pas d'optimisations AMP (fixes ad-hoc par opération)
- Plus lent mais plus facile à déboguer

**Fichiers** :
- `src/neurobrix/core/runtime/native_dispatcher.py`

#### 3.3. Mode "triton" (--triton)

**Custom Triton Kernels — R&D uniquement**

- Kernels Triton personnalisés pour opérations spécifiques
- Classification TRITON vs METADATA (`kernels/classification.py`)
- **PURE TRITON RULE** : Kernels dans `kernels/ops/` doivent être 100% Triton pur
- Pas de production (expérimental)

**Fichiers** :
- `src/neurobrix/kernels/adapter.py` — Traduction ATen → kernel
- `src/neurobrix/kernels/classification.py` — Classification TRITON/METADATA
- `src/neurobrix/kernels/mapping.py` — Mapping ATen → kernel name
- `src/neurobrix/kernels/ops/` — Kernels Triton purs

**Note** : Il n'y a **PAS** de "CPU fallback", "Universal GPU Backend", ou runtime C++/Rust dans NeuroBrix. Le système utilise exclusivement PyTorch comme backend.

#### 3.4. Zero Fallback Policy

Aucune substitution silencieuse, aucune improvisation.
Si une opération n'a pas d'exécuteur :
→ **NeuroBrixUnsupportedOperationError**

Le système doit **crasher explicitement** si des données sont manquantes. Pas de defaults silencieux.

### 4. Architecture Runtime Modulaire (Février 2026)

L'exécuteur runtime suit une architecture modulaire stricte :

#### 4.1. Pipeline d'exécution

```
RuntimePackage (loader.py)
    ↓
RuntimeExecutor (executor.py) — Orchestrateur
    ↓
FlowHandler (flow/base.py) — Factory pattern
    ↓
GraphExecutor (graph_executor.py)
    ↓
CompiledSequenceV2 (compiled_sequence.py) + DtypeEngine (dtype/engine.py)
```

#### 4.2. Structure des fichiers

```
src/neurobrix/
├── cli.py                    # CLI : run, info, inspect, validate, import, list, remove
├── core/
│   ├── runtime/
│   │   ├── executor.py       # RuntimeExecutor — Orchestrateur
│   │   ├── loader.py         # RuntimePackage — Chargement NBX
│   │   ├── factory.py        # ExecutorFactory — Création executors
│   │   ├── graph_executor.py # GraphExecutor — Exécution TensorDAG
│   │   ├── weight_loader.py  # WeightLoader — Chargement poids
│   │   ├── graph/
│   │   │   ├── compiled_sequence.py  # CompiledSequenceV2
│   │   │   ├── compiled_ops.py       # CompiledOpV2
│   │   │   ├── tensor_resolver.py    # TensorArena
│   │   │   └── sequential_dispatcher.py  # SequentialDispatcher
│   │   ├── flow/
│   │   │   ├── base.py               # FlowContext, FlowHandler ABC
│   │   │   ├── iterative_process.py  # Diffusion (pre_loop → loop → post_loop)
│   │   │   ├── static_graph.py       # Single-pass
│   │   │   ├── forward_pass.py       # Sequential transformer
│   │   │   └── autoregressive.py     # Token generation (LLM + VQ image)
│   │   ├── resolution/
│   │   │   └── input_synthesizer.py  # Résolution + synthèse inputs
│   │   ├── extraction/
│   │   │   └── output_processor.py   # Extraction outputs
│   │   └── cfg/
│   │       ├── cfg_executor.py       # Classifier-Free Guidance
│   │       └── strategy.py           # Stratégies CFG
│   ├── dtype/
│   │   ├── engine.py         # DtypeEngine — AMP autocast rules
│   │   ├── converter.py      # Conversions dtype
│   │   └── __init__.py       # DTensor wrapper
│   ├── prism/
│   │   └── solver.py         # PrismSolver — Hardware-aware strategy
│   ├── strategies/
│   │   ├── base.py           # Strategy ABC
│   │   ├── fgp.py            # Fine-Grained Pipeline
│   │   ├── pipeline.py       # Pipeline Parallel
│   │   ├── tensor_parallel.py # Tensor Parallel
│   │   └── zero3.py          # ZeRO-3 Offload
│   └── nbx/
│       └── cache.py          # NBXCache — Gestion cache utilisateur
├── kernels/
│   ├── adapter.py            # Triton adapter
│   ├── classification.py     # TRITON/METADATA classification
│   ├── mapping.py            # ATen → kernel mapping
│   └── ops/                  # Pure Triton kernels
└── config/
    ├── hardware/             # Profils hardware YAML
    └── vendors/              # Configurations vendor
```

#### 4.3. Forge (système privé)

```
forge/
├── forge.py                  # CLI : snap, build, trace, publish
├── importer/
│   ├── builder.py            # NBXBuilder — Construction .nbx
│   ├── analyzer.py           # Analyse snapshots
│   └── weights/
│       └── sharder.py        # Sharding poids
├── tracer/                   # Système de trace (anciennement trace/)
│   ├── capture.py            # Capture PyTorch
│   ├── dynamo.py             # TorchDynamo integration
│   ├── orchestrator.py       # Orchestration trace
│   └── stimulus/
│       ├── generator.py      # Génération inputs
│       └── resolver.py       # Résolution shapes
├── vendors/                  # Diffusers vendorisé
└── config/families/          # Templates YAML families
```

#### 4.4. Principes architecturaux

- **Factory Pattern** : `@register_flow` + `get_flow_handler()`
- **Single Responsibility** : Chaque handler gère UN flow type
- **ZERO HARDCODE** : Configuration depuis `topology.json`
- **ZERO COUPLING** : `forge/` a zéro imports depuis `neurobrix.core/`
- **Data-Driven** : Toutes les valeurs dérivées du container NBX

### 5. Flow Handlers

Les flow handlers orchestrent les différents types d'exécution :

| Flow Type | Handler | Usage |
|-----------|---------|-------|
| `iterative_process` | `IterativeProcessFlow` | Diffusion (PixArt, Sana, Flux) |
| `autoregressive_text` | `AutoregressiveFlow` | LLMs (DeepSeek, Llama) |
| `autoregressive_image` | `AutoregressiveFlow` | VQ image (Janus) |
| `forward_pass` | `ForwardPassFlow` | Transformers séquentiels |
| `static_graph` | `StaticGraphFlow` | Single-pass |

**Critical** : `autoregressive.py` gère DEUX familles (`image` + `llm`). Chaque modification DOIT être conditionnée par `gen_type` ou `family` pour éviter les régressions.

### 6. Prism — Hardware-Aware Strategy

Prism est le solveur de stratégie hardware-aware :

**Stratégies disponibles** :
- `SINGLE_GPU` — Single GPU (lazy/eager/lifecycle)
- `PP_NVLINK` — Pipeline Parallel avec NVLink
- `PP_PCIE` — Pipeline Parallel avec PCIe
- `TP_INTENT` — Tensor Parallel (expérimental)
- `ZERO3_OFFLOAD` — ZeRO-3 avec offload CPU
- `COMPONENT_AFFINITY` — Affinité par composant

**KV Cache** :
- Taille basée sur `defaults.json → max_tokens + prompt_margin (128)`
- **JAMAIS** `max_position_embeddings` (28× trop grand)
- Validation de fit avant sélection stratégie
- Fallback loop si meilleure stratégie ne peut pas fitter KV cache

**Lifecycle Classification** (autoregressive models) :
- **Persistent** : `language_model`, `gen_head`, `gen_embed`, `gen_aligner`
- **Transient** : `vision_model`, `gen_vision_model`, `aligner`

### 7. Cache et Registry

#### 7.1. Architecture Cache

```
~/.neurobrix/
├── store/          # Fichiers .nbx téléchargés (9+ GB chacun)
└── cache/          # Modèles extraits (runtime lit ICI)
    └── model-name/
        ├── manifest.json
        ├── topology.json
        ├── runtime/
        │   ├── defaults.json
        │   ├── variables.json
        │   └── execution.json
        ├── components/
        │   └── transformer/
        │       ├── graph.json
        │       ├── runtime.json
        │       └── weights/
        └── modules/
```

**CRITICAL** : Le runtime lit **TOUJOURS** depuis `~/.neurobrix/cache/`, **JAMAIS** depuis le fichier `.nbx`. Le `.nbx` est uniquement un format de transport.

#### 7.2. Registry (neurobrix.es)

- **API** : Next.js (10.0.0.39:3000) + PostgreSQL (10.0.0.35:5432)
- **Storage** : MinIO (10.0.0.36:9000), bucket `neurobrix`
- **Download** : `hub.neurobrix.es` (Cloudflare → HAProxy → MinIO)
- **Upload** : Presigned PUT via internal network (~580 MB/s)
- **Auth** : API tokens `nbx_...` (Bearer auth)

**Commandes** :
```bash
# Download model from registry
neurobrix import sana/1600m-1024

# List installed models
neurobrix list

# Remove model from cache
neurobrix remove 1600m-1024
neurobrix remove 1600m-1024 --store  # Also delete .nbx
```

### 8. DtypeEngine — Automatic Mixed Precision

Le DtypeEngine implémente les règles PyTorch AMP (source : `aten/src/ATen/autocast_mode.h`) :

**Catégories d'opérations** :

| Catégorie | Ops | Comportement |
|-----------|-----|--------------|
| **FP32** | `pow`, `rsqrt`, `softmax`, `sum`, `layer_norm`, `rms_norm` | Upcast vers fp32 |
| **FP16** | `mm`, `bmm`, `conv2d`, `linear` | Downcast vers fp16 |
| **Promote** | `add`, `mul`, `div` | Promotion type commun |

**Exemple (RMSNorm)** :
```
Sans AMP:   pow(fp16) → mean(fp16) → rsqrt(fp16) → Inf → ALL ZEROS
Avec AMP:   pow(fp32) → mean(fp32) → rsqrt(fp32) → matmul(fp16) → OK
```

**CRITICAL** : Ne JAMAIS retirer les règles AMP — elles sont universellement applicables per design PyTorch.

### 9. Format ATen Op Type (CRITIQUE)

**Format canonique** : `aten::{op}`

```
CORRECT:
  aten::view
  aten::mm
  aten::scaled_dot_product_attention

FAUX:
  aten.view.default  (format Dynamo — convertir immédiatement)
  aten_view          (identifiant Python — jamais utiliser)
  view               (nom nu — seulement pour lookup kernel)
```

**Flow de format** :
```
GRAPH (graph.json):
  op_uid: "aten.view::0"     (dot dans UID pour unicité)
  op_type: "aten::view"      (double colon - CANONIQUE)

RUNTIME (graph_executor.py):
  Utilise op_type directement: aten::view

KERNELS (adapter.py):
  Strip prefix pour lookup: view
```

### 10. Debug et Performance

**Variables d'environnement** :

| Variable | Effet |
|----------|-------|
| `NBX_DEBUG=1` | Logging verbose (force GPU sync, 2× plus lent) |
| `NBX_TRACE_ZEROS=1` | Trouve première op produisant all-zero |
| `NBX_TRACE_NAN=1` | Trace NaN/Inf dans premières ops |
| `NBX_NAN_GUARD=1` | Remplace NaN par 0 (2.5× plus lent) |

**Performance** :

| Mode | GPU Util | Step Time |
|------|----------|-----------|
| Compiled (default) | 80-95% | ~1150ms |
| Native (--seq_aten) | 60-75% | ~1500ms |
| Debug (NBX_DEBUG=1) | 40-60% | ~2000ms |

### 11. CLI Commands

**Runtime (public)** :
```bash
# Run model
neurobrix run --model PixArt-Sigma-XL-2-1024-MS --hardware v100-32g --prompt "A sunset"

# Registry operations
neurobrix import sana/1600m-1024
neurobrix list
neurobrix remove model-name

# Dev mode
PYTHONPATH=src python -m neurobrix run --model ... --hardware ...
```

**Forge (private)** :
```bash
# Snap model from HuggingFace
python forge/forge.py snap --name PixArt-alpha/PixArt-Sigma-XL-2-1024-MS

# Build .nbx from snapshot
python forge/forge.py build --snapshot-path /path/to/snapshot --family image

# Trace model graphs
python forge/forge.py trace --family llm --model deepseek-moe-16b-chat

# Publish to registry
NEUROBRIX_API_TOKEN=nbx_... python forge/forge.py publish models/image/model.nbx \
  --org sana --name 1600m-1024 --category IMAGE
```

### 12. Imports et Package Structure

**Imports publics** (depuis code utilisateur) :
```python
from neurobrix.core.runtime import RuntimeExecutor
from neurobrix.nbx import NBXContainer
from neurobrix.core.prism import PrismSolver
```

**Imports forge** (système privé) :
```python
from neurobrix.nbx.neurotax import NeuroTaxonomy  # Forge dépend du package
from tracer.capture import capture_model          # Tracer est indépendant
```

**ZERO COUPLING** : `forge/` n'importe rien depuis `neurobrix.core/`. `neurobrix.core/` n'importe rien depuis `forge/`. Communication uniquement via fichiers (`.nbx`, `.cache/graphs/`).

### 13. Conclusion

NeuroBrix 2026 est un système **production-ready** :

- **3 modes d'exécution** : compiled (défaut), native (debug), triton (R&D)
- **Architecture modulaire** : Separation of concerns stricte
- **AMP automatique** : Stabilité numérique garantie
- **Hardware-aware** : Prism solver avec 6 stratégies
- **Package pip** : Installation standard Python
- **Registry intégré** : Download/upload via neurobrix.es
- **Zero hardcode** : Tout dérivé du container NBX

**Pas d'ONNX. Pas de CPU fallback. Pas de runtime C++.** Uniquement PyTorch natif avec optimisations zero-overhead.
