gpuhire 0.2.0__tar.gz

gpuhire-0.2.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtualenv
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Build
+build/
+dist/
+*.whl
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project: local scratch
+/tmp/
+/scratch/
+/examples/_out/
+/examples/*_out/
+
+# Project: never commit credentials, even if accidentally dropped here
+**/kaggle.json
+**/access_token
+.modal.toml
+.env
+.env.local
+e2e_modal_out/
+e2e_out/
+
+# Артефакти прогонів (2026-07-29). `out/<job-id>/` — вивід fetch'а по кожному
+# job'у, `.scratch/` — робочі теки датасетів; і те, й те відтворюване і росте
+# без обмежень (1400+ файлів на момент правила). У git — тільки код.
+/out/
+/.scratch/
+*.log
+to_stop.txt
+
+# 🔴 Логи прогонів у корені. Наглядач із 19.08 пише свій лог у data_dir(),
+# але ручні запуски й далі лишають файли тут — а вони накопичуються роками
+# (травневі sweep_v*.log дожили до вересня й не значили вже нічого).
+*.log
+*.err
+/phase.txt
+/to_stop.txt
+
+# Реєстр боксів і калібрування — дані користувача, не пакета (див. config.registry_dir)
+/data/

gpuhire-0.2.0/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Журнал змін
+
+Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), версії —
+[SemVer](https://semver.org/lang/uk/). До 1.0 мінорна версія може міняти
+поведінку; те, що описано в [`docs/contract.md`](docs/contract.md), у межах
+мінорної версії не міняється.
+
+## [Unreleased]
+
+## [0.2.0] — 2026-09-21
+
+Перший публічний випуск. Версія 0.1 жила приватним інструментом одного
+дослідження; нижче — те, що змінилося на шляху до публікації.
+
+### Додано
+
+- **Доставка без бакета: `htr plan --transport box|auto`.** Хмарний прогін
+  доти вимагав свого S3 навіть від того, хто просто орендував машину на
+  годину: раннер уміє брати дані лише `curl` по посиланню, а видати таке
+  посилання вмів тільки бакет. Тепер його може видати сама машина — кадри й
+  ассети кладе туди системний `scp` (7.56 проти 0.48 МБ/с у SFTP paramiko,
+  заміряно на орендованому боксі), а на її петлі піднімається крихітний склад
+  (`htr/origin.py`, GET/PUT, лише `127.0.0.1`). Раннер не змінюється жодним
+  рядком. Доставка йде ПІСЛЯ воріт — інакше кожна забракована машина коштувала
+  б заливки; канал хоста до інтернету при цьому не міряється взагалі.
+  🔴 Чекпоінти на такій машині гинуть разом із нею, тож наглядач везе їх
+  додому кожні п'ять хвилин ПІД ЧАС роботи, а не в кінці. `auto` (дефолт)
+  бере бакет, коли він налаштований. Передполіт для `box` перевіряє диск, а не
+  мережу: посилань ще не існує, їх видасть машина, якої поки немає.
+- **Машинний вивід `--json` у `run`, `status`, `fetch`.** Останній рядок stdout,
+  що починається з `{`, — один JSON-об'єкт зі `schema`; людське з `--json` іде в
+  stderr, код виходу той самий, відмова теж відповідає об'єктом. Стан прогону —
+  із закритого переліку `queued · running · completed · failed · cancelled ·
+  unknown`. Споживачі більше не мусять розбирати текст.
+- **`docs/contract.md`** — на що мають право спиратись програми, які кличуть
+  gpurunner: команди й прапорці, форма відповідей, схема `plan.json`, змінні
+  оточення.
+- **Плагін оренди для Нишпорки** — entry point `nyshporka.cloud`
+  (`gpurunner.plugins.nyshporka_cloud:VastRent`). gpurunner орендує й гасить бокс
+  на Vast.ai (скоринг офферів, реєстр боксів, перевірка балансу, незнімна стеля
+  ціни), а заливку, прогін і забір Нишпорка веде сама по SSH; R2 не потрібен.
+  Понад контракт — `status()`, `login(api_key)`, `estimate(need)`. Опис —
+  [`docs/nyshporka.md`](docs/nyshporka.md), форма — `docs/contract.md` §6.
+- Vast: **оренда без job'а** — `VastBackend.rent_box / destroy_box / box_info /
+  live_instances`. onstart такого боксу — лише жорсткий таймер самознищення;
+  будь-який збій після створення інстансу (зокрема Ctrl+C) гасить його.
+- **SSH-ключ без рук:** `auth.vast.ensure_ssh_key()` генерує пару ed25519 у
+  `<config>/vast_ssh/`, коли ключа немає ні в `GPURUNNER_VAST_SSH_KEY`, ні в
+  `~/.ssh`. Наявний ключ не перезаписується ніколи; свій має пріоритет.
+- **`gpurunner auth vast --key <КЛЮЧ | ->`** зберігає ключ API у
+  `<config>/vast_api_key` (`-` — зі stdin); ключ ніде не друкується.
+- Реєстр боксів: вирок **`slow_run`** (тиждень, бан із двох ударів) — машина
+  читала повільніше за прогноз за словами викликача, що орендував без наглядача.
+- Job **`rukopys_ocr`** — сторінкове читання моделлю Rukopys-OCR-4B.
+- Vast: параметр **`min_cuda`** (мінімальна CUDA драйвера хоста).
+- **`tools/scan_private.py`** — ворота проти приватних даних, у pre-commit і CI.
+- `LICENSE` (MIT), `CONTRIBUTING.md`, `SECURITY.md`, extra `all`.
+- CI (Linux 3.11–3.13, Windows 3.12) і реліз за тегом через Trusted Publishing.
+- Наглядач попереджає, коли стартує з порожнім реєстром боксів.
+- `gpurunner htr calibrate` показує медіану окремо по старому й новому раннеру
+  та стелю за ядрами як вимір сітки. Саме розрив між раннерами був ранньою
+  ознакою того, що модель поїхала, — одне спільне число його ховало.
+- Стан заходу зберігає `pages_this_run` і `wall_sec` кожної справи. Доти
+  `pages_done` включав підняте з чекпоінтів, а темп рахувався лише від
+  зробленого зараз — і відсіяти відновлені й догінні заходи з калібровки було
+  неможливо в принципі.
+- Таблиця ринку показує «ядра» в колонці «що тисне», коли темп ріже саме CPU:
+  доти бокс із 20 шардами на 20 ядрах виглядав обмеженим шардами.
+
+### Змінено
+
+- **Реєстр боксів і калібрування шардів — дані користувача, а не пакета.**
+  Адресу дає `GPURUNNER_REPO_DATA_DIR`, без неї — `<тека даних>/registry`. Доти
+  реєстр жив у `data/` репозиторію й шукався відносно файла пакета — у
+  встановленому колесі ця адреса вказувала в `site-packages`.
+- **Нейтральні імена за замовчуванням:** бакет R2 `gpurunner-htr`, томи Modal
+  `gpurunner-htr` і `gpurunner-spotter`. Свої задаються параметром
+  `modal_volume`, змінними `GPURUNNER_MODAL_VOLUME[_<JOB>]`, `R2_BUCKET`.
+- `htr_eval`: параметр `target` обов'язковий.
+- `htr fetch-ckpt`: гілка декоду визначається правилом `out` / `out-<тег>`, а
+  не зашитим переліком моделей.
+- `requires-python >= 3.11` (було 3.12); версія пакета береться з одного місця.
+- Бекенд Modal відмовляє ще до збирання образу, якщо локальний Python не збігається
+  з версією образу (3.12): Modal серіалізує обгортку між інтерпретаторами.
+- Довідка CLI (`--help`) — українською цілком.
+
+### Виправлено
+
+- `htr plan`: архів кадрів заливався під іменем теки, а посилання вело на ім'я
+  прогону — перечитування справи іншою моделлю давало 404 у передпольоті.
+- Після `--json` людський вивід консолі не «прилипає» до потоку попереднього
+  виклику.
+- `htr supervise --detach` на macOS: умова вимагала бінарника `setsid`, якого
+  відчеплення не потребує (`start_new_session`). На POSIX вивід відчепленого
+  процесу тепер іде в `spawn.log`, як на Windows, а не в `/dev/null`.
+- Колесо збирається: `force-include` дублював файли пакета, і `uv build` падав.
+- `mypy src` чистий (було 69 зауважень).
+- **Кошторис занижувався саме на тих машинах, які ми купуємо тепер.** Модель
+  темпу множила повний темп шарда на флот, який нема кому годувати: після того
+  як 06.09 шард дістав право жити на одному ядрі, заходи пішли по 14–20 шардів
+  на 19–23 ядрах — режиму, на якому калібрували, тоді не існувало. Спільна
+  медіана прогноз/факт виглядала майже пристойно (1.06), і за нею ховався
+  розрив **0.96 на старому раннері проти 1.27 на новому**. Лікує стеля за
+  ЯДРАМИ: шард виходить на повний темп приблизно з двох ядер
+  (`CORES_PER_SHARD_FULL_RATE = 1.8`), нижче — темп росте з ядрами, а не з
+  флотом. Саме число підібране за смугою, де ядер бракує: без стелі вона дає
+  1.27, при 1.5 — 1.11 (усе ще завищує), при 2.0 — 0.87 (карає дешеві
+  малоядерні бокси — рівно та вада, через яку ворота ціни їх колись
+  відкидали). ⚠ Не плутати з тим, скільки ядер шард ЗАЙМАЄ: там близько
+  одного, і на 1.5 ядра шард працює — просто дає ~0.8 повного темпу.
+  Замір: 113 заходів у смузі «ядер менше двох на шард» дають сталу величину
+  рядко-годин на ЯДРО (~20 000), а не на шард; на фіксованому флоті 13–16
+  шардів 15 ядер дали 261 536 рядко-год, 19 — 448 416, 27 — 562 297.
+  🔴 Це НЕ повернення стелі, знятої 05.09: та була зростаюча й завищувала
+  прогноз багатоядерним (525 проти 2000), ця — спадна й ніколи не піднімає
+  прогноз вище за флотовий доданок.
+  Разом із нею перекалібровано криву за матеріалом (`L0` 29 → 40,
+  `A` 33 700 → 36 000). Результат: медіана 0.94 на 457 чистих заходах, обидві
+  смуги («ядер менше двох на шард» і решта) сходяться на 0.94, вересневий зріз
+  1.19 → 0.95, частка завищень понад 25% — 38% → 28%. Невідомий матеріал прогнозується як і доти (220 стор/год на
+  шард), тож жоден старий приймач не зрушив.
+- **Калібровка більше не рахує проби за заходи.** 59 записів із менш ніж 20
+  прочитаними сторінками (проби, догони, два записи з нулем сторінок при
+  додатному темпі) давали медіану 4.29 і тягли модель угору: вони міряють не
+  темп, а фіксовану ціну справи, яку модель рахує окремо.
+
+- **Вісім тестів розкладки були зелені на Windows і червоні на Linux.** Вони
+  підставляли `os.cpu_count()`, а `_usable_cores()` бере ще й
+  `len(os.sched_getaffinity(0))` — виклик, якого на Windows немає взагалі, а в
+  CI він повертає справжні два ядра раннера й мовчки затирає підставлене
+  число. Спільна фікстура `host_cores` ставить обидва джерела разом і додає
+  `sched_getaffinity` там, де його в `os` нема, — тобто гілка прив'язки тепер
+  перевіряється й на машині розробника. Сам раннер не міняється: він читав
+  ядра правильно, брехали тести.
+
+### Відоме про ім'я
+
+- ⚠ **На PyPI пакет зветься `gpuhire`**, а команда, модуль і репозиторій —
+  `gpurunner`. Ім'я `gpurunner` майданчик не дав узяти: воно надто схоже на
+  наявний `gpu-runner` (0.0.7), і захист від typosquatting дивиться не на
+  точний збіг. Перейменовувати команду заради цього не стали — вона стоїть у
+  документації, у скілах Нишпорки й у змінній `NYSH_GPURUNNER`, а людина в
+  терміналі набирає команду, не ім'я колеса.
+
+### Прибрано
+
+- Залежність `jinja2` і порожній пакет `templates` — не використовувались.
+
+### Відомі обмеження
+
+- Бібліотечний код друкує через `print`, окремого логера ще немає.
+- Бекенди, що емулюють файлову систему Kaggle, дублюють частину коду.
+- Перелік job'ів ведеться у двох місцях `jobs/__init__.py`.
+- Загальної команди перевірки оточення (`doctor`) немає — лише
+  `auth <бекенд> --verify` по одному.
+

gpuhire-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serhii Dalishchynskyi
+
+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.

gpuhire-0.2.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.5
+Name: gpuhire
+Version: 0.2.0
+Summary: Один CLI для GPU-задач на Kaggle, Modal, Colab, Vast, Lightning, Beam і Saturn: подати, стежити, забрати, не переплатити
+Project-URL: Homepage, https://github.com/SERGIUSH-UA/gpurunner
+Project-URL: Source, https://github.com/SERGIUSH-UA/gpurunner
+Project-URL: Issues, https://github.com/SERGIUSH-UA/gpurunner/issues
+Project-URL: Changelog, https://github.com/SERGIUSH-UA/gpurunner/blob/main/CHANGELOG.md
+Author: Serhii Dalishchynskyi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: batch,colab,gpu,htr,kaggle,modal,ocr,rental,vast
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Ukrainian
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: kaggle>=1.6
+Requires-Dist: nbformat>=5.10
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: psutil>=5.9
+Requires-Dist: pydantic>=2.6
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: boto3>=1.34; extra == 'all'
+Requires-Dist: fastapi>=0.115; extra == 'all'
+Requires-Dist: google-api-python-client>=2.130; extra == 'all'
+Requires-Dist: google-auth-oauthlib>=1.2; extra == 'all'
+Requires-Dist: modal>=0.64; extra == 'all'
+Requires-Dist: paramiko>=3.4; extra == 'all'
+Requires-Dist: pillow>=10.0; extra == 'all'
+Requires-Dist: uvicorn>=0.30; extra == 'all'
+Provides-Extra: beam
+Requires-Dist: beam-client>=0.2.200; extra == 'beam'
+Provides-Extra: colab
+Requires-Dist: google-api-python-client>=2.130; extra == 'colab'
+Requires-Dist: google-auth-oauthlib>=1.2; extra == 'colab'
+Provides-Extra: lightning
+Requires-Dist: lightning-sdk>=2026.7; extra == 'lightning'
+Provides-Extra: modal
+Requires-Dist: modal>=0.64; extra == 'modal'
+Provides-Extra: r2
+Requires-Dist: boto3>=1.34; extra == 'r2'
+Requires-Dist: pillow>=10.0; extra == 'r2'
+Provides-Extra: saturn
+Requires-Dist: saturn-client>=2026.2; extra == 'saturn'
+Requires-Dist: saturnfs>=2024.3; extra == 'saturn'
+Provides-Extra: vast
+Requires-Dist: paramiko>=3.4; extra == 'vast'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115; extra == 'web'
+Requires-Dist: uvicorn>=0.30; extra == 'web'
+Description-Content-Type: text/markdown
+
+# gpurunner
+
+Один CLI для GPU-задач на чужому залізі: подати, стежити, забрати результат,
+не переплатити. Сім бекендів за одним інтерфейсом — Kaggle, Modal, Google Colab,
+Vast.ai, Lightning, Beam, Saturn Cloud.
+
+> **In English.** `gpurunner` is a command-line tool that submits GPU jobs (OCR,
+> handwriting recognition, model training) to Kaggle, Modal, Colab, Vast.ai,
+> Lightning, Beam or Saturn Cloud through one interface, tracks them in a local
+> manifest, fetches outputs and keeps an eye on spending. Documentation and CLI
+> messages are in Ukrainian. It works on its own and also serves as the GPU
+> rental module of [nyshporka](https://github.com/SERGIUSH-UA/nyshporka).
+
+Статус: альфа (0.2). Команди й машинний вивід, на які спираються інші програми,
+описано в [`docs/contract.md`](docs/contract.md) і в межах мінорної версії не
+міняються; решта ще рухається.
+
+## 1. Навіщо
+
+- Той самий job іде на безкоштовну квоту Kaggle, на Modal із посекундним
+  білінгом або на орендований бокс Vast — міняється лише `-b`.
+- Кожен прогін лишає запис у локальному маніфесті: що подано, куди, з якими
+  параметрами, чим закінчилось і чому впало.
+- Гроші видно до старту: прорахунок вартості, стеля витрат, залишки по бекендах
+  (`gpurunner balance`), і що зараз тарифікується (`gpurunner burn`).
+- Для довгих заходів на Vast є наглядач (`gpurunner htr supervise`): орендує
+  бокс, стежить за темпом, доганяє пропуски, звіряє повноту й гасить оренду сам.
+- Бакет S3 для цього не обов'язковий: `htr plan --transport box` везе кадри й
+  ваги на саму машину по `scp` і піднімає на ній крихітний склад, з якого їх
+  бере робота. Чекпоінти наглядач забирає додому сам — машина може вмерти.
+
+## 2. Установлення
+
+Потрібен Python 3.11+.
+
+⚠ На PyPI пакет зветься **`gpuhire`**, а команда в терміналі — `gpurunner`.
+Ім'я `gpurunner` на PyPI зайняте схожим проєктом (`gpu-runner`), і майданчик
+не дав його взяти; перейменовувати команду заради цього не стали.
+
+```
+pip install gpuhire                 # ядро + Kaggle
+pip install "gpuhire[modal]"        # + Modal
+pip install "gpuhire[vast,r2]"      # + Vast.ai і доставка даних через R2
+pip install "gpuhire[all]"          # modal, colab, vast, web, r2
+```
+
+`lightning`, `beam`, `saturn` ставляться поіменно: їхні SDK важкі й потрібні
+одиницям. Як модуль Нишпорки: `pip install "gpuhire[vast,r2]"` поруч із
+нею — Нишпорка знайде плагін сама.
+
+Поруч із Нишпоркою gpurunner стає її **бекендом оренди**: оголошує entry point
+`nyshporka.cloud`, і `nysh cloud` сам орендує бокс на Vast.ai, читає справу по
+SSH, забирає результат і гасить оренду. Від людини — лише ключ API
+(`gpurunner auth vast --key <КЛЮЧ>`) і баланс; SSH-ключ генерується сам, R2 не
+потрібен. Докладно — [`docs/nyshporka.md`](docs/nyshporka.md).
+
+З вихідного коду:
+
+```
+git clone https://github.com/SERGIUSH-UA/gpurunner && cd gpurunner
+uv sync --extra all
+uv run gpurunner --version
+```
+
+## 3. Перший прогін
+
+```
+gpurunner auth kaggle --verify        # обліковка на місці?
+gpurunner ls                          # які є job'и й бекенди
+gpurunner run net-probe -b kaggle     # найдешевша перевірка: чи є в кернелі мережа
+gpurunner watch <handle>              # чекати до кінця
+gpurunner fetch <handle> -o out/      # забрати вихід
+```
+
+`--dry-run` перевіряє параметри й показує код, який поїде на бекенд, нічого не
+подаючи. Параметри job'а — `-p ключ=значення` (значення розбирається як JSON,
+якщо виходить).
+
+🔴 **Vast тарифікує погодинно й не спиняється після завершення job'а.** Після
+`fetch` обов'язково `gpurunner cancel <handle>`; що зараз горить, показує
+`gpurunner burn`.
+
+## 4. Бекенди
+
+| бекенд | extra | обліковка | особливість |
+|---|---|---|---|
+| `kaggle` | — | `~/.kaggle/kaggle.json` або `KAGGLE_USERNAME` + `KAGGLE_KEY` | безкоштовна тижнева квота; вхід — Kaggle Dataset |
+| `modal` | `modal` | `~/.modal.toml` (`modal token new`) | посекундний білінг; дані — у томі Modal; локальний Python має бути 3.12 — як в образі |
+| `colab` | `colab` | OAuth-клієнт Google у теці конфігурації | нотбук треба запустити руками: Runtime → Run all |
+| `vast` | `vast` | `VAST_API_KEY` або файл `vast_api_key` | оренда боксу по SSH; тарифікація до `cancel` |
+| `lightning` | `lightning` | `LIGHTNING_USER_ID`, `LIGHTNING_API_KEY` | Studio + teamspace |
+| `beam` | `beam` | `BEAM_TOKEN` або `~/.beam/config.ini` | стеля витрат на прогін і на місяць |
+| `saturn` | `saturn` | `SATURN_TOKEN`, `SATURN_BASE_URL` | типи інстансів — `gpurunner saturn sizes` |
+
+`gpurunner auth <бекенд>` показує, де шукається обліковка й чого бракує;
+`--verify` робить пробний запит. Тека конфігурації — `%LOCALAPPDATA%\gpurunner`
+(Windows) або `~/.config/gpurunner`; перекривається `GPURUNNER_CONFIG_DIR`.
+Приклади файлів — у [`docs/config/`](docs/config/).
+
+## 5. Job'и
+
+Перелік з описами й бекендами — `gpurunner ls`; готові набори параметрів із
+прорахунком вартості — `gpurunner recipes <job>`.
+
+Загальні:
+
+| job | що робить |
+|---|---|
+| `net-probe` | чи є у віддаленому кернелі мережа |
+| `paddleocr` | PaddleOCR PP-OCRv5 по переліку PDF за посиланнями → txt і json по сторінках |
+| `vit_classifier`, `crop_verifier`, `dino_surname_verifier` | дотренування бінарного класифікатора зображень (ViT / DINOv2) і скоринг |
+| `yolo_spotter` | дотренування YOLO на пошук одного рукописного слова |
+| `churro`, `rukopys_ocr` | сторінкове читання історичних документів VLM-моделями |
+| `kraken_lines`, `trocr_lines` | сегментація сторінок на рядки й читання рядків |
+| `kraken_train`, `parseq_train` | трен моделей читання рядків (kraken, PARSeq) |
+| `htr_eval`, `htr_lines_eval`, `htr_page_bench`, `paddle_page_bench`, `spotter_page_bench` | бенчмарки читання рукопису |
+
+Потребує пакета `nyshporka`:
+
+| job | що робить |
+|---|---|
+| `htr_case` | прогін архівної справи раннером Нишпорки на орендованій карті; раннер і моделі приїжджають архівом ассетів, gpurunner доставляє їх на бокс і стежить |
+
+Команди `gpurunner htr …` (план, передполіт, наглядач, забір чекпоінтів,
+калібрування) обслуговують саме `htr_case`.
+
+## 6. Команди
+
+```
+run · status · watch · logs · fetch · cancel · sweep      життєвий цикл прогону
+ls · recipes · balance · burn · reconcile · dash           огляд, гроші, звірка
+auth <бекенд>                                              обліковки
+dataset push|files                                         Kaggle-датасети
+drive push|files                                           вхідні дані Colab у Google Drive
+vast offers|instances · saturn sizes                       ринок і типи машин
+boxes ls|explain|ban|star|prune|forget                     реєстр орендних боксів
+bg start|status|stop                                       довгі задачі у фоні
+htr plan|preflight|supervise|state|stop|quiesce|fetch-ckpt|calibrate|append
+```
+
+`gpurunner <команда> --help` — повний перелік прапорців.
+
+## 7. Реєстр боксів
+
+Кожна оренда на Vast лишає рядок «обіцяне поруч із виміряним»: яке залізо
+заявив хост і який темп воно дало. З цього складається вердикт машини, і
+наступний пошук оферти погані машини оминає, а добрі шукає адресно.
+
+Реєстр — дані користувача, а не пакета: у ньому ідентифікатори машин, ціни й
+назви власних прогонів. Лежить у `GPURUNNER_REPO_DATA_DIR`, без змінної — у
+`<тека даних>/registry`. Змінну варто спрямувати в теку власного
+git-репозиторію: тоді в дифі видно, коли й чому бокс став поганим.
+
+## 8. Для програм
+
+Інші програми кличуть gpurunner окремим процесом і читають `--json`: останній
+рядок stdout, що починається з `{`, — один об'єкт. Форма відповідей, перелік
+стабільних команд, схема `plan.json` і змінні оточення —
+[`docs/contract.md`](docs/contract.md).
+
+Другий шлях — плагін у тому самому інтерпретаторі: клас
+`gpurunner.plugins.nyshporka_cloud:VastRent` (entry point `nyshporka.cloud`)
+орендує й гасить бокс для конвеєра Нишпорки. Методи, форма `Box.meta` і
+необов'язкові `status / login / estimate` — [§6 контракту](docs/contract.md#6-плагін-nyshporkacloud).
+
+## 9. Розробка
+
+```
+uv sync --extra all
+uv run pytest
+uv run ruff check .
+uv run mypy src
+python tools/scan_private.py          # ворота проти приватних даних
+```
+
+Тести не ходять у мережу й не потребують обліковок. Порядок внесення змін і
+чекліст релізу — [`CONTRIBUTING.md`](CONTRIBUTING.md); про вразливості —
+[`SECURITY.md`](SECURITY.md).
+
+## 10. Ліцензія
+
+MIT — див. [`LICENSE`](LICENSE).