{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "bb98a66f",
   "metadata": {},
   "source": [
    "# Telemetry History Analysis\n",
    "\n",
    "This notebook demonstrates how to consume the `history_summary.*` artefacts\n",
    "produced by continuous integration and extend the analysis locally."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b834641",
   "metadata": {},
   "source": [
    "## Load History Snapshot\n",
    "\n",
    "The `telemetry-report` artefact includes `history_summary.csv` and\n",
    "`history_summary.html`. We'll load the CSV and pivot the data for quick analysis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7ad14feb",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "import pandas as pd\n",
    "\n",
    "try:\n",
    "    import altair as alt\n",
    "except ImportError:\n",
    "    alt = None\n",
    "\n",
    "HISTORY_CSV = Path(\"docs/examples/analytics/data/tuner_reports/history_summary.csv\")\n",
    "if HISTORY_CSV.exists():\n",
    "    history = pd.read_csv(HISTORY_CSV)\n",
    "else:\n",
    "    # Fallback synthetic history if CI artefact not present locally\n",
    "    history = pd.DataFrame(\n",
    "        [\n",
    "            {\n",
    "                \"snapshot\": \"2024-11-10T000000Z\",\n",
    "                \"algorithm\": \"random\",\n",
    "                \"scenario\": \"SampleScenario\",\n",
    "                \"best_objective\": 6.2,\n",
    "                \"mean_objective\": 6.0,\n",
    "                \"runs\": 2,\n",
    "            },\n",
    "            {\n",
    "                \"snapshot\": \"2024-11-11T000000Z\",\n",
    "                \"algorithm\": \"random\",\n",
    "                \"scenario\": \"SampleScenario\",\n",
    "                \"best_objective\": 6.8,\n",
    "                \"mean_objective\": 6.4,\n",
    "                \"runs\": 2,\n",
    "            },\n",
    "            {\n",
    "                \"snapshot\": \"2024-11-12T000000Z\",\n",
    "                \"algorithm\": \"grid\",\n",
    "                \"scenario\": \"SampleScenario\",\n",
    "                \"best_objective\": 7.1,\n",
    "                \"mean_objective\": 6.8,\n",
    "                \"runs\": 2,\n",
    "            },\n",
    "            {\n",
    "                \"snapshot\": \"2024-11-13T000000Z\",\n",
    "                \"algorithm\": \"grid\",\n",
    "                \"scenario\": \"SampleScenario\",\n",
    "                \"best_objective\": 7.5,\n",
    "                \"mean_objective\": 7.1,\n",
    "                \"runs\": 2,\n",
    "            },\n",
    "        ]\n",
    "    )\n",
    "history"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d97fd99c",
   "metadata": {},
   "source": [
    "## Compute Deltas\n",
    "We can compute day-over-day improvements for each algorithm/scenario pair."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0996d73f",
   "metadata": {},
   "outputs": [],
   "source": [
    "history = history.sort_values([\"scenario\", \"algorithm\", \"snapshot\"]).reset_index(drop=True)\n",
    "history[\"best_delta\"] = history.groupby([\"scenario\", \"algorithm\"])[\"best_objective\"].diff()\n",
    "history"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bbca084e",
   "metadata": {},
   "source": [
    "## Visualize Trends\n",
    "Use Altair to plot the best objective trend per scenario."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c1a4acde",
   "metadata": {},
   "outputs": [],
   "source": [
    "if alt is None or history.empty:\n",
    "    display(\n",
    "        \"Altair not installed or no data available; install `altair` or supply reports to render the chart.\"\n",
    "    )\n",
    "else:\n",
    "    value_columns = [\"best_objective\"]\n",
    "    value_columns += [\n",
    "        c\n",
    "        for c in [\n",
    "            \"best_total_production\",\n",
    "            \"best_mobilisation_cost\",\n",
    "            \"best_utilisation_ratio_shift\",\n",
    "            \"best_utilisation_ratio_day\",\n",
    "            \"best_downtime_hours\",\n",
    "            \"best_weather_severity\",\n",
    "        ]\n",
    "        if c in history.columns\n",
    "    ]\n",
    "    chart_df = history.melt(\n",
    "        id_vars=[\"snapshot\", \"algorithm\", \"scenario\"],\n",
    "        value_vars=value_columns,\n",
    "        var_name=\"metric\",\n",
    "        value_name=\"value\",\n",
    "    )\n",
    "    metric_labels = {\n",
    "        \"best_objective\": \"Best Objective\",\n",
    "        \"best_total_production\": \"Total Production\",\n",
    "        \"best_mobilisation_cost\": \"Mobilisation Cost\",\n",
    "        \"best_utilisation_ratio_shift\": \"Utilisation (Shift)\",\n",
    "        \"best_utilisation_ratio_day\": \"Utilisation (Day)\",\n",
    "        \"best_downtime_hours\": \"Downtime Hours\",\n",
    "        \"best_weather_severity\": \"Weather Severity\",\n",
    "    }\n",
    "    chart_df[\"metric_label\"] = chart_df[\"metric\"].map(metric_labels).fillna(chart_df[\"metric\"])\n",
    "    chart = (\n",
    "        alt.Chart(chart_df)\n",
    "        .mark_line(point=True)\n",
    "        .encode(\n",
    "            x=\"snapshot:N\",\n",
    "            y=\"value:Q\",\n",
    "            color=\"algorithm:N\",\n",
    "            column=alt.Column(\"metric_label:N\", title=\"Metric\"),\n",
    "            row=\"scenario:N\",\n",
    "        )\n",
    "    )\n",
    "    chart"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec315b42",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "- Merge med42 or regression scenario reports into the history before comparing.\n",
    "- Use run-level telemetry (from `runs.sqlite`) to inspect KPI deltas for each snapshot."
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 5
}