feat: add setup notebook and update env example for Athena
This commit is contained in:
77
README.md
77
README.md
@@ -46,53 +46,61 @@ Palladium is a Jupyter notebook + Streamlit toolkit for building Total Economic
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
## Quick Start — Jupyter Lab first
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- Access to Athena API (API key required)
|
||||
- Jupyter Lab or VS Code with notebook support
|
||||
|
||||
### Installation
|
||||
Palladium is a **Jupyter Lab-first** environment. Everything starts from a
|
||||
notebook; the Streamlit app and CLI are companions, not prerequisites.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/nttdata/palladium.git
|
||||
cd palladium
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
make setup # venv + deps + editable install (one time)
|
||||
make lab # launches Jupyter Lab
|
||||
```
|
||||
|
||||
Then open **`00_setup.ipynb`** at the repo root. It will:
|
||||
|
||||
1. Prompt for your Athena API key (hidden input) and save it to `.env`
|
||||
2. Test the connection
|
||||
3. Show what report templates and tools exist in the instance
|
||||
|
||||
Current target instance: **https://athena.ouranos.helu.ca** (Ouranos sandbox —
|
||||
no production data, safe to experiment).
|
||||
|
||||
From any notebook, setup is one import:
|
||||
|
||||
```python
|
||||
from core.bootstrap import init
|
||||
|
||||
pal = init(study="202602_AmazonConnect") # loads .env, connects, imports study
|
||||
pal.client.list_reports()
|
||||
pal.seed_data.BENEFITS
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Copy the environment template and add your credentials:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
All credentials and IDs live in `<repo>/.env` (gitignored). `00_setup.ipynb`
|
||||
writes it for you; to do it by hand:
|
||||
|
||||
```bash
|
||||
# .env
|
||||
ATHENA_BASE_URL=https://athena.nttdata.com
|
||||
ATHENA_BASE_URL=https://athena.ouranos.helu.ca
|
||||
ATHENA_API_KEY=your-api-key-here
|
||||
# written by the provisioning notebook:
|
||||
PALLADIUM_REPORT_PUBLIC_ID=...
|
||||
PALLADIUM_TOOL_PUBLIC_ID=...
|
||||
PALLADIUM_PROPOSAL_ID=... # or PALLADIUM_ENGAGEMENT_ID — a TEI tool
|
||||
# attaches to exactly one of the two
|
||||
```
|
||||
|
||||
### Verify Connection
|
||||
|
||||
In a notebook: `init()` prints the connection status. From a shell:
|
||||
|
||||
```bash
|
||||
python -m palladium test
|
||||
```
|
||||
|
||||
Or in Python:
|
||||
|
||||
```python
|
||||
from core.tei_client import TEIClient
|
||||
|
||||
client = TEIClient()
|
||||
print(client.test_connection()) # {'status': 'ok', 'authenticated': True, ...}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
@@ -103,11 +111,12 @@ Each study lives in `studies/<slug>/`. The reference study is the
|
||||
February 2026 Forrester *Total Economic Impact™ Of Amazon Connect*:
|
||||
|
||||
```bash
|
||||
jupyter lab studies/202602_AmazonConnect/notebooks/
|
||||
make lab # then browse to studies/202602_AmazonConnect/notebooks/
|
||||
```
|
||||
|
||||
| Notebook | Purpose |
|
||||
|----------|---------|
|
||||
| `00_provision.ipynb` | **Run first** — creates the report template + fields, lets you select the CRM client and the Proposal/Engagement to attach to (pulling the client's profile to avoid re-entry), creates the tool, seeds the published values, calculates, and verifies the totals |
|
||||
| `01_benefits.ipynb` | Quantify and risk-adjust benefit categories |
|
||||
| `02_costs.ipynb` | Document implementation and ongoing costs |
|
||||
| `03_business_case.ipynb` | Financial summary, scenario analysis, visualizations |
|
||||
@@ -228,7 +237,10 @@ Three scenarios model uncertainty in adoption and realization
|
||||
|
||||
```
|
||||
palladium/
|
||||
├── 00_setup.ipynb # ← START HERE: credentials + connection
|
||||
├── Makefile # make setup / lab / app / test
|
||||
├── core/ # Shared, study-agnostic Python package
|
||||
│ ├── bootstrap.py # one-import notebook setup (init, save_credentials)
|
||||
│ ├── tei_client/ # Athena API client
|
||||
│ │ ├── client.py # TEIClient with all /api/v1/tei/ methods
|
||||
│ │ └── models.py # Optional dataclasses for typed access
|
||||
@@ -257,6 +269,7 @@ palladium/
|
||||
│ ├── config.py # TOOL_PUBLIC_ID, REPORT_PUBLIC_ID
|
||||
│ ├── seed_data.py # 5 benefits + 3 costs from the PDF
|
||||
│ ├── notebooks/
|
||||
│ │ ├── 00_provision.ipynb # creates template+tool in Athena, seeds & verifies
|
||||
│ │ ├── 01_benefits.ipynb
|
||||
│ │ ├── 02_costs.ipynb
|
||||
│ │ ├── 03_business_case.ipynb
|
||||
@@ -322,6 +335,16 @@ Authorization: Api-Key {your-api-key}
|
||||
|
||||
API keys are provisioned in Athena's admin interface per user/service account.
|
||||
|
||||
### Methodology conventions (Palladium ↔ Athena)
|
||||
|
||||
Two places where the Forrester methodology and the Athena TEI API differ, and
|
||||
how Palladium bridges them:
|
||||
|
||||
| Topic | Athena behaviour | Palladium convention |
|
||||
|---|---|---|
|
||||
| **Cost risk adjustment** | Costs are never risk-adjusted server-side | Cost values are pushed pre-multiplied by `(1 + risk_adj)`; field-level adjustment stays 0 |
|
||||
| **Year-0 "Initial" costs** | No year-0 concept; non-annual values are folded into Year 1 | Each cost gets a companion non-annual `<key>_initial` field. `TEIClient` folds them back into an `initial` key on read. Athena discounts these as Year 1 (Forrester doesn't discount Year 0) — expect ≈0.15% drift on cost PV |
|
||||
|
||||
---
|
||||
|
||||
## Report Pipeline Integration
|
||||
|
||||
Reference in New Issue
Block a user