diff --git a/README.md b/README.md index 2043b2e..826fcce 100644 --- a/README.md +++ b/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 + +# Export for report pipeline +python -m palladium export -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.* \ No newline at end of file