Внесок у проєкт LLiMa

LLiMa містить компілятор GenAI для сторони хоста та C++ середовище виконання для Modalix. Середовище виконання працює через упаковані точки входу CLI/HTTP/ZMQ; Python використовується для оркестрації CLI, а не як окремий загальнодоступний API середовища виконання. Зберігайте компілятор і середовище виконання, а також їхні залежності, окремо. Під час отримання коду з репозиторію, CONTRIBUTING.md надає інструкції для швидкого старту, а AGENTS.md визначає специфічні для агентів правила; цей посібник є детальним описом правил для розробників.

Навички програміста-агента.

Встановіть обидва набори навичок для учасників, LLiMa, як частину стандартного налаштування для учасників. Вони навмисно не встановлюються за допомогою стандартного індексу сценаріїв Neat SDK:

sima-cli playbooks install \
  gh:sima-neat/llima/skills/sima-contribute-to-llima
sima-cli playbooks install \
  gh:sima-neat/llima/skills/sima-add-llima-model-support

Загальні навички учасника охоплюють компілятор, середовище виконання, пакування, тестування, документацію та зміни, що стосуються всього репозиторію. Навички підтримки моделі додають сумісність і робочий процес реалізації для архітектур LLM і VLM, контрольних точок, розміщення тензорів, токенізаторів і шаблонів підказок. Переконайтеся, що обидва встановлено, щоб відповідні інструкції були доступні, коли внесок виходить за межі цих параметрів.

Схема репозиторію.

Площа	Шляхи, стежки	Відповідальність.
Конфігурація	sima_lmm/config/	Конфігураційні файли для LLM, VLM та ASR.
Вживання.	sima_lmm/hf/, sima_lmm/gguf/	Завантаження та перетворення форматів Hugging Face і GGUF.
Компіляція	sima_lmm/model/, sima_lmm/preproc/	Компоненти моделі, квантування, графіки та попередня обробка.
Інструменти для хостингу.	sima_lmm/host/	Зберіть, розгорніть, LoRA, і проведіть тестування продуктивності основних точок входу.
Оцінювання.	sima_lmm/mole/	MoLE робочі процеси
Інтерфейс командного рядка для середовища виконання.	sima_lmm/devkit/	Python Оркестрація за допомогою інтерфейсу командного рядка та керування моделлю.
C++ середовище виконання	sima_lmm/devkit/cpp/	Моделі, токенізатор, MLA, реалізації CLI/HTTP/ZMQ та внутрішнє зв’язування CLI.
Тести	tests/	Тести компілятора та середовища виконання Modalix.
Упаковка	CMakeLists.txt, cmake/, build*.sh, tools/install_*.sh	Debian, формат wheel та збірка артефактів.
Кеші CI	.github/workflows/, tools/ci/, tools/hf-safetensors/	Здійснює збірку, тестування та зберігає кеш моделі.
Документація/навички	README.md, docs/, skills/	Користувач, автор, інструкції щодо використання Playbooks.

Залежності, які потрібні лише для компіляції, не повинні включатися до sima_lmm/devkit/ або до пакетів Modalix, що використовуються в середовищі виконання.

Середовища розробки

Середовище виконання та пакування.

Використовуйте Neat SDK як підтримуване середовище для збірки. Зберіть усі пакети для середовища виконання та упаковані тести за допомогою:

./build.sh --all --clean

Під час звичайної збірки виконуються всі необхідні налаштування, зокрема, ініціалізація підмодулів; не потрібно виконувати окремий етап встановлення залежностей для стандартного процесу.

Корисні альтернативні варіанти збірки:

./build.sh --clean --core
./build.sh --clean --core --dev
./build.sh --clean --cli
./build.sh --no-dist

Результати генеруються в рамках build-deb/ і розміщуються в dist/. Modalix необхідний для виконання MLA і для реальної перевірки llima run.

Розробка компіляторів.

Використовуйте середовище Python 3.12, встановлене за допомогою Model Compiler. Здійснюйте пошук у наступному порядку:

1. /sdk-extensions/model-compiler
2. /sdk-add-on/model-compiler
3. $HOME/sdk-extensions/model-compiler

source <model-compiler-venv>/bin/activate
python -m pip install -e '.[sdk_ext,tests]'
llima-compile --help

Не створюйте додаткове середовище, яке затінюватиме встановлені пакети компілятора. Створюйте профілі для публікації за допомогою:

./build_compiler_wheel.sh
./build_mole_package.sh

Вони використовують інструменти для роботи з колісними приводами під час build/ і розміщують проміжні результати під час dist/compiler/ та dist/mole/.

Розробка Whisper та ASR.

Загальнодоступний процес llima-compile охоплює LLM та VLM. Для наявної Whisper замість попередньої використовується утиліта для розробників: scripts/gen_models--openai--whisper.py.

python scripts/gen_models--openai--whisper.py \
  --model_path /path/to/openai/whisper-small \
  --output /path/to/whisper-output \
  --part all

Запустіть його в середовищі Model Compiler із зазначенням явного шляху до моделі. --part приймає all, encoder, language_detect, init, single_pre, single_post та single_cache. Додайте --enable_log_probe, щоб скомпілювати вихідні дані декодера з увімкненим журналюванням; використовуйте --part all --enable_log_probe для повної збірки з увімкненим журналюванням.

Зазвичай зміни в компіляторі стосуються файлів sima_lmm/config/whisper_config.py, sima_lmm/model/whisper_*.py та скрипту; зміни в середовищі виконання стосуються sima_lmm/devkit/cpp/whisper_*. Перевірте за допомогою упакованого тесту середовища виконання C++ ASR, описаного в tests/README.md, та репрезентативних аудіофайлів на Modalix. Це специфічний шлях для Whisper, а не загальна архітектурна структура ASR.

Тестування

Обирайте тести за типом помилки. Збірка не замінює перевірку поведінки, і пропущений обов’язковий тест не вважається успішно пройденим.

Герметичні випробування.

Забезпечте, щоб чиста конфігурація, відображення, серіалізація, перевірка та числова логіка були незалежними від завантаження моделей:

pytest -q <targeted-test-path>

Тести компілятора, що використовують модель.

Тести компілятора розміщено за адресою tests/compilation/. Оберіть відповідну групу та маркер, описані в tests/README.md. Наприклад:

export LLIMA_HF_MODELS_PATH=/path/to/llima-model-inputs
python -P -m pytest \
  -c pytest.ini \
  tests/compilation/configuration \
  -m compiler_config \
  --strict-markers \
  -vv -ra

--model-inputs-path та LLIMA_HF_MODELS_PATH визначають підготовлену кореневу директорію Hugging Face/GGUF. Система безперервної інтеграції (CI) використовує маніфести, що знаходяться в tools/hf-safetensors/.

Налаштуйте необхідні вхідні дані замість того, щоб дозволяти пропуск тестів.

Матриця тестів, очікувані значення та базові правила розміщені в tests/README.md; виклик CI розміщено в .github/workflows/model-compiler-tests.yml. Генеруйте ONNX та числові артефакти порівняння під час виконання, а не зберігайте бінарні базові значення.

Перевірка під час виконання (у середовищі виконання).

Створіть пакети для кандидатів і додаткові компоненти для тестування в середовищі виконання:

./build.sh --all --clean

Це дозволяє зібрати проєкт, але не запускає тести. Встановіть відповідну версію LLiMa та пакети Internals на Modalix, розпакуйте додатковий архів і запустіть упаковані тести CTest і pytest, дотримуючись інструкцій щодо тестування в середовищі виконання DevKit, наведених у файлі tests/README.md.

Запускайте відповідні апаратні тести, коли зміни стосуються завантаження моделі, виконання висновків, токенізації, багатомодальної попередньої обробки, спекулятивного декодування, CLI/HTTP/ZMQ або життєвого циклу ресурсів. За потреби додайте репрезентативний базовий тест.

llima run <model_dir> --mode cli

Для змін, пов’язаних з VLM, додайте запит, що містить зображення. Ручне тестування на наявність помилок доповнює, але не замінює, охоплення відповідних пакетів.

Neat Core використовує встановлені LLiMa API та пакети середовища виконання C++. Коли будь-яка з цих компонентів або поведінка, що реалізується через API GenAI Core, змінюється, створіть Core, використовуючи кандидатські пакети sima-lmm-core та sima-lmm-dev, а не опубліковану або кешовану збірку LLiMa. Запустіть відповідні тести Core GenAI C++ на Modalix. Ця перевірка на наступному етапі не потрібна для ізольованих змін, що стосуються компілятора, документації або лише тестів.

Перевірка відповідності пакування встановленим вимогам.

Зберіть кожен змінений профіль:

./build.sh --all --clean
./build_compiler_wheel.sh
./build_mole_package.sh

Перевірте назви пакетів, права власності на файли, файли маніфестів встановлення, залежності, контрольні суми та метадані.

Стандарти кодування

Сумісність і межі.

Розглядайте встановлені заголовні файли C++, команди інтерфейсу командного рядка, серіалізовану конфігурацію, метадані пакету та згенеровані макети артефактів як сумісні інтерфейси. Віддавайте перевагу інкрементним змінам. У разі внесення несумісних змін, документуйте задіяні компоненти, процес міграції та заплановані зміни; оновлюйте виклики, тести, приклади та документацію для користувачів.

Тримайте компілятор, середовище виконання та залежності MoLE окремо. Стан середовища виконання не повинен бути вхідними даними для компіляції. Зміни меж пакету середовища виконання повинні зберігати ролі sima-lmm-core, sima-lmm-dev та sima-lmm-cli і включати відповідну валідацію API/ABI.

Якість реалізації.

• Цільові версії C++20 і Python, зазначені у файлі pyproject.toml.
• Дотримуйтеся загального форматування, використовуйте відповідні назви та забезпечте групування; уникайте надмірної узагальненості. механічне переформатування.
• Зберігайте кількість встановлених інтерфейсів на мінімальному рівні та не розголошуйте деталі реалізації.
• Додайте анотації типів Python, де це доцільно.
• Поясніть неявні умови договорів, числові припущення та технічні характеристики обладнання. обмеження; не потрібно описувати код.
• Перш ніж додавати абстракції, повторно використовуйте наявні допоміжні функції.
• Забезпечте збереження детермінованого вибору моделі, структури графа та можливості серіалізації. імена артефактів. Зберігайте початкові значення та уникайте впорядкування файлової системи/процесів.
• Відхиляйте неприйнятні або недійсні вхідні дані, надаючи контекст; зберігайте першопричини. між різними рівнями, і при цьому ніколи не обирає інший шлях виконання мовчки.
• Організуйте взаємодію між працівниками та процес демонтажу. Створіть буфер, обробіть, налаштуйте та... Явно вказуйте власника тимчасових файлів; безпечно видаляйте частково виконану роботу.
• Уникайте зайвого виділення пам’яті, створення копій і синхронізації в критичних ділянках коду.

Моделі, артефакти, залежності та секрети.

Дозволено використовувати наступні матеріали для тестування:

• переглянуто контракти щодо налаштувань JSON;
• джерела, контрольовані версії, початкові дані, допустимі відхилення та політика порівняння; і
• створює файли маніфесту для затверджених незмінних версій Hugging Face/GGUF.

Не додавайте до репозиторію завантажені ваги, дані користувачів або згенеровані файли ONNX, NumPy, квантовані дані, MPK, ELF або дерева моделей для середовища виконання. Зберігайте згенеровані результати в папках, які не відстежуються системою контролю версій, або в тимчасових папках.

Використовуйте deps/manifest.json для версій пакетів/платформ. Розглядайте third_party/ як сторонній код; ізолюйте та документуйте навмисні оновлення підмодулів. Не додавайте залежності компілятора до пакетів Debian, які використовуються під час виконання.

Ніколи не додавайте до репозиторію або не зберігайте в логах токени, облікові дані SSH, приватні репозиторії, підписані URL-адреси або особисті шляхи. Зберігайте авторизацію для моделей, що потребують контролю доступу, поза системою контролю версій і використовуйте загальнодоступні ідентифікатори моделей, незмінні версії та відредаговані журнали у звітах.

Документація, навички та запити на внесення змін.

Оновіть найближчий посібник для користувача:

• Вимоги до системи
• Компіляція моделі
• Розгортання моделі
• LLiMa CLI
• MoLE

Залиште файл CONTRIBUTING.md як інструкцію для швидкого старту, цей файл – як детальну політику, а AGENTS.md – як набір правил для агентів, що підлягають виконанню. У наборі навичок обов’язково повинні бути вказані дійсні SKILL.md, playbook.yml та метадані агентів; зробіть їх основний робочий процес коротким і перенесіть умовні деталі в прямі посилання.

Перевіряйте всі корисні дані навичок з кореневої директорії репозиторію в Neat SDK, не змінюючи встановлений стан агентів:

playbooks_validation_dir="$(mktemp -d)"
CODEX_HOME="${playbooks_validation_dir}/codex" \
CLAUDE_HOME="${playbooks_validation_dir}/claude" \
SIMA_CLI_HOME="${playbooks_validation_dir}/sima-cli" \
sima-cli playbooks install ./skills

Звіт про встановлення має містити інформацію про те, що було detected: 3, що було valid: 3 і що було discarded: 0. Версія sima-cli має відповідати вимогам min_cli_version у кожному файлі playbook.yml.

Для запитів на внесення змін:

• створіть гілку на основі та націльте її на поточну гілку develop;
• зосереджуйте зміни в коді, використовуючи наказові форми дієслів у повідомленнях до комітів;
• використовуйте .github/PULL_REQUEST_TEMPLATE.md;
• пов’яжіть вирішені проблеми з Fixes #<issue>;
• повідомити про ризики, сумісність/перехід, вплив на документацію, відтворювані команди. версії моделі/пакета, дані про апаратне забезпечення, пропущені перевірки та залишковий ризик; і
• виключіть облікові дані та конфіденційні активи.

Внесок вважається готовим, коли всі відповідні тести успішно проходять без непередбачених пропусків, необхідні пакети та перевірки Modalix завершено або чітко вказано, що вони недоступні, питання сумісності та документації вирішено, і в запиті на внесення змін (PR) містяться відтворювані докази.