AGENTS.md — AI Agent Guidelines for fVDB Reality Capture

This file provides persistent instructions for AI coding agents (Cursor, Copilot, Codex, etc.) working on this codebase. Human contributors should also refer to CONTRIBUTING.md.

Git Commits

• All commits must include a DCO sign-off (git commit --signoff / -s).
• All commits must be SSH-signed (git commit --gpg-sign / -S).
• Never skip hooks or signing: do not use --no-verify or --no-gpg-sign.

Python Code Style

• Format Python code with black using the exact flags from CI:

  black --target-version=py311 --line-length=120 .
  

• Do not run black with default settings — the default line-length (88) does not match this project's setting (120).

• There is currently no [tool.black] section in pyproject.toml; a future PR may add one so that plain black . picks up the correct settings automatically.

License Headers

Every source file must include the Apache-2.0 SPDX identifier.

Python files:

# Copyright Contributors to the OpenVDB Project
# SPDX-License-Identifier: Apache-2.0

Whitespace

• No trailing whitespace (CI enforces this; .wlt files are excluded).
• Use spaces, not tabs (binary and a few config files are excluded from this check).

Style

• Avoid excessive use of emoji and non-ascii characters in code and documentation except where it is helpful to user experience or user interfaces.

Testing

• Run relevant tests before pushing:

  cd tests && pytest -v unit benchmarks/test_benchmark_contract.py benchmarks/test_comparison_benchmark.py
  

• Note: tests require a GPU runner with fvdb-core installed.

Test Coverage

When adding new config options or features:

• Update tests/benchmarks/contract.py to validate new fields
• Add tests in test_comparison_benchmark.py or appropriate test file
• Run existing contract tests to ensure backwards compatibility

Opening Issues

• Set appropriate labels (e.g. bug, enhancement, documentation).
• Reference any related issues or PRs.
• For bugs: provide clear reproduction steps, expected vs actual behavior, and environment details.
• Set appropriate labels on the issue.
• Add the issue to the fvdb-reality-capture GitHub project

Opening Pull Requests

• Reference the issue being fixed (e.g. "Fixes #NNN").
• Include a test plan with specific commands to verify the change.
• Ensure all CI checks pass before requesting review (DCO, codestyle, tests).
• Keep PRs focused on a single concern.
• Set appropriate labels on the PR.
• Add the PR to the fvdb-reality-capture GitHub project

Do not commit unless directed:

• .vscode/settings.json - local IDE settings
• .cursor/ - local Cursor config
• Test-specific matrices or configs with hardcoded paths