Architecture Overview¶

Risk Bridge maintains a strict architectural separation between a pure, typed statistical core and impure orchestration boundaries.

Architectural Principles¶

Pure Mathematical Core: Likelihood evaluations, analytic gradients, constraint Jacobians, and calibration calculations are implemented as side-effect-free functions operating on NumPy arrays.
Impure Orchestration Edges: File system I/O, process-level concurrency, random number generator seeding, and directory management are pushed to the outer boundary of the application (risk_bridge.runs, risk_bridge.cli).
Explicit Functional Error Handling: The pipeline leverages comp-builders Result monads for fail-fast validation, avoiding hidden exceptions in multi-step workflows.
Data Contract Invariance: Tabular data transitions through canonical column representations (caseY, X..., zOrigin, zCat), isolating estimation mathematics from raw column names.

Module	Core Responsibility
`risk_bridge.config`	Immutable configuration dataclasses (`RunConfig`, `UserDataRunConfig`, etc.)
`risk_bridge.preprocess`	User dataset validation, column mapping, and canonical transformation
`risk_bridge.sampling`	Propensity score matching (PSM) and random sampling
`risk_bridge.calibration`	Discrete support enumeration and reference calibration strata
`risk_bridge.likelihood`	Joint negative log-likelihood \(\ell(\theta)\) and analytic gradients \(\nabla \ell\)
`risk_bridge.constraints`	Constraint functions \(g_k(\theta)\) and analytic Jacobians \(J(\theta)\)
`risk_bridge.optimize`	Unconstrained BFGS and constrained solver ladder (`trust-constr`, SLSQP)
`risk_bridge.metrics`	ROC/AUC, threshold accuracy, CITL, slope, O/E, and Brier score
`risk_bridge.output_schema`	Centralized constants defining the versioned CSV output contract
`risk_bridge.runs`	Orchestration loops for simulated and user-data workflows
`risk_bridge.reproducibility`	Environment capture and reproducibility contract serialization