Metadata-Version: 2.4
Name: fincausal
Version: 0.4.1
Summary: Finance decision intelligence tools for cost-sensitive credit and fraud risk modelling.
Author: Swapnil Bhagat
License-Expression: MIT
Keywords: finance,risk,credit-risk,fraud-detection,cost-sensitive-learning,stress-testing,machine-learning,model-risk,calibration,fairness,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0,>=1.23
Requires-Dist: pandas<3.0,>=1.5
Requires-Dist: scikit-learn<1.8,>=1.2
Requires-Dist: scipy<1.16,>=1.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# 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:

```bash
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:

```bash
pip install fincausal
```

## Quick start

```python
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

```python
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

```python
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

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

Feature PSI:

```python
from fincausal import feature_drift_report

print(feature_drift_report(X_train, X_test))
```

## Explanation utilities

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

## Reports

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

## Backtesting

```python
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:

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

External CSV loader:

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

## Testing

```bash
pytest
```

Current local status:

```text
27 passed
```

## Dependency policy

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

```text
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.
