|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Repository Overview |
| 6 | + |
| 7 | +BioNeMo Framework is a comprehensive suite for building and training biological foundation models at scale. The repository is split into three main areas: |
| 8 | + |
| 9 | +1. **bionemo-recipes/** - Lightweight, self-contained training recipes using FSDP (Fully Sharded Data Parallel) with TransformerEngine and megatron-FSDP |
| 10 | +2. **sub-packages/** - 5D parallel models (tensor/pipeline/context parallel) using NeMo/Megatron-Core, and dataloading/processing tools |
| 11 | +3. **3rdparty/** - Git submodules for NeMo and Megatron-LM dependencies |
| 12 | + |
| 13 | +## Code Architecture |
| 14 | + |
| 15 | +### bionemo-recipes Structure |
| 16 | + |
| 17 | +The recipes directory contains two types of components: |
| 18 | + |
| 19 | +**Models (`bionemo-recipes/models/`)**: HuggingFace-compatible `PreTrainedModel` classes with TransformerEngine layers. These are: |
| 20 | + |
| 21 | +- Distributed via Hugging Face Hub (e.g., nvidia/esm2_t48_15B_UR50D) |
| 22 | +- Drop-in replacements for standard transformers, compatible with `AutoModel.from_pretrained()` |
| 23 | +- Each model includes: conversion utilities (HF ↔ TE), golden value tests, checkpoint export scripts, and open-source license |
| 24 | + |
| 25 | +**Recipes (`bionemo-recipes/recipes/`)**: Self-contained Docker environments demonstrating training patterns. Each recipe: |
| 26 | + |
| 27 | +- Is completely isolated with no shared dependencies between recipes |
| 28 | +- Contains everything needed: Dockerfile, training scripts, Hydra configs, tests, sample data |
| 29 | +- Prioritizes KISS (Keep It Simple) over DRY - code duplication is preferred for clarity |
| 30 | +- Follows naming: `{model_name}_{framework}_{features}/` (e.g., `esm2_native_te/`) |
| 31 | + |
| 32 | +## Essential Commands |
| 33 | + |
| 34 | +### Pre-commit and Linting |
| 35 | + |
| 36 | +**CRITICAL**: Always run pre-commit hooks after making changes: |
| 37 | + |
| 38 | +```bash |
| 39 | +# After editing files |
| 40 | +pre-commit run --all-files |
| 41 | +# Or for modified files only |
| 42 | +pre-commit run |
| 43 | +``` |
| 44 | + |
| 45 | +Pre-commit includes: |
| 46 | + |
| 47 | +- Ruff linting/formatting (line-length: 119, Google-style docstrings) |
| 48 | +- Markdown formatting (mdformat) |
| 49 | +- License header checks |
| 50 | +- Trailing whitespace/EOF fixes |
| 51 | +- YAML validation |
| 52 | +- Secret detection |
| 53 | + |
| 54 | +If pre-commit fails, fix issues before considering task complete. Tasks are NOT complete until all linter errors are resolved and pre-commit passes. |
| 55 | + |
| 56 | +### Testing |
| 57 | + |
| 58 | +**For bionemo-recipes:** |
| 59 | + |
| 60 | +```bash |
| 61 | +# Test a specific recipe/model inside the devcontainer |
| 62 | +cd bionemo-recipes/recipes/{recipe_name} # or models/{model_name} |
| 63 | +pytest -v . |
| 64 | +``` |
| 65 | + |
| 66 | +## Development Workflow |
| 67 | + |
| 68 | +### Working on bionemo-recipes |
| 69 | + |
| 70 | +1. **Navigate to the recipe/model**: `cd bionemo-recipes/recipes/{name}` or `cd bionemo-recipes/models/{name}` |
| 71 | +2. **Make changes** - remember each recipe is self-contained |
| 72 | +3. **Test locally inside the devcontainer**: |
| 73 | + ```bash |
| 74 | + pytest -v . |
| 75 | + ``` |
| 76 | +4. **Run pre-commit**: `pre-commit run --files $(git ls-files -m)` |
| 77 | + |
| 78 | +### Code Quality Standards |
| 79 | + |
| 80 | +- **Line length**: 119 characters |
| 81 | +- **Docstrings**: Google-style (pydocstyle convention) |
| 82 | +- **Import sorting**: isort configuration (2 lines after imports) |
| 83 | +- **Linting**: Ruff for Python, Pyright for type checking |
| 84 | +- **Test files and `__init__.py`**: Have relaxed linting rules as configured in pyproject.toml |
| 85 | + |
| 86 | +## Key Configuration Files |
| 87 | + |
| 88 | +- **.pre-commit-config.yaml**: Pre-commit hook configuration |
| 89 | +- **.cursorrules**: Cursor AI coding guidelines |
| 90 | +- **pyproject.toml (per sub-package)**: Individual package configuration |
| 91 | + |
| 92 | +## Important Patterns |
| 93 | + |
| 94 | +### bionemo-recipes Philosophy |
| 95 | + |
| 96 | +- **Self-contained**: No cross-recipe dependencies, no imports from other recipes |
| 97 | +- **Educational**: Code is documentation - prioritize readability over abstraction |
| 98 | +- **KISS over DRY**: Duplicate code if it improves clarity |
| 99 | +- **One concept per recipe**: Don't try to demonstrate every feature in one script |
| 100 | + |
| 101 | +### Model Conversion Pattern (bionemo-recipes/models) |
| 102 | + |
| 103 | +Models require: |
| 104 | + |
| 105 | +1. Golden value tests proving TE model matches reference model |
| 106 | +2. Bidirectional conversion functions: `convert_hf_to_te()` and `convert_te_to_hf()` |
| 107 | +3. Export script (`export.py`) bundling all files for Hugging Face Hub |
| 108 | +4. Open-source license |
| 109 | + |
| 110 | +### Pre-commit Failures |
| 111 | + |
| 112 | +- Fix all issues before committing |
| 113 | +- Ruff will auto-fix many issues - verify fixes are appropriate |
| 114 | +- Some files have per-file ignores in pyproject.toml - respect those |
0 commit comments