palladium/README.md

# Palladium

**A library of master notebooks for consulting delivery** — workshop instruments and
business-case studies, built as Mercury-served Jupyter deliverables.

> *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 case no CFO can ignore.*

Every master obeys one **three-layer contract** (the always-on rules live in
[`CLAUDE.md`](CLAUDE.md)):

- **Mercury** is the polished, client-facing interface — the screen you share in a
  workshop, remote or in person.
- **Jupyter notebook cells** are the consultant's interface — workshop **content**
  and **client data** are edited in tagged cells, never in `.py` files.
- **Python modules** hold reusable logic and calculations worth calling as a module,
  typed and covered by validation tests.

## Taxonomy

| Kind | What it is | Naming | Lives |
|---|---|---|---|
| **Study** | Reproduction of a dated base document (Forrester TEI or similar), personalized as an overlay | `YYYYMM_TEI_Vendor_Product` / `YYYYMM_Client_Engagement` (dated) | `studies/` |
| **Assessment** | Reusable workshop instrument (discovery workshop, diagnostic) | `Instrument_Name` (undated, living) | `assessments/` |
| **Calculator** | Prices a vendor's product from that vendor's published rate card — verbatim anchor + client overlay | `Vendor_Subject_Calculator` (undated, living) | `calculators/` |
| **Engagement copy** | A master copied out for a client engagement — acquires client data, becomes **confidential** | `YYYYMM_Client_Instrument`, stamped at copy-time | **outside this repo** |

Masters in this repo stay **client-clean**: placeholder engagement data, published or
synthetic numbers, nothing a client said. Patterns:
[Assessment](docs/Assessment_Pattern_V1-00.md) ·
[Study](docs/Study_Pattern_V1-00.md) ·
[Calculator](docs/Calculator_Pattern_V1-00.md) ·
[shared Mercury mechanics](docs/Mercury_Notebook_Pattern_V1-00.md).

## Repository layout

```
palladium/
├── CLAUDE.md                          # the always-on contract (rubric, layers, risk tiers)
├── assessments/
│   ├── CX_Discovery_Workshop/         # ★ reference implementation (notebook-first model)
│   └── CX_AI_Diagnostic/              # capability diagnostic (pre-redesign: generated notebook)
├── calculators/
│   └── Genesys_Token_Calculator/      # ★ Genesys Cloud AI token cost — published rate card, 2026-07-12
├── studies/
│   ├── 202512_TEI_Genesys_CX_Cloud/   # Forrester TEI reproduction — NPV $10.8M · ROI 266%
│   ├── 202602_TEI_Amazon_Connect/     # Forrester TEI reproduction — NPV $78.7M · ROI 342%
│   └── 202607_CTM_GenesysCX/          # client engagement study (grandfathered — see CLAUDE.md)
├── template/MercuryNotebook/          # copy-me scaffold (py-engine model; see "Adding a master")
├── docs/                              # the pattern docs, brand.md, review prompt, Athena reference
├── core/                              # shared Athena toolkit (masters do NOT import it)
├── tests/                             # core tests + the notebook structural suite (all masters)
├── 00_setup.ipynb                     # Athena credentials + connection (core layer)
└── Makefile                           # make setup / lab / test / check-notebooks
```

Each master is **self-contained**: its own engine package, venv, tests, Mercury
config, and export script — a copy of the directory runs standalone.

## Quick start — run a master

```bash
git clone ssh://git@git.helu.ca:22022/r/palladium.git && cd palladium

cd assessments/CX_Discovery_Workshop
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

mercury --working-dir .              # the stage — share this screen with the client
jupyter lab                          # backstage — edit content/data cells, see the script
pytest                               # content + engagement + engine pins
python scripts/export_report.py      # exports/*.html + LLM-ready *.md
```

Every master's README carries its own specifics; the commands are the same shape in
all of them.

## Client engagements — copy out, never in place

A master never touches client data. To run one for a client (full checklist in the
[Assessment Pattern](docs/Assessment_Pattern_V1-00.md)):

1. **Copy** the master directory out of Palladium to your engagement location.
2. **Rename** it `YYYYMM_Client_Instrument` (e.g. `202608_Acme_CX_Discovery`).
3. **Provision** a fresh venv there (`pip install -e ".[dev]"` — copied venvs are broken).
4. **Fill the `engagement-data` cell** with the client facts.
5. **Verify** — `pytest` + the headless gate stay green by design.

The copy is now **confidential**: it lives with the engagement, never merges back.
Improvements found on engagements are hand-carried to the master as clean edits.
`.gitignore` blocks client documents repo-wide — see `CLAUDE.md` § Confidentiality.

## Validation

Two mechanisms guard every master:

**Deterministic** — per master (in its venv): engine pins, content pins read from the
notebook's tagged cells, the stage/backstage test, and the in-notebook verification
gate under headless `nbconvert --execute`. Repo-wide (root venv):
`make check-notebooks` runs the kernel-free structural suite over every committed
notebook — parses, cleanly executed, tag taxonomy present ([tests/nbcheck.py](tests/nbcheck.py)
classifies every notebook; grandfathered ones skip with a recorded reason).

**LLM review** — [`docs/Notebook_Review_Prompt_V1-00.md`](docs/Notebook_Review_Prompt_V1-00.md)
hunts what deterministic checks can't: content oddities, cross-cell rot, stale
numbers, stage leakage. Run it in-repo with `/review-notebook <path>` (Claude Code),
or paste the prompt into any LLM alongside the `.ipynb` JSON.

## Adding a new master

For an **Assessment**, start from the reference implementation and its pattern doc —
`assessments/CX_Discovery_Workshop/` + [Assessment Pattern](docs/Assessment_Pattern_V1-00.md).
For a **Study**, copy `template/MercuryNotebook/` and follow the
[Study Pattern](docs/Study_Pattern_V1-00.md) (note: the template still encodes the
py-engine model; its notebook-first rework is a recorded follow-up). For a
**Calculator**, start from `calculators/Genesys_Token_Calculator/` +
[Calculator Pattern](docs/Calculator_Pattern_V1-00.md). Any of them:
underscores in names (never dashes — directories are Python packages), and register
the new notebook in [tests/nbcheck.py](tests/nbcheck.py) — the completeness test
fails until you classify it.

## Athena / core (the TEI toolkit)

The `core/` package talks to [Athena](https://athena.nttdata.com) for
client/opportunity context and server-side TEI tooling — masters do **not** import
it. Start at **`00_setup.ipynb`** (`make setup && make lab`): it prompts for the API
key, writes `.env`, and tests the connection (current target:
`https://athena.ouranos.helu.ca`, the Ouranos sandbox).

```bash
python -m palladium test | list | reports | summary <id> | calculate <id> | export <id> -o export.json
```

The export JSON feeds the report pipeline: **Palladium → Peitho (LLM → HTML) →
html2docx → .docx**. Full API reference, object model, calculation logic, and the
Palladium↔Athena methodology bridges: [`docs/Athena_TEI.md`](docs/Athena_TEI.md) +
[`docs/Athena API.yaml`](docs/Athena%20API.yaml). Root tests (`make test`) cover the
client (mocked HTTP), the financial math, the export envelope — and the notebook
structural suite.

## 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 |