ryokai 0.1.0__tar.gz

ryokai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liling Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

ryokai-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: ryokai
+Version: 0.1.0
+Summary: 了解 — unified semantic MT evaluation: MEANT, XMEANT, YiSi, WOLVESAAR, and SimAlign-style word alignment over modern multilingual embeddings.
+Author: Liling Tan
+License: MIT
+Project-URL: Homepage, https://github.com/alvations/ryokai
+Project-URL: Repository, https://github.com/alvations/ryokai
+Project-URL: Issues, https://github.com/alvations/ryokai/issues
+Keywords: machine-translation,evaluation,metric,meant,xmeant,yisi,wolvesaar,simalign,word-alignment,semantic-roles,huggingface,multilingual
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: transformers>=4.30
+Requires-Dist: sentence-transformers>=2.2
+Requires-Dist: scipy>=1.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# ryokai 了解
+
+> *Ryokai* (了解, "understood / got it") — a unified Python library for **semantic machine-translation evaluation**, combining the strengths of MEANT 2.0, XMEANT, YiSi-1/2, WOLVESAAR, and SimAlign behind one clean API on top of modern multilingual embeddings.
+
+Pure PyTorch + HuggingFace `transformers` — no Stanza, no spaCy, no external parsers. Two HF models cover all 13 supported languages (`en`, `de`, `fr`, `es`, `cs`, `fi`, `hi`, `lv`, `pl`, `ro`, `ru`, `tr`, `zh`) in a single install:
+
+- POS / shallow SRL: [`wietsedv/xlm-roberta-base-ft-udpos28`](https://huggingface.co/wietsedv/xlm-roberta-base-ft-udpos28) — ~1.1 GB, downloaded once.
+- Multilingual embeddings: [`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`](https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2) — ~110 MB, used for both same-language and cross-language similarity.
+
+Both are one-line swappable for any modern multilingual encoder (Qwen3-Embedding, Jina v3, BGE-M3, Nemotron-8B…) — see [Embedding backbones](DOCUMENTATION.md#embedding-backbones) in `DOCUMENTATION.md`.
+
+## Install
+
+```bash
+pip install ryokai
+```
+
+## Quickstart
+
+```python
+from ryokai import Ryokai
+
+scorer = Ryokai()
+src_lang, tgt_lang = "en", "ja"
+
+# Most common: reference-free, word alignment + embedding
+# (XMEANT-lite / YiSi-2 / Doc-embedding adequacy cross-lingual)
+scorer.score(source=src, hypothesis=hyp,
+             source_lang=src_lang, target_lang=tgt_lang)
+```
+
+## Variants
+
+One `.score()` call, four modes, dispatched by which arguments you pass. `srl=False` is the default — `ryokai` is no longer MEANT-first.
+
+```python
+from ryokai import Ryokai
+scorer = Ryokai()
+src_lang, tgt_lang = "en", "ja"
+
+# Reference-free, word alignment + embedding (default, most common)
+# E.g. Doc-embedding adequacy / YiSi-2 / XMEANT-lite
+scorer.score(source=src, hypothesis=hyp,
+             source_lang=src_lang, target_lang=tgt_lang)
+
+# Reference-based, word alignment + embedding
+# E.g. Doc-embedding adequacy / WOLVESAAR / YiSi-1 / SimAlign style
+scorer.score(reference=ref, hypothesis=hyp, target_lang=tgt_lang)
+
+# Reference-free, frame-based — XMEANT proper
+scorer.score(source=src, hypothesis=hyp,
+             source_lang=src_lang, target_lang=tgt_lang, srl=True)
+
+# Reference-based, frame-based — MEANT 2.0
+scorer.score(reference=ref, hypothesis=hyp, target_lang=tgt_lang, srl=True)
+```
+
+See [`DOCUMENTATION.md`](DOCUMENTATION.md) for flags, aligner choices, embedding-backbone swaps, AER evaluation harness, CLI, architecture, and custom role weights.
+
+## References
+
+Ryokai is glue around several published techniques — credit belongs to their authors.
+
+| Technique | Year | Citation | Category |
+| --------- | ---- | -------- | -------- |
+| MEANT                  | 2011 | Lo & Wu. [*MEANT: An inexpensive, high-accuracy, semi-automatic metric for evaluating translation utility based on semantic roles*](https://aclanthology.org/P11-2042/). ACL 2011. | Semantic-frame MT evaluation  |
+| XMEANT                 | 2014 | Lo, Beloucif, Saers & Wu. [*XMEANT: Better semantic MT evaluation without reference translations*](https://aclanthology.org/P14-2124/). ACL 2014 (Short Papers). | Semantic-frame MT evaluation  |
+| MEANT 2.0              | 2017 | Lo. [*MEANT 2.0: Accurate semantic MT evaluation for any output language*](https://aclanthology.org/W17-4767/). WMT 2017. | Semantic-frame MT evaluation  |
+| Doc-embedding adequacy | 2015 | Vela & Tan. [*Predicting Machine Translation Adequacy with Document Embeddings*](https://aclanthology.org/W15-3051/). WMT 2015. | Embedding-based MT evaluation |
+| WOLVESAAR              | 2016 | Bechara, Gupta, Tan, Orăsan, Mitkov & van Genabith. [*WOLVESAAR at SemEval-2016 Task 1: Replicating the Success of Monolingual Word Alignment and Neural Embeddings for Semantic Textual Similarity*](https://aclanthology.org/S16-1096/). SemEval-2016. | Embedding-based MT evaluation |
+| YiSi                   | 2019 | Lo. [*YiSi — a Unified Semantic MT Quality Evaluation and Estimation Metric for Languages with Different Levels of Available Resources*](https://aclanthology.org/W19-5358/). WMT 2019. | Embedding-based MT evaluation |
+| Monolingual aligner    | 2014 | Sultan, Bethard & Sumner. [*Back to Basics for Monolingual Alignment: Exploiting Word Similarity and Contextual Evidence*](https://aclanthology.org/Q14-1018/). TACL 2014. | Word alignment                |
+| SimAlign               | 2020 | Jalili Sabet, Dufter, Yvon & Schütze. [*SimAlign: High Quality Word Alignments without Parallel Training Data using Static and Contextualized Embeddings*](https://aclanthology.org/2020.findings-emnlp.147/). Findings of EMNLP 2020. | Word alignment                |
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

ryokai-0.1.0/README.md

@@ -0,0 +1,77 @@
+# ryokai 了解
+
+> *Ryokai* (了解, "understood / got it") — a unified Python library for **semantic machine-translation evaluation**, combining the strengths of MEANT 2.0, XMEANT, YiSi-1/2, WOLVESAAR, and SimAlign behind one clean API on top of modern multilingual embeddings.
+
+Pure PyTorch + HuggingFace `transformers` — no Stanza, no spaCy, no external parsers. Two HF models cover all 13 supported languages (`en`, `de`, `fr`, `es`, `cs`, `fi`, `hi`, `lv`, `pl`, `ro`, `ru`, `tr`, `zh`) in a single install:
+
+- POS / shallow SRL: [`wietsedv/xlm-roberta-base-ft-udpos28`](https://huggingface.co/wietsedv/xlm-roberta-base-ft-udpos28) — ~1.1 GB, downloaded once.
+- Multilingual embeddings: [`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`](https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2) — ~110 MB, used for both same-language and cross-language similarity.
+
+Both are one-line swappable for any modern multilingual encoder (Qwen3-Embedding, Jina v3, BGE-M3, Nemotron-8B…) — see [Embedding backbones](DOCUMENTATION.md#embedding-backbones) in `DOCUMENTATION.md`.
+
+## Install
+
+```bash
+pip install ryokai
+```
+
+## Quickstart
+
+```python
+from ryokai import Ryokai
+
+scorer = Ryokai()
+src_lang, tgt_lang = "en", "ja"
+
+# Most common: reference-free, word alignment + embedding
+# (XMEANT-lite / YiSi-2 / Doc-embedding adequacy cross-lingual)
+scorer.score(source=src, hypothesis=hyp,
+             source_lang=src_lang, target_lang=tgt_lang)
+```
+
+## Variants
+
+One `.score()` call, four modes, dispatched by which arguments you pass. `srl=False` is the default — `ryokai` is no longer MEANT-first.
+
+```python
+from ryokai import Ryokai
+scorer = Ryokai()
+src_lang, tgt_lang = "en", "ja"
+
+# Reference-free, word alignment + embedding (default, most common)
+# E.g. Doc-embedding adequacy / YiSi-2 / XMEANT-lite
+scorer.score(source=src, hypothesis=hyp,
+             source_lang=src_lang, target_lang=tgt_lang)
+
+# Reference-based, word alignment + embedding
+# E.g. Doc-embedding adequacy / WOLVESAAR / YiSi-1 / SimAlign style
+scorer.score(reference=ref, hypothesis=hyp, target_lang=tgt_lang)
+
+# Reference-free, frame-based — XMEANT proper
+scorer.score(source=src, hypothesis=hyp,
+             source_lang=src_lang, target_lang=tgt_lang, srl=True)
+
+# Reference-based, frame-based — MEANT 2.0
+scorer.score(reference=ref, hypothesis=hyp, target_lang=tgt_lang, srl=True)
+```
+
+See [`DOCUMENTATION.md`](DOCUMENTATION.md) for flags, aligner choices, embedding-backbone swaps, AER evaluation harness, CLI, architecture, and custom role weights.
+
+## References
+
+Ryokai is glue around several published techniques — credit belongs to their authors.
+
+| Technique | Year | Citation | Category |
+| --------- | ---- | -------- | -------- |
+| MEANT                  | 2011 | Lo & Wu. [*MEANT: An inexpensive, high-accuracy, semi-automatic metric for evaluating translation utility based on semantic roles*](https://aclanthology.org/P11-2042/). ACL 2011. | Semantic-frame MT evaluation  |
+| XMEANT                 | 2014 | Lo, Beloucif, Saers & Wu. [*XMEANT: Better semantic MT evaluation without reference translations*](https://aclanthology.org/P14-2124/). ACL 2014 (Short Papers). | Semantic-frame MT evaluation  |
+| MEANT 2.0              | 2017 | Lo. [*MEANT 2.0: Accurate semantic MT evaluation for any output language*](https://aclanthology.org/W17-4767/). WMT 2017. | Semantic-frame MT evaluation  |
+| Doc-embedding adequacy | 2015 | Vela & Tan. [*Predicting Machine Translation Adequacy with Document Embeddings*](https://aclanthology.org/W15-3051/). WMT 2015. | Embedding-based MT evaluation |
+| WOLVESAAR              | 2016 | Bechara, Gupta, Tan, Orăsan, Mitkov & van Genabith. [*WOLVESAAR at SemEval-2016 Task 1: Replicating the Success of Monolingual Word Alignment and Neural Embeddings for Semantic Textual Similarity*](https://aclanthology.org/S16-1096/). SemEval-2016. | Embedding-based MT evaluation |
+| YiSi                   | 2019 | Lo. [*YiSi — a Unified Semantic MT Quality Evaluation and Estimation Metric for Languages with Different Levels of Available Resources*](https://aclanthology.org/W19-5358/). WMT 2019. | Embedding-based MT evaluation |
+| Monolingual aligner    | 2014 | Sultan, Bethard & Sumner. [*Back to Basics for Monolingual Alignment: Exploiting Word Similarity and Contextual Evidence*](https://aclanthology.org/Q14-1018/). TACL 2014. | Word alignment                |
+| SimAlign               | 2020 | Jalili Sabet, Dufter, Yvon & Schütze. [*SimAlign: High Quality Word Alignments without Parallel Training Data using Static and Contextualized Embeddings*](https://aclanthology.org/2020.findings-emnlp.147/). Findings of EMNLP 2020. | Word alignment                |
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

ryokai-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ryokai"
+version = "0.1.0"
+description = "了解 — unified semantic MT evaluation: MEANT, XMEANT, YiSi, WOLVESAAR, and SimAlign-style word alignment over modern multilingual embeddings."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Liling Tan" }]
+keywords = [
+    "machine-translation",
+    "evaluation",
+    "metric",
+    "meant",
+    "xmeant",
+    "yisi",
+    "wolvesaar",
+    "simalign",
+    "word-alignment",
+    "semantic-roles",
+    "huggingface",
+    "multilingual",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "torch>=2.0",
+    "transformers>=4.30",
+    "sentence-transformers>=2.2",
+    "scipy>=1.10",
+    "numpy>=1.24",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-xdist"]
+dev  = ["pytest>=7", "pytest-xdist", "ruff", "build", "twine"]
+
+[project.scripts]
+ryokai = "ryokai.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/alvations/ryokai"
+Repository = "https://github.com/alvations/ryokai"
+Issues = "https://github.com/alvations/ryokai/issues"
+
+[tool.setuptools]
+packages = ["ryokai", "ryokai.srl", "ryokai.sim"]
+include-package-data = true
+
+[tool.setuptools.package-data]
+ryokai = ["data/*.yaml", "data/**/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: tests that download HF models (deselect with -m 'not slow')",
+]

ryokai-0.1.0/ryokai/__init__.py

@@ -0,0 +1,283 @@
+"""ryokai — 了解.
+
+Unified semantic machine-translation evaluation. Reference-free or
+reference-based, word-alignment + embedding by default, frame-based
+MEANT 2.0 on opt-in — all behind a single `.score()` call.
+
+Quickstart
+----------
+>>> from ryokai import Ryokai
+>>> scorer = Ryokai()
+>>>
+>>> # Reference-free (most common; XMEANT / YiSi-2 / Doc-embedding adequacy)
+>>> scorer.score(source=src, hypothesis=hyp,
+...              source_lang="en", target_lang="ja")
+>>>
+>>> # Reference-based, word alignment + embeddings
+>>> # (Doc-embedding adequacy / WOLVESAAR / YiSi-1 / SimAlign)
+>>> scorer.score(reference=ref, hypothesis=hyp, target_lang="ja")
+>>>
+>>> # Frame-based MEANT 2.0 — opt in with srl=True
+>>> scorer.score(reference=ref, hypothesis=hyp, target_lang="ja", srl=True)
+>>>
+>>> # Frame-based reference-free (XMEANT proper)
+>>> scorer.score(source=src, hypothesis=hyp,
+...              source_lang="en", target_lang="ja", srl=True)
+"""
+from __future__ import annotations
+
+from ._langs import SUPPORTED_LANGS
+from .graph import Argument, Frame, SRLGraph
+from .labelconfig import LabelConfig
+from .scorer import DEFAULT_WEIGHTS, MEANTScore, Score, score_nosrl, score_pair
+from .sim import ContextualTokenSimBackend, StaticEmbeddingSimBackend
+from .sim.embeddings import EmbeddingSimBackend
+from .srl import HFPOSHeuristicSRLBackend, HFTokenClassifierSRLBackend, SRLBackend
+
+__version__ = "0.1.0"
+
+
+class Ryokai:
+    """Unified MT-eval scorer.
+
+    Construct once with the backend / alignment configuration you want;
+    call ``.score(...)`` per-pair. The mode is chosen by which arguments
+    you pass:
+
+    +------------------------+--------------+--------------------------------------------+
+    | source / reference     | srl          | Mode                                       |
+    +========================+==============+============================================+
+    | ``source=``            | False (def.) | Reference-free, word alignment + embedding |
+    |                        |              | (XMEANT-lite / YiSi-2 / Doc-embedding adq) |
+    +------------------------+--------------+--------------------------------------------+
+    | ``reference=``         | False (def.) | Reference-based, word alignment + embedding|
+    |                        |              | (WOLVESAAR / YiSi-1 / SimAlign style)      |
+    +------------------------+--------------+--------------------------------------------+
+    | ``source=``            | True         | Reference-free, frame-based (XMEANT)       |
+    +------------------------+--------------+--------------------------------------------+
+    | ``reference=``         | True         | Reference-based, frame-based (MEANT 2.0)   |
+    +------------------------+--------------+--------------------------------------------+
+
+    Constructor parameters configure the *how* (which models, which
+    aligner, weights, etc.); per-call parameters configure the *what*
+    (which sentences, which languages, ref- vs source-based, with or
+    without SRL).
+
+    Parameters
+    ----------
+    srl_backend : SRLBackend | None
+        SRL backend used whenever a `.score(..., srl=True)` call is made.
+        Defaults to `HFPOSHeuristicSRLBackend` — a multilingual XLM-R
+        UDPOS heuristic covering all 13 supported languages with one
+        model.
+    sim_backend : EmbeddingSimBackend | None
+        Sentence / argument similarity backend. Defaults to multilingual
+        MiniLM. Swap to any preset (``"qwen3-0.6b"``, ``"jina-v3"``,
+        ``"nemotron-8b"``…) or any HF model id.
+    weights : dict[str, float] | None
+        Per-role weights for frame-based F-score. Defaults to
+        `DEFAULT_WEIGHTS`.
+    label_config : LabelConfig | None
+        SRL label aliasing. Defaults to bundled `data/labelconfig.yaml`.
+    content_only : bool
+        No-SRL only: drop stopwords + punctuation before alignment
+        (WOLVESAAR style).
+    aggregation : str
+        No-SRL only: ``"f1"`` (default) or ``"harmonic"``.
+    aligner : str
+        No-SRL only: ``"sentence"`` (fast, default), ``"hungarian"``,
+        ``"argmax"``, ``"itermax"``, or ``"mai"``.
+    threshold : float
+        No-SRL contextual aligners: cosine floor below which a pair is
+        discarded. Default 0.5.
+    exact_match_shortcut : bool
+        No-SRL contextual aligners: case-insensitive surface equality
+        boosts a pair's similarity to 1.0 (Sultan-style prior).
+    """
+
+    def __init__(
+        self,
+        srl_backend: SRLBackend | None = None,
+        sim_backend: EmbeddingSimBackend | None = None,
+        weights: dict[str, float] | None = None,
+        label_config: LabelConfig | None = None,
+        content_only: bool = False,
+        aggregation: str = "f1",
+        aligner: str = "sentence",
+        threshold: float = 0.5,
+        exact_match_shortcut: bool = True,
+    ) -> None:
+        self._srl_backend = srl_backend
+        self.sim = sim_backend or EmbeddingSimBackend()
+        self.weights = weights or DEFAULT_WEIGHTS
+        self.label_config = label_config or LabelConfig()
+        self.content_only = content_only
+        self.aggregation = aggregation
+        self.aligner = aligner
+        self.threshold = threshold
+        self.exact_match_shortcut = exact_match_shortcut
+
+    @property
+    def srl(self) -> SRLBackend:
+        """Lazily instantiate the default SRL backend so users who never
+        call with ``srl=True`` never pay for the SRL model download."""
+        if self._srl_backend is None:
+            self._srl_backend = HFPOSHeuristicSRLBackend()
+        return self._srl_backend
+
+    @staticmethod
+    def _check_lang(name: str, value: str | None) -> None:
+        if value is None:
+            return
+        if value not in SUPPORTED_LANGS:
+            raise ValueError(
+                f"{name}={value!r} not supported. "
+                f"Supported: {sorted(SUPPORTED_LANGS)}"
+            )
+
+    def score(
+        self,
+        *,
+        hypothesis: str,
+        target_lang: str,
+        source: str | None = None,
+        source_lang: str | None = None,
+        reference: str | None = None,
+        srl: bool = False,
+    ) -> Score:
+        """Score one MT pair. See class docstring for the dispatch table.
+
+        Exactly one of ``source=`` or ``reference=`` must be given.
+        Higher returned ``f1`` = more adequate.
+        """
+        if (source is None) == (reference is None):
+            raise ValueError(
+                "pass exactly one of source= (reference-free) or "
+                "reference= (reference-based)"
+            )
+        self._check_lang("target_lang", target_lang)
+        self._check_lang("source_lang", source_lang)
+
+        if srl:
+            return self._score_with_srl(
+                hypothesis=hypothesis,
+                target_lang=target_lang,
+                source=source,
+                source_lang=source_lang,
+                reference=reference,
+            )
+        return self._score_nosrl(
+            hypothesis=hypothesis,
+            target_lang=target_lang,
+            source=source,
+            source_lang=source_lang,
+            reference=reference,
+        )
+
+    def _score_nosrl(
+        self,
+        *,
+        hypothesis: str,
+        target_lang: str,
+        source: str | None,
+        source_lang: str | None,
+        reference: str | None,
+    ) -> Score:
+        # the "other side" of the comparison is either source or reference
+        other = source if source is not None else reference
+        other_lang = source_lang if source is not None else target_lang
+        return score_nosrl(
+            other,
+            hypothesis,
+            self.sim,
+            lang=other_lang or target_lang,
+            content_only=self.content_only,
+            aggregation=self.aggregation,
+            aligner=self.aligner,
+            threshold=self.threshold,
+            exact_match_shortcut=self.exact_match_shortcut,
+        )
+
+    def _score_with_srl(
+        self,
+        *,
+        hypothesis: str,
+        target_lang: str,
+        source: str | None,
+        source_lang: str | None,
+        reference: str | None,
+    ) -> Score:
+        hyp_graph = self.srl.parse(hypothesis, target_lang)
+        if source is not None:
+            ref_graph = self.srl.parse(source, source_lang or target_lang)
+        else:
+            ref_graph = self.srl.parse(reference, target_lang)
+        return score_pair(
+            ref_graph, hyp_graph, self.sim, self.weights, self.label_config,
+        )
+
+    def score_corpus(
+        self,
+        *,
+        hypotheses: list[str],
+        target_lang: str,
+        sources: list[str] | None = None,
+        source_lang: str | None = None,
+        references: list[str] | None = None,
+        srl: bool = False,
+    ) -> list[Score]:
+        """Score a parallel corpus — one Score per pair.
+
+        Same dispatch rules as `.score()`: pass either `sources=` or
+        `references=`, not both.
+        """
+        if (sources is None) == (references is None):
+            raise ValueError(
+                "pass exactly one of sources= or references="
+            )
+        n = len(hypotheses)
+        others = sources if sources is not None else references
+        if len(others) != n:
+            raise ValueError(
+                f"length mismatch: hypotheses={n}, "
+                f"{'sources' if sources is not None else 'references'}={len(others)}"
+            )
+        out: list[Score] = []
+        for i in range(n):
+            kwargs = dict(
+                hypothesis=hypotheses[i],
+                target_lang=target_lang,
+                source_lang=source_lang,
+                srl=srl,
+            )
+            if sources is not None:
+                kwargs["source"] = sources[i]
+            else:
+                kwargs["reference"] = references[i]
+            out.append(self.score(**kwargs))
+        return out
+
+
+# Backwards-compatible alias — most MT-eval literature calls this MEANT.
+MEANT = Ryokai
+
+__all__ = [
+    "Ryokai",
+    "MEANT",
+    "Score",
+    "MEANTScore",
+    "SRLGraph",
+    "Frame",
+    "Argument",
+    "LabelConfig",
+    "SRLBackend",
+    "HFPOSHeuristicSRLBackend",
+    "HFTokenClassifierSRLBackend",
+    "EmbeddingSimBackend",
+    "ContextualTokenSimBackend",
+    "StaticEmbeddingSimBackend",
+    "DEFAULT_WEIGHTS",
+    "SUPPORTED_LANGS",
+    "score_pair",
+    "score_nosrl",
+]

ryokai-0.1.0/ryokai/_langs.py

@@ -0,0 +1,16 @@
+"""Registry of the 13 languages MEANT 2.0 originally supported."""
+SUPPORTED_LANGS: dict[str, str] = {
+    "en": "English",
+    "de": "German",
+    "fr": "French",
+    "es": "Spanish",
+    "cs": "Czech",
+    "fi": "Finnish",
+    "hi": "Hindi",
+    "lv": "Latvian",
+    "pl": "Polish",
+    "ro": "Romanian",
+    "ru": "Russian",
+    "tr": "Turkish",
+    "zh": "Chinese",
+}

ryokai-0.1.0/ryokai/cli.py

@@ -0,0 +1,87 @@
+"""ryokai CLI — score a parallel hyp file vs reference or source file."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import Ryokai, SUPPORTED_LANGS
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="ryokai",
+        description=(
+            "Score MT output. Pass --ref for reference-based scoring "
+            "(MEANT / WOLVESAAR / YiSi-1 / SimAlign style), or --src "
+            "for reference-free scoring (XMEANT / YiSi-2 / Doc-embedding "
+            "adequacy)."
+        ),
+    )
+    group = p.add_mutually_exclusive_group(required=True)
+    group.add_argument("--ref", help="Path to reference text (one segment per line).")
+    group.add_argument("--src", help="Path to source text (one segment per line).")
+    p.add_argument("--hyp", required=True, help="Path to hypothesis / MT output (one segment per line).")
+    p.add_argument(
+        "--target-lang", required=True, choices=sorted(SUPPORTED_LANGS),
+        help="Two-letter language code of the hypothesis.",
+    )
+    p.add_argument(
+        "--source-lang", choices=sorted(SUPPORTED_LANGS),
+        help="Language of --src. Defaults to --target-lang. Ignored if --ref is used.",
+    )
+    p.add_argument(
+        "--srl", action="store_true",
+        help="Use the frame-based MEANT 2.0 / XMEANT scorer. Default: word alignment + embedding.",
+    )
+    p.add_argument(
+        "--aligner", default="sentence",
+        choices=["sentence", "hungarian", "argmax", "itermax", "mai"],
+        help="No-SRL aligner. Ignored when --srl is set.",
+    )
+    p.add_argument(
+        "--sim-model", default=None,
+        help="Override the multilingual embedding model id or preset.",
+    )
+    p.add_argument(
+        "--no-corpus-avg", action="store_true",
+        help="Print one F1 per line instead of corpus mean.",
+    )
+    args = p.parse_args(argv)
+
+    hyps = [line.rstrip("\n") for line in open(args.hyp, encoding="utf-8")]
+    if args.ref:
+        others = [line.rstrip("\n") for line in open(args.ref, encoding="utf-8")]
+        kind = "references"
+    else:
+        others = [line.rstrip("\n") for line in open(args.src, encoding="utf-8")]
+        kind = "sources"
+    if len(others) != len(hyps):
+        print(
+            f"{kind} and hypotheses line counts differ: {len(others)} vs {len(hyps)}",
+            file=sys.stderr,
+        )
+        return 2
+
+    from .sim.embeddings import EmbeddingSimBackend
+    sim = EmbeddingSimBackend(args.sim_model) if args.sim_model else None
+    scorer = Ryokai(sim_backend=sim, aligner=args.aligner)
+    scores = scorer.score_corpus(
+        hypotheses=hyps,
+        target_lang=args.target_lang,
+        sources=others if args.src else None,
+        references=others if args.ref else None,
+        source_lang=args.source_lang,
+        srl=args.srl,
+    )
+
+    if args.no_corpus_avg:
+        for s in scores:
+            print(f"{s.f1:.4f}")
+    else:
+        mean = sum(s.f1 for s in scores) / len(scores) if scores else 0.0
+        print(f"ryokai = {mean:.4f}  (n={len(scores)})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())