Parallel-Run Reconciliation¶

Run this calculator and your existing calculator on the same portfolio, then reconcile the two outputs component by component — exposure class, CCF, EAD, PD, LGD, risk weight, RWA, and more. Every exposure is bucketed as a match, a within-tolerance difference, a break, or missing on one side, with our engine's reason and input drivers attached so a break can be traced to a data issue or an engine difference.

This is the feature that lets a risk team gain comfort that the new calculator produces the right numbers before they switch.

Why reconcile before you switch¶

Most institutions adopting this calculator already run an incumbent credit-risk engine. The hardest part of a migration is not installing the new system — it is signing off that the new numbers are correct on your own book.

The acceptance suite gives statistical confidence on ~500 hand-derived regulatory scenarios. It cannot give absolute confidence on a real portfolio of millions of exposures with attribute combinations no test enumerates. As the project's own migration note puts it, production deployment requires "a parallel-run discipline against an existing system, signed-off reconciliation thresholds, and a rollback plan."

Parallel-run reconciliation operationalises exactly that discipline:

• Run both engines on the same portfolio for the same reporting date.
• Reconcile the outputs and review the headline tie-out and the break worklist.
• Triage each break: is our input different from theirs (a data-mapping fix), or do the inputs agree but the outputs diverge (an engine difference to investigate)?
• Sign off once breaks are explained and within agreed thresholds.

How it works¶

flowchart LR
    A["Your portfolio<br/>(input data)"] --> B["This calculator<br/>CreditRiskCalc.calculate()"]
    A --> C["Your legacy<br/>calculator"]
    C --> D["Legacy output file<br/>(CSV / Parquet)"]
    B --> E["reconcile()"]
    D -->|"TOML mapping"| E
    E --> F["ReconciliationResponse<br/>(tie-out · buckets · breaks)"]

You supply our results (produced by the calculator) and your legacy output file, plus a small TOML mapping that says which legacy column is which component and how the two are keyed. The engine collapses our guarantee / real-estate sub-rows back to your reporting grain — and aggregates the legacy side the same way, so a legacy exposure split across several lines (a collateralised portion in one risk class, the residual in another) sums to the key grain instead of having all-but-the-first line dropped — joins the two sides, and buckets every mapped component.

What it compares¶

You map only the components you have. Each one is compared with a sensible default tolerance (overridable), and annotated with our engine's explain and input columns.

Buckets¶

Every component on every row lands in one bucket, and the row takes its worst:

Data fix or engine fix?¶

The point of attaching our explain and input columns to every row is to make a break triage-able. For a break on, say, risk_weight:

• If our input drivers (CQS, LTV band, …) differ from what the legacy system used → the break is a data / mapping issue — fix the feed or the mapping.
• If the inputs agree but the risk weight differs → it is an engine difference — raise it for investigation against the regulation.

Reading the report¶

The result is layered from a one-number verdict down to a single exposure's drivers.

How to run it¶

1. Write a mapping (TOML)¶

The mapping declares the legacy file, the join key(s), and which legacy column feeds each component. Numeric components accept scale (e.g. legacy figures in millions) and unit = "percent"; categoricals accept a value_map of label synonyms; any component can override its tolerance.

# reconciliation.toml
legacy_file   = "./legacy_q4.csv"
legacy_format = "csv"              # or "parquet"
legacy_keys   = ["obligor_id", "facility_id"]          # composite key supported
our_keys      = ["counterparty_reference", "root_facility_reference"]
top_n         = 50

[components.rwa]
legacy_column = "RWA_Amt"
scale         = 1_000_000          # legacy RWA is in millions
tol_kind      = "rel"              # optional override
tol           = 0.005              # 0.5% relative

[components.ead]
legacy_column = "EAD_Amt"
scale         = 1_000_000

[components.risk_weight]
legacy_column = "RW_pct"
unit          = "percent"          # 20.0 -> 0.20

[components.exposure_class]
legacy_column = "Asset_Class"
value_map     = { CORP = "corporate", RETAIL = "retail" }

legacy_keys = ["exposure_reference", "Asset_Class"]
our_keys    = ["exposure_reference", "exposure_class"]

2. Run it from Python¶

from datetime import date
from pathlib import Path

from rwa_calc.api import CreditRiskCalc

calc = CreditRiskCalc(
    data_path="/path/to/data",
    framework="CRR",
    reporting_date=date(2026, 12, 31),
    permission_mode="standardised",
)

response = calc.reconcile("reconciliation.toml")

# Headline: do the two engines tie out?
print(response.collect_totals_tie_out())
print(response.collect_summary_by_component())

# Warnings (non-fatal) — e.g. a mapped column the legacy file didn't contain
for err in response.errors:
    print(f"[{err.code}] {err.message}")

# The break worklist, largest first
breaks = response.collect_breaks_detail()
print(f"{breaks.height} break(s) to review")

# Full report to Excel (one sheet per view) or CSV (one file per view)
response.to_excel(Path("reconciliation.xlsx"))
response.to_csv(Path("reconciliation_out/"))

reconcile() accepts either a path to a .toml file (shown above) or a ReconciliationSettings object built in code via api.load_reconciliation_config.

3. Or use the interactive UI¶

The Reconciliation page in the app (served at /reconciliation) gives you the same result without writing Python: enter your data path, edit the TOML mapping in the form, and run. It renders the four drill-down tiers (headline tie-out, per-component summary, the break worklist, and the per-key forensic table with a bucket filter) and offers CSV / Excel downloads of the full per-key detail.

uv add rwa-calc
rwa-ui                 # then open http://localhost:8000/reconciliation

The same flow is available over HTTP for programmatic callers via POST /api/reconcile (with GET /api/reconcile/export/{csv|excel} for the downloads).

Details: See Interactive UI for the full list of pages and how to start the server.

Output reference¶

ReconciliationResponse¶

ReconciliationBundle¶

The underlying engine bundle (available as response.bundle). All frames are pl.LazyFrame; errors is a list.

Tolerances & data-quality warnings¶

Each numeric component has a sensible default tolerance — 1% relative for money amounts (EAD, RWA, expected loss) and a tight absolute tolerance for rates (risk weight, PD, LGD, CCF, supporting factor). Override any of them per component in the mapping with tol_kind ("rel" or "abs") and tol. Categorical components match on the exact label after case-folding and value_map synonyms.

Reconciliation never aborts on a data problem — issues are recorded as non-fatal warnings on response.errors so they are visible rather than silent:

Related¶

• Output Schemas — the per-exposure columns reconciliation reads from.
• Comparison & Impact Analysis — CRR vs Basel 3.1 (a different kind of comparison).
• Interactive UI — the Reconciliation page and the other app surfaces.
• Service API — CreditRiskCalc reference.