> ## Documentation Index
> Fetch the complete documentation index at: https://freelance-4888ed08.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Explainability & Trust

> Opening the 'Black Box' of AI decision making with SHAP

Data ScienceBusiness

> [!NOTE]
>
> **What this does:** Explains *why* the model made each prediction — not just the number, but which factors (weather, time, seasonality) drove the forecast, building trust and enabling data-driven decisions.

## Opening the Black Box

Trust is the currency of any AI system. We don't just provide a forecast number (e.g., "500 units"); we explain **why** the model believes that number is correct.

Our transparency engine uses **SHAP (SHapley Additive exPlanations)**, a Nobel-prize winning game theory approach, to "X-Ray" every prediction.

```mermaid theme={null}
graph TD
    %% Styling
    classDef person fill:#4F46E5,stroke:#fff,color:#fff,stroke-width:2px;
    classDef ui fill:#E0E7FF,stroke:#4338ca,color:#1e1b4b,stroke-width:2px;
    classDef orchestrator fill:#FEF3C7,stroke:#b45309,color:#78350f,stroke-width:2px;
    classDef ml fill:#DCFCE7,stroke:#15803d,color:#14532d,stroke-width:2px;

    %% Nodes
    Data[Historical Data]:::ml
    Model[CatBoost Model]:::ml
    
    %% Explainer Sub-System
    subgraph "Transparency Engine"
        direction TB
        Prediction[Forecast: 500 Units]:::ui
        Explainer[SHAP Explainer]:::orchestrator
        Report[Transparency Report]:::person
    end

    %% Flow
    Data --> Model
    Model --> Prediction
    Model --> Explainer
    Explainer --> Report
    
    %% Link Styling
    linkStyle default stroke:#6366f1,stroke-width:2px;
```

## 1. Global Drivers (The "Big Picture")

First, we ask: **"Overall, what levers move the needle the most?"**

This helps business planners understand the strategic rules the model has learned. We visualize this with a **Beeswarm Plot**.

**How to read the Beeswarm Plot**

* **Y-Axis (Rank)**: Features at the top are the most important.
* **Color**: **Red** = High value (e.g., High Price), **Blue** = Low value (e.g., Low Price).
* **X-Axis (Impact)**: How much it creates (+/-) demand.

> *Example*: If "Price" is at the top, and the Red dots are on the left (negative side), it means **Higher Prices strongly reduce Demand**.

> [!TIP]
>
> **Business Translation**:
>
> * **Feature Importance** → **"Strategic Levers"**
> * **SHAP Value** → **"Impact Score"** (in units sold)

## 2. Local X-Ray (The "Detective")

Next, we drill down to a specific prediction: **"Why did we predict 950 units for Store A next Tuesday?"**

We use a **Waterfall Plot** to tell the story of that specific day. It starts at the baseline (average) and adds/subtracts impact based on active conditions.

### The Decision Path

1. **Baseline**: The average demand is **500 units**.
2. **Pass 1 (Promotion)**: A promo is active. **+200 units**.
3. **Pass 2 (Seasonality)**: It is December. **+300 units**.
4. **Pass 3 (Price)**: Price was raised slightly. **-50 units**.
5. **Final Forecast**: **950 units**.

```python Local Interpretation Example theme={null}
from demand_forecasting.explainability.shap_explainer import ModelExplainer

# Explain a specific prediction (e.g., sample #0)
explanation = explainer.explain_prediction(sample_idx=0)

print(f"Prediction: {explanation['prediction']}")
print(f"Top Booster: {explanation['top_positive_contributors'][0]}") # e.g. ('is_holiday', +50.2)
print(f"Top Drag: {explanation['top_negative_contributors'][0]}")    # e.g. ('price', -10.5)
```

## Interactive Transparency

The static reports are just the beginning. Business planners can use the **Dash UI** to run real-time "What-If" scenarios.

> [card] [Scenario Planner](https://freelance-4888ed08.mintlify.site/ui/dashboard-overview.md)
>
> Adjust price or promo status and see how the SHAP values change instantly.

> [card] [Drift Monitoring](https://freelance-4888ed08.mintlify.site/ml-solution/data-quality-and-drift.md)
>
> Alerts when the model starts relying on features differently than before.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.