creditriskengine 0.2.0__py3-none-any.whl

creditriskengine/__init__.py

@@ -0,0 +1,42 @@
+"""
+CreditRiskEngine — Production-grade credit risk analytics.
+
+Modules:
+    core: Data models and type definitions
+    rwa: Risk-weighted asset calculation (SA and IRB)
+    ecl: Expected credit loss engines (IFRS 9, CECL)
+    models: PD, LGD, EAD modeling pipelines
+    validation: Model validation toolkit
+    portfolio: Portfolio credit risk models
+    reporting: Regulatory reporting
+"""
+
+__version__ = "0.2.0"
+
+# Public API — convenient top-level imports
+from creditriskengine.core.exposure import Collateral, Exposure
+from creditriskengine.core.portfolio import Portfolio
+from creditriskengine.core.types import (
+    CollateralType,
+    CreditQualityStep,
+    CreditRiskApproach,
+    IFRS9Stage,
+    IRBAssetClass,
+    IRBRetailSubClass,
+    Jurisdiction,
+    SAExposureClass,
+)
+
+__all__ = [
+    "Collateral",
+    "CollateralType",
+    "CreditQualityStep",
+    "CreditRiskApproach",
+    "Exposure",
+    "IFRS9Stage",
+    "IRBAssetClass",
+    "IRBRetailSubClass",
+    "Jurisdiction",
+    "Portfolio",
+    "SAExposureClass",
+]

creditriskengine/core/__init__.py

@@ -0,0 +1,46 @@
+"""Core types, data models, and configuration for creditriskengine.
+
+Provides regulatory type enumerations, exposure/portfolio data models,
+configuration loading, and the exception hierarchy.
+"""
+
+from creditriskengine.core.exceptions import (
+    CalculationError,
+    ConfigurationError,
+    CreditRiskEngineError,
+    DataError,
+    RegulatoryError,
+    ValidationError,
+)
+from creditriskengine.core.exposure import Collateral, Exposure
+from creditriskengine.core.portfolio import Portfolio
+from creditriskengine.core.types import (
+    CollateralType,
+    CreditQualityStep,
+    CreditRiskApproach,
+    IFRS9Stage,
+    IRBAssetClass,
+    IRBRetailSubClass,
+    Jurisdiction,
+    SAExposureClass,
+)
+
+__all__ = [
+    "CreditRiskEngineError",
+    "ConfigurationError",
+    "ValidationError",
+    "RegulatoryError",
+    "CalculationError",
+    "DataError",
+    "Jurisdiction",
+    "CreditRiskApproach",
+    "IRBAssetClass",
+    "IRBRetailSubClass",
+    "SAExposureClass",
+    "CreditQualityStep",
+    "IFRS9Stage",
+    "CollateralType",
+    "Exposure",
+    "Collateral",
+    "Portfolio",
+]

creditriskengine/core/audit.py

@@ -0,0 +1,191 @@
+"""Audit trail and lineage tracking for capital calculations.
+
+Provides immutable calculation records and an audit trail for governance
+and regulatory compliance.  Every RWA or ECL calculation can be recorded
+with its full input/output context so that supervisory reviews, model
+validation teams, and internal audit can trace any number back to its
+regulatory basis.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+import pandas as pd
+
+import creditriskengine
+
+
+@dataclass(frozen=True)
+class CalculationRecord:
+    """Immutable record of a single capital calculation."""
+
+    exposure_id: str
+    timestamp: datetime
+    approach: str
+    jurisdiction: str
+    inputs: dict[str, Any]
+    outputs: dict[str, Any]
+    regulatory_reference: str
+    engine_version: str
+    warnings: list[str] = field(default_factory=list)
+
+
+class AuditTrail:
+    """Stores and queries :class:`CalculationRecord` entries.
+
+    Parameters
+    ----------
+    records : list[CalculationRecord] | None
+        Optional pre-existing records to initialise the trail with.
+    """
+
+    def __init__(self, records: list[CalculationRecord] | None = None) -> None:
+        self._records: list[CalculationRecord] = list(records) if records else []
+
+    # -- mutators -------------------------------------------------------------
+
+    def record(
+        self,
+        exposure_id: str,
+        approach: str,
+        jurisdiction: str,
+        inputs: dict[str, Any],
+        outputs: dict[str, Any],
+        regulatory_reference: str,
+        warnings: list[str] | None = None,
+    ) -> CalculationRecord:
+        """Create and store a new :class:`CalculationRecord`.
+
+        ``engine_version`` and ``timestamp`` are captured automatically.
+
+        Returns
+        -------
+        CalculationRecord
+            The newly created record.
+        """
+        rec = CalculationRecord(
+            exposure_id=exposure_id,
+            timestamp=datetime.now(UTC),
+            approach=approach,
+            jurisdiction=jurisdiction,
+            inputs=dict(inputs),
+            outputs=dict(outputs),
+            regulatory_reference=regulatory_reference,
+            engine_version=creditriskengine.__version__,
+            warnings=list(warnings) if warnings else [],
+        )
+        self._records.append(rec)
+        return rec
+
+    # -- queries --------------------------------------------------------------
+
+    @property
+    def records(self) -> list[CalculationRecord]:
+        """Return a shallow copy of the internal record list."""
+        return list(self._records)
+
+    def get_records(
+        self,
+        exposure_id: str | None = None,
+        approach: str | None = None,
+    ) -> list[CalculationRecord]:
+        """Return records matching the given filters.
+
+        Parameters
+        ----------
+        exposure_id : str | None
+            If provided, only records for this exposure are returned.
+        approach : str | None
+            If provided, only records using this approach are returned.
+        """
+        result = self._records
+        if exposure_id is not None:
+            result = [r for r in result if r.exposure_id == exposure_id]
+        if approach is not None:
+            result = [r for r in result if r.approach == approach]
+        return result
+
+    # -- export / reporting ---------------------------------------------------
+
+    def to_dataframe(self) -> pd.DataFrame:
+        """Convert the audit trail to a :class:`pandas.DataFrame`."""
+        if not self._records:
+            return pd.DataFrame(
+                columns=[
+                    "exposure_id",
+                    "timestamp",
+                    "approach",
+                    "jurisdiction",
+                    "inputs",
+                    "outputs",
+                    "regulatory_reference",
+                    "engine_version",
+                    "warnings",
+                ],
+            )
+        rows = []
+        for r in self._records:
+            rows.append(
+                {
+                    "exposure_id": r.exposure_id,
+                    "timestamp": r.timestamp,
+                    "approach": r.approach,
+                    "jurisdiction": r.jurisdiction,
+                    "inputs": r.inputs,
+                    "outputs": r.outputs,
+                    "regulatory_reference": r.regulatory_reference,
+                    "engine_version": r.engine_version,
+                    "warnings": r.warnings,
+                }
+            )
+        return pd.DataFrame(rows)
+
+    def export_json(self, filepath: str) -> None:
+        """Write the audit trail to a JSON file.
+
+        Parameters
+        ----------
+        filepath : str
+            Destination path (will be overwritten if it exists).
+        """
+
+        data = []
+        for r in self._records:
+            data.append(
+                {
+                    "exposure_id": r.exposure_id,
+                    "timestamp": r.timestamp.isoformat(),
+                    "approach": r.approach,
+                    "jurisdiction": r.jurisdiction,
+                    "inputs": r.inputs,
+                    "outputs": r.outputs,
+                    "regulatory_reference": r.regulatory_reference,
+                    "engine_version": r.engine_version,
+                    "warnings": r.warnings,
+                }
+            )
+        with open(filepath, "w") as fh:
+            json.dump(data, fh, indent=2)
+
+    def summary(self) -> dict[str, dict[str, int]]:
+        """Aggregate statistics for the audit trail.
+
+        Returns
+        -------
+        dict
+            ``{"by_approach": {<approach>: <count>}, "by_jurisdiction": {<jurisdiction>: <count>}}``
+        """
+        by_approach: Counter[str] = Counter()
+        by_jurisdiction: Counter[str] = Counter()
+        for r in self._records:
+            by_approach[r.approach] += 1
+            by_jurisdiction[r.jurisdiction] += 1
+        return {
+            "by_approach": dict(by_approach),
+            "by_jurisdiction": dict(by_jurisdiction),
+        }

creditriskengine/core/config.py

@@ -0,0 +1,31 @@
+"""Configuration loader for creditriskengine.
+
+This module delegates to ``creditriskengine.regulatory.loader`` which is
+the canonical implementation.  It is kept for backward-compatibility so
+that ``from creditriskengine.core.config import load_jurisdiction_config``
+continues to work.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from creditriskengine.core.types import Jurisdiction
+from creditriskengine.regulatory.loader import load_config
+
+
+def load_jurisdiction_config(
+    jurisdiction: Jurisdiction,
+    config_dir: Path | None = None,
+) -> dict[str, Any]:
+    """Load regulatory configuration YAML for a jurisdiction.
+
+    Delegates to :func:`creditriskengine.regulatory.loader.load_config`.
+
+    Args:
+        jurisdiction: Target jurisdiction.
+        config_dir: Override path to regulatory config directory.
+
+    Returns:
+        Parsed YAML configuration dict.
+    """
+    return load_config(jurisdiction, config_dir=config_dir)

creditriskengine/core/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exception hierarchy for creditriskengine."""
+
+
+class CreditRiskEngineError(Exception):
+    """Base exception for all creditriskengine errors."""
+
+
+class ConfigurationError(CreditRiskEngineError):
+    """Raised when configuration is invalid or missing."""
+
+
+class JurisdictionError(CreditRiskEngineError):
+    """Raised when jurisdiction-specific config is not found."""
+
+
+class ValidationError(CreditRiskEngineError):
+    """Raised when input validation fails."""
+
+
+class RegulatoryError(CreditRiskEngineError):
+    """Raised when regulatory constraints are violated."""
+
+
+class CalculationError(CreditRiskEngineError):
+    """Raised when a calculation fails or produces invalid results."""
+
+
+class DataError(CreditRiskEngineError):
+    """Raised when input data is malformed or insufficient."""

creditriskengine/core/exposure.py

@@ -0,0 +1,117 @@
+"""
+Exposure and facility data models.
+
+Data models represent the minimum set of attributes required for
+regulatory capital calculation under both SA and IRB approaches.
+"""
+
+from datetime import date
+
+from pydantic import BaseModel, Field, field_validator
+
+from creditriskengine.core.types import (
+    CollateralType,
+    CreditQualityStep,
+    CreditRiskApproach,
+    IFRS9Stage,
+    IRBAssetClass,
+    IRBCorporateSubClass,
+    IRBRetailSubClass,
+    Jurisdiction,
+    SAExposureClass,
+)
+
+
+class Collateral(BaseModel):
+    """Collateral pledged against an exposure."""
+    collateral_type: CollateralType
+    value: float = Field(ge=0, description="Current market/appraised value")
+    currency: str = Field(default="USD", max_length=3)
+    haircut: float | None = Field(
+        default=None, ge=0, le=1, description="Supervisory or own-estimate haircut"
+    )
+    ltv: float | None = Field(default=None, ge=0, description="Loan-to-value ratio at origination")
+
+
+class Exposure(BaseModel):
+    """
+    Single credit exposure / facility for capital calculation.
+
+    Contains all fields needed for SA, F-IRB, and A-IRB RWA
+    computation, IFRS 9/CECL ECL calculation, and model validation.
+    """
+    # ---- Identifiers ----
+    exposure_id: str
+    counterparty_id: str
+
+    # ---- Amounts ----
+    ead: float = Field(ge=0, description="Exposure at Default amount")
+    drawn_amount: float = Field(ge=0, description="Current drawn/outstanding balance")
+    undrawn_commitment: float = Field(default=0, ge=0, description="Undrawn committed amount")
+
+    # ---- Classification ----
+    jurisdiction: Jurisdiction
+    approach: CreditRiskApproach
+    sa_exposure_class: SAExposureClass | None = None
+    irb_asset_class: IRBAssetClass | None = None
+    irb_corporate_subclass: IRBCorporateSubClass | None = None
+    irb_retail_subclass: IRBRetailSubClass | None = None
+
+    # ---- SA Parameters ----
+    credit_quality_step: CreditQualityStep | None = None
+    is_investment_grade: bool | None = None
+
+    # ---- IRB Parameters ----
+    pd: float | None = Field(default=None, ge=0, le=1, description="Probability of Default")
+    lgd: float | None = Field(default=None, ge=0, le=1, description="Loss Given Default")
+    ead_model: float | None = Field(default=None, ge=0, description="EAD from internal model")
+    maturity_years: float | None = Field(
+        default=None, ge=0, le=30, description="Effective residual maturity M in years"
+    )
+    turnover_eur_millions: float | None = Field(
+        default=None, ge=0, description="Annual turnover for SME firm-size adjustment"
+    )
+
+    # ---- Collateral and CRM ----
+    collaterals: list[Collateral] = Field(default_factory=list)
+    is_guaranteed: bool = False
+    guarantor_risk_weight: float | None = None
+
+    # ---- Real Estate ----
+    property_value: float | None = Field(default=None, ge=0)
+    ltv_ratio: float | None = Field(default=None, ge=0)
+    is_income_producing: bool = False
+    is_materially_dependent_on_cashflows: bool = False
+
+    # ---- IFRS 9 / ECL ----
+    ifrs9_stage: IFRS9Stage | None = None
+    days_past_due: int = Field(default=0, ge=0)
+    origination_date: date | None = None
+    maturity_date: date | None = None
+    origination_pd: float | None = Field(
+        default=None, ge=0, le=1, description="12-month PD at origination"
+    )
+    current_pd: float | None = Field(default=None, ge=0, le=1, description="Current 12-month PD")
+    is_credit_impaired: bool = False
+    effective_interest_rate: float | None = Field(
+        default=None, ge=0, description="EIR for ECL discounting"
+    )
+
+    # ---- Flags ----
+    is_defaulted: bool = False
+    is_in_default_workout: bool = False
+    currency: str = Field(default="USD", max_length=3)
+
+    @field_validator("pd")
+    @classmethod
+    def pd_floor_check(cls, v: float | None) -> float | None:
+        """Validate PD is between 0 and 1 (inclusive).
+
+        Note: The Basel III PD floor of 0.03% (CRE32.13) is enforced at the
+        IRB calculation level (``rwa.irb.formulas``), not at the data model
+        level, because SA and ECL workflows accept PDs below the IRB floor.
+        """
+        if v is not None and not 0 <= v <= 1:
+            msg = f"PD must be between 0 and 1, got {v}"
+            raise ValueError(msg)
+        return v

creditriskengine/core/logging_config.py

@@ -0,0 +1,88 @@
+"""
+Structured logging configuration for CreditRiskEngine.
+
+Provides sensible defaults for production and development use.
+Supports JSON structured logging for log aggregation systems
+(ELK, Splunk, CloudWatch, etc.).
+
+Usage:
+    from creditriskengine.core.logging_config import configure_logging
+    configure_logging()  # Development defaults
+    configure_logging(level="WARNING", json_format=True)  # Production
+"""
+
+import json
+import logging
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+
+class JSONFormatter(logging.Formatter):
+    """Structured JSON log formatter for production environments.
+
+    Produces one JSON object per log line, suitable for ingestion by
+    log aggregation tools (ELK stack, Splunk, AWS CloudWatch, etc.).
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_entry: dict[str, Any] = {
+            "timestamp": datetime.fromtimestamp(
+                record.created, tz=UTC
+            ).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+        if record.exc_info and record.exc_info[1]:
+            log_entry["exception"] = self.formatException(record.exc_info)
+        # Include any extra fields attached to the record
+        for key in ("exposure_id", "jurisdiction", "approach", "calculation_id"):
+            val = getattr(record, key, None)
+            if val is not None:
+                log_entry[key] = val
+        return json.dumps(log_entry, default=str)
+
+
+def configure_logging(
+    level: str = "INFO",
+    json_format: bool = False,
+    log_file: str | None = None,
+) -> None:
+    """Configure logging for CreditRiskEngine.
+
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        json_format: If True, use JSON structured format (recommended for production).
+        log_file: Optional file path for log output. If None, logs to stderr.
+
+    Example:
+        >>> from creditriskengine.core.logging_config import configure_logging
+        >>> configure_logging(level="DEBUG")  # Development
+        >>> configure_logging(level="WARNING", json_format=True)  # Production
+        >>> configure_logging(level="INFO", log_file="/var/log/cre.log")
+    """
+    root_logger = logging.getLogger("creditriskengine")
+    root_logger.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    # Remove existing handlers to avoid duplicates
+    root_logger.handlers.clear()
+
+    if json_format:
+        formatter = JSONFormatter()
+    else:
+        formatter = logging.Formatter(
+            fmt="%(asctime)s [%(levelname)-8s] %(name)s: %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+
+    if log_file:
+        handler: logging.Handler = logging.FileHandler(log_file, encoding="utf-8")
+    else:
+        handler = logging.StreamHandler(sys.stderr)
+
+    handler.setFormatter(formatter)
+    root_logger.addHandler(handler)

creditriskengine/core/portfolio.py

@@ -0,0 +1,48 @@
+"""Portfolio container for credit exposures."""
+
+from collections.abc import Iterator
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from creditriskengine.core.exposure import Exposure
+from creditriskengine.core.types import CreditRiskApproach, Jurisdiction
+
+
+class Portfolio(BaseModel):
+    """Container for a portfolio of credit exposures.
+
+    Provides iteration, filtering, and aggregation over exposures.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str = "Unnamed Portfolio"
+    jurisdiction: Jurisdiction | None = None
+    approach: CreditRiskApproach | None = None
+    exposures: list[Exposure] = Field(default_factory=list)
+
+    def add_exposure(self, exposure: Exposure) -> None:
+        """Add an exposure to the portfolio."""
+        self.exposures.append(exposure)
+
+    def total_ead(self) -> float:
+        """Total Exposure at Default across all exposures."""
+        return sum(e.ead for e in self.exposures)
+
+    def __len__(self) -> int:
+        return len(self.exposures)
+
+    def __iter__(self) -> Iterator[Exposure]:  # type: ignore[override]
+        return iter(self.exposures)
+
+    def filter_by_approach(self, approach: CreditRiskApproach) -> list[Exposure]:
+        """Return exposures using a specific calculation approach."""
+        return [e for e in self.exposures if e.approach == approach]
+
+    def filter_defaulted(self) -> list[Exposure]:
+        """Return defaulted exposures."""
+        return [e for e in self.exposures if e.is_defaulted]
+
+    def filter_non_defaulted(self) -> list[Exposure]:
+        """Return non-defaulted exposures."""
+        return [e for e in self.exposures if not e.is_defaulted]