# SPDX-FileCopyrightText: 2023-2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT
"""Result shapes: the TypedDicts every tool's output schema comes from.
Every tool returns a JSON object, and any tool can answer with
``{"error": "..."}`` instead of its payload (ADR 0001: errors as data), so
each shape lists the payload keys plus ``error`` and marks all of them
optional. The MCP SDK derives the tool's outputSchema from these, which is
what an agent reads to know the keys before it calls; the exact keys and
wording are pinned by tests/test_tool_result_shapes.py.
"""
from typing import Any
# pydantic resolves nested TypedDicts on Python 3.11 only for the
# typing_extensions class; typing.TypedDict there yields no output schema.
from typing_extensions import TypedDict
[docs]
class ErrorResult(TypedDict, total=False):
"""The failure payload every tool may return instead of its result."""
error: str
[docs]
class SchemaResult(TypedDict, total=False):
"""A JSON Schema (draft 7) for one message type's flat records."""
error: str
title: str
description: str
type: str
properties: dict[str, Any]
required: list[str]
additionalProperties: bool
version: str
[docs]
class RecordError(TypedDict):
"""One finding: the record's row and line, the field, the code, why.
``row`` counts records from 0 and ``line`` from 1, as the core's
issues do; ``code`` is the core's stable ``P001-E...`` issue code.
"""
row: int
line: int
path: str
code: str
message: str
[docs]
class ValidateRecordsResult(TypedDict, total=False):
"""Verdict over a batch: one entry per violation, plus the counts."""
error: str
valid: bool
total: int
valid_count: int
errors: list[RecordError]
[docs]
class ValidateIdentifierResult(TypedDict, total=False):
"""An IBAN or BIC verdict, with the library's message when invalid."""
error: str
kind: str
value: str
valid: bool
[docs]
class Camt053Result(TypedDict, total=False):
"""A parsed camt.053: the first statement's fields, and every one."""
error: str
statement_id: str
electronic_sequence_number: str
iban: str
currency: str
entries: list[dict[str, Any]]
statements: list[dict[str, Any]]
[docs]
class Pain002Result(TypedDict, total=False):
"""A parsed pain.002 status report, as the core library reports it."""
error: str
message_id: str
creation_datetime: str
original_message_id: str
original_message_name_id: str
group_status: str
payment_statuses: list[dict[str, Any]]
[docs]
class TemplateResult(TypedDict, total=False):
"""The bundled CSV template's column names for one message type."""
error: str
message_type: str
columns: list[str]
[docs]
class SchemeViolation(TypedDict):
"""One rulebook violation, with the remediation the library suggests."""
rule: str
field: str
index: int
message: str
remediation: str
severity: str
[docs]
class SchemeResult(TypedDict, total=False):
"""Verdict against a scheme rulebook profile."""
error: str
profile: str
is_valid: bool
violations: list[SchemeViolation]
[docs]
class DuplicateTransaction(TypedDict):
"""An intra-batch duplicate payment transaction."""
row: int
matching_row: int
debtor_account_IBAN: str
creditor_account_IBAN: str
amount: str
currency: str
requested_execution_date: str
[docs]
class SimulatePaymentBatchResult(TypedDict, total=False):
"""Simulation and pre-flight verdict over a payment batch."""
error: str
valid: bool
total: int
valid_count: int
control_sum_by_currency: dict[str, str]
unique_debtors: int
unique_creditors: int
duplicates: list[DuplicateTransaction]
schema_errors: list[RecordError]
scheme_violations: list[SchemeViolation]
MigrateResult = TypedDict(
"MigrateResult",
{
"error": str,
"records": list[dict[str, Any]],
"migrated": int,
"from": str,
"to": str,
},
total=False,
)
MigrateResult.__doc__ = (
"Records rewritten from one message edition to another."
)
[docs]
class XsdResult(TypedDict, total=False):
"""Verdict of an XML document against the official XSD."""
error: str
valid: bool
message_type: str
[docs]
class SanitiseResult(TypedDict, total=False):
"""A value and its ISO 20022 charset-clean rendering."""
value: str
sanitised: str
was_valid: bool
changed: bool
[docs]
class CorpusFileEntry(TypedDict, total=False):
"""One file of the example corpus, as the index lists it.
Market files name a scenario, a country and a rail family; coverage
files carry the edition only, so those three are null for them.
"""
scenario_id: str | None
version: str
variant: str | None
kind: str
file: str
country: str | None
family: str | None
[docs]
class CorpusListResult(TypedDict, total=False):
"""The example corpus index."""
error: str
count: int
files: list[CorpusFileEntry]
[docs]
class CorpusFileResult(TypedDict, total=False):
"""One corpus XML file with the request echoed beside it."""
error: str
scenario_id: str
version: str
variant: str | None
xml: str
[docs]
class CorpusProvenanceResult(TypedDict, total=False):
"""A scenario's provenance record, as the corpus ships it."""
error: str
scenario: str
message_type: str
variant: str | None
country: str
family: str
description: str
sha256: str
provenance: dict[str, Any]
validation: dict[str, Any]
constraints: list[Any]
twins: dict[str, Any]
build: dict[str, Any]
[docs]
class CoverageCount(TypedDict):
"""Declared schema elements, how many the corpus hits, as a percentage."""
declared: int
hit: int
percent: float
[docs]
class CorpusCoverageResult(TypedDict, total=False):
"""Schema-path coverage of the corpus for one message edition."""
error: str
message_type: str
complete: bool
sources: list[Any]
files: list[dict[str, Any]]
paths: CoverageCount
branches: CoverageCount
missing_paths: list[str]
missing_branches: list[str]
exempt: list[str]
unknown: list[str]
[docs]
class StagedBatchResult(TypedDict, total=False):
"""Result of staging a payment batch for simulation and approval."""
error: str
stage_id: str
sha256_fingerprint: str
total_transactions: int
control_sum_by_currency: dict[str, str]
estimated_fees: dict[str, str]
risk_score: int
risk_level: str
risk_factors: list[str]
status: str
confirmation_token: str
expires_at: str
[docs]
class ClearingCheck(TypedDict):
"""An individual rule check during clearing simulation."""
check: str
status: str
detail: str
[docs]
class SimulateClearingResult(TypedDict, total=False):
"""Clearing network simulation verdict and settlement estimation."""
error: str
stage_id: str
clearing_system: str
clearing_status: str
settlement_window: str
checks: list[ClearingCheck]
[docs]
class CommitPaymentBatchResult(TypedDict, total=False):
"""Confirmation of authorized payment batch commit."""
error: str
stage_id: str
status: str
sha256_fingerprint: str
total_transactions: int
output_file_path: str | None
committed_at: str
[docs]
class SchemeProfileEntry(TypedDict):
"""One scheme profile: its name, what it checks, and where from.
``rule_prefix`` begins every rule id a rail profile reports (``UK-FPS``
for ``UK-FPS-AMT``); it is null for the other profiles, whose rule ids
the core does not group under one prefix. ``sources`` are the public
documents a rail or purpose mandate was built from, empty otherwise.
"""
name: str
description: str
rule_prefix: str | None
sources: list[str]
[docs]
class SchemeProfilesResult(TypedDict, total=False):
"""Every scheme profile the core ships, in name order."""
error: str
count: int
profiles: list[SchemeProfileEntry]