veda

Imported from pictaile/veda (AGENTS.md). Install upstream with npx skills add pictaile/veda. Copyright stays with the author.

veda

Рушій інференсу LLM на C++23, CMake ≥ 3.20, без жодної зовнішньої залежності — свій JSON, safetensors, BPE, autograd. Роадмап пройдено: епіки E1–E13 (інференс) і E14–E17 (навчання). Працюють дві наскрізні віхи:

./build/veda_train --text corpus.txt --steps 500 --out runs/first
./build/veda_run   runs/first --prompt "the " --max 60

veda_run відкриває чекпоінт, написаний veda_train, не знаючи, що модель навчена, а не завантажена: чекпоінт — це каталог у форматі HF (config.json + model.safetensors + tokenizer.json), який читає той самий veda::io.

Шари в src/libs/: tensor (в'ю, страйди, bf16), ops (matmul, softmax, пул потоків), testing (еталонний харнес), io, tokenizer (BPE), nn, model (увага, RoPE, GQA, KV-кеш), binding, generate (греді/температура/top-k/top-p), profile, autograd, optim (AdamW), data, train (TinyTransformer, Trainer).

Що кожен епік вирішив і чому — у docs/ (по документу на шар: tensor.md, ops.md, harness.md, io.md, tokenizer.md, nn.md, attention.md, generate.md, performance.md, autograd.md, training.md, training-loop.md, training-performance.md). Читай їх перед зміною шару: там записані причини, і більшість із них — заміри, а не смаки.

Планувальні артефакти BMad — у _bmad-output/planning-artifacts/roadmap/ (roadmap.md, roadmap-training.md, tasks/E*). Ця тека в .gitignore: вона є локально, але не в git.

Бінарник veda (src/main.cpp + Facade) — демонстрація можливостей veda::core з епіку E1, а не точка входу рушія. Робочі точки входу — чотири інструменти в tools/.

Running and verifying

cmake -G Ninja -S . -B build        # Release за замовчуванням, див. нижче
cmake --build build -j8
ctest --test-dir build -j8          # 69 тестів, усі мають бути зелені (~0.2 с)

• CI немає. ctest локально — єдина перевірка; проганяй його перед тим, як заявити, що зроблено.
• Не збирай у Debug, коли міряєш щось. CMakeLists.txt форсує Release, якщо тип не заданий явно, і це не косметика: до E17 у проєкті не було жодного прапорця оптимізації, тож усі числа, будь-коли виміряні цим проєктом, були виміряні на -O0. Виправлення дало ×5.7 без жодної зміни в алгоритмах.
• Інструменти: veda_train (--text --out --steps --batch --window --lr --layers --hidden --heads --seed --profile --threads), veda_run (--prompt|--ids --max --temp --top-p --top-k --seed), veda_bench (--tokens --threads --prompt-len), veda_inspect <каталог|.safetensors>.
• Для clangd генеруй свій індекс: cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON (у поточному build/ він вимкнений), і вкажи clangd на build/.
• Усе, що торкається потоків, ганяй під -fsanitize=address,undefined. Це не формальність: у пулі потоків ASan знайшов два баги, яких незасанітайзена збірка не показувала (див. docs/training-performance.md). Окремого таргета чи пресета для цього немає — конфігуруй вручну в іншій теці збірки.

Conventions that differ from defaults

• Підключай заголовки плоско — #include "Tensor.h", не #include "libs/tensor/Tensor.h". Кожен каталог бібліотеки окремо перелічений у target_include_directories.
• Додаючи src/libs/<name>/, зроби обидві правки в CMakeLists.txt: впиши і .cpp, і .h у add_executable(veda ...), і додай каталог у target_include_directories. add_subdirectory та окремих бібліотечних таргетів у проєкті немає.
• Тести не лінкуються з таргетом veda. Кожен тест — окремий бінарник із власним main(); харнес — tests/TestSupport.h, без зовнішніх залежностей. Додавай так: veda_add_test(MyTest ${VEDA_CORE_SOURCES} ${VEDA_OPS_SOURCES} ...), перелічуючи саме ті групи джерел (VEDA_*_SOURCES), яких тест справді потребує — у цьому й сенс поділу.
• Усе, що тягне ops (а отже пул потоків), лінкуй із Threads::Threads.
• VEDA_TESTING_SOURCES (src/libs/testing/) — dev-інструмент: лінкується лише в тести, ніколи в veda. Ні збірка, ні запуск рушія не потребують ані цього модуля, ані Python (критерій прийняття E3).
• Операція — чиста функція, шар володіє вагами. Операції ніколи не мутують входи — жодних add_ «для швидкості». Це не стиль: autograd вимагає рівно цього, бо вузол стрічки тримає свої входи й мусить бути певен, що вони ті самі.
• Не додавай -ffast-math і не переставляй порядок сумування в matmul. Уся референсна звірка (E3) стоїть на тому, що Веда сумує саме в тому порядку, який декларує. Паралелити можна лише по незалежних виходах — розбиття циклу k було б швидшим і змінило б кожне число в моделі.
• Мітки вузлів autograd — рядкові літерали, не std::string: інакше кожен вузол алокує пам'ять усередині того, що профіль має міряти.

Known pitfalls

• Не складай у cmake-build-debug/ і cmake-build-debug-docker/ — їхній CMAKE_HOME_DIRECTORY вказує на /Users/konstantinohotnik/apps/veda і /tmp/veda, і обидві зібрані в Debug. Теки в .gitignore, у git їх немає. Складай у build/.
• docker-compose.yml монтує .:/app поверх /app, ховаючи build/ з образу — ./build/veda всередині контейнера не існує, поки не складеш там заново.
• __pycache__ не покритий .gitignore, і tools/__pycache__/*.pyc уже потрапили в індекс. Не комітай їх; якщо чіпаєш tools/*.py — прибери з індексу й додай патерн у .gitignore.
• Зміна порядку операцій із рухомою комою ламається тихо: помилка в сталий множник у backward усе одно навчає, просто гірше. Тому є autograd::check_gradient — користуйся ним на кожній новій операції, а не наприкінці.
• Токенізатор, що розійшовся з еталонним на одне злиття, псує вивід без жодної помилки. Кирилиця робить байтовий фолбек основним шляхом, а не крайнім випадком.