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):

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 · Study · Calculator · shared Mercury mechanics.

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

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):

Copy the master directory out of Palladium to your engagement location.
Rename it YYYYMM_Client_Instrument (e.g. 202608_Acme_CX_Discovery).
Provision a fresh venv there (pip install -e ".[dev]" — copied venvs are broken).
Fill the engagement-data cell with the client facts.
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 classifies every notebook; grandfathered ones skip with a recorded reason).

LLM review — 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. For a Study, copy template/MercuryNotebook/ and follow the Study Pattern (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. Any of them: underscores in names (never dashes — directories are Python packages), and register the new notebook in tests/nbcheck.py — the completeness test fails until you classify it.

Athena / core (the TEI toolkit)

The core/ package talks to Athena 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).

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 API.yaml. Root tests (make test) cover the client (mocked HTTP), the financial math, the export envelope — and the notebook structural suite.

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

7.8 KiB Raw Blame History