Add MAD Recipes: model recipes, support matrix and status pages on GitHub Pages by coketaste · Pull Request #294 · ROCm/MAD

coketaste · 2026-10-30T14:58:59Z

Summary

Adds MAD Recipes, a static site generated from this repository, in response to the request for a versioned MAD status update (current model support, oncoming models, QA coverage, ROCm support matrix, CI architectures).

Models: every supported model with per-GPU support (MI300X/MI325X/MI350X/MI355X), filters, table and card views, CSV export.
Recipes: one page per model, in the style of recipes.vllm.ai, with two ways to run it: the madengine command, or plain docker build / docker run (sbatch for multi-node models) with no madengine.
ROCm, QA, CI, Roadmap, Releases: one page each; Overview is the home page. A release can be frozen so the whole site, with recipes pinned to that commit, stays available under /<version>/.

Everything the repo already knows is derived from it (scripts/*/models.json, get_models_json.py, docker/), using madengine's own DiscoverModels, so adding a model adds its recipe page. The rest (QA scope, CI matrix, ROCm versions not in an image tag) lives in dashboard/status.yaml, which is public.

Oncoming models

The Roadmap is read from GitHub: open issues labeled new-model are the plan, and the PRs that close them (Closes #n) or carry the label themselves set the status (planned / in progress / in review / blocked). Merged work leaves the Roadmap and appears under Models. An open item whose model is already on develop is listed as "landed but still open".

.github/ISSUE_TEMPLATE/new_model.yml: a "Model onboarding" issue form that applies the label.
python3 tools/dashboard/build.py --roadmap-report: read-only report of model PRs missing the label and issues that already landed (for example Onboard command-r7b to MAD (vLLM extended tier) #229 and Onboard command-a-plus to MAD (vLLM default tier, MoE VLM) #230, whose models are on develop).

What a maintainer needs to do (I could not, as a non-admin)

Create the labels new-model and blocked.
Settings > Pages > Source: GitHub Actions.
Settings > Secrets and variables > Actions > Variables: DASHBOARD_PAGES = true.

Until DASHBOARD_PAGES is true the workflow only builds (on PRs and pushes) and does nothing on its schedule. Once it is set, develop is published on every push and every 3 hours, which picks up issue and PR changes that cannot trigger a workflow. DASHBOARD_SOURCE_REPO is optional and lets a fork publish another repo's develop.

Notes for review

No new dependencies beyond pyyaml and jinja2 for the generator; the roadmap uses urllib and the workflow's read-only GITHUB_TOKEN.
No existing file changes except a README section and .gitignore entries (_site/, dashboard/roadmap.internal.yaml, and an exception so dashboard/releases/*.json can be committed). .gitignore already excludes *.json and *.html, hence the templates use .html.j2.
Unreleased plans can stay out of the public site: dashboard/roadmap.internal.yaml is gitignored and only used by build.py --internal.
dashboard/status.yaml has TODOs for owners: the GPU CI matrix and ROCm versions for six images whose tag does not encode one.

Test plan

python3 -m pytest tools/dashboard: 49 tests (derivation helpers, recipe generation, PR-diff and roadmap logic with fixtures, and a render test that builds a two-version site and fails on any broken link).
python3 tools/dashboard/build.py --out _site against this tree: 229 recipe pages, 586 configurations, no broken internal links. Also built from a fresh clone of develop with --repo-root.
Pages checked in headless Edge at 1440 and 760 px, light and dark.
Read-only run of --roadmap-report against this repo's open issues and PRs.
After merge and the settings above: one workflow_dispatch run, then check the deployed site.
The plain Docker recipes follow madengine 2.4.0's docker build / docker run options but have not been run on a GPU yet.

🤖 Generated with Claude Code

Answers the five questions asked for a MAD status update in one place: current public model support, the oncoming model plan, what QA covers and what it does not, the ROCm support matrix, and the architectures with CI. - tools/dashboard/collect.py derives everything the repo already knows: models via madengine's DiscoverModels (static and get_models_json.py), GPU products from skip_gpu_arch or the Primus config directory, base images and ROCm versions from the Dockerfiles. - dashboard/status.yaml holds the facts the repo cannot know: CI matrix, QA statements, public-safe roadmap, ROCm versions not in an image tag. An optional gitignored roadmap.internal.yaml is merged only by build.py --internal, never in CI. - tools/dashboard/build.py renders the live page plus one page per frozen release (dashboard/releases/<version>.json, written by --freeze) with changes since the previous release. - .github/workflows/dashboard.yml runs the unit tests and builds on PRs, and deploys to Pages from develop on ROCm/MAD. Co-Authored-By: Claude <noreply@anthropic.com>

…m.ai The site is now multi-page: a browse/search home, one recipe page per model, and the versioned status report under status/. - tools/dashboard/recipes.py generates, per model and GPU product, the madengine command and the equivalent plain commands: docker build with the model's Dockerfile and context, and docker run with madengine's device/security options, MAD_* environment and run-directory steps. SLURM multi-node cards build and push the image and submit their launcher with sbatch, as the framework READMEs document. - Recipe pages group a model's precisions/transports as variants and merge per-GPU Primus configs, with hardware / variant / method pickers. - Model families ignore precision suffixes and punctuation, so Llama-3.3-70B-Instruct, -FP8-KV and -MXFP4-Preview share one page. - nodes_of reads the card's slurm block; status.yaml frameworks link their READMEs from the recipe pages. Co-Authored-By: Claude <noreply@anthropic.com>

- Top navigation: Overview (home), Models, ROCm, QA, CI, Roadmap, Releases, plus a version switcher and a frozen-release banner. - Models is the single model catalog: one row per recipe page with per-GPU support (every variant / some variants / none), a framework summary, table and card views, filters kept in the URL, and a config-level models.csv export. Recipe pages gain a breadcrumb and a variant x GPU support table. - Each frozen release renders the whole site under /<version>/ and its recipes check out the release commit; the switcher keeps the current page when it exists in the other version. - build.py renders one tree per version, derives relative roots from the output path, and fails the build on any broken internal link. Co-Authored-By: Claude <noreply@anthropic.com>

Roadmap: - Open issues labeled new-model are the plan; the PRs that close them, or PRs carrying the label on their own, set the status (planned / in progress / in review / blocked). Merged work drops off and appears under Models. Items whose model is already on develop are listed separately as landed but still open. - New madengine tags per item come from the PR's own diff against its merge base, so moved entries and models already on develop don't count. - Add a "Model onboarding" issue form that applies the label, and a read-only `build.py --roadmap-report` for maintainers. - No token or API errors fall back to the status.yaml roadmap with a warning. Hosting: - build.py --repo-root/--source-repo describe another checkout (e.g. ROCm/MAD develop from a fork); recipe clone URLs and GitHub links follow the source repo. --offline skips GitHub. - The workflow runs every 3 hours as well as on push, can check out vars.DASHBOARD_SOURCE_REPO, and deploys when vars.DASHBOARD_PAGES is true instead of only on ROCm/MAD. Co-Authored-By: Claude <noreply@anthropic.com>

Co-Authored-By: Claude <noreply@anthropic.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

- Model pages and lists show the provider's logo, matched from the Hugging Face org or, for Primus/JAX configs without one, from the model name. Logos are the Hugging Face org avatars that recipes.vllm.ai shows, fetched once by tools/dashboard/fetch_logos.py and vendored under dashboard/logos/, so the site loads no third-party images. - Frameworks get a mark where one exists (vLLM, PyTorch via Simple Icons, CC0) and a generated monogram otherwise; section pages get line glyphs; recipe pages mark the Docker and madengine methods. - Each page ships one inline SVG sprite with only the marks it uses. - dashboard/icons.yaml is the single place to add or change a logo, and `logos: neutral` (or --logos neutral) swaps every brand mark for a neutral monogram. A trademark notice is added to the footer and dashboard/logos/NOTICE.md records the sources. - Fix the roadmap template for PR-sourced items without a Hugging Face id. Co-Authored-By: Claude <noreply@anthropic.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

Models catalog: - A Scale column shows nodes per run and the scheduler it needs ("1 node", "2 nodes · SLURM", "1–4 nodes · SLURM", "2+ nodes · SLURM"), with chips for a manual Kubernetes path, opt-in configs, and single-node models that run multi-node under another framework (↗ multi-node). - The "Multi-node only" checkbox becomes a Scale filter: single node, multi-node, single and multi-node, SLURM, Kubernetes (?multinode=1 links still work). The CSV gains scheduler, k8s and discovery columns. Recipe pages: - A Scale row links the same model across frameworks, e.g. vLLM Llama-3.3-70B <-> vLLM / SGLang disaggregated P/D on 2 nodes. - Nodes becomes a real choice for node-count sweeps, and a Cluster choice (single node / SLURM / Kubernetes) strikes through what a card cannot do, with the reason (e.g. slurm_multi is SLURM-only in madengine). - Fix the madengine recipe for slurm_multi cards: madengine sizes the allocation from slurm.nodes and hands -N/-n in args to the script, so the old recipe ran on one node. The build context now sets nodes. - Disaggregated P/D cards get an "Other topologies" step (xP prefill + yD decode nodes) for madengine and sbatch. - KV cache transfer gets its README's per-node run as the Kubernetes / bare-metal recipe (status.yaml `k8s: manual`). - The multi-node-only JAX MaxText configs (grok1, Llama 3.1 405B, Mixtral 8x22B), hidden unless JAX_MAXTEXT_INCLUDE_MULTINODE=1, are listed as opt-in with an experimental recipe on madengine's primus launcher over SLURM. - Large EP and KV cache microbenchmarks become one page each (status.yaml `one_page`), their cards variants of it. QA and Overview: multi-node, Kubernetes and opt-in coverage are derived from the registry (replacing the hand-written MaxText entry); the Overview gets a Multi-node tile. Snapshot schema 2 adds row deployment fields; older frozen snapshots are back-filled when rendered. Co-Authored-By: Claude <noreply@anthropic.com>

MAD is an AMD open-source project; brand the site the way AMD's ROCm documentation (rocm-docs-core) does: - Header: the AMD logo first, linked to amd.com, then a divider and "MAD / Recipes". The artwork is AMD's own (rocm-docs-core amd-header-logo.svg), shapes unchanged, filled with the text color so it shows as the black or white one-color logo with the theme. The red bar that imitated a brand accent next to "MAD" is removed. - Favicon: the AMD Arrow alone, as amd.com uses it, cut from the same artwork; black or white by the browser's color scheme. - Footer: (c) Advanced Micro Devices, Inc., Terms and Conditions, Privacy and Trademarks (amd.com/en/corporate, as on rocm.docs.amd.com), the repo license, and AMD's trademark attribution ahead of the third-party logo notice. - Assets are vendored under dashboard/logos/amd/ by fetch_logos.py and recorded in sources.json and NOTICE.md, so the site still loads no third-party images. `logos: neutral` shows the word AMD and no favicon. - The top bar collapses at 1200px (was 1100px) for the wider brand, and drops the divider and "/ Recipes" on phones. Co-Authored-By: Claude <noreply@anthropic.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

The header now reads AMD logo, divider, "MAD". Drop the "/ Recipes" suffix and the .sep styling, and the phone rule that hid it, since the divider and brand are no longer collapsed separately. Co-Authored-By: Claude <noreply@anthropic.com>

Copilot

🟡 Changes recommended

The Large-EP recipe sets the wrong image variable, causing jobs to run the card’s existing Docker image instead of the image the recipe builds and pushes.

6 open issues

_{Review effort: Balanced}

Copilot