El Niño Probability Tracker, V1.5
Internal weekly tracker for the 2026-27 El Niño peak. Generates a
markdown brief and analog chart each Monday, automated via GitHub
Actions.
This README is the operator's guide. Implementation context for Claude
Code lives in CLAUDE.md. Methodology lives in methodology.md
(maintained separately as a project doc).
What it produces
Each Monday, in briefs/YYYY-MM-DD/:
brief.md: 4-section structured brief with headline probability
buckets, physical state panel, analog tracker, and editorial layer.analog.png: 2026-27 ONI trajectory vs 1997-98, 2015-16, 2023-24.
And in snapshots/YYYY-MM-DD.json, a frozen copy of all input data
that produced that issue. This is what makes week-over-week comparisons
possible.
Quickstart
git clone <this repo>
cd eltracker
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python run_brief.py
This generates a brief using whatever's in sources.py (the V1
hand-curated seed values). It will work without any API keys.
To enable live fetching and AI-generated editorial layer:
export ANTHROPIC_API_KEY=sk-ant-...
# Configure CDS API for ECMWF/ERA5 (free, register at cds.climate.copernicus.eu):
cat > ~/.cdsapirc <<EOF
url: https://cds.climate.copernicus.eu/api
key: <your-uid>:<your-api-key>
EOF
chmod 600 ~/.cdsapirc
python run_brief.py
Deploy to GitHub Actions (the weekly automation)
- Push this repo to GitHub (private).
- Settings -> Secrets and variables -> Actions, add:
ANTHROPIC_API_KEY (required for the auto-generated editorial)CDS_API_KEY in format <UID>:<API-key> (required once ECMWF
and ERA5 fetchers are implemented)SMTP_HOST, SMTP_USER, SMTP_PASS, BRIEF_RECIPIENT (optional;
for emailing the brief). Without these the workflow still runs
and commits to the repo.
- Actions tab -> "Weekly El Nino brief" -> "Run workflow" once
manually to verify the scaffolding before trusting the cron.
- The cron runs Mondays 13:00 UTC after that. Adjust the schedule in
.github/workflows/weekly_brief.yml if needed.
What's auto-fetched vs hand-curated
As of this V1.5 scaffolding, all fetchers are stubs that fall back to
seed values in sources.py. The pipeline runs end-to-end but reads
from seeds, not the live web. To make it truly automated, implement
the fetchers in priority order (see HANDOVER.md).
The brief includes a "Source freshness" subsection in the editorial
layer that shows which sources were fetched live vs fell back. So you
can always tell at a glance whether a given week was fully automated
or not.
What you do each week
In the steady state (all fetchers implemented, cron running):
Nothing. The brief lands in your inbox Monday afternoon. You read
it, decide whether to edit the auto-generated Analyst Read paragraph,
and move on.
In the bootstrap state (fetchers still stubs):
Either run python run_brief.py locally Monday morning after manually
updating any changed fields in sources.py (V1 workflow), or skip
weeks until the fetchers are implemented enough to run unattended.
Methodology version stability
When you change anything that would shift headline numbers without an
underlying probability change (RONI offset, conversion math, bucket
definitions, analog event list), bump METHODOLOGY_VERSION in
sources.py. The next brief will surface the bump with a loud banner
so you know that week's numbers are not strictly comparable to last
week's.
Layout
sources.py Seed values, methodology constants
fetchers/ One module per data source
fetch_all.py Orchestrator
probs.py Probability harmonization
snapshot.py Snapshots and diffing
analog.py Chart generation
editorial.py Anthropic API call for analyst prose
run_brief.py Entry point
briefs/ Generated briefs
snapshots/ Input state per issue (audit trail)
.github/workflows/weekly_brief.yml
scripts/send_email.py
