How an oil analyst uses EnergyScope

Pick data

Any of 2.8M series via search, key_series, or get_data. No schema lock-in — compose whatever metrics matter to your desk.

Build the snapshot

A flat metrics dict with the keys your analysis cares about. Reuse canonical keys (crack_321_z, cushing_z, bwet_z, ...) or add your own — the signal layer tolerates 57 input-key aliases out of the box.

Run the narrative layer

derived_signals(metrics=snapshot) returns 52 scored signals + 16 trade-thesis contradictions + 7 theme summaries + the dominant lens. Same engine that powers our presets.

Draft the HTML

Your agent writes the prose; the signal output does the analytical work. Contradictions ARE the headlines — the report scaffolds itself from the firing set.

Persist and publish

save_report_run(name, html, snapshot, prompt, publish=True) saves the run for future diffs AND mirrors the redacted, chrome-wrapped HTML to /reports/{name}.html. Next run, compare_runs() writes the "what changed" section automatically.

Without EnergyScope

• 30+ manual API calls per report
• Copy-paste from EIA website into Excel
• Hand-code Chart.js for every visualisation
• No seasonal context — "stocks at 462mb" means nothing alone
• In-sample R² cited as forecast quality (misleading)
• CFTC positioning reported as raw numbers without percentile
• Crude grades impossible to find in 2.8M series
• Hand-written "changes since last report" — often skipped or stale because there's no clear baseline to diff against
• No composable signal layer — tools run in isolation, outputs don't talk to each other, analyst stitches them together in prose
• Hours per report. Multiple tools. Manual orchestration.

With EnergyScope

• 1 call per report — preset + watchlist
• Seconds, not hours — ~15s for a desk brief, ~30s for the quarterly
• SVG charts generated inline for reports
• Seasonal context — "+7,267 vs 5yr avg, 60th pctl"
• Honest backtest — skill vs naive, not overfit R²
• Percentile rank on positioning, stocks, spreads, grades
• 15+ crude grades in the grades preset — LLS, Mars, WTS, Saudi Light landed, Mexican Mayan FOB, plus historical series (vintages documented inline so you know what's current)
• 52 scored signals → 16 contradictions → one regime label. The narrative layer composes raw metrics into headlines. No more "stocks at 462mb, what does it mean?" — the platform says freight_extreme (z=7.92), supply_shock_signature, regime: HORMUZ_CRISIS.
• "Changes since last brief" auto-generated from compare_runs() signal diff — score deltas, contradiction transitions, categorical regime shifts. Not hand-written.
• Regime detection before the cause is public. On April 9, the platform flagged a supply-shock constellation (5 contradictions firing). On April 14, IEA's OMR revealed the Strait of Hormuz had been closed since Feb 28. The platform identified the what 5 days before the why was public. Case study →
• Natural language. Your AI agent runs the analytics.