This release is a pre-release and may not be stable for production use.
MCAligner
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
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
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.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.