Imported from ryan-webster-vt/webstar (AGENTS.md). Install upstream with npx skills add ryan-webster-vt/webstar. Copyright stays with the author.

AGENTS.md

Daily NCAA MBB rankings pipeline (Python 3.11+, PyMC). Entry point is scripts/daily_pipeline.py; it reads/writes season data in AWS S3 and feeds the static site app/index.html (S3 + CloudFront). Runs daily on EC2 via Docker.

Note: the README architecture section is stale — it references main.py and scrape_data.py, which no longer exist. Trust the code.

Commands

• Setup: pip install -e ".[dev]" (installs pytest/ruff). CBBpy installs from GitHub, so git must be on PATH; g++ enables faster PyTensor compilation.
• Run pipeline: python scripts/daily_pipeline.py
• Lint: ruff check . (line-length 100, target py311)
• Tests: pytest — configured for tests/ with pythonpath = ["."], but no tests exist yet.
• Build/deploy Docker image: powershell scripts/push_to_ecr.ps1 [-PushLatest] — requires AWS CLI + Docker; auto-tags with git short SHA, appends -dirty-<timestamp> when the tree is dirty.

Pipeline order (matters)

daily_pipeline.py runs archive_game_results → scrape_data_v2 → execute_mcmc → scrape_todays_games → CloudFront invalidation. S3 is the source of truth for master_df.csv, current_rankings.csv, todays_games.csv, archived_results.csv; the data/*.csv files in the repo are local copies and are excluded from the Docker image. data/ncaa_teams.json is the canonical team list used to filter games and is baked into the image.

Environment

• .env at the repo root is loaded by daily_pipeline.py via python-dotenv; gitignored.
• WEBSTAR_S3_BUCKET — S3 data bucket (defaults to webstar-bucket).
• CF_DIST_ID — optional; CloudFront invalidation is skipped when unset.
• WEBSTAR_ROOT — repo-root override used in Docker.
• BEARER_TOKEN — CFBD API key, used by notebooks/cfb/.
• AWS credentials via the standard boto3 chain.

Conventions and gotchas

• Scripts in scripts/ use dual imports (from runtime_utils import ... with a scripts.-prefixed fallback) so they work run directly or as package modules — preserve this pattern.
• Resolve repo-relative paths with resolve_repo_path() from scripts/runtime_utils.py (honors WEBSTAR_ROOT), never hardcoded relative paths. Docker runs with WORKDIR /app/scripts.
• scrape_data_v2.py dedupes on game_id/team/opp_team, so re-running on the same day is safe.
• "Yesterday" is computed in America/New_York.
• execute_mcmc.py refits the full PyMC model over the season — expect it to take minutes.
• Normalize team names with normalize_team_name from utils/clean_names.py before joining team-keyed data; raw scraped names don't match data/ncaa_teams.json.
• notebooks/mbb/ holds exploration notebooks behind the scripts; notebooks/cfb/ and the empty scripts/cfb/ are early college-football work.
• .env and opencode.json are intentionally gitignored; never commit them.