Нишпорка

Читання рукописних архівних справ і пошук прізвища в них — для генеалогів.

Комерційні OCR не читають скоропис XVIII–XIX ст., а платформи, які читають, платні й не мають моделей під матеріал українських, молдовських і польських архівів. Нишпорка закриває саме цю прогалину: беремо теку сканів із архіву й отримуємо текст, у якому можна шукати прізвище.

Стан: alpha. Каталоги, завантаження, читання рукопису, гортач, сховище прочитаного, пошук, браузерне обличчя й установлення працюють. Ваги моделей ще не викладені релізом — доти читати можна лише з власними вагами. Що саме не готове, у розділі «Чого ще немає» нижче, без замовчувань.

Установлення

На чистій машині — без Python і без прав адміністратора. Інсталятор приносить uv, uv приносить власний інтерпретатор:

# Windows
powershell -ExecutionPolicy Bypass -File install\windows.ps1

# Linux / macOS
sh install/unix.sh

Або звичайним способом, якщо Python уже є:

pip install 'nyshporka[app,archives,htr]'
nysh init                      # створити робочий простір
nysh doctor                    # перевірити те, що ламається тихо
nysh serve                     # відкрити застосунок у браузері

Де лежить дослідження

Простір — тека, у якій живуть скани, прочитане й звіти. Типово nysh init кладе її в Документи/Нишпорка (або поруч із домівкою, якщо ця тека синхронізується з хмарою: обхід справ став би мережевим і виглядав би як зависання).

nysh init D:/Дослідження          # обрати місце при створенні
export NYSHPORKA_WORKSPACE=D:/Дослідження   # закріпити для ВСІХ команд
nysh --workspace D:/Дослідження doctor      # разово, на один запуск

$env:NYSHPORKA_WORKSPACE = 'D:\Дослідження'   # PowerShell, на поточну сесію

Без змінної команди шукають файл nyshporka.toml угору від поточної теки — тож усередині простору нічого вказувати не треба. Куди дивиться застосунок зараз, каже nysh doctor: перевірка «Робочий простір» друкує корінь і джерело (env:…, marker, explicit).

Що саме ставимо

Нишпорку ставлять дуже різні люди, і показувати всім однакове — означає комусь брехати. nysh init питає, чим ви користуватиметесь; змінити відповідь можна будь-коли (nysh sections), нічого не перевстановлюючи.

powershell -ExecutionPolicy Bypass -File install\windows.ps1 -Preset catalog

NYSH_PRESET=catalog sh install/unix.sh

🔴 Вимкнена частина вимкнена всюди, а не лише в шапці: її дії відмовляють і в браузері, і в командному рядку, і в агента — з назвою секції та командою, якою її увімкнути. Напівстан («кнопки немає, але команда працює») тут гірший за відсутність: він читається як несправність.

catalog — єдиний набір без torch (~2.5 ГБ). Він точно описує найпершого відвідувача: сканів ще немає, відеокарти теж, а питання вже є — «де взагалі метрики мого села». Обидва вкладені зрізи відповідають на нього одразу після встановлення, тож це робочий набір, а не урізаний.

Типово ставиться CPU-збірка torch. Задача читання впирається в ядра процесора, не у відеокарту (виміряно: 92% часу CPU при завантаженні карти близько нуля), тож на CPU все працює — просто повільніше: ~2 хв на сторінку проти ~20 с. Прискорення відеокартою доставляється окремим кроком (nysh doctor підкаже яким), а не вимагається збіркою.

Що вже працює

Два зрізи їдуть разом із пакетом, тож nysh find "моє село" працює одразу після встановлення — ні сканів, ні відеокарти, ні обходу чужих сайтів:

• каталог ДАХмО — 9020 справ 47 фондів, роки 1648-2025;
• поаркушевий покажчик плівок — 62 412 записів, 1594 населені пункти: яке село на яких КАДРАХ якої плівки. Це найкоротша відповідь на «де метрики мого села», і вона не вимагає завантажити жодного байта сканів.

🔴 Зрізи старіють, тож кожна відповідь несе їхню дату й межі покриття (покажчик плівок сьогодні накриває лише Молдову — в інших регіонах дзеркала поаркушевого покажчика немає в принципі). Зібране на місці має пріоритет над вкладеним.

Каталоги й завантаження. Переглядачі архівів (ARCHIUM — обласні та центральні), дзеркало плівок FamilySearch і Wikimedia Commons — за спільним контрактом джерела: search / browse / manifest / fetch. Найцінніше в дзеркалі — поаркушевий покажчик плівки: він відповідає «де метрики мого села» без жодного завантаження. Найцінніше в Commons — повний файл: дзеркала обрізають великі справи в рази (25 МБ проти 771 МБ), і виглядає обрізане як нормальна копія.

nysh find "Ракулешты"                  # де взагалі є щось про село
nysh browse fsfilm moldova             # що лежить у регіоні
nysh get fsfilm "<плівка>" --out . --frames 6-10
nysh crawl archium                     # зібрати каталог справ для пошуку

Що взагалі існує у фонді. Окреме питання від «що вже оцифровано», і саме воно вирішує, чи має сенс замовляти документ в архіві. Складають відповідь збирачі реєстру опису:

nysh registry sources                                  # які збирачі є
nysh registry plan  duck --repo ДАВіО --fond 904       # скільки це коштуватиме
nysh registry collect archium --repo ЦДІАК --fond 224 --fond-id 198
nysh registry rate                                     # чи витримали темп

Приймач збирання — не число рядків. Позиційний розбір таблиці опису вже одного разу віддав 2944 справи з однаковим заголовком, і за кількістю це виглядало успіхом. Тому кожен запуск друкує, скільки рядків мають роки, аркуші й заголовок, і чого джерело не бачить: позиції «вільний номер» і «Справа вибула» лягають окремо — пущені в реєстр, вони стають фантомами в черзі, за якою замовляють документи.

🔴 Duck Inspector — безкоштовний волонтерський сервіс, і його ліміт (5 запитів на 10 с) міряється по клієнту, а не по процесу. Тому запити йдуть через чергу, спільну на всю машину: дві сесії з бездоганною паузою кожна дали б подвійний темп. nysh registry rate показує максимум у вікні за журналом фактичних відправок — не за наміром.

⚠ Зібрані джерела ще не зводяться в один реєстр опису: складати registry/*.tsv пакет уміє, зливати їх — поки ні.

Читання рукопису. nysh read <тека> або екран «Читання»: план (скільки кадрів, яке письмо, яка модель) показується ДО запуску, бо справа читається годинами. Модель обирається за письмом і за файлом бойових ваг — «найновіша» ≠ «найкраща». Другий рушій читає ті самі кропи: він помиляється ІНАКШЕ й витягує те, де перший підставив правдоподібне слово.

Гортач. Вирізка рядка з рамкою — щоб було видно, ЗВІДКИ взявся текст. Виявити ≠ перевірити: машина подає кандидата, вирішує око. Дефолт — рядок, бо сторінка коштує в десятки разів дорожче (виміряно: 15 КБ проти 1.1 МБ).

Своя тека стає справою. Скани, зняті в архіві чи прислані колегою, не мають шифри — а без ключа в них немає ні обліку прочитаного, ні місця в реєстрі, ні можливості послатись на знахідку. Екран «Завести справу» (або nysh case) приймає шифру в тих формах, якими її справді пишуть — ДАХмО 315-1-8433, ф.315 оп.1 спр.8433, Ф. 211 Оп. 3 Д. 140. Опис пишеться в теку: вона переїжджає між дисками й потрапляє до колег, і опис їде з нею. Кнопка ✏ у переліку відкриває записане для правки — щоб змінити одне слово, а не передруковувати все наосліп.

Скани можуть лежати де завгодно. Не обов'язково всередині простору: тека на зовнішньому диску чи в мережі береться під облік там, де лежить, — позначкою у формі (або полем case_roots у nyshporka.toml). Файли не переносяться. Розширення зони завжди явне: застосунок ніколи не бере теку сам, бо шлях у гортач приходить із запиту браузера, і «дозволено все» тут коштувало б надто дорого. Тека всередині простору лишається записаною відносним шляхом — щоб простір можна було перенести на інший диск чи віддати колезі.

Зразкова справа в комплекті. nysh sample (або кнопка на екрані «Перевірити цю машину») кладе в простір три аркуші справи ДАХмО ф.315 оп.1 спр.159 — про висвячення в диякони, 1821-1822 — разом із готовим машинним декодом двома голосами. Це відповідь на перше питання після встановлення: клацнувши рядок у гортачі, видно, ЗВІДКИ взявся текст, а пошук по декоду знаходить у ньому прізвище. Прочитати ці аркуші заново поки нічим — ваги ще не викладені, — але весь ланцюг після читання можна пройти до того, як вкладати власні три тисячі сканів.

Довідники окремим комплектом. Газетир зведеного каталогу ЦДІАК (4566 поселень, 348 408 справ) і реєстри опису чотирьох фондів ставляться окремо від програми — дані оновлюються не тоді, коли код:

nysh catalog install --from <завантажений zip>   # releases
nysh geog find "Липовеньке"      # де взагалі є документи цього села

Газетир відповідає на питання, з якого починається пошук: які взагалі метрики цього поселення вціліли і що з них уже у вас. Шукає обома мовами й латинкою — Miastkowka знаходить те саме, що й кирилицею; раніше такий запит давав нуль, а це найгірший вид нуля, бо його читають як «такого села немає». І показує три конфесії окремо: метрики православної громади, костелу й рабинату лежать у різних фондах, тож шукати лише в православному розділі означає не бачити решти.

Сховище прочитаного. Облік того, що вже переглянуто оком — щоб наступна сесія не гортала ті самі аркуші вдруге. Пошук по прочитаному: у машинному декоді, у виписаних прізвищах, в учасниках розібраних записів.

Реєстр справ. Що є на диску, що прочитано машиною, що прошукано, що бачило око — з попередженням, коли зріз відстав від джерел.

Три обличчя, одне ядро. Браузерна консоль, командний рядок і MCP-сервер для Claude Code / Codex — тонкі обгортки навколо одного реєстру операцій. Коли правда одна, вони не можуть розійтись у відповідях; це перевіряється тестом, а не домовленістю. Працювати з агентом не обов'язково — без нього застосунок повний.

Якщо агент таки береться до роботи, він читає AGENTS.md і docs/agents/: що вміє, чого не вміє, як читати нуль, де межа, за якою вирішує людина, і як агенти вже помилялися на цьому матеріалі. Причина окремої теки проста — у перелік інструментів іде однорядковий підпис операції, а не її докстрінг, тож усе, чому саме так, довелось написати окремо.

🔴 Нуль мусить щось означати

Це головне правило проєкту, і воно вбудоване в код, а не в інструкцію.

Порожній результат пошуку — найдорожча відповідь у генеалогії: «немає» закриває напрям назавжди. Тому джерело, яке не може шукати (каталог не зібраний, дерево регіону не завантажене), не додає нуль до суми — воно відмовляється відповідати й каже, чого бракує:

⚠ archium: каталог справ ще не зібрано, тож шукати нема де — і нуль тут нічого
  не означав би: вбудований пошук сайту індексує лише назви фондів і описів.
⚠ жодне джерело не змогло шукати — цей нуль НІЧОГО не означає

Кожна відповідь несе coverage: де саме шукали. Кожне попередження їде полем конверта, а не лише в лозі, — інакше саме той читач, який не помітить нічого поза даними (агент), лишався б без попередження.

Чого ще немає

Чесно, без замовчувань:

• Ваги моделей не викладені. nysh models get знає, що качати, але реліз із вагами ще не складено; доти пак без sha256 не приймається взагалі — модель, про цілість якої нічого не відомо, читатиме справу годинами й видасть текст, що не відрізняється від поганого почерку. Власні ваги в <простір>/data/spotter/models працюють уже зараз.
• Гортач бачить 86% прогонів. Переміряно на 614 прогонах: готовий скан у 519, рендер зі справи-PDF ще у 7. Решта 88 — здебільшого збірки, у яких теки однієї справи немає в принципі, і прогони, чия тека лишилась на чужій машині; другі лікуються nysh cases bind. Для тих, що видно, аркуш тепер показується правильно й на рендері теж — раніше кроп рядка там з'їжджав.
• Покажчик плівок накриває лише Молдову. Не наша межа: в інших регіонах дзеркала folder_meta це голий підпис теки, поаркушевого переліку там немає.
• Описи є не для всіх фондів. Готові зрізи чотирьох фондів приходять довідниками (нижче); решту довелося б збирати самому, а збирачів у цьому пакеті немає.
• Зразок не читається заново — лише все після читання. Три аркуші справи ДАХмО 315-1-159 їдуть у пакеті вже з машинним декодом, тож гортач, пошук і реєстр працюють на них одразу; а прогнати по них САМЕ ЧИТАННЯ нічим, доки немає ваг. Це та сама межа, що й у першому пункті, і зникне вона разом із ним.
• Кандидатів нема кому подавати. Людський gate nysh review працює, але пишуть у нього fetcher'и чужих сайтів, яких у цій версії немає (питання їхніх умов використання в роздаваному продукті). На щойно створеному просторі черга порожня — це стан, а не поламка.

Розробка

uv sync --group dev
uv run pytest
uv run ruff check . && uv run mypy
pre-commit install            # ворота проти приватних даних

🔒 Ворота проти приватних даних

Пакет виділяється з приватного дослідницького репозиторію однієї родини, і головна небезпека тут — не зловмисник, а випадковість: один git add -A, скопійований для прикладу шматок коду з реальним ідентифікатором особи, шлях із машини автора в докстрінгу.

python tools/scan_private.py             # робоче дерево
python tools/scan_private.py --staged    # індекс (стоїть у pre-commit)
python tools/scan_private.py --history   # уся історія, перед першим push

Перевірка стоїть до коміту, бо git не забуває: файл, доданий і видалений наступним комітом, лишається в історії назавжди, а прибрати його означає переписати вже опубліковану гілку.

Ліцензія

AGPL-3.0-or-later.

Причина конкретна: конвеєр спирається на ultralytics і PyMuPDF, обидва під AGPL-3.0. Решта стеку читання чиста (kraken, PARSeq, timm, torch — Apache/BSD), тож вибір був між «викинути дві залежності» і «прийняти AGPL». Прийняли AGPL: код усе одно відкритий, а копілефт тут радше плюс.

⚠ Пакет strhub містить підмодуль models/abinet під non-commercial ліцензією USTC. Нишпорка використовує з нього лише PARSeq (Apache-2.0).