Metadata-Version: 2.5
Name: nyshporka
Version: 0.17.0
Summary: Робоче середовище для ШІ-агента в архівній генеалогії: читання рукописних справ і пошук прізвища в них
Project-URL: Homepage, https://github.com/SERGIUSH-UA/nyshporka
Project-URL: Source, https://github.com/SERGIUSH-UA/nyshporka
Project-URL: Issues, https://github.com/SERGIUSH-UA/nyshporka/issues
Project-URL: Changelog, https://github.com/SERGIUSH-UA/nyshporka/blob/main/CHANGELOG.md
Author: Serhii Dalishchynskyi
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: archives,genealogy,handwriting,htr,kraken,ocr,parseq
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
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 :: Image Recognition
Classifier: Topic :: Sociology :: Genealogy
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: loguru>=0.7
Requires-Dist: pillow>=10.4
Requires-Dist: platformdirs>=4.3
Requires-Dist: psutil>=6.0
Requires-Dist: pydantic-settings>=2.5
Requires-Dist: pydantic>=2.9
Requires-Dist: pypdfium2>=4.30
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml>=6
Requires-Dist: rapidfuzz>=3.10
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Requires-Dist: unidecode>=1.3
Provides-Extra: agent
Requires-Dist: anyio>=4.0; extra == 'agent'
Requires-Dist: mcp<2,>=1.2; extra == 'agent'
Provides-Extra: all
Requires-Dist: aiolimiter>=1.1; extra == 'all'
Requires-Dist: aiosqlite>=0.20; extra == 'all'
Requires-Dist: anyio>=4.0; extra == 'all'
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: curl-cffi>=0.7; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: httpx[socks]>=0.27; extra == 'all'
Requires-Dist: keyring>=25; extra == 'all'
Requires-Dist: lxml>=5.3; extra == 'all'
Requires-Dist: mcp<2,>=1.2; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: paramiko>=3.4; extra == 'all'
Requires-Dist: pdfplumber>=0.11; extra == 'all'
Requires-Dist: selectolax>=0.3.21; extra == 'all'
Requires-Dist: tenacity>=9; extra == 'all'
Requires-Dist: timm>=1.0; (platform_system != 'Darwin' or platform_machine != 'x86_64') and extra == 'all'
Requires-Dist: torch>=2.2; (platform_system != 'Darwin' or platform_machine != 'x86_64') and extra == 'all'
Requires-Dist: torchvision>=0.20; (platform_system != 'Darwin' or platform_machine != 'x86_64') and extra == 'all'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'all'
Provides-Extra: app
Requires-Dist: anyio>=4.0; extra == 'app'
Requires-Dist: fastapi>=0.115; extra == 'app'
Requires-Dist: mcp<2,>=1.2; extra == 'app'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'app'
Provides-Extra: archives
Requires-Dist: aiolimiter>=1.1; extra == 'archives'
Requires-Dist: aiosqlite>=0.20; extra == 'archives'
Requires-Dist: httpx[socks]>=0.27; extra == 'archives'
Requires-Dist: keyring>=25; extra == 'archives'
Requires-Dist: lxml>=5.3; extra == 'archives'
Requires-Dist: pdfplumber>=0.11; extra == 'archives'
Requires-Dist: selectolax>=0.3.21; extra == 'archives'
Requires-Dist: tenacity>=9; extra == 'archives'
Provides-Extra: cfshield
Requires-Dist: curl-cffi>=0.7; extra == 'cfshield'
Provides-Extra: cloud
Requires-Dist: boto3>=1.34; extra == 'cloud'
Requires-Dist: paramiko>=3.4; extra == 'cloud'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Provides-Extra: htr
Requires-Dist: timm>=1.0; (platform_system != 'Darwin' or platform_machine != 'x86_64') and extra == 'htr'
Requires-Dist: torch>=2.2; (platform_system != 'Darwin' or platform_machine != 'x86_64') and extra == 'htr'
Requires-Dist: torchvision>=0.20; (platform_system != 'Darwin' or platform_machine != 'x86_64') and extra == 'htr'
Provides-Extra: ocr
Requires-Dist: paddleocr>=3.5; extra == 'ocr'
Provides-Extra: rent
Requires-Dist: gpuhire[r2,vast]>=0.2; extra == 'rent'
Provides-Extra: train
Requires-Dist: boto3>=1.34; extra == 'train'
Requires-Dist: paramiko>=3.4; extra == 'train'
Provides-Extra: xlsx
Requires-Dist: openpyxl>=3.1; extra == 'xlsx'
Description-Content-Type: text/markdown

<p align="center">
  <img alt="Нишпорка"
       src="https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/src/nyshporka/brand/data/assets/mark.png"
       width="132" height="132">
</p>

<h1 align="center">Нишпорка</h1>

<p align="center"><em>Читає рукопис. Приносить знайдене.</em></p>

<p align="center">
  <a href="https://pypi.org/project/nyshporka/"><img alt="PyPI"
     src="https://img.shields.io/pypi/v/nyshporka"></a>
  <a href="https://github.com/SERGIUSH-UA/nyshporka/actions/workflows/ci.yml"><img alt="CI"
     src="https://github.com/SERGIUSH-UA/nyshporka/actions/workflows/ci.yml/badge.svg"></a>
  <img alt="Python" src="https://img.shields.io/pypi/pyversions/nyshporka">
  <img alt="Ліцензія" src="https://img.shields.io/badge/license-AGPL--3.0-informational">
</p>

**Нишпорка — робоче середовище для ШІ-агента в архівній генеалогії.** Вона дає
агентові руки: прочитати рукописну справу XVIII–XIX ст., знайти в прочитаному
прізвище, дістати вирізку рядка зі скану, зібрати реєстр опису фонду, записати
переглянуте так, щоб наступна сесія не переробляла те саме.

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

Чат на сайті цього не вміє: у нього немає доступу до вашого диска. Тому
Нишпорка не сервіс і не передплата, а пакет, який ви ставите поруч зі своїм
агентом — **Claude Code, Claude Desktop або Codex**. Усе лишається на вашій
машині.

<p align="center">
  <a href="https://sergiush-ua.github.io/nyshporka/agent/"><b>🤖 Підключити агента</b></a>
  &nbsp;·&nbsp;
  <a href="https://github.com/SERGIUSH-UA/nyshporka/releases/latest/download/nyshporka-setup.exe">⬇ Завантажити для Windows</a>
  &nbsp;·&nbsp;
  <a href="https://sergiush-ua.github.io/nyshporka/start/">поставив — що далі</a>
</p>

## Що дістає агент

* **122 операції з описом і схемою.** `nysh op <ім'я> --describe` віддає
  аргументи й повний докстрінг, нічого не виконуючи; `nysh op <ім'я>` виконує.
  Через це MCP не обов'язковий — агентові з терміналом досить самої команди.
* **18 MCP-tool'ів** — `nysh mcp install` прописує сервер у `.mcp.json`
  проєкту. Перелік навмисно вужчий за реєстр операцій: у нього є стеля, за
  якою модель перестає читати описи й починає вгадувати.
* **11 скілів — готових процедур під задачу** (`nysh skills install`): як
  прочитати справу на слабкій машині, як шукати прізвище так, щоб нуль щось
  означав, куди копати далі, як прийняти куплену зйомку, як дотренувати модель
  на своєму почерку.
* **Правила, а не поради** — [`AGENTS.md`](AGENTS.md) і
  [для агентів](https://sergiush-ua.github.io/nyshporka/agents/first-session/):
  як читати нуль, чому «не наш рід» вирішує людина, і як агенти вже помилялися
  на цьому матеріалі, з цінами.
* **Три обличчя, одне ядро.** Браузерна консоль, командний рядок і MCP —
  тонкі обгортки навколо одного реєстру операцій, тож вони не можуть розійтись
  у відповідях; це перевіряється тестом, а не домовленістю.

Ціна помилки тут інша, ніж у програмуванні, і середовище побудоване саме під
неї: хибне «немає» закриває напрям пошуку назавжди, а хибне «є» йде в родовід і
публікується як факт.

## Що агент зробить вашими сканами

* **Знайде, де лежать документи вашого села** — газетир ЦДІАК (4566 поселень,
  348 408 справ), поаркушевий покажчик плівок, каталог ДАХмО, церкви ~1772.
* **Прочитає рукопис** трьома рушіями: `[П]` **Писар** (кирилиця, головний
  голос), `[Д]` **Дяк** (кирилиця, другий голос — тримається пікселів там, де
  перший додумує), `[С]` **Скриба** (латинка: нотаріат і костельні книги).
* **Покаже, звідки взявся текст** — вирізка рядка з рамкою, сторінка, два
  голоси поруч.
* **Шукатиме прізвище** в прочитаному, у виписаних іменах і в учасниках
  записів.
* **Вестиме облік** переглянутого оком, щоб наступна сесія не гортала ті самі
  аркуші вдруге.
* **Віддасть таблицею** — розібрані акти в Ексель: фільтрувати роками, селом,
  станом і прізвищем.

Докладно, з межами кожного джерела — [**що вже
працює**](https://sergiush-ua.github.io/nyshporka/features/).

## Як це виглядає

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

**Видно, звідки взявся текст.** Клацнувши рядок, ви бачите його вирізку з
аркуша — у тому вигляді, у якому його бачив рушій.

<img alt="Гортач: скан із рамками рядків, машинний текст і вирізка обраного рядка"
     src="https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/docs/assets/screens/gortach.jpg">

**Де взагалі метрики мого села.** Газетир і покажчик плівок їдуть разом із
пакетом і відповідають одразу після встановлення — без сканів, без відеокарти,
без обходу чужих сайтів.

<img alt="Газетир: пошук села по всіх фондах і конфесіях одразу"
     src="https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/docs/assets/screens/gazetyr.png">

**Видно, скільки перевірено.** Пошук шукає нечітко, бо машина плутає літери
всередині слова. А під знахідками написано, скільки справ і сторінок було
переглянуто — щоб «нічого не знайшлось» не означало «просто ніде не шукали».

<img alt="Пошук: нечіткі збіги з оцінкою, шифром справи й покриттям пошуку"
     src="https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/docs/assets/screens/poshuk.png">

## Поставити

🤖 **Ставить агент?** Дайте йому одне посилання — [`AGENTS.md`](https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/AGENTS.md).
Там і встановлення, і перші кроки, і межі, за якими вирішує людина.

👤 **Ставите самі, без термінала?** Покрокова інструкція — три програми в
правильному порядку й один готовий запит —
[**«Підключити агента»**](https://sergiush-ua.github.io/nyshporka/agent/).

**Windows.** [⬇ Завантажити інсталятор][setup] — запустити, відповісти на два
питання, натиснути «Встановити». Python, прав адміністратора й термінала не
треба.

⚠ «Windows захистив ваш ПК» — «Докладніше» → «Виконати в будь-якому разі». Так
Windows зустрічає кожну програму, яку ще мало хто завантажував.

**Термінал, будь-яка система.** На чистій машині, без Python і без прав
адміністратора:

```powershell
irm https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/install/windows.ps1 -OutFile "$env:TEMP\nysh-install.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\nysh-install.ps1"
```
```sh
curl -LsSf https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/install/unix.sh | sh
```

🔴 Коли скрипт завершить роботу — закрийте вікно термінала й **відкрийте нове**:
доти команда `nysh` у ньому не знайдеться. Якщо й у новому вікні не знаходиться —
**перезапустіть комп'ютер**. (Тим, хто ставив інсталятором, це не потрібно:
ярлики працюють одразу.)

**Якщо Python або `uv` уже є:**

```bash
uv tool install "nyshporka[app,archives,htr]"   # або: pip install …
nysh init                      # створити робочий простір
nysh doctor                    # перевірити те, що ламається тихо
nysh mcp install               # прописати сервер агентові
nysh skills install            # покласти скіли туди, де їх бачить агент
```

🔴 **Щоб читати рукопис — ще два разові кроки.** Самі рушії й навчені моделі в
пакет не входять навмисно: інакше кожен, хто прийшов лише подивитись каталог
справ, платив би за них гігабайтами.

```bash
nysh htr install    # середовище рушіїв: kraken і PARSeq
nysh models get     # ваги трьох моделей, ~130 МБ
```

Каталогам, газетиру й пошуку по описах вони не потрібні — ті працюють одразу.

На робочій машині розробника інсталятор нічого не переставляє; `--dry-run`
показує, що буде зроблено, а `NYSH_NO_MODIFY_PATH=1` не чіпає PATH зовсім.
Важелі, набори частин, деінсталяція й те, де живе дослідження, —
[**встановлення докладно**](https://sergiush-ua.github.io/nyshporka/install/).

## Стан: alpha

Каталоги, завантаження, читання рукопису, гортач, сховище прочитаного, пошук,
браузерне обличчя й установлення працюють. Скани ви приносите самі; розбір
актів у поля робить ваш агент і вашим коштом — пакет дає нарізку, контракт,
валідацію й чексуми повноти, але сам не читає; а моделі читають добре той почерк, на якому
вчились, — на іншому матеріалі якість не міряна. Повний перелік того, чого ще немає, без замовчувань —
[**межі**](https://sergiush-ua.github.io/nyshporka/limits/).

## Далі

| | |
|---|---|
| підключити агента без термінала | [Підключити агента](https://sergiush-ua.github.io/nyshporka/agent/) |
| перша сесія агента, приймачі кроків | [Для агентів](https://sergiush-ua.github.io/nyshporka/agents/first-session/) |
| поставив — що робити першим | [Поставив. Що далі?](https://sergiush-ua.github.io/nyshporka/start/) |
| питання першого тижня | [Часті питання](https://sergiush-ua.github.io/nyshporka/faq/) |
| який екран на яке питання відповідає | [Карта екранів](https://sergiush-ua.github.io/nyshporka/screens/) |
| навчити Писаря своєму почерку | [Трен](https://sergiush-ua.github.io/nyshporka/train/) |
| прочитати справу на орендованій машині | [Хмара](https://sergiush-ua.github.io/nyshporka/cloud/) |
| що змінилось у версіях | [Що нового](https://sergiush-ua.github.io/nyshporka/whats-new/) |

## Приватність, ліцензія, участь

Телеметрії немає, облікових записів немає, дослідження нікуди не
вивантажується, а в мережу застосунок ходить лише тоді, коли його про це
попросили командою — [`PRIVACY.md`](PRIVACY.md).

Код — [AGPL-3.0-or-later](LICENSE), ваги моделей — окремо, під
[CC BY-SA 4.0](LICENSE-MODELS.md). Чому саме так, як підписується інсталятор і
що звіряти при завантаженні —
[підписування й ліцензії](https://sergiush-ua.github.io/nyshporka/signing/).

Знайшли ваду або хочете допомогти — [`CONTRIBUTING.md`](CONTRIBUTING.md) і
[Issues](https://github.com/SERGIUSH-UA/nyshporka/issues).

[setup]: https://github.com/SERGIUSH-UA/nyshporka/releases/latest/download/nyshporka-setup.exe
