API reference

Which lemmas translate which: a translation table built from alignment sets.

TranslationTable counts, for every lemma of every aligned source, which lemmas of the other source its words are linked to. It is the same count as MCParser’s translation_candidates tool (a word’s lemma falls back to its form; only links with at least min_confidence count), but built in one pass over the sets, so code can look up thousands of words cheaply. The counts of each sentence are kept, so a sentence’s own links can be left out (exclude, a sent_id) when the table is used as evidence for that sentence pair.

build_lexicon() turns the table into the exported lexicon.

mcaligner.lexicon.lemma_of(word)[source]

The word’s lemma, or its form if the lemma is empty (as in MCParser).

Parameters:

word (Token)

Return type:

str

class mcaligner.lexicon.Entry(occurrences=0, unaligned=0, pos=<factory>, translations=<factory>, by_sentence=<factory>, occurrences_by_sentence=<factory>, unaligned_by_sentence=<factory>)[source]

Bases: object

One lemma of one source.

Parameters:
  • occurrences (int)

  • unaligned (int)

  • pos (Counter[str])

  • translations (Counter[str])

  • by_sentence (dict[str, Counter[str]])

  • occurrences_by_sentence (Counter[str])

  • unaligned_by_sentence (Counter[str])

by_sentence: dict[str, Counter[str]]

Translations counted in each sentence (to leave one out).

candidates(exclude=None)[source]

Translations, without those counted in sentence exclude.

Parameters:

exclude (str | None)

Return type:

Counter[str]

class mcaligner.lexicon.TranslationTable(store, alignments=None, min_confidence=0.0)[source]

Bases: object

Lemma → linked-lemma counts for every source of the given alignment sets (default all).

Parameters:
  • store (CorpusStore)

  • alignments (Iterable[str] | None)

  • min_confidence (float)

entries: dict[str, dict[str, Entry]]

source name → lemma → entry.

pos: dict[str, dict[str, Counter[str]]]

source name → lemma → UPOS counts over the whole source (aligned or not).

mcaligner.lexicon.build_lexicon(table, min_count=1, top=None)[source]

{source: {lemma: {part_of_speech, occurrences, unaligned, alignments: {lemma: {count, part_of_speech}}}}}.

Lemmas are sorted; translations by count (most frequent first), keeping those seen at least min_count times (and at most top of them).

Parameters:
Return type:

dict[str, dict[str, dict]]

Link near-certain word pairs in code, without a model.

Rules only add links between words that have no link yet, and only when the match is unique in the sentence pair. They are:

  • identical — numerals and symbols (or other forms without letters) written the same on both sides; punctuation only with link_punctuation, since alignment guidelines such as Ugarit’s never align it;

  • names — a proper noun on one side whose romanisation matches a word on the other side (consonant skeletons; the Arabic MISC LTranslit= / Translit= are used when present, Greek is romanised from the lemma);

  • lexicon — a lemma whose translation is overwhelming in the evidence (at least min_count linked occurrences, and that translation for at least min_share of all its occurrences, unlinked ones included), when the translation occurs exactly once in the other sentence and the lemma exactly once in this one.

Evidence for the lexicon rule is a TranslationTable over the given alignment sets, counting only links with confidence of at least evidence_confidence (read-only sets default to 1.0). Rules write links with confidence RULE_CONFIDENCE, below that, so they never feed themselves; the sentence being linked is always left out of the evidence.

measure() proposes links for the pairs of a reference set (starting from no links, as at the start of a run) and reports each rule’s precision against it.

mcaligner.rules.EVIDENCE_CONFIDENCE = 0.96

Links count as lexicon evidence from this confidence (above what rules set).

mcaligner.rules.FUNCTION_TAGS = frozenset({'ADP', 'AUX', 'CCONJ', 'DET', 'PART', 'PRON', 'PUNCT', 'SCONJ', 'SYM'})

Words that are never the counterpart of a proper name.

mcaligner.rules.is_punctuation(word)[source]

UPOS PUNCT, or a form without any letter or digit.

Parameters:

word (Token)

Return type:

bool

class mcaligner.rules.RuleSettings(*, min_count=5, min_share=0.95, evidence_confidence=0.96, name_similarity=0.9, link_punctuation=False, rules=['identical', 'names', 'lexicon'])[source]

Bases: BaseModel

Parameters:
  • min_count (int)

  • min_share (float)

  • evidence_confidence (float)

  • name_similarity (float)

  • link_punctuation (bool)

  • rules (list[str])

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.rules.Proposal(*, sent_id, source, target, rule, confidence, reason)[source]

Bases: BaseModel

Parameters:
  • sent_id (str)

  • source (str)

  • target (str)

  • rule (str)

  • confidence (float)

  • reason (str)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.rules.RuleCount(*, links=0, correct=None, precision=None)[source]

Bases: BaseModel

Parameters:
  • links (int)

  • correct (int | None)

  • precision (float | None)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.rules.RulesReport(*, sentences=0, rules=<factory>, reference_links=None)[source]

Bases: BaseModel

Parameters:
  • sentences (int)

  • rules (dict[str, RuleCount])

  • reference_links (int | None)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mcaligner.rules.romanise(text)[source]

Lowercase ASCII letters: accents stripped, Greek transliterated, other scripts dropped.

Parameters:

text (str)

Return type:

str

mcaligner.rules.skeleton(text)[source]

The consonants of a romanised word in broad classes, doubles collapsed (Ἔφεσος → bs, ʾafasus → bs).

Parameters:

text (str)

Return type:

str

mcaligner.rules.name_keys(word)[source]

Skeletons of a word’s transliterations, lemma and form.

Parameters:

word (Token)

Return type:

set[str]

mcaligner.rules.similar(keys_a, keys_b, threshold)[source]

The best similarity of two skeleton sets; skeletons shorter than 3 must be equal.

Parameters:
  • keys_a (set[str])

  • keys_b (set[str])

  • threshold (float)

Return type:

float

class mcaligner.rules.Rules(store, target, settings=None, evidence=None)[source]

Bases: object

Applies the rules to a writable alignment set; evidence names the sets used by the lexicon rule (default all).

Parameters:
  • store (CorpusStore)

  • target (str)

  • settings (RuleSettings | None)

  • evidence (Iterable[str] | None)

refresh()[source]

Rebuild the evidence on next use (after links were added elsewhere).

Return type:

None

lexicon(sent_id, a, b, all_a, all_b)[source]

Lemmas with an overwhelming translation that occurs exactly once in the other sentence.

Parameters:
  • sent_id (str)

  • a (list[Token])

  • b (list[Token])

  • all_a (list[Token])

  • all_b (list[Token])

Return type:

list[Proposal]

propose(sent_id, links=None)[source]

Links the rules would add to a sentence pair that already has links (default: its current links).

Parameters:
  • sent_id (str)

  • links (list[Link] | None)

Return type:

list[Proposal]

apply(sent_ids=None)[source]

Add the rules’ links to the target set (default: every sentence of source A that is in source B).

Parameters:

sent_ids (Iterable[str] | None)

Return type:

RulesReport

mcaligner.rules.measure(rules, reference, sent_ids=None)[source]

Propose links for the pairs of reference from scratch; count those in reference (S or P) as correct.

Parameters:
  • rules (Rules)

  • reference (str)

  • sent_ids (Iterable[str] | None)

Return type:

tuple[RulesReport, list[tuple[Proposal, bool]]]

Score predicted word links against gold links.

With A the predicted links, S the gold sure links and P the gold sure and probable links (S ⊆ P), the report gives:

  • precision, recall and F1 over sure links (predicted S links against S);

  • precision, recall and F1 over all links (A against P, ignoring S/P);

  • the alignment error rate (Och & Ney 2003), AER = 1 − (|A∩S| + |A∩P|) / (|A| + |S|).

Links are compared by their word ids (3-5). Scores are given per sentence pair and over all pairs (micro-averaged: counts are summed first).

class mcaligner.evaluate.Counts(*, predicted=0, predicted_sure=0, gold_sure=0, gold_all=0, sure_correct=0, all_correct=0, a_and_s=0)[source]

Bases: BaseModel

Link counts for one sentence pair (or summed over several).

Parameters:
  • predicted (int)

  • predicted_sure (int)

  • gold_sure (int)

  • gold_all (int)

  • sure_correct (int)

  • all_correct (int)

  • a_and_s (int)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.evaluate.Scores(*, precision, recall, f1)[source]

Bases: BaseModel

Parameters:
  • precision (float)

  • recall (float)

  • f1 (float)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.evaluate.PairScore(*, sent_id, counts, sure, all, aer)[source]

Bases: BaseModel

Parameters:
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.evaluate.EvaluationReport(*, sentences, total, pairs)[source]

Bases: BaseModel

Parameters:
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

An alignment JSONL file as links per sent_id; links without a confidence are kept.

Parameters:
  • path (Path | str)

  • min_confidence (float)

Return type:

dict[str, list[Link]]

mcaligner.evaluate.evaluate(predicted, gold, annotated_only=False)[source]

Score every gold pair (a pair missing from the predictions has no links).

Pairs that are not in the gold file are ignored: gold alignments often cover only part of a text. With annotated_only only pairs with at least one predicted link count, which measures a partial run on what it has done.

Parameters:
  • predicted (dict[str, list[Link]])

  • gold (dict[str, list[Link]])

  • annotated_only (bool)

Return type:

EvaluationReport

mcaligner.evaluate.format_report(report, per_sentence=False)[source]

A plain-text table: P/R/F1 over sure and all links, and AER.

Parameters:
Return type:

str

Run settings: which model each agent uses, thresholds, batching and rules.

There are two agents: the aligner (links words; strong tier by default) and the optional scorer (rates the aligner’s links; efficient tier). The tiers are a strong, an efficient and a light model, as in MCParser. Settings can be loaded from YAML, e.g.:

strong_model: anthropic:claude-opus-5-5
efficient_model: anthropic:claude-sonnet-5-5
light_model: anthropic:claude-haiku-5-5
efficient_roles: [scorer]
threshold: 0.8             # links below this are revisited
rounds: 2
batch_sentences: 5         # sentence pairs per agent task
rules:
  min_count: 5
  min_share: 0.95
roles:
  aligner:
    thinking: low
    instructions: Link Arabic clitic prepositions to the Greek preposition.
  scorer:
    enabled: false
mcaligner.settings.Thinking

False (off), True (provider default) or a level.

Type:

Reasoning effort

alias of bool | Literal[‘minimal’, ‘low’, ‘medium’, ‘high’, ‘xhigh’]

mcaligner.settings.parse_thinking(value)[source]

Parse a command-line thinking value: off, on, or a level.

Parameters:

value (str)

Return type:

bool | Literal[‘minimal’, ‘low’, ‘medium’, ‘high’, ‘xhigh’]

class mcaligner.settings.RoleSettings(*, model=None, thinking=None, enabled=True, instructions=None)[source]

Bases: BaseModel

Parameters:
  • model (str | None)

  • thinking (bool | Literal['minimal', 'low', 'medium', 'high', 'xhigh'] | None)

  • enabled (bool)

  • instructions (str | None)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mcaligner.settings.COLUMNS = ('lemma', 'upos', 'xpos', 'feats', 'head', 'deprel')

Word columns that can be shown in the prompt, in this order.

mcaligner.settings.TOOL_NAMES = frozenset({'alignment_stats', 'analyse_form', 'category_links', 'find_tokens', 'get_context', 'get_parallel', 'lemma_links', 'link_examples', 'pair_words', 'similar_pairs', 'translation_candidates'})

The read tools the agents may be given (see mcaligner.mcp).

mcaligner.settings.GUIDELINES = PosixPath('/home/runner/work/mcaligner/mcaligner/mcaligner/guidelines')

Bundled annotation guidelines (<name>.md).

mcaligner.settings.guideline_path(name)[source]

The file for a bundled guideline name or a path, or None.

Parameters:

name (str)

Return type:

Path | None

class mcaligner.settings.Settings(*, strong_model='anthropic:claude-opus-5-5', efficient_model='anthropic:claude-sonnet-5-5', light_model='anthropic:claude-haiku-5-5', efficient_roles=['scorer'], light_roles=<factory>, strong_thinking=None, efficient_thinking=None, light_thinking=None, model=None, threshold=0.8, rounds=2, concurrency=1, request_limit=30, cache=True, batch_sentences=5, batch_words=150, candidates=3, evidence_confidence=0.8, misc_keys=['Gloss'], columns=['lemma', 'upos', 'head', 'deprel'], tools=None, guidelines='grc-lat', rules=<factory>, roles=<factory>)[source]

Bases: BaseModel

Parameters:
  • strong_model (str)

  • efficient_model (str)

  • light_model (str)

  • efficient_roles (list[str])

  • light_roles (list[str])

  • strong_thinking (bool | Literal['minimal', 'low', 'medium', 'high', 'xhigh'] | None)

  • efficient_thinking (bool | Literal['minimal', 'low', 'medium', 'high', 'xhigh'] | None)

  • light_thinking (bool | Literal['minimal', 'low', 'medium', 'high', 'xhigh'] | None)

  • model (str | None)

  • threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • rounds (Annotated[int, Ge(ge=1)])

  • concurrency (Annotated[int, Ge(ge=1)])

  • request_limit (Annotated[int, Ge(ge=1)])

  • cache (bool)

  • batch_sentences (Annotated[int, Ge(ge=1)])

  • batch_words (Annotated[int, Ge(ge=1)])

  • candidates (Annotated[int, Ge(ge=0)])

  • evidence_confidence (Annotated[float, Ge(ge=0), Le(le=1)])

  • misc_keys (list[str])

  • columns (list[str])

  • tools (list[str] | None)

  • guidelines (str | None)

  • rules (RuleSettings)

  • roles (dict[str, RoleSettings])

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

with_overrides(model=None, role_models=None, scorer=None, link_punctuation=None, **fields)[source]

A copy with command-line overrides applied (None values are ignored).

Parameters:
  • model (str | None)

  • role_models (dict[str, str | None] | None)

  • scorer (bool | None)

  • link_punctuation (bool | None)

  • fields (object)

Return type:

Settings

The rules → align → score loop over a writable alignment set.

Before the first round, code links what is near-certain (see mcaligner.rules). Then each round:

  1. Align. The aligner works on pairs it has not seen yet and on pairs with links below the threshold, in batches of several pairs per task. Links at or above the threshold are shown as settled and kept.

  2. Score (optional). The scorer rates the links the aligner set or changed; links it rates below the threshold go back to the aligner next round.

  3. Rules run again: confident new links are now evidence for the lexicon rule.

Rounds stop when no link is below the threshold, a round changes nothing, or the round limit is reached. Every task is one model request when the evidence in the prompt is enough (the agents may call read tools for more).

class mcaligner.pipeline.TaskResult(*, round, role, sent_ids, summary=None, error=None, details=Details(requests=0, tools={}, retries=[], dropped=0))[source]

Bases: BaseModel

Parameters:
  • round (int)

  • role (str)

  • sent_ids (list[str])

  • summary (str | None)

  • error (str | None)

  • details (Details)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.pipeline.RoundReport(*, round, aligned, scored, tasks, changed, rule_links, low_confidence)[source]

Bases: BaseModel

Parameters:
  • round (int)

  • aligned (int)

  • scored (int)

  • tasks (int)

  • changed (int)

  • rule_links (int)

  • low_confidence (int)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.pipeline.RunReport(*, target, pairs, links, low_confidence, mean_confidence, rounds, rules, tasks, total, usage)[source]

Bases: BaseModel

Parameters:
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.pipeline.Pipeline(store, target, team, settings, sent_ids=None, evidence=None, progress=None)[source]

Bases: object

Runs rules, aligner and scorer rounds over one writable alignment set.

sent_ids restricts the work to some pairs (default: every sentence of source A that is also in source B); evidence names the alignment sets used as translation evidence (default all); progress receives a line of text after every task and round.

Parameters:
  • store (CorpusStore)

  • target (str)

  • team (AlignerTeam)

  • settings (Settings)

  • sent_ids (list[str] | None)

  • evidence (list[str] | None)

  • progress (Callable[[str], None] | None)

scored: set[tuple[str, str, bool, float]]

Links the scorer has rated (with the S/P and confidence it gave), so they are not rated again.

to_align()[source]

Pairs the aligner has not seen, and pairs with links below the threshold.

Return type:

list[PairItem]

to_score()[source]

Pairs with links that the aligner set or changed and the scorer has not rated.

Return type:

list[PairItem]

batches(items)[source]

Tasks of at most batch_sentences pairs and batch_words words.

Parameters:

items (list[PairItem])

Return type:

list[list[PairItem]]

changed_since(seq)[source]

Pairs whose links an agent (not the rules) changed after history entry seq.

Parameters:

seq (int)

Return type:

int

async align()[source]

Run the aligner where needed. Returns (pairs, tasks).

Return type:

tuple[int, int]

async score()[source]

Run the scorer on the aligner’s unrated links. Returns (pairs, tasks).

Return type:

tuple[int, int]

async run(rounds=None)[source]

Apply the rules, then run up to rounds align/score rounds (default from the settings).

Parameters:

rounds (int | None)

Return type:

RunReport

The pydantic-ai agents (aligner, scorer), sharing one MCP connection to the store.

class mcaligner.agents.team.Details(*, requests=0, tools=<factory>, retries=<factory>, dropped=0)[source]

Bases: BaseModel

What happened inside one agent task.

Parameters:
  • requests (int)

  • tools (dict[str, int])

  • retries (list[str])

  • dropped (int)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.agents.team.ModelUsage(*, tasks=0, requests=0, input_tokens=0, cache_read_tokens=0, cache_write_tokens=0, output_tokens=0, cost=None)[source]

Bases: BaseModel

Token use of one model over a run.

Parameters:
  • tasks (int)

  • requests (int)

  • input_tokens (int)

  • cache_read_tokens (int)

  • cache_write_tokens (int)

  • output_tokens (int)

  • cost (float | None)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.agents.team.AlignerTeam(store, target, settings, models=None, toolset=None)[source]

Bases: object

Builds and runs the agents for one writable alignment set (target).

By default the agents reach the store through an in-process MCP server; pass toolset to use another MCP connection. models maps a role (or "*") to a model name or instance, overriding the settings; tests use it for scripted models.

Parameters:
  • store (CorpusStore)

  • target (str)

  • settings (Settings)

  • models (Mapping[str, Model | str] | None)

  • toolset (AbstractToolset[Any] | None)

usage: dict[str, ModelUsage]

Token use and estimated cost per model.

async run(role, prompt, batch, details=None)[source]

Run role on a task; the answer is applied when it is accepted.

If details is given, the task’s requests, tool calls (by tool) and the messages that made the model retry are added to it.

Parameters:
Return type:

Alignment | Scores

total()[source]

Usage summed over all models (cost is None if any model has no price).

Return type:

ModelUsage

Compact answers from the agents, checked and applied in code.

The aligner answers with one line per link, the scorer with one line per rating:

<id> 3-5 S 0.95              aligner: SENT_ID A-B S|P CONFIDENCE
<id> 3-5 0.9                 scorer:  SENT_ID A-B CONFIDENCE

Nothing is written until the whole answer is valid: unknown pairs, malformed lines and links to words that do not exist (checked with set_links(..., dry_run=True)) go back to the model as a retry with the list of problems.

class mcaligner.agents.outputs.Alignment(*, links, remove='', summary='')[source]

Bases: BaseModel

Your answer: the links of the sentence pairs.

Parameters:
  • links (str)

  • remove (str)

  • summary (str)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.agents.outputs.Scores(*, scores, summary='')[source]

Bases: BaseModel

Your answer: a confidence for each link to score.

Parameters:
  • scores (str)

  • summary (str)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcaligner.agents.outputs.TaskBatch(target, sent_ids, settled=<factory>, review=<factory>, dropped=0)[source]

Bases: object

The pairs of one task; passed to the agent run as its dependencies.

Parameters:
  • target (str)

  • sent_ids (list[str])

  • settled (dict[str, list[Link]])

  • review (dict[str, list[Link]])

  • dropped (int)

settled: dict[str, list[Link]]

the links shown as settled, per pair (they are kept).

Type:

Aligner

review: dict[str, list[Link]]

the links to score, per pair.

Type:

Scorer

dropped: int = 0

links to punctuation that code removed from the answer.

Type:

Aligner

SENT_ID A-B S|P CONFIDENCE lines as links per pair, plus error messages.

Parameters:
Return type:

tuple[dict[str, list[Link]], list[str]]

mcaligner.agents.outputs.parse_scores(text, batch)[source]

SENT_ID A-B CONFIDENCE lines as {link key: confidence} per pair, plus error messages.

Parameters:
Return type:

tuple[dict[str, dict[str, float]], list[str]]

class mcaligner.agents.outputs.Applier(store, link_punctuation=False)[source]

Bases: object

Checks an agent’s answer against the store, then applies it.

Parameters:
  • store (CorpusStore)

  • link_punctuation (bool)

without_punctuation(batch, links)[source]

The answer’s links without those that touch punctuation (counted in batch.dropped).

Parameters:
  • batch (TaskBatch)

  • links (dict[str, list[Link]])

Return type:

dict[str, list[Link]]

merged(batch, sent_id, links, removals)[source]

Settled links (minus removals) plus the answer’s links (which win on the same word pair).

Parameters:
  • batch (TaskBatch)

  • sent_id (str)

  • links (list[Link])

  • removals (set[str])

Return type:

list[Link]

Instructions and task prompts for the aligner and the scorer.

A task covers several sentence pairs. Each pair is rendered compactly: one line per word (id form lemma UPOS head deprel and glosses from MISC), the links already settled, the links to review, and for each unlinked word how its lemma is linked elsewhere (translation evidence). The answers are compact lines that code checks and applies (see mcaligner.agents.outputs).

class mcaligner.agents.prompts.PairItem(sent_id, a, b, settled=<factory>, review=<factory>)[source]

Bases: object

One sentence pair of a task.

Parameters:
  • sent_id (str)

  • a (Sentence)

  • b (Sentence)

  • settled (list[Link])

  • review (list[Link])

settled: list[Link]

Links kept as they are (at or above the threshold).

review: list[Link]

Links below the threshold (aligner) or links to score (scorer).

mcaligner.agents.prompts.column_text(columns)[source]

id form lemma UPOS head deprel for the columns shown.

Parameters:

columns (list[str] | tuple[str, ...])

Return type:

str

mcaligner.agents.prompts.tools_text(tools, columns)[source]

What the instructions say about the tools the agent has (None = all of them).

Parameters:
  • tools (set[str] | frozenset[str] | list[str] | None)

  • columns (list[str] | tuple[str, ...])

Return type:

str

mcaligner.agents.prompts.word_lines(sentence, misc_keys, columns=('lemma', 'upos', 'head', 'deprel'))[source]

id form and the columns (default lemma UPOS head deprel), then the MISC values, per word; a line per multiword token.

Parameters:
  • sentence (Sentence)

  • misc_keys (list[str])

  • columns (list[str] | tuple[str, ...])

Return type:

list[str]

mcaligner.agents.prompts.evidence_lines(item, table, source_a, source_b, limit)[source]

For unlinked words (not punctuation): their lemma’s linked lemmas elsewhere (this pair left out).

Parameters:
Return type:

list[str]

mcaligner.agents.prompts.pair_block(item, role, confidence, table, names, misc_keys, candidates, columns=('lemma', 'upos', 'head', 'deprel'))[source]

The text of one pair in a task prompt.

Parameters:
  • item (PairItem)

  • role (str)

  • confidence (dict[str, float])

  • table (TranslationTable | None)

  • names (tuple[str, str])

  • misc_keys (list[str])

  • candidates (int)

  • columns (list[str] | tuple[str, ...])

Return type:

str

The MCP tools the agents see: read-only, with compact results.

Both agents answer with compact lines that code applies, so they only get read tools. Results are rendered as short text, because every tool result is re-read on each later model request: alignment results here, the monolingual tools with MCParser’s own compact renderings.

mcaligner.agents.toolset.READ_TOOLS = frozenset({'alignment_stats', 'analyse_form', 'category_links', 'find_tokens', 'get_context', 'get_parallel', 'lemma_links', 'link_examples', 'pair_words', 'similar_pairs', 'translation_candidates'})

the task prompt already has the pairs, their links and the main evidence; the last six are mcaligner’s exploration tools.

Type:

Deliberately small

mcaligner.agents.toolset.LIST_ARGUMENTS = ('alignments', 'sources')

List arguments that models sometimes send as a JSON string.

mcaligner.agents.toolset.ROLE = Role(name='aligner', title='word alignment', columns=())

What MCParser’s compact renderings need to know about the caller.

class mcaligner.agents.toolset.ReadToolset(wrapped, allowed=None)[source]

Bases: WrapperToolset[Any]

Only the allowed tools (default READ_TOOLS), with list arguments repaired and results compacted.

Parameters:
  • wrapped (AbstractToolset[AgentDepsT])

  • allowed (frozenset[str] | None)

async get_tools(ctx)[source]

The tools that are available in this toolset.

Parameters:

ctx (RunContext[Any])

Return type:

dict[str, ToolsetTool[Any]]

static normalise(args)[source]

Accept list arguments sent as a JSON string (or a single name).

Parameters:

args (dict[str, Any])

Return type:

dict[str, Any]

async call_tool(name, tool_args, ctx, tool)[source]

Call a tool with the given arguments.

Parameters:
  • name (str) – The name of the tool to call.

  • tool_args (dict[str, Any]) – The arguments to pass to the tool.

  • ctx (RunContext[Any]) – The run context.

  • tool (ToolsetTool[Any]) – The tool definition returned by [get_tools][pydantic_ai.toolsets.AbstractToolset.get_tools] that was called.

Return type:

Any

mcaligner.agents.toolset.read_toolset(toolset, allowed=None)[source]

toolset limited to the allowed tool names (None = all read tools, [] = none).

Parameters:
  • toolset (AbstractToolset[Any])

  • allowed (list[str] | None)

Return type:

ReadToolset