{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "021ac129",
   "metadata": {},
   "source": [
    "# 🛡️ Palladium — Setup & Connection\n",
    "\n",
    "**Start here.** This notebook gets you from a fresh clone to a working Athena connection.\n",
    "\n",
    "| Where things live | |\n",
    "|---|---|\n",
    "| `00_setup.ipynb` | ← you are here: credentials + connection check |\n",
    "| `studies/<slug>/notebooks/` | the actual TEI work, numbered `00_provision` → `04_export` |\n",
    "| `core/` | shared logic (API client, financial math) — you rarely edit this |\n",
    "| `app/` | Streamlit data-entry UI: `make app` or `streamlit run app/main.py` |\n",
    "| `.env` | your Athena URL + API key (gitignored; created below) |\n",
    "\n",
    "Run cells top to bottom. Re-run any time — every step is idempotent."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "53fcc345",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Palladium(root='palladium', athena='not tested')"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Bootstrap — finds the repo root, loads .env, builds the API client.\n",
    "import sys, pathlib                       # path shim: works on a fresh kernel\n",
    "for _p in [pathlib.Path.cwd(), *pathlib.Path.cwd().parents]:\n",
    "    if (_p / \"pyproject.toml\").exists():\n",
    "        sys.path.insert(0, str(_p)); break\n",
    "\n",
    "from core.bootstrap import init, save_credentials\n",
    "\n",
    "pal = init(connect=False)\n",
    "pal"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ca43976",
   "metadata": {},
   "source": [
    "## 1 · Credentials\n",
    "\n",
    "Stored in `<repo>/.env` (gitignored). The cell below only prompts if no key is\n",
    "configured yet — paste the key at the prompt and it's saved for every future\n",
    "session, notebook, the CLI, and the Streamlit app.\n",
    "\n",
    "Current target: **https://athena.ouranos.helu.ca** (Ouranos sandbox — safe to experiment, no production data)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "853aaab8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "✅ Credentials already configured for https://athena.ouranos.helu.ca\n",
      "   (To rotate the key: save_credentials(api_key='new-key'))\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "from getpass import getpass\n",
    "\n",
    "if not os.getenv(\"ATHENA_API_KEY\"):\n",
    "    key = getpass(\"Athena API key (input hidden): \")\n",
    "    path = save_credentials(api_key=key)\n",
    "    print(f\"Saved → {path}\")\n",
    "else:\n",
    "    print(f\"✅ Credentials already configured for {os.getenv('ATHENA_BASE_URL')}\")\n",
    "    print(\"   (To rotate the key: save_credentials(api_key='new-key'))\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa7464fd",
   "metadata": {},
   "source": [
    "## 2 · Test the connection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "9b7fcc97",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "✅ Athena connected — https://athena.ouranos.helu.ca (0 report templates visible)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'status': 'ok',\n",
       " 'base_url': 'https://athena.ouranos.helu.ca',\n",
       " 'authenticated': True,\n",
       " 'reports_found': 0,\n",
       " 'timestamp': '2026-06-10T06:45:10.418874'}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pal = init()   # builds the client and pings /api/v1/tei/reports/\n",
    "client = pal.client\n",
    "pal.connection"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6877d6ae",
   "metadata": {},
   "source": [
    "## 3 · What's in this Athena instance?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "83edbe4d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "No TEI report templates yet — studies/202602_AmazonConnect/notebooks/00_provision.ipynb creates one.\n"
     ]
    }
   ],
   "source": [
    "import pandas as pd\n",
    "\n",
    "reports = client.list_reports()\n",
    "if reports:\n",
    "    display(pd.DataFrame(reports)[\n",
    "        [c for c in (\"id\", \"name\", \"vendor\", \"version\", \"status\",\n",
    "                     \"analysis_period_years\", \"discount_rate\",\n",
    "                     \"field_count\", \"instance_count\") if c in reports[0]]\n",
    "    ])\n",
    "else:\n",
    "    print(\"No TEI report templates yet — studies/202602_AmazonConnect/notebooks/00_provision.ipynb creates one.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "a247bedd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "No TEI tool instances yet.\n"
     ]
    }
   ],
   "source": [
    "tools = client.list_tools()\n",
    "if tools:\n",
    "    display(pd.DataFrame(tools)[\n",
    "        [c for c in (\"id\", \"name\", \"status\", \"current_version\") if c in tools[0]]\n",
    "    ])\n",
    "else:\n",
    "    print(\"No TEI tool instances yet.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33114d67",
   "metadata": {},
   "source": [
    "## Next steps\n",
    "\n",
    "1. **Provision the Amazon Connect study** → open\n",
    "   [`studies/202602_AmazonConnect/notebooks/00_provision.ipynb`](studies/202602_AmazonConnect/notebooks/00_provision.ipynb).\n",
    "   It creates the report template + fields in the sandbox, creates a tool,\n",
    "   seeds the Forrester values, calculates, and verifies the published totals\n",
    "   (NPV \\$78.7M · ROI 342% · payback <6 months).\n",
    "2. **Work the study** → notebooks `01_benefits` → `04_export` in the same folder.\n",
    "3. **Interactive data entry** → `make app` (or `streamlit run app/main.py`)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}