pyaegean

https://pyaegean.xyz
Admin
pyaegean is a Python toolkit for Ancient Greek and Aegean syllabic scripts, providing NLP pipelines,...
Tokens:72,981
Snippets:1,029
Trust Score:2.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install pyaegean

Source: https://pyaegean.xyz/api

Installation commands for the core library and optional extras.

```bash
pip install pyaegean            # core + Linear A + Greek (zero heavy dependencies)
pip install "pyaegean[all]"     # bundled runtime extras, including neural (not Parquet/framework adapters)
```

--------------------------------

### Install pyaegean

Source: https://pyaegean.xyz/

Install the library using pip.

```bash
pip install pyaegean
```

--------------------------------

### Install neural dependencies

Source: https://pyaegean.xyz/methodology

Installs the necessary packages to enable neural pipeline functionality.

```bash
pip install "pyaegean[neural]"
```

--------------------------------

### Build MCP Server

Source: https://pyaegean.xyz/api/mcp

Initializes a FastMCP server with all pyaegean tools registered. Requires the [mcp] extra installation.

```python
build_server() -> Any
```

--------------------------------

### Install pyaegean interoperability extras

Source: https://pyaegean.xyz/interoperability

Install specific dependencies for target NLP libraries. These extras are optional and only imported when the corresponding adapter is invoked.

```bash
pip install "pyaegean[spacy]"
pip install "pyaegean[stanza]"   # includes Stanza's PyTorch dependency
pip install "pyaegean[cltk]"     # CLTK 2.5.1 requires Python 3.13+
pip install "pyaegean[interop]"  # spaCy + Stanza; CLTK is included on Python 3.13+
pip install "pyaegean[cli,interop]"  # adapters plus the interop CLI commands
```

--------------------------------

### Get bundled version

Source: https://pyaegean.xyz/api/data

Returns the version string of the bundled datasets, which corresponds to the package version.

```python
bundled_data_version() -> str
```

--------------------------------

### Get On-Disk Paths

Source: https://pyaegean.xyz/api/data

Returns the expected cache paths for a dataset specification, regardless of whether the files currently exist.

```python
on_disk_paths(spec: DataSpec, root: Path) -> list[Path]
```

--------------------------------

### Get Document

Source: https://pyaegean.xyz/api/core

Retrieves a document by its unique identifier.

```python
get(doc_id: str) -> Document | None
```

--------------------------------

### Get Geographic Sites

Source: https://pyaegean.xyz/api/mcp

Retrieves site coordinates and provenance data, or word attestation counts per site.

```python
geo_sites(corpus: str, word: str | None = None) -> dict[str, Any]
```

--------------------------------

### fetch_prebuilt(name: str, dest: Path, *, member: str | None = None) -> bool

Source: https://pyaegean.xyz/api/data

Places a hosted prebuilt artifact at a specified destination. Returns True on success and False on failure to allow for fallback build processes.

```APIDOC
### fetch_prebuilt(name: str, dest: Path, *, member: str | None = None) -> bool

### Description
Places a hosted prebuilt artifact at the provided destination path. This is intended as an optimization to avoid slow local builds.

### Parameters
- **name** (str) - Required - The name of the prebuilt artifact.
- **dest** (Path) - Required - The destination path where the artifact should be placed.
- **member** (str | None) - Optional - Specifies a file inside an extract dataset's unpacked directory.
```

--------------------------------

### Initialize and evaluate the neural pipeline

Source: https://pyaegean.xyz/methodology

Demonstrates how to check asset versions, activate the neural pipeline, and perform UD evaluations on specific datasets.

```python
from aegean import data, greek

data.versions()                              # asset identities and digests
greek.use_neural_pipeline()                 # fetch grc-joint and activate its v3 artifact
greek.evaluate_on_ud("perseus", "test")    # in-family UD evaluation
greek.evaluate_on_ud("proiel", "test")     # out-of-domain UD evaluation
```

--------------------------------

### Initialize AI Client and Translate Text

Source: https://pyaegean.xyz/api/ai

Demonstrates how to instantiate an AI client for a specific provider and perform a translation task.

```python
from aegean import ai
client = ai.get_client("anthropic")          # needs pyaegean[anthropic] + a key
result = ai.translate("μῆνιν ἄειδε θεά", client=client)
print(result.labeled())                       # carries the EXPLORATORY tag
```

--------------------------------

### Get Cache Key

Source: https://pyaegean.xyz/api/core

Alias for the fingerprint method used by the caching system.

```python
cache_key() -> str
```

--------------------------------

### Convert DiagnoseReport to DataFrame

Source: https://pyaegean.xyz/api/aegean

Exports the report as a pandas DataFrame. Requires the [data] extra installation.

```python
to_dataframe()
```

--------------------------------

### Reproduce Shipped Pipeline

Source: https://pyaegean.xyz/benchmarks

Use these commands to initialize the neural pipeline and evaluate it against the Perseus and PROIEL test sets.

```python
from aegean import greek
greek.use_neural_pipeline()
greek.evaluate_on_ud("perseus", "test")
greek.evaluate_on_ud("proiel", "test")
```

--------------------------------

### Get concise gloss

Source: https://pyaegean.xyz/api/ai

Retrieves a cleaned, common-sense-first gloss for a lemma from loaded concise dictionaries.

```python
concise_gloss(lemma: str) -> str
```

--------------------------------

### Construct LLM client

Source: https://pyaegean.xyz/api/ai

Initializes a client for a specified provider. Importing aegean.ai registers built-in providers.

```python
get_client(provider: str = 'anthropic', *, model: str | None = None, api_key: str | None = None, cache: ResponseCache | None = None) -> LLMClient
```

--------------------------------

### DiskCache Initialization

Source: https://pyaegean.xyz/api/cache

Constructor for the sqlite-backed key-value store.

```python
DiskCache(path: str | Path)
```

--------------------------------

### Get word frequencies

Source: https://pyaegean.xyz/api/core

Returns a list of tuples containing words and their counts, sorted by descending frequency.

```python
word_frequencies() -> list[tuple[str, int]]
```

--------------------------------

### ai.get_client

Source: https://pyaegean.xyz/api/ai

Initializes a client for a specific AI provider.

```APIDOC
## ai.get_client(provider: str)

### Description
Returns an LLMClient instance for the specified provider. Requires the corresponding provider extra to be installed and an API key to be available.

### Parameters
- **provider** (str) - Required - The identifier for the AI provider (e.g., "anthropic", "openai").
```

--------------------------------

### Fetch prebuilt artifact

Source: https://pyaegean.xyz/api/data

Retrieves a prebuilt artifact to a destination path, returning False on failure to allow for fallback build processes.

```python
fetch_prebuilt(name: str, dest: Path, *, member: str | None = None) -> bool
```

--------------------------------

### Initialize Corpus

Source: https://pyaegean.xyz/api/core

Constructor for creating a new Corpus instance with documents and optional inventory or provenance.

```python
Corpus(documents: list[Document], sign_inventory: SignInventory | None = None, provenance: Provenance | None = None, script_id: str = '')
```

--------------------------------

### Get Cache Directory

Source: https://pyaegean.xyz/api/data

Returns the path to the directory where fetched datasets are stored. Can be overridden using the PYAEGEAN_CACHE environment variable.

```python
cache_dir() -> Path
```

--------------------------------

### List Available Versions

Source: https://pyaegean.xyz/api/data

Returns a list of all fetchable versions for a dataset, including the current pin and historical releases.

```python
available_versions(name: str) -> list[dict[str, Any]]
```

--------------------------------

### Run Console Script

Source: https://pyaegean.xyz/api/mcp

Entry point for the aegean-mcp console script to serve tools over stdio.

```python
main() -> None
```

--------------------------------

### Get Greek reading for a Cypriot word

Source: https://pyaegean.xyz/api/scripts-cypriot

Returns a tuple containing the lemma and gloss for a transliterated Cypriot word, or None if unavailable.

```python
greek_reading(word: str) -> tuple[str, str] | None
```

--------------------------------

### fetch_text(name: str, dest: str | Path, *, max_bytes: int = _MAX_GZIP_JSON_BYTES, download: bool = True, expect_gzip: bool | None = None) -> Path

Source: https://pyaegean.xyz/api/data

Fetches a registered dataset by name, gunzips it, and materializes it at the destination path.

```APIDOC
## fetch_text

### Description
Fetch dataset `name` and materialize it at `dest`, gunzipping and stamping it. This helper fetches the registered dataset, decompresses it under a `max_bytes` cap, and writes the result to `dest` atomically.

### Parameters
- **name** (str) - Required - The name of the registered dataset.
- **dest** (str | Path) - Required - The destination path for the materialized file.
- **max_bytes** (int) - Optional - Cap for decompression size to prevent oversized payloads.
- **download** (bool) - Optional - If False, returns `dest` without fetching.
- **expect_gzip** (bool | None) - Optional - Declares knowledge of the asset: True (always gzip), False (copy through), None (sniff content).

### Returns
- **Path** - The path to the materialized file.
```

--------------------------------

### Get path to DDbDP database

Source: https://pyaegean.xyz/api/scripts-greek

Returns the path to the fetched DDbDP SQLite database, which is unpacked on first use. Use this with aegean.db functions for memory-efficient full-text search.

```python
ddbdp_db() -> Path
```

--------------------------------

### Enable and Manage Cache

Source: https://pyaegean.xyz/api/cache

Basic workflow for enabling the cache, performing analysis, checking statistics, and clearing the cache.

```python
import aegean
aegean.cache.enable()                 # opt in (or set PYAEGEAN_ANALYSIS_CACHE=1)
aegean.analysis.dispersions(corpus)   # computed once, then served from disk
aegean.cache.stats()                  # {'enabled': True, 'entries': 1, 'path': …}
aegean.cache.clear()                  # wipe it
```

--------------------------------

### Build metrology profile

Source: https://pyaegean.xyz/api/analysis

Creates a metrology profile by iterating through physical lines and crediting numerals to commodity logograms. Requires a minimum number of entries per commodity.

```python
metrology_profile(corpus: Any, *, min_entries: int = 3) -> MetrologyProfile
```

--------------------------------

### ResponseCache Initialization

Source: https://pyaegean.xyz/api/ai

Initializes a cache for AI completions, optionally persisting to a file path.

```python
ResponseCache(path: str | Path | None = None)
```

--------------------------------

### Run the shortest bounded evidence check

Source: https://pyaegean.xyz/methodology

Executes the reproduction script to verify canonical review records and ensure project integrity without network access.

```bash
python scripts/reproduce_review.py
```

--------------------------------

### get_client

Source: https://pyaegean.xyz/api/ai

Constructs an LLM client for a specified provider.

```APIDOC
## get_client(provider: str = 'anthropic', *, model: str | None = None, api_key: str | None = None, cache: ResponseCache | None = None) -> LLMClient

### Description
Initializes and returns an LLM client for the specified provider.
```

--------------------------------

### Initialize Provenance dataclass

Source: https://pyaegean.xyz/api/core

Defines the source, license, and citation metadata for a corpus.

```python
Provenance(source: str, license: str = '', citation: str = '', url: str = '', schema_version: int = SCHEMA_VERSION, notes: tuple[str, ...] = tuple(), data_version: str = '', edition_fidelity: str = '')
```

--------------------------------

### available_versions

Source: https://pyaegean.xyz/api/data

Lists every fetchable version of a specific dataset.

```APIDOC
## available_versions(name: str) -> list[dict[str, Any]]

### Description
Returns a list of all fetchable versions for the given dataset, including the current pin and historical pins.

### Parameters
- **name** (str) - Required - The name of the dataset.
```

--------------------------------

### Activate neural pipeline

Source: https://pyaegean.xyz/benchmarks

Initializes the neural pipeline required before applying post-processing levers.

```python
greek.use_neural_pipeline()
```

--------------------------------

### from_spacy

Source: https://pyaegean.xyz/api/io

Import a real spaCy Doc and validate its complete native state.

```APIDOC
## from_spacy(doc: Any, *, sidecar: str | None = None, allow_lossy: bool = False) -> InteropResult[InteropDocument]

### Description
Import a real spaCy `Doc` and validate its complete native state.
```

--------------------------------

### Explain Greek Pipeline Results

Source: https://pyaegean.xyz/api/mcp

Provides a plain-language explanation of the lemma resolution and evidence classes for each token.

```python
greek_explain(text: str) -> list[dict[str, Any]]
```

--------------------------------

### List available corpora

Source: https://pyaegean.xyz/api/mcp

Returns a list of corpora names that can be loaded. Some corpora are bundled, while others are downloaded on first use.

```python
list_corpora() -> list[str]
```

--------------------------------

### mulberry32(seed: int) -> Callable[[], float]

Source: https://pyaegean.xyz/api/analysis

Initializes a tiny, fast, seeded 32-bit PRNG.

```APIDOC
## mulberry32

### Description
Returns a zero-argument callable yielding floats in [0, 1) based on a provided seed.

### Parameters
- **seed** (int) - Required - The seed for the PRNG.
```

--------------------------------

### LLMClient.complete

Source: https://pyaegean.xyz/api/ai

Performs a cached single-turn completion.

```APIDOC
## LLMClient.complete(prompt: str, *, system: str | None = None, max_tokens: int = 1024)

### Description
Executes a completion request. Results are cached based on provider, model, system prompt, user prompt, and token limit.

### Parameters
- **prompt** (str) - Required - The input prompt.
- **system** (str) - Optional - The system instruction.
- **max_tokens** (int) - Optional - Maximum number of tokens to generate.
```

--------------------------------

### Create SourceMarkupRef from dictionary

Source: https://pyaegean.xyz/api/aegean

Decodes and validates a canonical source reference mapping.

```python
from_dict(value: dict[str, Any]) -> 'SourceMarkupRef'
```

--------------------------------

### grounding_for(text: str, script: str, *, mode: GroundingMode = 'morphology', glosses: bool = True, greek_pipeline: GreekPipeline | None = None, greek_long_input: GreekLongInput = 'strict', grounding_failure: GroundingFailure = 'best-effort') -> list[GroundingItem]

Source: https://pyaegean.xyz/api/translate

Generates deterministic grounding evidence for the provided text. The output is a list of GroundingItem objects, each tagged with its source for traceability.

```APIDOC
## grounding_for

### Description
Generates local, deterministic grounding evidence for a given text in a specific script. Each item in the returned list is tagged with its source (e.g., morphology, syntax, lexicon) to allow for trace analysis.

### Parameters
- **text** (str) - Required - The input text to be grounded.
- **script** (str) - Required - The script of the input text.
- **mode** (GroundingMode) - Optional - The grounding style: 'morphology' (default), 'full', 'lemma', or 'none'.
- **glosses** (bool) - Optional - Whether to include glosses (superseded by mode).
- **greek_pipeline** (GreekPipeline | None) - Optional - An isolated pipeline instance for Greek text.
- **greek_long_input** (GreekLongInput) - Optional - Neural sentence contract: 'strict' (default), 'partial', or 'windowed'.
- **grounding_failure** (GroundingFailure) - Optional - Policy for analysis failures: 'best-effort' (default) or 'strict'.

### Returns
- **list[GroundingItem]** - A list of grounding evidence items.
```

--------------------------------

### select_sense(word: str, context: str, *, max_candidates: int = 3, overlap_weight: float = 1.0, markedness_weight: float = 0.25, prior_weight: float = 0.15) -> list[SenseCandidate]

Source: https://pyaegean.xyz/api/ai

Ranks LSJ senses for a specific word based on their fit to the provided context.

```APIDOC
## select_sense

### Description
Rank a word's LSJ senses by fit to the provided context. Returns a list of `SenseCandidate` objects.

### Parameters
- **word** (str) - Required - The word to disambiguate.
- **context** (str) - Required - The surrounding text context.
- **max_candidates** (int) - Optional - Maximum number of candidates to return (default: 3).
- **overlap_weight** (float) - Optional - Weight for lexical overlap (default: 1.0).
- **markedness_weight** (float) - Optional - Weight for register/dialect markers (default: 0.25).
- **prior_weight** (float) - Optional - Weight for sense-order/length prior (default: 0.15).
```

--------------------------------

### Bundle Utility Functions

Source: https://pyaegean.xyz/api/io

Functions for creating, serializing, parsing, reading, and writing interoperability bundles.

```python
bundle_from_document(document: InteropDocument, *, target: str) -> InteropBundle
```

```python
bundle_from_result(result: InteropResult[Any]) -> InteropBundle
```

```python
dumps_interop_bundle(bundle: InteropBundle) -> str
```

```python
loads_interop_bundle(value: str) -> InteropBundle
```

```python
read_interop_bundle(path: str | Path) -> InteropBundle
```

```python
write_interop_bundle(bundle: InteropBundle, path: str | Path) -> Path
```

--------------------------------

### Run evaluation

Source: https://pyaegean.xyz/api/ai

Executes evaluation cases using the provided client and returns an aggregate report.

```python
run_eval(cases: Sequence[GroundingCase], client: LLMClient) -> EvalReport
```

--------------------------------

### Run the independent review command

Source: https://pyaegean.xyz/review

Executes the review script to verify the source checkout and run the offline regression fixture.

```bash
git clone https://github.com/ryanpavlicek/pyaegean.git
cd pyaegean
python scripts/reproduce_review.py
```

--------------------------------

### Import and analyze corpora via CLI

Source: https://pyaegean.xyz/api

Use the aegean CLI to import text files into a corpus format and run statistical analysis.

```bash
$ aegean import myplato.txt -o myplato.json   # --split whole|paragraph|line
wrote 1 document(s) to myplato.json
$ aegean stats myplato.json --top 5           # …then any corpus command works
```

--------------------------------

### bundle_from_document

Source: https://pyaegean.xyz/api/io

Runs a lazy adapter to return a validated, portable InteropBundle from an InteropDocument.

```APIDOC
## bundle_from_document(document: InteropDocument, *, target: str) -> InteropBundle

### Description
Run one lazy adapter and return its validated portable bundle.

### Parameters
- **document** (InteropDocument) - Required - The document to adapt.
- **target** (str) - Required - The target format identifier.

### Returns
- **InteropBundle** - A validated, portable adapter bundle.
```

--------------------------------

### fetch(name: str, *, version: str | None = None, force: bool = False, abort: Callable[[], bool] | None = None, progress: Callable[[int, int], None] | None = None) -> Path

Source: https://pyaegean.xyz/api/data

Downloads a registered remote dataset into the cache and returns its local path. It handles atomic downloads, resume functionality, and version-specific fetching.

```APIDOC
### fetch(name: str, *, version: str | None = None, force: bool = False, abort: Callable[[], bool] | None = None, progress: Callable[[int, int], None] | None = None) -> Path

### Description
Downloads a registered remote dataset into the cache and returns its path. It verifies checksums, supports atomic downloads, and handles concurrent requests via locking.

### Parameters
- **name** (str) - Required - The name of the dataset to fetch.
- **version** (str | None) - Optional - Fetches a specific version of the dataset instead of the current pin.
- **force** (bool) - Optional - Forces a re-fetch.
- **abort** (Callable[[], bool] | None) - Optional - A callable polled during transfer; if it returns true, the fetch stops.
- **progress** (Callable[[int, int], None] | None) - Optional - A callback to report progress as (done, total).
```

--------------------------------

### to_spacy

Source: https://pyaegean.xyz/api/io

Project one immutable canonical document into a real spaCy Doc.

```APIDOC
## to_spacy(document: InteropDocument, *, vocab: Any = None, allow_lossy: bool = False) -> InteropResult[Any]

### Description
Project one immutable canonical document into a real spaCy `Doc`.
```

--------------------------------

### Import from Stanza

Source: https://pyaegean.xyz/api/io

Imports a Stanza document and validates its native state.

```python
from_stanza(doc: Any, *, sidecar: str | None = None, allow_lossy: bool = False) -> InteropResult[InteropDocument]
```

--------------------------------

### fit_heaps(points: Sequence[tuple[float, float]]) -> HeapsFit | None

Source: https://pyaegean.xyz/api/analysis

Fits Heaps' law V(N) = k·N^β by least squares in log–log space over a vocabulary-growth curve. Requires at least five points with tokens ≥ 1 and types ≥ 1.

```APIDOC
## fit_heaps

### Description
Fits Heaps' law V(N) = k·N^β by least squares in log–log space over a vocabulary-growth curve of (tokens, types) points.

### Parameters
- **points** (Sequence[tuple[float, float]]) - Required - A sequence of (tokens, types) tuples.
```

--------------------------------

### baayen_productivity

Source: https://pyaegean.xyz/api/analysis

Calculates Baayen's category-conditioned productivity for affixes.

```APIDOC
## baayen_productivity(words: Iterable[tuple[str, int]], *, affix_len: int = 1, mode: str = 'suffix') -> list[Productivity]

### Description
Calculates the productivity P for affixes, defined as the number of hapax-legomena types bearing the affix divided by the total token frequency of all words bearing it.
```

--------------------------------

### Generate citation strings

Source: https://pyaegean.xyz/api/core

Methods for formatting provenance data into standard citation formats.

```python
cite() -> str
```

```python
bibtex(key: str = 'aegean-corpus') -> str
```

```python
apa() -> str
```

--------------------------------

### Load SigLA Dataset

Source: https://pyaegean.xyz/api/scripts-lineara

Fetches and loads the SigLA-derived Linear A dataset as a Corpus.

```python
load_sigla() -> Any
```

--------------------------------

### from_stanza

Source: https://pyaegean.xyz/api/io

Import a real Stanza document and validate its complete native state.

```APIDOC
## from_stanza(doc: Any, *, sidecar: str | None = None, allow_lossy: bool = False) -> InteropResult[InteropDocument]

### Description
Import a real Stanza document and validate its complete native state.
```

--------------------------------

### Project to Stanza

Source: https://pyaegean.xyz/api/io

Projects an immutable canonical document into a Stanza Document.

```python
to_stanza(document: InteropDocument, *, allow_lossy: bool = False) -> InteropResult[Any]
```

--------------------------------

### from_epidoc

Source: https://pyaegean.xyz/api/io

Load token-carrier EpiDoc TEI into a Corpus.

```APIDOC
## from_epidoc(source: str | Path, *, script_id: str = 'greek') -> Corpus

### Description
Load token-carrier EpiDoc TEI into a `Corpus`. The inverse of `write_epidoc`.
```

--------------------------------

### Initialize Mulberry32 PRNG

Source: https://pyaegean.xyz/api/analysis

Creates a seeded 32-bit pseudo-random number generator that yields floats in the range [0, 1). Ensures reproducibility across different environments.

```python
mulberry32(seed: int) -> Callable[[], float]
```

--------------------------------

### Execute query on pre-built indices

Source: https://pyaegean.xyz/api/analysis

Runs a query using filters and output mode over pre-built indices. Note that for word output, counts represent document frequency rather than token frequency.

```python
eval_query(filters: list[FilterRow], output: Output, documents: list[Document], word_index: dict[str, WordEntry], annotated_ids: set[str], cooccur_map: dict[str, set[str]]) -> QueryResults
```

--------------------------------

### LLMClient and LLMResponse Definitions

Source: https://pyaegean.xyz/api/ai

Base classes and response structures for provider-specific AI clients.

```python
LLMClient(model: str | None = None, *, api_key: str | None = None, cache: ResponseCache | None = None)
```

```python
complete(prompt: str, *, system: str | None = None, max_tokens: int = 1024) -> LLMResponse
```

```python
LLMResponse(text: str, provider: str, model: str, raw: Any = None)
```

--------------------------------

### to_stanza

Source: https://pyaegean.xyz/api/io

Project one immutable canonical document into a real Stanza Document.

```APIDOC
## to_stanza(document: InteropDocument, *, allow_lossy: bool = False) -> InteropResult[Any]

### Description
Project one immutable canonical document into a real Stanza `Document`.
```

--------------------------------

### load_sigla() -> Any

Source: https://pyaegean.xyz/api/scripts-lineara

Loads the SigLA-derived Linear A dataset as a Corpus.

```APIDOC
## load_sigla()

### Description
Fetches and loads the SigLA-derived Linear A dataset as a Corpus. The data is cached locally after the first fetch.

### Returns
- **Any** - The loaded Corpus object.
```

--------------------------------

### Access Segment Role and Source

Source: https://pyaegean.xyz/api/aegean

Compatibility properties for reading status and source references.

```python
role: ReadingStatus
```

```python
source: SourceMarkupRef | None
```

--------------------------------

### Access SourceMarkupRef properties and methods

Source: https://pyaegean.xyz/api/core

Utilities for accessing attributes and converting the reference to or from a dictionary.

```python
attributes: tuple[tuple[str, str], ...]
```

```python
to_dict() -> dict[str, Any]
```

```python
from_dict(value: dict[str, Any]) -> 'SourceMarkupRef'
```

--------------------------------

### load_damos()

Source: https://pyaegean.xyz/api/scripts-linearb

Loads the DAMOS Linear B corpus as a Corpus object, fetching it on first use and caching it locally.

```APIDOC
## load_damos()

### Description
Loads the DAMOS Linear B corpus as a `Corpus` object. It fetches the corpus on first use and subsequently loads it from the local cache.

### Signature
`load_damos() -> Any`
```

--------------------------------

### Check download status

Source: https://pyaegean.xyz/api/data

Verifies if any artifact of the current dataset pin exists on disk.

```python
is_downloaded(spec: DataSpec, root: Path) -> bool
```

--------------------------------

### to_sql(path: str | Path, *, fts: bool = True, append: bool = False) -> None

Source: https://pyaegean.xyz/api/aegean

Writes the corpus to a SQLite database.

```APIDOC
## to_sql(path: str | Path, *, fts: bool = True, append: bool = False) -> None

### Description
Write this corpus to a SQLite database. Documents and tokens become queryable rows.

### Parameters
- **path** (str | Path) - Required - Path to the SQLite database file.
- **fts** (bool) - Optional - Enable FTS5 text index.
- **append** (bool) - Optional - Append to existing database instead of overwriting.
```

--------------------------------

### read_interop_bundle

Source: https://pyaegean.xyz/api/io

Reads a bounded UTF-8 bundle from a local file path.

```APIDOC
## read_interop_bundle(path: str | Path) -> InteropBundle

### Description
Read a bounded UTF-8 bundle from one local path.

### Parameters
- **path** (str | Path) - Required - The file system path to the bundle.

### Returns
- **InteropBundle** - The parsed and validated bundle.
```

--------------------------------

### to_cltk

Source: https://pyaegean.xyz/api/io

Project one immutable canonical document into a real CLTK Doc.

```APIDOC
## to_cltk(document: InteropDocument, *, allow_lossy: bool = False) -> InteropResult[Any]

### Description
Project one immutable canonical document into a real CLTK `Doc`.
```

--------------------------------

### Build corpus from directory

Source: https://pyaegean.xyz/api/io

Creates a Corpus object from all text files found in a directory.

```python
from_text_dir(path: str | Path, *, script_id: str = 'greek', glob: str = '*.txt', split: str = 'whole', encoding: str = 'utf-8') -> 'Corpus'
```

--------------------------------

### write_interop_bundle

Source: https://pyaegean.xyz/api/io

Atomically writes a validated bundle to a local file path.

```APIDOC
## write_interop_bundle(bundle: InteropBundle, path: str | Path) -> Path

### Description
Atomically write one validated bundle and return its path.

### Parameters
- **bundle** (InteropBundle) - Required - The bundle to write.
- **path** (str | Path) - Required - The destination path.

### Returns
- **Path** - The path where the bundle was written.
```

--------------------------------

### Load IOSPE inscriptions

Source: https://pyaegean.xyz/api/scripts-greek

Loads the IOSPE Greek inscriptions as a corpus.

```python
load_iospe() -> Any
```

--------------------------------

### Activate paradigms

Source: https://pyaegean.xyz/benchmarks

Enables the paradigm table, which is utilized by the lemma OOV rescue lever.

```python
use_paradigms()
```

--------------------------------

### keyness(target: Any, reference: Any, *, kind: str = 'words', min_target: int = 2, smoothing: float = 0.5) -> list[KeynessRow]

Source: https://pyaegean.xyz/api/analysis

Calculates key items of target against reference, sorted by G² descending.

```APIDOC
## keyness

### Description
Calculates key items of target against reference, strongest first. Items are sorted by G² descending.

### Parameters
- **target** (Any) - Required - The target corpus or data.
- **reference** (Any) - Required - The reference corpus or data.
- **kind** (str) - Optional - Default 'words'.
- **min_target** (int) - Optional - Default 2.
- **smoothing** (float) - Optional - Default 0.5.
```

--------------------------------

### greek_pipeline(text: str) -> list[dict[str, Any]]

Source: https://pyaegean.xyz/api/mcp

Runs the baseline Greek NLP pipeline on the provided text.

```APIDOC
## greek_pipeline

### Description
Run the (baseline, offline) Greek NLP pipeline: one row per token.

### Parameters
- **text** (str) - Required - The Greek text to process.
```

--------------------------------

### Evaluate PapyGreek Parsing Performance

Source: https://pyaegean.xyz/benchmarks

Commands to run the PapyGreek evaluation fold using either the CLI or the Python API.

```bash
aegean greek eval papygreek
```

```python
greek.evaluate_on_papygreek()
```

--------------------------------

### Define Script interface

Source: https://pyaegean.xyz/api/core

Abstract methods and properties for implementing new writing systems.

```python
sign_inventory: SignInventory
```

```python
tokenize(raw: str) -> list[Token]
```

--------------------------------

### Load Bundled JSON

Source: https://pyaegean.xyz/api/data

Loads a JSON file that is shipped directly within the package wheel.

```python
load_bundled_json(*parts: str) -> Any
```

--------------------------------

### Load I.Sicily inscriptions

Source: https://pyaegean.xyz/api/scripts-greek

Loads the I.Sicily Greek inscriptions as a corpus.

```python
load_isicily() -> Any
```

--------------------------------

### Load EDH inscriptions

Source: https://pyaegean.xyz/api/scripts-greek

Loads the EDH Ancient-Greek inscriptions as a corpus.

```python
load_edh() -> Any
```

--------------------------------

### write_epidoc

Source: https://pyaegean.xyz/api/io

Write EpiDoc TEI XML to disk.

```APIDOC
## write_epidoc(obj: Corpus | Document, path: str | Path) -> None

### Description
Write EpiDoc TEI XML to disk. A single `Document` is written to the file `path`; a `Corpus` is written as one `{id}.xml` file per document into the directory `path`.
```

--------------------------------

### List providers

Source: https://pyaegean.xyz/api/ai

Returns a sorted list of names for all registered providers.

```python
list_providers() -> list[str]
```

--------------------------------

### Combine corpora via CLI

Source: https://pyaegean.xyz/large-corpora

Concatenate multiple corpus files into a single database file using the aegean CLI.

```bash
$ aegean combine tlg0012.tlg001 tlg0012.tlg002 -o homer.db   # all of Homer in one db
```

--------------------------------

### Load a bundled corpus

Source: https://pyaegean.xyz/

Load a corpus like Linear A and access inscription tokens offline.

```python
import aegean

corpus = aegean.load("lineara")
ht13 = corpus.get("HT13")
[t.text for t in ht13.tokens][:6]
# ['KA-U-DE-TA', 'VIN', '𐄁', 'TE', '𐄁', 'RE-ZA']
```

--------------------------------

### Project to spaCy

Source: https://pyaegean.xyz/api/io

Projects an immutable canonical document into a spaCy Doc.

```python
to_spacy(document: InteropDocument, *, vocab: Any = None, allow_lossy: bool = False) -> InteropResult[Any]
```

--------------------------------

### load_gzip_json

Source: https://pyaegean.xyz/api/data

Decompresses and parses a fetched .json.gz index file with memory safety limits.

```APIDOC
## load_gzip_json(path: str | Path, *, max_bytes: int = _MAX_GZIP_JSON_BYTES) -> Any

### Description
gzip-decompress and parse a fetched .json.gz index, capping the decompressed size to prevent memory exhaustion.

### Parameters
- **path** (str | Path) - Required - The filesystem path to the gzipped JSON file.
- **max_bytes** (int) - Optional - The maximum allowed size in bytes for the decompressed data.
```

--------------------------------

### greek_explain(text: str) -> list[dict[str, Any]]

Source: https://pyaegean.xyz/api/mcp

Provides an explanation of the Greek NLP pipeline results for each token.

```APIDOC
## greek_explain

### Description
Explain what the (baseline, offline) Greek pipeline did to each token.

### Parameters
- **text** (str) - Required - The Greek text to explain.
```

--------------------------------

### from_cltk

Source: https://pyaegean.xyz/api/io

Imports a CLTK Doc and validates its native state.

```APIDOC
## from_cltk(doc: Any, *, sidecar: str | None = None, allow_lossy: bool = False) -> InteropResult[InteropDocument]

### Description
Import a real CLTK Doc and validate its complete native state.

### Parameters
- **doc** (Any) - Required - The CLTK document object.
- **sidecar** (str | None) - Optional - The sidecar data string.
- **allow_lossy** (bool) - Optional - Whether to allow lossy conversion.

### Returns
- **InteropResult[InteropDocument]** - The result containing the document and metadata.
```

--------------------------------

### list_corpora

Source: https://pyaegean.xyz/api/mcp

Lists the corpora that can be loaded by name. Includes both bundled corpora and those that download to the local data store on first use.

```APIDOC
## list_corpora

### Description
List the corpora that can be loaded by name. Five are bundled and load offline; the rest download into the local data store on first use.

### Signature
`list_corpora() -> list[str]`
```

--------------------------------

### Retrieve reproducibility manifest

Source: https://pyaegean.xyz/api/data

Returns a dictionary containing metadata for all datasets, including sha256 hashes and presence status for reproducibility tracking.

```python
versions() -> dict[str, Any]
```

--------------------------------

### Copy SignInventory

Source: https://pyaegean.xyz/api/aegean

Creates an independent copy of the inventory, ensuring mutable attributes are not shared between instances.

```python
copy() -> 'SignInventory'
```

--------------------------------

### load_bundled_json

Source: https://pyaegean.xyz/api/data

Loads a JSON file shipped inside the package wheel.

```APIDOC
## load_bundled_json(*parts: str) -> Any

### Description
Load a JSON file shipped inside the wheel.

### Parameters
- **parts** (str) - Required - Variable number of path segments representing the file location within the package.
```

--------------------------------

### to_sql()

Source: https://pyaegean.xyz/api/core

Writes the corpus to a SQLite database.

```APIDOC
## to_sql(path, *, fts=True, append=False)

### Description
Writes the corpus to a SQLite database. Documents and tokens become queryable rows.

### Parameters
- **path** (str | Path) - Required - Path to the SQLite database file.
- **fts** (bool) - Optional - Enable FTS5 text indexing.
- **append** (bool) - Optional - Upsert documents into an existing database.

### Signature
`to_sql(path: str | Path, *, fts: bool = True, append: bool = False) -> None`
```

--------------------------------

### ExploratoryResult Methods

Source: https://pyaegean.xyz/api/ai

Methods for interacting with and serializing ExploratoryResult objects.

```python
labeled() -> str
```

```python
trace() -> str
```

```python
to_dict() -> dict[str, Any]
```

```python
to_json(path: str | Path | None = None, *, indent: int | None = 2) -> str | None
```

```python
from_dict(data: dict[str, Any]) -> 'ExploratoryResult'
```

--------------------------------

### Balance Check

Source: https://pyaegean.xyz/api/analysis

Verifies document totals against summed item lines using script-specific markers.

```python
balance_check(document: Document) -> list[BalanceCheck]
```

--------------------------------

### greek_reading(word: str) -> tuple[str, str] | None

Source: https://pyaegean.xyz/api/scripts-cypriot

Retrieves the Greek lemma and gloss for a transliterated Cypriot word.

```APIDOC
## greek_reading(word: str) -> tuple[str, str] | None

### Description
Provides the Greek (lemma, gloss) for a transliterated Cypriot word. Returns None if no reading is available.

### Parameters
- **word** (str) - Required - The transliterated Cypriot word.

### Returns
- (tuple[str, str] | None) - A tuple containing the lemma and gloss, or None.
```

--------------------------------

### SiteCoord Properties

Source: https://pyaegean.xyz/api/geo

Accessors for Pleiades URI and contested provenance status.

```python
pleiades_uri: str | None
```

```python
is_contested: bool
```

--------------------------------

### Retrieve Site Coordinates

Source: https://pyaegean.xyz/api/geo

Returns the bundled gazetteer mapping site labels to SiteCoord objects.

```python
site_coordinates() -> dict[str, SiteCoord]
```

--------------------------------

### Load EpiDoc TEI

Source: https://pyaegean.xyz/api/io

Loads token-carrier EpiDoc TEI into a Corpus.

```python
from_epidoc(source: str | Path, *, script_id: str = 'greek') -> Corpus
```

--------------------------------

### Build corpus from text file

Source: https://pyaegean.xyz/api/io

Creates a Corpus object from a single plain-text file.

```python
from_text_file(path: str | Path, *, script_id: str = 'greek', split: str = 'whole', doc_id: str | None = None, encoding: str = 'utf-8', meta: dict[str, str] | None = None) -> 'Corpus'
```

--------------------------------

### Load IIP inscriptions

Source: https://pyaegean.xyz/api/scripts-greek

Loads the IIP Greek inscriptions as a corpus.

```python
load_iip() -> Any
```

--------------------------------

### Import from spaCy

Source: https://pyaegean.xyz/api/io

Imports a spaCy Doc and validates its native state.

```python
from_spacy(doc: Any, *, sidecar: str | None = None, allow_lossy: bool = False) -> InteropResult[InteropDocument]
```

--------------------------------

### from_text_file

Source: https://pyaegean.xyz/api/io

Builds a Corpus object from a plain-text file.

```APIDOC
## from_text_file(path: str | Path, *, script_id: str = 'greek', split: str = 'whole', doc_id: str | None = None, encoding: str = 'utf-8', meta: dict[str, str] | None = None) -> 'Corpus'

### Description
Builds a Corpus from a plain-text file.
```

--------------------------------

### aegean.cache.enable

Source: https://pyaegean.xyz/api/cache

Enables the persistent cache. If no path is provided, it uses the default cache file location.

```APIDOC
## enable(path: str | Path | None = None) -> DiskCache

### Description
Turn the cache on (idempotent), at `path` or the default cache file.

### Parameters
- **path** (str | Path | None) - Optional - The file system path to the sqlite cache file.
```

--------------------------------

### load_nt()

Source: https://pyaegean.xyz/api/scripts-greek

Loads the Greek New Testament (Nestle 1904) as an annotated corpus.

```APIDOC
## load_nt(book=None, ref=None, force=False)

### Description
Loads the Greek New Testament (Nestle 1904) as an annotated Corpus. Allows filtering by book and specific references.

### Parameters
- **book** (str) - Optional - Selects one book by name or abbreviation.
- **ref** (str) - Optional - Selects a specific chapter, verse, or range within a book.
- **force** (bool) - Optional - Force reload of the corpus.
```

--------------------------------

### Generate Reference Key

Source: https://pyaegean.xyz/api/analysis

Creates a normalized comparison key for words by removing hyphens, lowercasing, and optionally stripping notation marks.

```python
reference_key(raw_word: str, strip_notation: bool = True) -> str
```

--------------------------------

### Run Greek NLP Pipeline

Source: https://pyaegean.xyz/api/mcp

Processes text through the baseline Greek NLP pipeline, returning token-level analysis.

```python
greek_pipeline(text: str) -> list[dict[str, Any]]
```

--------------------------------

### Project to CLTK

Source: https://pyaegean.xyz/api/io

Projects an immutable canonical document into a CLTK Doc.

```python
to_cltk(document: InteropDocument, *, allow_lossy: bool = False) -> InteropResult[Any]
```

--------------------------------

### Check Present Paths

Source: https://pyaegean.xyz/api/data

Determines which of the expected on-disk artifacts for a dataset specification are currently present in the cache.

```python
present_paths(spec: DataSpec, root: Path) -> list[Path]
```

--------------------------------

### build_word_index

Source: https://pyaegean.xyz/api/analysis

Indexes every word token to the documents it appears in.

```APIDOC
## build_word_index(documents: Iterable[Document]) -> dict[str, WordEntry]

### Description
Index every word token to the documents it appears in. Numerals, logograms, and punctuation are skipped.
```

--------------------------------

### metrology_profile

Source: https://pyaegean.xyz/api/analysis

Builds a corpus metrology profile based on fraction census and commodity counts.

```APIDOC
## metrology_profile(corpus: Any, *, min_entries: int = 3) -> MetrologyProfile

### Description
Build the corpus metrology profile (fraction census + per-commodity counted-vs-measured), iterating physical lines. A commodity needs min_entries to get a profile.
```

--------------------------------

### Run Compound Query

Source: https://pyaegean.xyz/api/aegean

Executes a predicate engine query over the corpus. Returns results containing provenance and summary data for citation.

```python
query(filters: Sequence[FilterRow], output: Output = 'inscriptions', *, annotated_ids: set[str] | None = None) -> QueryResults
```

--------------------------------

### InteropResult document Property

Source: https://pyaegean.xyz/api/io

Compatibility alias used by adapter callers to retrieve the document.

```python
document: T
```

--------------------------------

### gloss(word: str) -> str | None

Source: https://pyaegean.xyz/api/scripts-cypriot

Retrieves a short English gloss for a given Cypriot word.

```APIDOC
## gloss(word: str) -> str | None

### Description
Returns a short English gloss for a Cypriot word. Returns None if the word is not found in the lexicon.

### Parameters
- **word** (str) - Required - The Cypriot word to look up.

### Returns
- (str | None) - The English gloss or None.
```

--------------------------------

### Load Corpus from SQLite

Source: https://pyaegean.xyz/api/db

Reconstructs a Corpus from a SQLite database, restoring documents, sign inventory, and provenance.

```python
from_sqlite(path: str | Path, *, progress: Callable[[int, int], None] | None = None) -> Corpus
```

--------------------------------

### Enumerate versioned cache paths

Source: https://pyaegean.xyz/api/data

Retrieves all on-disk paths associated with a dataset's versioned fetches for accounting or removal purposes.

```python
versioned_entry_paths(name: str, root: Path, *, version: str | None = None) -> list[Path]
```

--------------------------------

### evidence_block

Source: https://pyaegean.xyz/api/ai

Formats grounding evidence into a compact bulleted list.

```APIDOC
## evidence_block(evidence: Iterable[str | GroundingItem]) -> str

### Description
Renders a collection of grounding evidence items into a compact, labeled bullet list string suitable for model prompts.

### Parameters
- **evidence** (Iterable[str | GroundingItem]) - Required - The collection of evidence items to format.
```

--------------------------------

### Configure library verbosity

Source: https://pyaegean.xyz/api/aegean

Sets the logging level for the library, usable as a function call or context manager.

```python
set_verbosity(level: str | int) -> _Verbosity
```

--------------------------------

### Load Gzip JSON

Source: https://pyaegean.xyz/api/data

Decompresses and parses a fetched .json.gz file, with a configurable limit on decompressed size to prevent memory exhaustion.

```python
load_gzip_json(path: str | Path, *, max_bytes: int = _MAX_GZIP_JSON_BYTES) -> Any
```

--------------------------------

### Group documents by hand

Source: https://pyaegean.xyz/api/analysis

Groups documents by hand attribution string, providing a site and series breakdown. Documents without recorded hands are excluded.

```python
by_hand(corpus: Any, *, min_docs: int = 1) -> list[HandGroup]
```

--------------------------------

### Build a corpus from text

Source: https://pyaegean.xyz/api

Create a Corpus object from a string using the aegean.io module.

```python
from aegean import io

corpus = io.from_text("μῆνιν ἄειδε θεὰ Πηληϊάδεω Ἀχιλῆος", doc_id="iliad")
print(len(corpus), "document(s),", sum(len(d.words) for d in corpus), "words")
# 1 document(s), 5 words
```
Tokens:
Raw