Source code for pain001_mcp._records

# SPDX-FileCopyrightText: 2023-2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT

"""Record tools: schema checks, identifiers, fixes, migration, charset, MT101.

Each tool works on the records or text it is given; none reads or
writes a file.
"""

import unicodedata
from typing import Annotated, Any, Literal

from pain001 import sanitize_to_charset
from pain001.migration import VersionMapper
from pain001.validation import validate_bic, validate_iban
from pain001.validation.charset import ISO20022_ALLOWED_CHARACTERS
from pain001_loader_mt101.loader import parse_mt101
from pydantic import Field

from pain001_mcp._common import (
    _check_message_type,
    _IdentifierChecks,
    _MessageType,
)
from pain001_mcp._ladder import verdict
from pain001_mcp._shapes import (
    MigrateResult,
    SanitiseResult,
    ValidateIdentifierResult,
    ValidateRecordsResult,
)

# SWIFT extended ("Z") character set. The pain001 library only implements the
# SWIFT basic ("X") set (``ISO20022_ALLOWED_CHARACTERS``). The Z set is a strict
# superset that additionally permits the following 13 punctuation characters,
# per the SWIFT Standards MT General Information character-set definitions:
#
#     = ! " % & * < > ; { @ # _
#
# (Note: the Z set does NOT include the vertical bar ``|`` or the closing brace
# ``}`` — a ``}`` in a Z-charset field raises SWIFT error M60.) Deriving the Z
# set from the library's X set keeps the two in lockstep if pain001 ever revises
# its base table.
_SWIFT_Z_EXTRA_CHARACTERS: frozenset[str] = frozenset('=!"%&*<>;{@#_')
_SWIFT_Z_ALLOWED_CHARACTERS: frozenset[str] = (
    ISO20022_ALLOWED_CHARACTERS | _SWIFT_Z_EXTRA_CHARACTERS
)


def _sanitize_to_swift_z(value: str, replacement: str = " ") -> str:
    """Transliterate ``value`` into the SWIFT extended ("Z") character set.

    Mirrors :func:`pain001.sanitize_to_charset` (NFKD-decompose, drop combining
    marks, then replace anything outside the permitted set) but validates
    against the wider SWIFT Z set rather than the basic X set, so extended
    punctuation such as ``@``, ``&`` and ``_`` survives.

    Args:
        value: The text to transliterate.
        replacement: The string substituted for characters that are outside
            the Z set even after transliteration (default: a single space).

    Returns:
        A string containing only SWIFT Z permitted characters.
    """
    decomposed = unicodedata.normalize("NFKD", value)
    stripped = "".join(
        ch for ch in decomposed if not unicodedata.combining(ch)
    )
    return "".join(
        ch if ch in _SWIFT_Z_ALLOWED_CHARACTERS else replacement
        for ch in stripped
    )


_RecordsToValidate = Annotated[
    list[dict],
    Field(
        description=(
            "One or more flat payment records to validate, each a dict "
            "of field name → value (see get_input_schema for the fields "
            "and get_required_fields for the mandatory ones)."
        )
    ),
]


[docs] def validate_records( message_type: _MessageType, records: _RecordsToValidate, identifier_checks: _IdentifierChecks = True, ) -> ValidateRecordsResult: """Validate flat records the way the pain001 CLI and REST API do. Use this before ``generate_message``: it runs the core's validation ladder (pain001.validate), so a batch it accepts is one the CLI, the REST API and ``generate_message`` accept, and a batch it refuses is refused there too. The ladder checks the row contract (required fields, amounts, booleans, dates), every IBAN and BIC (unless ``identifier_checks`` is false), that the rows form one payment information block, then the message type's JSON Schema (for example an ISO 4217 currency). For payment-scheme rulebook checks (SEPA field lengths, charset, etc.) also run ``validate_payment_scheme``. The row contract and identifier checks refuse the batch as a whole (``valid_count`` 0) and name the first problems; the schema check then reports every row. Each error carries ``row`` (from 0), ``line`` (from 1), ``path`` (the field), ``code`` (the core's stable ``P001-E...`` issue code) and ``message``, which never repeats the value. Returns a report ``{"valid": bool, "total": int, "valid_count": int, "errors": [...]}``, or ``{"error": ...}`` for rows that do not form one batch, an empty list or an unknown message type. Args: message_type: A supported ISO 20022 pain message type. records: One or more flat payment records to validate. identifier_checks: If false, skip the IBAN and BIC checks. """ try: message_type = _check_message_type(message_type) except ValueError as exc: return {"error": str(exc)} return verdict(message_type, records, identifier_checks)
[docs] def suggest_record_fix( record: Annotated[ dict[str, Any], Field(description="One flat payment record; never modified."), ], validation_error: Annotated[ dict[str, Any], Field(description="Finding with field (or path) and rule keys."), ], message_type: _MessageType = "pain.001.001.03", ) -> dict[str, Any]: """Suggest deterministic, review-only fixes to non-financial fields. Returns patches or a cannot_autofix reason. Never changes IBANs, BICs, accounts, amounts or currencies, even for whitespace. Review every candidate and validate the full record before generating a payment. Args: record: A flat payment record, left unchanged. validation_error: Finding with field (or path) and rule keys. message_type: Supported schema supplying trusted field bounds. """ try: from pain001.validation.corrections import ( suggest_record_fix as suggest, ) except ImportError: return { "error": "This tool requires the matching core feature build with record corrections." } try: return suggest( record, validation_error, _check_message_type(message_type) ) except ValueError as exc: return {"error": str(exc)}
[docs] def validate_identifier( kind: Annotated[ str, Field( description=( "Which identifier to validate: 'iban' or 'bic' " "(case-insensitive). Any other value returns an error." ) ), ], value: Annotated[ str, Field( description=( "The identifier string to check — an IBAN or BIC/SWIFT code " "matching the chosen kind." ) ), ], ) -> ValidateIdentifierResult: """Validate a single financial identifier (IBAN or BIC). Use this for a one-off identifier check with a clear pass/fail and reason. To validate identifiers embedded across a whole batch, prefer ``validate_records`` / ``validate_payment_scheme`` instead of calling this per field. Returns ``{"kind": str, "value": str, "valid": bool, "error": str}`` (the ``error`` key is present only when ``valid`` is ``False``). Args: kind: One of ``"iban"`` or ``"bic"`` (case-insensitive). value: The identifier value to check. """ try: kind_norm = kind.lower() if kind_norm == "iban": ok, err = validate_iban(value, strict=False) elif kind_norm == "bic": ok, err = validate_bic(value, strict=False) else: raise ValueError( f"Unsupported identifier kind: {kind!r} " f"(expected 'iban' or 'bic')" ) payload: ValidateIdentifierResult = { "kind": kind_norm, "value": value, "valid": bool(ok), } if not ok and err: payload["error"] = err return payload except ValueError as exc: return {"error": str(exc)}
_RecordsToMigrate = Annotated[ list[dict], Field( description=( "Flat payment records in the from_version shape, each a dict " "of field name → value, to transform to to_version." ) ), ] _FromVersion = Annotated[ str, Field( description=( "Source pain.001 schema version the records currently use, " "e.g. 'pain.001.001.03' — see list_message_types." ) ), ] _ToVersion = Annotated[ str, Field( description=( "Target pain.001 schema version to migrate the records to, " "e.g. 'pain.001.001.09' — see list_message_types." ) ), ]
[docs] def migrate_records( records: _RecordsToMigrate, from_version: _FromVersion, to_version: _ToVersion, ) -> MigrateResult: """Migrate flat payment records between two pain.001 schema versions. Use this to upgrade/downgrade records when your bank requires a different pain.001 version than your source data uses (e.g. move ``.03`` rows to ``.09``); it reports which fields were renamed, derived, or dropped. This transforms records only — run ``validate_records`` afterwards, then ``generate_message`` to emit XML. Wraps :class:`pain001.migration.VersionMapper`. Returns the migrated rows plus a summary of which fields were renamed, derived, or dropped; ``{"error": ...}`` if either version is unsupported. Args: records: Records in the ``from_version`` shape. from_version: Source pain.001 version (e.g. ``"pain.001.001.03"``). to_version: Target pain.001 version (e.g. ``"pain.001.001.09"``). Returns: ``{"records": [...], "migrated": int, "from": str, "to": str}`` or ``{"error": ...}``. """ try: mapper = VersionMapper() migrated = mapper.migrate_rows(records, from_version, to_version) return { "records": migrated, "migrated": len(migrated), "from": from_version, "to": to_version, } except Exception as exc: # noqa: BLE001 - DataSourceError + others return {"error": str(exc)}
_FreeText = Annotated[ str, Field( description=( "A single free-text field value (e.g. a name or remittance " "line) to transliterate to the ISO 20022 Latin character set." ) ), ] _Charset = Annotated[ Literal["SWIFT_X", "SWIFT_Z"], Field( description=( "Which SWIFT character set to sanitise against. 'SWIFT_X' " "(default) is the basic set permitted in most ISO 20022 / " "pain.001 fields: letters, digits, space and the punctuation " "/ - ? : ( ) . , ' + . 'SWIFT_Z' is the extended superset that " 'additionally allows = ! " % & * < > ; { @ # _ (used in ' "narrative / envelope fields); it does NOT allow | or }. Pick " "SWIFT_Z only when the target field is documented as Z-set." ) ), ]
[docs] def sanitize_to_iso20022_charset( value: _FreeText, charset: _Charset = "SWIFT_X", ) -> SanitiseResult: """Sanitise one free-text field to a SWIFT / ISO 20022 character set. Use this on a single free-text value (name, remittance info) to transliterate accents and drop unsupported symbols before placing it in a record, and to see whether the value changed. Operates on one string; to check a whole batch's rulebook compliance use ``validate_payment_scheme``. Two character sets are supported via ``charset``: * ``"SWIFT_X"`` (default, backward-compatible) - the basic set used in most ISO 20022 / pain.001 fields. Delegates to :func:`pain001.sanitize_to_charset`. * ``"SWIFT_Z"`` - the SWIFT extended set, a strict superset of X that also permits ``= ! " % & * < > ; { @ # _`` (used in narrative / envelope fields). It does not permit ``|`` or ``}``. In both cases accents are transliterated (``é`` -> ``e``) and any remaining out-of-set character is replaced with a space. The result includes flags for whether the original was already valid and whether it changed - useful for surfacing the change to the user before writing it back to a record. Args: value: The text to sanitise. charset: ``"SWIFT_X"`` (default) or ``"SWIFT_Z"``. Returns: ``{"value": str, "sanitised": str, "was_valid": bool, "changed": bool}``. """ if charset == "SWIFT_Z": cleaned = _sanitize_to_swift_z(value) else: cleaned = sanitize_to_charset(value) return { "value": value, "sanitised": cleaned, "was_valid": cleaned == value, "changed": cleaned != value, }
[docs] def convert_mt101( mt101_text: Annotated[ str, Field( description=( "A legacy SWIFT MT101 (Request for Transfer) message as text " "— a bare ':tag:' field list or a raw '{4:...-}' block-4 " "envelope. An MT101 may carry several sequence-B transfers; " "each becomes its own record." ) ), ], ) -> list[dict] | dict: """Convert a legacy SWIFT MT101 message into pain.001-ready records. Use this to bridge the Nov-2025+ SWIFT MT→MX migration: parse an MT101 (*Request for Transfer*) into the flat records the other tools consume — feed the result straight to ``validate_records`` / ``validate_payment_scheme`` and then ``generate_message`` to emit pain.001.001.09 XML. An MT101 can request many transfers (repeating sequence B), so this returns *one record per transaction*. Operates on the supplied text only; no file is read or written. Wraps :func:`pain001_loader_mt101.loader.parse_mt101`. Sequence-A ordering-customer / account-servicing fields apply to every transaction unless a sequence-B block overrides them; fields the MT101 does not carry are synthesised to schema defaults (``payment_method`` ``"TRF"``, ``service_level_code`` ``"SEPA"``, etc.). Args: mt101_text: The MT101 payload as a string. Returns: A list of flat pain.001 records (one per transaction), or an ``{"error": ...}`` dict if the MT101 is missing a mandatory field (``:20:``, ``:30:``, or per transaction ``:21:`` / ``:32B:`` / a named beneficiary) or is otherwise malformed. """ try: return parse_mt101(mt101_text) except ValueError as exc: return {"error": str(exc)}