# SPDX-FileCopyrightText: 2023-2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT
"""Generation tools: pain XML from records in memory or from a data file.
The rows climb the core's validation ladder first, as ``pain001
generate`` and the REST API's generate route make them, so nothing is
generated that those refuse; the XML is then XSD-validated by the core
before it is returned. No tool here writes a file.
``validate_xml_against_schema`` runs the same XSD check on an XML string
the caller already holds.
"""
import asyncio
from typing import Annotated, Any
from pain001 import generate_xml_string
from pain001.async_adapter import generate_xml_string_async
from pain001.exceptions import Pain001Error
from pain001.validation.ladder import load_valid
from pain001.xml.validate_via_xsd import validate_xml_string_via_xsd
from pydantic import Field
from pain001_mcp._common import (
_RECORDS_FIELD_GUIDE,
_check_message_type,
_IdentifierChecks,
_MessageType,
_template_bundle,
_template_dir,
)
from pain001_mcp._ladder import error_payload, prepared
from pain001_mcp._shapes import XsdResult
def _admit(
message_type: str, source: str | list[dict[str, Any]], checks: bool
) -> tuple[str, str, str, list[dict[str, Any]]]:
"""Resolve the type and return its bundle and the admitted rows.
Args:
message_type: The type as the caller gave it (aliases allowed).
source: A data file path, or records already ``prepared``.
checks: If false, skip the IBAN, BIC and LEI checks.
Returns:
``(message type, template path, XSD path, rows)``.
A ``ValueError`` for an unknown type and the ladder's
``PaymentValidationError`` propagate.
"""
message_type = _check_message_type(message_type)
template_xml, xsd_schema = _template_bundle(message_type)
rows = load_valid(source, message_type, checks)
return message_type, template_xml, xsd_schema, rows
[docs]
def generate_message(
message_type: _MessageType,
records: Annotated[
list[dict],
Field(description=_RECORDS_FIELD_GUIDE),
],
identifier_checks: _IdentifierChecks = True,
) -> str:
"""Generate a validated ISO 20022 pain XML message from in-memory records.
This is the primary generation tool: pass records you already hold in
memory. Use ``generate_message_from_file`` when the data lives in a CSV
on disk, and ``generate_message_async`` for very large batches you want
to run off the event loop. The result is XSD-validated before return; no
file is written.
Records are normalized before rendering: 'amount'/'currency' aliases,
JSON booleans, and bare 'YYYY-MM-DD' dates are accepted, and
nb_of_txs/ctrl_sum are computed from the records. On failure the
``{"error": ...}`` payload lists every missing or invalid field at
once. The records are validated first exactly as ``validate_records``
and the pain001 CLI validate them (row contract, every IBAN and BIC
unless ``identifier_checks`` is false, one payment information
block, the JSON Schema); values are never coerced.
Returns the validated XML document as a string, or a JSON-encoded
``{"error": ..., "issues": [...]}`` payload if generation fails;
``issues`` (present when the validation refused the rows) lists each
finding's ``line``, ``column``, ``P001-E...`` ``code`` and
``message``.
Args:
message_type: A supported ISO 20022 pain message type.
records: One or more flat payment records.
identifier_checks: If false, skip the IBAN and BIC checks.
"""
try:
message_type, template_xml, xsd_schema, rows = _admit(
message_type, prepared(records), identifier_checks
)
return generate_xml_string(
rows, message_type, template_xml, xsd_schema
)
except (ValueError, RuntimeError, Pain001Error) as exc:
return error_payload(exc)
[docs]
async def generate_message_async(
message_type: _MessageType,
records: Annotated[
list[dict],
Field(
description=(
"Same record shape and ergonomics as generate_message; use "
"this async variant only when the batch is large. "
+ _RECORDS_FIELD_GUIDE
)
),
],
identifier_checks: _IdentifierChecks = True,
) -> str:
"""Generate validated pain XML off the event loop, for large batches.
Behaves exactly like ``generate_message`` but runs the synchronous
renderer in a worker thread so an agent can interleave a long
generation with other tool calls. Use ``generate_message`` for small
or interactive batches; use this only when the record count is large
enough that blocking would matter.
Validates in a worker thread, then delegates to
:func:`pain001.async_adapter.generate_xml_string_async`. Returns the
validated XML, or the same JSON-encoded ``{"error", "issues"?}``
payload as ``generate_message``.
Args:
message_type: A supported ISO 20022 pain message type.
records: One or more flat payment records.
identifier_checks: If false, skip the IBAN and BIC checks.
"""
try:
message_type, template_xml, xsd_schema, rows = await asyncio.to_thread(
_admit, message_type, prepared(records), identifier_checks
)
return await generate_xml_string_async(
rows, message_type, template_xml, xsd_schema
)
except (ValueError, RuntimeError, Pain001Error) as exc:
return error_payload(exc)
[docs]
def generate_message_from_file(
message_type: _MessageType,
data_file_path: Annotated[
str,
Field(
description=(
"Local filesystem path, below the server's working "
"directory, to a payment data file: CSV (one record per "
"row, a header matching the template columns, see "
"inspect_template), SQLite, JSON, JSONL or Parquet (see "
"list_supported_formats)."
)
),
],
) -> str:
"""Generate validated pain XML from a payment data file on the local disk.
Use this when the records live in a file rather than in memory; if
you already have them as dicts, call ``generate_message``. The file
is read and validated by the core's own loader and validation
ladder, exactly as ``pain001 generate`` reads it, so the same
path-safety guards apply and the same files are refused; an issue's
``line`` is the file's line (a CSV header is line 1).
Args:
message_type: A supported ISO 20022 pain message type.
data_file_path: Path to the payment data file.
Returns:
The validated XML, or a JSON-encoded ``{"error", "issues"?}``
payload as ``generate_message`` returns it.
"""
try:
message_type, template_xml, xsd_schema, rows = _admit(
message_type, data_file_path, True
)
return generate_xml_string(
rows, message_type, template_xml, xsd_schema
)
except Exception as exc: # noqa: BLE001 - many concrete types possible
return error_payload(exc)
[docs]
def validate_xml_against_schema(
xml_content: Annotated[
str,
Field(
description=(
"The full pain.001 / pain.008 XML document as a string, "
"validated against the message type's official XSD."
)
),
],
message_type: _MessageType,
) -> XsdResult:
"""Validate a raw pain.001 / pain.008 XML string against its official XSD.
Use this to check XML you already have as a string (e.g. received from
another system) without touching the filesystem. To validate records
*before* they become XML, use ``validate_records``; to parse a statement
or status-report file, use ``parse_camt053`` / ``parse_pain002``.
Wraps :func:`pain001.xml.validate_via_xsd.validate_xml_string_via_xsd`.
Args:
xml_content: The XML document as a string.
message_type: A supported ISO 20022 pain message type.
Returns:
``{"valid": bool, "message_type": str, "error": str?}`` -
``error`` is present only when ``valid`` is ``False``.
"""
try:
message_type = _check_message_type(message_type)
xsd = _template_dir(message_type) / f"{message_type}.xsd"
if not xsd.is_file(): # pragma: no cover - all valid types ship XSD
return {"error": f"No XSD bundled for {message_type}"}
try:
ok = validate_xml_string_via_xsd(xml_content, str(xsd))
except (
Exception
) as exc: # pragma: no cover - underlying API returns False, not raises
return {
"valid": False,
"message_type": message_type,
"error": str(exc),
}
return {"valid": bool(ok), "message_type": message_type}
except ValueError as exc:
return {"error": str(exc)}