Source code for pain001_mcp._schemes

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

"""Scheme tools: rulebook validation and the batch pre-flight simulation."""

from decimal import Decimal, InvalidOperation
from typing import Annotated, Any, cast

from pain001 import canonicalize_payment_record, validate_scheme
from pain001.plugins import registry as scheme_registry
from pain001.validation.rails import rail
from pain001.validation.schemes import PROFILES
from pydantic import Field

from pain001_mcp._common import (
    _RECORDS_FIELD_GUIDE,
    _MessageType,
    _OptionalSchemeProfile,
    _SchemeProfile,
)
from pain001_mcp._records import validate_records
from pain001_mcp._shapes import (
    DuplicateTransaction,
    SchemeProfileEntry,
    SchemeProfilesResult,
    SchemeResult,
    SchemeViolation,
    SimulatePaymentBatchResult,
)

_SchemeRecords = Annotated[
    list[dict],
    Field(
        description=(
            "Payment records as a list of flat dicts (field name → "
            "value) to check against the scheme rulebook."
        )
    ),
]
_SimulatedRecords = Annotated[
    list[dict],
    Field(
        description=(
            "One or more flat payment records to simulate and pre-flight "
            "before generating XML. " + _RECORDS_FIELD_GUIDE
        )
    ),
]

#: Debtor, creditor, amount, currency and execution date of one payment.
_TxKey = tuple[str, str, str, str, str]


[docs] def validate_payment_scheme( records: _SchemeRecords, profile: _SchemeProfile = "sepa-sct", ) -> SchemeResult: """Validate records against a payment-scheme rulebook (e.g. SEPA). Use this after ``validate_records`` to enforce scheme-specific business rules (SEPA field lengths, allowed characters, currency/BIC constraints) that JSON-Schema validation alone does not cover. ``validate_records`` checks structural shape; this checks rulebook compliance for one profile. Delegates to :func:`pain001.validate_scheme`. The ``profile`` parameter lists every profile the installed pain001 ships. Args: records: Payment records as a list of flat dicts. profile: The scheme profile name. Returns: ``{"profile", "is_valid", "violations": [...]}`` with structured ``violations`` (each with ``rule``, ``severity``, ``field``, ``message``, ``remediation`` keys), or ``{"error": ...}`` for an unknown profile. """ try: result = validate_scheme(records, profile) except ValueError as exc: return {"error": str(exc)} return { "profile": result.profile, "is_valid": result.is_valid, "violations": [ cast(SchemeViolation, v.as_dict()) for v in result.violations ], }
def _upper(record: dict[str, Any], key: str) -> str: """Return ``record[key]`` as stripped upper-case text (``""`` if absent).""" return str(record.get(key, "")).strip().upper() def _control_sums(sums: dict[str, Decimal]) -> dict[str, str]: """Return the per-currency totals as two-decimal strings, by currency.""" return {curr: f"{total:.2f}" for curr, total in sorted(sums.items())} def _tally(raw: Any, curr: str, sums: dict[str, Decimal]) -> str: """Add one amount to its currency total and return its key text. Args: raw: The record's ``payment_amount``, as given. curr: The record's currency; an empty one is not totalled. sums: Running totals by currency, updated in place. Returns: The amount to two decimals, the raw text when it is not a number, or ``""`` when there is no amount. """ if raw is None: return "" try: amount = Decimal(str(raw)) text = f"{amount:.2f}" if curr: sums[curr] = sums.get(curr, Decimal(0)) + amount except (InvalidOperation, TypeError): return str(raw).strip() return text def _duplicate(row: int, key: _TxKey, first: int) -> DuplicateTransaction: """Return the report of row ``row`` repeating row ``first``.""" debtor, creditor, amount, curr, date_val = key return { "row": row, "matching_row": first, "debtor_account_IBAN": debtor, "creditor_account_IBAN": creditor, "amount": amount, "currency": curr, "requested_execution_date": date_val, } def _parties(records: list[dict[str, Any]], key: str) -> set[str]: """Return the distinct non-empty account IBANs under ``key``.""" return {_upper(record, key) for record in records} - {""} def _scan_batch( records: list[dict[str, Any]], ) -> tuple[dict[str, Decimal], list[DuplicateTransaction]]: """Total the amounts and find duplicates across canonical records. Returns: Totals by currency, and every row that repeats an earlier one's debtor, creditor, amount, currency and execution date. """ sums: dict[str, Decimal] = {} duplicates: list[DuplicateTransaction] = [] seen: dict[_TxKey, int] = {} for row, record in enumerate(records): debtor = _upper(record, "debtor_account_IBAN") creditor = _upper(record, "creditor_account_IBAN") curr = _upper(record, "currency") date_val = str(record.get("requested_execution_date", "")).strip() amount = _tally(record.get("payment_amount"), curr, sums) if not (debtor and creditor and amount and curr): continue key = (debtor, creditor, amount, curr, date_val) if key in seen: duplicates.append(_duplicate(row, key, seen[key])) else: seen[key] = row return sums, duplicates
[docs] def simulate_payment_batch( message_type: _MessageType, records: _SimulatedRecords, scheme: _OptionalSchemeProfile = None, ) -> SimulatePaymentBatchResult: """Simulate and pre-flight a payment batch before XML generation. Performs comprehensive pre-flight verification without generating XML or staging files: 1. Validates records against the message type's JSON Schema. 2. Validates records against an optional payment-scheme rulebook. 3. Computes control sums grouped by currency. 4. Calculates unique debtor and creditor account counts. 5. Detects intra-batch duplicate transactions (same debtor, creditor, amount, currency, and execution date). Returns a structured verdict with totals, sums by currency, duplicate findings, and schema/scheme errors. Args: message_type: A supported ISO 20022 pain message type. records: One or more flat payment records to simulate. scheme: Optional payment scheme profile to validate against. """ report = validate_records(message_type, records) if "error" in report: return {"error": report["error"]} canonical = [canonicalize_payment_record(r) for r in records] sums, duplicates = _scan_batch(canonical) scheme_violations: list[SchemeViolation] = [] scheme_valid = True if scheme is not None: scheme_res = validate_payment_scheme(records, profile=scheme) if "error" in scheme_res: return {"error": scheme_res["error"]} scheme_violations = scheme_res.get("violations", []) scheme_valid = scheme_res.get("is_valid", True) valid = report.get("valid", False) and scheme_valid and not duplicates return { "valid": bool(valid), "total": report.get("total", len(records)), "valid_count": report.get("valid_count", 0), "control_sum_by_currency": _control_sums(sums), "unique_debtors": len(_parties(canonical, "debtor_account_IBAN")), "unique_creditors": len(_parties(canonical, "creditor_account_IBAN")), "duplicates": duplicates, "schema_errors": report.get("errors", []), "scheme_violations": scheme_violations, }
def _profile_entry(name: str) -> SchemeProfileEntry: """Describe one profile from the core's own data. The description is the scheme plugin's (what ``pain001 plugins list`` shows); a rail gives its rule-id prefix and sources, a purpose mandate its sources. """ plugin = scheme_registry.get_scheme(name) try: backing: Any = rail(name) prefix: str | None = backing.prefix except KeyError: backing, prefix = PROFILES[name], None return { "name": name, "description": plugin.meta.description if plugin else "", "rule_prefix": prefix, "sources": list(getattr(backing, "sources", ())), }
[docs] def list_scheme_profiles() -> SchemeProfilesResult: """List every payment-scheme rulebook profile the core ships. Use this to choose the ``profile`` for ``validate_payment_scheme`` (or the ``scheme`` of ``simulate_payment_batch`` and ``stage_payment_batch``) before calling it. Each entry gives the profile name, a one-line description, the prefix of the rule ids a rail profile reports (null for the SEPA, cross-border, duplicate and purpose-mandate profiles), and the public documents it was built from. Everything comes from the installed pain001; nothing is restated here. Returns: ``{"count": int, "profiles": [{"name", "description", "rule_prefix", "sources"}, ...]}`` in name order. """ profiles = [_profile_entry(name) for name in sorted(PROFILES)] return {"count": len(profiles), "profiles": profiles}