Agents and runs¶
mcaligner run applies the rules, then runs rounds of two
pydantic-ai agents over a writable alignment set:
Aligner (strong tier, default
anthropic:claude-opus-5-5). Works on pairs it has not seen and on pairs with links below the threshold (0.8), several pairs per task.Scorer (efficient tier, default
anthropic:claude-sonnet-5-5, optional). Rates the links the aligner set or changed; links it rates below the threshold go back to the aligner in the next round.Rules run again with the new confident links as evidence.
A run stops when nothing is below the threshold, a round changes no pair’s
links, or the round limit (--rounds, default 2) is reached.
What the aligner sees¶
For each pair: both sentences as compact lines (id form lemma UPOS head deprel and glosses from MISC), the settled links (kept), the links to review,
and for each unlinked word how its lemma is linked elsewhere:
## Pair B10K1V3
A: مبارك هو الله ابو ربنا يسوع المسيح: ...
1 مبارك مُبَارَك ADJ 3 nsubj blessed
...
Settled links: 3-3S 0.95 rules, 5-7S 0.95 rules, 6-9S 0.95 rules
Evidence for unlinked words (linked lemmas elsewhere):
A4 أَب: πατήρ×8, πατριά×1, γονεύς×1 (of 11)
B10 Χριστός: مَسِيح×25, المسيح×11, يسوع×5 (of 43, 3 unlinked)
It answers with one line per link, SENT_ID A-B S|P CONFIDENCE, plus
SENT_ID A-B lines for settled links to remove. Code checks every pair with
set_links(..., dry_run=True) and sends any problem back to the model; only a
fully valid answer is written. The scorer answers SENT_ID A-B CONFIDENCE.
Both agents can call read-only MCP tools (get_parallel,
translation_candidates, analyse_form, find_tokens, get_context) when
the prompt is not enough; their results are shown in compact text.
Models and settings¶
mcaligner run ... --model anthropic:claude-sonnet-5-5 # one model for both
mcaligner run ... --aligner-model ... --scorer-model ... # per role
mcaligner run ... --strong-thinking low --no-scorer
All options also live in a YAML settings file (mcaligner settings prints
the defaults): tiers, per-role model, thinking, instructions and
enabled, threshold, rounds, batch_sentences, batch_words,
candidates, misc_keys, guidelines, and the rule settings (including link_punctuation).
Columns and tools¶
The prompt shows each word as id form plus the columns setting (default lemma upos head deprel; --columns lemma,upos,head,deprel,feats,xpos, or none for forms only), then any misc_keys. tools limits the read tools the
agents may call (--tools none, or a list; default all). The instructions describe whatever is shown and available, so
the same code runs ablations such as “no parse” or “with FEATS”.
Guidelines and punctuation¶
The aligner’s and scorer’s instructions include annotation guidelines, so they follow the rules the human
annotators followed. The default is the bundled grc-lat (mcaligner/guidelines/grc-lat.md, a condensed version of
the Ugarit guidelines for Greek-Latin fragments; articles are not aligned). bicross is the BICROSS guidelines of 13 August 2024
for the New Testament manuscripts (articles are aligned with their noun’s translation), which the BICROSS annotators followed. The other bundled files are drafts, not checked against a human alignment: grc-cop (Greek-Coptic, Sahidic with the
Coptic split into articles, auxiliaries and pronouns), grc-ar (Greek-Arabic), lat-ar, grc-syr, syr-ar and got-lat. Use --guidelines PATH (or guidelines: in the settings) for your
own text, or --guidelines none for other language pairs such as Arabic-Greek.
Punctuation is never aligned under these guidelines, so links to punctuation are dropped in code from the aligner’s
answers and the identical rule skips it; the number dropped is in each task’s details.dropped in the report.
--link-punctuation (or rules: {link_punctuation: true}) allows them.
Cost¶
Every run prints tokens and an estimated price per model (list prices from
mcparser.pricing), and appends its full report to <set>.runs.jsonl.
Prompt caching is on by default.
Ephesians 1:1–5 with the other 150 verses as silver evidence, 2 rounds: 6
requests (one per task, no tool calls), about 44k input and 5k output tokens,
$0.18–0.21 (Opus about three quarters of it). Against silver: F1 0.87–0.88
over all links, AER 0.12–0.13; most disagreements were silver errors or
correct links from unsplit Arabic pronoun suffixes. The second round changed
little, so for large runs --rounds 1 is worth considering.