AGENTS.md · roboflow/rf-detr

Sections

1. Agent Responsibilities
2. Build & Development Environment
3. Testing
4. Code Quality & Linting
5. Documentation
6. Package Building
7. Project Structure
8. Architecture & Conventions
9. Common Workflows
10. CI/CD Workflows
11. Additional Resources

First lines (shown under the repo's Apache-2.0 license)

# RF-DETR - Agent Instructions

This file provides detailed technical context for AI coding agents working with RF-DETR.

**Canonical Sources:**

- **Contribution Guidelines:** [CONTRIBUTING.md](.github/CONTRIBUTING.md) - The authoritative source for all contribution practices
- **Human Documentation:** [README.md](README.md) - Project overview and usage
- **Copilot Instructions:** [.github/copilot-instructions.md](.github/copilot-instructions.md) - GitHub Copilot-specific guidance

This document supplements the contribution guidelines with detailed technical information for automated tooling.

## Agent Responsibilities

As an AI agent contributing to RF-DETR, you are responsible for:

1. **Following test-driven development practices**

    - Write failing tests first for bug fixes
    - Write comprehensive tests for new features
    - Ensure final PR commit has all tests passing

2. **Adhering to code quality standards**

    - Run `pre-commit run --all-files` before every commit
    - Follow type hint and docstring requirements
    - Prefer direct project imports; conventional third-party aliases are allowed

3. **Maintaining agentic documentation**

    - Update `AGENTS.md` when architecture patterns or technical conventions change
    - Update `.github/copilot-instructions.md` when high-level guidance changes
    - Update `.github/CONTRIBUTING.md` when human workflow is affected
    - Apply updates after receiving major feedback in PR reviews
    - For code reviews, follow the [code-review skill](.github/skills/code-review/SKILL.md)

4. **Consulting maintainers before major changes**

    - Open an issue before adding new models or significant features
    - Wait for approval on approach before implementing

5. **Writing secure, minimal code**

    - Avoid over-engineering and unnecessary abstractions
    - Write secure code (prevent injection vulnerabilities)
    - Follow existing patterns in the codebase

> [!NOTE]
>
> Keeping documentation current ensures consistency across agent contributions and reduces repeated feedback on the same issues.

## Build & Development Environment

> [!NOTE]
>
> **Canonical Reference:** See [Development Environment Setup](.github/CONTRIBUTING.md#development-environment-setup) in CONTRIBUTING.md for complete setup instructions.

### Setup

```bash
# Install uv (if not already installed)
pip install uv

# Create the virtual environment
uv venv

# Install the extras and groups used by the CPU test job (add ,coreml on macOS).
uv pip install -e ".[train,augment,cli,visual,data]" --group tests --torch-backend=cpu
```

**Prerequisites:** Python >=3.10 (tested on 3.10-3.14)

### Dependency Information

See `pyproject.toml` for complete dependency specifications:

- **Core:** PyTorch, torchvision, transformers, supervision, pydantic, pyDeprecate
- **Optional:** `[data]` (WebDataset streaming reader), `[train]` (minimal training loop dependencies, including the COCO evaluation backends selectable via `TrainConfig.eval_backend`), `[augment]` (custom Albumentations CPU augmentations and Kornia GPU augmentations), `[lora]` (LoRA fine-tuning), `[plus]` (Plus models), `[onnx]` (ONNX export), `[loggers]` (tensorboard, wandb, mlflow, clearml)
- **Development:** `tests`, `docs`, `build` groups

**Important version constraints:**

- PyTorch: >=2.2.0, \<3.0.0
- Transformers: >=5.0.0, \<6.0.0

## Testing

> [!NOTE]
>
> **Canonical Reference:** See [Test-Driven Development](.github/CONTRIBUTING.md#test-driven-development) in CONTRIBUTING.md for complete guidelines.
>
> **CI Workflows (Source of Truth):** See `.github/workflows/ci-tests-cpu.yml` and `.github/workflows/ci-tests-gpu.yml` for exact test commands used in CI.

### Commands

```bash
# CPU tests (default for local development; mirrors CI)
uv run --no-sync pytest src/ tests/ scripts/ -n 1 -m "not gpu" --ignore=tests/run_smoke_all_models.py --ignore=tests/legacy/test_checkpoint_compat.py --cov=rfdetr --cov-report=xml --timeout=240 --durations=50

# GPU tests (requires GPU; mirrors CI)
uv run --no-sync pytest tests/ -m gpu --ignore=tests/legacy/test_checkpoint_compat.py -n 2 --reruns 1 --only-rerun "OutOfMemoryError" --cov=rfdetr --cov-report=xml --timeout=600 --durations=20

# Pre-commit checks (ALWAYS run before committing)
pre-commit run --all-files
```

### Testing Principles

> [!IMPORTANT]
>
> **Testing Requirements:**
>
> - ⚠️ **During development:** Tests may fail as you work through TDD cycle
> - ✅ **Before opening PR:** Final commit MUST have all tests passing
> - ✅ **Before each commit:** Run `pre-commit run --all-files`

**Test-Driven Development:**

1. **Bug fixes:** Write failing test → Fix code → Verify all tests pass
2. **New features:** Write comprehensive tests → Implement feature → Refactor

**Test Organization:**

- Group related tests in classes
- Use `pytest.param(..., id="name")` only for a function, object, compound setup passed as one case, a per-case mark, or when the raw value would produce an unclear/empty ID (e.g., `""`); use bare string/number/boolean/`None` values otherwise, and do not maintain a parallel `ids` list
- Mark GPU/heavy tests with `@pytest.mark.gpu`
- Never use `pytest.importorskip`, and do not use `pytest.skip()` for missing optional dependencies. Gate optional-dependency tests with a named `pytest.mark.skipif` decorator built from an `_IS_<PACKAGE>_INSTALLED` flag, applied to the test, the class, or a `pytest.param(..., marks=...)` case (a module-wide `pytestmark = <named skipif>` is fine when every test in the module needs the package). Import the optional package locally inside the test or helper, which is the optional-dependency boundary the Imports rule allows, and gate helper doctests with `__doctest_requires__`
- Take the flag from `rfdetr.export.imports` (export formats) or `rfdetr.utilities.imports` (everything else); add a new flag to the matching module and never re-probe with `find_spec` in a test file. The one exception is a format whose exporter package guards its own import (`_IS_COREMLTOOLS_AVAILABLE`, `_IS_EXECUTORCH_AVAILABLE`, `_IS_ONNX2TF_AVAILABLE`, `_IS_POLYGRAPHY_AVAILABLE`): gate its tests on that flag, which skips a broken install instead of failing it. A flag proves a package is installed, not that it imports, so a broken install errors instead of skipping. Reserve in-body `pytest.skip()` for conditions that can only be discovered at runtime - see [CONTRIBUTING.md](.github/CONTRIBUTING.md#test-organization)
- Avoid multiple validation cases in a single test - see [CONTRIBUTING.md](.github/CONTRIBUTING.md#avoid-multiple-validation-cases-in-a-single-test) for details
- Fixtures return ready-to-use concrete state or a cohesive tuple of related state. Do not return a callable factory unless fixture-managed lifecycle is required; use an ordinary helper function for configurable construction.
- Keep fixture dependencies minimal, unpack only the values a test needs, and avoid aliases or wrappers that merely rename or forward an object without adding meaning.

**CI Information:** See [CI Testing](.github/CONTRIBUTING.md#ci-testing) in CONTRIBUTING.md for details on OS/Python version matrix and workflow configurations.

## Code Quality & Linting

> [!NOTE]
>
> **Canonical Reference:** See [Code Quality and Linting](.github/CONTRIBUTING.md#code-quality-and-linting) in CONTRIBUTING.md for setup and details.

### Command

```bash
# Always run full pre-commit (not individual tools)
pre-commit run --all-files
```

> [!TIP]
>
> Pre-commit hooks will auto-format many issues. Review changes and re-stage files.

**Configuration Files:**

- `.pre-commit-config.yaml` - Pre-commit hooks (ruff, mdformat, prettier, codespell, license headers)
- `pyproject.toml` - Ruff linting rules (`[tool.ruff]` section)

**Abstraction Discipline:**

- Introduce an abstraction only when it reduces cognitive load and the number of concepts a reader must follow. Extract stable repeated behavior or irrelevant construction mechanics while keeping behavior-defining inputs and outcomes explicit at call sites.
- Design an extracted helper for the complete related behavior already present, including relevant edge cases, and place it in the narrowest scope shared by its consumers. Prefer small visible duplication over a helper, wrapper, alias, or layer that adds indirection without semantic value.