arms-agent 1.0.0__tar.gz

arms_agent-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+# Package-local ignores.  Hatchling ships the nearest VCS ignore file inside the
+# sdist and reads it when choosing files, so this file keeps build artifacts out
+# of the wheel and keeps the workspace's own ignore list from being published.
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage

arms_agent-1.0.0/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2026, The Board of Trustees of Leland Stanford Junior University
+All rights reserved.
+
+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.
+
+THIS SOFTWARE IS PROVIDED BY The Board of Trustees of Leland Stanford Junior University
+''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 Board of Trustees of Leland Stanford Junior University 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.
+
+The views and conclusions contained in the software and documentation are those of the
+authors and should not be interpreted as representing official policies, either expressed
+or implied, of The Board of Trustees of Leland Stanford Junior University.

arms_agent-1.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: arms-agent
+Version: 1.0.0
+Summary: An ontology-constrained LLM agent that standardizes legacy biomedical metadata into CEDAR templates
+Project-URL: Homepage, https://github.com/musen-lab/metadata-standardization-agent
+Project-URL: Repository, https://github.com/musen-lab/metadata-standardization-agent
+Project-URL: Issues, https://github.com/musen-lab/metadata-standardization-agent/issues
+Project-URL: Paper, https://arxiv.org/abs/2604.08552
+Author: Josef Hardi
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: biomedical,cedar,langgraph,llm-agent,metadata,ontology
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.12
+Requires-Dist: cedar-mcp>=1.3.0
+Requires-Dist: langchain-core<2.0,>=1.2
+Requires-Dist: langchain-openai<2.0,>=1.0
+Requires-Dist: langchain<2.0,>=1.2
+Requires-Dist: langgraph<2.0,>=1.0
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: python-dotenv>=1.2.1
+Provides-Extra: tracing
+Requires-Dist: langfuse<5.0,>=4.14; extra == 'tracing'
+Description-Content-Type: text/markdown
+
+# ARMS Agent
+
+An LLM agent that standardizes legacy biomedical metadata records into the [CEDAR](https://metadatacenter.org/) template format.
+
+It fetches the live CEDAR template and queries BioPortal for canonical terms through [Model Context Protocol](https://www.anthropic.com/news/model-context-protocol) tools, so the constraints it applies are the ones the template holds right now.
+
+This is the agent described in *Automated Standardization of Legacy Biomedical Metadata Using an Ontology-Constrained LLM Agent* ([arXiv:2604.08552](https://arxiv.org/abs/2604.08552)). The evaluation harness, the 839-record dataset, and the code for every figure in the paper live in the [project repository](https://github.com/musen-lab/metadata-standardization-agent).
+
+## Install
+
+```bash
+pip install arms-agent
+```
+
+## Configure
+
+Three keys are required. Put them in the environment, or in a `.env` file in the directory you run from:
+
+```
+OPENAI_API_KEY=...       # LLM calls
+CEDAR_API_KEY=...        # fetching CEDAR templates
+BIOPORTAL_API_KEY=...    # ontology term lookups
+```
+
+Optional: set `OPENAI_BASE_URL` to route LLM calls through an OpenAI-compatible gateway.
+
+To trace each LLM call, tool call, and agent step to [Langfuse](https://langfuse.com/), install the extra and
+set both keys:
+
+```bash
+pip install 'arms-agent[tracing]'
+```
+
+```
+LANGFUSE_PUBLIC_KEY=...
+LANGFUSE_SECRET_KEY=...
+LANGFUSE_HOST=...       # optional, defaults to Langfuse Cloud
+```
+
+Tracing stays off until both keys are set, and `LANGFUSE_TRACING_ENABLED=false` switches it off while leaving
+the keys in place.
+
+## Command line
+
+```bash
+arms-migrate \
+  --input legacy-record.json \
+  --target-schema https://repo.metadatacenter.org/templates/dd5e8653-81cf-470b-b71b-15cab421bb84 \
+  --output migrated.json \
+  --model gpt-5-mini
+```
+
+`--output` takes a file or a directory. Given a directory, the filename comes from the input; left out, the
+result lands in your temp directory. `--model` defaults to `gpt-5.6-terra`. Add `--debug` for step-by-step
+logging on stderr.
+
+## Python
+
+```python
+import asyncio, json
+
+from langchain_core.messages import HumanMessage
+
+from arms_agent.agent import build_migration_agent, build_response_format
+from arms_agent.prompts import SYSTEM_PROMPT
+from arms_agent.tools import all_tools
+from arms_agent.workflow import build_workflow
+
+template_iri = "https://repo.metadatacenter.org/templates/dd5e8653-81cf-470b-b71b-15cab421bb84"
+legacy = json.load(open("legacy-record.json"))
+
+agent = build_migration_agent(
+    model="gpt-5-mini",
+    system_prompt=SYSTEM_PROMPT,
+    response_format=build_response_format(template_iri),
+    tools=all_tools,
+    reasoning_effort="high",
+)
+
+result = asyncio.run(
+    build_workflow(agent).ainvoke(
+        {
+            "messages": [
+                HumanMessage(
+                    content=(
+                        "Migrate the following legacy metadata record to the CEDAR template.\n\n"
+                        f"CEDAR Template IRI: {template_iri}\n\n"
+                        f"Legacy metadata:\n```json\n{json.dumps(legacy, indent=2)}\n```"
+                    )
+                )
+            ],
+            "cedar_template_iri": template_iri,
+        },
+        config={"recursion_limit": 30},
+    )
+)
+print(json.dumps(result["metadata"], indent=2))
+```
+
+The agent answers against a JSON schema built from the template, so the result conforms to the template's field structure. When a model answers without a validated object, a fixed extraction step parses the text into one.
+
+## Caching
+
+CEDAR template and BioPortal term responses are cached in SQLite for 24 hours, to keep repeated runs fast and off the rate limits. Override with `ARMS_CACHE_DIR` and `ARMS_CACHE_TTL_SECONDS`.
+
+## Other settings
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `OPENAI_EXTRACTION_MODEL` | `gpt-4.1-mini` | The model that parses a reply into an object when the main model answers without one. |
+| `OPENAI_COST_MULTIPLIER` | `1.0` | Scales the reported cost when your endpoint charges a fraction of OpenAI's list prices. |
+| `OPENAI_COST_CACHE_DISCOUNT` | `true` | Whether the endpoint discounts cached input tokens. |
+
+Costs are local estimates from provider-reported token counts, not billed amounts.
+
+## License
+
+BSD 2-Clause.

arms_agent-1.0.0/README.md

@@ -0,0 +1,118 @@
+# ARMS Agent
+
+An LLM agent that standardizes legacy biomedical metadata records into the [CEDAR](https://metadatacenter.org/) template format.
+
+It fetches the live CEDAR template and queries BioPortal for canonical terms through [Model Context Protocol](https://www.anthropic.com/news/model-context-protocol) tools, so the constraints it applies are the ones the template holds right now.
+
+This is the agent described in *Automated Standardization of Legacy Biomedical Metadata Using an Ontology-Constrained LLM Agent* ([arXiv:2604.08552](https://arxiv.org/abs/2604.08552)). The evaluation harness, the 839-record dataset, and the code for every figure in the paper live in the [project repository](https://github.com/musen-lab/metadata-standardization-agent).
+
+## Install
+
+```bash
+pip install arms-agent
+```
+
+## Configure
+
+Three keys are required. Put them in the environment, or in a `.env` file in the directory you run from:
+
+```
+OPENAI_API_KEY=...       # LLM calls
+CEDAR_API_KEY=...        # fetching CEDAR templates
+BIOPORTAL_API_KEY=...    # ontology term lookups
+```
+
+Optional: set `OPENAI_BASE_URL` to route LLM calls through an OpenAI-compatible gateway.
+
+To trace each LLM call, tool call, and agent step to [Langfuse](https://langfuse.com/), install the extra and
+set both keys:
+
+```bash
+pip install 'arms-agent[tracing]'
+```
+
+```
+LANGFUSE_PUBLIC_KEY=...
+LANGFUSE_SECRET_KEY=...
+LANGFUSE_HOST=...       # optional, defaults to Langfuse Cloud
+```
+
+Tracing stays off until both keys are set, and `LANGFUSE_TRACING_ENABLED=false` switches it off while leaving
+the keys in place.
+
+## Command line
+
+```bash
+arms-migrate \
+  --input legacy-record.json \
+  --target-schema https://repo.metadatacenter.org/templates/dd5e8653-81cf-470b-b71b-15cab421bb84 \
+  --output migrated.json \
+  --model gpt-5-mini
+```
+
+`--output` takes a file or a directory. Given a directory, the filename comes from the input; left out, the
+result lands in your temp directory. `--model` defaults to `gpt-5.6-terra`. Add `--debug` for step-by-step
+logging on stderr.
+
+## Python
+
+```python
+import asyncio, json
+
+from langchain_core.messages import HumanMessage
+
+from arms_agent.agent import build_migration_agent, build_response_format
+from arms_agent.prompts import SYSTEM_PROMPT
+from arms_agent.tools import all_tools
+from arms_agent.workflow import build_workflow
+
+template_iri = "https://repo.metadatacenter.org/templates/dd5e8653-81cf-470b-b71b-15cab421bb84"
+legacy = json.load(open("legacy-record.json"))
+
+agent = build_migration_agent(
+    model="gpt-5-mini",
+    system_prompt=SYSTEM_PROMPT,
+    response_format=build_response_format(template_iri),
+    tools=all_tools,
+    reasoning_effort="high",
+)
+
+result = asyncio.run(
+    build_workflow(agent).ainvoke(
+        {
+            "messages": [
+                HumanMessage(
+                    content=(
+                        "Migrate the following legacy metadata record to the CEDAR template.\n\n"
+                        f"CEDAR Template IRI: {template_iri}\n\n"
+                        f"Legacy metadata:\n```json\n{json.dumps(legacy, indent=2)}\n```"
+                    )
+                )
+            ],
+            "cedar_template_iri": template_iri,
+        },
+        config={"recursion_limit": 30},
+    )
+)
+print(json.dumps(result["metadata"], indent=2))
+```
+
+The agent answers against a JSON schema built from the template, so the result conforms to the template's field structure. When a model answers without a validated object, a fixed extraction step parses the text into one.
+
+## Caching
+
+CEDAR template and BioPortal term responses are cached in SQLite for 24 hours, to keep repeated runs fast and off the rate limits. Override with `ARMS_CACHE_DIR` and `ARMS_CACHE_TTL_SECONDS`.
+
+## Other settings
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `OPENAI_EXTRACTION_MODEL` | `gpt-4.1-mini` | The model that parses a reply into an object when the main model answers without one. |
+| `OPENAI_COST_MULTIPLIER` | `1.0` | Scales the reported cost when your endpoint charges a fraction of OpenAI's list prices. |
+| `OPENAI_COST_CACHE_DISCOUNT` | `true` | Whether the endpoint discounts cached input tokens. |
+
+Costs are local estimates from provider-reported token counts, not billed amounts.
+
+## License
+
+BSD 2-Clause.

arms_agent-1.0.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "arms-agent"
+version = "1.0.0"
+description = "An ontology-constrained LLM agent that standardizes legacy biomedical metadata into CEDAR templates"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "BSD-2-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Josef Hardi" },
+]
+keywords = ["metadata", "cedar", "ontology", "biomedical", "langgraph", "llm-agent"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+dependencies = [
+    "langchain>=1.2,<2.0",
+    "langgraph>=1.0,<2.0",
+    "langchain-openai>=1.0,<2.0",
+    "langchain-core>=1.2,<2.0",
+    "pydantic>=2.0,<3.0",
+    "cedar-mcp>=1.3.0",
+    "python-dotenv>=1.2.1",
+]
+
+[project.optional-dependencies]
+# Every Langfuse import is function-local and gated on tracing_enabled(), so the
+# agent runs without it.  Only projects that trace pay for the SDK.
+tracing = [
+    "langfuse>=4.14,<5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/musen-lab/metadata-standardization-agent"
+Repository = "https://github.com/musen-lab/metadata-standardization-agent"
+Issues = "https://github.com/musen-lab/metadata-standardization-agent/issues"
+Paper = "https://arxiv.org/abs/2604.08552"
+
+[project.scripts]
+arms-migrate = "arms_agent.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arms_agent"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/arms_agent", "tests", "README.md", "LICENSE", "pyproject.toml"]
+# Hatchling always ships the nearest VCS ignore file and cannot be told not to,
+# so arms-agent/.gitignore exists to be that file.  Without it the workspace's own
+# ignore list is published, naming internal paths no installer needs.
+
+# These rules mirror the workspace root, kept inline rather than extended from it.
+# The sdist ships this file without its parent, so an `extend` there resolves to
+# nothing and every ruff run inside an unpacked sdist fails.
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "TCH",  # flake8-type-checking
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["arms_agent"]
+
+[tool.ruff.lint.per-file-ignores]
+# The system prompt is authored as Markdown; long lines and intentional
+# trailing-space line breaks are part of the prompt text.
+"src/arms_agent/prompts.py" = ["E501", "W291"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

arms_agent-1.0.0/src/arms_agent/__init__.py

@@ -0,0 +1,13 @@
+"""Metadata Standardization Agent: A LangGraph agent for migrating legacy metadata to CEDAR template format."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # pyproject.toml is the only place the version is written.  Reading it back
+    # from the installed distribution keeps a second copy from drifting.
+    __version__ = version("arms-agent")
+except PackageNotFoundError:
+    # A source tree that was never installed still has to import.
+    __version__ = "0+unknown"

arms_agent-1.0.0/src/arms_agent/__main__.py

@@ -0,0 +1,127 @@
+"""Entry point for running the metadata standardization agent."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import tempfile
+import time
+from pathlib import Path
+
+from dotenv import find_dotenv, load_dotenv
+from langchain_core.messages import HumanMessage
+
+from arms_agent.agent import build_migration_agent, build_response_format
+from arms_agent.logging_config import configure_logging
+from arms_agent.prompts import SYSTEM_PROMPT
+from arms_agent.token_tracker import TokenUsageTracker
+from arms_agent.tools import all_tools
+from arms_agent.tracing import flush_tracing, instrument, traced_run
+from arms_agent.workflow import build_workflow
+
+# Load environment variables from the nearest .env, searching upward from the working
+# directory.  Counting parent directories from this file would only work inside a source
+# checkout; installed from a wheel, the package sits in site-packages and has no project
+# root above it.  find_dotenv returns "" when there is no .env, and load_dotenv("") is a
+# no-op, so a run without one is fine.
+load_dotenv(find_dotenv(usecwd=True), override=True)
+
+logger = logging.getLogger("arms_agent.__main__")
+
+
+def main() -> None:
+    """Run the migration agent with a legacy metadata record and CEDAR template IRI."""
+    parser = argparse.ArgumentParser(
+        description="Migrate a legacy metadata record to a CEDAR template format.",
+    )
+    parser.add_argument("--input", required=True, help="Path to the legacy metadata JSON file.")
+    parser.add_argument("--target-schema", required=True, help="IRI of the CEDAR template to migrate to.")
+    parser.add_argument(
+        "--output",
+        help="Output file path or directory. If a directory, the output filename is derived from the input. "
+        f"(default: {Path(tempfile.gettempdir()) / 'migrated-metadata.json'})",
+    )
+    parser.add_argument(
+        "--model",
+        default="gpt-5.6-terra",
+        help="LLM model identifier (default: gpt-5.6-terra).",
+    )
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging to stderr.")
+    args = parser.parse_args()
+
+    configure_logging(args.debug)
+
+    logger.debug("Legacy metadata file: %s", args.input)
+    logger.debug("CEDAR template IRI: %s", args.target_schema)
+
+    with open(args.input) as f:
+        legacy_metadata = json.load(f)
+
+    user_message = (
+        f"Migrate the following legacy metadata record to the CEDAR template.\n\n"
+        f"CEDAR Template IRI: {args.target_schema}\n\n"
+        f"Legacy metadata:\n```json\n{json.dumps(legacy_metadata, indent=2)}\n```"
+    )
+
+    agent = build_migration_agent(
+        model=args.model,
+        system_prompt=SYSTEM_PROMPT,
+        response_format=build_response_format(args.target_schema),
+        tools=all_tools,
+        reasoning_effort="high",
+        reasoning_mode="standard",
+    )
+    workflow = build_workflow(agent)
+    tracker = TokenUsageTracker()
+    input_stem = Path(args.input).stem
+    run_metadata = {
+        "input_file": Path(args.input).name,
+        "template_iri": args.target_schema,
+        "model": args.model,
+    }
+    run_config = instrument(
+        {
+            "recursion_limit": 30,
+            "callbacks": [tracker],
+            "run_name": f"migrate-{input_stem}",
+            "tags": ["cli", "migrate"],
+            "metadata": run_metadata,
+        }
+    )
+    start = time.perf_counter()
+    try:
+        with traced_run(f"migrate-{input_stem}", run_metadata):
+            result = asyncio.run(
+                workflow.ainvoke(
+                    {
+                        "messages": [HumanMessage(content=user_message)],
+                        "cedar_template_iri": args.target_schema,
+                    },
+                    config=run_config,
+                )
+            )
+    finally:
+        # Traces of a failed run are the ones worth keeping, so flush either way.
+        flush_tracing()
+    elapsed = time.perf_counter() - start
+    if args.output is None:
+        output_path = Path(tempfile.gettempdir()) / "migrated-metadata.json"
+    elif Path(args.output).is_dir():
+        output_path = Path(args.output) / f"{input_stem}.json"
+    else:
+        output_path = Path(args.output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(result["metadata"], indent=2) + "\n")
+    print(f"Output written to: {output_path}")
+
+    decisions_path = output_path.with_suffix(".decisions.json")
+    decisions_path.write_text(json.dumps(result.get("decisions") or [], indent=2) + "\n")
+    print(f"Processing log written to: {decisions_path}")
+    print(f"Execution time: {elapsed:.2f}s")
+    print(tracker.usage_summary())
+
+
+if __name__ == "__main__":
+    main()

arms_agent-1.0.0/src/arms_agent/agent.py

@@ -0,0 +1,138 @@
+"""LangGraph agent for metadata migration."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import TYPE_CHECKING, Any, Literal
+
+from langchain.agents import create_agent
+from langchain.agents.structured_output import ProviderStrategy
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from langchain_core.tools import BaseTool
+    from langgraph.graph.state import CompiledStateGraph
+
+from arms_agent.schema import build_response_model
+from arms_agent.state import AgentState
+from arms_agent.tools import get_cedar_template
+
+logger = logging.getLogger(__name__)
+
+# OpenAI o-series reasoning models don't support parallel_tool_calls
+_O_SERIES = re.compile(r"^o\d")
+
+# Which models take reasoning settings.  Not gpt-5.6 alone: the o-series and the whole
+# gpt-5 family accept them, and a non-reasoning model such as gpt-4.1 rejects the
+# request outright with "'reasoning.effort' is not supported with this model".
+_REASONING_MODELS = re.compile(r"^(o\d|gpt-5)")
+
+# The values the API accepts, as it reports them when given anything else.
+ReasoningEffort = Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]
+ReasoningMode = Literal["standard", "pro"]
+
+# Where the OpenAI-compatible API lives.  ``OPENAI_BASE_URL`` is the OpenAI SDK's own
+# name for this, so a gateway configured for any other OpenAI client works here
+# unchanged; ``OPENAI_API_BASE`` is accepted as well because langchain reads that one.
+_BASE_URL_VARS = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
+
+
+def resolve_base_url() -> str | None:
+    """Return the API endpoint to call, or ``None`` for OpenAI's own.
+
+    Set one of the variables in :data:`_BASE_URL_VARS` to route every call through a
+    gateway, such as the Stanford API Gateway, instead of ``api.openai.com``.  The key
+    in ``OPENAI_API_KEY`` then has to be the one that gateway issues.
+    """
+    for name in _BASE_URL_VARS:
+        value = os.environ.get(name, "").strip()
+        if value:
+            return value
+    return None
+
+
+def _reasoning_kwargs(
+    model: str,
+    reasoning_effort: ReasoningEffort,
+    reasoning_mode: ReasoningMode,
+) -> dict[str, Any]:
+    """Return the reasoning settings to hand ``ChatOpenAI``.
+
+    A model that does not reason gets nothing, since it rejects the request outright.
+    """
+    if not _REASONING_MODELS.match(model):
+        return {}
+    return {"reasoning": {"effort": reasoning_effort, "mode": reasoning_mode}}
+
+
+def build_response_format(template_iri: str) -> ProviderStrategy:
+    """Return the provider-enforced response format for *template_iri*.
+
+    Raises:
+        ValueError: If the template cannot be fetched, which would otherwise bind an
+            empty schema and silently produce empty records for a whole run.
+    """
+    template_dict = get_cedar_template.invoke({"template_id": template_iri})
+    if "error" in template_dict or not template_dict.get("children"):
+        msg = f"Cannot build a response schema for {template_iri}: {template_dict.get('error', 'no fields returned')}"
+        raise ValueError(msg)
+    return ProviderStrategy(build_response_model(template_dict), strict=True)
+
+
+def build_migration_agent(
+    model: str,
+    system_prompt: str,
+    response_format: ProviderStrategy | None,
+    tools: Sequence[BaseTool],
+    reasoning_effort: ReasoningEffort = "low",
+    reasoning_mode: ReasoningMode = "standard",
+) -> CompiledStateGraph:
+    """Build the agent that performs the migration.
+
+    Args:
+        model: The OpenAI model identifier to use.
+        system_prompt: The system prompt carrying the agent's policy.
+        response_format: The schema the final answer is bound to.
+            ``None`` leaves the answer unconstrained, as free text the extraction node then has to parse.
+        tools: The tools this agent may call.
+        reasoning_effort: How much reasoning the model spends before answering.
+            Ignored by models that do not reason.
+        reasoning_mode: Which reasoning behaviour to use.  Ignored by models that
+            do not reason.
+
+    Returns:
+        A compiled agent graph.
+    """
+    from langchain_openai import ChatOpenAI
+
+    base_url = resolve_base_url()
+    reasoning_kwargs = _reasoning_kwargs(model, reasoning_effort, reasoning_mode)
+
+    logger.info(
+        "Building migration agent with model=%s, tools=%d, structured_output=%s, reasoning=%s, endpoint=%s",
+        model,
+        len(tools),
+        response_format is not None,
+        reasoning_kwargs or None,
+        base_url or "api.openai.com",
+    )
+    model_kwargs: dict[str, Any] = {}
+    if tools and not _O_SERIES.match(model):
+        model_kwargs["parallel_tool_calls"] = True
+    llm = ChatOpenAI(
+        base_url=base_url,
+        model=model,
+        temperature=0,
+        model_kwargs=model_kwargs,
+        **reasoning_kwargs,
+    )
+    return create_agent(
+        llm,
+        tools=tools,
+        system_prompt=system_prompt,
+        state_schema=AgentState,
+        response_format=response_format,
+    )