Pain001

Generate and validate ISO 20022 payment files from tabular data.

Contents

Getting started

• Install — PyPI, source and Docker
• Requirements — toolchain floor, platforms
• Quick Start — scaffold, validate and generate synthetic payments

The Pain001 ecosystem

• The Pain001 ecosystem — core, MCP, LSP, loaders, plugin scaffold and mockbank

Library reference

• Capabilities at a glance — the current surface by theme
• Ecosystem comparison — short matrix; full table at docs/COMPARISON.md
• Benchmarks — headline numbers; full table at docs/BENCHMARKS.md
• Features — module-level capability list
• Configuration — core options
• Examples — runnable example index

Operational

• When not to use Pain001 — limitations
• Development — make targets, fuzzing, CI
• Security — guarantees and compliance
• Documentation — all reference docs
• Stability guarantees — SemVer axis, output stability, minimum toolchain discipline
• License

Install

As a Python library

python -m pip install pain001

Optional extras include api, parquet, redis, mcp, lsp, gpg, and otel. Version 0.0.71 adds rules (CEL policies) and upload (SFTP). Until that release is published, install these additions from source.

# Development checkout, including unreleased features
git clone --branch feat/v0.0.71 https://github.com/sebastienrousseau/pain001.git
cd pain001
poetry install --all-extras --with dev,docs

# Published container (CLI and REST API)
docker pull ghcr.io/sebastienrousseau/pain001:latest

Docker runs as a non-root user. Mount a writable directory at /data and use -w /data; generate -t pain.001.001.03 -d payments.csv -o output writes into an output directory, not a filename. No distro package or standalone native binary is claimed; see packaging.

Requirements

Python 3.10 or newer; CI tests Python 3.10–3.14 on Linux. Development uses Python 3.12 and Poetry. Optional integrations require their extras and, for GPG, the system GnuPG executable. No distro-system-Python compatibility is claimed. See toolchain policy.

Quick Start

pain001 init pain.001.001.03 -o payments.csv
pain001 validate -t pain.001.001.03 -d payments.csv
pain001 generate -t pain.001.001.03 -d payments.csv -o output

Run in a fresh writable directory. The scaffold uses bundled synthetic data; replace it with your own records before a real payment workflow. Generation validates the rendered XML against the bundled XSD before writing it. A dry run checks data but is not a bank acceptance guarantee.

The Pain001 ecosystem

Core, MCP, LSP, XLSX and MT101 packages follow the coordinated version policy; see suite policy. The new plugin scaffold and mockbank start separately at unreleased 0.0.1. Issue acceptance status distinguishes branch work from released packages. Companion packages are independently installed.

Capabilities at a glance

Ecosystem comparison

This matrix describes the repository's scope, not an independently benchmarked comparison with competitors.

See docs/COMPARISON.md for the evidence and complete matrix.

Benchmarks

CI smoke-runs benchmarks. No hardware-independent throughput or latency promise is made; use the generated run report for measurements.

See docs/BENCHMARKS.md for methodology and full results.

Features

• Generate validated XML to files or in memory through generate_xml_string. Streaming produces one file per chunk with recomputed control totals.
• Discover bundled message types with pain001 versions and inspect metadata with pain001 inspect. Inputs, templates and schemas are described in the user guide and input-column reference.
• Compose scheme profiles, including anti-duplicate; see SCHEMES.md. CEL rules (added in 0.0.71) apply before generation through CLI and REST. Account currency is never inferred from an IBAN.
• Extend loaders, validators, schemes and writers through the plugin contract and XLSX worked example. Plugins run with the process's privileges; they are not sandboxed.
• Use SFTP upload explicitly; generation never sends a payment automatically. Host trust is checked before authentication.
• Request suggest_record_fix via MCP for review-only corrections. IBANs, BICs, amounts and currencies are refused, not guessed; see correction decisions.
• Parse pain.002 status reports and camt.053 statements; build synthetic pain.002 reports. This is not a settlement engine.
• Run REST with pain001 serve, MCP with pain001 mcp, or the CSV language server with pain001-lsp-builtin, after installing the corresponding extras.
• Generate typed clients from openapi.json; see the public API reference.
• Browse the example corpus, JSON twins, and message deltas. Confidence/provenance records describe the evidence for each scenario; they do not certify a bank's acceptance.

Configuration

Use pain001 generate --help, pain001 upload --help, and pain001 plugins --help for the current command options rather than a copied flag list. YAML, TOML and INI configuration and profiles are described in configuration.

PAIN001_API_KEY enables API authentication; configure rate limits and shared job storage before multi-replica deployments. PAIN001_DISABLE_PLUGINS disables named plugins, and OTEL_ENABLED enables optional tracing. See OPERATIONS.md and the deployment cookbook. Never commit keys, credentials or real payment data.

Examples

The numbered examples cover generation, input formats, REST, MCP, streaming, schemes, parsers and corpus access; CI executes them. The Quick Start above is also exercised directly by a documentation regression test.

When not to use Pain001

• XSD validity and scheme checks do not guarantee bank acceptance, regulatory compliance, or settlement. Validate against your bank's authorized rules.
• EBICS, AS2, SWIFT connectivity and real settlement simulation are not provided. Only the explicit SFTP adapter is implemented here.
• camt.053 is a parser, not a statement generator; unrelated ISO families are outside scope. Inputs must be row-shaped records or a supported plugin format.
• Third-party plugins execute arbitrary Python with your process privileges.
• The project has one maintainer; independent plugin-author validation for issue #179 remains outstanding. Development-branch changes are not releases.

Development

poetry install --all-extras --with dev,docs
poetry run make check
poetry run make type
poetry run python scripts/render_readme.py --check
poetry run make docs

The coverage floor is 100% line and branch. make check runs lint, coverage, security and corpus checks; make type is a separate required gate. Pull requests also run mutation testing, benchmarks, SDK and container checks. See DEVELOPMENT.md for the complete gate map and CONTRIBUTING.md for signed commits and DCO.

README layout is generated from the portfolio template vendored at docs/readme-template.md, with evidence in docs/readme-values.json. Edit the values and regenerate with scripts/render_readme.py; CI checks drift. No fixed test count is advertised because it changes with the branch.

Security

Report security problems privately, never in a public issue.

Untrusted inbound XML uses hardened parsing and rendered XML is XSD-validated. The build uses locked dependencies and audited CI installation inputs. Actions are SHA-pinned except the explicitly accepted SLSA generator v2.1.0 references required for upstream provenance verification; see the security audit. Atheris and Hypothesis exercise validation paths; no OSS-Fuzz integration is claimed.

The maintainer-approved solo workflow requires PRs, status checks, conversation resolution and administrator enforcement, but zero mandatory approving reviews and no mandatory CODEOWNER approval. This is not independent review and does not resolve historical review findings. See governance.

Report vulnerabilities according to SECURITY.md.

Documentation

User manual · API reference · Developer guide · Ecosystem map

Also see architecture, support, release process, changelog, issue acceptance and security audit.

Stability guarantees

Versions advance one step at a time on the 0.0.x line, with 0.1.0 after 0.0.999; only the maintainer opens a release. This branch prepares 0.0.71; publication requires approved release PRs and signed release tags.

Generated XML changes for identical input, required fields, CLI/REST/MCP contracts and plugin contracts are breaking changes. They must be announced one release ahead; deprecated interfaces remain for at least one release with a warning. Golden files guard byte-exact output. Coordinated suite releases follow ADR-0001. Toolchain changes follow ADR-0004, not incidental dependency updates.

License

Dual-licensed under Apache-2.0 OR MIT, at your option. See LICENSE. Dependencies retain their own licences.