{"owner":"roboflow","repo":"rf-detr","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md",".github/copilot-instructions.md"],"skills":{"AGENTS.md":"# RF-DETR - Agent Instructions\n\nThis file provides detailed technical context for AI coding agents working with RF-DETR.\n\n**Canonical Sources:**\n\n- **Contribution Guidelines:** [CONTRIBUTING.md](.github/CONTRIBUTING.md) - The authoritative source for all contribution practices\n- **Human Documentation:** [README.md](README.md) - Project overview and usage\n- **Copilot Instructions:** [.github/copilot-instructions.md](.github/copilot-instructions.md) - GitHub Copilot-specific guidance\n\nThis document supplements the contribution guidelines with detailed technical information for automated tooling.\n\n## Agent Responsibilities\n\nAs an AI agent contributing to RF-DETR, you are responsible for:\n\n1. **Following test-driven development practices**\n\n    - Write failing tests first for bug fixes\n    - Write comprehensive tests for new features\n    - Ensure final PR commit has all tests passing\n\n2. **Adhering to code quality standards**\n\n    - Run `pre-commit run --all-files` before every commit\n    - Follow type hint and docstring requirements\n    - Prefer direct project imports; conventional third-party aliases are allowed\n\n3. **Maintaining agentic documentation**\n\n    - Update `AGENTS.md` when architecture patterns or technical conventions change\n    - Update `.github/copilot-instructions.md` when high-level guidance changes\n    - Update `.github/CONTRIBUTING.md` when human workflow is affected\n    - Apply updates after receiving major feedback in PR reviews\n\n4. **Consulting maintainers before major changes**\n\n    - Open an issue before adding new models or significant features\n    - Wait for approval on approach before implementing\n\n5. **Writing secure, minimal code**\n\n    - Avoid over-engineering and unnecessary abstractions\n    - Write secure code (prevent injection vulnerabilities)\n    - Follow existing patterns in the codebase\n\n> [!NOTE]\n>\n> Keeping documentation current ensures consistency across agent contributions and reduces repeated feedback on the same issues.\n\n## Build & Development Environment\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Development Environment Setup](.github/CONTRIBUTING.md#development-environment-setup) in CONTRIBUTING.md for complete setup instructions.\n\n### Setup\n\n```bash\n# Install uv (if not already installed)\npip install uv\n\n# Full development environment (always use this)\nuv sync --all-groups\n```\n\n**Prerequisites:** Python >=3.10 (tested on 3.10-3.13)\n\n### Dependency Information\n\nSee `pyproject.toml` for complete dependency specifications:\n\n- **Core:** PyTorch, torchvision, transformers, supervision, pydantic, pyDeprecate\n- **Optional:** `[train]` (minimal training loop dependencies), `[augment]` (custom Albumentations CPU augmentations and Kornia GPU augmentations), `[lora]` (LoRA fine-tuning), `[plus]` (Plus models), `[onnx]` (ONNX export), `[loggers]` (tensorboard, wandb, mlflow, clearml)\n- **Development:** `tests`, `docs`, `build` groups\n\n**Important version constraints:**\n\n- PyTorch: >=2.2.0, \\<3.0.0\n- Transformers: >=5.0.0, \\<6.0.0\n\n## Testing\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Test-Driven Development](.github/CONTRIBUTING.md#test-driven-development) in CONTRIBUTING.md for complete guidelines.\n>\n> **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.\n\n### Commands\n\n```bash\n# CPU tests (default for local development; mirrors CI)\nuv run --no-sync pytest src/ tests/ -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\n\n# GPU tests (requires GPU; mirrors CI)\nuv 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\n\n# Pre-commit checks (ALWAYS run before committing)\npre-commit run --all-files\n```\n\n### Testing Principles\n\n> [!IMPORTANT]\n>\n> **Testing Requirements:**\n>\n> - ⚠️ **During development:** Tests may fail as you work through TDD cycle\n> - ✅ **Before opening PR:** Final commit MUST have all tests passing\n> - ✅ **Before each commit:** Run `pre-commit run --all-files`\n\n**Test-Driven Development:**\n\n1. **Bug fixes:** Write failing test → Fix code → Verify all tests pass\n2. **New features:** Write comprehensive tests → Implement feature → Refactor\n\n**Test Organization:**\n\n- Group related tests in classes\n- Use `@pytest.mark.parametrize` with `pytest.param(..., id=\"name\")`\n- Mark GPU/heavy tests with `@pytest.mark.gpu`\n- Avoid multiple validation cases in a single test - see [CONTRIBUTING.md](.github/CONTRIBUTING.md#avoid-multiple-validation-cases-in-a-single-test) for details\n- 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.\n- 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.\n\n**CI Information:** See [CI Testing](.github/CONTRIBUTING.md#ci-testing) in CONTRIBUTING.md for details on OS/Python version matrix and workflow configurations.\n\n## Code Quality & Linting\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Code Quality and Linting](.github/CONTRIBUTING.md#code-quality-and-linting) in CONTRIBUTING.md for setup and details.\n\n### Command\n\n```bash\n# Always run full pre-commit (not individual tools)\npre-commit run --all-files\n```\n\n> [!TIP]\n>\n> Pre-commit hooks will auto-format many issues. Review changes and re-stage files.\n\n**Configuration Files:**\n\n- `.pre-commit-config.yaml` - Pre-commit hooks (ruff, mdformat, prettier, codespell, license headers)\n- `pyproject.toml` - Ruff linting rules (`[tool.ruff]` section)\n\n**Abstraction Discipline:**\n\n- 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.\n- 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.\n\n**License Header (required for all Python files):**\n\n```python\n# ------------------------------------------------------------------------\n# RF-DETR\n# Copyright (c) 2025 Roboflow. All Rights Reserved.\n# Licensed under the Apache License, Version 2.0 [see LICENSE for details]\n# ------------------------------------------------------------------------\n```\n\n## Documentation\n\n### Building Docs\n\n```bash\n# Full install (matches CI — required for XLarge/2XLarge model pages)\nuv pip install -e \".[plus]\" --group docs\n\n# Serve locally (live reload)\nuv run mkdocs serve\n\n# Build static site\nuv run mkdocs build\n```\n\n**Documentation Structure:**\n\n- **Source:** `docs/` directory (Markdown)\n- **Config:** `mkdocs.yaml` (uses custom YAML tags: `!!python/name`)\n- **Deployment:** GitHub Actions publishes to GitHub Pages\n\n**Note:** `mkdocs.yaml` is checked by the `check-yaml` pre-commit hook with `--unsafe` so custom YAML tags such as `!!python/name` are accepted.\n\n## Package Building\n\n```bash\n# Install build dependencies\nuv sync --group build\n\n# Build distributions\nuv build\n\n# Validate build\nuv run twine check --strict dist/*\n```\n\n**Build outputs:**\n\n- Source distribution: `dist/rfdetr-*.tar.gz`\n- Wheel: `dist/rfdetr-*.whl`\n\n## Project Structure\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Project Structure](.github/CONTRIBUTING.md#project-structure) in CONTRIBUTING.md for complete project organization, directory descriptions, and configuration files.\n>\n> **Quick summary:** `src/rfdetr/` (source code), `tests/` (test suite), `docs/` (documentation), `.github/` (CI/CD), `pyproject.toml` (dependencies and config).\n>\n> Internal package organization within `src/rfdetr/` is subject to change as this is an active research and development project.\n\n## Architecture & Conventions\n\n### Key Patterns\n\n**Augmentations:**\n\n- Default training, validation, prediction, and export preprocessing use torchvision-native transforms.\n- Custom non-empty `aug_config` values on the CPU path use Albumentations and require `rfdetr[augment]`.\n- `augmentation_backend=\"gpu\"` uses Kornia and requires `rfdetr[augment]`; `augmentation_backend=\"auto\"` falls back to CPU when CUDA or Kornia is unavailable.\n\n**Model Architecture:**\n\n- RFDETR wrappers: `self.model` is the model context returned by `get_model()`\n- Underlying PyTorch module: `self.model.model`\n- Segmentation models return `pred_masks` as `torch.Tensor` or dict with keys `['spatial_features', 'query_features', 'bias']`\n\n**Model Selection (examples, docs, tests, defaults):**\n\n- **Default to `RFDETRSmall` / `\"rfdetr-small\"`.** Use it wherever an example needs a concrete detection model.\n- **Never use base models** (`RFDETRBase` / `\"rfdetr-base\"`) in new examples, docs, or tests — treat as deprecated; substitute `small`.\n- **Released detection sizes** — `nano`, `small`, `medium`, `large` (plus `xlarge`/`2xlarge` Plus models). Always pick one of these for plain object detection; never a `-preview` variant.\n- **Released segmentation sizes** — `RFDETRSegNano`/`Small`/`Medium`/`Large` / `\"rfdetr-seg-{nano,small,medium,large}\"` (plus `xlarge`/`2xlarge`). Use a sized seg model for segmentation; `RFDETRSegPreview` / `\"rfdetr-seg-preview\"` is now superseded — do not use it in new examples, docs, or tests.\n- **`-preview` variants** are for capabilities with **no released sized version yet**. Only keypoints remain preview-only: `RFDETRKeypointPreview` / `\"rfdetr-keypoint-preview\"`. Use a preview variant **only** for that task — never as a stand-in for detection or segmentation.\n\n**Imports:**\n\n- Keep imports at module scope by default. Use a local import only for a verified circular-import boundary, optional dependency boundary, import-behavior test, or material startup/side-effect constraint; the reason must be evident from the surrounding code or documented where it is not obvious.\n\n```python\n# Prefer direct project imports. Standard aliases such as `numpy as np`,\n# `torch.nn.functional as F`, and lazy module aliases are allowed when conventional.\nfrom rfdetr.utilities.distributed import get_rank, get_world_size, is_main_process, save_on_master\nfrom rfdetr.utilities.logger import get_logger\n\n# Logger usage\nlogger = get_logger()  # Default name: \"rf-detr\", reads LOG_LEVEL env var\n\n# TQDM (environment compatibility)\nfrom tqdm.auto import tqdm  # NOT: from tqdm import tqdm\n```\n\n**Plus Models (XLarge, 2XLarge):**\n\n- Requires separate `rfdetr_plus` package (PML 1.0 license)\n- Import handled lazily via `__getattr__` in `src/rfdetr/platform/models.py`\n- Raises `ImportError` if package not installed\n\n**Subprocess Usage:**\n\n```python\nimport subprocess\n\nresult = subprocess.run(\n    [\"command\", \"arg1\", \"arg2\"],\n    check=True,  # Raise CalledProcessError on failure\n    text=True,  # Return stdout/stderr as strings\n    capture_output=True,\n)\n# Note: stderr is already a string, don't decode\n```\n\n**Logging:**\n\n- Use `logger.debug()` for detailed tensor/shape information (not `logger.info()`)\n- Use `logger.info()` for high-level progress/status\n\n**Checkpoint Handling:**\n\n- Always check file existence before operations\n- Prevents errors when training is interrupted\n\n### Type Hints & Docstrings\n\n> [!IMPORTANT]\n>\n> **Canonical Reference:** See [Google-Style Docstrings and Mandatory Type Hints](.github/CONTRIBUTING.md#google-style-docstrings-and-mandatory-type-hints) in CONTRIBUTING.md for complete requirements and examples.\n>\n> **Requirements:**\n>\n> - MANDATORY type hints for all function parameters and return types\n> - MANDATORY Google-style docstrings for all functions and classes\n> - **Do not duplicate types in docstrings** - types are in the function signature\n> - Target Python version: 3.10+\n> - **Helper functions in `tests/` need a doctest too**: any non-`test_*` function used by tests (fixture builders, assertion helpers, reference implementations) needs a docstring with an `Examples` doctest that exercises it directly — `pyproject.toml` runs `--doctest-plus` across `tests/` on purpose. Skip the live doctest (`# doctest: +SKIP` + one-line reason) only when the helper can't run standalone (e.g. a `@pytest.fixture`, or needs real GPU/XLA/network hardware).\n\n## Common Workflows\n\n### Making Changes\n\n1. **Setup:** `uv sync --all-groups`\n2. **Before changes:** Run tests to establish baseline\n3. **Development:**\n    - Make minimal, focused changes\n    - Follow existing patterns and conventions\n    - Add type hints and docstrings\n4. **Testing:**\n    - Bug fixes: Write test first, then fix\n    - Features: Test all major use cases\n    - Run: `uv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\" --ignore=tests/run_smoke_all_models.py --ignore=tests/legacy/test_checkpoint_compat.py --timeout=240 --durations=50`\n5. **Quality checks:** `pre-commit run --all-files`\n6. **Build (if needed):** `uv build`\n7. **Commit:** Pre-commit hooks run automatically\n\n### Adding New Model Variants\n\n> [!IMPORTANT]\n>\n> **Canonical Reference:** See [Adding a New Model](.github/CONTRIBUTING.md#adding-a-new-model) in CONTRIBUTING.md for detailed guidance.\n>\n> Always consult maintainers before implementing new models.\n\n### Security Considerations\n\n- **Write secure code:** Avoid injection vulnerabilities (XSS, SQL injection, command injection)\n- **Validate inputs:** Especially for file paths, URLs, and user-provided data\n- **No credentials:** Never commit API keys, tokens, or credentials\n- **Follow OWASP best practices**\n\n## CI/CD Workflows\n\nGitHub Actions workflows in `.github/workflows/`:\n\n- **ci-tests-cpu.yml:** CPU tests across OS/Python versions\n- **ci-tests-gpu.yml:** GPU-dependent tests\n- **ci-legacy-checkpoints.yml:** Backward-compatibility checkpoint-loading tests across historical rfdetr releases (advisory only — not a required check; a compat break does not block merge)\n- **ci-deps-resolution.yml:** Dependency resolution (`uv lock`) plus an install-plan check (`uv sync --dry-run`) for every extra on every Python interpreter allowed by requires-python (3.10-3.14). Resolution alone does not prove a pinned version ships a wheel for the interpreter in use. The `list-extras` job derives the checked set from every `[project.optional-dependencies]` extra, so a new extra is covered automatically\n- **build-package.yml:** Build and validate distributions\n- **ci-build-docs.yml:** Documentation builds\n- **publish-docs.yml:** Deploy docs to GitHub Pages\n\n**Concurrency:** PRs cancel in-progress runs on new pushes\n\n## Additional Resources\n\n- **Documentation:** https://rfdetr.roboflow.com\n- **Repository:** https://github.com/roboflow/rf-detr\n- **Issues:** https://github.com/roboflow/rf-detr/issues\n- **Discord:** https://discord.gg/GbfgXGJ8Bk\n- **Contributing:** `.github/CONTRIBUTING.md`\n- **Copilot Instructions:** `.github/copilot-instructions.md`\n\n---\n\n**Note:** This file is designed for AI coding agents. For human-readable project information, see README.md. For contribution guidelines, see CONTRIBUTING.md.\n","CLAUDE.md":"# Claude Code Project Instructions\n\n<!-- Imports AGENTS.md, which contains agent roles, behavioral rules, and coding constraints for this project. -->\n\n@AGENTS.md\n",".github/copilot-instructions.md":"# RF-DETR Copilot Instructions\n\n> [!NOTE]\n>\n> This document is GitHub Copilot-specific guidance. For canonical contribution guidelines (test-driven development, code quality, docstrings, etc.), see [CONTRIBUTING.md](CONTRIBUTING.md). For detailed agent-specific context, see [AGENTS.md](../AGENTS.md).\n\n## Repository Overview\n\nRF-DETR is a real-time transformer architecture for object detection and instance segmentation. Built on DINOv2 vision transformer backbone with PyTorch.\n\n- **Project Type:** Python ML library (computer vision)\n- **Python:** >=3.10 (3.10, 3.11, 3.12, 3.13)\n- **License:** Apache 2.0 (Plus models under PML 1.0)\n\n> [!TIP]\n>\n> - **Configuration:** See `pyproject.toml` for dependencies, build settings, and tool configurations.\n> - **Contributing:** See `.github/CONTRIBUTING.md` for contribution guidelines, CLA, and coding standards.\n\n## Quick Start\n\n**Package Manager:** This project uses `uv` for all dependency management.\n\n```bash\n# Development setup\nuv sync --all-groups\n\n# Run tests (always before committing)\nuv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\" --cov=rfdetr --cov-report=xml\n\n# Build package\nuv build\n```\n\n> [!IMPORTANT]\n>\n> Run `uv sync` after pulling changes to update dependencies.\n\n**Dependency extras:** `rfdetr[train]` is intentionally minimal and uses torchvision-native default augmentations. Custom Albumentations CPU configs and Kornia GPU augmentation both require `rfdetr[augment]`.\n\n## Code Quality\n\n**Linting & Formatting:** All code must pass pre-commit checks. See **[Code Quality and Linting](CONTRIBUTING.md#code-quality-and-linting)** in CONTRIBUTING.md for setup and details.\n\n```bash\npre-commit run --all-files\n```\n\n> **Configuration:** `.pre-commit-config.yaml` (hooks) and `[tool.ruff]` in `pyproject.toml` (Python linting)\n\n## Key Conventions\n\n> [!NOTE]\n>\n> Internal package organization (`src/rfdetr/`) is subject to change as this is an active research project. Explore the codebase to understand current module organization.\n\n**Imports:**\n\n- Always use direct imports: `from rfdetr.utilities.distributed import get_rank, is_main_process`\n- Logger: `from rfdetr.utilities.logger import get_logger` (reads `LOG_LEVEL` env var)\n- **Never use** `rfdetr.util.*` or `rfdetr.deploy.*` — deprecated shims scheduled for removal in v1.9.0\n- TQDM: `from tqdm.auto import tqdm` (NOT `from tqdm import tqdm`)\n\n## Testing & Development Workflow\n\n**Test-Driven Development:** Follow TDD practices - write tests first for bugs, comprehensive tests for features. See **[Test-Driven Development](CONTRIBUTING.md#test-driven-development)** in CONTRIBUTING.md for detailed guidelines.\n\n**Quick reference:**\n\n- Bug fixes: Write failing test → Fix → Verify all pass\n- Features: Write comprehensive tests → Implement → Refactor\n- Use test classes and `@pytest.mark.parametrize` for organization\n- Mark GPU/heavy tests with `@pytest.mark.gpu`\n\n**Testing Requirements:**\n\n- ⚠️ During development: Tests may fail (TDD cycle is fine)\n- ✅ Before PR: Final commit MUST have all tests passing\n- ✅ Before commit: Run `pre-commit run --all-files`\n\n**CI/CD:** See `.github/workflows/` for source of truth. Tests run on Python 3.10-3.13 across Ubuntu, Windows, macOS.\n\n## Coding Standards\n\n**Type Hints & Docstrings:** MANDATORY for all functions/classes. See **[Google-Style Docstrings and Mandatory Type Hints](CONTRIBUTING.md#google-style-docstrings-and-mandatory-type-hints)** in CONTRIBUTING.md for examples.\n\n**Import Conventions:**\n\n```python\n# Always use direct imports (NOT import ... as pattern)\nfrom rfdetr.utilities.distributed import get_rank, is_main_process, save_on_master\nfrom rfdetr.utilities.logger import get_logger\n\n# TQDM (for environment compatibility)\nfrom tqdm.auto import tqdm  # NOT from tqdm import tqdm\n```\n\n**Project-Specific Patterns:**\n\n- **Model selection:** Default to `RFDETRSmall` / `\"rfdetr-small\"` in examples, docs, and tests. **Never use base models** (`RFDETRBase` / `\"rfdetr-base\"`) — treat as deprecated, substitute `small`. Pick a released detection size (`nano`/`small`/`medium`/`large`) for detection and a released segmentation size (`seg-nano`/`seg-small`/`seg-medium`/`seg-large`) for segmentation; `-preview` variants are only for capabilities with no released sized version — now just `keypoint-preview`. `seg-preview` is superseded; use a sized seg model instead.\n- **Logging:** Use `logger.debug()` for detailed tensor/shape info (not `logger.info()`)\n- **Segmentation models:** Return `pred_masks` as `torch.Tensor` or dict with keys `['spatial_features', 'query_features', 'bias']`\n- **Checkpoint handling:** Always check file existence before operations\n- **License headers:** All Python files require Apache 2.0 header (enforced by pre-commit)\n\n**Best Practices:**\n\n- Make minimal, surgical changes - avoid over-engineering\n- Use existing patterns and libraries\n- Write secure code - avoid injection vulnerabilities (XSS, SQL injection, command injection)\n- Follow Python ML development best practices\n\n## Pre-Commit Checklist\n\nBefore submitting changes:\n\n1. ✅ Run tests: `uv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\"`\n2. ✅ Run pre-commit: `pre-commit run --all-files`\n3. ✅ Verify new functions have type hints + docstrings\n4. ✅ Review changes for minimal scope\n\n## Resources\n\n- **Docs:** https://rfdetr.roboflow.com\n- **Contributing:** `.github/CONTRIBUTING.md`\n- **Config:** `pyproject.toml`, `.pre-commit-config.yaml`\n- **Issues:** https://github.com/roboflow/rf-detr/issues\n\n## Maintaining Agentic Documentation\n\n**If your contribution:**\n\n- Changes project structure or introduces new patterns\n- Receives major feedback in PR review about conventions/patterns\n\n**Then update the relevant documents:**\n\n- This file (copilot-instructions.md) for high-level guidance\n- AGENTS.md for detailed technical patterns\n- CONTRIBUTING.md if it affects human contribution workflow\n\nThis ensures future contributions stay consistent and reduces repeated feedback.\n\n---\n\n**Note:** These instructions are GitHub Copilot-specific. When in doubt, refer to existing code patterns, contributing guidelines, and test files for examples.\n"},"files":{"AGENTS.md":"# RF-DETR - Agent Instructions\n\nThis file provides detailed technical context for AI coding agents working with RF-DETR.\n\n**Canonical Sources:**\n\n- **Contribution Guidelines:** [CONTRIBUTING.md](.github/CONTRIBUTING.md) - The authoritative source for all contribution practices\n- **Human Documentation:** [README.md](README.md) - Project overview and usage\n- **Copilot Instructions:** [.github/copilot-instructions.md](.github/copilot-instructions.md) - GitHub Copilot-specific guidance\n\nThis document supplements the contribution guidelines with detailed technical information for automated tooling.\n\n## Agent Responsibilities\n\nAs an AI agent contributing to RF-DETR, you are responsible for:\n\n1. **Following test-driven development practices**\n\n    - Write failing tests first for bug fixes\n    - Write comprehensive tests for new features\n    - Ensure final PR commit has all tests passing\n\n2. **Adhering to code quality standards**\n\n    - Run `pre-commit run --all-files` before every commit\n    - Follow type hint and docstring requirements\n    - Prefer direct project imports; conventional third-party aliases are allowed\n\n3. **Maintaining agentic documentation**\n\n    - Update `AGENTS.md` when architecture patterns or technical conventions change\n    - Update `.github/copilot-instructions.md` when high-level guidance changes\n    - Update `.github/CONTRIBUTING.md` when human workflow is affected\n    - Apply updates after receiving major feedback in PR reviews\n\n4. **Consulting maintainers before major changes**\n\n    - Open an issue before adding new models or significant features\n    - Wait for approval on approach before implementing\n\n5. **Writing secure, minimal code**\n\n    - Avoid over-engineering and unnecessary abstractions\n    - Write secure code (prevent injection vulnerabilities)\n    - Follow existing patterns in the codebase\n\n> [!NOTE]\n>\n> Keeping documentation current ensures consistency across agent contributions and reduces repeated feedback on the same issues.\n\n## Build & Development Environment\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Development Environment Setup](.github/CONTRIBUTING.md#development-environment-setup) in CONTRIBUTING.md for complete setup instructions.\n\n### Setup\n\n```bash\n# Install uv (if not already installed)\npip install uv\n\n# Full development environment (always use this)\nuv sync --all-groups\n```\n\n**Prerequisites:** Python >=3.10 (tested on 3.10-3.13)\n\n### Dependency Information\n\nSee `pyproject.toml` for complete dependency specifications:\n\n- **Core:** PyTorch, torchvision, transformers, supervision, pydantic, pyDeprecate\n- **Optional:** `[train]` (minimal training loop dependencies), `[augment]` (custom Albumentations CPU augmentations and Kornia GPU augmentations), `[lora]` (LoRA fine-tuning), `[plus]` (Plus models), `[onnx]` (ONNX export), `[loggers]` (tensorboard, wandb, mlflow, clearml)\n- **Development:** `tests`, `docs`, `build` groups\n\n**Important version constraints:**\n\n- PyTorch: >=2.2.0, \\<3.0.0\n- Transformers: >=5.0.0, \\<6.0.0\n\n## Testing\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Test-Driven Development](.github/CONTRIBUTING.md#test-driven-development) in CONTRIBUTING.md for complete guidelines.\n>\n> **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.\n\n### Commands\n\n```bash\n# CPU tests (default for local development; mirrors CI)\nuv run --no-sync pytest src/ tests/ -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\n\n# GPU tests (requires GPU; mirrors CI)\nuv 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\n\n# Pre-commit checks (ALWAYS run before committing)\npre-commit run --all-files\n```\n\n### Testing Principles\n\n> [!IMPORTANT]\n>\n> **Testing Requirements:**\n>\n> - ⚠️ **During development:** Tests may fail as you work through TDD cycle\n> - ✅ **Before opening PR:** Final commit MUST have all tests passing\n> - ✅ **Before each commit:** Run `pre-commit run --all-files`\n\n**Test-Driven Development:**\n\n1. **Bug fixes:** Write failing test → Fix code → Verify all tests pass\n2. **New features:** Write comprehensive tests → Implement feature → Refactor\n\n**Test Organization:**\n\n- Group related tests in classes\n- Use `@pytest.mark.parametrize` with `pytest.param(..., id=\"name\")`\n- Mark GPU/heavy tests with `@pytest.mark.gpu`\n- Avoid multiple validation cases in a single test - see [CONTRIBUTING.md](.github/CONTRIBUTING.md#avoid-multiple-validation-cases-in-a-single-test) for details\n- 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.\n- 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.\n\n**CI Information:** See [CI Testing](.github/CONTRIBUTING.md#ci-testing) in CONTRIBUTING.md for details on OS/Python version matrix and workflow configurations.\n\n## Code Quality & Linting\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Code Quality and Linting](.github/CONTRIBUTING.md#code-quality-and-linting) in CONTRIBUTING.md for setup and details.\n\n### Command\n\n```bash\n# Always run full pre-commit (not individual tools)\npre-commit run --all-files\n```\n\n> [!TIP]\n>\n> Pre-commit hooks will auto-format many issues. Review changes and re-stage files.\n\n**Configuration Files:**\n\n- `.pre-commit-config.yaml` - Pre-commit hooks (ruff, mdformat, prettier, codespell, license headers)\n- `pyproject.toml` - Ruff linting rules (`[tool.ruff]` section)\n\n**Abstraction Discipline:**\n\n- 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.\n- 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.\n\n**License Header (required for all Python files):**\n\n```python\n# ------------------------------------------------------------------------\n# RF-DETR\n# Copyright (c) 2025 Roboflow. All Rights Reserved.\n# Licensed under the Apache License, Version 2.0 [see LICENSE for details]\n# ------------------------------------------------------------------------\n```\n\n## Documentation\n\n### Building Docs\n\n```bash\n# Full install (matches CI — required for XLarge/2XLarge model pages)\nuv pip install -e \".[plus]\" --group docs\n\n# Serve locally (live reload)\nuv run mkdocs serve\n\n# Build static site\nuv run mkdocs build\n```\n\n**Documentation Structure:**\n\n- **Source:** `docs/` directory (Markdown)\n- **Config:** `mkdocs.yaml` (uses custom YAML tags: `!!python/name`)\n- **Deployment:** GitHub Actions publishes to GitHub Pages\n\n**Note:** `mkdocs.yaml` is checked by the `check-yaml` pre-commit hook with `--unsafe` so custom YAML tags such as `!!python/name` are accepted.\n\n## Package Building\n\n```bash\n# Install build dependencies\nuv sync --group build\n\n# Build distributions\nuv build\n\n# Validate build\nuv run twine check --strict dist/*\n```\n\n**Build outputs:**\n\n- Source distribution: `dist/rfdetr-*.tar.gz`\n- Wheel: `dist/rfdetr-*.whl`\n\n## Project Structure\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Project Structure](.github/CONTRIBUTING.md#project-structure) in CONTRIBUTING.md for complete project organization, directory descriptions, and configuration files.\n>\n> **Quick summary:** `src/rfdetr/` (source code), `tests/` (test suite), `docs/` (documentation), `.github/` (CI/CD), `pyproject.toml` (dependencies and config).\n>\n> Internal package organization within `src/rfdetr/` is subject to change as this is an active research and development project.\n\n## Architecture & Conventions\n\n### Key Patterns\n\n**Augmentations:**\n\n- Default training, validation, prediction, and export preprocessing use torchvision-native transforms.\n- Custom non-empty `aug_config` values on the CPU path use Albumentations and require `rfdetr[augment]`.\n- `augmentation_backend=\"gpu\"` uses Kornia and requires `rfdetr[augment]`; `augmentation_backend=\"auto\"` falls back to CPU when CUDA or Kornia is unavailable.\n\n**Model Architecture:**\n\n- RFDETR wrappers: `self.model` is the model context returned by `get_model()`\n- Underlying PyTorch module: `self.model.model`\n- Segmentation models return `pred_masks` as `torch.Tensor` or dict with keys `['spatial_features', 'query_features', 'bias']`\n\n**Model Selection (examples, docs, tests, defaults):**\n\n- **Default to `RFDETRSmall` / `\"rfdetr-small\"`.** Use it wherever an example needs a concrete detection model.\n- **Never use base models** (`RFDETRBase` / `\"rfdetr-base\"`) in new examples, docs, or tests — treat as deprecated; substitute `small`.\n- **Released detection sizes** — `nano`, `small`, `medium`, `large` (plus `xlarge`/`2xlarge` Plus models). Always pick one of these for plain object detection; never a `-preview` variant.\n- **Released segmentation sizes** — `RFDETRSegNano`/`Small`/`Medium`/`Large` / `\"rfdetr-seg-{nano,small,medium,large}\"` (plus `xlarge`/`2xlarge`). Use a sized seg model for segmentation; `RFDETRSegPreview` / `\"rfdetr-seg-preview\"` is now superseded — do not use it in new examples, docs, or tests.\n- **`-preview` variants** are for capabilities with **no released sized version yet**. Only keypoints remain preview-only: `RFDETRKeypointPreview` / `\"rfdetr-keypoint-preview\"`. Use a preview variant **only** for that task — never as a stand-in for detection or segmentation.\n\n**Imports:**\n\n- Keep imports at module scope by default. Use a local import only for a verified circular-import boundary, optional dependency boundary, import-behavior test, or material startup/side-effect constraint; the reason must be evident from the surrounding code or documented where it is not obvious.\n\n```python\n# Prefer direct project imports. Standard aliases such as `numpy as np`,\n# `torch.nn.functional as F`, and lazy module aliases are allowed when conventional.\nfrom rfdetr.utilities.distributed import get_rank, get_world_size, is_main_process, save_on_master\nfrom rfdetr.utilities.logger import get_logger\n\n# Logger usage\nlogger = get_logger()  # Default name: \"rf-detr\", reads LOG_LEVEL env var\n\n# TQDM (environment compatibility)\nfrom tqdm.auto import tqdm  # NOT: from tqdm import tqdm\n```\n\n**Plus Models (XLarge, 2XLarge):**\n\n- Requires separate `rfdetr_plus` package (PML 1.0 license)\n- Import handled lazily via `__getattr__` in `src/rfdetr/platform/models.py`\n- Raises `ImportError` if package not installed\n\n**Subprocess Usage:**\n\n```python\nimport subprocess\n\nresult = subprocess.run(\n    [\"command\", \"arg1\", \"arg2\"],\n    check=True,  # Raise CalledProcessError on failure\n    text=True,  # Return stdout/stderr as strings\n    capture_output=True,\n)\n# Note: stderr is already a string, don't decode\n```\n\n**Logging:**\n\n- Use `logger.debug()` for detailed tensor/shape information (not `logger.info()`)\n- Use `logger.info()` for high-level progress/status\n\n**Checkpoint Handling:**\n\n- Always check file existence before operations\n- Prevents errors when training is interrupted\n\n### Type Hints & Docstrings\n\n> [!IMPORTANT]\n>\n> **Canonical Reference:** See [Google-Style Docstrings and Mandatory Type Hints](.github/CONTRIBUTING.md#google-style-docstrings-and-mandatory-type-hints) in CONTRIBUTING.md for complete requirements and examples.\n>\n> **Requirements:**\n>\n> - MANDATORY type hints for all function parameters and return types\n> - MANDATORY Google-style docstrings for all functions and classes\n> - **Do not duplicate types in docstrings** - types are in the function signature\n> - Target Python version: 3.10+\n> - **Helper functions in `tests/` need a doctest too**: any non-`test_*` function used by tests (fixture builders, assertion helpers, reference implementations) needs a docstring with an `Examples` doctest that exercises it directly — `pyproject.toml` runs `--doctest-plus` across `tests/` on purpose. Skip the live doctest (`# doctest: +SKIP` + one-line reason) only when the helper can't run standalone (e.g. a `@pytest.fixture`, or needs real GPU/XLA/network hardware).\n\n## Common Workflows\n\n### Making Changes\n\n1. **Setup:** `uv sync --all-groups`\n2. **Before changes:** Run tests to establish baseline\n3. **Development:**\n    - Make minimal, focused changes\n    - Follow existing patterns and conventions\n    - Add type hints and docstrings\n4. **Testing:**\n    - Bug fixes: Write test first, then fix\n    - Features: Test all major use cases\n    - Run: `uv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\" --ignore=tests/run_smoke_all_models.py --ignore=tests/legacy/test_checkpoint_compat.py --timeout=240 --durations=50`\n5. **Quality checks:** `pre-commit run --all-files`\n6. **Build (if needed):** `uv build`\n7. **Commit:** Pre-commit hooks run automatically\n\n### Adding New Model Variants\n\n> [!IMPORTANT]\n>\n> **Canonical Reference:** See [Adding a New Model](.github/CONTRIBUTING.md#adding-a-new-model) in CONTRIBUTING.md for detailed guidance.\n>\n> Always consult maintainers before implementing new models.\n\n### Security Considerations\n\n- **Write secure code:** Avoid injection vulnerabilities (XSS, SQL injection, command injection)\n- **Validate inputs:** Especially for file paths, URLs, and user-provided data\n- **No credentials:** Never commit API keys, tokens, or credentials\n- **Follow OWASP best practices**\n\n## CI/CD Workflows\n\nGitHub Actions workflows in `.github/workflows/`:\n\n- **ci-tests-cpu.yml:** CPU tests across OS/Python versions\n- **ci-tests-gpu.yml:** GPU-dependent tests\n- **ci-legacy-checkpoints.yml:** Backward-compatibility checkpoint-loading tests across historical rfdetr releases (advisory only — not a required check; a compat break does not block merge)\n- **ci-deps-resolution.yml:** Dependency resolution (`uv lock`) plus an install-plan check (`uv sync --dry-run`) for every extra on every Python interpreter allowed by requires-python (3.10-3.14). Resolution alone does not prove a pinned version ships a wheel for the interpreter in use. The `list-extras` job derives the checked set from every `[project.optional-dependencies]` extra, so a new extra is covered automatically\n- **build-package.yml:** Build and validate distributions\n- **ci-build-docs.yml:** Documentation builds\n- **publish-docs.yml:** Deploy docs to GitHub Pages\n\n**Concurrency:** PRs cancel in-progress runs on new pushes\n\n## Additional Resources\n\n- **Documentation:** https://rfdetr.roboflow.com\n- **Repository:** https://github.com/roboflow/rf-detr\n- **Issues:** https://github.com/roboflow/rf-detr/issues\n- **Discord:** https://discord.gg/GbfgXGJ8Bk\n- **Contributing:** `.github/CONTRIBUTING.md`\n- **Copilot Instructions:** `.github/copilot-instructions.md`\n\n---\n\n**Note:** This file is designed for AI coding agents. For human-readable project information, see README.md. For contribution guidelines, see CONTRIBUTING.md.\n","CLAUDE.md":"# Claude Code Project Instructions\n\n<!-- Imports AGENTS.md, which contains agent roles, behavioral rules, and coding constraints for this project. -->\n\n@AGENTS.md\n",".github/copilot-instructions.md":"# RF-DETR Copilot Instructions\n\n> [!NOTE]\n>\n> This document is GitHub Copilot-specific guidance. For canonical contribution guidelines (test-driven development, code quality, docstrings, etc.), see [CONTRIBUTING.md](CONTRIBUTING.md). For detailed agent-specific context, see [AGENTS.md](../AGENTS.md).\n\n## Repository Overview\n\nRF-DETR is a real-time transformer architecture for object detection and instance segmentation. Built on DINOv2 vision transformer backbone with PyTorch.\n\n- **Project Type:** Python ML library (computer vision)\n- **Python:** >=3.10 (3.10, 3.11, 3.12, 3.13)\n- **License:** Apache 2.0 (Plus models under PML 1.0)\n\n> [!TIP]\n>\n> - **Configuration:** See `pyproject.toml` for dependencies, build settings, and tool configurations.\n> - **Contributing:** See `.github/CONTRIBUTING.md` for contribution guidelines, CLA, and coding standards.\n\n## Quick Start\n\n**Package Manager:** This project uses `uv` for all dependency management.\n\n```bash\n# Development setup\nuv sync --all-groups\n\n# Run tests (always before committing)\nuv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\" --cov=rfdetr --cov-report=xml\n\n# Build package\nuv build\n```\n\n> [!IMPORTANT]\n>\n> Run `uv sync` after pulling changes to update dependencies.\n\n**Dependency extras:** `rfdetr[train]` is intentionally minimal and uses torchvision-native default augmentations. Custom Albumentations CPU configs and Kornia GPU augmentation both require `rfdetr[augment]`.\n\n## Code Quality\n\n**Linting & Formatting:** All code must pass pre-commit checks. See **[Code Quality and Linting](CONTRIBUTING.md#code-quality-and-linting)** in CONTRIBUTING.md for setup and details.\n\n```bash\npre-commit run --all-files\n```\n\n> **Configuration:** `.pre-commit-config.yaml` (hooks) and `[tool.ruff]` in `pyproject.toml` (Python linting)\n\n## Key Conventions\n\n> [!NOTE]\n>\n> Internal package organization (`src/rfdetr/`) is subject to change as this is an active research project. Explore the codebase to understand current module organization.\n\n**Imports:**\n\n- Always use direct imports: `from rfdetr.utilities.distributed import get_rank, is_main_process`\n- Logger: `from rfdetr.utilities.logger import get_logger` (reads `LOG_LEVEL` env var)\n- **Never use** `rfdetr.util.*` or `rfdetr.deploy.*` — deprecated shims scheduled for removal in v1.9.0\n- TQDM: `from tqdm.auto import tqdm` (NOT `from tqdm import tqdm`)\n\n## Testing & Development Workflow\n\n**Test-Driven Development:** Follow TDD practices - write tests first for bugs, comprehensive tests for features. See **[Test-Driven Development](CONTRIBUTING.md#test-driven-development)** in CONTRIBUTING.md for detailed guidelines.\n\n**Quick reference:**\n\n- Bug fixes: Write failing test → Fix → Verify all pass\n- Features: Write comprehensive tests → Implement → Refactor\n- Use test classes and `@pytest.mark.parametrize` for organization\n- Mark GPU/heavy tests with `@pytest.mark.gpu`\n\n**Testing Requirements:**\n\n- ⚠️ During development: Tests may fail (TDD cycle is fine)\n- ✅ Before PR: Final commit MUST have all tests passing\n- ✅ Before commit: Run `pre-commit run --all-files`\n\n**CI/CD:** See `.github/workflows/` for source of truth. Tests run on Python 3.10-3.13 across Ubuntu, Windows, macOS.\n\n## Coding Standards\n\n**Type Hints & Docstrings:** MANDATORY for all functions/classes. See **[Google-Style Docstrings and Mandatory Type Hints](CONTRIBUTING.md#google-style-docstrings-and-mandatory-type-hints)** in CONTRIBUTING.md for examples.\n\n**Import Conventions:**\n\n```python\n# Always use direct imports (NOT import ... as pattern)\nfrom rfdetr.utilities.distributed import get_rank, is_main_process, save_on_master\nfrom rfdetr.utilities.logger import get_logger\n\n# TQDM (for environment compatibility)\nfrom tqdm.auto import tqdm  # NOT from tqdm import tqdm\n```\n\n**Project-Specific Patterns:**\n\n- **Model selection:** Default to `RFDETRSmall` / `\"rfdetr-small\"` in examples, docs, and tests. **Never use base models** (`RFDETRBase` / `\"rfdetr-base\"`) — treat as deprecated, substitute `small`. Pick a released detection size (`nano`/`small`/`medium`/`large`) for detection and a released segmentation size (`seg-nano`/`seg-small`/`seg-medium`/`seg-large`) for segmentation; `-preview` variants are only for capabilities with no released sized version — now just `keypoint-preview`. `seg-preview` is superseded; use a sized seg model instead.\n- **Logging:** Use `logger.debug()` for detailed tensor/shape info (not `logger.info()`)\n- **Segmentation models:** Return `pred_masks` as `torch.Tensor` or dict with keys `['spatial_features', 'query_features', 'bias']`\n- **Checkpoint handling:** Always check file existence before operations\n- **License headers:** All Python files require Apache 2.0 header (enforced by pre-commit)\n\n**Best Practices:**\n\n- Make minimal, surgical changes - avoid over-engineering\n- Use existing patterns and libraries\n- Write secure code - avoid injection vulnerabilities (XSS, SQL injection, command injection)\n- Follow Python ML development best practices\n\n## Pre-Commit Checklist\n\nBefore submitting changes:\n\n1. ✅ Run tests: `uv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\"`\n2. ✅ Run pre-commit: `pre-commit run --all-files`\n3. ✅ Verify new functions have type hints + docstrings\n4. ✅ Review changes for minimal scope\n\n## Resources\n\n- **Docs:** https://rfdetr.roboflow.com\n- **Contributing:** `.github/CONTRIBUTING.md`\n- **Config:** `pyproject.toml`, `.pre-commit-config.yaml`\n- **Issues:** https://github.com/roboflow/rf-detr/issues\n\n## Maintaining Agentic Documentation\n\n**If your contribution:**\n\n- Changes project structure or introduces new patterns\n- Receives major feedback in PR review about conventions/patterns\n\n**Then update the relevant documents:**\n\n- This file (copilot-instructions.md) for high-level guidance\n- AGENTS.md for detailed technical patterns\n- CONTRIBUTING.md if it affects human contribution workflow\n\nThis ensures future contributions stay consistent and reduces repeated feedback.\n\n---\n\n**Note:** These instructions are GitHub Copilot-specific. When in doubt, refer to existing code patterns, contributing guidelines, and test files for examples.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# RF-DETR - Agent Instructions\n\nThis file provides detailed technical context for AI coding agents working with RF-DETR.\n\n**Canonical Sources:**\n\n- **Contribution Guidelines:** [CONTRIBUTING.md](.github/CONTRIBUTING.md) - The authoritative source for all contribution practices\n- **Human Documentation:** [README.md](README.md) - Project overview and usage\n- **Copilot Instructions:** [.github/copilot-instructions.md](.github/copilot-instructions.md) - GitHub Copilot-specific guidance\n\nThis document supplements the contribution guidelines with detailed technical information for automated tooling.\n\n## Agent Responsibilities\n\nAs an AI agent contributing to RF-DETR, you are responsible for:\n\n1. **Following test-driven development practices**\n\n    - Write failing tests first for bug fixes\n    - Write comprehensive tests for new features\n    - Ensure final PR commit has all tests passing\n\n2. **Adhering to code quality standards**\n\n    - Run `pre-commit run --all-files` before every commit\n    - Follow type hint and docstring requirements\n    - Prefer direct project imports; conventional third-party aliases are allowed\n\n3. **Maintaining agentic documentation**\n\n    - Update `AGENTS.md` when architecture patterns or technical conventions change\n    - Update `.github/copilot-instructions.md` when high-level guidance changes\n    - Update `.github/CONTRIBUTING.md` when human workflow is affected\n    - Apply updates after receiving major feedback in PR reviews\n\n4. **Consulting maintainers before major changes**\n\n    - Open an issue before adding new models or significant features\n    - Wait for approval on approach before implementing\n\n5. **Writing secure, minimal code**\n\n    - Avoid over-engineering and unnecessary abstractions\n    - Write secure code (prevent injection vulnerabilities)\n    - Follow existing patterns in the codebase\n\n> [!NOTE]\n>\n> Keeping documentation current ensures consistency across agent contributions and reduces repeated feedback on the same issues.\n\n## Build & Development Environment\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Development Environment Setup](.github/CONTRIBUTING.md#development-environment-setup) in CONTRIBUTING.md for complete setup instructions.\n\n### Setup\n\n```bash\n# Install uv (if not already installed)\npip install uv\n\n# Full development environment (always use this)\nuv sync --all-groups\n```\n\n**Prerequisites:** Python >=3.10 (tested on 3.10-3.13)\n\n### Dependency Information\n\nSee `pyproject.toml` for complete dependency specifications:\n\n- **Core:** PyTorch, torchvision, transformers, supervision, pydantic, pyDeprecate\n- **Optional:** `[train]` (minimal training loop dependencies), `[augment]` (custom Albumentations CPU augmentations and Kornia GPU augmentations), `[lora]` (LoRA fine-tuning), `[plus]` (Plus models), `[onnx]` (ONNX export), `[loggers]` (tensorboard, wandb, mlflow, clearml)\n- **Development:** `tests`, `docs`, `build` groups\n\n**Important version constraints:**\n\n- PyTorch: >=2.2.0, \\<3.0.0\n- Transformers: >=5.0.0, \\<6.0.0\n\n## Testing\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Test-Driven Development](.github/CONTRIBUTING.md#test-driven-development) in CONTRIBUTING.md for complete guidelines.\n>\n> **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.\n\n### Commands\n\n```bash\n# CPU tests (default for local development; mirrors CI)\nuv run --no-sync pytest src/ tests/ -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\n\n# GPU tests (requires GPU; mirrors CI)\nuv 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\n\n# Pre-commit checks (ALWAYS run before committing)\npre-commit run --all-files\n```\n\n### Testing Principles\n\n> [!IMPORTANT]\n>\n> **Testing Requirements:**\n>\n> - ⚠️ **During development:** Tests may fail as you work through TDD cycle\n> - ✅ **Before opening PR:** Final commit MUST have all tests passing\n> - ✅ **Before each commit:** Run `pre-commit run --all-files`\n\n**Test-Driven Development:**\n\n1. **Bug fixes:** Write failing test → Fix code → Verify all tests pass\n2. **New features:** Write comprehensive tests → Implement feature → Refactor\n\n**Test Organization:**\n\n- Group related tests in classes\n- Use `@pytest.mark.parametrize` with `pytest.param(..., id=\"name\")`\n- Mark GPU/heavy tests with `@pytest.mark.gpu`\n- Avoid multiple validation cases in a single test - see [CONTRIBUTING.md](.github/CONTRIBUTING.md#avoid-multiple-validation-cases-in-a-single-test) for details\n- 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.\n- 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.\n\n**CI Information:** See [CI Testing](.github/CONTRIBUTING.md#ci-testing) in CONTRIBUTING.md for details on OS/Python version matrix and workflow configurations.\n\n## Code Quality & Linting\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Code Quality and Linting](.github/CONTRIBUTING.md#code-quality-and-linting) in CONTRIBUTING.md for setup and details.\n\n### Command\n\n```bash\n# Always run full pre-commit (not individual tools)\npre-commit run --all-files\n```\n\n> [!TIP]\n>\n> Pre-commit hooks will auto-format many issues. Review changes and re-stage files.\n\n**Configuration Files:**\n\n- `.pre-commit-config.yaml` - Pre-commit hooks (ruff, mdformat, prettier, codespell, license headers)\n- `pyproject.toml` - Ruff linting rules (`[tool.ruff]` section)\n\n**Abstraction Discipline:**\n\n- 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.\n- 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.\n\n**License Header (required for all Python files):**\n\n```python\n# ------------------------------------------------------------------------\n# RF-DETR\n# Copyright (c) 2025 Roboflow. All Rights Reserved.\n# Licensed under the Apache License, Version 2.0 [see LICENSE for details]\n# ------------------------------------------------------------------------\n```\n\n## Documentation\n\n### Building Docs\n\n```bash\n# Full install (matches CI — required for XLarge/2XLarge model pages)\nuv pip install -e \".[plus]\" --group docs\n\n# Serve locally (live reload)\nuv run mkdocs serve\n\n# Build static site\nuv run mkdocs build\n```\n\n**Documentation Structure:**\n\n- **Source:** `docs/` directory (Markdown)\n- **Config:** `mkdocs.yaml` (uses custom YAML tags: `!!python/name`)\n- **Deployment:** GitHub Actions publishes to GitHub Pages\n\n**Note:** `mkdocs.yaml` is checked by the `check-yaml` pre-commit hook with `--unsafe` so custom YAML tags such as `!!python/name` are accepted.\n\n## Package Building\n\n```bash\n# Install build dependencies\nuv sync --group build\n\n# Build distributions\nuv build\n\n# Validate build\nuv run twine check --strict dist/*\n```\n\n**Build outputs:**\n\n- Source distribution: `dist/rfdetr-*.tar.gz`\n- Wheel: `dist/rfdetr-*.whl`\n\n## Project Structure\n\n> [!NOTE]\n>\n> **Canonical Reference:** See [Project Structure](.github/CONTRIBUTING.md#project-structure) in CONTRIBUTING.md for complete project organization, directory descriptions, and configuration files.\n>\n> **Quick summary:** `src/rfdetr/` (source code), `tests/` (test suite), `docs/` (documentation), `.github/` (CI/CD), `pyproject.toml` (dependencies and config).\n>\n> Internal package organization within `src/rfdetr/` is subject to change as this is an active research and development project.\n\n## Architecture & Conventions\n\n### Key Patterns\n\n**Augmentations:**\n\n- Default training, validation, prediction, and export preprocessing use torchvision-native transforms.\n- Custom non-empty `aug_config` values on the CPU path use Albumentations and require `rfdetr[augment]`.\n- `augmentation_backend=\"gpu\"` uses Kornia and requires `rfdetr[augment]`; `augmentation_backend=\"auto\"` falls back to CPU when CUDA or Kornia is unavailable.\n\n**Model Architecture:**\n\n- RFDETR wrappers: `self.model` is the model context returned by `get_model()`\n- Underlying PyTorch module: `self.model.model`\n- Segmentation models return `pred_masks` as `torch.Tensor` or dict with keys `['spatial_features', 'query_features', 'bias']`\n\n**Model Selection (examples, docs, tests, defaults):**\n\n- **Default to `RFDETRSmall` / `\"rfdetr-small\"`.** Use it wherever an example needs a concrete detection model.\n- **Never use base models** (`RFDETRBase` / `\"rfdetr-base\"`) in new examples, docs, or tests — treat as deprecated; substitute `small`.\n- **Released detection sizes** — `nano`, `small`, `medium`, `large` (plus `xlarge`/`2xlarge` Plus models). Always pick one of these for plain object detection; never a `-preview` variant.\n- **Released segmentation sizes** — `RFDETRSegNano`/`Small`/`Medium`/`Large` / `\"rfdetr-seg-{nano,small,medium,large}\"` (plus `xlarge`/`2xlarge`). Use a sized seg model for segmentation; `RFDETRSegPreview` / `\"rfdetr-seg-preview\"` is now superseded — do not use it in new examples, docs, or tests.\n- **`-preview` variants** are for capabilities with **no released sized version yet**. Only keypoints remain preview-only: `RFDETRKeypointPreview` / `\"rfdetr-keypoint-preview\"`. Use a preview variant **only** for that task — never as a stand-in for detection or segmentation.\n\n**Imports:**\n\n- Keep imports at module scope by default. Use a local import only for a verified circular-import boundary, optional dependency boundary, import-behavior test, or material startup/side-effect constraint; the reason must be evident from the surrounding code or documented where it is not obvious.\n\n```python\n# Prefer direct project imports. Standard aliases such as `numpy as np`,\n# `torch.nn.functional as F`, and lazy module aliases are allowed when conventional.\nfrom rfdetr.utilities.distributed import get_rank, get_world_size, is_main_process, save_on_master\nfrom rfdetr.utilities.logger import get_logger\n\n# Logger usage\nlogger = get_logger()  # Default name: \"rf-detr\", reads LOG_LEVEL env var\n\n# TQDM (environment compatibility)\nfrom tqdm.auto import tqdm  # NOT: from tqdm import tqdm\n```\n\n**Plus Models (XLarge, 2XLarge):**\n\n- Requires separate `rfdetr_plus` package (PML 1.0 license)\n- Import handled lazily via `__getattr__` in `src/rfdetr/platform/models.py`\n- Raises `ImportError` if package not installed\n\n**Subprocess Usage:**\n\n```python\nimport subprocess\n\nresult = subprocess.run(\n    [\"command\", \"arg1\", \"arg2\"],\n    check=True,  # Raise CalledProcessError on failure\n    text=True,  # Return stdout/stderr as strings\n    capture_output=True,\n)\n# Note: stderr is already a string, don't decode\n```\n\n**Logging:**\n\n- Use `logger.debug()` for detailed tensor/shape information (not `logger.info()`)\n- Use `logger.info()` for high-level progress/status\n\n**Checkpoint Handling:**\n\n- Always check file existence before operations\n- Prevents errors when training is interrupted\n\n### Type Hints & Docstrings\n\n> [!IMPORTANT]\n>\n> **Canonical Reference:** See [Google-Style Docstrings and Mandatory Type Hints](.github/CONTRIBUTING.md#google-style-docstrings-and-mandatory-type-hints) in CONTRIBUTING.md for complete requirements and examples.\n>\n> **Requirements:**\n>\n> - MANDATORY type hints for all function parameters and return types\n> - MANDATORY Google-style docstrings for all functions and classes\n> - **Do not duplicate types in docstrings** - types are in the function signature\n> - Target Python version: 3.10+\n> - **Helper functions in `tests/` need a doctest too**: any non-`test_*` function used by tests (fixture builders, assertion helpers, reference implementations) needs a docstring with an `Examples` doctest that exercises it directly — `pyproject.toml` runs `--doctest-plus` across `tests/` on purpose. Skip the live doctest (`# doctest: +SKIP` + one-line reason) only when the helper can't run standalone (e.g. a `@pytest.fixture`, or needs real GPU/XLA/network hardware).\n\n## Common Workflows\n\n### Making Changes\n\n1. **Setup:** `uv sync --all-groups`\n2. **Before changes:** Run tests to establish baseline\n3. **Development:**\n    - Make minimal, focused changes\n    - Follow existing patterns and conventions\n    - Add type hints and docstrings\n4. **Testing:**\n    - Bug fixes: Write test first, then fix\n    - Features: Test all major use cases\n    - Run: `uv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\" --ignore=tests/run_smoke_all_models.py --ignore=tests/legacy/test_checkpoint_compat.py --timeout=240 --durations=50`\n5. **Quality checks:** `pre-commit run --all-files`\n6. **Build (if needed):** `uv build`\n7. **Commit:** Pre-commit hooks run automatically\n\n### Adding New Model Variants\n\n> [!IMPORTANT]\n>\n> **Canonical Reference:** See [Adding a New Model](.github/CONTRIBUTING.md#adding-a-new-model) in CONTRIBUTING.md for detailed guidance.\n>\n> Always consult maintainers before implementing new models.\n\n### Security Considerations\n\n- **Write secure code:** Avoid injection vulnerabilities (XSS, SQL injection, command injection)\n- **Validate inputs:** Especially for file paths, URLs, and user-provided data\n- **No credentials:** Never commit API keys, tokens, or credentials\n- **Follow OWASP best practices**\n\n## CI/CD Workflows\n\nGitHub Actions workflows in `.github/workflows/`:\n\n- **ci-tests-cpu.yml:** CPU tests across OS/Python versions\n- **ci-tests-gpu.yml:** GPU-dependent tests\n- **ci-legacy-checkpoints.yml:** Backward-compatibility checkpoint-loading tests across historical rfdetr releases (advisory only — not a required check; a compat break does not block merge)\n- **ci-deps-resolution.yml:** Dependency resolution (`uv lock`) plus an install-plan check (`uv sync --dry-run`) for every extra on every Python interpreter allowed by requires-python (3.10-3.14). Resolution alone does not prove a pinned version ships a wheel for the interpreter in use. The `list-extras` job derives the checked set from every `[project.optional-dependencies]` extra, so a new extra is covered automatically\n- **build-package.yml:** Build and validate distributions\n- **ci-build-docs.yml:** Documentation builds\n- **publish-docs.yml:** Deploy docs to GitHub Pages\n\n**Concurrency:** PRs cancel in-progress runs on new pushes\n\n## Additional Resources\n\n- **Documentation:** https://rfdetr.roboflow.com\n- **Repository:** https://github.com/roboflow/rf-detr\n- **Issues:** https://github.com/roboflow/rf-detr/issues\n- **Discord:** https://discord.gg/GbfgXGJ8Bk\n- **Contributing:** `.github/CONTRIBUTING.md`\n- **Copilot Instructions:** `.github/copilot-instructions.md`\n\n---\n\n**Note:** This file is designed for AI coding agents. For human-readable project information, see README.md. For contribution guidelines, see CONTRIBUTING.md.\n","category":"root","tokens":3845},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Claude Code Project Instructions\n\n<!-- Imports AGENTS.md, which contains agent roles, behavioral rules, and coding constraints for this project. -->\n\n@AGENTS.md\n","category":"root","tokens":41},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# RF-DETR Copilot Instructions\n\n> [!NOTE]\n>\n> This document is GitHub Copilot-specific guidance. For canonical contribution guidelines (test-driven development, code quality, docstrings, etc.), see [CONTRIBUTING.md](CONTRIBUTING.md). For detailed agent-specific context, see [AGENTS.md](../AGENTS.md).\n\n## Repository Overview\n\nRF-DETR is a real-time transformer architecture for object detection and instance segmentation. Built on DINOv2 vision transformer backbone with PyTorch.\n\n- **Project Type:** Python ML library (computer vision)\n- **Python:** >=3.10 (3.10, 3.11, 3.12, 3.13)\n- **License:** Apache 2.0 (Plus models under PML 1.0)\n\n> [!TIP]\n>\n> - **Configuration:** See `pyproject.toml` for dependencies, build settings, and tool configurations.\n> - **Contributing:** See `.github/CONTRIBUTING.md` for contribution guidelines, CLA, and coding standards.\n\n## Quick Start\n\n**Package Manager:** This project uses `uv` for all dependency management.\n\n```bash\n# Development setup\nuv sync --all-groups\n\n# Run tests (always before committing)\nuv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\" --cov=rfdetr --cov-report=xml\n\n# Build package\nuv build\n```\n\n> [!IMPORTANT]\n>\n> Run `uv sync` after pulling changes to update dependencies.\n\n**Dependency extras:** `rfdetr[train]` is intentionally minimal and uses torchvision-native default augmentations. Custom Albumentations CPU configs and Kornia GPU augmentation both require `rfdetr[augment]`.\n\n## Code Quality\n\n**Linting & Formatting:** All code must pass pre-commit checks. See **[Code Quality and Linting](CONTRIBUTING.md#code-quality-and-linting)** in CONTRIBUTING.md for setup and details.\n\n```bash\npre-commit run --all-files\n```\n\n> **Configuration:** `.pre-commit-config.yaml` (hooks) and `[tool.ruff]` in `pyproject.toml` (Python linting)\n\n## Key Conventions\n\n> [!NOTE]\n>\n> Internal package organization (`src/rfdetr/`) is subject to change as this is an active research project. Explore the codebase to understand current module organization.\n\n**Imports:**\n\n- Always use direct imports: `from rfdetr.utilities.distributed import get_rank, is_main_process`\n- Logger: `from rfdetr.utilities.logger import get_logger` (reads `LOG_LEVEL` env var)\n- **Never use** `rfdetr.util.*` or `rfdetr.deploy.*` — deprecated shims scheduled for removal in v1.9.0\n- TQDM: `from tqdm.auto import tqdm` (NOT `from tqdm import tqdm`)\n\n## Testing & Development Workflow\n\n**Test-Driven Development:** Follow TDD practices - write tests first for bugs, comprehensive tests for features. See **[Test-Driven Development](CONTRIBUTING.md#test-driven-development)** in CONTRIBUTING.md for detailed guidelines.\n\n**Quick reference:**\n\n- Bug fixes: Write failing test → Fix → Verify all pass\n- Features: Write comprehensive tests → Implement → Refactor\n- Use test classes and `@pytest.mark.parametrize` for organization\n- Mark GPU/heavy tests with `@pytest.mark.gpu`\n\n**Testing Requirements:**\n\n- ⚠️ During development: Tests may fail (TDD cycle is fine)\n- ✅ Before PR: Final commit MUST have all tests passing\n- ✅ Before commit: Run `pre-commit run --all-files`\n\n**CI/CD:** See `.github/workflows/` for source of truth. Tests run on Python 3.10-3.13 across Ubuntu, Windows, macOS.\n\n## Coding Standards\n\n**Type Hints & Docstrings:** MANDATORY for all functions/classes. See **[Google-Style Docstrings and Mandatory Type Hints](CONTRIBUTING.md#google-style-docstrings-and-mandatory-type-hints)** in CONTRIBUTING.md for examples.\n\n**Import Conventions:**\n\n```python\n# Always use direct imports (NOT import ... as pattern)\nfrom rfdetr.utilities.distributed import get_rank, is_main_process, save_on_master\nfrom rfdetr.utilities.logger import get_logger\n\n# TQDM (for environment compatibility)\nfrom tqdm.auto import tqdm  # NOT from tqdm import tqdm\n```\n\n**Project-Specific Patterns:**\n\n- **Model selection:** Default to `RFDETRSmall` / `\"rfdetr-small\"` in examples, docs, and tests. **Never use base models** (`RFDETRBase` / `\"rfdetr-base\"`) — treat as deprecated, substitute `small`. Pick a released detection size (`nano`/`small`/`medium`/`large`) for detection and a released segmentation size (`seg-nano`/`seg-small`/`seg-medium`/`seg-large`) for segmentation; `-preview` variants are only for capabilities with no released sized version — now just `keypoint-preview`. `seg-preview` is superseded; use a sized seg model instead.\n- **Logging:** Use `logger.debug()` for detailed tensor/shape info (not `logger.info()`)\n- **Segmentation models:** Return `pred_masks` as `torch.Tensor` or dict with keys `['spatial_features', 'query_features', 'bias']`\n- **Checkpoint handling:** Always check file existence before operations\n- **License headers:** All Python files require Apache 2.0 header (enforced by pre-commit)\n\n**Best Practices:**\n\n- Make minimal, surgical changes - avoid over-engineering\n- Use existing patterns and libraries\n- Write secure code - avoid injection vulnerabilities (XSS, SQL injection, command injection)\n- Follow Python ML development best practices\n\n## Pre-Commit Checklist\n\nBefore submitting changes:\n\n1. ✅ Run tests: `uv run --no-sync pytest src/ tests/ -n 2 -m \"not gpu\"`\n2. ✅ Run pre-commit: `pre-commit run --all-files`\n3. ✅ Verify new functions have type hints + docstrings\n4. ✅ Review changes for minimal scope\n\n## Resources\n\n- **Docs:** https://rfdetr.roboflow.com\n- **Contributing:** `.github/CONTRIBUTING.md`\n- **Config:** `pyproject.toml`, `.pre-commit-config.yaml`\n- **Issues:** https://github.com/roboflow/rf-detr/issues\n\n## Maintaining Agentic Documentation\n\n**If your contribution:**\n\n- Changes project structure or introduces new patterns\n- Receives major feedback in PR review about conventions/patterns\n\n**Then update the relevant documents:**\n\n- This file (copilot-instructions.md) for high-level guidance\n- AGENTS.md for detailed technical patterns\n- CONTRIBUTING.md if it affects human contribution workflow\n\nThis ensures future contributions stay consistent and reduces repeated feedback.\n\n---\n\n**Note:** These instructions are GitHub Copilot-specific. When in doubt, refer to existing code patterns, contributing guidelines, and test files for examples.\n","category":".github","tokens":1533}]}