fincausal 0.4.1

Finance decision intelligence tools for cost-sensitive credit and fraud risk modelling.

FinCausal

FinCausal is a finance-focused Python library for decision-risk analysis, cost-sensitive classification, and model-governance workflows in credit risk, fraud detection, AML alerting, and operational risk review.

It helps analysts move from a narrow model-performance question:

“Does this model have good accuracy?”

To a decision-governance question:

“Which decision threshold reduces expected financial loss while respecting customer-impact and operational constraints?”

Version 0.4.1 focus

Version 0.4.1 adds the missing governance modules around the core cost-sensitive classifier:

• constrained threshold optimisation
• calibration checks
• fairness/customer-impact checks
• model monitoring and drift diagnostics
• explanation utilities
• report export to Markdown and HTML
• train/validation/test backtesting helper
• rolling-period backtesting helper
• benchmark CSV loader
• edge-case test coverage
• safe dependency ranges for NumPy/Pandas/scikit-learn

Installation

Recommended clean environment:

conda create -n fincausal-env python=3.11 -y
conda activate fincausal-env
pip install dist/fincausal-0.4.1-py3-none-any.whl

From PyPI after publishing:

pip install fincausal

Quick start

from fincausal import (
    CostMatrix,
    CostSensitiveClassifier,
    make_credit_risk_data,
    train_validation_test_split,
)

X, y = make_credit_risk_data(n_samples=5000, random_state=42)
X_train, X_val, X_test, y_train, y_val, y_test = train_validation_test_split(X, y)

costs = CostMatrix(false_positive=100, false_negative=5000, currency="GBP")
model = CostSensitiveClassifier(cost_matrix=costs)
model.fit(X_train, y_train)

result = model.optimize_threshold(
    X_val,
    y_val,
    max_flagged_rate=0.45,
    min_precision=0.35,
)

print(result["best_threshold"])
print(model.loss_report(X_test, y_test))

Calibration checks

calibration = model.calibration_report(X_test, y_test, n_bins=10)
print(calibration["brier_score"])
print(calibration["expected_calibration_error"])
print(calibration["table"])

Fairness/customer-impact checks

import pandas as pd

segments = pd.qcut(X_test["income"], q=3, labels=["low", "middle", "high"])
fairness = model.fairness_report(X_test, y_test, segments, threshold=model.best_threshold_)
print(fairness)

This is a customer-impact/model-governance check. It is not a legal protected-class fairness certification.

Model monitoring and drift

score_drift = model.score_drift_report(X_train, X_test)
print(score_drift)

Feature PSI:

from fincausal import feature_drift_report

print(feature_drift_report(X_train, X_test))

Explanation utilities

importance = model.feature_importance_report(X_test, y_test, n_repeats=5)
print(importance)

Reports

report = model.decision_report(X_test, y_test)
report.save_markdown("fincausal_report.md")
report.save_html("fincausal_report.html")

Backtesting

from fincausal import threshold_validation_backtest

backtest = threshold_validation_backtest(
    X_train,
    y_train,
    X_val,
    y_val,
    X_test,
    y_test,
    cost_matrix=costs,
    max_flagged_rate=0.45,
    min_precision=0.35,
)

print(backtest["optimized_test_report"])

Benchmark data

Built-in synthetic benchmark:

from fincausal import make_credit_risk_data
X, y = make_credit_risk_data(n_samples=5000, random_state=42)

External CSV loader:

from fincausal import load_credit_risk_csv
X, y = load_credit_risk_csv("credit_data.csv", target_col="default_risk")

Testing

pytest

Current local status:

27 passed

Dependency policy

The package uses safe dependency ranges to avoid forcing unstable major-version upgrades:

numpy>=1.23,<2.0
pandas>=1.5,<3.0
scikit-learn>=1.2,<1.8
scipy>=1.9,<1.16

Limitations

FinCausal is an early-stage alpha library. It is not a production-grade bank model-risk platform and does not replace independent validation, regulatory review, security review, or legal fairness assessment.

All results depend on model quality, sample design, selected business constraints, and supplied cost assumptions.

Roadmap

• public benchmark notebooks
• documentation website
• GitHub Actions CI/CD
• versioned PyPI release workflow
• richer PDF/HTML report templates
• SHAP integration as optional extra
• monitoring dashboard examples

License

MIT License.