Metadata-Version: 2.4
Name: counterfactual_storyboard
Version: 0.1.0
Summary: Generate and visualize narrative sequences of counterfactual explanations
Author-email: Antigravity <author@example.com>
License: MIT
Project-URL: Homepage, https://github.com/example/counterfactual_storyboard
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: dice-ml>=0.10.1
Requires-Dist: plotly>=5.14.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: scikit-learn>=1.0.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"

# CounterfactualStoryboard

A Python library for generating and visualizing narrative sequences of counterfactual explanations. 

`CounterfactualStoryboard` calculates the **Shortest Path**, **Cheapest Path**, and **Most Actionable Path** to reach a desired outcome, generating plain-language explanations and a beautiful decision storyboard.

## Features
- **Abstract Engine**: Built on `dice-ml`, but extensible to other counterfactual generation algorithms.
- **Narrative Generation**: Uses Jinja2 templates to turn numeric feature changes into human-readable sentences.
- **Dual Visualization**: Outputs interactive HTML/Plotly dashboards or static Matplotlib figures.
- **Model Agnostic**: Works with `scikit-learn`, `TensorFlow`, `PyTorch`, or any custom model via a simple `predict_fn`.

## Installation

```bash
pip install counterfactual_storyboard
```

## Quickstart

```python
import pandas as pd
from sklearn.ensemble import RandomForestClassifier
from counterfactual_storyboard import StoryboardExplainer, FeatureMetadata

# 1. Train your model
df = pd.read_csv("data.csv")
X = df.drop(columns=["target"])
y = df["target"]
model = RandomForestClassifier().fit(X, y)

# 2. Define Feature Metadata (Costs and Mutability)
metadata = FeatureMetadata(
    continuous_features=["age", "balance", "credit_score"],
    actionable_features=["balance"], 
    feature_costs={"age": 100, "balance": 1, "credit_score": 10}
)

# 3. Initialize Explainer
explainer = StoryboardExplainer(
    predict_fn=model.predict_proba,
    training_data=df,
    target_column="target",
    feature_metadata=metadata
)

# 4. Generate Storyboard for an instance
instance = X.iloc[0:1]
storyboard = explainer.generate_storyboard(instance, target_class=1)

# 5. Visualize
storyboard.show()
```
