palladium/README.md

Palladium

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

Palladium is a Jupyter notebook-based calculator and Streamlit application 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                                              │
│                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────┐ │
│  │  Notebooks   │    │  Streamlit   │    │  Export    │ │
│  │  (Analysis)  │    │  (Data Entry)│    │  (Report)  │ │
│  └──────┬───────┘    └──────┬───────┘    └─────┬─────┘ │
│         │                   │                   │       │
│         └───────────┬───────┘                   │       │
│                     ▼                           │       │
│           ┌──────────────────┐                  │       │
│           │   TEI Client     │                  │       │
│           │   (API Layer)    │──────────────────┘       │
│           └────────┬─────────┘                          │
└────────────────────┼────────────────────────────────────┘
                     │
                     ▼
              ┌─────────────┐         ┌──────────────────┐
              │   Athena    │         │  Report Pipeline │
              │   (API)     │         │  (html2docx)     │
              └─────────────┘         └──────────────────┘

Components

Component	Purpose
TEI Client	Python API client for Athena's TEI endpoints
Calculations	Financial logic — NPV, ROI, payback, risk adjustment
Notebooks	Interactive analysis — benefits, costs, business case
Streamlit App	Data entry UI with version management
Export	Structured JSON for the LLM report generation pipeline

---

Quick Start

Prerequisites

• Python 3.11+
• Access to Athena API (API key required)
• Jupyter Lab or VS Code with notebook support

Installation

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

Configuration

Copy the environment template and add your credentials:

cp .env.example .env

# .env
ATHENA_BASE_URL=https://athena.nttdata.com
ATHENA_API_KEY=your-api-key-here

Verify Connection

python -m palladium test

Or in a notebook:

from tei_client import TEIClient

client = TEIClient()
result = client.test_connection()
print(result)  # {'status': 'ok', 'authenticated': True, ...}

---

Usage

Jupyter Notebooks

The primary workflow for TEI analysis:

jupyter lab notebooks/

Notebook	Purpose
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
04_export.ipynb	Generate report-ready JSON for html2docx pipeline

Streamlit Application

Interactive UI for data entry and version management:

streamlit run app/main.py

CLI

# Test connection
python -m palladium test

# List TEI instances
python -m palladium list

# Show financial summary
python -m palladium summary <public_id>

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

---

TEI Methodology

Palladium implements the Forrester TEI™ framework [1]:

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.

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

Scenario Analysis

Three scenarios model uncertainty in adoption and realization:

Scenario	Approach
Conservative	Higher risk adjustments, lower adoption rates
Moderate	Balanced assumptions (base case)
Aggressive	Lower risk adjustments, faster adoption

---

Project Structure

palladium/
├── app/                        # Streamlit application
│   ├── main.py                 # App entry point
│   ├── pages/
│   │   ├── benefits.py         # Benefits data entry
│   │   ├── costs.py            # Costs data entry
│   │   ├── summary.py          # Financial summary dashboard
│   │   └── versions.py         # Version history & comparison
│   └── components/
│       ├── charts.py           # Visualization components
│       └── tables.py           # Data table components
├── notebooks/                  # Jupyter analysis notebooks
│   ├── 01_benefits.ipynb
│   ├── 02_costs.ipynb
│   ├── 03_business_case.ipynb
│   └── 04_export.ipynb
├── tei_client/                 # Athena API client
│   ├── __init__.py
│   ├── client.py               # HTTP client with auth
│   └── models.py               # Response data models
├── calculations/               # Financial calculation engine
│   ├── __init__.py
│   ├── npv.py                  # Net present value
│   ├── roi.py                  # Return on investment
│   ├── payback.py              # Payback period
│   └── scenarios.py            # Scenario multipliers
├── export/                     # Report pipeline export
│   ├── __init__.py
│   └── report_data.py          # JSON export for html2docx
├── tests/
│   ├── test_client.py
│   ├── test_calculations.py
│   └── test_export.py
├── .env.example
├── .gitignore
├── 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

Endpoint	Purpose
GET /forge/api/tei/reports/	List available TEI model templates
GET /forge/api/tei/reports/{id}/fields/	Get field definitions for a model
POST /forge/api/tei/tools/	Create new TEI instance
GET /forge/api/tei/tools/{public_id}/	Get instance metadata
GET /forge/api/tei/tools/{public_id}/values/	Get current field values
PUT /forge/api/tei/tools/{public_id}/values/	Bulk update values
POST /forge/api/tei/tools/{public_id}/calculate/	Trigger calculation
GET /forge/api/tei/tools/{public_id}/summary/	Get financial summary
POST /forge/api/tei/tools/{public_id}/versions/	Save version snapshot
GET /forge/api/tei/tools/{public_id}/export/	Export for report pipeline

Authentication

Authorization: Api-Key {your-api-key}

API keys are provisioned in Athena's admin interface per user/service account.

---

Report Pipeline Integration

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

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

The export JSON includes:

• All benefit categories with risk-adjusted values
• All cost categories with yearly breakdown
• Financial summary (NPV, ROI, payback)
• Yearly cash flow data (for waterfall/bar charts)
• Scenario analysis results (conservative/moderate/aggressive)
• Metadata (client, opportunity, analysis period, discount rate)

---

Version Management

Palladium manages version history through the Streamlit UI:

1. Save Version — Snapshots current values + financial summary with a descriptive note
2. View History — See all versions with headline metrics (NPV, ROI)
3. Compare Versions — Side-by-side diff showing what changed 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

Code Style

ruff check .
ruff format .

Adding a New Benefit Category

1. Define the field in Athena's TEI Model admin (field name, type, category, defaults)
2. The field automatically appears in Palladium via the API
3. Update notebook analysis if category-specific logic is needed
4. Update export mapping if the report template expects specific structure

---

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