Metadata-Version: 2.4
Name: fincausal
Version: 0.1.0
Summary: Finance decision intelligence tools for cost-sensitive risk modelling, stress testing, and intervention simulation.
Author: Swapnil Bhagat
License: MIT
Keywords: finance,risk,credit-risk,fraud-detection,cost-sensitive-learning,stress-testing,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scikit-learn>=1.2
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 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:

```bash
pip install -e .
```

After PyPI publication:

```bash
pip install fincausal
```

## Quickstart

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

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

print(stress)
```

## Intervention simulation

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