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:
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.