chore: import upstream snapshot with attribution

.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# These owners will be the default owners for everything in the repo.
+# They will be requested for review when someone opens a pull request.
+* @SkalskiP @Borda @probicheaux @isaacrob
+
+# supervise the core model modules
+/rfdetr                 @probicheaux @isaacrob @Matvezy
+
+# supervise the training modules
+/src/rfdetr/training/   @Borda @probicheaux @isaacrob
+/tests/training/        @Borda @probicheaux @isaacrob

.github/CONTRIBUTING.md

@@ -0,0 +1,497 @@
+# Contributing to RF-DETR
+
+Thank you for helping to advance RF-DETR! Your participation is invaluable in evolving our platform—whether you’re squashing bugs, refining documentation, or rolling out new features. Every contribution pushes the project forward.
+
+## Table of Contents
+
+1. [How to Contribute](#how-to-contribute)
+2. [Project Structure](#project-structure)
+3. [Development Environment Setup](#development-environment-setup)
+4. [Test-Driven Development](#test-driven-development)
+5. [Code Quality and Linting](#code-quality-and-linting)
+6. [Deprecation Policy](#deprecation-policy)
+7. [Building Documentation](#building-documentation)
+8. [CLA Signing](#cla-signing)
+9. [Google-Style Docstrings and Mandatory Type Hints](#google-style-docstrings-and-mandatory-type-hints)
+10. [Reporting Bugs](#reporting-bugs)
+11. [Adding a New Model](#adding-a-new-model)
+12. [Security Considerations](#security-considerations)
+13. [License](#license)
+
+## How to Contribute
+
+Your contributions can be in many forms—whether it’s enhancing existing features, improving documentation, resolving bugs, or proposing new ideas. Here’s a high-level overview to get you started:
+
+1. [Fork the Repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo): Click the “Fork” button on our GitHub page to create your own copy.
+2. [Clone Locally](https://docs.github.com/en/enterprise-server@3.11/repositories/creating-and-managing-repositories/cloning-a-repository): Download your fork to your local development environment.
+3. [Create a Branch](https://docs.github.com/en/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop): Use a descriptive name with appropriate prefix:
+    ```bash
+    # Branch naming convention: {type}/{issue_number}-name_or_description
+    git checkout -b fix/123-authentication_bug
+    git checkout -b feat/678-add_export_support
+    git checkout -b docs/update_readme
+    ```
+    **Prefixes:** `fix/` (bug fixes), `feat/` (new features), `docs/` (documentation), `refactor/`, `test/`, `chore/`
+4. Develop Your Changes: Make your updates, ensuring your commit messages clearly describe your modifications.
+5. [Commit and Push](https://docs.github.com/en/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop): Run:
+    ```bash
+    git add .
+    git commit -m "A brief description of your changes"
+    git push -u origin your-descriptive-name
+    ```
+6. [Open a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request): Submit your pull request against the main development branch. Please detail your changes and link any related issues.
+
+Before merging, check that all tests pass and that your changes adhere to our development and documentation standards.
+
+## Project Structure
+
+Understanding the project structure will help you navigate the codebase and make contributions effectively.
+
+```
+rf-detr/
+├── .github/              # GitHub configuration
+│   ├── workflows/        # CI/CD pipelines (tests, builds, docs deployment)
+│   ├── CONTRIBUTING.md   # This file - contribution guidelines
+│   ├── copilot-instructions.md  # GitHub Copilot-specific guidance
+│   └── ISSUE_TEMPLATE/   # Issue templates
+├── docs/                 # Documentation source (MkDocs)
+│   ├── *.md              # Documentation pages
+│   └── assets/           # Images and other assets
+├── src/rfdetr/           # Main package source code
+│   ├── __init__.py       # Package entry point
+│   └── ...               # Other modules (models, datasets, utils, etc.)
+├── tests/                # Test suite
+│   ├── test_*.py         # Test files
+│   └── conftest.py       # Pytest configuration and fixtures
+├── pyproject.toml        # Project metadata, dependencies, tool configurations
+├── mkdocs.yaml           # Documentation configuration
+├── .pre-commit-config.yaml  # Pre-commit hooks configuration
+├── README.md             # Project overview and quick start
+├── LICENSE               # Apache 2.0 license
+└── AGENTS.md             # AI agent-specific technical documentation
+```
+
+**Key Directories:**
+
+- **`src/rfdetr/`** - All source code for the RF-DETR package
+
+    - Contains models, datasets, training logic, deployment utilities, and more
+    - Internal organization may change as the project evolves
+
+- **`tests/`** - Comprehensive test suite
+
+    - Unit tests, integration tests, and end-to-end tests
+    - Use `@pytest.mark.gpu` for GPU-dependent tests
+
+- **`docs/`** - Documentation source files
+
+    - Written in Markdown, built with MkDocs
+    - Published to https://rfdetr.roboflow.com
+
+- **`.github/`** - GitHub-specific configuration
+
+    - CI/CD workflows define automated testing and deployment
+    - Contributing guidelines and issue templates
+
+**Important Configuration Files:**
+
+- **`pyproject.toml`** - Single source of truth for:
+
+    - Project metadata and dependencies
+    - Tool configurations (ruff, pytest, coverage, etc.)
+    - Build system configuration
+
+- **`.pre-commit-config.yaml`** - Defines pre-commit hooks for code quality
+
+- **`mkdocs.yaml`** - Documentation site configuration
+
+> [!TIP]
+> When contributing, focus on the relevant directory for your change:
+>
+> - Bug fixes/features → `src/rfdetr/` and `tests/`
+> - Documentation → `docs/`
+> - CI/build issues → `.github/workflows/` or config files
+
+## Development Environment Setup
+
+RF-DETR uses **`uv`** as the package manager for dependency management. Ensure you have Python >=3.10 installed (supports 3.10, 3.11, 3.12, 3.13).
+
+### Installing uv
+
+```bash
+pip install uv
+```
+
+### Setting Up Your Development Environment
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/rf-detr.git
+cd rf-detr
+
+# Install all development dependencies
+uv sync --all-groups
+
+# Or install specific dependency groups
+uv sync --group tests      # Testing dependencies only
+uv sync --group docs       # Documentation dependencies only
+uv sync --group build      # Build tools only
+```
+
+**Important:** Always run `uv sync` after pulling changes to ensure your dependencies are up to date.
+
+### Running Tests
+
+> **CI Workflows as Source of Truth:** See `.github/workflows/ci-tests-cpu.yml` and `.github/workflows/ci-tests-gpu.yml` for the exact commands used in continuous integration.
+
+```bash
+# Run CPU tests (default for local development; mirrors CI)
+uv run --no-sync pytest src/ tests/ -n 2 -m "not gpu" --ignore=tests/run_smoke_all_models.py --cov=rfdetr --cov-report=xml --timeout=240 --durations=50
+
+# Run GPU tests (requires GPU; mirrors CI)
+uv run --no-sync pytest tests/ -m gpu -n 3 --reruns 1 --only-rerun "OutOfMemoryError" --cov=rfdetr --cov-report=xml --timeout=600 --durations=20
+```
+
+**Development vs. PR Requirements:**
+
+- **During development:** Tests may fail as you work through TDD cycle (write failing test → implement → fix)
+- **Before opening PR:** Your final commit MUST have all tests passing
+- **Before each commit:** Run `pre-commit run --all-files` to ensure code quality
+
+### Building the Package
+
+```bash
+# Build source and wheel distributions
+uv build
+
+# Validate the build
+uv run twine check --strict dist/*
+```
+
+## Test-Driven Development
+
+We follow test-driven development practices to ensure code quality and prevent regressions.
+
+### For Bug Fixes
+
+1. **Write a test that replicates the issue** - The test should fail initially, demonstrating the bug
+2. **Commit the failing test** (optional during development, but commit message should note "WIP" or "test for issue #XXX")
+3. **Implement the fix** - Make the minimal change needed to make the test pass
+4. **Verify all tests pass** - Ensure your fix doesn't break existing functionality
+5. **Commit the fix** - This commit MUST have all tests passing before opening PR
+
+**Note:** It's acceptable to have failing tests in intermediate commits during development. However, your **final commit before opening a PR must have all tests passing**. This aligns with test-driven development: first create a failing test that proves the bug exists, then fix it.
+
+### For New Features
+
+1. **Write tests covering all major use cases** - Think about edge cases, invalid inputs, and expected behaviors
+2. **Implement the feature** - Build the feature to satisfy the test requirements
+3. **Refactor if needed** - Clean up the implementation while keeping tests green
+
+### Test Organization
+
+**Use test classes to group related tests:**
+
+```python
+import pytest
+
+
+class TestModelInference:
+    def test_single_image_inference(self):
+        # Test code
+        pass
+
+    def test_batch_inference(self):
+        # Test code
+        pass
+```
+
+**Use `pytest.mark.parametrize` to extend test cases:**
+
+```python
+import pytest
+
+
+@pytest.mark.parametrize(
+    "model_variant",
+    [
+        pytest.param("nano", id="nano"),
+        pytest.param("small", id="small"),
+        pytest.param("medium", id="medium"),
+    ],
+)
+def test_model_loading(model_variant):
+    # Test code that runs for each model variant
+    pass
+```
+
+**Avoid multiple validation cases in a single test:**
+
+Do not write tests that loop through multiple cases internally. Instead, use `@pytest.mark.parametrize` so each case runs as a separate test:
+
+```python
+import pytest
+from rfdetr.assets.model_weights import ModelWeights
+
+
+# BAD: Multiple cases in one test - all assertions must pass for test to pass
+def test_all_models_have_valid_urls():
+    for model in ModelWeights:
+        assert model.url.startswith("http")  # Hard to identify which model failed
+
+
+# GOOD: Parametrized - each model is a separate test case
+@pytest.mark.parametrize("model", list(ModelWeights), ids=[m.filename for m in ModelWeights])
+def test_all_models_have_valid_urls(model):
+    assert model.url.startswith("http")  # Clear which model failed
+```
+
+Benefits of parametrization:
+
+- Each case runs as an independent test (failures are isolated)
+- Test IDs clearly identify which case failed
+- Easier to debug and maintain
+- Better test reporting in CI
+
+**Mark GPU-required or computationally heavy tests:**
+
+```python
+import pytest
+
+
+@pytest.mark.gpu  # Use this marker for GPU-dependent or heavy tests (e.g., training)
+def test_model_training():
+    # Training test code
+    pass
+```
+
+Tests marked with `@pytest.mark.gpu` are excluded from CPU CI workflows and run separately on GPU infrastructure.
+
+### CI Testing
+
+> [!NOTE]
+> **CI Workflows (Source of Truth):** See `.github/workflows/ci-tests-cpu.yml` and `.github/workflows/ci-tests-gpu.yml` for exact commands.
+
+Our continuous integration tests run on:
+
+- **Operating Systems:** Ubuntu, Windows, macOS
+- **Python Versions:** 3.10, 3.11, 3.12, 3.13
+- **CPU Workflow:** `pytest -m "not gpu"` - Runs on all OS/Python combinations
+- **GPU Workflow:** `pytest -m gpu` - Runs separately on GPU infrastructure
+
+This ensures your changes work across all supported platforms and Python versions.
+
+**Key GitHub Actions workflow files** (in `.github/workflows/`):
+
+- **ci-tests-cpu.yml** — CPU tests across Ubuntu/Windows/macOS × Python 3.10–3.13
+- **ci-tests-gpu.yml** — GPU-dependent tests
+- **build-package.yml** — Build and validate distributions (`uv build` + `twine check`)
+- **ci-build-docs.yml** — Documentation build validation
+- **publish-docs.yml** — Deploy docs to GitHub Pages on release
+
+**Concurrency:** PRs cancel in-progress runs on new pushes.
+
+### Running Tests
+
+```bash
+# Run tests with parallel execution (recommended)
+uv run --no-sync pytest src/ tests/ -n 2 -m "not gpu" --ignore=tests/run_smoke_all_models.py --timeout=240 --durations=50
+
+# Run a specific test file
+uv run --no-sync pytest tests/models/test_model.py
+
+# Run a specific test
+uv run --no-sync pytest tests/models/test_model.py::test_model_loading
+```
+
+## Code Quality and Linting
+
+All code must pass linting and formatting checks before being merged. We use **pre-commit hooks** to automate this process.
+
+> [!TIP]
+> Pre-commit hooks will auto-format many issues. If pre-commit fails, review the changes it made and re-stage the files.
+
+### Setting Up Pre-commit
+
+```bash
+# Install pre-commit
+pip install pre-commit
+
+# Install the git hooks
+pre-commit install
+
+# Run manually on all files
+pre-commit run --all-files
+```
+
+**Configuration:** See `.pre-commit-config.yaml` for all hooks and `pyproject.toml` for tool-specific settings (e.g., `[tool.ruff]`).
+
+## Deprecation Policy
+
+RF-DETR uses [pyDeprecate](https://github.com/Borda/pyDeprecate) to emit structured deprecation warnings. Use `@deprecated` for functions and methods, `@deprecated_class` for classes. The importable package name is `deprecate` (not `pyDeprecate`); refer to its docs for advanced usage.
+
+```python
+from deprecate import deprecated
+
+
+@deprecated(target=new_fn, deprecated_in="1.7.0", remove_in="1.9.0")
+def old_fn(*args, **kwargs): ...
+```
+
+**Rules:**
+
+- All version strings must be full semver: `1.7.0`, not `1.7`.
+- Minimum window: a symbol deprecated in `X.Y.0` cannot be removed before `X.(Y+2).0` (two minor releases).
+- Every new deprecation needs an entry in `docs/getting-started/migration.md` under a `### Deprecated (removal in vX.Z.0)` subsection.
+
+**Removal checklist** (when `remove_in` version arrives):
+
+1. Delete the deprecated symbol, class, or shim file.
+2. Remove any remaining `@deprecated` / `@deprecated_class` decorators.
+3. Add a breaking-change entry to `docs/getting-started/migration.md`.
+4. Search for lingering imports of the removed symbol and update them.
+5. Verify `pre-commit run --all-files` passes and tests are green.
+
+## Building Documentation
+
+RF-DETR's documentation is built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. API reference pages are auto-generated from docstrings using [mkdocstrings](https://mkdocstrings.github.io/).
+
+> [!NOTE]
+> Building the full documentation locally requires the `plus` extra (`rfdetr[plus]`), which provides the XLarge and 2XLarge model pages. Without it, the build will fail on those reference pages.
+
+### Install Documentation Dependencies
+
+```bash
+# Full docs build (matches CI — required for XLarge/2XLarge model pages)
+uv pip install -e ".[plus]" --group docs
+
+# Minimal install (skip plus models — XLarge/2XLarge pages will error)
+uv sync --group docs
+```
+
+### Serve Locally with Live Reload
+
+```bash
+uv run mkdocs serve
+```
+
+Open [http://localhost:8000](http://localhost:8000) in your browser. The server watches for file changes and reloads automatically — no restart needed as you edit documentation.
+
+### Build Static Site
+
+```bash
+# Build static documentation site to the site/ directory
+uv run mkdocs build
+```
+
+**Note:** `mkdocs.yaml` uses custom YAML tags (`!!python/name`). The `check-yaml` pre-commit hook runs with `--unsafe` to allow this — do not remove that flag.
+
+### Documentation Structure
+
+```
+docs/
+├── index.md              # Home page
+├── learn/                # How-to guides and tutorials
+│   ├── install.md
+│   ├── run/              # Detection and segmentation guides
+│   └── train/            # Training guides (parameters, augmentations, loggers, etc.)
+├── reference/            # Auto-generated API reference (from docstrings)
+├── tutorials/
+└── theme/                # Custom theme overrides
+mkdocs.yaml               # MkDocs configuration and navigation
+```
+
+> [!TIP]
+> When adding a new documentation page, add it to the `nav` section in `mkdocs.yaml` so it appears in the site navigation. Pages that exist in `docs/` but are not listed in `nav` will not be included in the site.
+
+## CLA Signing
+
+In order to maintain the integrity of our project, every pull request must include a signed Contributor License Agreement (CLA). This confirms that your contributions are properly licensed under our Apache 2.0 License. After opening your pull request, simply add a comment stating:
+
+```
+I have read the CLA Document and I sign the CLA.
+```
+
+This step is essential before any merge can occur.
+
+## Google-Style Docstrings and Mandatory Type Hints
+
+For clarity and maintainability, any new functions or classes must include [Google-style docstrings](https://google.github.io/styleguide/pyguide.html) and use Python type hints. Type hints are mandatory in all function definitions, ensuring explicit parameter and return type declarations.
+
+> [!IMPORTANT]
+> Type hints are in the function signature. **Do not duplicate types in docstrings** - describe the parameter's purpose instead.
+
+For example:
+
+```python
+def sample_function(param1: int, param2: int = 10) -> bool:
+    """
+    Provides a brief description of function behavior.
+
+    Args:
+        param1: Explanation of the first parameter's purpose.
+        param2: Explanation of the second parameter, defaulting to 10.
+
+    Returns:
+        True if the operation succeeds, otherwise False.
+
+    Examples:
+        >>> sample_function(5, 10)
+        True
+    """
+    return param1 == param2
+```
+
+Following this pattern helps ensure consistency throughout the codebase.
+
+## Reporting Bugs
+
+Bug reports are vital for continued improvement. When reporting an issue, please include a clear, minimal reproducible example that demonstrates the problem. Detailed bug reports assist us in swiftly diagnosing and addressing issues.
+
+## Adding a New Model
+
+> [!IMPORTANT]
+> Before implementing a new model, **discuss with maintainers first**. Project structure and patterns are subject to change.
+
+**General workflow:**
+
+1. **Open an issue** describing the proposed model and approach
+    - You may ask maintainers to confirm the expected evaluation protocol (dataset, metrics) before running full benchmarks
+2. **Demonstrate improvement** versus reference models on a standard public dataset (e.g., COCO val2017)
+    - If the change is for an existing RF-DETR model, show a case where the new approach is Pareto optimal (e.g., better accuracy at similar or lower latency/model size) over the existing model
+    - If the change is adding a new functionality, show a case where the new approach is Pareto optimal over comparable third-party models (see the [README model table](../README.md) for reference baselines)
+    - Provide a script for us to reproduce your results
+3. **Wait for maintainer feedback** on architecture and integration approach
+4. **Follow test-driven development:**
+    - Write comprehensive tests for the new model
+    - Implement the model following approved approach
+    - Ensure all tests pass
+5. **Add documentation** as directed by maintainers
+6. **Submit PR** with reference to the discussion issue
+
+Maintainers will guide you on specific files to modify and patterns to follow based on current project architecture.
+
+## Security Considerations
+
+- **Write secure code:** Avoid injection vulnerabilities (XSS, SQL injection, command injection)
+- **Validate inputs:** Especially for file paths, URLs, and user-provided data
+- **No credentials:** Never commit API keys, tokens, or credentials to the repository
+- **Follow OWASP best practices** for any user-facing or network-facing code
+
+## License
+
+By contributing to RF-DETR, you agree that your contributions will be licensed under the Apache 2.0 License as specified in our [LICENSE](/LICENSE) file.
+
+Thank you for your commitment to making RF-DETR better. We look forward to your pull requests and continued collaboration. Happy coding!
+
+### License Headers
+
+All Python files must start with the following header:
+
+```python
+# ------------------------------------------------------------------------
+# RF-DETR
+# Copyright (c) 2025 Roboflow. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 [see LICENSE for details]
+# ------------------------------------------------------------------------
+```

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,80 @@
+name: 🐞 Bug Report
+# title: " "
+description: "Problems with RF-DETR"
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for submitting an RF-DETR 🐞 Bug Report!
+
+  - type: checkboxes
+    attributes:
+      label: Search before asking
+      description: >
+        Please search the RF-DETR documentation and [issues](https://github.com/roboflow/rf-detr/issues) to see if a similar bug report already exists.
+      options:
+        - label: >
+            I have searched the RF-DETR issues and found no similar bug report.
+          required: true
+
+  - type: textarea
+    attributes:
+      label: Bug
+      description: >
+        Please provide as much information as possible. Include full console output and error messages (including any traceback). Use Markdown to format text, code, and logs. Screenshots can help clarify visual issues.
+      placeholder: |
+        Include logs, tracebacks, screenshots, or any other relevant info to help us quickly diagnose and solve your problem.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Environment
+      description: |
+        Try the latest version of RF-DETR (`pip install -U rf-detr`) before reporting a bug. If the issue persists, please provide details about your setup:
+        - RF-DETR version
+        - OS (e.g. Ubuntu 20.04, Windows 10)
+        - Python version
+        - PyTorch version
+        - CUDA/cuDNN version
+        - GPU/CPU hardware
+      placeholder: |
+        Example:
+        - RF-DETR: 0.1.0
+        - OS: Ubuntu 20.04
+        - Python: 3.9.0
+        - PyTorch: 1.13.1
+        - GPU: NVIDIA RTX 4080
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Minimal Reproducible Example
+      description: >
+        Provide code or steps that are as minimal and self-contained as possible to reproduce the issue. This helps us diagnose problems more quickly.
+      placeholder: |
+        ```
+        # Example code to reproduce your issue
+        model = ...
+        ...
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Additional
+      description: |
+        Anything else you would like to share? (Optional)
+      placeholder: |
+        Additional context, suggestions, or observations.
+
+  - type: checkboxes
+    attributes:
+      label: Are you willing to submit a PR?
+      description: >
+        (Optional) We encourage you to submit a [Pull Request](https://github.com/roboflow/rf-detr/pulls) (PR) to help improve RF-DETR, especially if you already have a fix or feature in mind.
+      options:
+        - label: Yes, I'd like to help by submitting a PR!

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,49 @@
+name: 🤩 Feature Request
+description: Suggest an idea for RF-DETR
+# title: " "
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for submitting an RF-DETR Feature Request!
+
+  - type: checkboxes
+    attributes:
+      label: Search before asking
+      description: >
+        Please search the [issues](https://github.com/roboflow/rf-detr/issues) to see if a similar feature request already exists.
+      options:
+        - label: >
+            I have searched the RF-DETR [issues](https://github.com/roboflow/rf-detr/issues) and found no similar feature requests.
+          required: true
+
+  - type: textarea
+    attributes:
+      label: Description
+      description: A short description of your feature.
+      placeholder: |
+        What new feature would you like to see in RF-DETR?
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Use case
+      description: |
+        Describe the use case of your feature request. It will help us understand and prioritize the feature request.
+      placeholder: |
+        How would this feature be used, and who would use it?
+
+  - type: textarea
+    attributes:
+      label: Additional
+      description: Anything else you would like to share?
+
+  - type: checkboxes
+    attributes:
+      label: Are you willing to submit a PR?
+      description: >
+        (Optional) We encourage you to submit a [Pull Request](https://github.com/roboflow/supervision/pulls) (PR) to help improve Supervision for everyone, especially if you have a good understanding of how to implement a fix or feature.
+      options:
+        - label: Yes I'd like to help by submitting a PR!

.github/LICENSE_HEADER.txt

@@ -0,0 +1,5 @@
+------------------------------------------------------------------------
+RF-DETR
+Copyright (c) 2025 Roboflow. All Rights Reserved.
+Licensed under the Apache License, Version 2.0 [see LICENSE for details]
+------------------------------------------------------------------------

.github/SECURITY.md

@@ -0,0 +1,97 @@
+# Security Policy
+
+## Project Status
+
+RF-DETR is a **research project** under active development. While we strive for stability, the codebase may contain undiscovered vulnerabilities typical of research-grade software.
+
+## Supported Versions
+
+Security fixes are generally provided for the latest stable release.
+
+Fixes for older versions may be provided at the maintainers' discretion, depending on severity and feasibility.
+
+| Version        | Support Status     |
+| -------------- | ------------------ |
+| Latest release | :white_check_mark: |
+| Older versions | Case-by-case       |
+
+## Reporting a Vulnerability
+
+Please report security issues privately.
+
+**Do not** create a public GitHub issue for security vulnerabilities.
+
+Report to: **security@roboflow.com**
+
+Include (if available):
+
+- A clear description and impact
+- Steps to reproduce / proof-of-concept
+- Affected versions, environment details, and relevant logs
+
+We aim to acknowledge reports within a few days and will work with you on appropriate disclosure timelines. Response times may vary depending on severity and complexity.
+
+## Security Considerations for ML Projects
+
+### Model Weights and Checkpoints
+
+**Critical**: PyTorch checkpoint files (`.pt`, `.pth`) can execute arbitrary code when loaded because they are commonly pickle-based.
+
+- **Only load models from trusted sources**
+- Prefer safer formats (e.g. `safetensors`) when available
+- When possible, use safer loading options (e.g. `torch.load(..., weights_only=True)` where supported)
+
+**Note**: ONNX models (`.onnx`) are not pickle-based, but parsing/optimizer toolchains can still have security vulnerabilities. Treat untrusted files cautiously.
+
+**Resources**:
+
+- [PyTorch Security Best Practices](https://pytorch.org/docs/stable/security.html)
+- [PyTorch CVE Database](https://github.com/pytorch/pytorch/security/advisories)
+
+### Dependency Security
+
+RF-DETR depends on the PyTorch ecosystem and other ML libraries:
+
+- Keep PyTorch, torchvision, and transformers updated
+- Monitor security advisories for dependencies
+- Use virtual environments to isolate installations
+- Regularly update dependencies (for users): `pip install --upgrade rfdetr`
+
+### Data Processing
+
+- Validate and sanitize input data
+- Be cautious when processing data from untrusted sources
+- Consider resource limits when processing large batches
+
+### Training and Inference
+
+- Untrusted training data may contain adversarial examples
+- Monitor resource usage during training to detect anomalies
+- Consider using resource limits in production environments
+
+## Known Limitations
+
+- This is research software not hardened for production use
+- The package has not undergone formal security auditing
+- Custom CUDA kernels may have memory safety issues
+- Limited input validation in some code paths
+
+## Best Practices
+
+1. **Run in isolated environments**: Use containers or virtual machines for production deployments
+2. **Limit resource access**: Apply appropriate resource constraints (memory, GPU, CPU)
+3. **Monitor for anomalies**: Track unusual behavior during training or inference
+4. **Keep updated**: Regularly update to the latest version
+5. **Review dependencies**: Understand the security posture of all dependencies
+
+## Security Updates
+
+Security patches will be announced via:
+
+- GitHub Security Advisories
+- Release notes
+- Project README
+
+If a vulnerability is deemed significant, we may request a CVE identifier to ensure proper tracking across the ecosystem.
+
+Subscribe to repository notifications to stay informed.

.github/copilot-instructions.md

@@ -0,0 +1,140 @@
+# RF-DETR Copilot Instructions
+
+> [!NOTE]
+> 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).
+
+## Repository Overview
+
+RF-DETR is a real-time transformer architecture for object detection and instance segmentation. Built on DINOv2 vision transformer backbone with PyTorch.
+
+**Project Type:** Python ML library (computer vision)
+**Python:** >=3.10 (3.10, 3.11, 3.12, 3.13)
+**License:** Apache 2.0 (Plus models under PML 1.0)
+
+> [!TIP]
+>
+> - **Configuration:** See `pyproject.toml` for dependencies, build settings, and tool configurations.
+> - **Contributing:** See `.github/CONTRIBUTING.md` for contribution guidelines, CLA, and coding standards.
+
+## Quick Start
+
+**Package Manager:** This project uses `uv` for all dependency management.
+
+```bash
+# Development setup
+uv sync --all-groups
+
+# Run tests (always before committing)
+uv run --no-sync pytest src/ tests/ -n 2 -m "not gpu" --cov=rfdetr --cov-report=xml
+
+# Build package
+uv build
+```
+
+> [!IMPORTANT]
+> Run `uv sync` after pulling changes to update dependencies.
+
+## Code Quality
+
+**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.
+
+```bash
+pre-commit run --all-files
+```
+
+> **Configuration:** `.pre-commit-config.yaml` (hooks) and `[tool.ruff]` in `pyproject.toml` (Python linting)
+
+## Key Conventions
+
+> [!NOTE]
+> Internal package organization (`src/rfdetr/`) is subject to change as this is an active research project. Explore the codebase to understand current module organization.
+
+**Imports:**
+
+- Always use direct imports: `from rfdetr.utilities.distributed import get_rank, is_main_process`
+- Logger: `from rfdetr.utilities.logger import get_logger` (reads `LOG_LEVEL` env var)
+- **Never use** `rfdetr.util.*` or `rfdetr.deploy.*` — deprecated shims scheduled for removal in v1.9.0
+- TQDM: `from tqdm.auto import tqdm` (NOT `from tqdm import tqdm`)
+
+## Testing & Development Workflow
+
+**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.
+
+**Quick reference:**
+
+- Bug fixes: Write failing test → Fix → Verify all pass
+- Features: Write comprehensive tests → Implement → Refactor
+- Use test classes and `@pytest.mark.parametrize` for organization
+- Mark GPU/heavy tests with `@pytest.mark.gpu`
+
+**Testing Requirements:**
+
+- ⚠️ During development: Tests may fail (TDD cycle is fine)
+- ✅ Before PR: Final commit MUST have all tests passing
+- ✅ Before commit: Run `pre-commit run --all-files`
+
+**CI/CD:** See `.github/workflows/` for source of truth. Tests run on Python 3.10-3.13 across Ubuntu, Windows, macOS.
+
+## Coding Standards
+
+**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.
+
+**Import Conventions:**
+
+```python
+# Always use direct imports (NOT import ... as pattern)
+from rfdetr.utilities.distributed import get_rank, is_main_process, save_on_master
+from rfdetr.utilities.logger import get_logger
+
+# TQDM (for environment compatibility)
+from tqdm.auto import tqdm  # NOT from tqdm import tqdm
+```
+
+**Project-Specific Patterns:**
+
+- **Logging:** Use `logger.debug()` for detailed tensor/shape info (not `logger.info()`)
+- **Segmentation models:** Return `pred_masks` as `torch.Tensor` or dict with keys `['spatial_features', 'query_features', 'bias']`
+- **Checkpoint handling:** Always check file existence before operations
+- **License headers:** All Python files require Apache 2.0 header (enforced by pre-commit)
+
+**Best Practices:**
+
+- Make minimal, surgical changes - avoid over-engineering
+- Use existing patterns and libraries
+- Write secure code - avoid injection vulnerabilities (XSS, SQL injection, command injection)
+- Follow Python ML development best practices
+
+## Pre-Commit Checklist
+
+Before submitting changes:
+
+1. ✅ Run tests: `uv run --no-sync pytest src/ tests/ -n 2 -m "not gpu"`
+2. ✅ Run pre-commit: `pre-commit run --all-files`
+3. ✅ Verify new functions have type hints + docstrings
+4. ✅ Review changes for minimal scope
+
+## Resources
+
+- **Docs:** https://rfdetr.roboflow.com
+- **Contributing:** `.github/CONTRIBUTING.md`
+- **Config:** `pyproject.toml`, `.pre-commit-config.yaml`
+- **Issues:** https://github.com/roboflow/rf-detr/issues
+
+## Maintaining Agentic Documentation
+
+**If your contribution:**
+
+- Changes project structure or introduces new patterns
+- Receives major feedback in PR review about conventions/patterns
+
+**Then update the relevant documents:**
+
+- This file (copilot-instructions.md) for high-level guidance
+- AGENTS.md for detailed technical patterns
+- CONTRIBUTING.md if it affects human contribution workflow
+
+This ensures future contributions stay consistent and reduces repeated feedback.
+
+---
+
+**Note:** These instructions are GitHub Copilot-specific. When in doubt, refer to existing code patterns, contributing guidelines, and test files for examples.

.github/workflows/build-package.yml

@@ -0,0 +1,41 @@
+name: Build Package
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: "3.10"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: 🐍 Install uv and set Python version ${{ inputs.python-version }}
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          python-version: ${{ inputs.python-version }}
+          activate-environment: true
+
+      - name: 🏗️ Build source and wheel distributions
+        run: |
+          uv pip install --group build
+          uv build
+          uv run --no-sync twine check --strict dist/*
+
+      - name: 📤 Upload distribution artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

.github/workflows/ci-build-docs.yml

@@ -0,0 +1,47 @@
+name: Docs/Test WorkFlow
+
+on:
+  pull_request:
+    branches: ["main", "release/*", "develop"]
+  push:
+    branches: ["main", "release/*", "develop"]
+  workflow_dispatch: {}
+
+# Restrict permissions by default
+permissions:
+  contents: read # Required for checkout
+  checks: write # Required for test reporting
+
+jobs:
+  docs-build-test:
+    name: Test docs build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+
+      - name: 🐍 Install uv and set Python
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          python-version: "3.10"
+          activate-environment: true
+
+      - name: 🏗️ Install dependencies
+        timeout-minutes: 5
+        run: uv pip install -e ".[plus]" --group docs
+
+      - name: 🧪 Test Docs Build
+        run: uv run --no-sync mkdocs build --verbose
+
+      - name: 📤 Upload docs artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: docs-site
+          path: site/
+          retention-days: 7
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

.github/workflows/ci-deps-resolution.yml

@@ -0,0 +1,52 @@
+name: Dependency resolution
+
+on:
+  push:
+    branches: ["main", "release/*", "develop"]
+    paths: ["pyproject.toml"]
+  pull_request:
+    paths: ["pyproject.toml"]
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+concurrency:
+  group: deps-resolution-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  tflite-resolution:
+    name: Resolve [tflite] extra — Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        # tflite deps carry python_version>='3.12' and <'3.13' markers; onnx2tf pins numpy==1.26.4
+        # exactly, which conflicts with ml-dtypes>=0.5.1 requiring numpy>=2.1.0 on 3.13.
+        # Add 3.13 and relax the <'3.13' upper bound when onnx2tf drops the exact numpy pin.
+        python-version: ["3.12"]
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: 🔍 Resolve [tflite] optional dependencies
+        run: |
+          uv pip compile pyproject.toml \
+            --extra tflite \
+            --python-version ${{ matrix.python-version }} \
+            --no-header \
+            --quiet
+
+      - name: Minimize uv cache
+        continue-on-error: true
+        run: uv cache prune --ci

.github/workflows/ci-integrations.yml

@@ -0,0 +1,49 @@
+name: Smoke Tests
+
+on:
+  push:
+    branches: ["main", "release/*", "develop"]
+  pull_request:
+    branches: ["main", "release/*", "develop"]
+
+permissions:
+  contents: read
+
+env:
+  # UV_TORCH_BACKEND only works with 'uv pip' commands, not 'uv sync'.
+  # Used by 'uv pip install torch torchvision' step to install CPU-only PyTorch.
+  UV_TORCH_BACKEND: "cpu"
+
+concurrency:
+  group: model-smoke-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  try-all-models:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        python-version: ["3.10", "3.13"]
+    timeout-minutes: 15
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+      - name: 🚀 Install Packages (plus extras)
+        timeout-minutes: 5
+        # Install PyTorch CPU-only first (UV_TORCH_BACKEND=cpu works with 'uv pip')
+        run: uv pip install -e .[plus]
+
+      - name: 🔎 Smoke-test model instantiation, downloads, and inference
+        run: python tests/run_smoke_all_models.py
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

.github/workflows/ci-tests-cpu.yml

@@ -0,0 +1,99 @@
+name: CPU tests Workflow
+
+on:
+  push:
+    branches: ["main", "release/*", "develop", "feat/*"]
+  pull_request:
+
+permissions:
+  contents: read
+defaults:
+  run:
+    shell: bash
+
+env:
+  # UV_TORCH_BACKEND only works with 'uv pip' commands, not 'uv sync'.
+  # Used by 'uv pip install torch torchvision' step to install CPU-only PyTorch.
+  UV_TORCH_BACKEND: "cpu"
+
+concurrency:
+  group: pytest-test-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build-pkg:
+    uses: ./.github/workflows/build-package.yml
+
+  run-tests:
+    name: Testing
+    # needs: build  # todo: consider using this build package for testing
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - { os: "windows-latest", python-version: "3.10" }
+          - { os: "macos-latest", python-version: "3.10" }
+          - { os: "windows-latest", python-version: "3.13" }
+          - { os: "macos-latest", python-version: "3.13" }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+      - name: 🚀 Install Packages
+        timeout-minutes: 5
+        # Install PyTorch CPU-only first (UV_TORCH_BACKEND=cpu works with 'uv pip')
+        run: uv pip install -e ".[train,cli,visual,kornia]" --group tests
+
+      - name: 🧪 Run the Test
+        run: |
+          uv run --no-sync pytest src/ tests/ \
+            -n 2 -m "not gpu and not coco17" \
+            --ignore=tests/run_smoke_all_models.py \
+            --cov=rfdetr --cov-report=xml \
+            --timeout=420 \
+            --durations=50
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: "coverage.xml"
+          flags: cpu,${{ runner.os }},py${{ matrix.python-version }}
+          env_vars: OS,PYTHON
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+      - name: Minimize uv cache
+        continue-on-error: true
+        run: uv cache prune --ci
+
+  testing-guardian:
+    runs-on: ubuntu-latest
+    needs: run-tests
+    if: always()
+    steps:
+      - name: 📋 Display test result
+        run: echo "${{ needs.run-tests.result }}"
+      - name: ❌ Fail guardian on test failure
+        if: needs.run-tests.result == 'failure'
+        run: exit 1
+      # Ensure that cancelled or skipped test runs still cause this guardian job to fail,
+      # using an explicit exit code instead of relying on timeout behavior.
+      - name: ⚠️ cancelled or skipped...
+        if: contains(fromJSON('["cancelled", "skipped"]'), needs.run-tests.result)
+        run: |
+          echo "run-tests job result is '${{ needs.run-tests.result }}'; failing explicitly."
+          exit 1
+      - name: ✅ tests succeeded
+        if: needs.run-tests.result == 'success'
+        run: echo "All tests completed successfully in job 'run-tests'."

.github/workflows/ci-tests-gpu.yml

@@ -0,0 +1,75 @@
+name: GPU tests Workflow
+
+on:
+  push:
+    branches: ["main", "release/*", "develop", "feat/*"]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+defaults:
+  run:
+    shell: bash
+
+env:
+  PYTHON_VERSION: "3.12"
+  # UV_TORCH_BACKEND only works with 'uv pip' commands, not 'uv sync'.
+  # Set to "auto" for GPU workflow (auto-detects CUDA version).
+  UV_TORCH_BACKEND: "auto"
+
+concurrency:
+  group: pytest-gpu-test-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  run-gpu-tests:
+    name: Testing
+    if: github.event_name == 'push' || !github.event.pull_request.draft
+    timeout-minutes: 35
+    runs-on: Roboflow-GPU-VM-Runner
+    steps:
+      - name: 🖥️ Print GPU information
+        run: nvidia-smi
+      - name: 🧰 Install build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: 🐍 Install uv and set Python version
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          activate-environment: true
+
+      - name: 🚀 Install Packages
+        timeout-minutes: 5
+        # Use uv pip install (not uv sync) to avoid universal lock resolution failing on
+        # extras that require Python>=3.12 (e.g. tflite/onnx2tf) when project supports >=3.10.
+        # UV_TORCH_BACKEND=auto (set above) works only with uv pip, not uv sync.
+        run: uv pip install -e ".[onnx,plus,train,visual]" --group tests --group ci-gpu-pin
+
+      - name: 🧪 Run the Test
+        run: |
+          uv run --no-sync pytest tests/ \
+          -m gpu \
+          -n 3 \
+          --reruns 1 --only-rerun "OutOfMemoryError" \
+          --cov=rfdetr --cov-report=xml \
+          --timeout=600 \
+          --durations=20
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: "coverage.xml"
+          flags: gpu,${{ runner.os }},py${{ env.PYTHON_VERSION }}
+          env_vars: OS,PYTHON
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

.github/workflows/ci-typing.yml

@@ -0,0 +1,47 @@
+name: Mypy Type Check
+
+on:
+  push:
+    branches: ["main", "release/*", "develop"]
+  pull_request:
+
+permissions:
+  contents: read
+defaults:
+  run:
+    shell: bash
+
+env:
+  # UV_TORCH_BACKEND only works with 'uv pip' commands, not 'uv sync'.
+  # Used by 'uv pip install torch torchvision' step to install CPU-only PyTorch.
+  UV_TORCH_BACKEND: "cpu"
+
+concurrency:
+  group: mypy-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  type-check:
+    name: Type Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: 🐍 Install uv and set Python version
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          python-version: "3.10"
+          activate-environment: true
+
+      - name: 🚀 Install Packages
+        timeout-minutes: 5
+        run: uv pip install -e ".[train,cli,visual]" --group typing
+
+      - name: 🔍 Run mypy
+        run: uv run --no-sync mypy src/rfdetr/ --no-error-summary
+
+      - name: Minimize uv cache
+        continue-on-error: true
+        run: uv cache prune --ci

.github/workflows/pr-conflict-labeler.yml

@@ -0,0 +1,26 @@
+name: PR Conflict Labeler
+
+on:
+  # So that PRs touching the same files as the push are updated
+  push:
+    branches: ["main", "release/*", "develop"]
+  # So that the `dirtyLabel` is removed if conflicts are resolved
+  # We recommend `pull_request_target` so that github secrets are available.
+  # In `pull_request` we wouldn't be able to change labels of fork PRs
+  pull_request_target:
+    types: [synchronize]
+
+permissions:
+  pull-requests: write
+  issues: write
+
+jobs:
+  labeling:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - name: check if prs are dirty
+        uses: eps1lon/actions-label-merge-conflict@1df065ebe6e3310545d4f4c4e862e43bdca146f0 # v3
+        with:
+          dirtyLabel: "has conflicts"
+          repoToken: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/publish-docs.yml

@@ -0,0 +1,208 @@
+# Build and deploy MkDocs documentation to GitHub Pages (https://rfdetr.roboflow.com/)
+# using mike for versioned docs.
+#
+# Deploy matrix:
+#   push develop                    → mike deploy develop        (rfdetr.roboflow.com/develop/)
+#   push release/latest             → mike deploy latest         (rfdetr.roboflow.com/latest/)
+#   release published (stable/post) → mike deploy <base>          (rfdetr.roboflow.com/<base>/; .postN stripped; RC/pre-release skipped)
+#   workflow_dispatch target=develop         → same as push develop
+#   workflow_dispatch target=release/latest  → same as push release/latest (→ latest alias)
+#   workflow_dispatch target=<version tag>   → mike deploy <tag>
+#
+# Every deploy also:
+#   - Copies robots.txt, llms.txt, llms-full.txt to gh-pages root
+#   - Regenerates sitemap.xml normalising versioned paths to /latest/
+#   - Pings IndexNow (Bing) with canonical /latest/ URLs
+
+name: Build and Publish Docs
+
+on:
+  push:
+    branches: ["release/latest", "develop"]
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Deploy target: 'develop', 'release/latest', or a version tag (e.g. '1.2.3'). Determines both the checkout ref and the mike version label."
+        required: true
+        default: "release/latest"
+
+# Ensure only one concurrent deployment
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref_name || github.event_name == 'workflow_dispatch' && inputs.target || github.event_name == 'release' && github.event.release.tag_name || github.ref_name }}
+  cancel-in-progress: true
+
+# Restrict permissions by default
+permissions:
+  contents: write # Required for committing to gh-pages
+  pages: write # Required for deploying to Pages
+  pull-requests: write # Required for PR comments
+
+jobs:
+  doc-deploy:
+    name: Publish Docs
+    runs-on: ubuntu-latest
+    environment:
+      name: documentation-deployment
+      url: https://rfdetr.roboflow.com/
+    timeout-minutes: 10
+    steps:
+      - name: 🔍 Validate dispatch target
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          TARGET="${{ inputs.target }}"
+          if [ "$TARGET" = "develop" ] || [ "$TARGET" = "release/latest" ]; then
+            echo "✓ Target '$TARGET' is valid"
+          elif echo "$TARGET" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(\.post[0-9]+)?$'; then
+            echo "✓ Target '$TARGET' is valid (version tag)"
+          else
+            echo "::error::Invalid target '$TARGET'. Must be 'develop', 'release/latest', or a version tag (e.g. '1.2.3' or '1.2.3.post1')"
+            exit 1
+          fi
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.target || github.ref }}
+
+      - name: 🐍 Install uv and set Python
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          python-version: "3.10"
+          activate-environment: true
+
+      - name: 🏗️ Install dependencies
+        # Install PyTorch CPU-only first (UV_TORCH_BACKEND=cpu works with 'uv pip')
+        run: uv pip install -e ".[plus]" --group docs
+
+      - name: ⚙️ Configure git for github-actions
+        run: |
+          git config --global user.name "${{ github.actor }}"
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+
+      - name: 🚀 Deploy Development Docs
+        if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run --no-sync mike deploy --push develop
+
+      - name: 🚀 Deploy Latest Branch Docs
+        if: github.event_name == 'push' && github.ref == 'refs/heads/release/latest'
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run --no-sync mike deploy --push --update-aliases latest
+
+      - name: 🚀 Deploy Release Docs
+        if: github.event_name == 'release' && github.event.action == 'published' && !github.event.release.prerelease
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          DOC_VERSION="${TAG%.post*}"
+          uv run --no-sync mike deploy --push "$DOC_VERSION"
+
+      - name: 🚀 Deploy Docs (workflow_dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TARGET="${{ inputs.target }}"
+          if [ "$TARGET" = "develop" ]; then
+            uv run --no-sync mike deploy --push develop
+          elif [ "$TARGET" = "release/latest" ]; then
+            uv run --no-sync mike deploy --push --update-aliases latest
+          else
+            DOC_VERSION="${TARGET%.post*}"
+            uv run --no-sync mike deploy --push "$DOC_VERSION"
+          fi
+
+      - name: 🏗️ Build docs for artifact
+        run: uv run --no-sync mkdocs build
+
+      - name: 📤 Upload docs artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: docs-site
+          path: site/
+          retention-days: 7
+
+      - name: Deploy root static files to gh-pages
+        if: >-
+          (github.event_name == 'push' &&
+           (github.ref == 'refs/heads/develop' ||
+            github.ref == 'refs/heads/release/latest')) ||
+          (github.event_name == 'release' &&
+           github.event.action == 'published' &&
+           !github.event.release.prerelease) ||
+          github.event_name == 'workflow_dispatch'
+        run: |
+          cp docs/root-static/robots.txt /tmp/robots.txt
+          cp docs/root-static/llms.txt /tmp/llms.txt
+          cp docs/root-static/llms-full.txt /tmp/llms-full.txt
+          cp docs/root-static/cace9ef287cb8d641db90d4295fcb1e1.txt /tmp/indexnow.txt
+          git fetch origin gh-pages:refs/remotes/origin/gh-pages
+          git checkout -B gh-pages origin/gh-pages
+          cp /tmp/robots.txt robots.txt
+          cp /tmp/llms.txt llms.txt
+          cp /tmp/llms-full.txt llms-full.txt
+          cp /tmp/indexnow.txt cace9ef287cb8d641db90d4295fcb1e1.txt
+          git add robots.txt llms.txt llms-full.txt cace9ef287cb8d641db90d4295fcb1e1.txt
+          # Normalize versioned paths (/X.Y.Z/) to /latest/ so sitemap URLs are
+          # not blocked by the User-agent: * Disallow rules in robots.txt.
+          # latest/ may be a mike alias redirect (no sitemap.xml) — fall back to highest versioned dir.
+          SITEMAP_SRC=""
+          if [ -f latest/sitemap.xml ]; then
+            SITEMAP_SRC="latest/sitemap.xml"
+          else
+            LATEST_VER=$(ls -d [0-9]* 2>/dev/null | grep -E '^[0-9]+\.[0-9]+' | sort -V | tail -1)
+            if [ -n "$LATEST_VER" ] && [ -f "$LATEST_VER/sitemap.xml" ]; then
+              SITEMAP_SRC="$LATEST_VER/sitemap.xml"
+            elif [ -f develop/sitemap.xml ]; then
+              SITEMAP_SRC="develop/sitemap.xml"
+            fi
+          fi
+          if [ -n "$SITEMAP_SRC" ]; then
+            sed 's|rfdetr\.roboflow\.com/[^/]*/|rfdetr.roboflow.com/latest/|g' "$SITEMAP_SRC" > sitemap.xml
+            git add sitemap.xml
+          fi
+          git diff --staged --quiet || git commit -m "chore: update root static files and sitemap"
+          git push origin gh-pages || (git pull --rebase origin gh-pages && git push origin gh-pages)
+
+      # IndexNow key: cace9ef287cb8d641db90d4295fcb1e1
+      # Key file served at https://rfdetr.roboflow.com/cace9ef287cb8d641db90d4295fcb1e1.txt
+      # (deployed via "Deploy root static files" step above).
+      # To rotate: generate new key, update docs/root-static/<key>.txt, replace key string here.
+      - name: 📡 Notify IndexNow (Bing)
+        if: >-
+          (github.event_name == 'push' &&
+           (github.ref == 'refs/heads/develop' ||
+            github.ref == 'refs/heads/release/latest')) ||
+          (github.event_name == 'release' &&
+           github.event.action == 'published' &&
+           !github.event.release.prerelease) ||
+          github.event_name == 'workflow_dispatch'
+        run: |
+          curl -s -o /dev/null -w "%{http_code}" -X POST "https://api.indexnow.org/IndexNow" \
+            -H "Content-Type: application/json; charset=utf-8" \
+            -d '{
+              "host": "rfdetr.roboflow.com",
+              "key": "cace9ef287cb8d641db90d4295fcb1e1",
+              "keyLocation": "https://rfdetr.roboflow.com/cace9ef287cb8d641db90d4295fcb1e1.txt",
+              "urlList": [
+                "https://rfdetr.roboflow.com/",
+                "https://rfdetr.roboflow.com/latest/",
+                "https://rfdetr.roboflow.com/latest/learn/install/",
+                "https://rfdetr.roboflow.com/latest/learn/pretrained/",
+                "https://rfdetr.roboflow.com/latest/learn/run/detection/",
+                "https://rfdetr.roboflow.com/latest/learn/run/segmentation/",
+                "https://rfdetr.roboflow.com/latest/learn/train/",
+                "https://rfdetr.roboflow.com/latest/learn/export/",
+                "https://rfdetr.roboflow.com/latest/learn/deploy/",
+                "https://rfdetr.roboflow.com/latest/learn/benchmarks/"
+              ]
+            }' || true
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

.github/workflows/publish-pre-release.yml

@@ -0,0 +1,51 @@
+name: Publish Pre-Releases to PyPI
+
+on:
+  push:
+    tags:
+      # Matches Semantic Versioning pre-release tags (e.g., 1.2.3a0, 1.2.3.a0, 1.2.3rc2, 1.2.3.rc2)
+      # Format: MAJOR.MINOR.PATCH[.|]a|b|rcN
+      - "[0-9]*.[0-9]*.[0-9]*a[0-9]*"
+      - "[0-9]*.[0-9]*.[0-9]*.a[0-9]*"
+      - "[0-9]*.[0-9]*.[0-9]*b[0-9]*"
+      - "[0-9]*.[0-9]*.[0-9]*.b[0-9]*"
+      - "[0-9]*.[0-9]*.[0-9]*rc[0-9]*"
+      - "[0-9]*.[0-9]*.[0-9]*.rc[0-9]*"
+  workflow_dispatch:
+  pull_request:
+    branches: ["main", "release/latest", "develop"]
+    paths:
+      - ".github/workflows/build-package.yml"
+      - ".github/workflows/publish-pre-release.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  build-pkg:
+    uses: ./.github/workflows/build-package.yml
+
+  publish-pre-release:
+    name: Publish Pre-release Package
+    needs: build-pkg
+    runs-on: ubuntu-latest
+    environment:
+      name: test
+      url: https://pypi.org/project/rfdetr/
+    timeout-minutes: 10
+    permissions:
+      id-token: write # Required for PyPI publishing
+    steps:
+      - name: 📥 Download distribution artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - name: Display distribution files
+        run: ls -lh dist/
+
+      - name: 🚀 Publish to PyPi
+        if: github.event_name != 'pull_request'
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          attestations: true

.github/workflows/publish-release.yml

@@ -0,0 +1,49 @@
+name: Publish Releases to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+  pull_request:
+    branches: ["main", "release/latest", "develop"]
+    paths:
+      - ".github/workflows/build-package.yml"
+      - ".github/workflows/publish-release.yml"
+
+jobs:
+  build-pkg:
+    uses: ./.github/workflows/build-package.yml
+
+  publish-release:
+    name: Publish Release Package
+    needs: build-pkg
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/rfdetr/
+    timeout-minutes: 10
+    permissions:
+      id-token: write # Required for PyPI publishing
+      contents: write # Add this line
+    steps:
+      - name: 📥 Download distribution artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - name: Display distribution files
+        run: ls -lh dist/
+
+      - name: 🚀 Publish to PyPi
+        # Only publish non-pre-releases
+        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          attestations: true
+
+      - name: 📤 Upload assets to GitHub Release
+        if: github.event_name == 'release'
+        uses: AButler/upload-release-assets@3d6774fae0ed91407dc5ae29d576b166536d1777 # v3.0
+        with:
+          files: "dist/*.whl;dist/*.tar.gz"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}