pyaegean

A specialist Python toolkit for Ancient Greek and the Aegean syllabic scripts: alphabetic Greek and Linear A, Linear B, the Cypriot syllabary, and Cypro-Minoan, through one small, dependency-light library.

Latest PyPI release: v0.54.0 (beta). Usable and tested, but the API may still shift before 1.0. This README follows the current release. Analytical and generative output on the undeciphered material (Linear A, Cypro-Minoan) is exploratory: leads for a human expert, never ground truth. The bundled Linear A corpus is a normalized transcription (no full epigraphic apparatus); for edition-grade readings consult GORILA / SigLA.

Quick start for researchers

Sixty seconds, offline, no accounts:

pip install pyaegean

import aegean
from aegean import greek

ht13 = aegean.load("lineara").get("HT13")      # a tablet from the bundled 1,721-inscription corpus
[t.text for t in ht13.tokens][:3]
# ['KA-U-DE-TA', 'VIN', '𐄁']

[(r.text, r.upos, r.lemma) for r in greek.pipeline("ἐν ἀρχῇ ἦν ὁ λόγος.")]
# [('ἐν','ADP','ἐν'), ('ἀρχῇ','NOUN','ἀρχή'), ('ἦν','VERB','εἰμί'), …]   full analysis, one call

[(t.text, t.status.name) for t in aegean.load("cypriot").get("IG XV 1, 120").tokens]
# [('a-ke-se-to-ro','CERTAIN'), …, ('e-mi','RESTORED')]   editorial apparatus on every word

More runnable examples are in Try it below. Then pick your path:

• Classicist analyzing texts: Getting Started assumes no prior programming; Choosing a Workflow matches your task to a working pattern; Recipes are end-to-end scholarly workflows, each ending in a citation; Greek NLP is the full pipeline reference.
• Epigrapher or papyrologist: Using Critical Editions covers the six fetchable inscription and papyrus corpora, per-token reading statuses, and edition fidelity.
• Aegean-script researcher: Linear A is the per-script handbook (Linear B, Cypriot, and Cypro-Minoan have siblings); Limitations states what the undeciphered material can and cannot support.
• NLP researcher: Benchmarks has the measured numbers, the evaluation protocol, and cited cross-tool comparisons; docs/benchmarks.md is the canonical source; Choosing a Pipeline maps material to the right backend.

The documentation site pairs this quick start with the full API reference.

What this is

The Greek world wrote in more than one script. Alphabetic Greek carries Homer, the tragedians, and the New Testament. Centuries earlier, the Aegean syllabic scripts recorded the Bronze Age: Linear B (Mycenaean Greek, deciphered), the Cypriot syllabary (chiefly Arcado-Cypriot Greek, deciphered; the corpus also carries Eteocypriot and undetermined material), and two scripts we still cannot read: Linear A (Minoan) and Cypro-Minoan.

pyaegean is a narrow, deep toolkit for all of it: a script-agnostic corpus data layer, a full Greek NLP pipeline, the analytical methods of the Linear A Research Workbench ported to Python, and a multi-provider AI layer. Generative results are labeled exploratory and carry their provider, model, prompt, and any grounding sources. Neural analyses can opt into typed, scoped confidence with explicit unavailable reasons; empirical source/task calibration and review thresholds remain evidence-gated. The core installs with zero heavy dependencies and imports instantly; heavier backends (models, treebanks, lexica) are opt-in and fetched to a local cache, never bundled.

For classicists, computational philologists, linguists, and students: anyone who wants a clean, citable data layer over Greek and the Aegean scripts. The Getting Started guide assumes no prior programming.

Highlights

Install

pip install pyaegean              # core + Linear A + Greek (zero heavy dependencies)
pip install "pyaegean[cli]"       # + the `aegean` command line
pip install "pyaegean[tui]"       # + the `aegean tui` full-screen terminal UI (Textual)
pip install "pyaegean[neural]"    # + the neural Greek pipeline & lemmatizer (onnxruntime; no torch)
pip install "pyaegean[ai]"        # + Anthropic / OpenAI / Grok / Gemini / OpenRouter clients (the openai SDK also drives the local option)
pip install "pyaegean[mcp]"       # + the `aegean-mcp` Model Context Protocol server (for agents)
pip install "pyaegean[interop]"   # + Python adapters; combine with [cli] for the interop commands
pip install "pyaegean[all]"       # bundled runtime extras, including neural (not Parquet/framework adapters)

Try it

No install required: run the guided tour in your browser, nothing to set up:

Or try the toolkit live in your browser: the core pipeline running client-side via Pyodide, nothing to install: pyaegean.xyz/demo.

import aegean

corpus = aegean.load("lineara")          # 1,721 inscriptions, bundled, offline
ht = corpus.filter(site="Haghia Triada") # filter by metadata (full site name)
df = corpus.to_dataframe(level="word")   # pandas-native, one row per word

from aegean.analysis import balance_check, word_matches_sign_pattern
balance_check(corpus.get("HT13"))                       # KU-RO accounting reconciliation
[w for w, _ in corpus.word_frequencies()
 if word_matches_sign_pattern(w, "KU-*-RO")]            # wildcard sign search → ['KU-MA-RO']

from aegean import greek

greek.betacode_to_unicode("mh=nin")     # 'μῆνιν'   (type Greek in plain ASCII)
greek.syllabify("ἄνθρωπος")             # ['ἄν', 'θρω', 'πος']
greek.scan_hexameter("ἄνδρα μοι ἔννεπε, Μοῦσα, πολύτροπον, ὃς μάλα πολλὰ").pattern
# '—⏑⏑|—⏑⏑|—⏑⏑|—⏑⏑|—⏑⏑|—×'             (Odyssey 1.1)

[(r.text, r.upos, r.lemma) for r in greek.pipeline("ἐν ἀρχῇ ἦν ὁ λόγος.")]
# [('ἐν','ADP','ἐν'), ('ἀρχῇ','NOUN','ἀρχή'), ('ἦν','VERB','εἰμί'), …]   one call, per-token records

segmented = greek.segment_text("[λόγος.] καί.", policy="papyrus")
segmented.boundaries[0].to_dict(segmented.source)
# exact source span + policy/provenance metadata (use sentence_policy= on pipeline())

greek.catalog(author="Plato")[0]   # find a work id to load — bundled, offline, instant
# {'id': 'tlg0059.tlg001', 'author': 'Plato', 'title': 'Euthyphro', 'greek_title': 'Εὐθύφρων', 'source': 'perseus'}

Or bring your own text: a string, a .txt file, a folder of texts, or a CSV becomes a full Corpus:

from aegean import io

corpus = io.from_text("ἐν ἀρχῇ ἦν ὁ λόγος.")   # offline; Greek tokenizer
[t.text for t in corpus.get("text").tokens]    # ['ἐν', 'ἀρχῇ', 'ἦν', 'ὁ', 'λόγος']
# now corpus.query(...), corpus.word_frequencies(), aegean.io.to_csv(corpus, …) — the whole API

Or skip Python entirely: the aegean CLI ([cli] extra) covers the whole toolkit, with --json on every data-producing command and stdin piping:

aegean quickstart                              # the guided first five minutes, offline
aegean doctor                                  # check the environment (extras, data store, models)
aegean repl                                    # interactive shell: run commands without the `aegean` prefix
aegean tui                                     # full-screen terminal UI: browse a corpus, the Greek workbench, the data store (`[tui]` extra)
aegean show lineara HT13                       # one tablet, line by line
aegean balance lineara --strict                # reconcile every stated total
aegean greek scan "ἄνδρα μοι ἔννεπε, Μοῦσα, πολύτροπον, ὃς μάλα πολλὰ"
aegean greek pipeline "ἐν ἀρχῇ ἦν ὁ λόγος." --neural --json
printf '%s\n' '["μῆνιν","ἄειδε"]' | aegean greek stream -   # bounded neural JSONL
aegean greek interop export treebank.conllu --target spacy -o treebank.spacy.json
aegean greek catalog --author plato            # search 1,778 loadable works (offline)
aegean import myplato.txt -o myplato.json      # your own text → a corpus, then `aegean stats myplato.json`

The core Greek and bundled-corpus examples run offline without heavy dependencies. The CLI, TUI, DataFrame, neural, and AI examples require their documented extras; network providers also require network access. Large assets are fetched to a local cache only when you opt in (and never bundled inside the wheel): the full Linear B corpus (aegean.load("damos")), the SigLA Linear A dataset (aegean.load("sigla")), the Greek epigraphy and papyrus corpora (aegean.load("isicily"), "iip", "iospe", "igcyr", "edh", and the 57k-papyrus "ddbdp"), the full New Testament (aegean.load("nt")), the Linear A facsimile mirror (aegean.data.fetch("lineara-images")), the AGDT-derived lexicon and models (greek.use_treebank() and friends: small prebuilt artifacts, with build-from-source as the fallback), the LSJ index (greek.use_lsj()), and the neural models (greek.use_neural_lemmatizer() / use_neural_pipeline()).

Documentation

Full documentation lives in the project wiki:

• Getting Started: for newcomers to Python
• Example notebook: a runnable guided tour (open in Colab)
• Tutorial: two guided, end-to-end research walkthroughs
• Linear A · Linear B · Cypriot · Cypro-Minoan: per-script guides
• Recipes: end-to-end scholarly workflows, each ending in a citation
• Greek NLP · CLI · Analysis · AI Layer · Data & Provenance: reference
• Interoperability: CoNLL-U, spaCy, Stanza, and CLTK projections, sidecars, reports, and serializer boundaries
• API reference: the supported facade modules, with public classes and functions generated from the source

Roadmap

The changelog is the record of what each release shipped. Current work is focused on:

• integrating export and runtime-variant qualification with the now-frozen, source-balanced model-selection gate, then fitting source/task calibration only where the available development evidence supports it;
• comparing deterministic and neural translation grounding on matched passages before changing any default;
• training and independently evaluating a separately versioned successor to the current Greek model only after those foundations are frozen;
• producing calibrated runtime variants and a reviewer reproduction kit only after a candidate model passes the cross-domain gates; and
• adding license-clean dictionaries, conda-forge packaging, and verified gazetteer coverage.

About the author

Ryan Pavlicek

I'm a software engineer that likes creating useful tools for exploring interesting problems.

Contact: email or create an issue on the GitHub repo.

Email: 'ryan [dot] pavlicek [dot] github [at] gmail [dot] com'

(Replace [at] with @ and [dot] with .)

Citation

If pyaegean helped with work you publish, please cite it. In the scholarly spirit, two layers:

1. Always cite the underlying scholarship pyaegean stands on: GORILA (Godart & Olivier 1976–1985; all five volumes are digitized in the École française d'Athènes' CEFAEL library at that link) for Linear A; the Perseus AGDT treebank, LSJ, and (for fetched works) the Perseus Digital Library / Open Greek and Latin for Greek; the Unicode Character Database for the Linear B / Cypriot / Cypro-Minoan sign data; and GreBerta/GreTa plus the AGDT, Gorman, and Pedalion treebanks behind the neural models. The editions are listed in NOTICE, and every corpus emits its own source citation via corpus.cite().
2. Also cite pyaegean if you used its analysis, methods, or outputs (pin the version you ran, for reproducibility). GitHub's "Cite this repository" button (generated from CITATION.cff) gives APA / BibTeX in one click, or use:

@software{pavlicek_pyaegean,
  author  = {Pavlicek, Ryan},
  title   = {{pyaegean: a Python toolkit for Ancient Greek and the Aegean syllabic scripts}},
  year    = {2026},
  version = {0.54.0},
  url     = {https://github.com/ryanpavlicek/pyaegean}
}

No obligation for casual or exploratory use, but if it helped, I'd love to hear about it.

License

Apache-2.0. Linear A corpus data is GORILA (Godart & Olivier 1976–1985) via mwenge/lineara.xyz; the Linear B / Cypriot / Cypro-Minoan sign data is from the Unicode Character Database. Facsimile imagery © École Française d'Athènes (referenced, not redistributed). The opt-in Greek backends fetch small prebuilt artifacts derived from the Perseus AGDT (CC BY-SA 3.0) and LSJ (CC BY-SA 4.0) to cache, falling back to building from upstream. The DAMOS and SigLA corpora are CC BY-NC-SA 4.0, hosted as clearly-labeled release assets and fetched to cache: NC data is never bundled inside the wheel. The Greek epigraphic and papyrus corpora (I.Sicily CC BY 4.0, IIP CC BY-NC 4.0, IOSPE CC BY, IGCyr/GVCyr CC BY-NC-SA 4.0, EDH CC BY-SA 4.0, DDbDP CC BY 3.0) are likewise project-hosted release assets fetched on demand, with attribution in each corpus's provenance. See NOTICE.