agents.md

# AGENTS.md

Guidance for AI coding agents working in this repository.

## What this repo is

Frontend code for the TabArena leaderboard, deployed as a Gradio app on a Hugging Face Space. The leaderboard ranks tabular ML models across tasks, splits, and dataset subsets.

- Entrypoint: `main.py` (Gradio app; HF Space runs it via the `app_file` declared in `README.md` frontmatter).
- UI text and copy: `website_texts.py`.
- Static constants (e.g. model-type emoji map): `constants.py`.
- Precomputed artifacts (CSVs + zipped PNGs): `data/imputation_{no,yes}/splits_{...}/tasks_{...}/datasets_{...}/`.
- Python: requires 3.12+. Dependencies pinned via `pyproject.toml`.

## Local dev

```bash
pip install -e ".[dev]"   # or: uv pip install -r pyproject.toml
python main.py            # launches the Gradio app
```

## Data pipeline (not regenerated in this repo)

Leaderboard data is produced upstream and dropped into `data/`:

1. Run `run_generate_website_artifacts.py` in the autogluon/tabarena repo.
2. Clear the local `data/` directory.
3. Unzip `clean_website_artifacts.zip` into `data/`.

Do not edit files under `data/` by hand — they are generated artifacts.

## Architecture notes

- `LBMatrix` (in `main.py`) enumerates the leaderboard variants along four axes: `imputation`, `splits`, `tasks`, `datasets`. The first element of each list is the default selection for that axis — changing list order changes both the default tab and the rendering order.
- `LBContainer` loads `website_leaderboard.csv` and lazily unzips the per-view PNGs from `data/...`.
- The reactive Gradio render is driven by four `gr.State` values, one per axis; selecting a tab updates the corresponding state and triggers `render_details`.

## Conventions

- Keep changes minimal — this is a small display app, not a framework. Avoid speculative abstraction.
- Don't add comments that just describe what code does; the file is short enough to read.
- User-facing copy lives in `website_texts.py`. Update it there, not inline.
- Version bumps: edit `version` in `pyproject.toml` and the matching changelog entry in `website_texts.py` (`VERSION_HISTORY_BUTTON_TEXT`).

## Things to verify before reporting a UI change as done

- Launch `python main.py` and click through the affected tabs in a browser.
- Type checks and unit tests aren't meaningful here (none configured) — manual verification is the bar.