From cc5b0337629089ddc7cf54c819cdde4ef510f611 Mon Sep 17 00:00:00 2001
From: Richard Loyer <richard.loyer@c42.lu>
Date: Sun, 24 May 2026 12:34:14 +0200
Subject: [PATCH] Engine cadrage: CLAUDE.md analyse R&D, verdict
 NPU-prefill/CPU-decode

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .gitignore |  5 +++++
 CLAUDE.md  | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 CLAUDE.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..9597919
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+build/
+models/
+*.gguf
+*.pte
+*.log
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..692fe55
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,34 @@
+# Kazeia-Engine
+
+Moteur d'inférence LLM Snapdragon 8 Elite **sans conversion `.pte`** : charger
+GGUF directement, NPU pour le prefill, CPU pour le decode. Mono-tablette,
+local-first, sans root. Bench-driven : aucune décision sans chiffre reproductible.
+
+## Cibles & gabarits
+- **Qwen3-4B** (dense, attn pleine) — tourne déjà sous ExecuTorch : decode 14-21 tok/s, TTFT 190 ms. **Réf à approcher.**
+- **Qwen3.5-4B** (hybride DDDA×8 : 24 DeltaNet + 8 FullAttn, GDN, conv1d, SSM, head_dim 256, vocab 248k, tied embeds) — ExecuTorch ne sait pas l'exporter proprement. C'est lui qu'il faut bien faire tourner. Empreinte mémoire mini = priorité.
+
+## Verdict R&D (issu de briques + bench, ne PAS refaire l'erreur)
+Sur SM8750, Qwen3.5-4B-Q4_0, **decode M=1 = memory-bandwidth bound**, pas compute. Mesures :
+| Voie | Decode | Prefill | Statut |
+|---|---:|---:|---|
+| llama.cpp CPU NEON (`-dev none`) | **16.5 tok/s** | 75 | stable, ~67% BW |
+| llama.cpp CPU+Hexagon auto | 16.5 | **159** | stable — prefill HMX |
+| llama.cpp Hexagon-only | 3.6 | — | DSP seul = perdant decode |
+| briques DSP-first custom | 5.3 | 26 | crash ~12min, abandonné |
+→ **Angle = NPU prefill / CPU decode, exactement ce que fait llama.cpp+chraac.** Tout DSP-first sur decode plafonne (~5 tok/s) ; gros vocab + tied embeds bloque spec-dec. CPU NEON bat le HVX 3.4× sur Q6_K M=1. Bonus DDDA : 75% des couches O(1) → decode stable en long contexte.
+
+## Socle
+- `/opt/Kazeia/chraac-llama` (branch dev-refactoring 897501a) — llama.cpp + backend Hexagon = point de départ. Decode CPU + prefill HMX.
+- ExecuTorch GitHub — référence/qnn_llama_runner, à dépasser pas dépendre.
+- `briques-archive/` + mémoires `project_briques_qwen35*` — kernels HVX (Q6_K valign, q4x4x2 repack), pièges V79 0x2e, oracle ggml. Lire avant kernels.
+- HW: i8mm+bf16+dotprod, **PAS de SVE** ; LPDDR5x ~77 GB/s, CPU eff ~25. Build `-O3 -march=armv8.6-a+dotprod+fp16+i8mm+bf16`, ggml=chraac (jamais whisper.cpp/upstream → RTF 1.5).
+
+## Plan d'attaque mémoire-mini
+1. Bench chraac CPU+HTP sur Qwen3-4B (match ExecuTorch?) + Qwen3.5-4B Q4_0 pure.
+2. Mémoire mini : poids Q4_0/embeds Q6_K, prefill HTP / decode CPU, pas de double-copie poids ; viser <4 GB pour 4B.
+3. Refacto Phase 8 si gap : repack Q4_0 8x8 NEON decode + HMX prefill.
+
+## Limite assistant
+R&D LLM frontière (kernels HVX bit-exacts, quant) = aide partielle, je le dis au cas par cas.
+GGUF/llama.cpp archivés vers `/opt/Kazeia/to_delete`. Git local: commits réguliers. — Richard & Damien.