01
Ingest engine & adapters
Get real usage data from anywhere into one clean shape without losing or duplicating a row.
Six interchangeable sources cover every operating mode: seeded mocks for reproducible demos, key-free parsers for console-exported JSON so operators without admin credentials can feed it real spend today, and paginated live API adapters for hands-free pulls.
Why it matters
- Every row validated against a 17-column canonical schema before touching the store
- Bad rows land in a reject ledger with reasons; strict mode raises one diagnostic listing all of them
- Re-ingesting restates rather than duplicates, so scheduled re-pulls can never double-count
- Duplicate IDs with differing token counts fail immediately instead of vanishing silently
02
Canonical schema & rate card
One definition of a usage record and one source of prices, shared by everything.
The schema keeps billed and computed cost side by side: what the provider charged, and what the toolkit computed from published prices. The rate card holds effective-dated pricing for both providers plus the USD-to-GBP reference, so no currency rate is ever hardcoded.
Why it matters
- Two independent cost fields turn every ingest into an ongoing audit
- A price change overnight, or a parsing bug, exposes itself as drift between the fields
- Unknown models raise instead of costing $0, killing the classic silent budget leak
- Cross-field validators enforce timestamp ordering and flag source-versus-derived mismatch over $1
03
Forecast & budget tracker
Know mid-month whether each client will finish over budget.
Per client: month-to-date spend, projected month-end, budget consumed, projected percentage and an over-pace flag. Money renders as $1,202.50 (£949.98), the GBP reference sourced from the rate card, never a literal.
Why it matters
- Projects over active days, not calendar days: a client starting on the 20th is judged fairly
- The projected overage figure is carried verbatim into the actions layer, one chain of custody
- No downstream recomputation that could drift from the source number
04
Back-test replay
Prove the forecast is actually any good.
Replays the projection at day 7, 14, 21 and 28 using only data available up to each checkpoint, then scores every projection against the realised month-end actual.
Why it matters
- Anyone can ship a straight-line forecast; this measures how its error shrinks through the month
- Zero data leakage by construction, so the score is honest
- Part of a wider habit: claims are measured, not asserted
05
Spend explorer & Command Centre
One self-contained HTML page answering "where is the money going?" at a glance.
KPIs, daily trend, breakdowns by client, model and key, period deltas, efficiency views and a budget panel render into a single file. No server, no build step: data embedded as JSON, charts from a pinned CDN, opens in any browser.
Why it matters
- Chart.js pinned with a Subresource Integrity hash, so a compromised CDN cannot inject scripts
- Secrets reported as presence-only booleans; values structurally cannot reach the page
- Colour-blind-safe palette with labels too, so meaning never rides on colour alone
- Every figure carries its period and unit; indicative prices are stated plainly
06
Anomaly detector
Surface genuine spend spikes without crying wolf.
Scans daily cost series per scope: total, project, model family or API key. An alert fires only when a day clears both gates: at least 3 standard deviations above baseline AND at least $50 above it.
Why it matters
- Leave-one-out baseline: the day under test is excluded from its own statistics, so a spike cannot mask itself
- Dual conditions kill the false-positive machine where tiny-variance series flag $3 Tuesdays
- Survivors rank by magnitude with baseline, deviation and z-score attached
07
Automated insight report
Turn the whole data layer into a briefing read in ninety seconds.
A TL;DR-first Markdown report weaving provenance, headline KPIs, drivers, anomalies, forecast versus budget and costed recommendations from a pluggable advisor registry. It classifies its own sources in plain English so demo data can never masquerade as real spend.
Why it matters
- Pure and deterministic: same store renders byte-identical output, no wall clock anywhere
- That property lets 204 tests pin exact figures and catch regressions to the cent
- It is what makes the Monday 08:03 automated delivery trustworthy
08
Actions layer
Close the loop from signal to recommended action.
A stateless deriver converts report signals into ranked actions, each carrying estimated dollar impact, confidence, caveats and a declarative done-check describing how a human would verify completion. When nothing clears the impact floor it says so explicitly.
Why it matters
- Most analytics stop at a chart; this stops at what to do, what it is worth, how to check it worked
- Impact figures copied verbatim from their source signal, never recomputed
- Deliberately advisory: execution needs a state store, deferred honestly rather than faked