Robert Helewka
c187bde188
Replace Streamlit and JupyterLab commands with Mercury for serving interactive notebooks as web apps. Update README to reflect new architecture where notebooks are the primary deliverables, utilizing Mercury input widgets for live client tuning. Add export_report.py script to generate LLM-readable HTML/Markdown reports from the notebooks. Update corrected business case notebook to include Mercury dependency and usage instructions.
98 lines
4.3 KiB
Markdown
98 lines
4.3 KiB
Markdown
# CTM Token Calculator
|
||
|
||
**Genesys AI Token Cost & Business Case Calculator** — interactive,
|
||
defensible modeling of Genesys Cloud **CX 3** platform + AI feature costs
|
||
against realistic benefit scenarios, replacing single-point vendor ROI
|
||
outputs with sensitivity-aware **Floor / Realistic / Stretch** analysis.
|
||
|
||
> ⚠️ **Planning tool.** Uses published Genesys list rates unless overridden —
|
||
> explicitly not a replacement for contractual pricing. No Genesys API
|
||
> integration; this is a forward-looking model, not a production-consumption
|
||
> dashboard.
|
||
|
||
## CTM context
|
||
|
||
- 9 sites (NAM, EMEA, AUZ, 6× APAC), **2,088 contracted named users**
|
||
- NAM volumes from CTM discovery; **all other site data is estimated —
|
||
confirm with CTM** (flagged throughout the UI)
|
||
- Cost takeouts include the NICE IEX (NAM) retirement placeholder ($1.3M/yr,
|
||
estimated)
|
||
- Every meter carries a confidence flag: 🟢 confirmed (published rate) ·
|
||
🟡 estimated · 🔴 unknown (working default, rate not yet sourced)
|
||
|
||
## Install & run
|
||
|
||
```bash
|
||
cd ctm-token-calculator
|
||
python -m venv .venv && source .venv/bin/activate
|
||
pip install -e ".[app,notebook,dev]"
|
||
|
||
# Serve the notebooks as interactive web apps (Mercury)
|
||
mercury --working-dir notebooks/
|
||
|
||
# Or work on them directly in JupyterLab
|
||
jupyter lab notebooks/
|
||
|
||
# Export the corrected business case as LLM-readable report sources
|
||
# (exports/*.html for review, exports/*.md for feeding an LLM)
|
||
python scripts/export_report.py
|
||
|
||
# Tests
|
||
pytest
|
||
```
|
||
|
||
## Architecture
|
||
|
||
**The notebooks are the deliverables.** All math lives in the pure-Python
|
||
`tokencalc/` library; the notebooks are thin presentation layers over it.
|
||
[Mercury](https://runmercury.com) serves them as interactive web apps — the
|
||
`mercury` input widgets in `ctm_business_case_corrected.ipynb` let you tune
|
||
contract values, termination dates, token assumptions, and implementation
|
||
pricing live for a client, and headless runs (nbconvert, the section-10 regression
|
||
gate) simply use the widget defaults. `scripts/export_report.py` executes the
|
||
notebook and writes HTML + markdown to `exports/`; the notebook's section-12
|
||
machine-readable appendix carries every number behind the figures so an LLM
|
||
can draft the client report from the export.
|
||
|
||
| Notebook | Purpose |
|
||
|---|---|
|
||
| `notebooks/ctm_business_case_corrected.ipynb` | Client-facing corrected business case (Mercury-interactive) |
|
||
| `notebooks/ctm_token_calculator.ipynb` | Full token-cost / scenario workbench |
|
||
|
||
| Module | Purpose |
|
||
|---|---|
|
||
| `meters.py` | Token meter + pricing dataclasses, confidence enum |
|
||
| `defaults.py` | Genesys meter catalogue, CTM sites/takeouts/phasing, CX 3 rate ($111.28/user/mo) |
|
||
| `inputs.py` | Validated input dataclasses (sites, feature scopes, takeouts) |
|
||
| `scenarios.py` | Floor/Realistic/Stretch + benefit params (Genesys claim vs pressure-tested) |
|
||
| `cost_model.py` | Platform, per-user AI, consumption AI cost engines |
|
||
| `benefit_model.py` | AHT/ACW/email/deflection/STA benefit engines |
|
||
| `business_case.py` | 3-year P&L, NPV @ 8%, payback, ROI |
|
||
| `exports.py` | Multi-sheet Excel, CSV, JSON scenario save/load |
|
||
|
||
### Correctness rules encoded in the model
|
||
|
||
1. **Agent Copilot covers Supervisor AI Summary** — AI Summary & Insights is
|
||
never billed at sites where Copilot is enabled (Copilot's 40 tokens/user/mo
|
||
includes summarization). Implemented and tested.
|
||
2. **Billing-style rounding** — monthly consumption token totals are rounded
|
||
up (`ceil`) per site before pricing; per-user totals are exact.
|
||
3. **Regional pricing** — every site resolves its token rate through its
|
||
pricing region (US/EU/AU/APAC); nothing is hardcoded to US.
|
||
4. **Adoption ramp** — consumption features ramp (default Y1 = 70%); per-user
|
||
licences are paid in full from their phase year. Phasing is per-site,
|
||
per-feature, per-phase (1/2/3/off).
|
||
|
||
### Verified reference numbers
|
||
|
||
- STA: 2,088 users × 30 tokens × 12 × $1 = **$751,680** ✓ (test)
|
||
- Agent Copilot: 2,088 × 40 × 12 × $1 = **$1,002,240** ✓ (test)
|
||
- NPV hand-check: 100/yr × 3 @ 8% = 257.710 ✓ (test)
|
||
|
||
## Auditability
|
||
|
||
Every number traces to an input and a meter: cost rows carry the feature,
|
||
scope (sites), and confidence; benefit rows carry the driver line and scope;
|
||
the Excel export includes input, meter, cost-detail, benefit-detail, business
|
||
case, and three-scenario comparison sheets.
|