Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

MCAligner logo MCAligner

MCAligner

PyPI version Tests Apache 2.0 licence

Word alignment of parallel texts with a team of LLM agents. MCAligner links the words of two parsed versions of the same text, such as a translation and its source, and writes the links in the Ugarit style (3-5S sure, 12-18P probable). The links can feed a bilingual lexicon.

Code rules settle the near-certain words (identical symbols, transliterated names, words whose translation is overwhelming in the links so far). An aligner agent links the rest in batches, an optional scorer gives every link a confidence, and weak links go back for another round. Every link records which agent made it. All access to the texts goes through the MCP server of MCParser, which also prepares the parsed files, so the same tools work from Claude Desktop.

Installation

MCAligner needs Python 3.11 or later. Install it from PyPI (the --pre flag is needed while it is an alpha release; it also installs MCParser):

pip install --pre mcaligner
export ANTHROPIC_API_KEY=...      # the key for the models you use
mcaligner --version

or with uv, as a command-line tool:

uv tool install --prerelease allow mcaligner

To work from a clone instead:

git clone https://github.com/rbturnbull/mcaligner && cd mcaligner
uv sync          # then prefix the commands below with `uv run`

Quick start

1. Prepare two CoNLL-U files with MCParser. MCAligner needs both texts parsed, with the same sent_id (for example a verse or a fragment) on both sides. MCParser turns raw text into CoNLL-U using a treebank you trust as the examples:

mcparser init john-grc.yaml -o john-grc.conllu -s grc=proiel-grc-train.conllu
mcparser run  john-grc.conllu -s grc=proiel-grc-train.conllu --cheap-first
# the same for the other language

The input is one sentence per line or YAML mapping ids to text. See Preparing files with MCParser and MCParser’s documentation.

2. Align.

mcaligner run -s grc=john-grc.conllu -s cop=john-cop.conllu \
    -a pred=grc,cop,john-aligned.jsonl --target pred --guidelines grc-cop

Try --max-sentences 5 first: the run prints the tokens and estimated cost per model. A run can be repeated to continue where it stopped.

3. Evaluate and export.

mcaligner evaluate john-aligned.jsonl gold.jsonl                  # P/R/F1 and AER
mcaligner lexicon -s grc=... -s cop=... -a pred=grc,cop,john-aligned.jsonl -o lexicon.yaml
mcaligner mcp config -s grc=... -s cop=... -a pred=grc,cop,john-aligned.jsonl   # Claude Desktop

Alignments are JSON Lines; mcparser align import and mcparser align export convert to and from Pharaoh/Ugarit text and YAML.

Guidelines

The agents are given annotation guidelines, and these matter more than anything else we tested. --guidelines takes a bundled name (grc-lat the default, bicross, grc-cop, grc-ar, lat-ar, grc-syr, syr-ar, got-lat), the path of your own file, or none.

Results

On held-out tests (cold start, Opus aligner, Sonnet scorer, two rounds):

Test set

F1 (links)

AER

Cost

BICROSS Greek-Latin, 79 verses, Kreinecker

0.947

0.053

$2.64

BICROSS, against Tilke

0.975

0.025

$2.64

DFHG Greek-Latin, 80 fragments

0.922

0.042

$2.34

The two BICROSS annotators agree with each other at F1 0.946 (AER 0.054), and the DFHG annotators at about 0.927, so the pipeline is at the level of human agreement on both. Details, caveats and ablations (the parse columns do not help; the guidelines do) are in docs/results.md.

Sister projects

  • MCParser: dependency parsing with a team of LLM agents. It prepares the CoNLL-U files that MCAligner aligns.

  • Hexapla: builds static websites for reading and exploring word-aligned manuscript texts from TEI transcriptions, CoNLL-U parses and alignment links such as MCAligner’s.

Documentation

Full documentation: https://rbturnbull.github.io/mcaligner, or ./mkdocs.sh and open docs/_build/html/index.html. Design notes for contributors: AGENTS.md; see also CONTRIBUTING.md.

Development

uv sync --all-groups
uv run pytest      # no network; aim for 100% line and branch coverage

Acknowledgements

European Research Council

The research leading to this software was conducted as part of the BICROSS project (‘The Significance of Bilingual Manuscripts for Detecting Cross-Language Interaction in the New Testament Tradition’), which has received funding from the European Research Council (ERC) under the European Union’s Horizon Europe Research and Innovation Programme (Grant Agreement No. 101043730 – BICROSS – ERC-2021-COG). Funded by the European Union. Views and opinions expressed are however those of the author only and do not necessarily reflect those of the European Union or the European Education and Culture Executive Agency (EACEA). Neither the European Union nor EACEA can be held responsible for them.

Author

Robert Turnbull (Melbourne Data Analytics Platform, University of Melbourne)

Metadata

Release files for mcaligner 0.2.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcaligner 0.2.0a1
File Size Uploaded Provenance Actions
mcaligner-0.2.0a1.tar.gz 326.7 kB Without provenance Details for mcaligner-0.2.0a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcaligner 0.2.0a1
File Interpreter ABI Platform Actions
mcaligner-0.2.0a1-py3-none-any.whl Python 3 none any Details for mcaligner-0.2.0a1-py3-none-any.whl

Total release size: 404.7 kB

Release files / mcaligner-0.2.0a1.tar.gz

Download URL mcaligner-0.2.0a1.tar.gz
Size 326.7 kB
Tags Source
SHA-256 checksum
How to use checksums
57839be952e4135e9430eebb5da9b647ecc431f0e9e7f391a34963330e9f204f
BLAKE2b-256 checksum
How to use checksums
f9c0788865f52ae7b031930361a760ab907ea4f26299cb5419e410c9ec6a9b7f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / mcaligner-0.2.0a1-py3-none-any.whl

Download URL mcaligner-0.2.0a1-py3-none-any.whl
Size 78.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5a1f2280cb36c98d972d13a435a46727a21cb03c623f72d5d67ced2666f409eb
BLAKE2b-256 checksum
How to use checksums
eda247c1a1865470ac93dabf11f6eff9331863e642f02389e13f4c660053606d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for mcaligner 0.2.0a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page