palladium/README.md

Palladium

TEI (Total Economic Impact) Calculator — The strategic artifact that protects the business case.

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 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.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│  Palladium                                                        │
│                                                                   │
│   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                   │
└──────────────────────────────────────────────────────────────────┘

Components

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/cli	python -m palladium command-line interface

All studies follow the Mercury Notebook Deliverable Pattern: the notebook is the artifact — self-contained study package, Mercury-served, gate-verified, LLM-exportable. Start from template/MercuryNotebook/. 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 CLI is a companion, not a prerequisite.

git clone https://github.com/nttdata/palladium.git
cd palladium
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 root-level notebook, the Athena connection is one import (pattern studies are self-contained and never import core):

from core.bootstrap import init

pal = init()                               # loads .env, builds client, tests it
pal.client.list_reports()

Configuration

All credentials and IDs live in <repo>/.env (gitignored). 00_setup.ipynb 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

Verify Connection

In a notebook: init() prints the connection status. From a shell:

python -m palladium test

---

Usage

Run a study end-to-end

Each new study is self-contained under the Mercury Notebook Deliverable Pattern. The reference TEI study is the February 2026 Forrester Total Economic Impact™ Of Amazon Connect (pattern Variant 4 — composite reproduction):

cd studies/202602_TEI_Amazon_Connect
python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
mercury --working-dir notebooks/     # serve the deliverable (the stage)
python scripts/export_report.py      # export .html/.md report sources

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.

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

# Test connection
python -m palladium test

# List TEI tool instances
python -m palladium list

# List available report templates
python -m palladium reports

# Show financial summary for a tool
python -m palladium summary <public_id>

# Trigger server-side recalculation
python -m palladium calculate <public_id>

# Export for the report pipeline
python -m palladium export <public_id> -o export.json

Tests

pytest tests/ -v

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).

---

Adding a new study

Copy the template, not an existing study:

cp -r template/MercuryNotebook studies/YYYYMM_TEI_Vendor_Product

Then follow template/MercuryNotebook/README.md: rename studylib/ to your study package (underscores only — dashes break Python imports), replace the toy model, re-pin the tests, rework the notebook. studies/202602_TEI_Amazon_Connect/ is the worked TEI example; studies/202607_CTM_GenesysCX/ is the full multi-notebook reference.

---

TEI Methodology

Palladium implements the Forrester TEI™ framework.

Benefit Categories

Benefits are quantified across categories, risk-adjusted, and discounted to present value:

Category	Examples
Cost Savings	Legacy license elimination, reduced headcount, lower telecom
Productivity	Reduced handle time, faster training, automated QA
Revenue	Improved retention, better conversion, new channel revenue
Risk Reduction	Compliance automation, reduced legal exposure, audit readiness

Risk Adjustment

Each benefit carries a risk-adjustment factor (0–50%) reflecting implementation uncertainty. A 20% risk adjustment on a $10M benefit yields a risk-adjusted value of $8M. Costs are risk-adjusted upward by the same factor (higher risk → higher modelled cost).

Financial Metrics

Metric	Description
NPV	Net Present Value — total risk-adjusted benefits minus costs, discounted
ROI	Return on Investment — (benefits − costs) / costs × 100
Payback	Months until cumulative benefits exceed cumulative costs

The initial investment (year 0) is not discounted. Year-N cashflows are discounted at the end of the year: PV = CF_n / (1 + r)^n. This matches the Forrester methodology used in the published studies.

Scenario Analysis

Three scenarios model uncertainty in adoption and realization (see core.calculations.SCENARIOS):

Scenario	Adoption	Risk delta	Effect
Conservative	80%	+10pp on benefits	Lower benefits, higher modelled cost
Moderate	100%	0	Base case (= published study)
Aggressive	115%	–5pp on benefits	Higher benefits, lower padding on cost

---

Project Structure

palladium/
├── 00_setup.ipynb                     # ← START HERE: credentials + connection
├── 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
│   │   ├── client.py                  # TEIClient with all /api/v1/tei/ methods
│   │   └── models.py                  # Optional dataclasses for typed access
│   ├── calculations/                  # Pure-python financial math
│   │   ├── npv.py
│   │   ├── roi.py
│   │   ├── payback.py
│   │   └── scenarios.py
│   ├── export/
│   │   └── report_data.py             # JSON envelope for the report pipeline
│   └── cli/
│       └── main.py                    # `python -m palladium ...`
├── palladium/                         # CLI shim (just exposes `python -m palladium`)
│   └── __main__.py
├── template/
│   └── MercuryNotebook/               # copy-me pattern scaffold (runnable)
├── 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)
│   │   ├── notebooks/business_case.ipynb
│   │   ├── tests/ · scripts/ · config.toml · pyproject.toml
│   │   ├── exports/                   # generated; .gitignored
│   │   └── docs/
│   │       └── 202602_TEI Report Amazon Connect.pdf
│   └── 202607_CTM_GenesysCX/          # CTM × Genesys study — pattern reference impl
├── tests/                             # root tests for core/
│   ├── test_client.py
│   ├── test_calculations.py
│   └── test_export.py
├── Athena API.yaml                    # OpenAPI reference
├── .env.example
├── requirements.txt
├── pyproject.toml
└── README.md

---

Athena Integration

Palladium connects to Athena's TEI module for data persistence and cross-tool reporting.

API Endpoints Used

All endpoints are under /api/v1/tei/ and require Authorization: Api-Key {key}.

Endpoint	Purpose
GET /api/v1/tei/reports/	List available TEI report templates
GET /api/v1/tei/reports/{public_id}/	Get a report template
GET /api/v1/tei/reports/{public_id}/fields/	Get field definitions for a template
POST /api/v1/tei/tools/	Create a new TEI tool instance
GET /api/v1/tei/tools/{public_id}/	Get instance metadata
PATCH /api/v1/tei/tools/{public_id}/	Update name/status
GET /api/v1/tei/tools/{public_id}/values/	Get current field values
PUT /api/v1/tei/tools/{public_id}/values/	Bulk-update values
PATCH /api/v1/tei/tools/{public_id}/values/{field_key}/	Patch a single value
POST /api/v1/tei/tools/{public_id}/calculate/	Trigger calculation
GET /api/v1/tei/tools/{public_id}/summary/	Get financial summary
GET /api/v1/tei/tools/{public_id}/versions/	List version snapshots
POST /api/v1/tei/tools/{public_id}/versions/	Save a new version
GET /api/v1/tei/tools/{public_id}/versions/{n}/	Get a specific version
GET /api/v1/tei/tools/{public_id}/export/	Export for the report pipeline
GET /api/v1/tei/summary/	Aggregate NPV across all tools

Object model

Athena object	Notes
Opportunity	Top-level sales record. Owns one or more Proposals.
Proposal	A specific bid/offer to a client. A TEI tool is linked to a Proposal.
Engagement	Optional — for active client engagements. A TEI tool may also link here.
TEIReport	Template (e.g. Amazon Connect 2026) — defines fields, discount rate, analysis horizon.
TEITool	Instance of a Report bound to a Proposal — holds values, summaries, versions.

Authentication

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

Palladium's export produces structured JSON consumed by the LLM report generation pipeline:

Palladium Export (JSON)
    │
    ▼
Peitho — LLM generates HTML (following HTML_DOCUMENT_FORMAT.md)
    │
    ▼
html2docx converts to native Word
    │
    ▼
Professional TEI Report (.docx)

The export envelope (core.export.build_report_data) includes:

• All benefit categories with risk-adjusted values
• All cost categories with yearly breakdown (and Initial column)
• Financial summary (NPV, ROI, payback, yearly cashflow)
• Conservative / moderate / aggressive scenario analysis
• Metadata (study slug, proposal, engagement, generator stamp)
• The raw Athena /export/ payload for reference

---

Version Management

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)
3. Compare Versions — Side-by-side diff of value changes between any two versions
4. Restore Version — Load a previous version's values as the current state

Version notes should capture:

• Assumptions made and their sources
• Which scenario the version represents
• What changed since the previous version
• Client confirmations or corrections

---

Development

Running Tests

pytest tests/ -v

Tests are designed to run without an Athena connection — HTTP is mocked and the calculation suite uses the Amazon Connect seed data to verify the Forrester numbers reproduce within rounding.

Code Style

ruff check .
ruff format .

Adding a New Benefit Category

1. Define the field in Athena's TEI Report admin (field name, type, category, defaults)
2. The field automatically appears in Palladium via the API — no client changes
3. Update notebook prose if category-specific commentary is needed
4. If the report template exposes a new structure, extend the envelope in core/export/report_data.py

---

Dependencies

Package	Version	Purpose
requests	≥2.31	HTTP client for Athena API
python-dotenv	≥1.0	Environment configuration
jupyter	≥1.0	Notebook environment
pandas	≥2.0	Data manipulation
plotly	≥5.18	Interactive visualizations
numpy	≥1.26	Financial calculations
pytest	≥7.4	Testing
ruff	≥0.1	Linting and formatting

---

Related Projects

Project	Relationship
Athena	Platform API — data persistence, cross-tool reporting
Peitho	Document generation — consumes Palladium's export JSON
html2docx	Converts LLM-generated HTML to native Word documents