fincausal 0.1.0

Finance decision intelligence tools for cost-sensitive risk modelling, stress testing, and intervention simulation.

FinCausal

FinCausal is a Python library for finance-focused decision intelligence.

Version 0.1.0 focuses on a narrow but practical MVP:

• cost-sensitive credit/fraud classification
• threshold optimization by expected financial loss
• financial-loss reporting
• simple stress testing
• model-based intervention simulation
• synthetic credit-risk demo data

Why this exists

Standard ML workflows often optimize metrics such as accuracy, AUC, or F1 score. In finance, the real question is often different:

Which decision threshold reduces expected financial loss?

FinCausal helps analysts compare normal model thresholds with cost-aware thresholds using explicit false-positive and false-negative costs.

Installation

Local install from this folder:

pip install -e .

After PyPI publication:

pip install fincausal

Quickstart

from sklearn.model_selection import train_test_split
from fincausal import CostSensitiveClassifier, make_credit_risk_data

X, y = make_credit_risk_data(n_samples=3000, random_state=42)

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, random_state=42, stratify=y
)

model = CostSensitiveClassifier(
    cost_matrix={"FP": 50, "FN": 500}
)

model.fit(X_train, y_train)
model.optimize_threshold(X_test, y_test)

normal_report = model.loss_report(X_test, y_test, threshold=0.50)
optimized_report = model.loss_report(X_test, y_test)

print("Normal threshold cost:", normal_report["total_cost"])
print("Optimized threshold cost:", optimized_report["total_cost"])
print("Money saved:", normal_report["total_cost"] - optimized_report["total_cost"])

Stress testing

stress = model.stress_test(
    X_test,
    shock={
        "income": -0.10,
        "debt_to_income": 0.15,
        "loan_amount": 0.10,
    },
)

print(stress)

Intervention simulation

intervention = model.simulate_intervention(
    X_test,
    changes={
        "loan_amount": -0.15,
        "debt_to_income": -0.10,
    },
)

print(intervention)

Important: intervention simulation is model-based only. It is not proof of causality.

Current limitations

This is an early MVP, not a production banking risk engine.

Current limitations:

• no full causal-graph validation yet
• no DoWhy/EconML integration yet
• no SHAP wrapper yet
• no PDF/HTML model report generator yet
• synthetic dataset is for demonstration only

Roadmap

Planned additions:

1. SHAP-based explainability wrapper
2. PDF/HTML model report generation
3. fraud-risk synthetic dataset
4. causal-estimation wrapper with careful assumptions
5. scenario library for interest-rate, unemployment, and macro shocks
6. documentation site

License

MIT License.