ai4science-studio CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository purpose

AI4Science Studio is an agent-first recipe collection for open AI-for-science models. The primary interface is an AI coding agent (Cursor, Claude Code, etc.) that reads machine-readable metadata to discover, configure, and run models. There is no build system, compiled code, or test suite—the repo is Markdown files, YAML manifests, and (optionally) scripts and notebooks in recipe folders. Upstream code lives in external GitHub repos; upstream model weights live on Hugging Face.

Agent entry points (read these first)

• models.yaml (repo root) — index of all models; read this to discover what's available.
• <model>/model.yaml — per-model manifest with HF id, license, recipes, env vars, and hardware.
• .cursor/skills/ — agent skills for Cursor; .claude/commands/ — slash commands for Claude Code.

Directory layout

models.yaml                                 # repo-wide model index (agent entry point)
<domain>/models/<model-slug>/model.yaml     # machine-readable model manifest
<domain>/models/<model-slug>/README.md      # HF id, license, upstream links
<domain>/models/<model-slug>/recipes/       # how-to docs, one subfolder per task
<domain>/models/<model-slug>/examples/      # ready-to-run scripts

Domains: earth_science/, material_science/, protein_folding/, healthcare/, physics_simulation/

Model slug rule

Hugging Face id org/model → directory name org__model (replace / with __). Some models use a public name on disk instead; in that case, document the canonical HF id in the model's README.md. Example: earth_science/models/ORBIT-2/ maps to HF id jychoi-hpc/ORBIT-2.

Adding a new model

1. Pick the correct domain folder.
2. Copy _template/ to <domain>/models/<model-slug>/.
3. Fill in README.md: Hugging Face model id (or N/A with alternate source), task, license (SPDX id or link), upstream code/paper.
4. Place how-to docs under <model-slug>/recipes/. Prefer one subfolder per task (recipes/inference/, recipes/finetune/, etc.), each with its own README.md.
5. Place ready-to-run scripts under <model-slug>/examples/: docker_run.sh, run_<task>.sh/.py, preflight_<slug>.py, and sbatch_<task>_amd.sh. All scripts must be chmod +x. For HPC models with heavy pip deps, also add build_overlay_amd.sh.
6. Create a model.yaml in the model folder with structured metadata (name, hf_id, license, task, recipes, env_vars).
7. Add the model to the root models.yaml index.
8. Do not commit large checkpoints or datasets—document how to obtain them instead.