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

Dependencies

• After any uv add / uv remove, regenerate the Hugging Face requirements file or the deploy will not get the change — the Space installs from requirements.txt, not from uv.lock: uv export --format requirements.txt --no-hashes --no-dev --frozen --output-file requirements.txt
• Commit pyproject.toml, uv.lock, and requirements.txt together when dependencies change.

Rendering Constraints (Hugging Face)

• Hugging Face Spaces run headless with no GPU/WebGL and no guaranteed ffmpeg.
• For any server-side image or animation rendering, use CPU-only paths: Matplotlib's Agg backend, GIF via Pillow.
• Avoid kaleido / Plotly static-image export (3D is extremely slow headless) and ffmpeg-dependent MP4 output. Both were tried and proved unreliable here; the parallel-print GIF export uses Matplotlib Agg instead.

Local Tooling

• .claude/ (e.g. launch.json for the local preview server) is gitignored and not deployed.

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