Nyshporka

Reads manuscripts. Brings back what it finds.

Download for Windows Install with a command

Free and open source (AGPL-3.0). Code on GitHub

▶ How to install it and where to start — video lessons

Ways to install

The same app, three ways. The installer is more convenient; the commands are for Linux and macOS, for those installing on a server, and for those more at home in a terminal.

Windows — a single file

no Python and no administrator rights needed

Run it, answer two questions, press “Install”. The installer brings its own interpreter and puts everything in your user profile.

nyshporka-setup.exe

⚠ “Windows protected your PC” — “More info” → “Run anyway”. This is how Windows greets every program that few people have downloaded yet. You can verify the file with the .sha256 next to the installer in the release.

Terminal — all systems

no Python and no administrator rights needed

One command on a clean machine. The script brings uv, and uv brings its own interpreter; no need to clone the repository.

Windows (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"

Linux and macOS

curl -LsSf https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/install/unix.sh | sh

🔴 When the script finishes, close the terminal window and open a new one: until then the nysh command won't be found in it. If it isn't found in the new one either, restart your computer.

Python or uv already installed

PyPI · Python 3.11+

The package installs from PyPI; GitHub isn't needed at all.

uv tool install "nyshporka[app,archives,htr]"   # or: pip install "nyshporka[app,archives,htr]"
nysh init                      # create a working folder
nysh doctor                    # check the machine
nysh serve                     # open the app in the browser

A light set, without torch (~2.5 GB less): uv tool install "nyshporka[app,archives]". Updates: nysh update --check.

To read manuscripts — two more steps

The reading models aren't included in the package on purpose: otherwise everyone who came just to browse the catalogue of files would pay for them in gigabytes. The steps are one-off and usually the assistant does them; the archive catalogues don't need them.

nysh htr install    # an environment for the reading models, once
nysh models get     # three reading models, ~130 MB
nysh doctor         # the “Рушії читання” (reading engines) check should turn green

How to connect an assistant, component sets and installer options — “Install and connect an assistant”.

What it looks like

The app opens in your browser but runs on your computer — even without the internet.

Viewer: the scan, the read text and the clipping of the line it was read from.

Gazetteer: where your village's documents are — across all fonds and denominations at once, before you have a single scan.

Search: fuzzy matches, with the file's reference code and how much has been checked.

Three reading models

nysh models get brings three models. Pysar and Diak read Cyrillic and can work together on the same file — then the text is combined from their voices. Skryba reads Latin script.

Pysar

main voice: chancery papers, parish registers, confession lists

Handles most Cyrillic files. When the handwriting is illegible, it relies on how such documents were usually written.

Diak

second voice: sticks to the pixels where the first one fills in the gaps

Reads the same script as Pysar, but stays closer to the strokes themselves. The two voices are compared: where they differ, it's worth looking at the folio.

Skryba

Latin script: notarial records and Catholic parish books

A separate script and separate material: Latin entries from notarial records and Catholic parish books, which the Cyrillic models don't handle.

How it works

1 Install Nyshporka and connect an AI assistant (agent) — Claude Desktop, Claude Code or Codex.
2 Tell the assistant in plain words who you are looking for: “here are scans of the Chechelnyk parish registers, find everyone named Kovalskyi”.
3 The assistant finds the files, reads the folios and looks for the surname.
4 You see what was found right on the scan, with the folio number, and decide for yourself whether it is your family or not.

What goes to Supriaha and what doesn't

Goes only with your consent

The read text and the file's metadata. A file of 3772 folios weighs 4–5 MB in a package.

Never goes

The scans themselves. Your notes, findings and tree. By default the app shares nothing: some of us paid for the photography.