README.md

---
license: cc-by-nc-sa-4.0
pipeline_tag: object-detection
language:
  - gmy
tags:
  - linear-a
  - linear-b
  - aegean-scripts
  - epigraphy
  - ancient-languages
  - object-detection
  - image-classification
  - digital-humanities
  - ocr
  - yolo
  - convnext
  - minoan
  - mycenaean
  - greek
---

# BOTHROS — Linear A & Linear B sign reading from photographs

Weights for the [BOTHROS](https://github.com/jmacdonald263/bothros) pipeline:
photograph an ancient Aegean tablet, get the signs on it by catalogue code and
reading.

**🤗 Try the [live demo](https://huggingface.co/spaces/JMacD263/bothros-demo)** — no install, upload a photo. (Free-tier Space; if it shows "sleeping", give it ~30s to wake.)

> **The name** — a [*bóthros*](https://en.wikipedia.org/wiki/Bothros) (βόθρος) is the pit Odysseus digs in
> the *Odyssey*, pouring libations so the spirits of the dead rise to speak with him. Apt for a
> tool that reads scripts silent for three thousand years.

- **`yolo_aegean_unified.pt`** — one YOLO11s detector localising signs for *both*
  scripts (sign detection is class-agnostic; Linear A and Linear B signs are
  visually cognate).
- **`la_classifier.pth` / `lb_classifier.pth`** — ConvNeXt-Tiny classifiers
  (AB-codes for Linear A; B-codes + readings for Linear B).
- **`lb_class_to_reading.json`** — Linear B B-code → phonetic reading map.

**Scope:** this release covers Linear A and Linear B. Cretan Hieroglyphic (a *stronger*
internal result, held back over train/test leakage in too small a corpus) and Cypro-Minoan
(parked — the comparable Corazza 2022 corpus is non-redistributable) are not in v0.1.0; see
the [GitHub repo](https://github.com/jmacdonald263/bothros) for status.

## Results (held-out, leak-free)

| metric | Linear A | Linear B | DeepScribe (cuneiform ref) |
|---|---|---|---|
| classifier oracle top-1 | 79.3% | 64.5% | 74% |
| pipeline E2E sign top-1 | 68.7% | 63.8% | 56.3% |
| pipeline per-line F1 | 64.9% | 76.5% | — |
| CER (lower better) | ~0.48 | 0.44 | 0.669 |

*Per-line F1 is at the precise operating points (conf-filter 0.25 LA, n=133 / 0.30 LB,
n=320). DeepScribe is a cross-domain reference (different script/corpus, hand-annotated GT,
141 classes vs LA 374 / LB 142), not a head-to-head. Full methodology + reproduction:
[GitHub repo](https://github.com/jmacdonald263/bothros).*

*Cross-script: a Linear-B-only detector reads Linear A at **60.7% F1 zero-shot** — the
basis for shipping one unified `aegean-unified` detector for both scripts.*

## Benchmark vs release weights

Two sets ship here. **Benchmark** (`yolo_aegean_unified.pt`, `la_classifier.pth`,
`lb_classifier.pth`) — strict held-out split; the numbers above are theirs; use these
to reproduce/compare. **Release** (`*_release`) — retrained on the **full data incl.
the held-out split**: max capability + broader coverage (LB 148 vs 142 classes), but
**NOT benchmarkable** (they have seen the test tablets — cite the benchmark numbers,
not these). Fetch with `download_weights.py --release`; run with `bothros read … --release`.

## Usage
```bash
pip install bothros            # or: pip install -e . from the GitHub repo
python3 scripts/download_weights.py
python3 -m bothros read your_tablet.jpg --script la   # or --script lb
```

## Licence
**CC BY-NC-SA 4.0** — derived from research-only corpora: lineara.xyz + GORILA (Linear
A images), **SigLA (Ester Salgarella & Simon Castellan)** + lineara.xyz (Linear A sign
boxes + AB-code catalogue), DĀMOS (Federico Aurora) + LinearBExplorer (Linear B). No
corpus images are redistributed — only the trained weights.
The pipeline source code is MIT (see the GitHub repo). Non-commercial use only.

## Citation
DOI [10.5281/zenodo.20746759](https://doi.org/10.5281/zenodo.20746759) ·
code + docs: https://github.com/jmacdonald263/bothros