Configuration API¶

PolarsEngine = Literal["cpu", "gpu", "streaming"]

@dataclass(frozen=True)
class CalculationConfig:
    """
    Attributes:
        regime_id: Regime identifier ("crr" | "b31") — the regime carrier.
        reporting_date: As-of date for the calculation.
        base_currency: Currency for reporting (default "GBP").
        apply_fx_conversion: Whether to convert exposures to base_currency.
        output_floor: Output floor configuration.
        post_model_adjustments: Post-model adjustments (Basel 3.1 only).
        permission_mode: STANDARDISED (all SA) or IRB (model permissions drive routing).
        use_investment_grade_assessment: Art. 122(6) election — IG=65% / non-IG=135%.
        eur_gbp_rate: EUR/GBP exchange rate for monetary-threshold conversion.
        collect_engine: Polars engine for .collect() — "cpu" (default).
    """

    regime_id: str  # "crr" | "b31" — the regime carrier
    reporting_date: date
    base_currency: str = "GBP"
    apply_fx_conversion: bool = True
    output_floor: OutputFloorConfig = field(default_factory=OutputFloorConfig.crr)
    post_model_adjustments: PostModelAdjustmentConfig = field(
        default_factory=PostModelAdjustmentConfig.crr
    )
    ccr: CCRConfig = field(default_factory=CCRConfig)
    permission_mode: PermissionMode = PermissionMode.STANDARDISED
    irb_permissions: IRBPermissions | None = None
    equity_transitional: EquityTransitionalConfig = field(default_factory=EquityTransitionalConfig)
    eur_gbp_rate: Decimal = Decimal("0.8732")
    enable_double_default: bool = False
    use_investment_grade_assessment: bool = False
    crm_collateral_method: CRMCollateralMethod = CRMCollateralMethod.COMPREHENSIVE
    airb_collateral_method: AIRBCollateralMethod | None = None
    collect_engine: PolarsEngine = "cpu"
    spill_edges: bool = False
    spill_dir: Path | None = None
    log_level: str = "INFO"
    log_format: Literal["text", "json"] = "text"
    audit_cache_dir: Path | None = None
    audit_cache_max_runs: int | None = None

    @property
    def is_crr(self) -> bool:
        """Check if using CRR framework."""

    @property
    def is_basel_3_1(self) -> bool:
        """Check if using Basel 3.1 framework."""

    def get_output_floor_percentage(self) -> Decimal:
        """Get the applicable output floor percentage for the reporting date."""

    @classmethod
    def crr(
        cls,
        reporting_date: date,
        permission_mode: PermissionMode = PermissionMode.STANDARDISED,
        eur_gbp_rate: Decimal = Decimal("0.8732"),
        enable_double_default: bool = False,
        crm_collateral_method: CRMCollateralMethod = CRMCollateralMethod.COMPREHENSIVE,
        collect_engine: PolarsEngine = "cpu",
        spill_dir: Path | None = None,
        log_level: str = "INFO",
        log_format: Literal["text", "json"] = "text",
    ) -> CalculationConfig:
        """
        Create CRR (Basel 3.0) configuration.

        CRR characteristics (these regulatory values resolve from the CRR
        rulepack pack, not from config fields):
        - Single PD floor (0.03%) for all classes
        - No LGD floors for A-IRB
        - SME supporting factor (0.7619/0.85)
        - Infrastructure supporting factor (0.75)
        - No output floor
        - 1.06 scaling factor for IRB K
        - Optional double-default treatment (Art. 153(3), 202)
        """

    @classmethod
    def basel_3_1(
        cls,
        reporting_date: date,
        permission_mode: PermissionMode = PermissionMode.STANDARDISED,
        post_model_adjustments: PostModelAdjustmentConfig | None = None,
        use_investment_grade_assessment: bool = False,
        institution_type: InstitutionType | None = None,
        reporting_basis: ReportingBasis | None = None,
        gcra_amount: float = 0.0,
        sa_t2_credit: float = 0.0,
        art_40_deductions: float = 0.0,
        skip_transitional_floor: bool = False,
        crm_collateral_method: CRMCollateralMethod = CRMCollateralMethod.COMPREHENSIVE,
        airb_collateral_method: AIRBCollateralMethod = AIRBCollateralMethod.LGD_MODELLING,
        collect_engine: PolarsEngine = "cpu",
        spill_dir: Path | None = None,
        log_level: str = "INFO",
        log_format: Literal["text", "json"] = "text",
    ) -> CalculationConfig:
        """
        Create Basel 3.1 (PRA PS1/26) configuration.

        Basel 3.1 characteristics:
        - Differentiated PD floors by exposure class
        - LGD floors for A-IRB by collateral type
        - No supporting factors
        - Output floor (72.5%, transitional from 60% in 2027)
        - 1.06 scaling factor removed
        """

from datetime import date
from decimal import Decimal
from rwa_calc.contracts.config import CalculationConfig
from rwa_calc.domain.enums import CRMCollateralMethod, PermissionMode

# CRR baseline with Art. 153(3) double-default *and* the Art. 222 simple
# financial collateral method on the SA leg, plus a non-default EUR/GBP
# rate for retail / SME threshold conversion.
config = CalculationConfig.crr(
    reporting_date=date(2026, 12, 31),
    permission_mode=PermissionMode.IRB,
    eur_gbp_rate=Decimal("0.8800"),
    enable_double_default=True,                              # Art. 153(3)
    crm_collateral_method=CRMCollateralMethod.SIMPLE,        # Art. 222 (SA-only)
    log_format="json",                                       # audit-ready logs
)

assert config.is_crr
assert config.enable_double_default is True
assert config.crm_collateral_method is CRMCollateralMethod.SIMPLE

from datetime import date
from rwa_calc.contracts.config import CalculationConfig
from rwa_calc.domain.enums import (
    AIRBCollateralMethod,
    CRMCollateralMethod,
    InstitutionType,
    PermissionMode,
    ReportingBasis,
)

# Stand-alone UK IRB firm, individual basis, electing:
# - Art. 122(6)(b)/(8)(b) IG vs non-IG split for unrated corporates
# - Art. 191A Part 2 / Art. 169A election to use the Foundation
#   Collateral Method on the A-IRB book
# - Art. 222 Simple Method on the SA financial collateral book
# - Art. 92 para 5 voluntary skip of the 60/65/70% transitional → 72.5%
#   from day one
config = CalculationConfig.basel_3_1(
    reporting_date=date(2027, 6, 30),
    permission_mode=PermissionMode.IRB,
    use_investment_grade_assessment=True,                          # Art. 122(6)/(8)
    airb_collateral_method=AIRBCollateralMethod.FOUNDATION,        # Art. 169A
    crm_collateral_method=CRMCollateralMethod.SIMPLE,              # Art. 222
    institution_type=InstitutionType.STANDALONE_UK,                # Art. 92 para 2A(a)(i)
    reporting_basis=ReportingBasis.INDIVIDUAL,
    skip_transitional_floor=True,                                  # Art. 92 para 5
)

assert config.is_basel_3_1
assert config.use_investment_grade_assessment is True
assert config.airb_collateral_method is AIRBCollateralMethod.FOUNDATION
assert config.crm_collateral_method is CRMCollateralMethod.SIMPLE
assert config.output_floor.is_floor_applicable() is True
assert config.get_output_floor_percentage() == Decimal("0.725")    # phased-in from day one

from dataclasses import replace
from datetime import date
from decimal import Decimal
from rwa_calc.contracts.config import CalculationConfig

config = CalculationConfig.basel_3_1(reporting_date=date(2027, 6, 30))

# Adjust the EUR/GBP rate used for monetary-threshold conversion without
# disturbing any other framework defaults.
config = replace(config, eur_gbp_rate=Decimal("0.8800"))

assert config.eur_gbp_rate == Decimal("0.8800")

@dataclass(frozen=True)
class OutputFloorConfig:
    enabled: bool = False
    floor_percentage: Decimal = Decimal("0.725")  # 72.5%
    transitional_start_date: date | None = None
    transitional_end_date: date | None = None
    transitional_floor_schedule: dict[date, Decimal] = field(default_factory=dict)

    def get_floor_percentage(self, calculation_date: date) -> Decimal:
        """Get the applicable floor percentage for a given date.

        Returns 0% if floor is disabled or the calculation date precedes
        the transitional start date (PS1/26: 1 Jan 2027 for UK firms).

        Transitional schedule:
        PRA compressed schedule (4-year, not BCBS 6-year):
        - 2027: 60%
        - 2028: 65%
        - 2029: 70%
        - 2030+: 72.5%
        """

    @classmethod
    def crr(cls) -> OutputFloorConfig:
        """CRR: No output floor."""

    @classmethod
    def basel_3_1(cls) -> OutputFloorConfig:
        """Basel 3.1 output floor with PRA transitional schedule."""

class PermissionMode(StrEnum):
    STANDARDISED = "standardised"
    IRB = "irb"

from datetime import date
from rwa_calc.contracts.config import CalculationConfig
from rwa_calc.domain.enums import PermissionMode

config = CalculationConfig.crr(
    reporting_date=date(2026, 12, 31),
    permission_mode=PermissionMode.IRB,
    enable_double_default=True,  # Art. 153(3) double-default treatment
)

assert config.enable_double_default is True

from datetime import date
from rwa_calc.contracts.config import CalculationConfig
from rwa_calc.domain.enums import PermissionMode

config = CalculationConfig.basel_3_1(
    reporting_date=date(2027, 6, 30),
    permission_mode=PermissionMode.IRB,
    use_investment_grade_assessment=True,  # Art. 122(6)/(8) IG=65% / non-IG=135%
)

assert config.use_investment_grade_assessment is True

class CRMCollateralMethod(StrEnum):
    COMPREHENSIVE = "comprehensive"  # FCCM — Art. 223-224 (default)
    SIMPLE = "simple"                # FCSM — Art. 222 (SA-only, 20% RW floor)

from datetime import date
from rwa_calc.contracts.config import CalculationConfig
from rwa_calc.domain.enums import CRMCollateralMethod

config = CalculationConfig.basel_3_1(
    reporting_date=date(2027, 6, 30),
    crm_collateral_method=CRMCollateralMethod.SIMPLE,  # Art. 222 (FCSM)
)

assert config.crm_collateral_method is CRMCollateralMethod.SIMPLE

class AIRBCollateralMethod(StrEnum):
    LGD_MODELLING = "lgd_modelling"  # Art. 169A (default under B31)
    FOUNDATION = "foundation"        # Art. 229-231 (supervisory LGDS/LGDU)

from datetime import date
from rwa_calc.contracts.config import CalculationConfig
from rwa_calc.domain.enums import AIRBCollateralMethod, PermissionMode

config = CalculationConfig.basel_3_1(
    reporting_date=date(2027, 6, 30),
    permission_mode=PermissionMode.IRB,
    airb_collateral_method=AIRBCollateralMethod.FOUNDATION,  # Art. 169A election → Foundation
)

assert config.airb_collateral_method is AIRBCollateralMethod.FOUNDATION

from datetime import date
from decimal import Decimal
from rwa_calc.contracts.config import CalculationConfig
from rwa_calc.domain.enums import PermissionMode

# SA-only CRR configuration (default)
config = CalculationConfig.crr(
    reporting_date=date(2026, 12, 31),
)

# CRR with IRB routing (requires model_permissions input data)
config = CalculationConfig.crr(
    reporting_date=date(2026, 12, 31),
    permission_mode=PermissionMode.IRB,
)

# Access configuration
print(f"Regime: {config.regime_id}")             # "crr"
print(f"Framework: {config.framework}")          # RegulatoryFramework.CRR (derived property)
print(f"Is CRR: {config.is_crr}")                # True (derived property)

# Basel 3.1 with IRB routing (auto-calculates output floor from reporting_date)
config = CalculationConfig.basel_3_1(
    reporting_date=date(2027, 6, 30),
    permission_mode=PermissionMode.IRB,
)

# Check output floor percentage (transitional for 2027 = 60%)
floor = config.get_output_floor_percentage()
print(f"Output floor: {floor:.0%}")  # 60%

# Fully phased-in (2030+)
config = CalculationConfig.basel_3_1(
    reporting_date=date(2030, 1, 1),
    permission_mode=PermissionMode.IRB,
)
floor = config.get_output_floor_percentage()
print(f"Output floor: {floor:.1%}")  # 72.5%

from rwa_calc.rulebook.resolve import resolve

# Resolve the frozen, content-hashed rulepack for this run.
pack = resolve(config.regime_id, config.reporting_date)

# PD/LGD floors, supporting factors and the IRB scaling factor are cited
# entries on the resolved pack (read via the pack's entry accessors), not
# attributes on `config`.

from rwa_calc.domain.enums import PermissionMode

# SA-only — all exposures use standardised approach
config = CalculationConfig.crr(
    reporting_date=date(2026, 12, 31),
    permission_mode=PermissionMode.STANDARDISED,  # default
)

# IRB mode — model_permissions input data drives approach routing
# Each exposure is matched to its model's approved approach (AIRB, FIRB, slotting)
# Exposures without a model permission fall back to SA
config = CalculationConfig.basel_3_1(
    reporting_date=date(2027, 6, 30),
    permission_mode=PermissionMode.IRB,
)