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

Update README.md

Browse Source
This commit is contained in:
Robert Helewka
2026-05-20 23:37:52 +00:00
parent 4816abb8d0
commit a6f3ee3676
1 changed files with 343 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

339
README.md
View File

@@ -1,5 +1,3 @@
# palladium
# Palladium # Palladium
**TEI (Total Economic Impact) Calculator** — The strategic artifact that protects the business case. **TEI (Total Economic Impact) Calculator** — The strategic artifact that protects the business case.
@@ -7,3 +5,340 @@
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. 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.* > *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 |