AGENTS.md

Project Instructions

Python Environment

• Always use uv to run Python scripts and manage dependencies — never use pip or python directly
• Run scripts with uv run python script.py instead of python script.py
• Install packages with uv add package-name instead of pip install
• To run one-off commands: uv run <command>
• The project uses uv for virtual environment management; do not create venvs manually with python -m venv

Common Commands

• uv run python script.py — run a script
• uv add <package> — add a dependency
• uv sync — install all dependencies from lockfile
• uv run pytest — run tests

Hugging Face Deployment

• .stl files must be tracked by Git LFS (*.stl filter=lfs in .gitattributes)
• Verify Git LFS is available before push: git lfs version
• Confirm tracked LFS files: git lfs ls-files
• Standard push sequence: git push origin main then git push hf-space main
• If Hugging Face rejects binaries, re-check .gitattributes and LFS status before retrying
• git lfs migrate rewrites history; only use it intentionally and coordinate with collaborators first