AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization

TD3B is a Python 3.10 research codebase for directional peptide-binder generation. Core diffusion components live in `models/`; TD3B losses, scoring, MCTS integration, data utilities, and the direction oracle live in `td3b/`. Training helpers are under `training/`, standalone tree search is in `mcts/`, and comparison methods are in `baselines/`. Configuration objects and YAML settings belong in `configs/`. Pretrained weights are tracked in `checkpoints/`, classifier artifacts in `scoring/functions/classifiers/`, and tokenizer resources in `tokenizer/`. Use `inference.py` and `finetune_multi_target.py` as the main entry points. The notebook in `notebooks/` is the interactive demo. Local datasets should use `data/train.csv` and `data/test.csv`; they are not included in the repository.

## Build, Test, and Development Commands

Create the supported environment and install the package in editable mode:

```bash
conda env create -f env.yml
conda activate td3b
pip install -e .
```

Run inference with `python inference.py --ckpt_path checkpoints/td3b.ckpt --val_csv data/test.csv --save_path results/ --seed 42`. Before training, replace the placeholder paths in `launch_multi_target.sh`, then run `bash launch_multi_target.sh`. Run a baseline through its positional interface, for example `bash baselines/run.sh data/test.csv cg cuda:0 baselines/outputs`.

## Coding Style & Naming Conventions

Follow the existing Python style: four-space indentation, `snake_case` for modules, functions, and variables, `PascalCase` for classes/config dataclasses, and `UPPER_SNAKE_CASE` for constants. Add type hints and short docstrings to public or non-obvious functions. Keep CLI flags descriptive and lowercase with underscores. No formatter or linter is configured; keep imports grouped as standard library, third-party, then local modules, and avoid unrelated reformatting.

## Testing Guidelines

There is currently no automated test suite or coverage threshold. For every change, run `python -m compileall models td3b training mcts scoring baselines utils` and exercise the affected CLI with a small input. GPU-dependent changes should document the CUDA device, checkpoint, seed, and command used. Add future tests under `tests/` using `test_<module>.py` and `test_<behavior>` names.

## Commit & Pull Request Guidelines

Recent commits use short, imperative summaries such as `Add Colab demo notebook section to README` and `Reorganize root modules into ... packages`. Keep commits focused and avoid committing generated results, caches, or machine-specific paths. Pull requests should explain the motivation and implementation, list validation commands, link relevant issues, and note data/checkpoint assumptions. Include sample output or screenshots for notebook or visualization changes.