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.

collateral, guarantee and cqs are additive/exact CRM drivers — map a legacy column for each to compare collateral allocation, guarantee benefit and credit-quality step side-by-side. A component you do not map simply shows our side only in the single-loan forensic.

[components.approach]
legacy_column = "Method"
value_map = { STD = "standardised", "IRB-F" = "foundation_irb", "IRB-A" = "advanced_irb" }

Buckets¶

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

Focusing on material differences¶

Our engine emits legitimate our-only lines that carry zero exposure — a fully-provisioned exposure, a zero-undrawn facility row, a guarantee-remainder sub-row. Each is a correct missing_right, but with zero gross exposure it adds nothing to any money total while inflating the bucket counts, burying the real omissions. The overview and the per-key explorer therefore offer an opt-in "Hide zero-gross-exposure rows" toggle (off by default). A row is immaterial when its gross exposure — max(|our EAD|, |legacy EAD|), falling back to RWA when EAD is unmapped — rounds to zero. Toggling it on re-derives every breakdown count (per bucket, per component, per class / approach) and the biggest-breaks worklist with those rows removed; the money tie-out and Σ|Δ| charts are unchanged (a zero-gross row contributes nothing). The wide per-key frame carries gross_exposure and is_immaterial, so the same filter is available in the explorer and the CSV / Excel export.

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.

reconcile() embeds a full calculate() for our side. If you already hold a completed run for the same parameters and data, pass it as calculation= and the pipeline is not re-run — the reconciliation starts from that run's cached results:

prior = calc.calculate()
# ... later, same data on disk ...
response = calc.reconcile("reconciliation.toml", calculation=prior)

The seam trusts what it is given — verify freshness yourself, or go through rwa_calc.api.run_index (which fingerprints parameters plus the input files' size/mtime signature) the way the UI does.

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. The run executes on a background worker and shows a live, stage-by-stage progress stepper (the same one the calculator page uses) so a large parallel run no longer looks like a frozen tab; when it finishes the page opens the report automatically. The report is an aggregates-first overview — headline tie-out, per-component summary, the segment tables and a ranked "biggest breaks" top-N — that never materialises the full diff, so it stays fast for portfolios of any size. From there you drill down: each segment row opens the per-key explorer (filter by bucket / class / approach / worst-component / key, sort any column, and page through the full row-level diff), and each key opens its single-loan forensic (every component's legacy-vs-ours plus the explain / input drivers). A "Hide zero-gross-exposure rows" toggle on the overview and the explorer drops immaterial our-only / legacy-only lines from the breakdown counts (see Focusing on material differences). CSV / Excel downloads of the full per-key detail remain available.

If the identical calculation already ran — from the calculator page, either half of a comparison run, or a previous reconciliation's own embedded run (same data path, framework, reporting date, permission mode, data format — and no input file changed since) — the form offers a pre-ticked reuse checkbox so the engine run is skipped and the reconciliation starts from that run's cached results. Freshness is re-verified at submit time against the input files' size/mtime signature; any change falls back silently to a full recompute. The reuse pool persists under ~/.rwa_calc/ (or $RWA_STATE_DIR), so it survives an app restart.

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). Pass the run_id returned by POST /api/calculate to reconcile that registered run without re-running the pipeline — an explicit run_id is strict: unknown ids 404 and a mismatched framework/date, failed run or expired results 422 rather than silently recomputing.

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.