Skip to main content
Glama
README.md
# RetroRAG

A Windows app (initially) for building a **retrieval (RAG) library of retro computer & console documentation** that Claude
and other AI systems (including locally hosted ones such as Unsloth Studio, Ollama, LM Studio) can search.

- Organise by **system** (C64, Amiga 500, ZX Spectrum, NES…) and **category**: user guides, programming reference,
  schematics, pinouts, chip datasheets, service & repair, books & magazines, emulator source, firmware & ROMs,
  disk & tape images.
- Add **PDF, GIF, JPG, PNG, TIFF, BMP, TXT, MD, HTML, RTF, Word (DOC/DOCX), Excel (XLS/XLSX), source code, ROMs, disk/tape images, ZIPs**, or whole folders
  (e.g. an emulator's source tree). Drag & drop onto a system or category.
- **OCR** (Tesseract) turns scans into editable Markdown. Words below a confidence threshold are marked
  `{?w0rd|42?}` so you can find and fix them.
- **Proofreading editor**: scan on the left, text on the right. The current line and word are highlighted on the scan.
- **Binary files get an "info card"**: CRC32/MD5/SHA1, format, D64 directory listing, ZX TAP/TZX headers, Amiga ADF
  volume name, iNES/Game Boy/Mega Drive headers, and embedded text strings from ROMs. An AI can then answer
  "what's on this disk?" or "which Kickstart is this?".
- **Hybrid search**: keyword (BM25, with hex-address normalisation so `$D020`, `0xD020` and `D020h` all match)
  plus semantic (embeddings), merged by rank fusion.
- **Connect AI**: MCP for Claude Desktop / Claude Code (stdio); MCP over HTTP for Unsloth Studio, LM Studio,
  Open WebUI, Cursor and others; a REST API with OpenAPI spec; export as a Markdown corpus or JSONL.
- **Portable**: the library is a self-contained folder using relative paths, and there's a portable mode plus a
  standalone `.exe` build.

---

## Install on a PC

### Option A: from source (needs Python 3.10+)
1. Copy this folder to the PC, but not the `.venv` folder: virtual environments only work on the PC that made them.
2. Run **`setup.bat`**. It creates `.venv`, installs packages (including the built-in embedder), checks
   for Tesseract, and asks whether to use portable mode.
3. Start the app with **`RetroRAG.bat`**.

### Option B: standalone build (no Python needed on the target PC)
Run **`build_exe.bat`** on any PC that has the source set up. It produces `dist\RetroRAG\` containing:
- `RetroRAG.exe`: the app.
- `retrorag-cli.exe`: the console version, used by Claude Desktop / Claude Code and for scripting.
- `portable.flag`: settings and the default library live inside the folder.
- Optionally a bundled `Tesseract-OCR\` folder, so OCR works without installing anything.

Copy or zip `dist\RetroRAG` to any Windows 10/11 PC or a USB drive and run `RetroRAG.exe`.

### Tesseract OCR
`winget install UB-Mannheim.TesseractOCR`. You can also set the path in Settings → OCR, or put a `Tesseract-OCR`
folder next to the app. For other languages, add them in the Tesseract installer and set e.g. `eng+deu` in Settings.

---

## Look and feel
Windows 11-style light and dark themes using the Segoe Fluent icon set. *View → Theme*: Follow Windows
(the default, which switches with your Windows setting), Light, Dark or **Retro**.

**Retro** turns the app into a monochrome CRT:
- Everything is drawn in an 8-bit pixel font, with simulated scan lines and a screen vignette.
- Scans are shown as glowing phosphor on a dark screen, and low-confidence words appear in inverse video.
- *Settings → Appearance* picks the phosphor (green PET, amber or white), turns scan lines on or off, and
  can use a different font file.
- The built-in font, *RetroRAG Phosphor*, is an original design rather than a copy of any machine's
  character ROM. To use a PET / VIC-20 style font you've downloaded instead (for example Kreative Software's
  free "Pet Me" family), choose its `.ttf` there.
- The font is generated by `tools/make_pixel_font.py`, which needs `pip install fonttools`. Edit the glyphs
  there and re-run it to change the font.

## Workflow

1. **➕ System**: name, aliases (`C64, CBM 64`, used for search filters), manufacturer, year, CPU, notes.
2. **Add files / Add folder** (or drag & drop). Choose the category. *Copy into library* (the default) keeps the
   library self-contained. For folders you can choose which file types to include; for emulator source the
   default is text and code only.
   - **Variants:** a system can be a variant of another (*Variant of* in the system dialog, *Add variant…* on a system's right-click menu, or drag one system onto another). Put shared documentation on the family (e.g. *ZX Spectrum*) and only the extra material on each variant (*48K*, *128K*, *+3*). Variants can nest, e.g. *ZX Spectrum → 128K → +3*.
     - **Searching a variant** (in Search test or by the AI) returns its own documents plus everything common from its family. Searching the family returns all of them.
     - **Removing a family** keeps its variants; they move up a level.
   - **Moving a misfiled document:** right-click → *Move to system…*, drag it onto another system or category in the tree, or change **System** on the Document tab and click *Save details*. The file moves on disk together with its OCR text, corrections and links.
3. **🔤 Run OCR** on scanned PDFs and images. PDFs with a text layer are extracted directly; only pages without
   text are OCR'd, and *Force OCR* re-does every page.
4. **Proofread** (double-click a document):

   | Key | Action |
   |---|---|
   | **F3** / Shift+F3 | next / previous flagged word, which is selected so you can type the fix over it |
   | **Ctrl+Enter** | accept the word at the cursor (removes the marker) and jump to the next one |
   | **Ctrl+Del** | delete the flagged word at the cursor (junk from a drawing) and jump to the next one |
   | Ctrl+S | save |
   | Ctrl+H | find / replace (with regex). Good for systematic errors, e.g. `0` → `O` in words |
   | Ctrl+wheel, Ctrl+= / Ctrl+- | zoom the scan |
   | click on the scan | jump to that line in the text |

   - **Seeing what to fix:** the magnifier strip above the text shows the current line from the scan, enlarged, with the word boxed. On the page, the word flashes when you move to it, and *Spotlight* dims everything except the current line.
   - **Flagged "words" in drawings:** in schematics, Tesseract sometimes reads part of the drawing (a chip outline, a wire, a pin box) as a short word, e.g. `{?Fs|46?}` with a box covering a whole IC. That's not text, so delete it: **Ctrl+Del** removes the flagged word at the cursor and jumps to the next one. *More → Remove drawing shapes read as words* clears a whole page. New OCR runs skip these shapes automatically (Settings → OCR → *Ignore drawing shapes…*). The rule of thumb: if it's real text, fix it and press Ctrl+Enter; if it's part of a drawing, Ctrl+Del.
   - **Diagram noise:** *More → Delete garbage lines on this page* removes lines that are mostly OCR junk from diagrams and schematics. Ctrl+Z undoes it.
   - A **●** on the editor tab means unsaved changes. *Save* (Ctrl+S) shows **✓ Saved**.
   - **Re-OCR page** retries one page with another layout mode (*11 - Sparse text* suits schematics and pinouts)
     or another cleanup level.
   - **Mark reviewed** records that the text is proofread.
   - The confidence threshold (default 70%) is in Settings → OCR.
   - **Preview pane** (Document tab, right of the form). Scans with OCR or extracted text switch between
     **Original** (the page image, with page navigation) and **Processed** (the text the AI sees, flagged words
     highlighted). Plain text, source files and pictures not yet OCR'd show the original only. There's no preview
     for firmware/ROMs, disk and tape images, or files inside an emulator or firmware source tree.
   - **Related documents** (Document tab). Link a document to others with **Link…**. The available link
     types are: related to, pinout / schematic for, datasheet for, implements (source code), errata for,
     newer revision of, and part / chapter of. You can add a note to any link.
   - **Suggest links** proposes links for one document, and *Index → Suggest links across library…* proposes
     them for everything. Suggestions come from shared chip names and part numbers (SID, 6581, Z80…),
     register addresses (`$D400` and `54272` count as the same), and very similar content. Tick the ones
     to keep; dismissed suggestions don't come back.
   - Links matter most for documents search can't connect on its own: schematics and pinouts with little
     text (give them notes and tags too), emulator source vs. prose manuals, and errata or newer revisions.
5. **⚙ Build index** (F5). This runs automatically after changes unless you turn it off in the Index menu.
6. Try queries in **Search test**. You see exactly what the AI receives.
7. **🔌 Connect AI** shows ready-to-copy settings for this PC.

**Marker format.** `{?word|NN?}` means Tesseract read *word* with *NN*% confidence. Markers are always
stripped before indexing or export, so a missed one never pollutes the RAG. Each scan also gets a `.ocr.json`
sidecar holding every word's position on the page, which the editor uses for highlighting.

**Scan cleanup.** *Auto* (the default) OCRs each page as-is. If mean confidence is below 80%, it retries with
a strong median denoise and keeps the better result. This helps a lot with speckled photocopies.

---

## Connecting AI systems

Start the HTTP servers with **▶ Start servers** in the toolbar. You can make them start with the app
(AI menu), or run them without the GUI: `retrorag-cli api`.

| Client | How |
|---|---|
| **Claude Desktop** | Connect AI → *Add to Claude Desktop* (edits `claude_desktop_config.json` and keeps a `.bak`), then restart Claude. |
| **Claude Code** | Connect AI → copy the `claude mcp add retrorag …` command. |
| **Unsloth Studio** | Chat → MCP → *Add custom MCP*: URL `http://127.0.0.1:8766/mcp` (add header `Authorization: Bearer <token>` if you set one). Turn on *Use MCP Servers*. |
| LM Studio, Open WebUI, Cursor, Continue, Jan… | MCP over HTTP: `http://127.0.0.1:8766/mcp` |
| Open WebUI (OpenAPI tools), scripts | REST: `http://127.0.0.1:8765/search?q=...&system=C64`, docs at `/docs`, spec at `/openapi.json` |
| Anything else / offline | Export → Markdown corpus (YAML front matter per doc) or JSONL chunks |

MCP tools: `search_docs(query, system?, category?, limit, mode)`, `list_systems`, `list_documents`,
`read_document(doc_id, page_from?, page_to?)`, `get_related(doc_id)`, `get_context(chunk_id)`.

Each search hit carries a short `related` list (title, relationship, doc id), so the AI can tell the SID
chapter has a datasheet, a pinout and an emulator implementation, and fetch them only if needed.
Links also appear in each document's indexed header, in `read_document` output, at
`/documents/{id}/related` in the REST API, and in the Markdown export's front matter.

**AI on a different PC** (e.g. Unsloth on a GPU box): Settings → Servers → *Listen on* `0.0.0.0`, click
*Generate* for an access token, restart the servers, and use this PC's IP address in the URL.

### Embeddings
RetroRAG embeds text **itself by default**, so no Ollama, Unsloth Studio or other AI server is needed.

- **Built-in nomic-embed-text** (the default). This is the same model Ollama serves, run inside RetroRAG on
  your CPU (ONNX Runtime) on Windows, macOS, Linux and Raspberry Pi.
  - The model (137 MB) downloads once, the first time you build an index. After that it works offline.
  - To prepare a machine that will be offline, run `retrorag-cli download-model`. The standalone builds
    (`build_exe.bat`, `build_app.sh`) include the model automatically.
- Other presets in Settings → Embeddings, for when you'd rather use a server:
  - **Built-in bge-small:** 34 MB, about 3× faster, but noticeably less accurate on paraphrased questions.
  - **Ollama:** nomic-embed-text, mxbai-embed-large or embeddinggemma. Run `ollama pull <model>` first.
  - **Unsloth Studio:** OpenAI-compatible `/v1/embeddings` at `http://localhost:8888/v1`, model `default`.
    Create an API key in Studio (Settings → API).
  - **LM Studio** or a **llama.cpp server:** any OpenAI-compatible endpoint.
  - **None:** keyword search only. This still works well for register names and addresses.
- If a library is set to Ollama but Ollama isn't running and nothing has been embedded yet, RetroRAG switches
  that library to the built-in model automatically, rather than quietly falling back to keyword-only search.

Benchmark on a laptop CPU: 317 chunks, and 10 plainly-worded questions such as "read the fire button on a
game controller":

| Model | Indexing speed | Right document first | Query time |
|---|---|---|---|
| Built-in nomic-embed-text (default) | 11.6 chunks/s | 9 of 10 | 22 ms |
| Built-in bge-small | 37 chunks/s | 6 of 10 | 5 ms |
| Ollama nomic-embed-text (CPU) | 6.6 chunks/s | 9 of 10 | 262 ms |

**Indexing speed.** Embedding is nearly all of the indexing time. Chunking and keyword indexing take a
fraction of a second, even for a 300-page manual.
- **Re-indexing after edits is quick.** Unchanged chunks keep their embeddings, so saving a proofreading fix
  re-embeds only the chunk you changed: about 0.6 s instead of re-embedding the whole manual.
- **Source code is keyword-only by default.** That suits identifiers and keeps big emulator trees fast. Turn
  on *Embed source code* in Settings → Embeddings if you want semantic search over code.
- **Progress** shows chunks/s and the time remaining. For a much faster first index of a huge library, point
  the embeddings at a GPU machine (its Ollama or Unsloth Studio).

The model used for indexing must also be available wherever queries are answered, because RetroRAG embeds
the question too. The built-in model makes that easy, since it travels with the app. Changing the model
re-embeds everything on the next build.

---

## Library layout and portability

```
<library>\
  library.json                  settings (OCR, embeddings, servers) - travel with the library
  retrorag.db                   SQLite: systems, documents, chunks, full-text index, embeddings
  systems\commodore-64\
      user-guides-manuals\c64_users_guide.pdf
      user-guides-manuals\c64_users_guide.pdf.md         editable text (OCR / extracted)
      user-guides-manuals\c64_users_guide.pdf.ocr.json   OCR word boxes for the editor
      disk-tape-images\demo.d64  +  demo.d64.md          info card
      emulator-source\vice-3.8\src\...
      system.json                manifest written when a system is removed with "keep files"
```

- All paths in the database are relative, so you can **move or copy the whole library folder** to another PC
  and open it with *File → Open library folder*.
- *Linked in place* files (added with "copy" unticked) are absolute paths. Use *File → Copy linked files into
  library* before moving the library.
- **Portable mode** (`portable.flag` next to the app) keeps app settings in `.\settings` and the default library
  in `.\Library`, so the app folder plus library can live on a USB drive.
- After moving to a new PC or path, open *Connect AI* again and re-add to Claude Desktop, since the paths differ.

### Removing a system
*System → Remove selected system…* offers:
- **Keep the files on disk.** Originals, OCR text and your corrections stay in `systems\<name>\`, with a
  `system.json` manifest of titles, tags, notes and categories. Adding a system with the same name later, or
  using *File → Import system folder…*, brings everything back, including proofread text.
- **Delete the files too.** Removes the system's folder. Linked-in-place originals outside the library are
  never deleted.

*Import system folder* also works for a system folder copied from another RetroRAG library.

---

## Command line
Use `retrorag-cli` on Windows and `./retrorag-cli.sh` on Linux, macOS or a Pi.
```
retrorag-cli stats
retrorag-cli add --system "Commodore 64" --category "Schematics" C:\scans\c64_schematic.gif
retrorag-cli ocr                         # OCR everything that needs it
retrorag-cli index [--all]
retrorag-cli search "raster interrupt" --system C64
retrorag-cli api                         # REST :8765 + MCP HTTP :8766
retrorag-cli mcp [--http]                # MCP on stdio (what Claude Desktop runs) or HTTP
retrorag-cli export --markdown D:\out  |  --jsonl chunks.jsonl [--embeddings]
retrorag-cli settings                    # show library settings
retrorag-cli settings api_host=0.0.0.0   # change them (handy on a headless server)
```
Add `--library <folder>` to any command to use a library other than the last-opened one.

## Notes and limits
- OCR quality depends on the scan. Schematics and pinout diagrams are mostly graphics, so add **notes and tags**
  to those documents: they're indexed and searchable.
- Semantic search loads all vectors into memory. That's fine for hundreds of thousands of chunks. Indexing a
  very large source tree (e.g. all of MAME) is slow to embed, so consider adding just the relevant drivers and
  devices.
- Read-only servers; the REST API allows any origin (CORS) so browser-based tools can call it. Keep it on
  127.0.0.1 or set an access token.

## Platforms

| | Desktop app | Headless server (MCP / REST) | Tested |
|---|---|---|---|
| Windows 10/11 | yes | yes | fully: GUI, OCR, embeddings, MCP, REST, standalone .exe build |
| Linux x86-64 | yes | yes | server, CLI, MCP and REST tested on Debian; GUI needs Qt's system libraries (below) |
| Raspberry Pi 4/5, 64-bit Pi OS | yes (slow) | yes (recommended) | all dependencies have ARM64 builds for Pi OS Bookworm |
| macOS (Apple Silicon / Intel) | yes | yes | all dependencies have macOS builds; not yet run on a Mac |

32-bit Raspberry Pi OS isn't supported, because Qt and PyMuPDF don't publish builds for it.

### Linux and macOS
```bash
git clone https://github.com/feralCheese/RetroRAG && cd RetroRAG
./setup.sh                # creates .venv, installs packages, checks Tesseract
./retrorag.sh             # starts the app
./retrorag-cli.sh --help  # command line, MCP and REST server
```
Prerequisites:
- **Debian, Ubuntu or Pi OS:** `sudo apt install python3 python3-venv tesseract-ocr libegl1 libxcb-cursor0`.
- **Fedora:** `sudo dnf install python3 tesseract`.
- **macOS:** `brew install python tesseract`.

`./build_app.sh` makes a standalone copy in `dist/RetroRAG` for the machine it runs on. PyInstaller
doesn't cross-compile, so build on a Mac for Macs and on a Pi for Pis. On macOS this produces a folder with
the program inside, not a signed `.app` bundle.

Settings live in `%APPDATA%\RetroRAG` on Windows, `~/Library/Application Support/RetroRAG` on macOS, and
`~/.config/RetroRAG` on Linux, unless you use portable mode. "Show in folder" uses Explorer, Finder, or
your Linux file manager. Without the Windows icon font, icons come from your Linux icon theme or Qt's
built-in set.

### Raspberry Pi as an always-on RAG server
The best way to use a Pi is as the always-on server: do OCR, proofreading and indexing on your PC, then
let the Pi answer the AI.

1. On the Pi (64-bit Raspberry Pi OS, Pi 4 or 5 with 4 GB or more), install the prerequisites:

   ```bash
   sudo apt install python3-venv tesseract-ocr
   ```

   Then install without the GUI:

   ```bash
   git clone https://github.com/feralCheese/RetroRAG && cd RetroRAG && ./setup.sh --server
   ```
2. Copy your library folder from the PC, e.g. with `rsync -a "RetroRAG Library/" pi@retropi:~/RetroRAG-Library/`.
   The embeddings are stored inside it.
3. The Pi only has to embed each question, using the same model the library was indexed with.
   - To use Ollama on the Pi: `curl -fsSL https://ollama.com/install.sh | sh`, then `ollama pull nomic-embed-text`.
   - Or point it at your PC's Ollama: `./retrorag-cli.sh -l ~/RetroRAG-Library settings embed_url=http://my-pc:11434`.
4. Turn on access from the network and set a token:

   ```bash
   ./retrorag-cli.sh -l ~/RetroRAG-Library settings api_host=0.0.0.0 api_token=choose-a-long-secret
   ```

   Then start the server:

   ```bash
   ./retrorag-cli.sh -l ~/RetroRAG-Library api
   ```

   That serves REST on `:8765` and MCP on `:8766/mcp`.
5. Point Unsloth Studio, Claude Code, LM Studio and other clients at `http://retropi:8766/mcp` with the header
   `Authorization: Bearer <token>`.

To start it automatically at boot, save the following as `/etc/systemd/system/retrorag.service`, then run
`sudo systemctl enable --now retrorag`:
```ini
[Unit]
Description=RetroRAG server
After=network-online.target

[Service]
User=pi
WorkingDirectory=/home/pi/RetroRAG
ExecStart=/home/pi/RetroRAG/retrorag-cli.sh -l /home/pi/RetroRAG-Library api
Restart=on-failure

[Install]
WantedBy=multi-user.target
```
OCR and indexing on the Pi work, but they're much slower than on a PC. After adding documents on the PC,
copy the library across again (`rsync`) and restart the service.

## Licence
RetroRAG is licensed under the GNU Affero General Public License v3.0 (see `LICENSE`). This matches PyMuPDF,
which RetroRAG uses for PDFs and bundles in the standalone build. The built-in *RetroRAG Phosphor* pixel font
is an original design and is part of this project.