Initial commit

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+Decision_Kernel_Lite__Choosing_Under_Uncertainty.pptx filter=lfs diff=lfs merge=lfs -text

Decision_Kernel_Lite__Choosing_Under_Uncertainty.pptx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e599b2e2b6d56ffdd6f8ce62834a497ac10c870cc9efa4f8df07d593ebb39f03
+size 2503143

Dockerfile

@@ -0,0 +1,31 @@
+# ---- Base image ----
+FROM python:3.11-slim
+
+# ---- Environment ----
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# ---- System deps (minimal) ----
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# ---- Workdir ----
+WORKDIR /app
+
+# ---- Install Python deps ----
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# ---- Copy app ----
+COPY . .
+
+# ---- Expose Streamlit port ----
+EXPOSE 7860
+
+# ---- Streamlit config ----
+ENV STREAMLIT_SERVER_PORT=7860
+ENV STREAMLIT_SERVER_ADDRESS=0.0.0.0
+
+# ---- Run ----
+CMD ["streamlit", "run", "app.py"]

Readme.md

@@ -0,0 +1,210 @@
+
+---
+
+# **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.
+
+---

app.py

@@ -0,0 +1,287 @@
+import numpy as np
+import pandas as pd
+import streamlit as st
+
+
+# -----------------------
+# Core math
+# -----------------------
+def normalize_probs(p: np.ndarray) -> np.ndarray:
+    p = np.asarray(p, dtype=float)
+    p = np.clip(p, 0.0, None)
+    s = float(p.sum())
+    if s <= 0:
+        return np.ones_like(p) / len(p)
+    return p / s
+
+
+def expected_loss(loss: np.ndarray, p: np.ndarray) -> np.ndarray:
+    # loss: (A, S), p: (S,)
+    return loss @ p
+
+
+def regret_matrix(loss: np.ndarray) -> np.ndarray:
+    # regret[a,s] = loss[a,s] - min_a loss[a,s]
+    return loss - loss.min(axis=0, keepdims=True)
+
+
+def max_regret(regret: np.ndarray) -> np.ndarray:
+    return regret.max(axis=1)
+
+
+def cvar_discrete(losses: np.ndarray, probs: np.ndarray, alpha: float = 0.8) -> float:
+    """
+    CVaRα for discrete outcomes:
+    - Sort by loss ascending
+    - Find tail mass beyond alpha (i.e., worst 1-alpha probability)
+    - Return probability-weighted average loss over the tail
+    """
+    alpha = float(alpha)
+    alpha = min(max(alpha, 0.0), 1.0)
+
+    order = np.argsort(losses)
+    l = np.asarray(losses, dtype=float)[order]
+    p = np.asarray(probs, dtype=float)[order]
+
+    p = normalize_probs(p)
+    cum = np.cumsum(p)
+
+    # tail = outcomes with cum_prob >= alpha
+    tail = cum >= alpha
+    if not np.any(tail):
+        # alpha==1 with numerical edge cases; take worst outcome
+        tail[-1] = True
+
+    tail_p = p[tail].sum()
+    if tail_p <= 0:
+        return float(l[-1])
+
+    return float((l[tail] * p[tail]).sum() / tail_p)
+
+
+def cvar_per_action(loss: np.ndarray, p: np.ndarray, alpha: float) -> np.ndarray:
+    return np.array([cvar_discrete(loss[i, :], p, alpha=alpha) for i in range(loss.shape[0])], dtype=float)
+
+
+# -----------------------
+# UI
+# -----------------------
+st.set_page_config(page_title="Decision Kernel Lite", layout="wide")
+st.markdown(
+    """
+    <style>
+        section[data-testid="stSidebar"] {
+            width: 420px !important;
+        }
+        section[data-testid="stSidebar"] > div {
+            width: 420px !important;
+        }
+    </style>
+    """,
+    unsafe_allow_html=True,
+)
+
+st.title("Decision Kernel Lite")
+st.caption("One output: choose an action under uncertainty. Three lenses: Expected Loss, Regret, CVaR.")
+
+# Defaults
+default_actions = ["A1", "A2", "A3"]
+default_scenarios = ["Low", "Medium", "High"]
+default_probs = [0.3, 0.4, 0.3]
+default_loss = np.array([[10, 5, 1], [6, 4, 6], [2, 6, 12]])
+
+st.sidebar.header("Controls")
+alpha = st.sidebar.slider("CVaR alpha (tail threshold)", 0.50, 0.99, 0.80, 0.01)
+tie_policy = st.sidebar.selectbox("Tie policy", ["First", "Show all"], index=1)
+
+st.sidebar.header("Decision rule")
+primary_rule = st.sidebar.radio("Choose action by", ["Expected Loss", "Minimax Regret", "CVaR"], index=0)
+
+# Editable inputs
+left, right = st.columns([1.2, 1])
+
+with left:
+    st.subheader("1) Define scenarios + probabilities")
+    scen_df = pd.DataFrame({"Scenario": default_scenarios, "Probability": default_probs})
+    scen_df = st.data_editor(scen_df, num_rows="dynamic", use_container_width=True)
+
+    # clean scenarios/probs
+    scen_df = scen_df.dropna(subset=["Scenario"]).copy()
+    scen_df["Scenario"] = scen_df["Scenario"].astype(str).str.strip()
+    scen_df = scen_df[scen_df["Scenario"] != ""]
+    if scen_df.empty:
+        st.error("Add at least one scenario.")
+        st.stop()
+
+    scenarios = scen_df["Scenario"].tolist()
+    probs_raw = scen_df["Probability"].fillna(0.0).astype(float).to_numpy()
+    probs = normalize_probs(probs_raw)
+
+    if not np.isclose(probs_raw.sum(), 1.0):
+        st.info(f"Probabilities normalized to sum to 1.0 (raw sum was {probs_raw.sum():.3f}).")
+
+with right:
+    st.subheader("2) Define actions + losses")
+    # loss table editor
+    loss_df = pd.DataFrame(default_loss, index=default_actions, columns=default_scenarios)
+
+    # If user changed scenarios count, reindex to match
+    # Start from current editor state if available by reconstructing using scenarios
+    loss_df = loss_df.reindex(columns=scenarios)
+    for c in scenarios:
+        if c not in loss_df.columns:
+            loss_df[c] = 0.0
+    loss_df = loss_df[scenarios]
+
+    loss_df = st.data_editor(
+        loss_df.reset_index().rename(columns={"index": "Action"}),
+        num_rows="dynamic",
+        use_container_width=True,
+    )
+
+    loss_df = loss_df.dropna(subset=["Action"]).copy()
+    loss_df["Action"] = loss_df["Action"].astype(str).str.strip()
+    loss_df = loss_df[loss_df["Action"] != ""]
+    if loss_df.empty:
+        st.error("Add at least one action.")
+        st.stop()
+
+    actions = loss_df["Action"].tolist()
+    loss_vals = loss_df.drop(columns=["Action"]).fillna(0.0).astype(float).to_numpy()
+
+# Compute
+loss_mat = loss_vals  # shape (A, S)
+A, S = loss_mat.shape
+
+exp = expected_loss(loss_mat, probs)
+reg = regret_matrix(loss_mat)
+mxr = max_regret(reg)
+cvar = cvar_per_action(loss_mat, probs, alpha=alpha)
+
+results = pd.DataFrame(
+    {
+        "Expected Loss": exp,
+        "Max Regret": mxr,
+        f"CVaR@{alpha:.2f}": cvar,
+    },
+    index=actions,
+)
+
+# -----------------------
+# Heuristic recommendation (rule suggestion)
+# -----------------------
+# Minimal heuristic: if tail risk is materially worse than average, recommend CVaR;
+# if probabilities are weak/unknown, recommend Minimax Regret; otherwise Expected Loss.
+
+tail_ratio = float(results[f"CVaR@{alpha:.2f}"].min() / max(results["Expected Loss"].min(), 1e-9))
+
+if tail_ratio >= 1.5:
+    rule_reco = "CVaR"
+    rule_reason = f"Tail risk dominates average (best CVaR / best Expected Loss = {tail_ratio:.2f})."
+else:
+    rule_reco = "Expected Loss"
+    rule_reason = f"Tail risk is not extreme (ratio = {tail_ratio:.2f}); average-optimal is defensible."
+
+# Let user override the heuristic explicitly (keeps governance clean)
+use_rule_reco = st.sidebar.checkbox("Use recommended rule (heuristic)", value=False)
+if use_rule_reco:
+    primary_rule = rule_reco
+
+
+# Choose by rule
+if primary_rule == "Expected Loss":
+    metric = results["Expected Loss"]
+    best_val = metric.min()
+    best_actions = metric[metric == best_val].index.tolist()
+elif primary_rule == "Minimax Regret":
+    metric = results["Max Regret"]
+    best_val = metric.min()
+    best_actions = metric[metric == best_val].index.tolist()
+else:
+    col = f"CVaR@{alpha:.2f}"
+    metric = results[col]
+    best_val = metric.min()
+    best_actions = metric[metric == best_val].index.tolist()
+
+chosen = best_actions[0] if tie_policy == "First" else ", ".join(best_actions)
+st.sidebar.header("Rule guidance (when to use what)")
+
+st.sidebar.markdown(
+    """
+**Expected Loss (risk-neutral)**
+- Use when decisions repeat frequently and you can tolerate variance.
+- Use when probabilities are reasonably trusted.
+- Optimizes *average* pain.
+
+**Minimax Regret (robust to bad probability estimates)**
+- Use when probabilities are unreliable or politically contested.
+- Use for one-shot / high-accountability decisions.
+- Minimizes “I should have done X” exposure.
+
+**CVaR (tail-risk protection)**
+- Use when rare bad outcomes are unacceptable (ruin / safety / bankruptcy).
+- Use when downside is asymmetric and must be bounded.
+- Optimizes the *average of worst cases* (tail), not the average overall.
+"""
+)
+
+# Layout output
+st.divider()
+topL, topR = st.columns([2, 1], vertical_alignment="center")
+with topL:
+    st.subheader("Decision")
+    st.markdown(f"### Choose **{chosen}**")
+    st.caption(f"Primary rule: **{primary_rule}**")
+with topR:
+    st.metric("Scenarios", S)
+    st.metric("Actions", A)
+
+st.subheader("Evidence table")
+st.dataframe(results.style.format("{:.3f}"), use_container_width=True)
+
+st.subheader("Regret table (per action × scenario)")
+reg_df = pd.DataFrame(reg, index=actions, columns=scenarios)
+st.dataframe(reg_df.style.format("{:.3f}"), use_container_width=True)
+
+# Decision card
+st.subheader("Decision Card")
+st.info(f"Recommended rule (heuristic): **{rule_reco}** — {rule_reason}")
+
+prob_str = ", ".join([f"{s}={p:.2f}" for s, p in zip(scenarios, probs)])
+
+exp_best = results["Expected Loss"].idxmin()
+mxr_best = results["Max Regret"].idxmin()
+cvar_best = results[f"CVaR@{alpha:.2f}"].idxmin()
+
+st.code(
+    f"""DECISION KERNEL LITE — DECISION CARD
+
+Decision:
+Choose action {chosen}
+
+Context:
+- Actions evaluated: {", ".join(actions)}
+- Scenarios considered: {", ".join(scenarios)}
+- Probabilities: {prob_str}
+
+Results:
+- Expected Loss optimal: {exp_best} ({results.loc[exp_best, "Expected Loss"]:.3f})
+- Minimax Regret optimal: {mxr_best} ({results.loc[mxr_best, "Max Regret"]:.3f})
+- CVaR@{alpha:.2f} optimal: {cvar_best} ({results.loc[cvar_best, f"CVaR@{alpha:.2f}"]:.3f})
+
+Rule guidance:
+- Expected Loss: repeated decisions + trusted probabilities
+- Minimax Regret: probabilities unreliable + high accountability
+- CVaR: tail-risk unacceptable / ruin protection
+
+Recommended rule (heuristic): {rule_reco} — {rule_reason}
+
+
+Primary rule used: {primary_rule}
+""",
+    language="text",
+)
+
+with st.expander("Raw inputs"):
+    st.write("Probabilities (normalized):", probs)
+    st.dataframe(pd.DataFrame(loss_mat, index=actions, columns=scenarios), use_container_width=True)

docs/Appendix.md

@@ -0,0 +1,190 @@
+# **Appendix — Decision Kernel Lite**
+
+## **Purpose**
+
+This appendix consolidates **worked examples, edge cases, and interpretation notes** supporting Decision Kernel Lite.
+
+It is intended for:
+
+* reviewers and auditors
+* advanced users
+* downstream system integrators
+
+This appendix is **reference-only** and complements the Executive and Technical Briefs.
+
+---
+
+## **Appendix A — Worked Example (Baseline Case)**
+
+### **Inputs**
+
+**Actions:** A1, A2, A3
+**Scenarios:** Low, Medium, High
+**Probabilities:** 0.30, 0.40, 0.30
+
+**Loss Matrix**
+
+| Action | Low | Medium | High |
+| -----: | --: | -----: | ---: |
+|     A1 |  10 |      5 |    1 |
+|     A2 |   6 |      4 |    6 |
+|     A3 |   2 |      6 |   12 |
+
+---
+
+### **Expected Loss**
+
+[
+\text{EL}(A1)=5.3,\quad
+\text{EL}(A2)=5.2,\quad
+\text{EL}(A3)=6.6
+]
+
+**Optimal:** A2
+
+Interpretation: A2 minimizes average loss given the stated probabilities.
+
+---
+
+### **Regret Matrix**
+
+| Action | Low | Medium | High | Max Regret |
+| -----: | --: | -----: | ---: | ---------: |
+|     A1 |   8 |      1 |    0 |          8 |
+|     A2 |   4 |      0 |    5 |          5 |
+|     A3 |   0 |      2 |   11 |         11 |
+
+**Optimal (Minimax Regret):** A2
+
+Interpretation: A2 minimizes worst-case hindsight regret.
+
+---
+
+### **CVaR @ 0.8**
+
+With three discrete scenarios, CVaR selects outcomes in the **worst 20% tail**, which collapses to the worst scenario.
+
+| Action | CVaR@0.8 |
+| -----: | -------: |
+|     A1 |       10 |
+|     A2 |        6 |
+|     A3 |       12 |
+
+**Optimal (CVaR):** A2
+
+Interpretation: A2 has the lowest average loss conditional on being in the tail.
+
+---
+
+### **Decision Card (Result)**
+
+```
+Decision: Choose A2
+
+Rationale:
+- Expected Loss optimal
+- Minimax Regret optimal
+- CVaR optimal
+```
+
+All lenses agree. This represents a **fully aligned decision**.
+
+---
+
+## **Appendix B — When Decision Lenses Disagree**
+
+Disagreement between lenses is **expected** and informative.
+
+| Situation                            | Expected Loss | Minimax Regret | CVaR    |
+| ------------------------------------ | ------------- | -------------- | ------- |
+| Aggressive upside bet                | Favors        | Rejects        | Rejects |
+| Conservative safety choice           | Rejects       | Neutral        | Favors  |
+| High accountability / political risk | Neutral       | Favors         | Neutral |
+
+**Guidance:**
+
+* Do not average lenses
+* Select the rule that matches the risk posture
+* Document the choice explicitly
+
+---
+
+## **Appendix C — CVaR in Discrete Scenario Settings**
+
+In small discrete scenario sets:
+
+* CVaR approximates worst-case average
+* This behavior is correct by definition
+
+As the number of scenarios increases:
+
+* CVaR becomes smoother
+* Tail behavior is better resolved
+
+Decision Kernel Lite intentionally operates in the **discrete regime**.
+
+---
+
+## **Appendix D — Probability Misspecification**
+
+When probabilities are uncertain or contested:
+
+* Expected Loss becomes fragile
+* Minimax Regret remains valid
+* CVaR protects against catastrophic misestimation
+
+**Operational rule:**
+If probabilities are debated → prefer **Regret** or **CVaR**.
+
+---
+
+## **Appendix E — Integration Positioning**
+
+Decision Kernel Lite is designed to sit between analytics and action:
+
+```text
+Forecasts → Scenarios → Probabilities → Losses
+                           ↓
+                    Decision Kernel Lite
+                           ↓
+                    Action / Policy / Price
+```
+
+It does not replace forecasting or optimization.
+It **binds them into a decision**.
+
+---
+
+## **Appendix F — Design Exclusions (Intentional)**
+
+Decision Kernel Lite deliberately excludes:
+
+* forecasting models
+* probability estimation
+* optimization solvers
+* learning or calibration
+
+Rationale:
+
+* forecasting belongs upstream
+* optimization belongs downstream
+* decision justification belongs here
+
+This separation preserves clarity, auditability, and governance.
+
+---
+
+## **Appendix G — Audit & Governance Notes**
+
+* Deterministic computations
+* Explicit assumptions
+* No hidden state
+* Copy/paste Decision Card output
+
+This makes the kernel suitable for:
+
+* executive review
+* governance committees
+* post-decision audits
+
+---

docs/Executive_brief.md

@@ -0,0 +1,178 @@
+
+---
+
+# **Executive Brief — Decision Kernel Lite**
+
+## **Why This Exists**
+
+Most decisions fail not because of missing data, but because uncertainty is handled informally:
+
+* probabilities are debated, not modeled
+* downside risk is underweighted
+* justifications are retrospective, not structured
+
+Decision Kernel Lite provides a **simple, auditable mechanism** to choose actions when outcomes are uncertain and costs are asymmetric.
+
+It replaces intuition-driven debate with **explicit trade-offs**.
+
+---
+
+## **What the System Does**
+
+Decision Kernel Lite takes four inputs:
+
+* a set of **actions**
+* a set of plausible **scenarios**
+* **probabilities** for each scenario
+* a **loss matrix** describing consequences
+
+From these, it produces:
+
+* a **single recommended action**
+* a clear justification using multiple risk lenses
+* a **Decision Card** suitable for executive review
+
+No forecasting.
+No optimization.
+Only the decision.
+
+---
+
+## **The Three Risk Lenses**
+
+The system evaluates every action using three complementary rules.
+
+### **1. Expected Loss — “What works best on average?”**
+
+* Optimizes average outcome
+* Appropriate when probabilities are trusted
+* Best for repeatable decisions
+
+This is the default economic lens.
+
+---
+
+### **2. Minimax Regret — “What will I regret least?”**
+
+* Optimizes post-hoc defensibility
+* Appropriate when probabilities are unreliable or disputed
+* Best for one-shot, high-accountability decisions
+
+This lens protects decision-makers from hindsight criticism.
+
+---
+
+### **3. CVaR — “How bad are the bad cases?”**
+
+* Focuses on tail risk
+* Appropriate when rare failures are unacceptable
+* Best for safety, financial ruin, or irreversible outcomes
+
+This lens prioritizes survival over average performance.
+
+---
+
+## **How the Final Decision Is Chosen**
+
+* All three lenses are computed simultaneously
+* A **primary decision rule** is selected explicitly
+* A heuristic recommendation is provided, but can be overridden
+
+This ensures:
+
+* transparency
+* governance
+* accountability
+
+There is no “black box” choice.
+
+---
+
+## **What the Output Looks Like**
+
+The system produces a **Decision Card** summarizing:
+
+* the recommended action
+* the assumptions used
+* how each rule evaluated the options
+* why the final rule was chosen
+
+This artifact can be:
+
+* pasted into an executive memo
+* included in a slide deck
+* stored for audit and review
+
+---
+
+## **What Makes This Different**
+
+Decision Kernel Lite does **not** attempt to:
+
+* predict demand
+* estimate probabilities automatically
+* optimize operational parameters
+
+Its value lies in **decision clarity**, not model sophistication.
+
+It sits between:
+
+* analytics (what might happen)
+* and operations (what to do)
+
+---
+
+## **Typical Use Cases**
+
+* strategic one-off choices
+* pricing or investment decisions with asymmetric downside
+* contract or supplier selection
+* policy or governance decisions
+* scenario planning workshops
+
+Any situation where:
+
+> “We must decide, even though we are uncertain.”
+
+---
+
+## **Business Value**
+
+Organizations using structured decision kernels achieve:
+
+* faster decision cycles
+* fewer unexamined assumptions
+* reduced post-decision conflict
+* clearer accountability
+
+Most importantly:
+
+> Decisions become explainable, not just executable.
+
+---
+
+## **Positioning**
+
+Decision Kernel Lite is a **foundational decision layer**.
+
+It can be:
+
+* used standalone
+* embedded into larger planning systems
+* integrated downstream of forecasting or upstream of optimization
+
+It is deliberately minimal, fast, and domain-agnostic.
+
+---
+
+## **Bottom Line**
+
+Decision Kernel Lite does not promise certainty.
+
+It delivers something more valuable:
+
+> **Clarity about what you are choosing — and why — under uncertainty.**
+
+---
+
+

docs/Technical_Brief.md

@@ -0,0 +1,238 @@
+
+---
+
+# **Technical Brief — Decision Kernel Lite**
+
+## **Purpose**
+
+This document specifies the **mathematical definitions**, **algorithms**, and **implementation choices** used in Decision Kernel Lite.
+
+The goal is not theoretical novelty, but **correct, transparent, and reproducible decision logic**.
+
+---
+
+## **Formal Problem Definition**
+
+Let:
+
+* Actions: ( a \in {1,\dots,A} )
+* Scenarios: ( s \in {1,\dots,S} )
+* Scenario probabilities: ( p_s \ge 0,\ \sum_s p_s = 1 )
+* Loss matrix: ( L_{a,s} \in \mathbb{R}_{\ge 0} )
+
+A decision consists of selecting one action ( a^* ) under uncertainty about which scenario ( s ) will occur.
+
+---
+
+## **Decision Lenses**
+
+Decision Kernel Lite evaluates each action using three lenses.
+
+### **1. Expected Loss**
+
+[
+\text{EL}(a) = \sum_{s=1}^{S} p_s \cdot L_{a,s}
+]
+
+**Interpretation**
+
+* Risk-neutral criterion
+* Minimizes long-run average loss
+
+**Implementation**
+
+```python
+expected_loss = loss_matrix @ probabilities
+```
+
+---
+
+### **2. Regret and Minimax Regret**
+
+**Regret matrix**
+
+[
+R_{a,s} = L_{a,s} - \min_{a'} L_{a',s}
+]
+
+**Max regret per action**
+
+[
+\text{MR}(a) = \max_s R_{a,s}
+]
+
+**Decision rule**
+
+[
+a^* = \arg\min_a \text{MR}(a)
+]
+
+**Interpretation**
+
+* Robust to probability misspecification
+* Optimizes post-hoc defensibility
+
+**Implementation**
+
+```python
+regret = loss - loss.min(axis=0, keepdims=True)
+max_regret = regret.max(axis=1)
+```
+
+---
+
+### **3. CVaR (Conditional Value at Risk)**
+
+CVaR evaluates **average loss in the worst tail of outcomes**.
+
+#### **Procedure (discrete)**
+
+1. Sort losses ( L_{a,s} ) in ascending order
+2. Sort probabilities accordingly
+3. Compute cumulative probability
+4. Select outcomes where cumulative probability ≥ ( \alpha )
+5. Compute probability-weighted average over the tail
+
+[
+\text{CVaR}_\alpha(a)
+=====================
+
+\mathbb{E}[L_{a,s} \mid \text{worst } (1-\alpha) \text{ mass}]
+]
+
+**Interpretation**
+
+* Tail-risk-aware
+* Penalizes catastrophic downside
+
+**Implementation**
+
+```python
+order = np.argsort(losses)
+cum = np.cumsum(probs[order])
+tail = cum >= alpha
+cvar = (losses[order][tail] * probs[order][tail]).sum() / probs[order][tail].sum()
+```
+
+---
+
+## **Probability Normalization**
+
+To guarantee numerical and logical safety:
+
+* Negative probabilities are clipped to zero
+* Zero-sum vectors default to uniform probabilities
+* All probabilities are normalized to sum to 1
+
+```python
+p = np.clip(p, 0, None)
+p = p / p.sum() if p.sum() > 0 else np.ones_like(p) / len(p)
+```
+
+This ensures the kernel **never fails due to malformed inputs**.
+
+---
+
+## **Rule Selection Heuristic**
+
+Decision Kernel Lite includes an **advisory heuristic**:
+
+[
+\text{Tail Ratio} =
+\frac{\min_a \text{CVaR}_\alpha(a)}{\min_a \text{EL}(a)}
+]
+
+* If Tail Ratio ≥ 1.5 → recommend **CVaR**
+* Otherwise → recommend **Expected Loss**
+
+**Properties**
+
+* Transparent
+* Non-binding
+* Overridable by the user
+
+This preserves governance while guiding non-technical users.
+
+---
+
+## **Decision Logic Flow**
+
+```text
+Inputs
+  ↓
+Normalize probabilities
+  ↓
+Compute:
+  - Expected Loss
+  - Regret matrix
+  - Max Regret
+  - CVaR
+  ↓
+Select primary rule
+  ↓
+Choose action
+  ↓
+Generate Decision Card
+```
+
+All computations are deterministic and stateless.
+
+---
+
+## **System Architecture**
+
+* **Core kernel**: pure NumPy (testable, embeddable)
+* **UI layer**: Streamlit (input + presentation only)
+* **Deployment**: Docker / Hugging Face Spaces
+
+There is no persistence, no external API, and no hidden state.
+
+---
+
+## **Design Constraints (Intentional)**
+
+The system deliberately avoids:
+
+* forecasting
+* probability estimation
+* optimization solvers
+* learning or calibration
+
+These belong to **adjacent layers**, not the decision kernel.
+
+---
+
+## **Computational Complexity**
+
+Let ( A ) = number of actions, ( S ) = number of scenarios.
+
+* Expected Loss: ( O(A \cdot S) )
+* Regret: ( O(A \cdot S) )
+* CVaR: ( O(A \cdot S \log S) )
+
+The system is effectively instantaneous for realistic decision sizes.
+
+---
+
+## **Reproducibility & Auditability**
+
+* Deterministic outputs
+* Explicit assumptions
+* Full transparency of trade-offs
+* Copy/paste Decision Card
+
+This makes the kernel suitable for:
+
+* executive decisions
+* governance reviews
+* post-decision audits
+
+---
+
+## **Summary**
+
+Decision Kernel Lite implements **classical, defensible decision theory** in a minimal, production-ready form.
+
+It transforms uncertainty from an excuse into a **structured input**.
+
+---

requirements.txt

@@ -0,0 +1,3 @@
+streamlit>=1.30,<2.0
+numpy>=1.23,<2.0
+pandas>=1.5,<3.0