# NEUROBRIX : ANALYSE DES FAIBLESSES CONCURRENTES & PROPOSITION

**Document Status**: Aspirational vision document (February 2026)
**Current Reality**: NeuroBrix is a pure Python + Triton system. Vision of compiled native runtimes archived.

## PARTIE 1 : LES FAIBLESSES DE CHAQUE SYSTÈME

---

### PYTORCH (Meta)

```
FAIBLESSES:
───────────

1. EAGER MODE PAR DÉFAUT = LENT
   - Chaque opération passe par Python
   - Overhead énorme pour l'inférence
   - Pas conçu pour la production à l'origine

2. torch.compile EST IMMATURE
   - Sorti en 2023, encore instable
   - "Graph breaks" fréquents (retombe en eager)
   - Pas toutes les ops supportées
   - Compilation lente au premier run

3. MULTI-GPU COMPLIQUÉ
   - DDP/FSDP = complexe à configurer
   - Pas de sharding automatique intelligent
   - Doit connaître ton hardware à l'avance

4. MÉMOIRE MAL GÉRÉE
   - Allocateur pas optimal
   - Fragmentation mémoire
   - Pas de paging automatique CPU↔GPU

5. DÉPENDANCE PYTHON
   - Pas de runtime standalone
   - GIL Python = bottleneck
   - Déploiement = embarquer Python entier

6. FORMAT POIDS FRAGMENTÉ
   - .pt, .bin, .safetensors... pas de standard
   - Checkpoints énormes
   - Pas de streaming natif
```

---

### [ARCHIVED] ONNX / ONNX Runtime (Microsoft)

**Note**: NeuroBrix no longer pursues ONNX compatibility. The NBX format is the single source of truth.

```
FAIBLESSES:
───────────

1. EXPORT ONNX = CAUCHEMAR
   - Pas toutes les ops PyTorch supportées
   - Dynamic shapes problématiques
   - Différences de comportement post-export
   - Debugging quasi-impossible

2. OPSET VERSIONING HELL
   - Chaque version = ops différentes
   - Compatibilité arrière pas garantie
   - Model exporté en opset 17 ≠ opset 14

3. GRAPH STATIQUE FIGÉ
   - Pas de control flow dynamique
   - Batch size souvent fixé
   - Pas d'adaptation runtime

4. OPTIMISATIONS LIMITÉES
   - Moins bon que TensorRT sur NVIDIA
   - Moins bon que CoreML sur Apple
   - "Moyen partout, excellent nulle part"

5. PAS DE TRAINING
   - Inference only
   - Pas de gradients
   - Pas de fine-tuning

6. CUSTOM OPS = GALÈRE
   - Implémenter une op custom = complexe
   - Pas de kernel fusion automatique
   - Extensions difficiles
```

---

### TensorRT (NVIDIA)

```
FAIBLESSES:
───────────

1. NVIDIA ONLY !!!
   - Zéro support AMD
   - Zéro support Intel
   - Zéro support Apple Silicon
   - Lock-in hardware total

2. CONVERSION LENTE
   - Build du engine = minutes/heures
   - Doit rebuilder pour chaque GPU différent
   - Pas portable entre architectures NVIDIA

3. BOÎTE NOIRE
   - Code source fermé (core)
   - Debugging = impossible
   - "Ça marche pas" = bonne chance

4. BATCH SIZE / SHAPES FIXÉS
   - Doit spécifier min/max/opt shapes
   - Rebuild si tu veux changer
   - Pas vraiment dynamique

5. MÉMOIRE INFLEXIBLE
   - Alloue tout à l'avance
   - Pas de paging
   - Pas de partage entre models

6. LLMs = TENSORRT-LLM SÉPARÉ
   - Produit complètement différent
   - API différente
   - Pas unifié
```

---

### vLLM / TGI (LLM Inference)

```
FAIBLESSES:
───────────

1. LLM ONLY
   - Pas d'image generation
   - Pas de video
   - Pas d'audio
   - Spécialisé = limité

2. ARCHITECTURES HARDCODÉES
   - Liste fixe de modèles supportés
   - Nouveau modèle = PR dans leur repo
   - Pas universel

3. DÉPENDANCE PYTORCH
   - Pas de runtime indépendant
   - Embarque tout l'écosystème

4. MULTI-GPU BASIQUE
   - Tensor parallelism OK
   - Mais pas de placement intelligent
   - Pas d'hétérogénéité (16GB + 32GB)

5. PAS DE TRAINING
   - Inference only
   - Pas de fine-tuning intégré
```

---

### Triton Inference Server (NVIDIA)

```
FAIBLESSES:
───────────

1. COMPLEXITÉ ÉNORME
   - Configuration = usine à gaz
   - Model repository structure rigide
   - Courbe d'apprentissage brutale

2. NVIDIA-CENTRIC
   - Optimisé pour NVIDIA
   - Autres backends = citoyens de seconde classe

3. OVERHEAD RÉSEAU
   - Conçu pour serving HTTP/gRPC
   - Pas optimal pour local
   - Latence ajoutée

4. PAS UN RUNTIME
   - C'est un SERVER
   - Dépend de backends (PyTorch, ONNX, TensorRT)
   - Pas d'exécution propre
```

---

### JAX / XLA (Google)

```
FAIBLESSES:
───────────

1. COURBE D'APPRENTISSAGE
   - Functional programming = différent
   - Moins de ressources/tutoriels
   - Communauté plus petite

2. TPU-CENTRIC
   - Optimisé pour Google TPU
   - GPU = citoyen de seconde classe
   - Apple Silicon = oublie

3. ÉCOSYSTÈME FRAGMENTÉ
   - Flax, Haiku, Optax... trop de choix
   - Pas de standard clair

4. DEBUGGING DIFFICILE
   - JIT compilation = erreurs cryptiques
   - Traceback incompréhensibles
```

---

## PARTIE 2 : TABLEAU RÉCAPITULATIF

```
┌──────────────────┬────────┬───────┬─────────┬───────┬────────┬───────────┐
│                  │PyTorch │ ONNX  │TensorRT │ vLLM  │ Triton │   JAX     │
├──────────────────┼────────┼───────┼─────────┼───────┼────────┼───────────┤
│ Multi-hardware   │   ⚠️   │  ✅   │   ❌    │  ⚠️   │   ⚠️   │    ⚠️     │
│ Performance      │   ⚠️   │  ⚠️   │   ✅    │  ✅   │   ✅   │    ✅     │
│ Dynamic shapes   │   ✅   │  ❌   │   ❌    │  ⚠️   │   ⚠️   │    ⚠️     │
│ Training         │   ✅   │  ❌   │   ❌    │  ❌   │   ❌   │    ✅     │
│ Fine-tuning      │   ✅   │  ❌   │   ❌    │  ❌   │   ❌   │    ✅     │
│ Multi-GPU auto   │   ❌   │  ❌   │   ❌    │  ⚠️   │   ⚠️   │    ✅     │
│ Hétérogène GPU   │   ❌   │  ❌   │   ❌    │  ❌   │   ❌   │    ❌     │
│ Memory paging    │   ❌   │  ❌   │   ❌    │  ✅   │   ❌   │    ❌     │
│ Universal models │   ⚠️   │  ⚠️   │   ❌    │  ❌   │   ⚠️   │    ⚠️     │
│ Standalone       │   ❌   │  ✅   │   ✅    │  ❌   │   ✅   │    ❌     │
│ Open source      │   ✅   │  ✅   │   ❌    │  ✅   │   ⚠️   │    ✅     │
│ Easy deployment  │   ❌   │  ⚠️   │   ⚠️    │  ⚠️   │   ❌   │    ❌     │
└──────────────────┴────────┴───────┴─────────┴───────┴────────┴───────────┘

Note: ONNX column retained for competitive analysis only. NeuroBrix uses NBX format exclusively.

✅ = Bon    ⚠️ = Partiel/Limité    ❌ = Non supporté
```

---

## PARTIE 3 : CE QUE PERSONNE NE FAIT BIEN

```
1. HARDWARE HÉTÉROGÈNE
   ─────────────────────
   Personne ne gère: "J'ai 2x V100-16GB + 2x V100-32GB"
   Tous supposent: GPUs identiques

2. UNIVERSAL MODEL SUPPORT
   ────────────────────────
   Tout le monde: if model == "llama" ... elif model == "flux" ...
   Personne: Architecture générique qui marche pour TOUT

3. AUTOMATIC OPTIMAL PLACEMENT
   ────────────────────────────
   Personne ne calcule: "Layer 42 sur GPU 2 car il a plus de VRAM"
   Tous: Naïf round-robin ou manuel

4. SEAMLESS TRAINING ↔ INFERENCE
   ──────────────────────────────
   Training: PyTorch
   Inference: ONNX/TensorRT
   Conversion: Manuelle, buggy, perte de features

5. MEMORY INTELLIGENCE
   ────────────────────
   Personne: Offload automatique CPU↔GPU selon pression mémoire
   vLLM: Fait du paging mais LLM-only

6. TRUE PORTABILITY
   ─────────────────
   Export un model, run partout?
   ONNX essaie mais: ops manquantes, comportement différent

7. ZERO-CONFIG MULTI-GPU
   ──────────────────────
   Personne: "Voici mon model, voici mes GPUs, débrouille-toi"
   Tous: Configuration manuelle requise
```

---

## PARTIE 4 : LA VISION NEUROBRIX

**Current Reality (February 2026)**: NeuroBrix is a pure Python + Triton runtime system with the following achieved goals:

```
ACHIEVED (v0.1):
  ✅ Universal .nbx format (graph + weights)
  ✅ Zero model hardcoding (recipe-driven execution)
  ✅ Intelligent multi-GPU placement (PRISM solver)
  ✅ Heterogeneous GPU support (16GB + 32GB mix)
  ✅ Dynamic dtype resolution (bf16/fp16/fp32)
  ✅ Zero-config execution (neurobrix run --model ... --hardware ...)
  ✅ Registry system (neurobrix.es with import/list/remove)
  ✅ DtypeEngine with PyTorch AMP autocast rules
  ✅ CompiledSequenceV2 (zero-overhead execution)

IN PROGRESS:
  🔄 Triton kernel coverage (R&D, --triton flag)
  🔄 Memory paging CPU↔GPU
  🔄 Training/fine-tuning support

ARCHIVED (not pursued):
  ❌ C++ / Rust / Zig / Mojo native runtime
  ❌ ONNX compatibility
  ❌ Standalone binary (requires Python + PyTorch)
```

### Philosophie Core

```
"N'IMPORTE QUEL MODÈLE SUR N'IMPORTE QUEL HARDWARE"

Reality Check:
- Zero model hardcoding ✅ (recipe-driven)
- Zero runtime dependencies ❌ (requires Python + PyTorch)
- Zero manual configuration ✅ (PRISM auto-placement)
- Zero conversion/export ✅ (.nbx is the format)
- Zero vendor lock-in ⚠️ (NVIDIA only for now, AMD/Metal future work)
```

### Architecture Actuelle (February 2026)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│                   NEUROBRIX RUNTIME (Python + Triton)                       │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      GRAPH EXECUTION LAYER                           │   │
│  │                  (src/neurobrix/core/runtime/)                       │   │
│  │                                                                      │   │
│  │   • Format .nbx (graph.json + weights + manifest)                   │   │
│  │   • RuntimeExecutor orchestrates from execution.json                │   │
│  │   • CompiledSequenceV2: zero-overhead arena execution               │   │
│  │   • DtypeEngine: PyTorch AMP autocast rules for stability           │   │
│  │   • Three modes: compiled (default), native (--seq_aten), triton    │   │
│  │                                                                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                              PRISM                                   │   │
│  │                  (src/neurobrix/core/prism/)                         │   │
│  │                                                                      │   │
│  │   • Hardware detection (NVIDIA GPUs, VRAM, NVLink)                  │   │
│  │   • Strategy scoring: single_gpu, zero3, pipeline, tensor_parallel  │   │
│  │   • KV cache estimation from defaults.json (LLMs)                   │   │
│  │   • Lifecycle classification (persistent vs transient components)   │   │
│  │   • Dtype resolution: bf16/fp16/fp32 per hardware profile           │   │
│  │   • Fallback loop if best strategy doesn't fit                      │   │
│  │                                                                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        KERNEL BACKENDS                               │   │
│  │                                                                      │   │
│  │   ┌──────────────────┐  ┌──────────────────┐                        │   │
│  │   │  PyTorch ATen    │  │  Triton (R&D)    │                        │   │
│  │   │  (DEFAULT)       │  │  (--triton flag) │                        │   │
│  │   │  CUDA dispatch   │  │  Custom kernels  │                        │   │
│  │   └──────────────────┘  └──────────────────┘                        │   │
│  │                                                                      │   │
│  │   NVIDIA CUDA ONLY (AMD/Metal future work)                          │   │
│  │                                                                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

CLI Entry Points:
  neurobrix run --model X --hardware Y --prompt "..."     (pip installed)
  PYTHONPATH=src python -m neurobrix run ...              (dev mode)

Cache Layout:
  ~/.neurobrix/cache/MODEL_NAME/  (extracted .nbx for runtime)
  ~/.neurobrix/store/             (downloaded .nbx files)
```

### Les 7 Pilliers NeuroBrix (Vision vs Reality)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  1. UNIVERSAL FORMAT (.nbx) ✅                                             │
│     ─────────────────────                                                   │
│     • Graph atomique TensorDAG (graph.json avec ~80 ATen ops)             │
│     • Weights en safetensors shardés                                       │
│     • Execution recipe (runtime/execution.json, variables.json)            │
│     • Config complète (manifest.json, defaults.json, topology.json)        │
│                                                                             │
│  2. HARDWARE AGNOSTIC ⚠️                                                    │
│     ─────────────────────                                                   │
│     • NVIDIA CUDA only (AMD/Metal future work)                             │
│     • PRISM selects optimal strategy per detected hardware                 │
│     • Zero rebuild pour changer de GPU NVIDIA                              │
│     • [ARCHIVED] JIT compilation to native kernels                         │
│                                                                             │
│  3. INTELLIGENT PLACEMENT (PRISM) ✅                                       │
│     ─────────────────────────────                                           │
│     • Topology + hardware profile → strategy scoring                       │
│     • Heterogeneous GPU support (16GB + 32GB + 64GB mix)                  │
│     • KV cache estimation from defaults.json                               │
│     • Fallback loop if best strategy doesn't fit                           │
│                                                                             │
│  4. MEMORY VIRTUALIZATION 🔄                                                │
│     ────────────────────────                                                │
│     • [IN PROGRESS] Paging CPU↔GPU                                         │
│     • [ACHIEVED] Lifecycle classification (persistent vs transient)        │
│     • [ACHIEVED] KV cache sizing from max_tokens not max_position_embeddings│
│     • [FUTURE] Prefetch intelligent                                        │
│                                                                             │
│  5. TRAINING + INFERENCE UNIFIED 🔄                                        │
│     ──────────────────────────────                                          │
│     • [ACHIEVED] Inference at production quality                           │
│     • [IN PROGRESS] Training/fine-tuning support                           │
│     • [ACHIEVED] Weights in safetensors (trainable format)                 │
│     • Zero conversion pour inference (runtime lit .nbx directement)        │
│                                                                             │
│  6. TRULY UNIVERSAL MODELS ✅                                              │
│     ─────────────────────────                                               │
│     • Image (PixArt, Sana, Janus VQ), LLM (DeepSeek, Llama, Mistral)      │
│     • Video (CogVideoX), Audio (Whisper)                                   │
│     • Recipe-driven flow (execution.json détermine le type)                │
│     • Zero model hardcoding (component detector + recipe orchestrator)     │
│                                                                             │
│  7. ZERO DEPENDENCIES ❌ [ARCHIVED]                                        │
│     ───────────────────                                                     │
│     • [REALITY] Requires Python + PyTorch (pip install neurobrix)          │
│     • [REALITY] Uses PyTorch ATen for compute (or Triton for R&D)          │
│     • [REALITY] DtypeEngine implements PyTorch AMP rules                   │
│     • [ARCHIVED] Standalone binary vision (not pursued)                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Legend: ✅ Achieved | 🔄 In Progress | ⚠️ Partial | ❌ Archived
```

### Comparison Finale (Reality Check - February 2026)

```
┌──────────────────┬────────┬───────┬─────────┬───────┬──────────────────────┐
│                  │PyTorch │ ONNX  │TensorRT │ vLLM  │   NEUROBRIX v0.1     │
├──────────────────┼────────┼───────┼─────────┼───────┼──────────────────────┤
│ Multi-hardware   │   ⚠️   │  ✅   │   ❌    │  ⚠️   │  ⚠️ NVIDIA only      │
│ Performance      │   ⚠️   │  ⚠️   │   ✅    │  ✅   │  ⚠️ PyTorch ATen base│
│ Dynamic shapes   │   ✅   │  ❌   │   ❌    │  ⚠️   │  ✅ Recipe-driven    │
│ Training         │   ✅   │  ❌   │   ❌    │  ❌   │  🔄 In progress      │
│ Fine-tuning      │   ✅   │  ❌   │   ❌    │  ❌   │  🔄 In progress      │
│ Multi-GPU auto   │   ❌   │  ❌   │   ❌    │  ⚠️   │  ✅ PRISM solver     │
│ Hétérogène GPU   │   ❌   │  ❌   │   ❌    │  ❌   │  ✅ PRISM (16+32GB)  │
│ Memory paging    │   ❌   │  ❌   │   ❌    │  ✅   │  🔄 In progress      │
│ Universal models │   ⚠️   │  ⚠️   │   ❌    │  ❌   │  ✅ Zero hardcode    │
│ Standalone       │   ❌   │  ✅   │   ✅    │  ❌   │  ❌ Requires PyTorch │
│ Open source      │   ✅   │  ✅   │   ❌    │  ✅   │  ✅ 100% MIT         │
│ Easy deployment  │   ❌   │  ⚠️   │   ⚠️    │  ⚠️   │  ✅ pip install     │
└──────────────────┴────────┴───────┴─────────┴───────┴──────────────────────┘

Legend: ✅ Full support | ⚠️ Partial | 🔄 In development | ❌ Not supported

NeuroBrix Unique Strengths (vs all competitors):
  • Heterogeneous GPU support (different VRAM sizes)
  • Zero model hardcoding (universal component detector)
  • Recipe-driven execution (execution.json orchestrates flow)
  • Intelligent strategy selection (PRISM solver with fallback)
  • KV cache data-driven sizing (from defaults.json, not hardcoded)
  • Registry system (neurobrix.es with import/list/remove)
```

---

## PARTIE 5 : IMPLÉMENTATION TECHNIQUE (February 2026)

### Le Runtime NeuroBrix - Stack Technique ACTUEL

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  COUCHE 1: FORMAT .NBX (Implemented)                                        │
│  ────────────────────────────────────                                       │
│                                                                             │
│  model.nbx (ZIP, transport format — extracted to ~/.neurobrix/cache/)      │
│  ├── manifest.json           # Metadata (family, generation_type, modules) │
│  ├── topology.json           # Component graph + execution bindings        │
│  ├── runtime/                                                               │
│  │   ├── defaults.json       # User-tunable defaults (steps, dtype, etc)   │
│  │   ├── variables.json      # Variable contracts with resolvers           │
│  │   └── execution.json      # Loop definitions (iterative_process)        │
│  ├── components/                                                            │
│  │   ├── transformer/                                                       │
│  │   │   ├── graph.json      # TensorDAG (~80 ATen ops, not .nbg)         │
│  │   │   ├── runtime.json    # Component attributes                        │
│  │   │   └── weights/                                                       │
│  │   │       ├── shard_0000.safetensors                                    │
│  │   │       └── shard_0001.safetensors                                    │
│  │   ├── vae/                                                               │
│  │   └── text_encoder/                                                      │
│  └── modules/                                                               │
│      ├── scheduler/          # Scheduler state/config                       │
│      └── tokenizer/          # Tokenizer config (refs HF)                   │
│                                                                             │
│  GRAPH.JSON = TensorDAG (not proprietary .nbg format)                       │
│  - ATen ops (aten::mm, aten::scaled_dot_product_attention, etc.)           │
│  - Symbolic shapes tracked during trace (trace/symbolic/)                  │
│  - op_uid, op_type, input_uids, attributes per node                        │
│                                                                             │
│  RUNTIME READS FROM: ~/.neurobrix/cache/MODEL_NAME/ (NOT .nbx directly)    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  COUCHE 2: ATOMIC OPS (~50 ops couvrent tout)                              │
│  ────────────────────────────────────────────                               │
│                                                                             │
│  TENSOR OPS:          NEURAL OPS:           CONTROL:                       │
│  ───────────          ───────────           ────────                        │
│  • MatMul             • Conv2D              • Reshape                       │
│  • Add                • ConvTranspose2D     • Transpose                     │
│  • Mul                • BatchNorm           • Concat                        │
│  • Div                • LayerNorm           • Split                         │
│  • Sub                • GroupNorm           • Gather                        │
│  • Pow                • RMSNorm             • Scatter                       │
│  • Sqrt               • Attention           • Slice                         │
│  • Exp                • Linear              • Pad                           │
│  • Log                • Embedding           • Tile                          │
│                       • Softmax             • Where                         │
│  ACTIVATIONS:         • Dropout                                            │
│  ────────────                                                               │
│  • ReLU               SPECIAL:                                              │
│  • GELU               ────────                                              │
│  • SiLU               • RotaryEmbed                                        │
│  • Sigmoid            • Upsample                                           │
│  • Tanh               • Downsample                                         │
│  • Softplus           • Interpolate                                        │
│                                                                             │
│  POURQUOI ~50 SUFFIT:                                                       │
│  - Tout réseau = combinaison de ces primitives                             │
│  - Attention = MatMul + Softmax + MatMul                                   │
│  - Transformer block = Linear + Norm + Attention + Linear                  │
│  - Même FlashAttention = une seule op "Attention" côté graph               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  COUCHE 3: EXECUTION LAYER (Implemented)                                    │
│  ───────────────────────────────────────                                    │
│                                                                             │
│  Graph JSON (ATen ops)                                                      │
│      │                                                                      │
│      ▼                                                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    EXECUTION MODES                                   │   │
│  │                                                                      │   │
│  │  A) COMPILED (DEFAULT) - CompiledSequenceV2                         │   │
│  │     • Zero-overhead arena execution (TensorArena + integer slots)   │   │
│  │     • DtypeEngine with PyTorch AMP autocast rules                   │   │
│  │     • Closure-based resolvers (no dict lookups)                     │   │
│  │     • Dead tensor analysis (liveness tracking)                      │   │
│  │     • Used by: neurobrix run (default mode)                         │   │
│  │                                                                      │   │
│  │  B) NATIVE (--seq_aten) - NativeATenDispatcher                      │   │
│  │     • Dict-based execution (legacy, fallback mode)                  │   │
│  │     • Ad-hoc stability fixes per op                                 │   │
│  │     • String-based dispatch + dict lookups                          │   │
│  │     • Used for: debugging graph execution issues                    │   │
│  │                                                                      │   │
│  │  C) TRITON (--triton) - R&D Mode                                    │   │
│  │     • Custom Triton kernels via KernelAdapter                       │   │
│  │     • Classification.py: TRITON ops vs METADATA ops                 │   │
│  │     • PURE TRITON rule: kernels/ops/ must be 100% Triton            │   │
│  │     • Used for: kernel performance research                         │   │
│  │                                                                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│      │                                                                      │
│      ├──────────────┬──────────────                                         │
│      ▼              ▼                                                       │
│  ┌────────────┐    ┌────────────┐                                           │
│  │ PyTorch    │    │  Triton    │                                           │
│  │ ATen       │    │  (R&D)     │                                           │
│  │ (CUDA)     │    │  NVIDIA    │                                           │
│  └────────────┘    └────────────┘                                           │
│                                                                             │
│  [ARCHIVED] Native Compilation Options (not pursued):                      │
│                                                                             │
│  ❌ Custom CUDA/HIP/Metal kernels                                          │
│  ❌ MLIR / LLVM codegen                                                    │
│  ❌ Bend/HVML                                                              │
│  ❌ Standalone binary                                                      │
│                                                                             │
│  CURRENT APPROACH: Pure Python + Triton (leverages PyTorch ecosystem)      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  COUCHE 4: PRISM (Hardware Supervisor) - IMPLEMENTED                        │
│  ──────────────────────────────────────────────────                         │
│                                                                             │
│  INPUT:                                                                     │
│  ┌─────────────────┐    ┌─────────────────┐                                │
│  │  NBXContainer   │    │  Hardware Profile│                               │
│  │  (topology.json)│    │  (v100-32g.yml)  │                               │
│  └────────┬────────┘    └────────┬─────────┘                               │
│           │                      │                                          │
│           └──────────┬───────────┘                                          │
│                      ▼                                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      PRISM SOLVER                                    │   │
│  │                  (core/prism/solver.py)                              │   │
│  │                                                                      │   │
│  │  1. MEMORY ESTIMATION ✅                                            │   │
│  │     - Per-component: weights + activations from profile.json        │   │
│  │     - KV cache: from defaults.json (max_tokens + prompt_margin)     │   │
│  │     - Lifecycle classification (persistent vs transient)            │   │
│  │                                                                      │   │
│  │  2. STRATEGY SCORING ✅                                             │   │
│  │     - Candidates: single_gpu, zero3, pipeline, tensor_parallel      │   │
│  │     - Score based on: perf penalty, topology complexity             │   │
│  │     - Validate KV cache fits (fallback loop if not)                 │   │
│  │     - Heterogeneous support: weighted sharding by VRAM              │   │
│  │                                                                      │   │
│  │  3. DTYPE RESOLUTION ✅                                             │   │
│  │     - Per hardware profile: supports_dtypes: [float32, float16]     │   │
│  │     - DtypeEngine enforces AMP rules + bf16→fp16 with range verification via _scan_bf16_fp16_safety()│
│  │     - FlowContext passes dtype to all components                    │   │
│  │                                                                      │   │
│  │  4. MEMORY SCHEDULING 🔄                                            │   │
│  │     - [IN PROGRESS] CPU↔GPU paging                                  │   │
│  │     - [IN PROGRESS] Prefetch based on execution order               │   │
│  │     - [FUTURE] Overlap compute + transfer                           │   │
│  │                                                                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                      │                                                      │
│                      ▼                                                      │
│  OUTPUT:                                                                    │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  PrismPlan (dataclass)                                               │   │
│  │                                                                      │   │
│  │  allocations: Dict[str, ComponentAllocation]                         │   │
│  │    {                                                                 │   │
│  │      "transformer": {                                                │   │
│  │        "device_id": 0,                                              │   │
│  │        "dtype": torch.float16,                                      │   │
│  │        "memory_bytes": 13GB                                         │   │
│  │      },                                                              │   │
│  │      "vae": {                                                        │   │
│  │        "device_id": 1,  // Multi-GPU placement                     │   │
│  │        "dtype": torch.float16,                                      │   │
│  │        "memory_bytes": 800MB                                        │   │
│  │      }                                                               │   │
│  │    }                                                                 │   │
│  │  strategy_id: "single_gpu_lifecycle"                                 │   │
│  │  metadata: {"total_vram_gb": 31.5, "largest_component": "transformer"}│
│  │                                                                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## PARTIE 6 : [ARCHIVED] LANGAGE D'IMPLÉMENTATION

**DECISION (February 2026)**: NeuroBrix uses **pure Python + Triton** instead of compiled runtimes.

**Rationale**:
- PyTorch ecosystem maturity (ATen ops, autocast rules, CUDA dispatch)
- Triton provides performance without C++/Rust complexity
- Python enables rapid iteration on graph execution logic
- CompiledSequenceV2 achieves near-native performance in pure Python
- DtypeEngine implements PyTorch AMP rules (proven numerical stability)

**Trade-offs accepted**:
- ❌ Standalone binary (requires Python + PyTorch environment)
- ❌ Multi-platform support (NVIDIA CUDA only, AMD/Metal future work)
- ✅ Development velocity (Python is faster to iterate)
- ✅ Ecosystem leverage (PyTorch operators, safetensors, HF integrations)

### [HISTORICAL CONTEXT] Options Considered

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  OPTION A: RUST [REJECTED]                                                  │
│  ──────────────                                                             │
│  Reason: Ecosystem immaturity, bindings fragility, slower development       │
│  Projects: Candle (HuggingFace), Burn                                       │
│                                                                             │
│  OPTION B: C++ [REJECTED]                                                   │
│  ─────────────                                                              │
│  Reason: Memory bugs, CMake complexity, AMP rules harder to replicate       │
│  Projects: llama.cpp, ggml, TensorRT                                        │
│                                                                             │
│  OPTION C: ZIG [REJECTED]                                                   │
│  ─────────────                                                              │
│  Reason: Very young ecosystem, minimal ML libraries                         │
│                                                                             │
│  OPTION D: MOJO [REJECTED]                                                  │
│  ────────────────                                                           │
│  Reason: Not open source (2024), vendor lock-in (Modular Inc)               │
│                                                                             │
│  OPTION E: PYTHON + TRITON [CHOSEN] ✅                                     │
│  ─────────────────────────────────                                          │
│  Advantages:                                                                │
│  + Leverage PyTorch ecosystem (ATen ops, AMP autocast, CUDA dispatch)       │
│  + Triton for custom kernels (Python-based, GPU performance)                │
│  + Rapid iteration on graph execution (CompiledSequenceV2)                  │
│  + DtypeEngine replicates PyTorch numerical stability rules                 │
│  + pip install neurobrix (standard Python packaging)                        │
│                                                                             │
│  Disadvantages:                                                             │
│  - Requires Python + PyTorch runtime (not standalone)                       │
│  - NVIDIA CUDA only (no AMD/Metal/CPU yet)                                  │
│  - Python overhead (mitigated by CompiledSequenceV2 arena execution)        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

CURRENT ARCHITECTURE (February 2026):
- Package: src/neurobrix/ (pip installable)
- Runtime: core/runtime/ (Python + PyTorch ATen)
- Kernels: kernels/ops/ (Triton for R&D via --triton flag)
- Execution: CompiledSequenceV2 (zero-overhead arena, integer slots)
- Numerical stability: DtypeEngine (PyTorch AMP rules)
- Entry point: neurobrix run (CLI command)
```

---

## PARTIE 7 : ROADMAP - Progress Report (February 2026)

```
PHASE 1: FOUNDATION ✅ COMPLETED
──────────────────────────────
✅ Format .nbx v0.1 (manifest.json, topology.json, graph.json, weights)
✅ TensorDAG with ~80 ATen ops (not custom ops - leverage PyTorch)
✅ NBXContainer parser (core/nbx/)
✅ RuntimeExecutor with recipe orchestration (core/runtime/executor.py)
✅ Tests on: PixArt, Sana, Janus VQ, DeepSeek-MoE, Llama models

PHASE 2: EXECUTION LAYER ✅ COMPLETED
────────────────────────────────────
✅ PyTorch ATen integration (NativeATenDispatcher, CompiledSequenceV2)
✅ DtypeEngine with AMP autocast rules (numerical stability)
✅ CompiledSequenceV2: zero-overhead arena execution (integer slots)
✅ GraphExecutor with inference_mode (memory leak fixed)
✅ Tests on: image diffusion (PixArt, Sana), LLMs (DeepSeek, Llama)

PHASE 3: PRISM ✅ COMPLETED
─────────────────────────
✅ Hardware detection (NVIDIA GPUs, VRAM, NVLink topology)
✅ Memory estimation (per-component weights + activations + KV cache)
✅ Strategy scoring (single_gpu, zero3, pipeline, tensor_parallel)
✅ Multi-GPU heterogeneous (16GB + 32GB + 64GB mix, weighted sharding)
✅ Tests on: Janus-Pro-7B (32GB V100), DeepSeek-MoE-16B (multi-GPU)

PHASE 4: ADVANCED 🔄 IN PROGRESS
──────────────────────────────
✅ Heterogeneous multi-GPU (PRISM lifecycle classification)
🔄 Memory paging CPU↔GPU (in development)
❌ AMD ROCm support (not started - NVIDIA only)
✅ Precision management (DtypeEngine with bf16→fp32 safety)
✅ Tests on: Large models (Janus 7B, DeepSeek-MoE 16B, Sana 1600M)

PHASE 5: PRODUCTION 🔄 IN PROGRESS
──────────────────────────────────
❌ Apple Metal support (future work)
🔄 Triton kernel coverage (R&D mode via --triton flag)
🔄 Training/Fine-tuning support (in development)
✅ Registry system (neurobrix.es with import/list/remove)
✅ Documentation (CLAUDE.md, BIBLE_NEUROBRIX.md, lessons/)
🔄 Benchmarks vs diffusers (image diffusion competitive)

CURRENT FOCUS (Q1 2026):
────────────────────────
• Memory paging implementation (CPU↔GPU offload)
• Training/fine-tuning support (gradient computation + optimizer integration)
• Triton kernel optimization (reduce divergence from PyTorch)
• Multi-modal model support (Janus text+image unified inference)

FUTURE WORK:
────────────
• AMD ROCm backend (Triton supports ROCm, needs hardware profile work)
• Apple Metal backend (via MPS or custom Metal shaders)
• Kernel fusion optimization (fuse matmul+bias+gelu chains)
• Quantization support (INT8, INT4 via custom ops or vLLM integration)
```

---

## CONCLUSION : VISION VS REALITY (February 2026)

### What We Built (v0.1)

NeuroBrix is a **pure Python + Triton runtime system** that achieves:

1. **Universal Model Support** ✅
   - Zero model hardcoding (recipe-driven execution from execution.json)
   - Supports: image diffusion (PixArt, Sana, Janus), LLMs (DeepSeek, Llama), video (CogVideoX)
   - Component detector automatically identifies architecture patterns

2. **Intelligent Hardware Placement** ✅
   - PRISM solver for heterogeneous multi-GPU (16GB + 32GB + 64GB mix)
   - Strategy scoring with KV cache awareness and fallback loop
   - Lifecycle classification (persistent vs transient components)

3. **Numerical Stability** ✅
   - DtypeEngine implements PyTorch AMP autocast rules
   - Safe dtype conversions (bf16→fp16 allowed with range scan, bf16→fp32 always safe)
   - Fixed fp16 matmul overflow issues (RMSNorm, RoPE, attention)

4. **Zero-Overhead Execution** ✅
   - CompiledSequenceV2 arena execution (integer slots, closure resolvers)
   - Dead tensor analysis with liveness tracking
   - Eliminated Python dict lookup overhead (~75% GPU util → 95%)

5. **Registry System** ✅
   - neurobrix.es for model distribution (PostgreSQL + MinIO)
   - CLI commands: neurobrix import/list/remove
   - Dual cache (~/.neurobrix/store/ for .nbx, ~/.neurobrix/cache/ for runtime)

### What We Didn't Build (Archived Vision)

1. **Standalone Binary** ❌
   - Requires Python + PyTorch environment (pip install neurobrix)
   - Trade-off: ecosystem leverage > deployment simplicity

2. **Multi-Platform Kernels** ❌
   - NVIDIA CUDA only (no AMD ROCm, no Apple Metal yet)
   - Trade-off: focus on core functionality first

3. **Compiled Native Runtime** ❌
   - No C++ / Rust / Zig / Mojo runtime
   - Trade-off: Python development velocity > native performance

4. **ONNX Compatibility** ❌
   - NBX format is the single source of truth
   - Trade-off: own format = full control, no export bugs

### Why This Is Still Revolutionary

Despite using Python instead of compiled runtimes, NeuroBrix solves problems **nobody else solves**:

- **Heterogeneous GPU placement**: Mix 16GB + 32GB GPUs in the same cluster
- **Zero model hardcoding**: Works with ANY model via recipe-driven execution
- **KV cache intelligence**: Data-driven sizing from defaults.json, not hardcoded
- **Strategy fallback**: If best strategy doesn't fit, automatically try next candidate
- **Numerical stability by design**: DtypeEngine enforces PyTorch AMP rules universally

The vision of "ANY MODEL ON ANY HARDWARE" is 80% achieved with pure Python.
The remaining 20% (AMD/Metal, standalone binary, memory paging) is future work.

**The core insight**: You don't need C++/Rust to build a universal ML runtime.
You need **good abstractions** (NBX format, PRISM solver, recipe orchestration).

---

**Document Revision History**:
- Original: Aspirational vision document (compiled runtimes, multi-platform)
- February 2026: Reality check update (Python + Triton, NVIDIA CUDA, v0.1 achievements)
```
