Source code for pain001_mcp._corpus

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

"""Example corpus tools (pain001 >= 0.0.67).

Four read-only tools over :mod:`pain001.corpus`: the index, one file, a
file's provenance sidecar, and an edition's schema coverage. An older
core without the corpus gets a clear error payload, never an import
failure.
"""

import importlib
from typing import Annotated, Any, cast

from pydantic import Field

from pain001_mcp._shapes import (
    CorpusCoverageResult,
    CorpusFileEntry,
    CorpusFileResult,
    CorpusListResult,
    CorpusProvenanceResult,
)

_CORPUS_MISSING = (
    "the example corpus needs pain001 >= 0.0.67; the installed pain001 "
    "has no pain001.corpus module"
)


def _corpus_api() -> Any | None:
    """Return :mod:`pain001.corpus`, or ``None`` when the library predates it.

    The corpus shipped in pain001 0.0.67; older releases are still valid
    peers of this server, so the four corpus tools report a clear error
    instead of failing at import time.
    """
    try:
        return importlib.import_module("pain001.corpus")
    except ImportError:
        return None


_CorpusKind = Annotated[
    str | None,
    Field(
        description=(
            "'market' for the realistic per-country scenarios, "
            "'coverage' for the schema coverage sets, or omit for both."
        )
    ),
]
_CorpusCountry = Annotated[
    str | None,
    Field(
        description=(
            "Two-letter country code to keep one market pack only, "
            "e.g. 'GB' or 'CH'. Ignored for coverage files."
        )
    ),
]
_CorpusVersion = Annotated[
    str | None,
    Field(
        description=(
            "Keep only files of this message type, e.g. 'pain.001.001.09'."
        )
    ),
]


def _entry(entry: Any) -> CorpusFileEntry:
    """Return the index row the tool reports for one corpus file."""
    return {
        "kind": entry.kind,
        "scenario_id": entry.scenario_id,
        "version": entry.version,
        "country": entry.country,
        "family": entry.family,
        "variant": entry.variant,
        "file": entry.path.name,
    }


[docs] def list_corpus_files( kind: _CorpusKind = None, country: _CorpusCountry = None, version: _CorpusVersion = None, ) -> CorpusListResult: """List the example files pain001 ships: market scenarios and coverage sets. Use this to discover the ``scenario_id``, ``version``, and ``variant`` identifiers of the ready-made, validated ISO 20022 files ``pain001`` ships; ``get_corpus_file`` and ``get_corpus_provenance`` accept those identifiers. Market files are realistic payments per country and rail (``scenario_id`` like ``gb.chaps.property-purchase``); a ``variant`` names the bank overlay a file was built with. Coverage files exercise every element and choice branch of one message type and carry no scenario. Delegates to :func:`pain001.corpus.list_files`. Args: kind: ``market``, ``coverage`` or ``None`` for both. country: Optional two-letter country filter for market files. version: Optional message-type filter. Returns: ``{"count", "files": [{"kind", "scenario_id", "version", "country", "family", "variant", "file"}, ...]}``, or ``{"error": ...}`` when the installed pain001 has no corpus. """ corpus = _corpus_api() if corpus is None: return {"error": _CORPUS_MISSING} wanted_country = country.upper() if country else None files: list[CorpusFileEntry] = [ _entry(entry) for entry in corpus.list_files(kind) if not (wanted_country and entry.country != wanted_country) and not (version and entry.version != version) ] return {"count": len(files), "files": files}
[docs] def get_corpus_file( scenario_id: Annotated[ str, Field( description=( "The market scenario, e.g. 'gb.chaps.property-purchase' " "(from list_corpus_files)." ) ), ], version: Annotated[ str, Field(description="The message type, e.g. 'pain.001.001.09'."), ], variant: Annotated[ str | None, Field( description=( "An overlay id for the bank variant, e.g. " "'gb.example.priority'; omit for the generic file." ) ), ] = None, ) -> CorpusFileResult: """Return the XML of one validated example file from the market corpus. Use this to show a model, a tester or a mapping exercise what a correct file for a given country and rail looks like in a given edition. The text is exactly what pain001 ships; it passed the XSD, the ISO MDR rules, the rail profile and the overlay when it was built. Delegates to :func:`pain001.corpus.get_file`. Args: scenario_id: The scenario. version: The message type. variant: The overlay id of a bank variant, else ``None``. Returns: ``{"scenario_id", "version", "variant", "xml"}``, or ``{"error": ...}`` when there is no such file or no corpus. """ corpus = _corpus_api() if corpus is None: return {"error": _CORPUS_MISSING} try: xml = corpus.get_file(scenario_id, version, variant) except FileNotFoundError as exc: return {"error": str(exc)} return { "scenario_id": scenario_id, "version": version, "variant": variant, "xml": xml, }
[docs] def get_corpus_provenance( scenario_id: Annotated[ str, Field(description="The market scenario (from list_corpus_files)."), ], version: Annotated[ str, Field(description="The message type, e.g. 'pain.001.001.09'."), ], variant: Annotated[ str | None, Field( description=( "An overlay id for the bank variant; omit for the generic " "file." ) ), ] = None, ) -> CorpusProvenanceResult: """Return the provenance sidecar of one example file. Use this to know how far to trust a file: the sources it was derived from, the confidence of the evidence (``verified``, ``derived`` or ``assumed``), the validation ladder result per rung, what the builder renamed or dropped to fit the edition, and the file's SHA-256. Delegates to :func:`pain001.corpus.provenance`. Args: scenario_id: The scenario. version: The message type. variant: The overlay id of a bank variant, else ``None``. Returns: The parsed sidecar as a dict, or ``{"error": ...}`` when there is no such file or no corpus. """ corpus = _corpus_api() if corpus is None: return {"error": _CORPUS_MISSING} try: record: dict = corpus.provenance(scenario_id, version, variant) except FileNotFoundError as exc: return {"error": str(exc)} return cast(CorpusProvenanceResult, record)
[docs] def get_corpus_coverage( version: Annotated[ str, Field(description="The message type, e.g. 'pain.001.001.13'."), ], ) -> CorpusCoverageResult: """Return the schema coverage verdict of one message type's coverage set. Use this to check that the shipped coverage files reach every element path and choice branch of an edition's XSD before relying on them to smoke a parser or a mapping. Delegates to :func:`pain001.corpus.coverage_report`. Args: version: The message type. Returns: The ``coverage.json`` content (path and branch counts and percentages, completeness, missing and exempt lists), or ``{"error": ...}`` when the edition has no set or there is no corpus. """ corpus = _corpus_api() if corpus is None: return {"error": _CORPUS_MISSING} try: report: dict = corpus.coverage_report(version) except FileNotFoundError as exc: return {"error": str(exc)} return cast(CorpusCoverageResult, report)