345 lines
11 KiB
Markdown
345 lines
11 KiB
Markdown
# 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](https://athena.nttdata.com) 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
|
||
|
||
```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
|
||
```
|
||
|
||
### Configuration
|
||
|
||
Copy the environment template and add your credentials:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
```bash
|
||
# .env
|
||
ATHENA_BASE_URL=https://athena.nttdata.com
|
||
ATHENA_API_KEY=your-api-key-here
|
||
```
|
||
|
||
### Verify Connection
|
||
|
||
```bash
|
||
python -m palladium test
|
||
```
|
||
|
||
Or in a notebook:
|
||
|
||
```python
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
streamlit run app/main.py
|
||
```
|
||
|
||
### CLI
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
pytest tests/ -v
|
||
```
|
||
|
||
### Code Style
|
||
|
||
```bash
|
||
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 |
|
||
|