# SPDX-FileCopyrightText: 2023-2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT
"""Faces: a pain.001 document projected into another standard (pain001 >= 0.0.78).
Two tools over :mod:`pain001.faces` (ADR-0005 in the core repository):
``list_faces`` names each face, its target and the bindings it accepts;
``project_face`` returns the target payload and a loss report of every
source element the target could not carry. The document arrives as XML
text and goes through :func:`pain001.faces.project_face_text`, which
never reads a server path and refuses entity declarations. The tools
are registered in :mod:`pain001_mcp.server` with the others.
"""
from __future__ import annotations
import importlib
from typing import Annotated, Any
from pydantic import Field
from typing_extensions import TypedDict
FACES_MISSING = (
"faces need pain001 >= 0.0.78; the installed pain001 has no "
"pain001.faces.project_face_text"
)
def _faces_api() -> Any | None:
"""Return :mod:`pain001.faces`, or ``None`` when the library predates it."""
try:
faces = importlib.import_module("pain001.faces")
except ImportError:
return None
return faces if hasattr(faces, "project_face_text") else None
def _face_names() -> list[str]:
"""The registered face names, or none when the library has no faces."""
faces = _faces_api()
return [] if faces is None else list(faces.available_faces())
_FACE_NAMES = _face_names()
_FACE_LIST = ", ".join(f"'{name}'" for name in _FACE_NAMES) or "see list_faces"
_XmlContent = Annotated[
str,
Field(
description=(
"The full pain.001 document as XML text (not a file path), "
"at most 10 MiB."
)
),
]
_FaceName = Annotated[
str,
Field(
description=f"The target face: one of {_FACE_LIST}.",
json_schema_extra={"enum": _FACE_NAMES} if _FACE_NAMES else None,
),
]
_Version = Annotated[
str | None,
Field(
description=(
"The pain.001 edition, e.g. 'pain.001.001.09'; omit to detect "
"it from the document's namespace."
)
),
]
_Bindings = Annotated[
dict[str, Any] | None,
Field(
description=(
"Values the message does not carry, keyed as list_faces names "
"them (e.g. {'ConsentId': '...'} for uk_open_banking); used for "
"this call only."
)
),
]
[docs]
class FaceEntry(TypedDict):
"""One face: its name, its target and the binding keys it accepts."""
name: str
description: str
bindings: list[str]
[docs]
class FaceListResult(TypedDict, total=False):
"""Every face, or an error when the library has none."""
error: str
count: int
faces: list[FaceEntry]
[docs]
class LossReportResult(TypedDict):
"""Source leaves carried and not carried, by indexed path."""
face: str
total_source_elements: int
mapped_count: int
unmapped_count: int
is_lossless: bool
loss_ratio: float
mapped_paths: list[str]
unmapped_paths: list[str]
[docs]
class FaceProjectionResult(TypedDict, total=False):
"""The target payload and its loss report, or the face's refusal."""
error: str
face: str
version: str
payload: dict[str, Any]
loss_report: LossReportResult
[docs]
def list_faces() -> FaceListResult:
"""List the faces: the standards a pain.001 document can be projected into.
Use this before ``project_face`` to pick a target and to learn which
bindings it accepts. A binding is a value the payment message does
not carry, such as the UK Open Banking ``ConsentId`` agreed with the
bank; any key a face does not list is refused.
Delegates to :func:`pain001.faces.list_supported_faces`.
Returns:
``{"count", "faces": [{"name", "description", "bindings"}, ...]}``,
or ``{"error": ...}`` when the installed pain001 has no faces.
"""
faces = _faces_api()
if faces is None:
return {"error": FACES_MISSING}
entries: list[FaceEntry] = faces.list_supported_faces()
return {"count": len(entries), "faces": entries}
[docs]
def project_face(
xml_content: _XmlContent,
face: _FaceName,
version: _Version = None,
bindings: _Bindings = None,
) -> FaceProjectionResult:
"""Project a pain.001 document into another standard's JSON shape.
Use this to turn a payment file into the request body a UK Open
Banking or Berlin Group API expects, or into ISO 20022 element names,
and to see exactly what the target cannot carry: the loss report
lists every source element left out, by indexed path. A face never
invents a value: when the target requires an element the document
lacks, the answer is an ``{"error": ...}`` naming it. To check the
document itself first, use ``validate_xml_against_schema``.
Delegates to :func:`pain001.faces.project_face_text`.
Args:
xml_content: The pain.001 document as XML text.
face: The target face.
version: The edition, or ``None`` to detect it.
bindings: Side inputs the face accepts, or ``None``.
Returns:
``{"face", "version", "payload", "loss_report"}``, or
``{"error": ...}`` when the face refuses the document or a
binding, or the installed pain001 has no faces.
"""
faces = _faces_api()
if faces is None:
return {"error": FACES_MISSING}
try:
result = faces.project_face_text(
xml_content, face, version=version, bindings=bindings
)
except faces.FaceError as exc:
return {"error": str(exc)}
projection: FaceProjectionResult = result.to_dict()
return projection