mlsys-lab 0.1.0__tar.gz

mlsys_lab-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+.DS_Store
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Learner state. Every task ships a starter (starter.py / starter.cpp /
+# starter.cu); the editor seeds solve.* from it on first open. solve.* is the
+# learner's own attempt and is never part of the bank.
+tasks/*/solve.py
+tasks/*/solve.cpp
+tasks/*/solve.cu
+
+# local build artefacts
+a.out
+*.o
+.preview/
+
+# generation queues, archives and one-off scripts stay out of the published repo
+.internal/
+*.vsix

mlsys_lab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksandr Savkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlsys_lab-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: mlsys-lab
+Version: 0.1.0
+Summary: Auto-graded exercises in low-level ML systems: real C++, real CUDA-C on a software GPU, deterministic metrics
+Project-URL: Homepage, https://github.com/mikamika06/mlsys-lab
+Project-URL: Issues, https://github.com/mikamika06/mlsys-lab/issues
+Author: Oleksandr Savkov
+License: MIT License
+        
+        Copyright (c) 2026 Oleksandr Savkov
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cpp,cuda,exercises,gpu,llm-inference,performance,quantization,systems-programming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Description-Content-Type: text/markdown
+
+# mlsys-lab
+
+Auto-graded exercises in low-level ML systems. You write **real C++**, **real
+CUDA-C** and Python; a local grader runs it and checks a **measured number**
+against declarative gates.
+
+No cloud, no account, no GPU required. Every metric is deterministic, so the same
+submission scores identically on any machine.
+
+```
+$ mlsys grade gpu-1-padding-to-remove-transpose-bank-conflicts
+
+  max_abs_err        0.0        <= 1e-12   PASS
+  smem_wave_ratio    16.5       <= 1.05    FAIL
+                     ^ your tile is 32 wide, so every column read hits one bank
+```
+
+## Why the numbers are trustworthy
+
+Wall-clock timing is never a gate. Instead the engine models the hardware and
+counts what actually happened:
+
+| you write | it runs on | it measures |
+|---|---|---|
+| `solve.cu` | a software GPU: 32-lane warps, 128-byte transactions, 32 shared-memory banks, barriers, warp shuffles | coalescing transactions, bank-conflict waves, warp divergence, cycles |
+| `solve.cpp` | the local `clang++ -O2 -std=c++20`, plus a modelled set-associative cache | cache misses, lines touched, and the program's own output |
+| `solve.py` | the interpreter, with an instrumented probe | allocations, copies, numerical error against a computed oracle |
+
+The reference answer is always **computed by the grader**, never hard-coded — so
+a task cannot be passed by guessing the expected output.
+
+## Install
+
+```bash
+pip install mlsys-lab           # the engine and all 2052 tasks
+
+mlsys list                      # browse the bank
+mlsys grade <task-id> --file my_solution.py
+```
+
+The bank ships inside the package, so there is nothing to clone and nothing to
+download on first run. Your solutions live wherever you put them — `--file` takes
+a path, and the bank is never written to.
+
+C++ tasks need a C++20 compiler (`clang++` or `g++`); everything else is Python
+plus NumPy. CUDA tasks need **no** NVIDIA hardware — the `.cu` is executed by the
+simulator in `src/mlsys/sim/`.
+
+### VS Code
+
+Install **mlsys-lab** from the Marketplace, then run **mlsys-lab: Open Workspace**.
+If the package is not installed yet, the extension offers to do it. Solutions go to
+`~/mlsys-lab/<task-id>/` (configurable via `mlsys.workDir`).
+
+### Contributing to the bank
+
+```bash
+git clone https://github.com/mikamika06/mlsys-lab
+cd mlsys-lab && pip install -e .
+```
+
+A checkout takes precedence over the installed copy, so the tasks you are editing
+are the ones that get graded. `$MLSYS_TASKS` overrides both.
+
+## What is in the bank
+
+Three native tracks plus the systems material:
+
+- **Deep Python** — the data model, descriptors, the GIL, memory layout
+- **Deep C++** — ownership, moves, ABI, undefined behaviour you can observe
+- **CPU performance** — cache blocking, layout (AoS/SoA), branches, SIMD
+- **GPU / CUDA** — coalescing, bank conflicts, divergence, barriers, shuffles
+- **Numerics & tensors** — stability, shapes and strides, low-precision formats
+- **LLM internals** — attention, RoPE, GQA, the KV cache, sampling
+- **LLM systems** — paged KV, continuous batching, parallelism, speculative decoding
+- **Applied** — quantization, attention/KV, export & compilation, serving,
+  memory & offload, sparsity & distillation
+
+## Concepts, explained with a number
+
+[`docs/concepts/`](docs/concepts/) — one page per concept, each with a measurement produced by
+the simulator in this repo and the command that regenerates it, then the graded exercise.
+Start with [memory coalescing](docs/concepts/memory-coalescing.md) (128-byte transactions
+against read stride, 2 → 33) or [false sharing](docs/concepts/false-sharing.md) (coherence
+invalidations against padding, 7,999 → 0).
+
+## What else exists
+
+[`docs/LANDSCAPE.md`](docs/LANDSCAPE.md) surveys the other resources aimed at each of
+these areas — 141 of them, every link checked — and marks whether each one actually
+grades your work or only shows you code. It says where this bank is *not* your best
+option, which is most of the point of having the page.
+
+The short version: GPU/CUDA, algorithms-from-scratch and LLM internals are well served
+already (GPU-Puzzles, LeetGPU, Tensara, deep-ml, CS336, LeetCUDA). Six of the fourteen
+areas have **no** auto-graded resource anywhere, and four — applied quantization,
+compilation & export, memory & offload, and sparsity/pruning/distillation — have nothing
+to practise against at all: papers, production libraries and documentation, but no
+exercise that tells you that you got it wrong.
+
+## Writing a task
+
+A task is a directory under `tasks/`. See [`docs/TASK_FORMAT.md`](docs/TASK_FORMAT.md).
+
+```
+tasks/<id>/
+  meta.json     id, title, difficulty, gates       ("native": "cpp" | "cuda")
+  task.md       ## Context / ## Task / ## Example / ## What the gate checks
+  check.py      grade(sol, fx) -> {metric: value}  — computes its own reference
+  starter.py    the empty contract the learner starts from
+  solution_ref.py
+```
+
+```bash
+tools/verify_task.sh   <id>    # python task:  reference passes, starter fails
+tools/verify_native.sh <id>    # C++ / CUDA task
+```
+
+Both print `TASK_OK` only if the reference passes the gates **and** the shipped
+starter fails them — a task that anything can pass is not a task.
+
+## Layout
+
+```
+src/mlsys/        the engine
+  sim/            software GPU, CUDA-C front end, cache model, ABI model
+  runners/        cpp.py (clang++), cuda.py (software GPU)
+  scorers.py      the metrics tasks gate on
+tasks/            the bank
+editor/           VS Code extension
+tools/            verify, queue helpers, browser preview
+docs/             curriculum and research
+```
+
+## License
+
+MIT

mlsys_lab-0.1.0/README.md

@@ -0,0 +1,137 @@
+# mlsys-lab
+
+Auto-graded exercises in low-level ML systems. You write **real C++**, **real
+CUDA-C** and Python; a local grader runs it and checks a **measured number**
+against declarative gates.
+
+No cloud, no account, no GPU required. Every metric is deterministic, so the same
+submission scores identically on any machine.
+
+```
+$ mlsys grade gpu-1-padding-to-remove-transpose-bank-conflicts
+
+  max_abs_err        0.0        <= 1e-12   PASS
+  smem_wave_ratio    16.5       <= 1.05    FAIL
+                     ^ your tile is 32 wide, so every column read hits one bank
+```
+
+## Why the numbers are trustworthy
+
+Wall-clock timing is never a gate. Instead the engine models the hardware and
+counts what actually happened:
+
+| you write | it runs on | it measures |
+|---|---|---|
+| `solve.cu` | a software GPU: 32-lane warps, 128-byte transactions, 32 shared-memory banks, barriers, warp shuffles | coalescing transactions, bank-conflict waves, warp divergence, cycles |
+| `solve.cpp` | the local `clang++ -O2 -std=c++20`, plus a modelled set-associative cache | cache misses, lines touched, and the program's own output |
+| `solve.py` | the interpreter, with an instrumented probe | allocations, copies, numerical error against a computed oracle |
+
+The reference answer is always **computed by the grader**, never hard-coded — so
+a task cannot be passed by guessing the expected output.
+
+## Install
+
+```bash
+pip install mlsys-lab           # the engine and all 2052 tasks
+
+mlsys list                      # browse the bank
+mlsys grade <task-id> --file my_solution.py
+```
+
+The bank ships inside the package, so there is nothing to clone and nothing to
+download on first run. Your solutions live wherever you put them — `--file` takes
+a path, and the bank is never written to.
+
+C++ tasks need a C++20 compiler (`clang++` or `g++`); everything else is Python
+plus NumPy. CUDA tasks need **no** NVIDIA hardware — the `.cu` is executed by the
+simulator in `src/mlsys/sim/`.
+
+### VS Code
+
+Install **mlsys-lab** from the Marketplace, then run **mlsys-lab: Open Workspace**.
+If the package is not installed yet, the extension offers to do it. Solutions go to
+`~/mlsys-lab/<task-id>/` (configurable via `mlsys.workDir`).
+
+### Contributing to the bank
+
+```bash
+git clone https://github.com/mikamika06/mlsys-lab
+cd mlsys-lab && pip install -e .
+```
+
+A checkout takes precedence over the installed copy, so the tasks you are editing
+are the ones that get graded. `$MLSYS_TASKS` overrides both.
+
+## What is in the bank
+
+Three native tracks plus the systems material:
+
+- **Deep Python** — the data model, descriptors, the GIL, memory layout
+- **Deep C++** — ownership, moves, ABI, undefined behaviour you can observe
+- **CPU performance** — cache blocking, layout (AoS/SoA), branches, SIMD
+- **GPU / CUDA** — coalescing, bank conflicts, divergence, barriers, shuffles
+- **Numerics & tensors** — stability, shapes and strides, low-precision formats
+- **LLM internals** — attention, RoPE, GQA, the KV cache, sampling
+- **LLM systems** — paged KV, continuous batching, parallelism, speculative decoding
+- **Applied** — quantization, attention/KV, export & compilation, serving,
+  memory & offload, sparsity & distillation
+
+## Concepts, explained with a number
+
+[`docs/concepts/`](docs/concepts/) — one page per concept, each with a measurement produced by
+the simulator in this repo and the command that regenerates it, then the graded exercise.
+Start with [memory coalescing](docs/concepts/memory-coalescing.md) (128-byte transactions
+against read stride, 2 → 33) or [false sharing](docs/concepts/false-sharing.md) (coherence
+invalidations against padding, 7,999 → 0).
+
+## What else exists
+
+[`docs/LANDSCAPE.md`](docs/LANDSCAPE.md) surveys the other resources aimed at each of
+these areas — 141 of them, every link checked — and marks whether each one actually
+grades your work or only shows you code. It says where this bank is *not* your best
+option, which is most of the point of having the page.
+
+The short version: GPU/CUDA, algorithms-from-scratch and LLM internals are well served
+already (GPU-Puzzles, LeetGPU, Tensara, deep-ml, CS336, LeetCUDA). Six of the fourteen
+areas have **no** auto-graded resource anywhere, and four — applied quantization,
+compilation & export, memory & offload, and sparsity/pruning/distillation — have nothing
+to practise against at all: papers, production libraries and documentation, but no
+exercise that tells you that you got it wrong.
+
+## Writing a task
+
+A task is a directory under `tasks/`. See [`docs/TASK_FORMAT.md`](docs/TASK_FORMAT.md).
+
+```
+tasks/<id>/
+  meta.json     id, title, difficulty, gates       ("native": "cpp" | "cuda")
+  task.md       ## Context / ## Task / ## Example / ## What the gate checks
+  check.py      grade(sol, fx) -> {metric: value}  — computes its own reference
+  starter.py    the empty contract the learner starts from
+  solution_ref.py
+```
+
+```bash
+tools/verify_task.sh   <id>    # python task:  reference passes, starter fails
+tools/verify_native.sh <id>    # C++ / CUDA task
+```
+
+Both print `TASK_OK` only if the reference passes the gates **and** the shipped
+starter fails them — a task that anything can pass is not a task.
+
+## Layout
+
+```
+src/mlsys/        the engine
+  sim/            software GPU, CUDA-C front end, cache model, ABI model
+  runners/        cpp.py (clang++), cuda.py (software GPU)
+  scorers.py      the metrics tasks gate on
+tasks/            the bank
+editor/           VS Code extension
+tools/            verify, queue helpers, browser preview
+docs/             curriculum and research
+```
+
+## License
+
+MIT

mlsys_lab-0.1.0/docs/CURRICULUM.md

@@ -0,0 +1,166 @@
+# Майстер-навчальний план — платформа глибокої ML-systems майстерності
+### (робоча назва «Arena»; локальний авто-грейдинг для deep Python · deep C++ · тензори · LLM · CPU · GPU)
+
+**Місія (уточнена):** не «квантизація під одну співбесіду», а **глибока майстерність systems/performance-інженерії**: глибокий Python + глибокий C++ + низькорівнева робота з тензорами й LLM на **CPU і GPU**. Задачі **постійно свіжі** (движок оновлення під живе поле). **Mac-first — фаза, не константа:** Mac → Linux/CUDA → Windows. Конкретний кейс LayoutLMv3 і M4 — лише один приклад, не якір.
+
+**Три принципи грейдингу (незмінні):**
+1. **Локально, число як в Advent of Code** — солвер рахує код у себе, платформа перевіряє ЧИСЛО.
+2. **Детермінізм — властивість грейдера, не заліза** — пороги на `byte-exact` / `op-count` / `FLOP` / `KL` / `argmax` / `size-ratio`; швидкість **лише як same-machine ratio** + обов'язковий correctness-gate попереду; ніколи абсолютні мс.
+3. **Fixtures — збережені масиви, не моделі** (`.npy`/`safetensors`, канонічний little-endian, sha256-манифест) → однаковий критерій на будь-якій ОС.
+
+**Обсяг:** ~120 авто-перевірюваних задач у пулі (53 з нових стовпів + ~67 із домену стиснення/LLM/eval — див. `PLAN.md`).
+
+---
+
+## Блок 0 — КАРКАС ПЛАТФОРМИ (grader) ⚙️ будуємо ПЕРШИМ
+Це фундамент: правила детермінізму/портативності, без яких GPU-задачі решти блоків не запустяться на Mac у Фазі 1. Він же — перший навчальний блок про те, «чому CPU≠GPU за однаковим seed».
+
+**Під-теми (від базового):** seeds & `torch.use_deterministic_algorithms` → біти fp32/fp16/bf16, round-to-nearest-even, subnormals (`ml_dtypes`) → неасоціативність суми, reassociation, вплив `OMP_NUM_THREADS`/BLAS → fixtures як масиви (endianness/dtype/sha256) → tolerance-ворота (`rtol`/`atol`/ULP) замість `==` → форсування бекенду (CPU-only, вимк. TF32, `CUBLAS_WORKSPACE_CONFIG`) → абстракція «одна задача — кілька бекендів» (адаптери cpu/metal/mlx/cuda) → Mac-шлях для GPU (`TRITON_INTERPRET=1`, `NUMBA_ENABLE_CUDASIM=1`) → тулчейни (clang/gcc/msvc, CMake, nvcc), ФС/шляхи → CI-матриця та фазовий rollout.
+
+**Приклади задач:**
+- Канонічна byte-exact фікстура `.npy` + sha256 · `byte-exact` · cross-platform · d2
+- fp32→bf16 round-to-nearest-even, що збігається з `ml_dtypes` (повернути к-сть розбіжностей = 0) · d3
+- Детермінована редукція, біт-ідентична при `OMP_NUM_THREADS ∈ {1,2,4,8}` · `uint64-pattern` · d3
+- Підбір мінімального `atol` для fp16-vs-fp32 ворота (повернути ціле `e`) · d3
+- Пастка TF32: показати, що matmul виходить за `rtol=1e-5` при `allow_tf32=True` · cloud-cuda · d3
+- Golden-фікстура end-to-end: генерація на канонічному бекенді + sha256 на 3 ОС · d4
+
+**Ресурси:** PyTorch Reproducibility notes · Goldberg «What Every CS Should Know About FP» · `jax-ml/ml_dtypes` · `huggingface/safetensors` · `numpy.testing.assert_allclose` · reproducible-builds.org.
+
+---
+
+## Блок 1 — Глибокий Python (для ML-систем) 🐍 [Mac-first онбординг]
+**Місія:** Python↔native fluency + вимірювання, на які спираються всі решта блоків. ~90% на чистому CPU — ідеальний старт.
+
+**Під-теми (ordered):** CPython object model (PyObject, refcount, `gc`, interning) → bytecode & `dis`, чому цикли повільні → GIL і модель пам'яті → view vs copy, приховані копії → **numpy internals**: strides/layout → as_strided/views → broadcasting (0-strides) → ufunc & векторизація → профілювання (`cProfile`, `line_profiler`, `memray`, `scalene`, `py-spy`) → C-межа: `ctypes`/`cffi` → `pybind11`/`nanobind` → `Cython` (typed memoryviews) → concurrency (threads/GIL, multiprocessing, `shared_memory`) → packaging нативних wheel (`meson-python`, `uv`).
+
+**Приклади задач:**
+- `broadcast_to` з нуля через `as_strided` (доказ zero-copy: `np.shares_memory==True`) · d2
+- `sliding_window_view` (im2col-праймітив) через strides, byte-exact · d3
+- Векторизуй пайплайн: 0 Python-циклів (op-count) + correctness-gate · d2
+- `pybind11`/`nanobind`: bind C++ ядро, match golden `.npy` + zero-copy · d4
+- Cython: прибери «жовте» (`cython -a` = 0 Python-рядків у циклі) + ratio ≥30× · mac-local · d4
+- Полюй на приховану копію (`memray` alloc-count = очікуване N) · d3
+- GIL-експеримент: класифікувати, коли threads не масштабуються (CPU-bound) · d3
+- `numba`-CUDA-sim reduction-kernel (той самий код → real-CUDA пізніше) · mac-local-sim · d4
+
+**Ресурси:** CPython devguide + «Python behind the scenes» · NumPy Manual (ufuncs/broadcasting/strides) · `pybind11` / **`nanobind`** (дефолт 2026) / Cython docs · `scalene` / `memray` / `py-spy` · `uv` + `meson-python`.
+**Фронтир (авто-свіжість):** free-threaded (no-GIL) CPython 3.14t → гілка «повтори GIL-експеримент, покажи що threads тепер масштабуються».
+
+---
+
+## Блок 2 — Глибокий C++ (kernels & systems) ⚙️
+**Місія:** писати високопродуктивні ML-ядра з нуля; апаратно-незалежні критерії (golden, FLOP-count, arithmetic intensity), швидкість — secondary ratio.
+
+**Під-теми:** модель пам'яті/alignment/layout → кеш-ієрархія, memory-bound vs compute-bound, **roofline** → cache-blocked трансформації (blocked transpose, packing) → SIMD: **ARM NEON** intrinsics (`float32x4_t`, `vfmaq`), редукції, хвости (AVX2/512 — x86-шлях пізніше) → **GEMM з нуля**: наївна петля → register-blocking → L1/L2-тайлінг → packing (GotoBLAS/BLIS micro-kernel) → im2col+conv як GEMM → ggml-стильні квант-ядра (Q8_0/Q4_0 byte-exact) → bindings (`pybind11`/`nanobind`, CMake) → профілювання (Instruments/dtrace на Mac, perf/cachegrind на Linux) → GPU-ядро (Metal/MLX Mac-шлях → CUDA).
+
+**Приклади задач:**
+- Naive GEMM проти golden (`max_abs_err ≤ 1e-4`) · d1
+- Cache-blocked GEMM + перевірка `FLOP == 2·M·N·K` + same-machine ratio · d3
+- SIMD dot-product на NEON, bit-exact (фіксований порядок block-of-4+tail) · mac-local · d2
+- im2col + conv2d як GEMM проти golden · d4
+- ggml-стильне Q4_0 quant/dequant ядро, byte-exact vs референс · d4
+- Roofline-класифікація: обчислити arithmetic intensity (`|AI−ref|/ref ≤ 0.01`) · d2
+- GPU matmul ядро (єдиний golden-контракт для Metal/MLX і CUDA) · cloud-cuda · d4
+
+**Ресурси:** `flame/how-to-optimize-gemm` · BLISlab (arXiv 1609.00076) · Goto&van de Geijn «Anatomy of HPC MatMul» · Arm NEON Intrinsics Ref + `thenifty/neon-guide` · Roofline (CACM 2009) · Agner Fog · `ggml`/llama.cpp (golden) · `nanobind`.
+
+---
+
+## Блок 3 — Тензори низького рівня (стиснення/формати) 🧮
+**Місія:** уся математика квантизації/форматів руками. **Детальний банк — у `PLAN.md` (модулі М1–М4).**
+
+**Під-теми:** uniform affine (scale/zero-point, sym/asym, per-tensor vs per-channel, похибка ≤ scale/2) → INT8/INT4 group-wise → FP-формати (FP16/BF16/FP8/MXFP4) → NF4 + double-quant → **PTQ-алгоритми**: RTN → SmoothQuant → AWQ → HQQ → GPTQ → GGUF/K-quants byte-exact (Q8_0→Q4_0→Q4_K super-block) + imatrix → Apple MLX/CoreML нативний стек.
+
+**Приклади:** symmetric INT8 round-trip (1 рядок) · linear INT8 per-channel (`size_ratio≥3.8`, `KL≤0.05`) · AWQ проти RTN на INT4 (`ppl≤0.97×RTN`) · GPTQ 3-bit Hessian (капстоун d5) · ggml Q4_K super-block byte-exact · NF4 code-points з нуля (max diff ≤1e-4). **~20 задач** (див. PLAN.md).
+
+---
+
+## Блок 4 — LLM зсередини 🧠
+**Місія:** механіка трансформера й inference на реальних числах, від attention до KV-cache/MoE.
+
+**Під-теми:** токенізація → embedding+позиція → **attention Q/K/V**, causal-маска → multi-head + спеціалізація голів (induction) → FFN як key-value пам'ять → prefill vs decode → sampling/температура → **KV-cache**: MHA→GQA→MQA→MLA (низькоранговий латент) → KV-квант (KIVI) → H2O eviction → PagedAttention → **MoE offloading** (LRU expert-cache, Colibrì/ds4).
+
+**Приклади:** MHA→GQA mean-pool (`kv_ratio≥4`, `agree≥0.97`) · KV INT8 з обмеженою ppl · MLA low-rank латент (звідки «57x») · **LRU expert-cache на фіксованому трейсі** (чистий AoC, `bytes_streamed` byte-exact) · політика, що б'є LRU (`miss≤0.85×`) · PagedAttention блочний алокатор. **~15 задач** (див. PLAN.md М5–М6).
+
+---
+
+## Блок 5 — GPU (кросплатформно) 🎛️
+**Місія:** GPU-ядра, що стартують на Mac (sim/interpreter/Metal/MLX) і масштабуються до CUDA. Один алгоритм — один критерій — обидва бекенди.
+
+**Під-теми:** grid/block/thread/warp, guards → пам'ять global/shared/registers, coalescing → parallel reductions (tree, warp-shuffle) → shared-memory tiling matmul → scan/prefix-sum → occupancy, launch-config → **Triton** (block-pointers, autotune, interpreter) → **Metal compute** / MPS → **MLX** custom kernels (`mx.fast.metal_kernel`) → fused softmax/layernorm/RoPE → **flash-attention** (online softmax + tiling) → quant-matmul (W4A16) → real-CUDA advanced (streams, `cp.async`, tensor cores, Nsight).
+
+**Приклади задач:**
+- Map/Zip kernel (GPU-Puzzles, guards, AST-чек «без готових ops») · mac-local-sim · d1
+- Parallel reduction з warp-shuffle (той самий тест: interpreter + CUDA) · d2
+- Tiled matmul з shared memory (заборона cuBLAS/`tl.dot` на повну) · d3
+- Numerically-stable fused softmax (без NaN, `KL<1e-6`) · d3
+- MLX custom kernel: fused RoPE (`mx.fast.metal_kernel`) · mac-local · d2
+- **Flash-attention** (online softmax; memory-gate: пік `< c·N·d`, не `N²`) · d5
+- Int4/Int8 dequant-matmul (заборона матеріалізувати fp-ваги) · d4
+
+**Ресурси:** PMPP 4th ed. (хребет) · `srush/GPU-Puzzles` (numba-sim, Mac) · `srush/Triton-Puzzles` + Lite · Triton docs (interpreter) · MLX `metal_kernel` docs · Apple Metal Shading Language + MPS · GPU MODE lectures · KernelBench · Tensara/LeetGPU (валідатори) · CUDA C++ Programming Guide.
+
+---
+
+## Блок 6 — CPU-перформанс і чесне вимірювання 📏 (наскрізний)
+**Місія:** «судейський» шар + CPU-perf; перетворює «стало менше/швидше» на чесне число.
+
+**Під-теми:** якісні метрики (`argmax-agreement`, `KL`, `perplexity`, **seqeval** entity-level F1 — чому 91%, а не 98%) → статистика (`bootstrap-CI`, McNemar — значуще чи шум) → latency-дисципліна (`perf_counter`, **p50/p95 не mean**, warmup, thread-pin, speedup=ratio) → профілювання (`memray`, `py-spy`, ORT-profiling JSON, perf) → **VNNI/ISA-detection** (чому INT8 швидший на x86, інший на M4) → roofline.
+
+**Приклади:** argmax+KL scorer (звірка з еталоном ≤1e-6) · seqeval token-vs-entity (`|f1−0.912|≤0.002`) · bootstrap-CI+McNemar (seed=42) · ORT-profiling → частка часу в QLinear · latency p50/p95 + ratio · ISA/VNNI probe з cpuinfo-fixture. **~8 задач** (див. PLAN.md М0).
+
+---
+
+## Блок 7 — Serving і системи ☁️ (просунуте, cloud-tier)
+**Під-теми:** vLLM (PagedAttention, continuous batching), **W4A16 через Marlin**, FP8 KV, `llm-compressor` артефакти, GuideLLM (TTFT/ITL/RPS) → pruning (magnitude/channel/sensitivity, N:M 2:4), distillation (KL+temperature), **QAT** (`torch.ao`) → 8-bit optimizers → розподілене (data/tensor/pipeline parallel).
+
+**Приклади:** W4A16+vLLM+GuideLLM speedup-ratio + якісний гейт · cross-check `llm-compressor` артефакту vs власний dequant · magnitude pruning під sparsity-бюджет · QAT vs PTQ static (довести перевагу QAT) · `lm-eval` custom task. **~10 задач** (див. PLAN.md М7–М8 + bnb/QAT).
+
+---
+
+## Движок «вічно свіжих задач» 🔄
+Конвеєр **WATCH → DETECT → DRAFT → CALIBRATE → REVIEW → PUBLISH** (cron: GitHub Actions / scheduled agent):
+1. **WATCH** — щоденний pull: arXiv API (cs.LG/cs.PF/cs.DC), **HF Papers trending** (Papers-with-Code закрито Meta 07.2025 → рахуємо важливість самі), GitHub star-velocity, HN Algolia, релізи llama.cpp/vLLM/PyTorch → єдина черга (ідемпотентний upsert).
+2. **DETECT** — новизна через MinHash/LSH + embeddings проти корпусу.
+3. **DRAFT** — LLM робить чернетку задачі, але **обов'язково з детермінованим hardware-independent критерієм**.
+4. **CALIBRATE** — на reference-солвері авто-виводимо пороги (correctness-gate + p50/p90 ratio), фіксуємо seeds + lockfile.
+5. **REVIEW** — людський gate (leakage/ліцензія/коректність grader) → **PUBLISH**.
+
+**Cadence:** щотижневі «drops» (5–10 задач) + сезонні sponsored-раунди (модель Advent of Code / GPU MODE). **Жанр «відтвори свіжий claim»:** реалізуй щойно виданий метод, збіжись за метрикою (`argmax==ref`, `KL<ε`) — claim інкапсульовано в hidden reference, не в живий інтернет. **Anti-rot:** щотижневий регрес усього корпусу проти pinned reference у 2 середовищах → карантин «згнилих» задач, міграція v1→v2 зі збереженням pass/fail вектора golden-submissions. **Field-lag SLA** — днів від публікації методу до задачі.
+
+**Приклади мета-задач (самі гейбельні):** multi-source ingest normalizer (sha256 NDJSON) · near-duplicate detector (MinHash) · candidate priority ranker (Kendall τ=1.0) · threshold auto-calibrator · task-rot regression harness · task versioning migration · **reproduce-a-brand-new-paper-claim** (mac-sim + cloud-cuda варіанти). **~11 задач.**
+
+**Ресурси:** GPU MODE `reference-kernels` + `kernelbot` (еталон auto-grade конвеєра) · KernelBench (`fast_p` двоступеневий grading) · `duanyytop/agents-radar` (скелет cron-агрегатора) · arXiv API · HN Algolia API · HF Papers · Modal (GPU runners).
+
+---
+
+## Кросплатформні фази (staging)
+| Фаза | Платформа | Що працює |
+|---|---|---|
+| **Ф1** | macOS-arm64 | CPU + Triton-interpreter + `NUMBA_ENABLE_CUDASIM` + MLX/Metal. **Увесь курс, крім перф-ratio на реальному GPU.** |
+| **Ф2** | Linux + CUDA (Modal/spot) | реальні ядра, TF32-пастки, cuBLAS-пінінг, Nsight-метрики, speedup-ratio |
+| **Ф3** | Windows | msvc-тулчейн, шляхи/CRLF, long/uint розміри |
+
+Golden-еталони генеруються **один раз** на канонічному бекенді (CPU, fp32, `OMP=1`, TF32-off, deterministic-on). GPU-задачі несуть **два шляхи** (mac-sim + cloud-cuda) з тим самим числовим gate — стейджинг змінює лише runner, не критерій.
+
+---
+
+## Дорожня карта збірки
+1. **M-0:** Блок 0 (grader-каркас: fixtures-масиви, tolerance-ворота, multi-backend adapter, канонічний golden) — без нього нічого не портується.
+2. **M-1:** Блок 1 (Python) як Mac-first онбординг + Блок 6 scorer-примітиви.
+3. **M-2:** Блок 3 (тензори) + Блок 2 (C++) — ядро «низького рівня».
+4. **M-3:** Блок 4 (LLM) + Блок 5 (GPU, Mac-шлях).
+5. **M-4:** Движок свіжості (WATCH→PUBLISH) — щойно є ≥3 блоки, щоб було що оновлювати.
+6. **M-5:** Ф2 (Linux+CUDA) + Блок 7 (serving) + Ф3 (Windows).
+
+**Генерація задач — паралельним Workflow (1 задача = 1 агент):** пише умову+starter+reference+grader+fixtures і **емпірично калібрує поріг** на reference. Ліцензії: постановку+метрику беремо вільно; код чужих репо не вендоримо дослівно (більшість MIT/Apache/BSD).
+
+---
+
+## Відкриті рішення (твої)
+1. **Порядок блоків для тебе:** старт із Блоку 1 (Python) чи одразу Блок 3 (тензори)?
+2. **Скоуп Ф1-MVP:** Блок 0 + Блок 1 + перші 2 модулі Блоку 3 — чи ширше.
+3. **Назва** (робоча «Arena»).
+4. **Движок свіжості зараз чи після ядра** (рекомендація: після M-2, щоб було що оновлювати).
+5. **Приватно спершу чи публічно (Show HN) з першого дропа.**