feat: initial implementation of VaR engine

Portfolio Value-at-Risk computation engine with Historical and
Parametric (variance-covariance) methods, stressed VaR/ES, live
market data via yfinance, and audit-ready Excel export with
embedded formulas.

Includes:
- Gradio web UI with live-updating inputs
- Historical & Parametric VaR/ES calculations
- Stressed metrics over configurable stress windows
- Excel reports with formula-driven cells (no hardcoded values)
- Jupyter notebooks for exploration
- Project scaffolding (pyproject.toml, uv lockfile)

.gitattributes

@@ -0,0 +1,4 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.gradio
+log/
+output/

README.md

@@ -0,0 +1,66 @@
+# VaR Engine
+
+An interactive web app to compute **Value at Risk (VaR)** and **Expected Shortfall (ES)** for equities, featuring an interactive Gradio UI and **audit-ready Excel reports with embedded formulas**.
+
+
+## Features
+
+- **Interactive UI**: Sleek Gradio interface that dynamically updates on input changes.
+- **Live Market Data**: Fetches historical prices via `yfinance`
+- **Historical & Parametric VaR**: Supports both Historical and Parametric (variance-covariance) methods
+- **Stressed VaR/ES**: Computes stressed metrics over a configurable stress window (e.g. GFC 2008)
+- **Audit-Ready Excel**: Exports reports with **formula-driven calculations (no hardcoded outputs)**
+
+## Getting Started
+
+### Option 1: Using `uv` (Recommended)
+
+1.  **Sync the environment**:
+    ```bash
+    uv sync
+    ```
+2.  **Run the application**:
+    ```bash
+    gradio app.py
+    ```
+
+### Option 2: Manual Setup (Pip)
+
+1.  **Create and activate a virtual environment**:
+    - **MacOS / Linux**:
+      ```bash
+      python3 -m venv .venv
+      source .venv/bin/activate
+      ```
+    - **Windows**:
+      ```powershell
+      python -m venv .venv
+      .venv\Scripts\activate
+      ```
+
+2.  **Install dependencies**:
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+3.  **Run the application**:
+    ```bash
+    gradio app.py
+    ```
+
+The server will launch locally (typically at `http://127.0.0.1:7860` or `http://localhost:7860`). Open this address in your browser to access the VaR Engine.
+
+## Project Structure
+
+- **`app.py`**: The thin Gradio presentation/UI layer.
+- **`src/`**: Core VaR calculation engine, data processing, and plotting logic.
+- **`config.yaml`**: Application settings (tickers, lookback window, stress period).
+- **`notebooks/`**: Jupyter notebooks for exploratory analysis (historical, parametric, Monte Carlo).
+- **`log/`**: Persistent application logs managed by `loguru`.
+- **`output/`**: Directory for exported Excel report files.
+
+
+## Future Work
+
+- **Multi-Asset Portfolio Support (In Progress)**: Extending from single equities to portfolios with configurable weights and aggregation of VaR/ES  
+- **Asset Class Expansion (In Progress)**: Adding support for indices, ETFs, bonds, and other instruments  

app.py

@@ -0,0 +1,295 @@
+"""
+app.py -- Gradio UI for Value at Risk Analysis.
+"""
+
+import pandas as pd
+import gradio as gr
+from src.logger import logger
+from src.config import TICKERS, LOOKBACK_DAYS, STRESS_START_DATE, STRESS_END_DATE, STRESS_LABEL
+from src.historical import historical_var_es_pipeline
+from src.parametric import parametric_var_es_pipeline
+
+
+def calculate_var_analysis(
+    ticker: str,
+    end_date_str: str,
+    portfolio_value: float,
+    n_days: int,
+    var_confidence_label: str,
+    es_confidence_label: str,
+    method: str,
+):
+    """Calculate Value at Risk analysis based on Gradio inputs and delegate to the analysis pipeline."""
+    logger.info(
+        f"Analysis requested: {ticker} | VaR={var_confidence_label} ES={es_confidence_label} | {method} | N={n_days} | Date={end_date_str} | PV=${portfolio_value:,.0f}"
+    )
+
+    var_confidence = float(var_confidence_label.strip().replace("%", "")) / 100.0
+    es_confidence = float(es_confidence_label.strip().replace("%", "")) / 100.0
+    var_conf_pct = var_confidence_label.strip()
+    es_conf_pct = es_confidence_label.strip()
+
+    today = pd.Timestamp.today().normalize()
+
+    try:
+        end_date = pd.to_datetime(end_date_str, errors="raise").normalize()
+    except Exception:
+        gr.Warning("Invalid date selection. Please try again.")
+        return reset_analysis_results(n_days, var_confidence_label, es_confidence_label, method)
+
+    if end_date >= today:
+        gr.Warning(
+            "Invalid date selection. VaR estimation requires historical data, so please choose a date prior to today."
+        )
+        return reset_analysis_results(n_days, var_confidence_label, es_confidence_label, method)
+
+    fy_start = pd.Timestamp(year=today.year - 1, month=4, day=1)
+
+    if end_date < fy_start:
+        gr.Warning(f"VaR Date must be after {fy_start.strftime('%Y-%m-%d')}")
+        return reset_analysis_results(n_days, var_confidence_label, es_confidence_label, method)
+
+    if portfolio_value <= 0:
+        gr.Warning("Portfolio value must be positive.")
+        return reset_analysis_results(n_days, var_confidence_label, es_confidence_label, method)
+
+    pipeline = historical_var_es_pipeline if method == "Historical VaR" else parametric_var_es_pipeline
+    result = pipeline(
+        ticker,
+        var_confidence,
+        es_confidence,
+        LOOKBACK_DAYS,
+        int(n_days),
+        portfolio_value,
+        end_date,
+        stress_start=STRESS_START_DATE,
+        stress_end=STRESS_END_DATE,
+        stress_label=STRESS_LABEL,
+    )
+
+    logger.success(
+        f"Analysis complete: VaR=${result['var_nd']:,.2f}, ES=${result['es_nd']:,.2f}, Excel={result['excel_path']}\n"
+    )
+
+    return (
+        gr.update(
+            label=f"{int(n_days)}-day {var_conf_pct} VaR",
+            value=f"${result['var_nd']:,.2f}",
+        ),
+        gr.update(
+            label=f"{int(n_days)}-day {es_conf_pct} ES",
+            value=f"${result['es_nd']:,.2f}",
+        ),
+        gr.update(
+            label=f"{int(n_days)}-day {var_conf_pct} Stressed VaR",
+            value=f"${result['stressed_var_nd']:,.2f}",
+        ),
+        gr.update(
+            label=f"{int(n_days)}-day {es_conf_pct} Stressed ES",
+            value=f"${result['stressed_es_nd']:,.2f}",
+        ),
+        gr.update(value=result["fig_dist"], visible=True),
+        gr.update(value=result["excel_path"], visible=True),
+    )
+
+
+def reset_analysis_results(n_days: float, var_confidence_label: str, es_confidence_label: str, method: str):
+    """Reset and hide analysis results when input parameters are modified."""
+    var_conf_pct = var_confidence_label.strip()
+    es_conf_pct = es_confidence_label.strip()
+    method_short = "Historical" if method == "Historical VaR" else "Parametric"
+
+    return (
+        gr.update(value="", label=f"{int(n_days)}-day {var_conf_pct} VaR"),
+        gr.update(value="", label=f"{int(n_days)}-day {es_conf_pct} ES"),
+        gr.update(value="", label=f"{int(n_days)}-day {var_conf_pct} Stressed VaR"),
+        gr.update(value="", label=f"{int(n_days)}-day {es_conf_pct} Stressed ES"),
+        gr.update(value=None, visible=False),
+        gr.update(visible=False),
+    )
+
+
+def enable_run_button_for_method(method: str):
+    """Enable the Run Analysis button only for fully implemented VaR methods."""
+    return gr.update(interactive=(method in ("Historical VaR", "Parametric VaR")))
+
+
+# ------------------------------------------------------------------
+# UI builder
+# ------------------------------------------------------------------
+
+
+def build_app() -> gr.Blocks:
+    """Construct and return the Gradio Blocks application."""
+
+    with gr.Blocks(
+        title="VaR Engine",
+    ) as app:
+        with gr.Row():
+            with gr.Column(scale=3):
+                gr.Markdown("# VaR Engine")
+            with gr.Column(scale=1, min_width=260):
+                download_file = gr.DownloadButton(
+                    "Download Excel Report",
+                    variant="primary",
+                    visible=False,
+                    elem_id="excel-btn",
+                )
+
+        with gr.Row():
+            # Sidebar
+            with gr.Column(scale=1, min_width=260):
+                gr.Markdown("### Inputs")
+                with gr.Group():
+                    ticker_dd = gr.Dropdown(
+                        choices=TICKERS,
+                        value=TICKERS[0],
+                        label="Ticker",
+                    )
+                    end_date_input = gr.DateTime(
+                        include_time=False,
+                        type="datetime",
+                        label="VaR Date",
+                    )
+                    portfolio_val_input = gr.Number(
+                        value=1000000,
+                        label="Portfolio Value ($)",
+                    )
+                    n_days_slider = gr.Slider(
+                        minimum=1,
+                        maximum=15,
+                        step=1,
+                        value=10,
+                        label="N Days for VaR",
+                    )
+                    with gr.Row():
+                        confidence_dd = gr.Dropdown(
+                            choices=["99%", "97.5%", "95%"],
+                            value="99%",
+                            label="VaR Confidence",
+                            min_width=100,
+                        )
+                        es_confidence_dd = gr.Dropdown(
+                            choices=["99%", "97.5%", "95%"],
+                            value="99%",
+                            label="ES Confidence",
+                            min_width=100,
+                        )
+                    method_radio = gr.Radio(
+                        choices=[
+                            "Historical VaR",
+                            "Parametric VaR",
+                        ],
+                        value="Historical VaR",
+                        label="Method",
+                    )
+                run_btn = gr.Button("Run Analysis", variant="primary")
+
+                # Enable/disable run button based on method availability
+                method_radio.change(
+                    fn=enable_run_button_for_method,
+                    inputs=method_radio,
+                    outputs=run_btn,
+                )
+            with gr.Column(scale=3):
+                gr.Markdown("### Results")
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        var_box = gr.Textbox(
+                            label="10-day 99% VaR",
+                            interactive=False,
+                        )
+                    with gr.Column(scale=1):
+                        es_box = gr.Textbox(
+                            label="10-day 99% ES",
+                            interactive=False,
+                        )
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        stressed_var_box = gr.Textbox(
+                            label="10-day 99% Stressed VaR",
+                            interactive=False,
+                        )
+                    with gr.Column(scale=1):
+                        stressed_es_box = gr.Textbox(
+                            label="10-day 99% Stressed ES",
+                            interactive=False,
+                        )
+
+                plot_dist = gr.Plot(show_label=False, visible=False)
+
+        # Wiring
+        all_outputs = [var_box, es_box, stressed_var_box, stressed_es_box, plot_dist, download_file]
+
+        run_btn.click(
+            fn=calculate_var_analysis,
+            inputs=[
+                ticker_dd,
+                end_date_input,
+                portfolio_val_input,
+                n_days_slider,
+                confidence_dd,
+                es_confidence_dd,
+                method_radio,
+            ],
+            outputs=all_outputs,
+        )
+
+        all_inputs = [
+            ticker_dd,
+            end_date_input,
+            portfolio_val_input,
+            n_days_slider,
+            confidence_dd,
+            es_confidence_dd,
+            method_radio,
+        ]
+
+        label_inputs = [n_days_slider, confidence_dd, es_confidence_dd, method_radio]
+
+        for comp in all_inputs:
+            if comp is n_days_slider:
+                comp.release(
+                    fn=reset_analysis_results,
+                    inputs=label_inputs,
+                    outputs=all_outputs,
+                )
+            else:
+                comp.change(
+                    fn=reset_analysis_results,
+                    inputs=label_inputs,
+                    outputs=all_outputs,
+                )
+
+        method_radio.change(
+            fn=enable_run_button_for_method, inputs=method_radio, outputs=run_btn
+        )
+
+    return app
+
+
+# ------------------------------------------------------------------
+# Entry point
+# ------------------------------------------------------------------
+
+if __name__ == "__main__":
+    custom_css = """
+    .form { border: none !important; box-shadow: none !important; gap: 0 !important; }
+    .form .block, .form .row, .form > * { border: none !important; box-shadow: none !important; }
+    #excel-btn, #excel-btn.primary {
+        background: #ea580c !important;
+        background-color: #ea580c !important;
+        color: white !important;
+        border-color: #7c2d12 !important;
+        border: 1px solid #7c2d12 !important;
+    }
+    #excel-btn:hover, #excel-btn.primary:hover {
+        background: #c2410c !important;
+        background-color: #c2410c !important;
+        border-color: #451a03 !important;
+        border: 1px solid #451a03 !important;
+    }
+    """
+
+    application = build_app()
+    application.launch(share=True, theme=gr.themes.Base(), css=custom_css)  

config.yaml

@@ -0,0 +1,19 @@
+# ------------------------------------------------------------------
+# VaR Engine – Application Settings
+# ------------------------------------------------------------------
+
+tickers:
+  - AAPL
+  - MSFT
+  - GOOG
+  - AMZN
+  - NVDA
+  - JPM
+  - BCS
+
+lookback_days: 251
+
+# Stress window used for Stressed VaR/ES
+stressed_period_label: "Global Financial Crisis (2008)"
+stressed_period_start_date: "2008-01-01"
+stressed_period_end_date: "2008-12-31"

notebooks/historical.ipynb

@@ -0,0 +1,229 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "title",
+   "metadata": {},
+   "source": [
+    "# Historical VaR"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e210b117",
+   "metadata": {},
+   "source": [
+    "## 1. Imports"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": "import numpy as np\nimport pandas as pd\nimport plotly.graph_objects as go\nimport yfinance as yf\nfrom datetime import datetime\nimport warnings\nwarnings.filterwarnings('ignore')"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "c0717aab",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Analyzing GOOG with 99% confidence\n",
+      "Lookback period: 251 days, Horizon: 10 days\n",
+      "Portfolio value: $1,000,000\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Set up parameters\n",
+    "TICKER = 'GOOG'\n",
+    "CONFIDENCE_LEVEL = 0.99\n",
+    "LOOKBACK_DAYS = 251  # ~1 year of trading days\n",
+    "HORIZON_DAYS = 10\n",
+    "PORTFOLIO_VALUE = 1_000_000\n",
+    "\n",
+    "print(f\"Analyzing {TICKER} with {CONFIDENCE_LEVEL:.0%} confidence\")\n",
+    "print(f\"Lookback period: {LOOKBACK_DAYS} days, Horizon: {HORIZON_DAYS} days\")\n",
+    "print(f\"Portfolio value: ${PORTFOLIO_VALUE:,}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bc738b1a",
+   "metadata": {},
+   "source": [
+    "## 1. Fetch Prices "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "fetch_data",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def fetch_prices(ticker, lookback, var_date=None):\n",
+    "    \"\"\"Fetch daily close prices for a ticker.\n",
+    "\n",
+    "    Gets the last `lookback` trading days of data up to the day before `var_date`.\n",
+    "    If `var_date` is not given, it uses the last business day.\n",
+    "    \"\"\"\n",
+    "    # if the var date is none fetch the last business day\n",
+    "    if var_date is None:\n",
+    "        var_date = (pd.Timestamp.today() - pd.offsets.BDay()).date()\n",
+    "    \n",
+    "    calendar_days = int(lookback * 1.6)\n",
+    "    start = var_date - pd.Timedelta(days=calendar_days)\n",
+    "\n",
+    "    df = yf.download(\n",
+    "        ticker,\n",
+    "        start=start.strftime(\"%Y-%m-%d\"),\n",
+    "        end=var_date.strftime(\"%Y-%m-%d\"),\n",
+    "        progress=False,\n",
+    "        interval=\"1d\",\n",
+    "        auto_adjust=True\n",
+    "    )\n",
+    "\n",
+    "    if df.empty:\n",
+    "        raise ValueError(f\"No data returned for ticker '{ticker}'.\")\n",
+    "    \n",
+    "    prices = df[\"Close\"].squeeze()\n",
+    "    prices.name = ticker\n",
+    "    result = prices.tail(lookback)\n",
+    "    return result"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "ff696443",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Shape: (251,)\n",
+      "Start date: 2025-03-26\n",
+      "End date: 2026-03-25\n"
+     ]
+    }
+   ],
+   "source": [
+    "prices = fetch_prices(TICKER, LOOKBACK_DAYS)\n",
+    "print(f\"Shape: {prices.shape}\")\n",
+    "print(f\"Start date: {prices.index.min().date()}\")\n",
+    "print(f\"End date: {prices.index.max().date()}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "614eb489",
+   "metadata": {},
+   "source": [
+    "## 2. Return Calculation\n",
+    "\n",
+    "Calculate daily returns from the price data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a2d126c7",
+   "metadata": {},
+   "outputs": [],
+   "source": "def compute_returns(prices, kind=\"arithmetic\"):\n    \"\"\"Compute daily returns from a price series.\n\n    kind : \"arithmetic\" or \"log\"\n        arithmetic  ->  (P_t - P_{t-1}) / P_{t-1}\n        log         ->  log(P_t) - log(P_{t-1})\n    \"\"\"\n    if kind == \"log\":\n        returns = np.log(prices) - np.log(prices.shift(1))\n        returns.name = \"Daily Log Return\"\n    else:\n        returns = (prices - prices.shift(1)) / prices.shift(1)\n        returns.name = \"Daily Return\"\n    return returns.dropna()"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ba2e12a3",
+   "metadata": {},
+   "outputs": [],
+   "source": "# Calculate returns\ndaily_returns = compute_returns(prices, kind=\"arithmetic\")\n\nprint(\"Daily return series:\")\nprint(\"Shape: \", daily_returns.shape)\nprint(\"\\n \", daily_returns.head())"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3aba51de",
+   "metadata": {},
+   "source": [
+    "## 3. Calculate VaR and ES"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "calculate_var_es",
+   "metadata": {},
+   "outputs": [],
+   "source": "def calculate_historical_var(returns, confidence):\n    \"\"\"Compute VaR from returns using the percentile method.\n\n    VaR is the (1 - confidence) percentile of returns, negated to express as loss.\n    Returns VaR as a positive loss fraction.\n    \"\"\"\n    vals = returns.values\n    return -float(np.percentile(np.asarray(vals), (1.0 - confidence) * 100))\n\n\ndef calculate_historical_es(returns, confidence):\n    \"\"\"Compute ES from returns using the percentile method.\n\n    ES = E[loss | loss > VaR], the mean of losses exceeding VaR.\n    Returns ES as a positive loss fraction.\n    \"\"\"\n    var = calculate_historical_var(returns, confidence)\n    losses = -np.asarray(returns.values)\n    tail = losses[losses > var]\n    return float(np.mean(tail)) if len(tail) > 0 else var"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0368a7bb",
+   "metadata": {},
+   "outputs": [],
+   "source": "var_pct = calculate_historical_var(daily_returns, CONFIDENCE_LEVEL)\nes_pct = calculate_historical_es(daily_returns, CONFIDENCE_LEVEL)\nprint(f\"VaR: {var_pct:.4f} ({var_pct*100:.2f}%)\")\nprint(f\"ES: {es_pct:.4f} ({es_pct*100:.2f}%)\")"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "analysis_section",
+   "metadata": {},
+   "source": [
+    "## 5. Orchestration of the workflow"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12a3fbb2",
+   "metadata": {},
+   "outputs": [],
+   "source": "def historical_var_es_pipeline(ticker, confidence, lookback, n_days, portfolio_value, end_date=None):\n    \"\"\"Run the full historical VaR workflow.\n\n    Fetches data, computes 1-day VaR/ES, and scales results to n-day horizon.\n    Returns dollar VaR/ES along with the underlying data.\n    \"\"\"\n    # 1. Fetch data and compute returns\n    prices = fetch_prices(ticker, lookback, end_date)\n    daily_returns = compute_returns(prices, kind=\"arithmetic\")\n\n    # 2. Calculate 1-day VaR and ES\n    var_1d_pct = calculate_historical_var(daily_returns, confidence)\n    es_1d_pct = calculate_historical_es(daily_returns, confidence)\n    var_1d = var_1d_pct * portfolio_value\n    es_1d = es_1d_pct * portfolio_value\n\n    # 3. Scale to N-day horizon\n    scaling_factor = np.sqrt(n_days)\n    var_nd = var_1d * scaling_factor\n    es_nd = es_1d * scaling_factor\n\n    return {\n        \"var_1d\": var_1d,\n        \"var_nd\": var_nd,\n        \"es_1d\": es_1d,\n        \"es_nd\": es_nd,\n        \"prices\": prices,\n        \"daily_returns\": daily_returns,\n    }"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2609e970",
+   "metadata": {},
+   "outputs": [],
+   "source": "results = historical_var_es_pipeline(\n    ticker=TICKER,\n    confidence=CONFIDENCE_LEVEL,\n    lookback=LOOKBACK_DAYS,\n    n_days=HORIZON_DAYS,\n    portfolio_value=PORTFOLIO_VALUE)"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "summary",
+   "metadata": {},
+   "outputs": [],
+   "source": "print(\"=\" * 60)\nprint(f\"HISTORICAL VaR ANALYSIS SUMMARY - {TICKER}\")\nprint(\"=\" * 60)\nprint(f\"VaR Date: {datetime.now().strftime('%Y-%m-%d')}\")\nprint(f\"Portfolio Value: ${PORTFOLIO_VALUE:,}\")\nprint(f\"Confidence Level: {CONFIDENCE_LEVEL:.0%}\")\nprint(f\"Time Horizon: {HORIZON_DAYS} days\")\nprint(f\"Historical Period: {LOOKBACK_DAYS} trading days\")\nprint()\nprint(\"VaR METRICS:\")\nprint('-'*60)\nprint(f\"  {HORIZON_DAYS}-Day VaR: ${results['var_nd']:,.2f} ({results['var_nd']/PORTFOLIO_VALUE*100:.2f}%)\")\nprint(f\"  {HORIZON_DAYS}-Day ES:  ${results['es_nd']:,.2f} ({results['es_nd']/PORTFOLIO_VALUE*100:.2f}%)\")\nprint()"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

notebooks/monte-carlo-simulation.ipynb

@@ -0,0 +1,474 @@
+{
+    "cells": [
+        {
+            "cell_type": "markdown",
+            "id": "title",
+            "metadata": {},
+            "source": [
+                "# Monte Carlo VaR — Step by Step"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "id": "c1",
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "import numpy as np\n",
+                "import matplotlib.pyplot as plt\n",
+                "import yfinance as yf\n",
+                "import warnings\n",
+                "warnings.filterwarnings('ignore')"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "id": "c2",
+            "metadata": {},
+            "outputs": [
+                {
+                    "data": {
+                        "text/plain": [
+                            "array([0.4 , 0.35, 0.25])"
+                        ]
+                    },
+                    "execution_count": 26,
+                    "metadata": {},
+                    "output_type": "execute_result"
+                }
+            ],
+            "source": [
+                "TICKERS = ['AAPL', 'GOOGL', 'MSFT']\n",
+                "WEIGHTS = np.array([0.40, 0.35, 0.25])\n",
+                "PORT_VALUE = 1_000_000\n",
+                "np.random.seed(42)\n",
+                "\n",
+                "WEIGHTS"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 27,
+            "id": "c3",
+            "metadata": {},
+            "outputs": [
+                {
+                    "name": "stderr",
+                    "output_type": "stream",
+                    "text": [
+                        "[*********************100%***********************]  3 of 3 completed\n"
+                    ]
+                },
+                {
+                    "data": {
+                        "text/html": [
+                            "<div>\n",
+                            "<style scoped>\n",
+                            "    .dataframe tbody tr th:only-of-type {\n",
+                            "        vertical-align: middle;\n",
+                            "    }\n",
+                            "\n",
+                            "    .dataframe tbody tr th {\n",
+                            "        vertical-align: top;\n",
+                            "    }\n",
+                            "\n",
+                            "    .dataframe thead th {\n",
+                            "        text-align: right;\n",
+                            "    }\n",
+                            "</style>\n",
+                            "<table border=\"1\" class=\"dataframe\">\n",
+                            "  <thead>\n",
+                            "    <tr style=\"text-align: right;\">\n",
+                            "      <th>Ticker</th>\n",
+                            "      <th>AAPL</th>\n",
+                            "      <th>GOOGL</th>\n",
+                            "      <th>MSFT</th>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>Date</th>\n",
+                            "      <th></th>\n",
+                            "      <th></th>\n",
+                            "      <th></th>\n",
+                            "    </tr>\n",
+                            "  </thead>\n",
+                            "  <tbody>\n",
+                            "    <tr>\n",
+                            "      <th>2025-12-24</th>\n",
+                            "      <td>273.554016</td>\n",
+                            "      <td>314.089996</td>\n",
+                            "      <td>486.908630</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>2025-12-26</th>\n",
+                            "      <td>273.144409</td>\n",
+                            "      <td>313.510010</td>\n",
+                            "      <td>486.599365</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>2025-12-29</th>\n",
+                            "      <td>273.504089</td>\n",
+                            "      <td>313.559998</td>\n",
+                            "      <td>485.990753</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>2025-12-30</th>\n",
+                            "      <td>272.824707</td>\n",
+                            "      <td>313.850006</td>\n",
+                            "      <td>486.369904</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>2025-12-31</th>\n",
+                            "      <td>271.605835</td>\n",
+                            "      <td>313.000000</td>\n",
+                            "      <td>482.518677</td>\n",
+                            "    </tr>\n",
+                            "  </tbody>\n",
+                            "</table>\n",
+                            "</div>"
+                        ],
+                        "text/plain": [
+                            "Ticker            AAPL       GOOGL        MSFT\n",
+                            "Date                                          \n",
+                            "2025-12-24  273.554016  314.089996  486.908630\n",
+                            "2025-12-26  273.144409  313.510010  486.599365\n",
+                            "2025-12-29  273.504089  313.559998  485.990753\n",
+                            "2025-12-30  272.824707  313.850006  486.369904\n",
+                            "2025-12-31  271.605835  313.000000  482.518677"
+                        ]
+                    },
+                    "execution_count": 27,
+                    "metadata": {},
+                    "output_type": "execute_result"
+                }
+            ],
+            "source": [
+                "prices = yf.download(TICKERS, start='2023-01-01', end='2026-01-01', auto_adjust=True)['Close'][TICKERS].dropna()\n",
+                "prices.tail()"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 28,
+            "id": "c4",
+            "metadata": {},
+            "outputs": [
+                {
+                    "data": {
+                        "text/html": [
+                            "<div>\n",
+                            "<style scoped>\n",
+                            "    .dataframe tbody tr th:only-of-type {\n",
+                            "        vertical-align: middle;\n",
+                            "    }\n",
+                            "\n",
+                            "    .dataframe tbody tr th {\n",
+                            "        vertical-align: top;\n",
+                            "    }\n",
+                            "\n",
+                            "    .dataframe thead th {\n",
+                            "        text-align: right;\n",
+                            "    }\n",
+                            "</style>\n",
+                            "<table border=\"1\" class=\"dataframe\">\n",
+                            "  <thead>\n",
+                            "    <tr style=\"text-align: right;\">\n",
+                            "      <th>Ticker</th>\n",
+                            "      <th>AAPL</th>\n",
+                            "      <th>GOOGL</th>\n",
+                            "      <th>MSFT</th>\n",
+                            "    </tr>\n",
+                            "  </thead>\n",
+                            "  <tbody>\n",
+                            "    <tr>\n",
+                            "      <th>count</th>\n",
+                            "      <td>751.0000</td>\n",
+                            "      <td>751.0000</td>\n",
+                            "      <td>751.0000</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>mean</th>\n",
+                            "      <td>0.0011</td>\n",
+                            "      <td>0.0017</td>\n",
+                            "      <td>0.0010</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>std</th>\n",
+                            "      <td>0.0160</td>\n",
+                            "      <td>0.0190</td>\n",
+                            "      <td>0.0146</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>min</th>\n",
+                            "      <td>-0.0970</td>\n",
+                            "      <td>-0.0999</td>\n",
+                            "      <td>-0.0638</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>25%</th>\n",
+                            "      <td>-0.0067</td>\n",
+                            "      <td>-0.0087</td>\n",
+                            "      <td>-0.0068</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>50%</th>\n",
+                            "      <td>0.0013</td>\n",
+                            "      <td>0.0023</td>\n",
+                            "      <td>0.0012</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>75%</th>\n",
+                            "      <td>0.0087</td>\n",
+                            "      <td>0.0116</td>\n",
+                            "      <td>0.0091</td>\n",
+                            "    </tr>\n",
+                            "    <tr>\n",
+                            "      <th>max</th>\n",
+                            "      <td>0.1426</td>\n",
+                            "      <td>0.0973</td>\n",
+                            "      <td>0.0965</td>\n",
+                            "    </tr>\n",
+                            "  </tbody>\n",
+                            "</table>\n",
+                            "</div>"
+                        ],
+                        "text/plain": [
+                            "Ticker      AAPL     GOOGL      MSFT\n",
+                            "count   751.0000  751.0000  751.0000\n",
+                            "mean      0.0011    0.0017    0.0010\n",
+                            "std       0.0160    0.0190    0.0146\n",
+                            "min      -0.0970   -0.0999   -0.0638\n",
+                            "25%      -0.0067   -0.0087   -0.0068\n",
+                            "50%       0.0013    0.0023    0.0012\n",
+                            "75%       0.0087    0.0116    0.0091\n",
+                            "max       0.1426    0.0973    0.0965"
+                        ]
+                    },
+                    "execution_count": 28,
+                    "metadata": {},
+                    "output_type": "execute_result"
+                }
+            ],
+            "source": [
+                "log_returns = np.log(prices / prices.shift(1)).dropna()\n",
+                "log_returns.describe().round(4)"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 29,
+            "id": "c5",
+            "metadata": {},
+            "outputs": [
+                {
+                    "data": {
+                        "text/plain": [
+                            "array([0.00105378, 0.00168275, 0.00096676])"
+                        ]
+                    },
+                    "execution_count": 29,
+                    "metadata": {},
+                    "output_type": "execute_result"
+                }
+            ],
+            "source": [
+                "mu  = log_returns.mean().values\n",
+                "mu"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 30,
+            "id": "c6",
+            "metadata": {},
+            "outputs": [
+                {
+                    "data": {
+                        "text/plain": [
+                            "array([[0.00025692, 0.00014008, 0.00011358],\n",
+                            "       [0.00014008, 0.00036247, 0.00013643],\n",
+                            "       [0.00011358, 0.00013643, 0.00021204]])"
+                        ]
+                    },
+                    "execution_count": 30,
+                    "metadata": {},
+                    "output_type": "execute_result"
+                }
+            ],
+            "source": [
+                "cov = log_returns.cov().values\n",
+                "cov"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 35,
+            "id": "c7",
+            "metadata": {},
+            "outputs": [
+                {
+                    "data": {
+                        "text/plain": [
+                            "array([1472.72241061, 1118.21086262,  518.11465968])"
+                        ]
+                    },
+                    "execution_count": 35,
+                    "metadata": {},
+                    "output_type": "execute_result"
+                }
+            ],
+            "source": [
+                "S0     = prices.iloc[-1].values\n",
+                "shares = (WEIGHTS * PORT_VALUE) / S0\n",
+                "shares"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 36,
+            "id": "c8",
+            "metadata": {},
+            "outputs": [
+                {
+                    "data": {
+                        "text/plain": [
+                            "(10000, 3)"
+                        ]
+                    },
+                    "execution_count": 36,
+                    "metadata": {},
+                    "output_type": "execute_result"
+                }
+            ],
+            "source": [
+                "sim_returns = np.random.multivariate_normal(mu, cov, size=10_000)\n",
+                "sim_returns.shape"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 37,
+            "id": "c9",
+            "metadata": {},
+            "outputs": [
+                {
+                    "data": {
+                        "text/plain": [
+                            "array([[268.98623474, 310.87375941, 483.01010853],\n",
+                            "       [266.65990125, 306.33240488, 473.68121623],\n",
+                            "       [269.20598714, 303.56541957, 473.94807854]])"
+                        ]
+                    },
+                    "execution_count": 37,
+                    "metadata": {},
+                    "output_type": "execute_result"
+                }
+            ],
+            "source": [
+                "sim_prices = S0 * np.exp(sim_returns)\n",
+                "sim_prices[:3]"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 38,
+            "id": "c10",
+            "metadata": {},
+            "outputs": [
+                {
+                    "name": "stdout",
+                    "output_type": "stream",
+                    "text": [
+                        "Mean ΔP: $+1,474  |  Std: $13,661\n"
+                    ]
+                }
+            ],
+            "source": [
+                "delta_P = sim_prices @ shares - PORT_VALUE\n",
+                "print(f'Mean ΔP: ${np.mean(delta_P):+,.0f}  |  Std: ${np.std(delta_P):,.0f}')"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 39,
+            "id": "c11",
+            "metadata": {},
+            "outputs": [
+                {
+                    "name": "stdout",
+                    "output_type": "stream",
+                    "text": [
+                        "95% VaR = $21,007  (2.10% of portfolio)\n"
+                    ]
+                }
+            ],
+            "source": [
+                "var95 = -np.percentile(delta_P, 5)\n",
+                "print(f'95% VaR = ${var95:,.0f}  ({var95/PORT_VALUE:.2%} of portfolio)')"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 40,
+            "id": "c12",
+            "metadata": {},
+            "outputs": [
+                {
+                    "name": "stdout",
+                    "output_type": "stream",
+                    "text": [
+                        "99% VaR = $29,626  (2.96% of portfolio)\n"
+                    ]
+                }
+            ],
+            "source": [
+                "var99 = -np.percentile(delta_P, 1)\n",
+                "print(f'99% VaR = ${var99:,.0f}  ({var99/PORT_VALUE:.2%} of portfolio)')"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": 43,
+            "id": "c14",
+            "metadata": {},
+            "outputs": [
+                {
+                    "data": {
+                        "image/png": "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",
+                        "text/plain": [
+                            "<Figure size 1000x400 with 1 Axes>"
+                        ]
+                    },
+                    "metadata": {},
+                    "output_type": "display_data"
+                }
+            ],
+            "source": [
+                "plt.figure(figsize=(10, 4))\n",
+                "plt.hist(delta_P, bins=80, density=True, alpha=0.7, color='steelblue', edgecolor='none')\n",
+                "plt.axvline(-var95, color='orange', lw=2, label=f'95% VaR ${var95:,.0f}')\n",
+                "plt.axvline(-var99, color='red', lw=2, label=f'99% VaR ${var99:,.0f}')\n",
+                "plt.xlabel('P&L ($)')\n",
+                "plt.ylabel('Density')\n",
+                "plt.title('1-Day P&L Distribution')\n",
+                "plt.legend()\n",
+                "plt.tight_layout()\n",
+                "plt.show()"
+            ]
+        }
+    ],
+    "metadata": {
+        "kernelspec": {
+            "display_name": "Python 3",
+            "language": "python",
+            "name": "python3"
+        },
+        "language_info": {
+            "name": "python",
+            "version": "3.9.6"
+        }
+    },
+    "nbformat": 4,
+    "nbformat_minor": 5
+}

notebooks/parametric.ipynb

@@ -0,0 +1,605 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "title",
+   "metadata": {},
+   "source": [
+    "# Parametric VaR\n",
+    "\n",
+    "The Parametric (Variance-Covariance) approach assumes that portfolio returns are\n",
+    "**normally distributed**. Instead of sorting historical returns, we estimate the\n",
+    "mean and standard deviation of the return distribution and use the **z-score**\n",
+    "at the desired confidence level to compute VaR analytically."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "imports_header",
+   "metadata": {},
+   "source": [
+    "## 1. Imports"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "import yfinance as yf\n",
+    "from scipy import stats\n",
+    "from datetime import datetime\n",
+    "import warnings\n",
+    "warnings.filterwarnings('ignore')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "parameters",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Analyzing GOOG with 99% confidence\n",
+      "Lookback period: 251 days, Horizon: 10 days\n",
+      "Portfolio value: $1,000,000\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Set up parameters\n",
+    "TICKER = 'GOOG'\n",
+    "CONFIDENCE_LEVEL = 0.99\n",
+    "LOOKBACK_DAYS = 251  # ~1 year of trading days\n",
+    "HORIZON_DAYS = 10\n",
+    "PORTFOLIO_VALUE = 1_000_000\n",
+    "\n",
+    "print(f\"Analyzing {TICKER} with {CONFIDENCE_LEVEL:.0%} confidence\")\n",
+    "print(f\"Lookback period: {LOOKBACK_DAYS} days, Horizon: {HORIZON_DAYS} days\")\n",
+    "print(f\"Portfolio value: ${PORTFOLIO_VALUE:,}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fetch_header",
+   "metadata": {},
+   "source": [
+    "## 2. Fetch Prices"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "fetch_data",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def fetch_prices(ticker, lookback, var_date=None):\n",
+    "    \"\"\"Fetch daily close prices for a ticker.\n",
+    "\n",
+    "    Gets the last `lookback` trading days of data up to the day before `var_date`.\n",
+    "    If `var_date` is not given, it uses the last business day.\n",
+    "    \"\"\"\n",
+    "    if var_date is None:\n",
+    "        var_date = (pd.Timestamp.today() - pd.offsets.BDay()).date()\n",
+    "\n",
+    "    calendar_days = int(lookback * 1.6)\n",
+    "    start = var_date - pd.Timedelta(days=calendar_days)\n",
+    "\n",
+    "    df = yf.download(\n",
+    "        ticker,\n",
+    "        start=start.strftime(\"%Y-%m-%d\"),\n",
+    "        end=var_date.strftime(\"%Y-%m-%d\"),\n",
+    "        progress=False,\n",
+    "        interval=\"1d\",\n",
+    "        auto_adjust=True\n",
+    "    )\n",
+    "\n",
+    "    if df.empty:\n",
+    "        raise ValueError(f\"No data returned for ticker '{ticker}'.\")\n",
+    "\n",
+    "    prices = df[\"Close\"].squeeze()\n",
+    "    prices.name = ticker\n",
+    "    result = prices.tail(lookback)\n",
+    "    return result"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "run_fetch",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Shape: (251,)\n",
+      "Start date: 2025-03-27\n",
+      "End date: 2026-03-26\n"
+     ]
+    }
+   ],
+   "source": [
+    "prices = fetch_prices(TICKER, LOOKBACK_DAYS)\n",
+    "print(f\"Shape: {prices.shape}\")\n",
+    "print(f\"Start date: {prices.index.min().date()}\")\n",
+    "print(f\"End date: {prices.index.max().date()}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "returns_header",
+   "metadata": {},
+   "source": [
+    "## 3. Return Calculation\n",
+    "\n",
+    "Calculate daily returns from the price data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "compute_returns",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def compute_returns(prices, kind=\"arithmetic\"):\n",
+    "    \"\"\"Compute daily returns from a price series.\n",
+    "\n",
+    "    kind : \"arithmetic\" or \"log\"\n",
+    "        arithmetic  ->  (P_t - P_{t-1}) / P_{t-1}\n",
+    "        log         ->  log(P_t) - log(P_{t-1})\n",
+    "    \"\"\"\n",
+    "    if kind == \"log\":\n",
+    "        returns = np.log(prices) - np.log(prices.shift(1))\n",
+    "        returns.name = \"Daily Log Return\"\n",
+    "    else:\n",
+    "        returns = (prices - prices.shift(1)) / prices.shift(1)\n",
+    "        returns.name = \"Daily Return\"\n",
+    "    return returns.dropna()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "run_returns",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Daily log return series:\n",
+      "Shape:  (250,)\n",
+      "\n",
+      "  Date\n",
+      "2025-03-28   -0.050114\n",
+      "2025-03-31    0.001089\n",
+      "2025-04-01    0.016820\n",
+      "2025-04-02   -0.000126\n",
+      "2025-04-03   -0.040007\n",
+      "Name: Daily Log Return, dtype: float64\n"
+     ]
+    }
+   ],
+   "source": [
+    "daily_returns = compute_returns(prices, kind=\"log\")\n",
+    "\n",
+    "print(\"Daily log return series:\")\n",
+    "print(\"Shape: \", daily_returns.shape)\n",
+    "print(\"\\n \", daily_returns.head())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "distribution_header",
+   "metadata": {},
+   "source": [
+    "## 4. Estimate Distribution Parameters\n",
+    "\n",
+    "The parametric method models daily returns as $R \\sim \\mathcal{N}(\\mu, \\sigma^2)$.  \n",
+    "We estimate the **mean** ($\\mu$) and **standard deviation** ($\\sigma$) from the\n",
+    "historical sample, then derive VaR from the normal quantile."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "estimate_params",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def estimate_distribution(returns):\n",
+    "    \"\"\"Estimate mean and standard deviation of daily returns.\"\"\"\n",
+    "    mu = returns.mean()\n",
+    "    # ddof=1 ensures we divide by (N-1), giving an unbiased estimate of volatility from sample data\n",
+    "    sigma = returns.std(ddof=1)\n",
+    "    return mu, sigma"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "run_estimate",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Mean daily return (mu):      0.002162 (0.2162%)\n",
+      "Std dev daily return (sigma): 0.018841 (1.8841%)\n"
+     ]
+    }
+   ],
+   "source": [
+    "mu, sigma = estimate_distribution(daily_returns)\n",
+    "\n",
+    "print(f\"Mean daily return (mu):      {mu:.6f} ({mu*100:.4f}%)\")\n",
+    "print(f\"Std dev daily return (sigma): {sigma:.6f} ({sigma*100:.4f}%)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "var_header",
+   "metadata": {},
+   "source": [
+    "## 5. Calculate VaR and ES\n",
+    "\n",
+    "**Parametric VaR** at confidence level $c$ is:\n",
+    "\n",
+    "$$\\text{VaR}_{1\\text{-day}} = -(\\mu + z_{\\alpha}\\,\\sigma)$$\n",
+    "\n",
+    "where $z_{\\alpha} = \\Phi^{-1}(1 - c)$ is the z-score for the lower tail.\n",
+    "\n",
+    "**Expected Shortfall (ES)** under the normal assumption is:\n",
+    "\n",
+    "$$\\text{ES}_{1\\text{-day}} = -(\\mu - \\sigma \\cdot \\frac{\\phi(z_{\\alpha})}{1-c})$$\n",
+    "\n",
+    "where $\\phi$ is the standard normal PDF."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "calculate_var_es",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def calculate_parametric_var(returns, confidence):\n",
+    "    \"\"\"Compute parametric VaR assuming normally distributed returns.\n",
+    "\n",
+    "    VaR = -(mu - z * sigma)   where z = norm.ppf(confidence).\n",
+    "    Returns VaR as a positive loss fraction.\n",
+    "    \"\"\"\n",
+    "    mu, sigma = estimate_distribution(returns)\n",
+    "    z = float(stats.norm.ppf(confidence))\n",
+    "    return -(mu - z * sigma)\n",
+    "\n",
+    "\n",
+    "def calculate_parametric_es(returns, confidence):\n",
+    "    \"\"\"Compute parametric ES assuming normally distributed returns.\n",
+    "\n",
+    "    ES = -(mu - sigma * phi(z) / (1 - confidence)).\n",
+    "    Returns ES as a positive loss fraction.\n",
+    "    \"\"\"\n",
+    "    mu, sigma = estimate_distribution(returns)\n",
+    "    z = float(stats.norm.ppf(confidence))\n",
+    "    alpha = 1.0 - confidence\n",
+    "    return -(mu - sigma * float(stats.norm.pdf(z)) / alpha)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "run_var",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "1-Day VaR: 0.0417 (4.17%)\n",
+      "1-Day ES:  0.0481 (4.81%)\n"
+     ]
+    }
+   ],
+   "source": [
+    "var_pct = calculate_parametric_var(daily_returns, CONFIDENCE_LEVEL)\n",
+    "es_pct = calculate_parametric_es(daily_returns, CONFIDENCE_LEVEL)\n",
+    "print(f\"1-Day VaR: {var_pct:.4f} ({var_pct*100:.2f}%)\")\n",
+    "print(f\"1-Day ES:  {es_pct:.4f} ({es_pct*100:.2f}%)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "orchestration_header",
+   "metadata": {},
+   "source": [
+    "## 6. Orchestration of the Workflow"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "calculate_parametric_var",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def parametric_var_es_pipeline(ticker, confidence, lookback, n_days, portfolio_value, end_date=None):\n",
+    "    \"\"\"Run the full parametric VaR workflow.\n",
+    "\n",
+    "    Fetches data, estimates distribution parameters, computes 1-day VaR/ES\n",
+    "    using the normal model, and scales results to the n-day horizon.\n",
+    "    Returns dollar VaR/ES along with the underlying data.\n",
+    "    \"\"\"\n",
+    "    # 1. Fetch data and compute returns\n",
+    "    prices = fetch_prices(ticker, lookback, end_date)\n",
+    "    daily_returns = compute_returns(prices, kind=\"log\")\n",
+    "    mu, sigma = estimate_distribution(daily_returns)\n",
+    "\n",
+    "    # 2. Calculate 1-day VaR and ES\n",
+    "    var_1d_pct = calculate_parametric_var(daily_returns, confidence)\n",
+    "    es_1d_pct = calculate_parametric_es(daily_returns, confidence)\n",
+    "    var_1d = var_1d_pct * portfolio_value\n",
+    "    es_1d = es_1d_pct * portfolio_value\n",
+    "\n",
+    "    # 3. Scale to N-day horizon\n",
+    "    scaling_factor = np.sqrt(n_days)\n",
+    "    var_nd = var_1d * scaling_factor\n",
+    "    es_nd = es_1d * scaling_factor\n",
+    "\n",
+    "    return {\n",
+    "        \"var_1d\": var_1d,\n",
+    "        \"var_nd\": var_nd,\n",
+    "        \"es_1d\": es_1d,\n",
+    "        \"es_nd\": es_nd,\n",
+    "        \"prices\": prices,\n",
+    "        \"daily_returns\": daily_returns,\n",
+    "        \"mu\": mu,\n",
+    "        \"sigma\": sigma,\n",
+    "    }"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "run_analysis",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = parametric_var_es_pipeline(\n",
+    "    ticker=TICKER,\n",
+    "    confidence=CONFIDENCE_LEVEL,\n",
+    "    lookback=LOOKBACK_DAYS,\n",
+    "    n_days=HORIZON_DAYS,\n",
+    "    portfolio_value=PORTFOLIO_VALUE)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "id": "summary",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "============================================================\n",
+      "PARAMETRIC VaR ANALYSIS SUMMARY - GOOG\n",
+      "============================================================\n",
+      "VaR Date: 2026-03-28\n",
+      "Portfolio Value: $1,000,000\n",
+      "Confidence Level: 99%\n",
+      "Time Horizon: 10 days\n",
+      "Historical Period: 251 trading days\n",
+      "\n",
+      "DISTRIBUTION PARAMETERS:\n",
+      "------------------------------------------------------------\n",
+      "  Mean daily return (mu):    0.002162\n",
+      "  Std dev (sigma):           0.018841\n",
+      "\n",
+      "VaR METRICS:\n",
+      "------------------------------------------------------------\n",
+      "  10-Day VaR: $131,766.21 (13.18%)\n",
+      "  10-Day ES:  $151,955.80 (15.20%)\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"=\" * 60)\n",
+    "print(f\"PARAMETRIC VaR ANALYSIS SUMMARY - {TICKER}\")\n",
+    "print(\"=\" * 60)\n",
+    "print(f\"VaR Date: {datetime.now().strftime('%Y-%m-%d')}\")\n",
+    "print(f\"Portfolio Value: ${PORTFOLIO_VALUE:,}\")\n",
+    "print(f\"Confidence Level: {CONFIDENCE_LEVEL:.0%}\")\n",
+    "print(f\"Time Horizon: {HORIZON_DAYS} days\")\n",
+    "print(f\"Historical Period: {LOOKBACK_DAYS} trading days\")\n",
+    "print()\n",
+    "print(\"DISTRIBUTION PARAMETERS:\")\n",
+    "print('-'*60)\n",
+    "print(f\"  Mean daily return (mu):    {results['mu']:.6f}\")\n",
+    "print(f\"  Std dev (sigma):           {results['sigma']:.6f}\")\n",
+    "print()\n",
+    "print(\"VaR METRICS:\")\n",
+    "print('-'*60)\n",
+    "print(f\"  {HORIZON_DAYS}-Day VaR: ${results['var_nd']:,.2f} ({results['var_nd']/PORTFOLIO_VALUE*100:.2f}%)\")\n",
+    "print(f\"  {HORIZON_DAYS}-Day ES:  ${results['es_nd']:,.2f} ({results['es_nd']/PORTFOLIO_VALUE*100:.2f}%)\")\n",
+    "print()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "tests_header",
+   "metadata": {},
+   "source": [
+    "## 7. Assumption Tests\n",
+    "\n",
+    "Parametric VaR rests on specific assumptions. The tests below verify that:\n",
+    "1. Returns are assumed to be **normally distributed**.\n",
+    "2. VaR is computed from **mean and standard deviation**.\n",
+    "3. **Tail risk is driven purely by volatility**."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "test1_intro",
+   "metadata": {},
+   "source": [
+    "### Test 1 – Normality of Returns\n",
+    "\n",
+    "Parametric VaR assumes that daily returns follow a normal distribution.  \n",
+    "We apply two statistical tests to evaluate this assumption:\n",
+    "\n",
+    "| Test | Purpose | Best for |\n",
+    "| --- | --- | --- |\n",
+    "| **Shapiro-Wilk** | General normality test (primary) | Small-to-medium samples (~250) |\n",
+    "| **Jarque-Bera** | Tests skewness & kurtosis specifically | Diagnosing *how* normality fails |\n",
+    "\n",
+    "A **p-value > 0.05** means we cannot reject the null hypothesis of normality\n",
+    "at the 5% significance level. The Shapiro-Wilk result drives the overall\n",
+    "conclusion; Jarque-Bera provides supporting detail."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "id": "test_normality_fn",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def test_normality(returns):\n",
+    "    \"\"\"Test whether returns follow a normal distribution.\n",
+    "\n",
+    "    Runs both the Shapiro-Wilk test (primary, suitable for n ~ 250)\n",
+    "    and the Jarque-Bera test (supporting, focuses on skewness and\n",
+    "    kurtosis).  Returns a dict with all test statistics.\n",
+    "    \"\"\"\n",
+    "    # Shapiro-Wilk (primary)\n",
+    "    sw_stat, sw_p = stats.shapiro(returns)\n",
+    "\n",
+    "    # Jarque-Bera (supporting diagnostic)\n",
+    "    jb_stat, jb_p = stats.jarque_bera(returns)\n",
+    "\n",
+    "    # Descriptive shape statistics\n",
+    "    skewness = returns.skew()\n",
+    "    excess_kurtosis = returns.kurtosis()  # normal = 0\n",
+    "\n",
+    "    return {\n",
+    "        \"sw_stat\": sw_stat,\n",
+    "        \"sw_pvalue\": sw_p,\n",
+    "        \"jb_stat\": jb_stat,\n",
+    "        \"jb_pvalue\": jb_p,\n",
+    "        \"skewness\": skewness,\n",
+    "        \"excess_kurtosis\": excess_kurtosis,\n",
+    "        \"n_obs\": len(returns),\n",
+    "        \"is_normal\": sw_p > 0.05\n",
+    "    }"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "id": "run_test_normality",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "============================================================\n",
+      "TEST 1: Normality of Returns\n",
+      "============================================================\n",
+      "  Sample size:       250\n",
+      "\n",
+      "SHAPE STATISTICS:\n",
+      "------------------------------------------------------------\n",
+      "  Skewness:          0.5195  (normal ~ 0)\n",
+      "  Excess kurtosis:   4.2984  (normal ~ 0)\n",
+      "\n",
+      "PRIMARY TEST  –  Shapiro-Wilk:\n",
+      "------------------------------------------------------------\n",
+      "  Statistic:         0.949339\n",
+      "  p-value:           0.000000\n",
+      "\n",
+      "SUPPORTING TEST  –  Jarque-Bera:\n",
+      "------------------------------------------------------------\n",
+      "  Statistic:         193.9030\n",
+      "  p-value:           0.000000\n",
+      "\n",
+      "CONCLUSION (based on Shapiro-Wilk):\n",
+      "============================================================\n",
+      "  WARNING - Normality rejected (Shapiro-Wilk p < 0.05).\n",
+      "  Returns may exhibit fat tails or skew; Parametric VaR could underestimate true tail risk.\n",
+      "  Data is NOT normal as per Shapiro-Wilk test.\n"
+     ]
+    }
+   ],
+   "source": [
+    "normality = test_normality(daily_returns)\n",
+    "\n",
+    "print(\"=\" * 60)\n",
+    "print(\"TEST 1: Normality of Returns\")\n",
+    "print(\"=\" * 60)\n",
+    "print(f\"  Sample size:       {normality['n_obs']}\")\n",
+    "print()\n",
+    "print(\"SHAPE STATISTICS:\")\n",
+    "print(\"-\" * 60)\n",
+    "print(f\"  Skewness:          {normality['skewness']:.4f}  (normal ~ 0)\")\n",
+    "print(f\"  Excess kurtosis:   {normality['excess_kurtosis']:.4f}  (normal ~ 0)\")\n",
+    "print()\n",
+    "print(\"PRIMARY TEST  –  Shapiro-Wilk:\")\n",
+    "print(\"-\" * 60)\n",
+    "print(f\"  Statistic:         {normality['sw_stat']:.6f}\")\n",
+    "print(f\"  p-value:           {normality['sw_pvalue']:.6f}\")\n",
+    "print()\n",
+    "print(\"SUPPORTING TEST  –  Jarque-Bera:\")\n",
+    "print(\"-\" * 60)\n",
+    "print(f\"  Statistic:         {normality['jb_stat']:.4f}\")\n",
+    "print(f\"  p-value:           {normality['jb_pvalue']:.6f}\")\n",
+    "print()\n",
+    "print(\"CONCLUSION (based on Shapiro-Wilk):\")\n",
+    "print(\"=\" * 60)\n",
+    "if normality[\"is_normal\"]:\n",
+    "    print(\"  PASS - Cannot reject normality at 5% significance.\")\n",
+    "    print(\"  The normal-distribution assumption is reasonable for this sample.\")\n",
+    "    print(\"  Data is considered normal as per Shapiro-Wilk test.\")\n",
+    "else:\n",
+    "    print(\"  WARNING - Normality rejected (Shapiro-Wilk p < 0.05).\")\n",
+    "    print(\"  Returns may exhibit fat tails or skew; Parametric VaR could underestimate true tail risk.\")\n",
+    "    print(\"  Data is NOT normal as per Shapiro-Wilk test.\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "value-at-risk (3.13.5)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "value-at-risk"
+version = "0.1.0"
+description = "Portfolio Value at Risk (VaR) Analysis Engine"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "gradio>=6.9.0",
+    "loguru>=0.7.3",
+    "matplotlib>=3.10.8",
+    "numpy>=2.4.3",
+    "openpyxl>=3.1.5",
+    "pandas>=3.0.1",
+    "plotly>=6.6.0",
+    "kaleido>=0.2.1",
+    "yfinance>=1.2.0",
+    "scipy>=1.17.1",
+]
+
+[tool.pyright]
+include = ["."]
+extraPaths = ["."]

requirements.txt

@@ -0,0 +1,10 @@
+gradio>=6.9.0
+loguru>=0.7.3
+matplotlib>=3.10.8
+numpy>=2.4.3
+openpyxl>=3.1.5
+pandas>=3.0.1
+plotly>=6.6.0
+kaleido>=0.2.1
+yfinance>=1.2.0
+scipy>=1.17.1

src/__init__.py

@@ -0,0 +1,57 @@
+"""VaR business logic."""
+
+from src.logger import logger
+
+from src.utils import (
+    fetch_prices,
+    compute_returns,
+    plot_distribution,
+)
+from src.historical import (
+    calculate_historical_var,
+    calculate_historical_es,
+    compute_historical_var_es,
+    compute_stressed_historical_var_es,
+    historical_var_es_pipeline,
+)
+from src.parametric import (
+    estimate_distribution,
+    calculate_parametric_var,
+    calculate_parametric_es,
+    compute_parametric_var_es,
+    compute_stressed_parametric_var_es,
+    parametric_var_es_pipeline,
+)
+from src.excel_export import export_historical_var_report, export_parametric_var_report
+from src.config import (
+    TICKERS,
+    LOOKBACK_DAYS,
+    STRESS_LABEL,
+    STRESS_START_DATE,
+    STRESS_END_DATE,
+)
+
+__all__ = [
+    "logger",
+    "fetch_prices",
+    "compute_returns",
+    "plot_distribution",
+    "calculate_historical_var",
+    "calculate_historical_es",
+    "compute_historical_var_es",
+    "compute_stressed_historical_var_es",
+    "historical_var_es_pipeline",
+    "estimate_distribution",
+    "calculate_parametric_var",
+    "calculate_parametric_es",
+    "compute_parametric_var_es",
+    "compute_stressed_parametric_var_es",
+    "parametric_var_es_pipeline",
+    "export_historical_var_report",
+    "export_parametric_var_report",
+    "TICKERS",
+    "LOOKBACK_DAYS",
+    "STRESS_LABEL",
+    "STRESS_START_DATE",
+    "STRESS_END_DATE",
+]

src/config.py

@@ -0,0 +1,21 @@
+"""
+config.py -- Load application configuration from config.yaml.
+
+Usage:
+    from src.config import TICKERS, LOOKBACK_DAYS, STRESS_LABEL, STRESS_START_DATE, STRESS_END_DATE
+"""
+
+from pathlib import Path
+
+import yaml
+
+_CONFIG_PATH = Path(__file__).resolve().parent.parent / "config.yaml"
+
+with open(_CONFIG_PATH) as _f:
+    _cfg = yaml.safe_load(_f)
+
+TICKERS: list[str] = _cfg["tickers"]
+LOOKBACK_DAYS: int = _cfg["lookback_days"]
+STRESS_LABEL: str = _cfg["stressed_period_label"]
+STRESS_START_DATE: str = _cfg["stressed_period_start_date"]
+STRESS_END_DATE: str = _cfg["stressed_period_end_date"]

src/excel_export.py

@@ -0,0 +1,540 @@
+"""
+excel_export.py -- Excel workbook creation with natively calculated VaR/ES formulas.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+from datetime import date
+import openpyxl
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+from openpyxl.worksheet.worksheet import Worksheet
+import pandas as pd
+from loguru import logger
+
+# Cell values can be str, int, float, None, etc.
+CellValue = str | int | float | None
+SummaryRow = list[CellValue]
+
+
+# ---------------------------------------------------------------------------
+# Shared styles
+# ---------------------------------------------------------------------------
+
+HEADER_FILL = PatternFill(start_color="1F497D", end_color="1F497D", fill_type="solid")
+HEADER_FONT = Font(color="FFFFFF", bold=True)
+VAR_95_FILL = PatternFill(start_color="FFD966", end_color="FFD966", fill_type="solid")  # orangish-yellow
+VAR_99_FILL = PatternFill(start_color="F6C96C", end_color="F6C96C", fill_type="solid")  # light amber
+THIN_BORDER = Border(
+    left=Side(style="thin"),
+    right=Side(style="thin"),
+    top=Side(style="thin"),
+    bottom=Side(style="thin"),
+)
+
+
+# ---------------------------------------------------------------------------
+# Public helpers
+# ---------------------------------------------------------------------------
+
+
+def make_output_dir() -> str:
+    """Create and return the directory ``output/{YYYY-MM-DD}/``."""
+    dir_path = os.path.join("output", date.today().strftime("%Y-%m-%d"))
+    os.makedirs(dir_path, exist_ok=True)
+    logger.debug(f"Output directory: {dir_path}")
+    return dir_path
+
+
+# ---------------------------------------------------------------------------
+# Data columns (A-D) -- shared between Historical and Parametric
+# ---------------------------------------------------------------------------
+
+
+def _write_data_columns(
+    worksheet: Worksheet,
+    prices: pd.Series,
+    max_data_row: int,
+    method: str,
+) -> None:
+    """Write date/price headers and rows into columns A-D.
+
+    Column C:
+    - Historical: -(P_t - P_{t-1}) / P_{t-1}  (arithmetic loss, positive = loss)
+    - Parametric: LN(P_t / P_{t-1})            (log return, negative = loss)
+    Column D:
+    - Historical: LARGE() -- losses descending (worst first)
+    - Parametric: SMALL() -- returns ascending (worst first)
+    """
+    if method == "Historical":
+        col_c_header = "Daily Arithmetic Return"
+        col_d_header = "Sorted Return"
+    else:
+        col_c_header = "Daily Log Return"
+        col_d_header = "Sorted Return"
+    center = Alignment(horizontal="right")
+
+    headers = ["Date", "Close Price", col_c_header, col_d_header]
+    for col_idx, header in enumerate(headers, start=1):
+        cell = worksheet.cell(row=1, column=col_idx, value=header)
+        cell.fill = HEADER_FILL
+        cell.font = HEADER_FONT
+        cell.border = THIN_BORDER
+        if col_idx in (2, 3, 4):
+            cell.alignment = center
+
+    dates = pd.DatetimeIndex(prices.index)
+    price_values = prices.values
+
+    for i in range(len(prices)):
+        row = i + 2
+        worksheet.cell(row=row, column=1, value=dates[i].strftime("%Y-%m-%d"))
+        price_cell = worksheet.cell(row=row, column=2, value=float(price_values[i]))
+        price_cell.alignment = center
+
+        if row > 2:
+            if method == "Historical":
+                col_c_formula = f"=(B{row}-B{row - 1})/B{row - 1}"
+                col_d_formula = f"=SMALL(C$3:C${max_data_row}, ROW()-2)"
+            else:
+                col_c_formula = f"=LN(B{row}/B{row - 1})"
+                col_d_formula = f"=SMALL(C$3:C${max_data_row}, ROW()-2)"
+            return_cell = worksheet.cell(row=row, column=3, value=col_c_formula)
+            return_cell.number_format = "0.0000%"
+            return_cell.alignment = center
+
+            sorted_cell = worksheet.cell(row=row, column=4, value=col_d_formula)
+            sorted_cell.number_format = "0.0000%"
+            sorted_cell.alignment = center
+
+
+# ---------------------------------------------------------------------------
+# VaR / ES formulas -- method-specific
+# ---------------------------------------------------------------------------
+
+
+def _var_dollar_formula(method: str, max_data_row: int, alpha: float, pv_ref: str) -> str:
+    """Return the Excel formula for 1-Day VaR ($) — positive = loss.
+
+    Historical: PERCENTILE(losses, confidence) * V
+    Parametric: -V * (mu - z_alpha * sigma)   where column C = LN returns
+    """
+    confidence = 1.0 - alpha
+    rng = f"C$3:C${max_data_row}"
+    if method == "Historical":
+        return f"=-PERCENTILE({rng},{alpha})*{pv_ref}"
+    else:
+        return (
+            f"=-{pv_ref}*(AVERAGE({rng})"
+            f"-_xlfn.NORM.S.INV({confidence})*_xlfn.STDEV.S({rng}))"
+        )
+
+
+def _es_dollar_formula(method: str, max_data_row: int, alpha: float, pv_ref: str) -> str:
+    """Return the Excel formula for 1-Day ES ($) — positive = loss.
+
+    Historical: ES = E[loss | loss > VaR] where loss = -return
+                -AVERAGEIF(returns < VaR_threshold) * V
+    Parametric: -V * (mu - sigma * phi(z) / alpha)
+    """
+    confidence = 1.0 - alpha
+    rng = f"C$3:C${max_data_row}"
+    if method == "Historical":
+        var_threshold = f"PERCENTILE({rng},{alpha})"
+        return f'=-AVERAGEIF({rng},"<"&{var_threshold})*{pv_ref}'
+    else:
+        return (
+            f"=-{pv_ref}*(AVERAGE({rng})"
+            f"-_xlfn.STDEV.S({rng})"
+            f"*_xlfn.NORM.DIST(_xlfn.NORM.S.INV({confidence}),0,1,FALSE)/{alpha})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Core export (shared between Historical and Parametric)
+# ---------------------------------------------------------------------------
+
+
+def _export_sheet(
+    method: str,
+    path: str,
+    prices: pd.Series,
+    ticker: str,
+    n_days: int,
+    portfolio_value: float,
+    var_date: pd.Timestamp | None,
+    stressed: bool,
+    lookback: int | None,
+    stress_start: str,
+    stress_end: str,
+    stress_label: str,
+    var_confidence: float = 0.99,
+    es_confidence: float = 0.975,
+) -> str:
+    """Create or append a VaR/ES sheet to an Excel workbook.
+
+    ``method`` must be ``"Historical"`` or ``"Parametric"``.
+    """
+
+    # ---- 1. Workbook / sheet setup -----------------------------------------
+
+    sheet_title = "VaR and ES"
+    stressed_sheet_title = "Stressed VaR and ES"
+
+    if stressed:
+        workbook = openpyxl.load_workbook(path)
+        worksheet = workbook.create_sheet(title=stressed_sheet_title)
+    else:
+        workbook = openpyxl.Workbook()
+        worksheet = workbook.active
+        assert worksheet is not None
+        worksheet.title = sheet_title
+
+    max_data_row = len(prices) + 1
+
+    # ---- 2. Write data columns A-D -----------------------------------------
+
+    _write_data_columns(worksheet, prices, max_data_row, method)
+
+    # ---- 2b. Highlight sorted returns at 95% and 99% VaR positions ---------
+
+    n_returns = max_data_row - 2  # returns start at row 3
+    for alpha, fill in [(0.05, VAR_95_FILL), (0.01, VAR_99_FILL)]:
+        pos = alpha * n_returns
+        lo = math.floor(pos)
+        hi = math.ceil(pos)
+        for k in {lo, hi}:
+            if 1 <= k <= n_returns:
+                worksheet.cell(row=k + 2, column=4).fill = fill  # column D
+
+    # ---- 3. Build parameter entries ----------------------------------------
+
+    date_str = var_date.strftime("%Y-%m-%d") if var_date is not None else ""
+
+    if stressed:
+        param_entries: list[SummaryRow] = [
+            ["Method", method, ""],
+            ["Ticker", ticker, ""],
+            ["VaR Date", date_str, ""],
+            ["Portfolio Value ($)", portfolio_value, ""],
+            ["N-Day Horizon", n_days, ""],
+            ["Stress Period Start Date", stress_start, ""],
+            ["Stress Period End Date", stress_end, ""],
+            ["Stress Period", stress_label, ""],
+        ]
+    else:
+        param_entries = [
+            ["Method", method, ""],
+            ["Ticker", ticker, ""],
+            ["VaR Date", date_str, ""],
+            ["Portfolio Value ($)", portfolio_value, ""],
+            ["N-Day Horizon", n_days, ""],
+            ["Return Observations", lookback - 1 if lookback else "", ""],
+        ]
+
+    # ---- 4. Compute row layout ---------------------------------------------
+    #
+    # Layout (0-based indices into summary_data):
+    #   [0]       Parameter header
+    #   [1..N]    param_entries   (N = len(param_entries))
+    #   [N+1]     separator
+    #   [N+2]     Standard header  (Risk Metric | 99% VaR ($) | 97.5% ES ($))
+    #   [N+3]     Standard 1-Day
+    #   [N+4]     Standard 10-Day Scaled
+    #   [N+5]     separator
+    #   [N+6]     Custom header   (Risk Metric | VaR X% | ES Y%)
+    #   [N+7]     Custom 1-Day
+    #   [N+8]     Custom 10-Day Scaled
+    #   [N+9]     Custom n-Day Scaled  (only when n_days != 10)
+
+    summary_start_row = 2
+    summary_start_col = 7  # Column G
+
+    N_params = len(param_entries)
+    # Portfolio Value is always param_entries[3]; entries start at absolute index 1
+    portfolio_value_abs_idx = 1 + 3  # = 4
+    pv_ref = f"$H${summary_start_row + portfolio_value_abs_idx}"
+
+    param_header_idx = 0
+    param_separator_idx = N_params + 1
+
+    std_header_idx = param_separator_idx + 1
+    std_1day_idx = std_header_idx + 1
+    std_10day_idx = std_1day_idx + 1
+    std_separator_idx = std_10day_idx + 1
+
+    custom_header_idx = std_separator_idx + 1
+    custom_1day_idx = custom_header_idx + 1
+    custom_10day_idx = custom_1day_idx + 1
+    custom_nday_idx: int | None = None
+    if n_days != 10:
+        custom_nday_idx = custom_10day_idx + 1
+
+    # ---- 5. Build standard table (fixed 99% VaR / 97.5% ES) ----------------
+
+    # Only show custom table when the selected levels differ from the standard (99%/97.5%)
+    show_custom = not (var_confidence == 0.99 and es_confidence == 0.975)
+
+    std_1day_h = f"H{summary_start_row + std_1day_idx}"
+    std_1day_i = f"I{summary_start_row + std_1day_idx}"
+
+    std_header_label = "Standard Stressed Risk Summary" if stressed else "Standard Risk Summary"
+
+    std_rows: list[SummaryRow] = [
+        [std_header_label, "99% VaR ($)", "97.5% ES ($)"],
+        ["1-Day",
+         _var_dollar_formula(method, max_data_row, 0.01, pv_ref),
+         _es_dollar_formula(method, max_data_row, 0.025, pv_ref)],
+        ["10-Day Scaled",
+         f"={std_1day_h} * SQRT(10)",
+         f"={std_1day_i} * SQRT(10)"],
+    ]
+    std_nday_idx: int | None = None
+    if n_days != 10 and not show_custom:
+        std_nday_idx = std_10day_idx + 1
+        std_rows.append([
+            f"{n_days}-Day Scaled",
+            f"={std_1day_h} * SQRT({n_days})",
+            f"={std_1day_i} * SQRT({n_days})",
+        ])
+
+    # ---- 6. Build custom table (user-selected confidence levels) ------------
+
+    var_alpha = 1.0 - var_confidence
+    es_alpha = 1.0 - es_confidence
+    var_conf_label = f"{var_confidence * 100:g}%"
+    es_conf_label = f"{es_confidence * 100:g}%"
+
+    custom_1day_h = f"H{summary_start_row + custom_1day_idx}"
+    custom_1day_i = f"I{summary_start_row + custom_1day_idx}"
+
+    custom_header_label = "Stressed Risk Summary" if stressed else "Risk Summary"
+
+    custom_rows: list[SummaryRow] = [
+        [custom_header_label, f"{var_conf_label} VaR ($)", f"{es_conf_label} ES ($)"],
+        ["1-Day",
+         _var_dollar_formula(method, max_data_row, var_alpha, pv_ref),
+         _es_dollar_formula(method, max_data_row, es_alpha, pv_ref)],
+        ["10-Day Scaled",
+         f"={custom_1day_h} * SQRT(10)",
+         f"={custom_1day_i} * SQRT(10)"],
+    ]
+    if n_days != 10:
+        custom_rows.append([
+            f"{n_days}-Day Scaled",
+            f"={custom_1day_h} * SQRT({n_days})",
+            f"={custom_1day_i} * SQRT({n_days})",
+        ])
+
+    # ---- 7. Assemble full summary ------------------------------------------
+
+    empty_row: SummaryRow = ["", "", ""]
+    summary_data: list[SummaryRow] = []
+    summary_data.append(["Parameter", "Value", ""])       # index 0
+    summary_data.extend(param_entries)                    # indices 1..N
+    summary_data.append(empty_row)                        # index N+1
+    summary_data.extend(std_rows)                         # indices N+2..N+4
+    if show_custom:
+        summary_data.append(empty_row)                    # index N+5
+        summary_data.extend(custom_rows)                  # indices N+6..
+
+    # ---- 9. Write and style the summary ------------------------------------
+
+    # Indices of param-section rows (skip col I for these)
+    param_all_indices = {param_header_idx} | set(range(1, 1 + N_params))
+
+    # Which rows to right-align value (col H) — param entries except Portfolio Value
+    right_align_indices = set(range(1, 1 + N_params)) - {portfolio_value_abs_idx}
+
+    # Which rows get money ($) formatting
+    money_format_indices: set[int] = {
+        portfolio_value_abs_idx,
+        std_1day_idx, std_10day_idx,
+    }
+    if std_nday_idx is not None:
+        money_format_indices.add(std_nday_idx)
+    if show_custom:
+        money_format_indices |= {custom_1day_idx, custom_10day_idx}
+        if custom_nday_idx is not None:
+            money_format_indices.add(custom_nday_idx)
+
+    # Which rows get dark-blue header styling
+    section_header_indices = {param_header_idx, std_header_idx}
+    if show_custom:
+        section_header_indices.add(custom_header_idx)
+
+    # Which rows skip all styling (separators)
+    unstyled_indices = {param_separator_idx}
+    if show_custom:
+        unstyled_indices.add(std_separator_idx)
+
+    for data_index, row_data in enumerate(summary_data):
+        sheet_row = summary_start_row + data_index
+        for col_offset, value in enumerate(row_data):
+            # Third column (col I) is unused for parameter rows
+            if data_index in param_all_indices and col_offset == 2:
+                continue
+
+            col = summary_start_col + col_offset
+            cell = worksheet.cell(row=sheet_row, column=col, value=value)  # type: ignore[arg-type]
+
+            # Skip styling for empty separators
+            if data_index in unstyled_indices:
+                continue
+
+            cell.border = THIN_BORDER
+
+            if data_index in section_header_indices:
+                cell.fill = HEADER_FILL
+                cell.font = HEADER_FONT
+                if col == 8:
+                    cell.alignment = Alignment(horizontal="right")
+                elif col == 9 and data_index != param_header_idx:
+                    cell.alignment = Alignment(horizontal="right")
+
+            if data_index in right_align_indices and col_offset == 1:
+                cell.alignment = Alignment(horizontal="right")
+
+            if col in (8, 9):  # Columns H and I
+                if data_index in money_format_indices:
+                    cell.number_format = '"$"#,##0.00'
+
+    # ---- 10. Column widths -------------------------------------------------
+
+    column_widths = {
+        "A": 12, "B": 15, "C": 20, "D": 15,
+        "E": 5, "F": 5,
+        "G": 27, "H": 24, "I": 24,
+    }
+    for column_letter, width in column_widths.items():
+        worksheet.column_dimensions[column_letter].width = width
+
+    # ---- 11. Save ----------------------------------------------------------
+
+    workbook.save(path)
+    action = "sheet added" if stressed else "report saved"
+    logger.info(f"{method} VaR ES {action}: {path}")
+    return path
+
+
+# ---------------------------------------------------------------------------
+# API -- thin wrappers around _export_sheet
+# ---------------------------------------------------------------------------
+
+
+def export_historical_var_sheet(
+    path: str,
+    prices: pd.Series,
+    ticker: str,
+    n_days: int,
+    portfolio_value: float,
+    var_date: pd.Timestamp | None = None,
+    stressed: bool = False,
+    lookback: int | None = None,
+    stress_start: str = "",
+    stress_end: str = "",
+    stress_label: str = "",
+    var_confidence: float = 0.99,
+    es_confidence: float = 0.975,
+) -> str:
+    """Create or append a Historical VaR/ES sheet to an Excel workbook."""
+    return _export_sheet(
+        "Historical", path, prices, ticker, n_days, portfolio_value,
+        var_date, stressed, lookback, stress_start, stress_end, stress_label,
+        var_confidence, es_confidence,
+    )
+
+
+def export_parametric_var_sheet(
+    path: str,
+    prices: pd.Series,
+    ticker: str,
+    n_days: int,
+    portfolio_value: float,
+    var_date: pd.Timestamp | None = None,
+    stressed: bool = False,
+    lookback: int | None = None,
+    stress_start: str = "",
+    stress_end: str = "",
+    stress_label: str = "",
+    var_confidence: float = 0.99,
+    es_confidence: float = 0.975,
+) -> str:
+    """Create or append a Parametric VaR/ES sheet to an Excel workbook."""
+    return _export_sheet(
+        "Parametric", path, prices, ticker, n_days, portfolio_value,
+        var_date, stressed, lookback, stress_start, stress_end, stress_label,
+        var_confidence, es_confidence,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Report-level exports (output dir + both normal & stressed sheets)
+# ---------------------------------------------------------------------------
+
+
+def export_historical_var_report(
+    prices: pd.Series,
+    ticker: str,
+    n_days: int,
+    portfolio_value: float,
+    var_date: pd.Timestamp | None,
+    lookback: int,
+    stressed_prices: pd.Series,
+    stress_start: str,
+    stress_end: str,
+    stress_label: str,
+    var_confidence: float = 0.99,
+    es_confidence: float = 0.975,
+) -> str:
+    """Generate a full Historical VaR Excel report (normal + stressed sheets)."""
+    output_dir = make_output_dir()
+    date_str = var_date.strftime("%Y-%m-%d") if var_date else ""
+    excel_path = os.path.join(output_dir, f"{ticker}_{date_str}_Historical_VaR.xlsx")
+
+    export_historical_var_sheet(
+        path=excel_path, prices=prices, ticker=ticker, n_days=n_days,
+        portfolio_value=portfolio_value, var_date=var_date, stressed=False,
+        lookback=lookback, var_confidence=var_confidence, es_confidence=es_confidence,
+    )
+    export_historical_var_sheet(
+        path=excel_path, prices=stressed_prices, ticker=ticker, n_days=n_days,
+        portfolio_value=portfolio_value, var_date=var_date, stressed=True,
+        stress_start=stress_start, stress_end=stress_end, stress_label=stress_label,
+        var_confidence=var_confidence, es_confidence=es_confidence,
+    )
+    return excel_path
+
+
+def export_parametric_var_report(
+    prices: pd.Series,
+    ticker: str,
+    n_days: int,
+    portfolio_value: float,
+    var_date: pd.Timestamp | None,
+    lookback: int,
+    stressed_prices: pd.Series,
+    stress_start: str,
+    stress_end: str,
+    stress_label: str,
+    var_confidence: float = 0.99,
+    es_confidence: float = 0.975,
+) -> str:
+    """Generate a full Parametric VaR Excel report (normal + stressed sheets)."""
+    output_dir = make_output_dir()
+    date_str = var_date.strftime("%Y-%m-%d") if var_date else ""
+    excel_path = os.path.join(output_dir, f"{ticker}_{date_str}_Parametric_VaR.xlsx")
+
+    export_parametric_var_sheet(
+        path=excel_path, prices=prices, ticker=ticker, n_days=n_days,
+        portfolio_value=portfolio_value, var_date=var_date, stressed=False,
+        lookback=lookback, var_confidence=var_confidence, es_confidence=es_confidence,
+    )
+    export_parametric_var_sheet(
+        path=excel_path, prices=stressed_prices, ticker=ticker, n_days=n_days,
+        portfolio_value=portfolio_value, var_date=var_date, stressed=True,
+        stress_start=stress_start, stress_end=stress_end, stress_label=stress_label,
+        var_confidence=var_confidence, es_confidence=es_confidence,
+    )
+    return excel_path

src/historical.py

@@ -0,0 +1,168 @@
+"""
+historical_var.py -- Historical Value at Risk calculation and analysis pipeline.
+"""
+
+import numpy as np
+import pandas as pd
+from loguru import logger
+from src.utils import fetch_prices, compute_returns, plot_distribution
+from src.excel_export import export_historical_var_report
+
+
+def calculate_historical_var(returns: pd.Series, confidence: float) -> float:
+    """Return VaR as a positive loss value.
+
+    VaR = (1 - confidence) percentile of returns, negated to express as loss.
+    """
+    vals = returns.values
+    return -float(np.percentile(np.asarray(vals), (1.0 - confidence) * 100))
+
+
+def calculate_historical_es(returns: pd.Series, confidence: float) -> float:
+    """Return ES as a positive loss value.
+
+    ES = E[loss | loss > VaR], the mean of losses exceeding VaR.
+    """
+    var = calculate_historical_var(returns, confidence)
+    losses = -np.asarray(returns.values)
+    tail = losses[losses > var]
+    return float(np.mean(tail)) if len(tail) > 0 else var
+
+
+
+def compute_historical_var_es(
+    returns: pd.Series,
+    var_confidence: float,
+    es_confidence: float,
+    n_days: int,
+    portfolio_value: float,
+) -> dict:
+    """Compute VaR and ES from returns and scale to n-day horizon.
+
+    Returns a dict with 1-day and n-day dollar VaR and ES.
+    """
+    var_1d_pct = calculate_historical_var(returns, var_confidence)
+    es_1d_pct = calculate_historical_es(returns, es_confidence)
+    var_1d = var_1d_pct * portfolio_value
+    es_1d = es_1d_pct * portfolio_value
+
+    scaling_factor = np.sqrt(n_days)
+    var_nd = var_1d * scaling_factor
+    es_nd = es_1d * scaling_factor
+
+    return {
+        "var_1d": var_1d,
+        "var_nd": var_nd,
+        "es_1d": es_1d,
+        "es_nd": es_nd,
+    }
+
+
+def compute_stressed_historical_var_es(
+    ticker: str,
+    var_confidence: float,
+    es_confidence: float,
+    n_days: int,
+    portfolio_value: float,
+    stress_start: str,
+    stress_end: str,
+    stress_label: str,
+) -> dict:
+    """Compute Stressed Historical VaR and ES over a defined stress window."""
+    prices = fetch_prices(ticker, start_date=stress_start, end_date=stress_end)
+    daily_returns = compute_returns(prices, kind="arithmetic")
+
+    result = compute_historical_var_es(daily_returns, var_confidence, es_confidence, n_days, portfolio_value)
+
+    logger.info(
+        f"Stressed VaR: 1d=${result['var_1d']:,.2f}, {n_days}d=${result['var_nd']:,.2f} | "
+        f"Stressed ES: 1d=${result['es_1d']:,.2f}, {n_days}d=${result['es_nd']:,.2f}"
+    )
+
+    return {
+        **result,
+        "stress_start": stress_start,
+        "stress_end": stress_end,
+        "stress_label": stress_label,
+        "prices": prices,
+    }
+
+
+def historical_var_es_pipeline(
+    ticker: str,
+    var_confidence: float,
+    es_confidence: float,
+    lookback: int,
+    n_days: int,
+    portfolio_value: float,
+    end_date: pd.Timestamp | None = None,
+    stress_start: str = "2008-01-01",
+    stress_end: str = "2008-12-31",
+    stress_label: str = "Global Financial Crisis (2008)",
+):
+    """Execute the full Historical VaR pipeline.
+
+    Returns a dict with all computed results.
+    PnL and VaR values are expressed in dollars based on *portfolio_value*.
+    If end_date is None, defaults to current date.
+    """
+    # 1. Fetch data and compute returns
+    prices = fetch_prices(ticker, lookback, end_date)
+    daily_returns = compute_returns(prices, kind="arithmetic")
+
+    # 2. Compute normal VaR and ES
+    normal = compute_historical_var_es(
+        daily_returns, var_confidence, es_confidence, n_days, portfolio_value,
+    )
+
+    # 3. Compute Stressed VaR/ES
+    stressed = compute_stressed_historical_var_es(
+        ticker, var_confidence, es_confidence, n_days, portfolio_value,
+        stress_start, stress_end, stress_label,
+    )
+
+    # 4. Generate Excel report (normal + stressed sheets)
+    excel_path = export_historical_var_report(
+        prices=prices,
+        ticker=ticker,
+        n_days=n_days,
+        portfolio_value=portfolio_value,
+        var_date=end_date,
+        lookback=lookback,
+        stressed_prices=stressed["prices"],
+        stress_start=stressed["stress_start"],
+        stress_end=stressed["stress_end"],
+        stress_label=stressed["stress_label"],
+        var_confidence=var_confidence,
+        es_confidence=es_confidence,
+    )
+
+    # 5. Generate distribution plot
+    var_date_str = end_date.strftime("%Y-%m-%d") if end_date else ""
+    var_conf_pct = f"{var_confidence * 100:g}"
+    es_conf_pct = f"{es_confidence * 100:g}"
+    fig_dist = plot_distribution(
+        returns=daily_returns * portfolio_value,
+        var_cutoff=-normal["var_nd"],
+        var_label=f"VaR ({var_conf_pct}%, {n_days}d)",
+        es_cutoff=-normal["es_nd"],
+        es_label=f"ES ({es_conf_pct}%, {n_days}d)",
+        var_date=var_date_str,
+        method="Historical",
+        ticker=ticker,
+    )
+
+    logger.info(
+        f"VaR: 1d=${normal['var_1d']:,.2f}, {n_days}d=${normal['var_nd']:,.2f} | "
+        f"ES: 1d=${normal['es_1d']:,.2f}, {n_days}d=${normal['es_nd']:,.2f}"
+    )
+
+    return {
+        **normal,
+        "stressed_var_nd": stressed["var_nd"],
+        "stressed_es_nd": stressed["es_nd"],
+        "prices": prices,
+        "daily_returns": daily_returns,
+        "excel_path": excel_path,
+        "fig_dist": fig_dist,
+    }

src/logger.py

@@ -0,0 +1,37 @@
+"""
+logger.py -- Centralized loguru configuration.
+
+Import this module once (in app.py) to activate console + file sinks.
+All other modules just do `from loguru import logger` directly.
+"""
+
+import sys
+from pathlib import Path
+
+from loguru import logger
+
+# Project root = parent of src/
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+LOG_DIR = PROJECT_ROOT / "log"
+LOG_FILE = LOG_DIR / "var_engine.log"
+
+# Remove default stderr handler
+logger.remove()
+
+# Colored console output (INFO+)
+logger.add(
+    sys.stderr,
+    level="INFO",
+    colorize=True,
+    format="<green>{time:HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan> - <level>{message}</level>",
+)
+
+# Single rotating file (DEBUG+)
+LOG_DIR.mkdir(parents=True, exist_ok=True)
+logger.add(
+    str(LOG_FILE),
+    level="INFO",
+    rotation="10 MB",
+    retention="30 days",
+    format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}",
+)

src/parametric.py

@@ -0,0 +1,183 @@
+"""
+parametric_var.py -- Parametric (Variance-Covariance) Value at Risk calculation and analysis pipeline.
+"""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+from loguru import logger
+from src.utils import fetch_prices, compute_returns, plot_distribution
+from src.excel_export import export_parametric_var_report
+
+
+def estimate_distribution(returns: pd.Series) -> tuple[float, float]:
+    """Estimate mean and standard deviation of daily returns.
+
+    Uses an unbiased sample standard deviation (ddof=1).
+    Returns (mu, sigma).
+    """
+    mu = float(returns.mean())
+    sigma = float(returns.std(ddof=1))
+    return mu, sigma
+
+
+def calculate_parametric_var(returns: pd.Series, confidence: float) -> float:
+    """Return VaR as a positive loss value using the normal model.
+
+    VaR = -(mu - z * sigma)   where z = norm.ppf(confidence).
+    """
+    mu, sigma = estimate_distribution(returns)
+    z = float(stats.norm.ppf(confidence))
+    return -(mu - z * sigma)
+
+
+def calculate_parametric_es(returns: pd.Series, confidence: float) -> float:
+    """Return ES as a positive loss value using the normal model.
+
+    ES = -(mu - sigma * phi(z) / (1 - confidence)).
+    """
+    mu, sigma = estimate_distribution(returns)
+    z = float(stats.norm.ppf(confidence))
+    alpha = 1.0 - confidence
+    return -(mu - sigma * float(stats.norm.pdf(z)) / alpha)
+
+
+
+def compute_parametric_var_es(
+    returns: pd.Series,
+    var_confidence: float,
+    es_confidence: float,
+    n_days: int,
+    portfolio_value: float,
+) -> dict:
+    """Compute VaR and ES from returns and scale to n-day horizon.
+
+    Returns a dict with 1-day and n-day dollar VaR and ES.
+    """
+    var_1d_pct = calculate_parametric_var(returns, var_confidence)
+    es_1d_pct = calculate_parametric_es(returns, es_confidence)
+    var_1d = var_1d_pct * portfolio_value
+    es_1d = es_1d_pct * portfolio_value
+
+    scaling_factor = np.sqrt(n_days)
+    var_nd = var_1d * scaling_factor
+    es_nd = es_1d * scaling_factor
+
+    return {
+        "var_1d": var_1d,
+        "var_nd": var_nd,
+        "es_1d": es_1d,
+        "es_nd": es_nd,
+    }
+
+
+def compute_stressed_parametric_var_es(
+    ticker: str,
+    var_confidence: float,
+    es_confidence: float,
+    n_days: int,
+    portfolio_value: float,
+    stress_start: str,
+    stress_end: str,
+    stress_label: str,
+) -> dict:
+    """Compute Stressed Parametric VaR and ES over a defined stress window."""
+    prices = fetch_prices(ticker, start_date=stress_start, end_date=stress_end)
+    daily_returns = compute_returns(prices, kind="log")
+    result = compute_parametric_var_es(daily_returns, var_confidence, es_confidence, n_days, portfolio_value)
+
+    logger.info(
+        f"Stressed Parametric VaR: 1d=${result['var_1d']:,.2f}, {n_days}d=${result['var_nd']:,.2f} | "
+        f"Stressed ES: 1d=${result['es_1d']:,.2f}, {n_days}d=${result['es_nd']:,.2f}"
+    )
+
+    return {
+        **result,
+        "stress_start": stress_start,
+        "stress_end": stress_end,
+        "stress_label": stress_label,
+        "prices": prices,
+    }
+
+
+def parametric_var_es_pipeline(
+    ticker: str,
+    var_confidence: float,
+    es_confidence: float,
+    lookback: int,
+    n_days: int,
+    portfolio_value: float,
+    end_date: pd.Timestamp | None = None,
+    stress_start: str = "2008-01-01",
+    stress_end: str = "2008-12-31",
+    stress_label: str = "Global Financial Crisis (2008)",
+):
+    """Execute the full Parametric VaR pipeline.
+
+    Returns a dict with all computed results.
+    VaR and ES values are expressed as positive dollar losses based on *portfolio_value*.
+    If end_date is None, defaults to the last business day.
+    """
+    # 1. Fetch data and compute returns
+    prices = fetch_prices(ticker, lookback, end_date)
+    daily_returns = compute_returns(prices, kind="log")
+    mu, sigma = estimate_distribution(daily_returns)
+
+    # 2. Compute normal VaR and ES
+    normal = compute_parametric_var_es(
+        daily_returns, var_confidence, es_confidence, n_days, portfolio_value,
+    )
+
+    # 3. Compute Stressed VaR/ES
+    stressed = compute_stressed_parametric_var_es(
+        ticker, var_confidence, es_confidence, n_days, portfolio_value,
+        stress_start, stress_end, stress_label,
+    )
+
+    # 4. Generate Excel report (normal + stressed sheets)
+    excel_path = export_parametric_var_report(
+        prices=prices,
+        ticker=ticker,
+        n_days=n_days,
+        portfolio_value=portfolio_value,
+        var_date=end_date,
+        lookback=lookback,
+        stressed_prices=stressed["prices"],
+        stress_start=stressed["stress_start"],
+        stress_end=stressed["stress_end"],
+        stress_label=stressed["stress_label"],
+        var_confidence=var_confidence,
+        es_confidence=es_confidence,
+    )
+
+    # 5. Generate distribution plot
+    var_date_str = end_date.strftime("%Y-%m-%d") if end_date else ""
+    var_conf_pct = f"{var_confidence * 100:g}"
+    es_conf_pct = f"{es_confidence * 100:g}"
+    fig_dist = plot_distribution(
+        returns=daily_returns * portfolio_value,
+        var_cutoff=-normal["var_nd"],
+        var_label=f"VaR ({var_conf_pct}%, {n_days}d)",
+        es_cutoff=-normal["es_nd"],
+        es_label=f"ES ({es_conf_pct}%, {n_days}d)",
+        var_date=var_date_str,
+        method="Parametric",
+        ticker=ticker,
+    )
+
+    logger.info(
+        f"Parametric VaR: 1d=${normal['var_1d']:,.2f}, {n_days}d=${normal['var_nd']:,.2f} | "
+        f"ES: 1d=${normal['es_1d']:,.2f}, {n_days}d=${normal['es_nd']:,.2f}"
+    )
+
+    return {
+        **normal,
+        "stressed_var_nd": stressed["var_nd"],
+        "stressed_es_nd": stressed["es_nd"],
+        "prices": prices,
+        "daily_returns": daily_returns,
+        "mu": mu,
+        "sigma": sigma,
+        "excel_path": excel_path,
+        "fig_dist": fig_dist,
+    }

src/utils.py

@@ -0,0 +1,240 @@
+"""
+utils.py -- Shared utilities: data fetching, return computation, and plotting.
+"""
+
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+import yfinance as yf
+from loguru import logger
+
+
+def fetch_prices(
+    ticker: str,
+    lookback: int | None = None,
+    var_date: pd.Timestamp | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> pd.Series:
+    """Download close prices for *ticker*.
+
+    Two modes of operation:
+
+    **Lookback mode** (default):  Supply *lookback* and optionally *var_date*.
+    Fetches the last *lookback* trading days ending before *var_date*.
+
+    **Date-range mode**:  Supply *start_date* and *end_date* (YYYY-MM-DD strings).
+    Fetches all trading days in that window, plus one prior day so the
+    first daily return falls on or near *start_date*.
+    """
+    if start_date and end_date:
+        # Date-range mode (stress periods)
+        start = pd.to_datetime(start_date) - pd.Timedelta(days=10)
+        end = pd.to_datetime(end_date) + pd.Timedelta(days=1)  # yfinance 'end' is exclusive
+
+        logger.debug(
+            f"Fetching {ticker}: {start.strftime('%Y-%m-%d')} to {end_date}"
+        )
+
+        try:
+            df = yf.download(
+                ticker,
+                start=start.strftime("%Y-%m-%d"),
+                end=end.strftime("%Y-%m-%d"),
+                progress=False,
+                interval="1d",
+                auto_adjust=True,
+            )
+        except Exception:
+            raise ValueError(
+                f"No data returned for ticker '{ticker}' ({start_date} to {end_date})."
+            )
+        if not isinstance(df, pd.DataFrame) or df.empty:
+            raise ValueError(
+                f"No data returned for ticker '{ticker}' ({start_date} to {end_date})."
+            )
+
+        prices = pd.Series(df["Close"].squeeze())
+        prices.name = ticker
+
+        # Trim to one trading day before start_date through end_date
+        start_ts = pd.to_datetime(start_date)
+        start_idx = prices.index.searchsorted(start_ts)
+        start_idx = max(0, start_idx - 1)
+        prices = prices.iloc[start_idx:]
+        prices = prices.loc[:end_date]
+
+        logger.info(
+            f"Fetched {len(prices)} trading days for {ticker} "
+            f"({prices.index[0].strftime('%Y-%m-%d')} to {prices.index[-1].strftime('%Y-%m-%d')})"
+        )
+        return prices
+
+    # Lookback mode (historical VaR)
+    if var_date is None:
+        var_date = pd.Timestamp((pd.Timestamp.today() - pd.offsets.BDay()).date())
+    
+    if lookback is None:
+        raise ValueError("lookback is required when start_date/end_date are not provided.")
+    calendar_days = int(lookback * 1.6)
+    # yfinance 'end' is exclusive, so passing var_date fetches up to the day before
+    start = var_date - pd.Timedelta(days=calendar_days)
+    logger.debug(
+        f"Fetching {ticker}: {start.strftime('%Y-%m-%d')} to {var_date.strftime('%Y-%m-%d')} (lookback={lookback})"
+    )
+
+    try:
+        df = yf.download(
+            ticker,
+            start=start.strftime("%Y-%m-%d"),
+            end=var_date.strftime("%Y-%m-%d"),
+            progress=False,
+            interval="1d",
+            auto_adjust=True
+        )
+    except Exception:
+        raise ValueError(f"No data returned for ticker '{ticker}'.")
+    if not isinstance(df, pd.DataFrame) or df.empty:
+        raise ValueError(f"No data returned for ticker '{ticker}'.")
+
+    prices = pd.Series(df["Close"].squeeze())
+    prices.name = ticker
+    result = prices.tail(lookback)
+    logger.info(
+        f"Fetched {len(result)} trading days for {ticker} (last date: {result.index[-1].strftime('%Y-%m-%d')})"
+    )
+    return result
+
+
+# ------------------------------------------------------------------
+# Return computation
+# ------------------------------------------------------------------
+
+
+def compute_returns(prices: pd.Series, kind: str = "arithmetic") -> pd.Series:
+    """Compute daily returns from a price series.
+
+    Parameters
+    ----------
+    kind : "arithmetic" or "log"
+        arithmetic  ->  (P_t - P_{t-1}) / P_{t-1}
+        log         ->  log(P_t) - log(P_{t-1})
+    """
+    if kind == "log":
+        log_prices = pd.Series(np.log(prices))
+        returns = log_prices - log_prices.shift(1)
+        name = "Daily Log Return"
+    else:
+        returns = (prices - prices.shift(1)) / prices.shift(1)
+        name = "Daily Return"
+    returns = pd.Series(returns, name=name)
+    return returns.dropna()
+
+
+
+# ------------------------------------------------------------------
+# Plotting (Plotly)
+# ------------------------------------------------------------------
+
+
+def plot_distribution(
+    returns: pd.Series,
+    var_cutoff: float,
+    var_label: str = "VaR",
+    es_cutoff: float | None = None,
+    es_label: str = "ES",
+    var_date: str = "",
+    method: str = "",
+    ticker: str = "",
+) -> go.Figure:
+    """Return a histogram of the daily P&L distribution highlighting VaR and ES tail risk."""
+    fig = go.Figure()
+
+    # Split the distribution at the VaR cutoff (P&L below VaR are in the left tail)
+    normal_returns = returns[returns >= var_cutoff]
+    tail_returns = returns[returns < var_cutoff]
+
+    fig.add_trace(
+        go.Histogram(
+            x=normal_returns.values,
+            marker_color="steelblue",
+            opacity=0.8,
+        )
+    )
+    fig.add_trace(
+        go.Histogram(
+            x=tail_returns.values,
+            marker_color="darkorange",
+            opacity=0.8,
+        )
+    )
+
+    if var_cutoff is not None:
+        fig.add_vline(x=var_cutoff, line_width=1.5, line_dash="dot", line_color="black")
+        fig.add_annotation(
+            x=var_cutoff, xref="x",
+            y=0.5, yref="paper",
+            text=f"{var_label}<br>= ${abs(var_cutoff):,.2f}",
+            xanchor="left", yanchor="middle",
+            xshift=6,
+            showarrow=False,
+            font=dict(size=9, color="#444444"),
+        )
+
+    if es_cutoff is not None:
+        fig.add_vline(x=es_cutoff, line_width=1.5, line_dash="dash", line_color="darkred")
+        fig.add_annotation(
+            x=es_cutoff, xref="x",
+            y=0.5, yref="paper",
+            text=f"{es_label}<br>= ${abs(es_cutoff):,.2f}",
+            xanchor="right", yanchor="middle",
+            xshift=-6,
+            showarrow=False,
+            font=dict(size=9, color="darkred"),
+        )
+
+    title = "Daily Portfolio P&L Distribution with VaR & ES Thresholds"
+
+    fig.update_layout(
+        title=dict(text=title, font=dict(size=14)),
+        xaxis_title=dict(text="P&L ($)", font=dict(size=12)),
+        yaxis_title=dict(text="Frequency", font=dict(size=12)),
+        barmode="stack",
+        template="plotly_white",
+        yaxis=dict(showgrid=False),
+        margin=dict(t=80, b=40),
+        height=392.5,
+        showlegend=False,
+    )
+
+    if var_date:
+        fig.add_annotation(
+            text=f"VaR Date: {var_date}",
+            xref="paper", yref="paper",
+            x=1.08, y=1.22,
+            xanchor="right", yanchor="top",
+            showarrow=False,
+            font=dict(size=9, color="#444444"),
+        )
+
+    if method:
+        fig.add_annotation(
+            text=f"Method: {method}",
+            xref="paper", yref="paper",
+            x=1.08, y=1.16,
+            xanchor="right", yanchor="top",
+            showarrow=False,
+            font=dict(size=9, color="#444444"),
+        )
+
+    if ticker:
+        fig.add_annotation(
+            text=f"Ticker: {ticker}",
+            xref="paper", yref="paper",
+            x=1.08, y=1.10,
+            xanchor="right", yanchor="top",
+            showarrow=False,
+            font=dict(size=9, color="#444444"),
+        )
+
+    return fig