How to read handwritten scans with AI
Finding the file is half the work: then come hundreds of folios of cursive, and the surname may be on any of them. Nyshporka (Ukrainian «Нишпорка») is a free, open application that reads handwriting with its own models on your computer, searches the text for a surname, village or word, and shows every find on the scan. An AI agent runs it: you say in plain words whom and where you are looking for, and the agent runs the steps itself. It is a separate project, not part of Predok.
What it does
- Where to look. A gazetteer of the Central State Historical Archive in Kyiv (TsDIAK: 4,566 settlements, 348 thousand files), the catalogue of the State Archive of Khmelnytskyi Oblast, an index of FamilySearch films (Moldova only so far). These work right after installation, with no scans and no reading models.
- Reads handwriting. Three models trained on 18th–19th century cursive: two for Cyrillic (Pysar and Diak read the same lines but make different mistakes) and Skryba for Latin script (notarial and Catholic parish books).
- Searches fuzzily. The machine confuses a quarter to a third of the letters, so the text it reads is for searching, not for quoting. The search finds a mangled surname too, and states how many files and folios were looked through: "nothing" without that number means nothing.
- Shows the evidence. Every line found comes as a clipping of the scan; you decide whether it is your ancestor.
- Takes what is already read. Supriaha is a shared bank of read files: if someone has already read the book, the text arrives in a minute instead of hours of reading.
- Assembles the result. Records go into a table for Excel, confirmed finds into a family history with a clipping for every fact, and the family history into a family website with a tree and a map.
In more detail: how it works and the FAQ.
What you need to install
No large language model is installed on the computer. The thinking is done by a cloud assistant under your subscription; only small handwriting-recognition models run locally.
| What | How much |
|---|---|
| Computer | Windows 10–11, macOS or Linux |
| An assistant that works with files on disk | Claude Desktop (Code tab, Claude Pro or Max subscription), Claude Code, or Codex (ChatGPT subscription) |
| Nyshporka | free; on Windows an ordinary installer with no Python and no admin rights, elsewhere one script |
| Disk space | about 5 GB, of which the reading models with their environment take 2.5 GB (the weights alone are about 225 MB); plus the scans (2–8 MB per folio) |
| Graphics card | not needed: about 2 minutes a page on an ordinary laptop, about 20 seconds with a graphics card |
| Installation time | 30–40 minutes together with the assistant, mostly downloading |
Step-by-step instructions without a terminal: install and connect the assistant. If you only need the catalogues, install the catalog set without the reading models.
A large file of several thousand folios takes a week on a laptop; on a rented machine (Ukrainian) it takes an hour or two for a dollar or two, with the price shown before renting.
Nyshporka does not work in a chat on a website (claude.ai, chatgpt.com, Predok's chat) or through a connector: it needs an assistant with access to the disk.
How Predok helps
Predok and Nyshporka complement each other: Predok knows which files exist and where their scans are, and Nyshporka reads the scans themselves. Both are installed in the same agent environment: the Predok plugin and Nyshporka side by side. The order of work:
- Predok: which parish the village belonged to at the date of the event, which files exist for those years, with call numbers and links to scans.
- Scans: the agent downloads from open sites (ARCHIUM, Wikimedia Commons) itself; from FamilySearch you save them. First check whether the file is already in Supriaha.
- Nyshporka reads the file and searches for the surname; you check the finds against the clippings.
- What is confirmed you propose to Predok with the call number and folio, so the next researcher does not read the same book again.
Example request: "Find in Predok the metric books of Olesko parish for 1880–1900 with links to scans, download them into Nyshporka and find all the Kahaniuks. Show the finds as clippings of the scans."
Limits
- The models read well the handwriting they were trained on; on other hands there are more mistakes. Check the first file of new material by eye.
- Breaking records into fields (dates, names, roles) is done by the assistant and costs subscription tokens — about 84 thousand per folio, so it is done for selected books.
- Reading takes only images (
jpg,png,tif,webp); a PDF is first split into pages. - Nyshporka does not download files from FamilySearch: that needs a browser sign-in.
- Licences: the code is AGPL-3.0; the model weights are CC BY-NC-SA 4.0 with a permission for paid research a person does themselves (details).