palladium/00_setup.ipynb

{
 "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>/` | self-contained pattern studies (own venv, engine, Mercury notebook) |\n| `core/` | shared logic (API client, financial math) — you rarely edit this |\n| `.env` | your Athena URL + API key (gitignored; created below) |\n\nRun cells top to bottom. Re-run any time — every step is idempotent."
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "53fcc345",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Palladium(root='palladium', athena='not tested')"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": "# Bootstrap — finds the repo root, loads .env, builds the API client.\nimport sys, pathlib                       # path shim: works on a fresh kernel\nfor _p in [pathlib.Path.cwd(), *pathlib.Path.cwd().parents]:\n    if (_p / \"pyproject.toml\").exists():\n        sys.path.insert(0, str(_p)); break\n\nfrom core.bootstrap import init, save_credentials\n\npal = init(connect=False)\npal"
  },
  {
   "cell_type": "markdown",
   "id": "7ca43976",
   "metadata": {},
   "source": "## 1 · Credentials\n\nStored in `<repo>/.env` (gitignored). The cell below only prompts if no key is\nconfigured yet — paste the key at the prompt and it's saved for every future\nsession, notebook, the CLI, and the Streamlit app.\n\nCurrent target: **https://athena.ouranos.helu.ca** (Ouranos sandbox — safe to experiment, no production data)."
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "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\nfrom getpass import getpass\n\nif 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}\")\nelse:\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": 8,
   "id": "9b7fcc97",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "✅ Athena connected — https://athena.ouranos.helu.ca (1 report templates visible)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'status': 'ok',\n",
       " 'base_url': 'https://athena.ouranos.helu.ca',\n",
       " 'authenticated': True,\n",
       " 'reports_found': 1,\n",
       " 'timestamp': '2026-06-10T07:08:06.947037'}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": "pal = init()   # builds the client and pings /api/v1/tei/reports/\nclient = pal.client\npal.connection"
  },
  {
   "cell_type": "markdown",
   "id": "6877d6ae",
   "metadata": {},
   "source": "## 3 · What's in this Athena instance?"
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "83edbe4d",
   "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></th>\n",
       "      <th>id</th>\n",
       "      <th>name</th>\n",
       "      <th>vendor</th>\n",
       "      <th>version</th>\n",
       "      <th>status</th>\n",
       "      <th>analysis_period_years</th>\n",
       "      <th>discount_rate</th>\n",
       "      <th>field_count</th>\n",
       "      <th>instance_count</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>xsUTbjh4iDnJ</td>\n",
       "      <td>Amazon Connect 2026</td>\n",
       "      <td>AWS</td>\n",
       "      <td>1.0</td>\n",
       "      <td>active</td>\n",
       "      <td>3</td>\n",
       "      <td>0.1000</td>\n",
       "      <td>11</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "             id                 name vendor version  status  \\\n",
       "0  xsUTbjh4iDnJ  Amazon Connect 2026    AWS     1.0  active   \n",
       "\n",
       "   analysis_period_years discount_rate  field_count  instance_count  \n",
       "0                      3        0.1000           11               0  "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": "import pandas as pd\n\nreports = client.list_reports()\nif 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    ])\nelse:\n    print(\"No TEI report templates yet.\")"
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "a247bedd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "No TEI tool instances yet.\n"
     ]
    }
   ],
   "source": "tools = client.list_tools()\nif tools:\n    display(pd.DataFrame(tools)[\n        [c for c in (\"id\", \"name\", \"status\", \"current_version\") if c in tools[0]]\n    ])\nelse:\n    print(\"No TEI tool instances yet.\")"
  },
  {
   "cell_type": "markdown",
   "id": "33114d67",
   "metadata": {},
   "source": "## Next steps\n\n1. **Open a study** — each `studies/<slug>/` is self-contained (own venv +\n   engine + verification gate): see its README, e.g.\n   [`studies/202602_TEI_Amazon_Connect/`](studies/202602_TEI_Amazon_Connect/README.md)\n   (NPV \\$78.7M · ROI 342%) or\n   [`studies/202512_TEI_Genesys_CX_Cloud/`](studies/202512_TEI_Genesys_CX_Cloud/README.md)\n   (NPV \\$10.8M · ROI 266%).\n2. **Serve a deliverable** → `mercury --working-dir notebooks/` from the study root.\n3. **Start a new study** → copy `template/MercuryNotebook/` per the\n   [pattern](docs/Mercury_Notebook_Pattern_V1-00.md)."
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d20d824f-e464-4ff7-8191-10c2495842a0",
   "metadata": {},
   "outputs": [],
   "source": ""
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "630ee935-7c7b-47e5-9c13-6285316823e2",
   "metadata": {},
   "outputs": [],
   "source": ""
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7eba3877-8e51-443f-9953-9d0a48425f9f",
   "metadata": {},
   "outputs": [],
   "source": ""
  }
 ],
 "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
}