Readme.md

---

# **Decision Kernel Lite — Choosing Under Uncertainty**

A minimal, reproducible system for making **defensible decisions under uncertainty**, using three complementary risk lenses:

* **Expected Loss**
* **Minimax Regret**
* **CVaR (Conditional Value at Risk)**

The system collapses scenarios, probabilities, and asymmetric losses into **one deployable decision** with an explicit rationale.

---

## **What Problem This Solves**

Most business decisions fail not because of bad models, but because:

* probabilities are uncertain or disputed
* downside risk is asymmetric
* decisions are justified with intuition instead of structure

Decision Kernel Lite provides a **decision-first abstraction** that makes trade-offs explicit and auditable.

It does **not** predict.
It does **not** optimize operations.
It **chooses actions**.

---

## **Core Concept**

A decision is defined by four primitives:

```text
Actions × Scenarios × Probabilities × Losses
```

From these, the kernel evaluates actions using three lenses:

| Lens           | Optimizes for           |
| -------------- | ----------------------- |
| Expected Loss  | Average pain            |
| Minimax Regret | Hindsight defensibility |
| CVaR           | Tail-risk protection    |

The output is a **Decision Card** — not a dashboard.

---

## **What This Repository Provides**

This repository includes:

* a pure **decision kernel** (no ML, no forecasting)
* three mathematically sound decision rules
* a **Streamlit UI** for rapidž input → decision
* an explicit **rule-selection heuristic**
* a copy/paste **Decision Card** suitable for exec decks or memos

This is not analytics.
It is **decision intelligence**.

---

## **Decision Rules — When to Use What**

### **Expected Loss (Risk-Neutral)**

Use when:

* decisions repeat frequently
* probabilities are reasonably trusted
* variance is acceptable

Optimizes:

* long-run average outcomes

---

### **Minimax Regret (Robust / Political Safety)**

Use when:

* probabilities are unreliable or contested
* decisions are one-shot or high-accountability
* post-hoc defensibility matters

Optimizes:

* “I should not regret this choice”

---

### **CVaR (Tail-Risk Protection)**

Use when:

* rare bad outcomes are unacceptable
* downside is asymmetric (ruin, safety, bankruptcy)
* survival > average performance

Optimizes:

* average loss in the worst cases

---

## **Heuristic Rule Recommendation**

The system includes a simple, transparent heuristic:

* if tail risk dominates average risk → **recommend CVaR**
* otherwise → **recommend Expected Loss**

The recommendation is **advisory only** and can be overridden.

Governance is preserved.

---

## **Repository Structure**

```text
decision_kernel_lite/
├── app.py               → Streamlit application
├── requirements.txt     → minimal dependencies
├── Dockerfile           → containerized deployment
├── README.md            → this file
├── Executive_brief.md   → executive narrative
└── Technical_brief.md   → math + implementation
```

---

## **How to Run**

### Local

```bash
pip install -r requirements.txt
streamlit run app.py
```

### Docker

```bash
docker build -t decision-kernel-lite .
docker run -p 7860:7860 decision-kernel-lite
```

Open: `http://localhost:7860`

---

## **Deployment**

Works on:

* **Hugging Face Spaces (Docker SDK)**
* local Docker
* any environment that supports Streamlit

No external services required.

---

## **What This Is Not**

Decision Kernel Lite deliberately excludes:

* forecasting models
* machine learning
* optimization solvers
* domain-specific logic

Those belong **upstream or downstream**.

This kernel is intentionally **domain-agnostic**.

---

## **Positioning**

Decision Kernel Lite is designed to be:

* embedded downstream of forecasts
* embedded upstream of optimization
* used standalone for high-stakes choices

It is the **decision layer** in a larger Decision Intelligence stack.

---

## **Summary**

This system delivers:

1. a **clear action recommendation**
2. multiple **risk-aware justifications**
3. explicit trade-offs between lenses
4. a governance-ready Decision Card
5. a deployable, minimal interface

> Decisions are not predictions.
> They are commitments under uncertainty.

---