Palladium

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 for data persistence, performs financial calculations (NPV, ROI, payback period), and exports structured data for the report generation pipeline.

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/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                                             │
└──────────────────────────────────────────────────────────────────┘

Components

Component	Purpose
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: the notebook is the artifact — self-contained study package, Mercury-served, gate-verified, LLM-exportable. Start from template/MercuryNotebook/. The Streamlit app/ path is retired by that pattern; existing TEI studies migrate to it.

---

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.

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 notebook, setup is one import:

from core.bootstrap import init

pal = init(study="202512_GenesysCX")       # loads .env, connects, imports study
pal.client.list_reports()
pal.seed_data.BENEFITS

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
# 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:

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.

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:

streamlit run app/main.py

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

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.

---

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 / 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
│   ├── calculations/                  # Pure-python financial math
│   │   ├── npv.py
│   │   ├── roi.py
│   │   ├── payback.py
│   │   └── 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
│   ├── 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/                             # 50 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

Palladium manages version history through both the API and the Streamlit UI:

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
streamlit	≥1.30	Data entry application
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