kroma-om 0.2.0__tar.gz

kroma_om-0.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Lam Nguyen, Erika Barcelos, Roger French, and Yinghui Wu
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

kroma_om-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: kroma-om
+Version: 0.2.0
+Summary: Ontology matching with knowledge retrieval and large language models
+Author: Lam Nguyen, Erika Barcelos, Roger French, Yinghui Wu
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/cwru-sdle/kroma
+Project-URL: Documentation, https://kroma.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/cwru-sdle/kroma
+Project-URL: Issues, https://github.com/cwru-sdle/kroma/issues
+Project-URL: Paper, https://doi.org/10.1007/978-3-032-09527-5_34
+Project-URL: arXiv, https://arxiv.org/abs/2507.14032
+Keywords: ontology matching,ontology alignment,knowledge graphs,large language models,retrieval-augmented generation,semantic web
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: python-dotenv
+Requires-Dist: rdflib
+Requires-Dist: requests
+Requires-Dist: scipy
+Provides-Extra: models
+Requires-Dist: nltk; extra == "models"
+Requires-Dist: networkx; extra == "models"
+Requires-Dist: node2vec; extra == "models"
+Requires-Dist: openai; extra == "models"
+Requires-Dist: scikit-learn; extra == "models"
+Requires-Dist: scipy; extra == "models"
+Requires-Dist: sentence-transformers; extra == "models"
+Requires-Dist: SPARQLWrapper; extra == "models"
+Requires-Dist: together; extra == "models"
+Requires-Dist: torch; extra == "models"
+Requires-Dist: transformers; extra == "models"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
+Dynamic: license-file
+
+<div align="center">
+
+# KROMA
+
+**Ontology matching with knowledge retrieval and large language models**
+
+[![PyPI](https://img.shields.io/pypi/v/kroma-om)](https://pypi.org/project/kroma-om/)
+[![Docs](https://readthedocs.org/projects/kroma/badge/?version=latest)](https://kroma.readthedocs.io/en/latest/)
+[![ISWC 2025](https://img.shields.io/badge/ISWC-2025-b31b1b)](https://doi.org/10.1007/978-3-032-09527-5_34)
+[![License: BSD 3-Clause](https://img.shields.io/badge/license-BSD%203--Clause-green.svg)](https://github.com/cwru-sdle/kroma/blob/main/LICENSE)
+
+[**Documentation**](https://kroma.readthedocs.io/en/latest/) ·
+[Quick start](#quick-start) ·
+[Example](#example) ·
+[Results](#results) ·
+[Paper](https://doi.org/10.1007/978-3-032-09527-5_34) ·
+[Citation](#citation)
+
+</div>
+
+KROMA finds the concepts that two ontologies share. It retrieves likely
+matches for each concept, accepts identical names directly, and asks a large
+language model about the rest, showing it each concept's labels, synonyms,
+parents and children.
+
+## Quick start
+
+```bash
+pip install kroma-om openai
+export OPENAI_API_KEY=sk-...
+
+kroma match mouse.owl human.owl -o alignments.csv
+```
+
+Or from Python:
+
+```python
+import kroma
+
+result = kroma.match("mouse.owl", "human.owl", model="gpt-4o-mini")
+result.save("alignments.csv")    # .csv, .tsv, or .rdf (OAEI format)
+```
+
+KROMA reads any RDF format (`.owl`, `.ttl`, `.rdf`, …) and works with OpenAI,
+Together AI, or any function that takes a prompt and returns text. See the
+[documentation](https://kroma.readthedocs.io/en/latest/) for all
+options.
+
+## Example
+
+Try KROMA with a local [Ollama](https://ollama.com) model, no API key needed:
+
+```bash
+git clone https://github.com/cwru-sdle/kroma.git && cd kroma/examples
+pip install kroma-om
+ollama pull llama3.2:1b
+python match_ollama.py --model llama3.2:1b
+```
+
+| Source | Target | Confidence (0-10) |
+|:--|:--|:--:|
+| heart | cardiac organ | 10 |
+| lung | lungs | 8 |
+| organ | body organ | 8 |
+
+Run with `llama3.2:1b` on a small demo dataset; see the
+[example](https://github.com/cwru-sdle/kroma/tree/main/examples) for details.
+
+## Results
+
+F1 (%) on six OAEI tracks, from the [ISWC 2025 paper](https://doi.org/10.1007/978-3-032-09527-5_34):
+
+| Track | KROMA | Best baseline |
+|:--|:--:|:--:|
+| Mouse–Human | **94.94** | 92.20 |
+| NCIT–DOID | **98.63** | 94.80 |
+| Nell–DBpedia | **97.08** | 96.00 |
+| YAGO–Wikidata | **95.54** | 92.19 |
+| ENVO–SWEET | **93.18** | 83.70 |
+| MI–MatOnto | **61.25** | 32.97 |
+
+Ablations, other models and cost are in the
+[full paper](https://github.com/cwru-sdle/kroma/blob/main/full.pdf).
+
+## Reproducing the paper
+
+```bash
+git clone https://github.com/cwru-sdle/kroma.git && cd kroma
+./setup.sh && source .venv/bin/activate
+uv pip install ".[models]"
+
+kroma run --method_config kroma_scibert_envo_sweet \
+          --llm meta-llama/Llama-3.3-70B-Instruct-Turbo-Free
+```
+
+Datasets, configs and flags are described in
+[Benchmark experiments](https://kroma.readthedocs.io/en/latest/usage.html).
+
+## Citation
+
+```bibtex
+@inproceedings{nguyen_2025_kroma,
+  title     = {KROMA: Ontology Matching with Knowledge Retrieval and Large Language Models},
+  author    = {Lam Nguyen and Erika Barcelos and Roger French and Yinghui Wu},
+  booktitle = {The Semantic Web -- ISWC 2025: 24th International Semantic Web Conference, Proceedings, Part I},
+  series    = {Lecture Notes in Computer Science},
+  publisher = {Springer},
+  pages     = {629--649},
+  year      = {2025},
+  doi       = {10.1007/978-3-032-09527-5_34}
+}
+```
+
+## License
+
+[BSD 3-Clause](https://github.com/cwru-sdle/kroma/blob/main/LICENSE) ·
+Developed at the [SDLE Research Center](https://github.com/cwru-sdle),
+Case Western Reserve University.

kroma_om-0.2.0/README.md

@@ -0,0 +1,118 @@
+<div align="center">
+
+# KROMA
+
+**Ontology matching with knowledge retrieval and large language models**
+
+[![PyPI](https://img.shields.io/pypi/v/kroma-om)](https://pypi.org/project/kroma-om/)
+[![Docs](https://readthedocs.org/projects/kroma/badge/?version=latest)](https://kroma.readthedocs.io/en/latest/)
+[![ISWC 2025](https://img.shields.io/badge/ISWC-2025-b31b1b)](https://doi.org/10.1007/978-3-032-09527-5_34)
+[![License: BSD 3-Clause](https://img.shields.io/badge/license-BSD%203--Clause-green.svg)](https://github.com/cwru-sdle/kroma/blob/main/LICENSE)
+
+[**Documentation**](https://kroma.readthedocs.io/en/latest/) ·
+[Quick start](#quick-start) ·
+[Example](#example) ·
+[Results](#results) ·
+[Paper](https://doi.org/10.1007/978-3-032-09527-5_34) ·
+[Citation](#citation)
+
+</div>
+
+KROMA finds the concepts that two ontologies share. It retrieves likely
+matches for each concept, accepts identical names directly, and asks a large
+language model about the rest, showing it each concept's labels, synonyms,
+parents and children.
+
+## Quick start
+
+```bash
+pip install kroma-om openai
+export OPENAI_API_KEY=sk-...
+
+kroma match mouse.owl human.owl -o alignments.csv
+```
+
+Or from Python:
+
+```python
+import kroma
+
+result = kroma.match("mouse.owl", "human.owl", model="gpt-4o-mini")
+result.save("alignments.csv")    # .csv, .tsv, or .rdf (OAEI format)
+```
+
+KROMA reads any RDF format (`.owl`, `.ttl`, `.rdf`, …) and works with OpenAI,
+Together AI, or any function that takes a prompt and returns text. See the
+[documentation](https://kroma.readthedocs.io/en/latest/) for all
+options.
+
+## Example
+
+Try KROMA with a local [Ollama](https://ollama.com) model, no API key needed:
+
+```bash
+git clone https://github.com/cwru-sdle/kroma.git && cd kroma/examples
+pip install kroma-om
+ollama pull llama3.2:1b
+python match_ollama.py --model llama3.2:1b
+```
+
+| Source | Target | Confidence (0-10) |
+|:--|:--|:--:|
+| heart | cardiac organ | 10 |
+| lung | lungs | 8 |
+| organ | body organ | 8 |
+
+Run with `llama3.2:1b` on a small demo dataset; see the
+[example](https://github.com/cwru-sdle/kroma/tree/main/examples) for details.
+
+## Results
+
+F1 (%) on six OAEI tracks, from the [ISWC 2025 paper](https://doi.org/10.1007/978-3-032-09527-5_34):
+
+| Track | KROMA | Best baseline |
+|:--|:--:|:--:|
+| Mouse–Human | **94.94** | 92.20 |
+| NCIT–DOID | **98.63** | 94.80 |
+| Nell–DBpedia | **97.08** | 96.00 |
+| YAGO–Wikidata | **95.54** | 92.19 |
+| ENVO–SWEET | **93.18** | 83.70 |
+| MI–MatOnto | **61.25** | 32.97 |
+
+Ablations, other models and cost are in the
+[full paper](https://github.com/cwru-sdle/kroma/blob/main/full.pdf).
+
+## Reproducing the paper
+
+```bash
+git clone https://github.com/cwru-sdle/kroma.git && cd kroma
+./setup.sh && source .venv/bin/activate
+uv pip install ".[models]"
+
+kroma run --method_config kroma_scibert_envo_sweet \
+          --llm meta-llama/Llama-3.3-70B-Instruct-Turbo-Free
+```
+
+Datasets, configs and flags are described in
+[Benchmark experiments](https://kroma.readthedocs.io/en/latest/usage.html).
+
+## Citation
+
+```bibtex
+@inproceedings{nguyen_2025_kroma,
+  title     = {KROMA: Ontology Matching with Knowledge Retrieval and Large Language Models},
+  author    = {Lam Nguyen and Erika Barcelos and Roger French and Yinghui Wu},
+  booktitle = {The Semantic Web -- ISWC 2025: 24th International Semantic Web Conference, Proceedings, Part I},
+  series    = {Lecture Notes in Computer Science},
+  publisher = {Springer},
+  pages     = {629--649},
+  year      = {2025},
+  doi       = {10.1007/978-3-032-09527-5_34}
+}
+```
+
+## License
+
+[BSD 3-Clause](https://github.com/cwru-sdle/kroma/blob/main/LICENSE) ·
+Developed at the [SDLE Research Center](https://github.com/cwru-sdle),
+Case Western Reserve University.

kroma_om-0.2.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kroma-om"
+version = "0.2.0"
+description = "Ontology matching with knowledge retrieval and large language models"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+  { name = "Lam Nguyen" },
+  { name = "Erika Barcelos" },
+  { name = "Roger French" },
+  { name = "Yinghui Wu" },
+]
+license = "BSD-3-Clause"
+keywords = ["ontology matching", "ontology alignment", "knowledge graphs", "large language models", "retrieval-augmented generation", "semantic web"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+  "numpy",
+  "python-dotenv",
+  "rdflib",
+  "requests",
+  "scipy",
+]
+
+[project.optional-dependencies]
+models = [
+  "nltk",
+  "networkx",
+  "node2vec",
+  "openai",
+  "scikit-learn",
+  "scipy",
+  "sentence-transformers",
+  "SPARQLWrapper",
+  "together",
+  "torch",
+  "transformers",
+]
+dev = ["pytest"]
+docs = ["sphinx>=7", "sphinx-rtd-theme>=2"]
+
+[project.scripts]
+kroma = "kroma.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/cwru-sdle/kroma"
+Documentation = "https://kroma.readthedocs.io/en/latest/"
+Repository = "https://github.com/cwru-sdle/kroma"
+Issues = "https://github.com/cwru-sdle/kroma/issues"
+Paper = "https://doi.org/10.1007/978-3-032-09527-5_34"
+arXiv = "https://arxiv.org/abs/2507.14032"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["kroma*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

kroma_om-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kroma_om-0.2.0/src/kroma/__init__.py

@@ -0,0 +1,36 @@
+"""KROMA: ontology matching with knowledge retrieval and large language models.
+
+KROMA decides whether a concept in a source ontology and a concept in a target
+ontology refer to the same real-world entity. For each candidate pair it
+retrieves the concepts' context (ontology structure, cached dictionaries,
+SPARQL endpoints and ConceptNet), asks one or more language models for a
+Yes/No answer with a confidence, and refines a bisimulation-based partition of
+the merged ontology graph as answers arrive.
+
+To align two ontologies, call :func:`kroma.match` (or run ``kroma match``).
+To reproduce the paper's benchmarks, use ``kroma run`` and
+:class:`kroma.pipeline.MatchingRun`.
+
+Example:
+    >>> import kroma
+    >>> result = kroma.match("source.owl", "target.owl")  # doctest: +SKIP
+    >>> result.save("alignments.csv")  # doctest: +SKIP
+"""
+
+__version__ = "0.2.0"
+
+from kroma.alignment import Alignment, MatchResult, save_alignments
+from kroma.matcher import find_candidates, match
+from kroma.ontology import Concept, Ontology, load_ontology
+
+__all__ = [
+    "__version__",
+    "match",
+    "find_candidates",
+    "load_ontology",
+    "Ontology",
+    "Concept",
+    "Alignment",
+    "MatchResult",
+    "save_alignments",
+]

kroma_om-0.2.0/src/kroma/agents/__init__.py

@@ -0,0 +1 @@
+"""Language-model agents: creation, prompting and answer parsing."""

kroma_om-0.2.0/src/kroma/agents/factory.py

@@ -0,0 +1,43 @@
+"""Create the chat agents used for single-model and debate inference."""
+
+from typing import Dict, Any, List
+from kroma.inference.factory import create_inference_model
+
+def create_agents_from_config(
+    configs: List[Dict[str, str]]
+) -> Dict[int, Any]:
+    """Create one agent per config entry.
+
+    Args:
+        configs (list[dict[str, str]]): Entries with ``agent_type`` (a chat
+            backend) and ``agent_name`` (a model), for example
+            ``[{"agent_type": "openai", "agent_name": "gpt-4o-mini"}]``.
+
+    Returns:
+        dict[int, BaseModel]: Agents keyed by their position in ``configs``.
+    """
+    agents: Dict[int, Any] = {}
+    for idx, cfg in enumerate(configs):
+        agents[idx] = create_inference_model(cfg['agent_type'], cfg['agent_name'])
+    return agents
+
+
+def create_agents(
+    n_agents: int,
+    backend: str,
+    model_name: str
+) -> Dict[int, Any]:
+    """Create ``n_agents`` agents with the same backend and model.
+
+    Args:
+        n_agents (int): Number of agents.
+        backend (str): Chat backend name, such as ``"openai"``.
+        model_name (str): Model name.
+
+    Returns:
+        dict[int, BaseModel]: Agents keyed ``0`` to ``n_agents - 1``.
+    """
+    return {
+        i: create_inference_model(backend, model_name)
+        for i in range(n_agents)
+    }

kroma_om-0.2.0/src/kroma/agents/inference.py

@@ -0,0 +1,211 @@
+"""Single-model and debate inference strategies."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Tuple
+
+from kroma.agents.factory import create_agents, create_agents_from_config
+from kroma.agents.utils import (
+    active_learning_score,
+    extract_confidence,
+    extract_yes_no,
+    majority_vote,
+)
+from kroma.tasks.prompts.builders import (
+    build_last_round_prompt,
+    build_round_prompt,
+    build_task_prompt,
+)
+from kroma.tasks.query_engine import query
+
+
+def expand_term(term, pcmap, dictionary, options):
+    """Gather a concept's context as a prompt-ready tuple.
+
+    Args:
+        term (tuple): ``(code, ...)``; only the code is used.
+        pcmap (dict): Parent and child maps for the concept's ontology.
+        dictionary (dict): Cached dictionaries.
+        options (list[str]): Context sources for
+            :func:`kroma.tasks.query_engine.query`.
+
+    Returns:
+        tuple: ``(code, parents, children, synonyms, labels)``.
+    """
+    parents, children, synonyms, labels = query(term[0], pcmap, dictionary, options)
+    return term[0], parents, children, synonyms, labels
+
+
+def _run_rounds(agents, n_rounds, src, tgt, context_block, reasoning):
+    history: List[Tuple[int, int]] = []
+    metrics = {"input_token": 0, "output_token": 0, "api_calls": 0}
+    for round_idx in range(n_rounds):
+        if round_idx == 0:
+            system_prompt, base_prompt = build_task_prompt(src, tgt, reasoning=reasoning)
+        elif round_idx == n_rounds - 1:
+            system_prompt, base_prompt = build_last_round_prompt(src, tgt, history, perturb=False)
+        else:
+            system_prompt, base_prompt = build_round_prompt(src, tgt, history, perturb=False)
+        user_prompt = context_block + base_prompt
+        for agent in agents.values():
+            response, input_tokens, output_tokens = agent.generate(
+                system_prompt,
+                user_prompt,
+                include_tokens=True,
+                truncate=False,
+            )
+            history.append((extract_yes_no(response), extract_confidence(response)))
+            metrics["input_token"] += input_tokens
+            metrics["output_token"] += output_tokens
+            metrics["api_calls"] += 1
+    prediction, confidence = majority_vote(history)
+    return prediction, metrics, confidence
+
+
+class InferenceStrategy(ABC):
+    """Chooses agents and how many debate rounds to run."""
+
+    @abstractmethod
+    def agents(self, backend, model_name, agent_configs):
+        """Return the agent mapping and the number of rounds.
+
+        Returns:
+            tuple[dict[int, BaseModel], int | None]: Agents and rounds;
+            ``None`` rounds means use the ``n_rounds`` passed to :meth:`run`.
+        """
+
+    def run(
+        self,
+        backend,
+        model_name,
+        source_term,
+        target_term,
+        pcmaps,
+        dictionary,
+        options,
+        agent_configs,
+        n_rounds=3,
+        reasoning=False,
+        active_learning=False,
+        f1_score=0.0,
+        context=None,
+    ):
+        """Score one source/target pair.
+
+        Every agent answers in every round; the prediction is the majority
+        answer and the confidence its average (see
+        :func:`kroma.agents.utils.majority_vote`).
+
+        Args:
+            backend (str): Chat backend name.
+            model_name (str): Model name.
+            source_term (tuple): Source ``(code, ...)``.
+            target_term (tuple): Target ``(code, ...)``.
+            pcmaps (dict): ``{"source": pcmap, "target": pcmap}``.
+            dictionary (dict): Cached dictionaries.
+            options (list[str]): Context sources.
+            agent_configs (list[dict]): Agent configs for debate.
+            n_rounds (int): Rounds when the strategy does not fix them.
+            reasoning (bool): Passed to the prompt builder.
+            active_learning (bool): Accept the answer only when
+                :func:`~kroma.agents.utils.active_learning_score` is positive.
+            f1_score (float): Running F1, which scales the active-learning
+                noise.
+            context (str | None): Text placed before every user prompt.
+
+        Returns:
+            tuple: ``(prediction, metrics, confidence, accept)``. ``prediction``
+            is 1 or 0, ``metrics`` holds ``input_token``, ``output_token`` and
+            ``api_calls``, ``confidence`` is 0 to 10, and ``accept`` says
+            whether to refine the graph with this answer.
+        """
+        agents, rounds = self.agents(backend, model_name, agent_configs)
+        if rounds is None:
+            rounds = n_rounds
+        source = expand_term(source_term, pcmaps["source"], dictionary, options)
+        target = expand_term(target_term, pcmaps["target"], dictionary, options)
+        prediction, metrics, confidence = _run_rounds(
+            agents,
+            rounds,
+            source,
+            target,
+            context or "",
+            reasoning,
+        )
+        accept = True
+        if active_learning:
+            accept = active_learning_score(confidence, f1_score) > 0
+        return prediction, metrics, confidence, accept
+
+
+class SingleModelInference(InferenceStrategy):
+    """One model, one round."""
+
+    def agents(self, backend, model_name, agent_configs):
+        """Return one agent for ``backend``/``model_name`` and one round."""
+        return create_agents(1, backend, model_name), 1
+
+
+class DebateInference(InferenceStrategy):
+    """One agent per config, across the configured number of rounds.
+
+    Args:
+        n_rounds (int): Debate rounds.
+    """
+
+    def __init__(self, n_rounds: int):
+        self.n_rounds = n_rounds
+
+    def agents(self, backend, model_name, agent_configs):
+        """Return one agent per entry in ``agent_configs`` and ``n_rounds``."""
+        return create_agents_from_config(agent_configs), self.n_rounds
+
+
+def infer(
+    debate: bool,
+    backend: str,
+    model_name: str,
+    source_term: Tuple[str, str],
+    target_term: Tuple[str, str],
+    pcmaps: Dict[str, Dict[str, set]],
+    dictionary: Dict[str, Any],
+    options: List[str],
+    embed_model=None,
+    store=None,
+    agent_configs: List[Dict[str, str]] = None,
+    n_rounds: int = 3,
+    dropout: float = 0.5,
+    reasoning: bool = False,
+    active_learning: bool = False,
+    f1_score: float = 0.0,
+    bisim: bool = False,
+    context: str = None,
+):
+    """Run single-model or debate inference for one alignment pair.
+
+    ``embed_model``, ``store``, ``dropout`` and ``bisim`` are accepted so
+    existing callers keep working. Context is built by the matching run and
+    passed in. See :meth:`InferenceStrategy.run` for the other arguments.
+
+    Args:
+        debate (bool): Use :class:`DebateInference` instead of
+            :class:`SingleModelInference`.
+
+    Returns:
+        tuple: ``(prediction, metrics, confidence, accept)``.
+    """
+    strategy = DebateInference(n_rounds) if debate else SingleModelInference()
+    return strategy.run(
+        backend=backend,
+        model_name=model_name,
+        source_term=source_term,
+        target_term=target_term,
+        pcmaps=pcmaps,
+        dictionary=dictionary,
+        options=options,
+        agent_configs=agent_configs or [],
+        n_rounds=n_rounds,
+        reasoning=reasoning,
+        active_learning=active_learning,
+        f1_score=f1_score,
+        context=context,
+    )