Update README.md
This commit is contained in:
351
README.md
351
README.md
@@ -1,9 +1,344 @@
|
||||
# palladium
|
||||
# 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 |
|
||||
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user