r/palladium
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Migrate Genesys CX Cloud TEI study to the pattern; retire Streamlit app

Browse Source 
studies/202512_GenesysCX -> studies/202512_TEI_Genesys_CX_Cloud,
rebuilt as pattern Variant 4 (TEI composite reproduction):

- teicalc/ self-contained engine: Forrester's tables as the never-edited
  verbatim anchor (incl. the p.14 typo note and the $0 AI-token line),
  generic model/scenarios/staging carried over from the Amazon Connect
  study, ClientDrivers overlay (agents / weekly interactions / revenue,
  flat composite so no growth re-base) with ai_tokens_annual as a direct
  input for the token line the published study models at $0
- one deliverable notebook (business_case.ipynb): widget-pair sidebar
  drivers incl. the AI-token price, published-vs-overlay KPI columns,
  cash-flow/waterfall/scenario charts, verification gate, backstage JSON
  data appendix
- gate + tests reproduce the published totals within $2: NPV $10.8M /
  ROI 266% (engine $10,783,466 / 265.79%; payback 3.3 months, not
  headlined in the PDF); 29 study tests, headless nbconvert green,
  stage simulation leak-free, exports carry the appendix
- old Athena workflow (00_provision..04_export, config.py, seed_data.py,
  PALLADIUM_GENESYSCX_* keys, ATHENA_EXPECTED reconciliation) deleted;
  git history preserves it

With the last legacy study migrated, the retirement lands too:
- app/ (Streamlit UI) and core/notebook_helpers deleted; nothing else
  imported them
- streamlit stripped from pyproject extras, requirements.txt, Makefile;
  .env.example reduced to the Athena keys; 00_setup.ipynb and
  core/bootstrap.py repointed at the pattern studies
- root README reworked: self-contained studies + slim core/ Athena
  toolkit (tei_client, calculations, export, cli)

All suites green: Genesys 29, Amazon Connect 27, CTM 55, template 7,
root 58.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Robert Helewka
2026-07-09 16:38:51 -04:00
parent a420af230b
commit e88449d15a
54 changed files with 8462 additions and 6427 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
README.md
View File

@@ -2,7 +2,7 @@
**TEI (Total Economic Impact) Calculator** — The strategic artifact that protects the business case.
Palladium is a Jupyter notebook + Streamlit toolkit for building Total Economic Impact analyses. It connects to [Athena](https://athena.nttdata.com) for data persistence, performs financial calculations (NPV, ROI, payback period), and exports structured data for the report generation pipeline.
Palladium is a Jupyter-notebook toolkit for building Total Economic Impact analyses. Each study is a self-contained Mercury-served notebook deliverable (math in a study package, verification gate, LLM-readable exports); a small shared `core/` talks to [Athena](https://athena.nttdata.com) for client/opportunity context and server-side TEI tooling.
> *In Greek mythology, the Palladium was a sacred artifact of Athena that protected Troy. Whoever possessed it held strategic advantage. In our ecosystem, Palladium protects the deal — transforming discovery inputs into a financial case no CFO can ignore.*
@@ -12,23 +12,17 @@ Palladium is a Jupyter notebook + Streamlit toolkit for building Total Economic
┌──────────────────────────────────────────────────────────────────┐
│ Palladium │
│ │
│ studies/202512_GenesysCX/ ← legacy study (this path) │
│ studies/YYYYMM_<Vendor>/ │
│ ├─ notebooks/ ─┐ │
│ ├─ seed_data.py │ │
│ └─ config.py │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ core/ │ ←─ │ app/ │ │
│ │ shared logic │ │ Streamlit │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ tei_client → ───────────────────► Athena API │
│ calculations │
│ export ──────────────────────────► export.json │
│ notebook_helpers │
│ cli │
│ studies/YYYYMM_TEI_Vendor_Product/ ← self-contained study │
│ studies/YYYYMM_Client_EngagementName/ (own venv + engine) │
│ ├─ <studylib>/ ← ALL math, verbatim anchors │
│ ├─ notebooks/ ← THE deliverable (Mercury-served) │
│ ├─ tests/ ← pinned acceptance numbers │
│ └─ exports/ ← .html/.md + JSON appendix (for LLMs, │
│ and the Athena repository roadmap) │
│ │
│ core/ ← shared Athena toolkit (studies do NOT import it) │
│ tei_client → ──────────────────────────► Athena API │
│ calculations · export · cli · bootstrap │
└──────────────────────────────────────────────────────────────────┘
```
@@ -36,26 +30,25 @@ Palladium is a Jupyter notebook + Streamlit toolkit for building Total Economic
| Component | Purpose |
|-----------|---------|
| **`studies/`** | One self-contained folder per engagement — own venv, engine package, Mercury notebook, tests, exports |
| **`template/`** | Copy-me study scaffold — start here for new studies |
| **`core/tei_client`** | Python API client for Athena's TEI endpoints |
| **`core/calculations`** | Financial logic — NPV, ROI, payback, risk adjustment, scenarios |
| **`core/export`** | Builds the structured JSON envelope consumed by the report pipeline |
| **`core/notebook_helpers`** | Pandas tables, Plotly charts, IPython display widgets |
| **`core/cli`** | `python -m palladium` command-line interface |
| **`app/`** | Streamlit data-entry UI with version management — *study-agnostic* |
| **`studies/`** | One folder per TEI engagement (notebooks, seed data, config, source PDF) |
| **`template/`** | Copy-me study templates — start here for new studies |
> **New studies follow the [Mercury Notebook Deliverable Pattern](docs/Mercury_Notebook_Pattern_V1-00.md)**:
> **All studies follow the [Mercury Notebook Deliverable Pattern](docs/Mercury_Notebook_Pattern_V1-00.md)**:
> the notebook *is* the artifact — self-contained study package, Mercury-served,
> gate-verified, LLM-exportable. Start from [`template/MercuryNotebook/`](template/MercuryNotebook/).
> The Streamlit `app/` path is retired by that pattern; existing TEI studies migrate to it.
> The Streamlit `app/` and `core/notebook_helpers` were retired when the last
> legacy study migrated (git history keeps them).
---
## Quick Start — Jupyter Lab first
Palladium is a **Jupyter Lab-first** environment. Everything starts from a
notebook; the Streamlit app and CLI are companions, not prerequisites.
notebook; the CLI is a companion, not a prerequisite.
```bash
git clone https://github.com/nttdata/palladium.git
@@ -73,14 +66,14 @@ Then open **`00_setup.ipynb`** at the repo root. It will:
Current target instance: **https://athena.ouranos.helu.ca** (Ouranos sandbox —
no production data, safe to experiment).
From any notebook, setup is one import:
From any root-level notebook, the Athena connection is one import (pattern
studies are self-contained and never import `core`):
```python
from core.bootstrap import init
pal = init(study="202512_GenesysCX") # loads .env, connects, imports study
pal = init() # loads .env, builds client, tests it
pal.client.list_reports()
pal.seed_data.BENEFITS
```
### Configuration
@@ -92,11 +85,6 @@ writes it for you; to do it by hand:
# .env
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
@@ -129,19 +117,11 @@ Its notebook reproduces the published totals within the PDF's rounding —
**NPV $78.7M • ROI 342% • Payback <6 months** — and the verification gate
asserts it on every headless run. See the study's README for details.
The remaining legacy study, `studies/202512_GenesysCX/`, still uses the
shared `core/` workflow (`make lab`, provision → push → calculate); it
migrates to the pattern next, after which `core/`'s notebook helpers and
`app/` retire.
### Streamlit application (study-agnostic)
Interactive UI for data entry and version management. Works for any TEI
study because field definitions come from Athena at runtime:
```bash
streamlit run app/main.py
```
`studies/202512_TEI_Genesys_CX_Cloud/` follows the same shape (**NPV $10.8M
• ROI 266%**), with one signature input: the Genesys AI Experience token
line the published study models at $0, priced live from the client's quote.
`studies/202607_CTM_GenesysCX/` is the full multi-notebook reference
implementation.
### CLI
@@ -171,9 +151,10 @@ python -m palladium export <public_id> -o export.json
pytest tests/ -v
```
50 tests cover the API client (mocked HTTP), the financial math, and the
export envelope shape. The Amazon Connect seed data is asserted against
the published Forrester totals.
The root suite covers the API client (mocked HTTP), the financial math, and
the export envelope shape; the Amazon Connect verbatim anchor is asserted
against the published Forrester totals. Each study additionally carries its
own pinned suite (`cd studies/<slug> && pytest`).
---
@@ -244,7 +225,7 @@ Three scenarios model uncertainty in adoption and realization
```
palladium/
├── 00_setup.ipynb # ← START HERE: credentials + connection
├── Makefile # make setup / lab / app / test
├── Makefile # make setup / lab / test
├── core/ # Shared, study-agnostic Python package
│ ├── bootstrap.py # one-import notebook setup (init, save_credentials)
│ ├── tei_client/ # Athena API client
@@ -257,25 +238,19 @@ palladium/
│ │ └── scenarios.py
│ ├── export/
│ │ └── report_data.py # JSON envelope for the report pipeline
│ ├── notebook_helpers/
│ │ ├── tables.py # Pandas dataframe builders
│ │ ├── charts.py # Plotly figures
│ │ └── display.py # IPython KPI cards, alerts
│ └── cli/
│ └── main.py # `python -m palladium ...`
├── palladium/ # CLI shim (just exposes `python -m palladium`)
│ └── __main__.py
├── app/ # Streamlit UI — works with any TEI study
│ ├── main.py # entry point
│ ├── views/ # benefits, costs, summary, versions (NOT `pages/` — avoids Streamlit auto-multipage)
│ └── components/ # tables, charts
├── template/
│ └── MercuryNotebook/ # copy-me pattern scaffold (runnable)
├── studies/ # One folder per engagement
│ ├── 202512_GenesysCX/ # CX Cloud TEI — legacy shared-core layout
│ │ ├── README.md # NPV $10.8M · ROI 266% + AI-token line
│ │ ├── config.py / seed_data.py # study-scoped PALLADIUM_GENESYSCX_* keys
│ │ └── notebooks/ # 00_provision, 01_business_case
├── studies/ # One self-contained folder per engagement
│ ├── 202512_TEI_Genesys_CX_Cloud/ # CX Cloud TEI — pattern Variant 4
│ │ ├── README.md # NPV $10.8M · ROI 266% + the $0 AI-token line
│ │ ├── teicalc/ # self-contained engine (anchor/model/overlay)
│ │ ├── notebooks/business_case.ipynb
│ │ ├── tests/ · scripts/ · config.toml · pyproject.toml
│ │ └── docs/ # Forrester PDF + Genesys token-metering notes
│ ├── 202602_TEI_Amazon_Connect/ # Amazon Connect TEI — pattern Variant 4
│ │ ├── README.md # NPV $78.7M · ROI 342%, reproduced + gated
│ │ ├── teicalc/ # self-contained engine (anchor/model/overlay)
@@ -285,7 +260,7 @@ palladium/
│ │ └── docs/
│ │ └── 202602_TEI Report Amazon Connect.pdf
│ └── 202607_CTM_GenesysCX/ # CTM × Genesys study — pattern reference impl
├── tests/ # 50 tests for core/
├── tests/ # root tests for core/
│ ├── test_client.py
│ ├── test_calculations.py
│ └── test_export.py
@@ -384,7 +359,8 @@ The export envelope (`core.export.build_report_data`) includes:
## Version Management
Palladium manages version history through both the API and the Streamlit UI:
Athena keeps version history for TEI tools, driven through the API
(`core.tei_client`: `save_version` / `list_versions` / `get_version`):
1. **Save Version** — Snapshots current values + summary with a descriptive note
2. **View History** — All versions with headline metrics (NPV, ROI)
@@ -435,7 +411,6 @@ ruff format .
| `requests` | ≥2.31 | HTTP client for Athena API |
| `python-dotenv` | ≥1.0 | Environment configuration |
| `jupyter` | ≥1.0 | Notebook environment |
| `streamlit` | ≥1.30 | Data entry application |
| `pandas` | ≥2.0 | Data manipulation |
| `plotly` | ≥5.18 | Interactive visualizations |
| `numpy` | ≥1.26 | Financial calculations |