Move supervision to an optional extra

[robmarkcole]

Search before asking

• I have searched the RF-DETR issues and found no similar feature requests.

Description

RF-DETR currently requires supervision as a core dependency, mainly because public inference APIs return sv.Detections and docs/examples use Supervision annotators.

For users who only need model training or basic inference, this pulls in extra dependencies, including OpenCV transitively. It would be useful to support a minimal install path that can train and run inference without supervision.

Suggested direction:

• Move supervision out of base dependencies and into an extra
• Keep core model forward, training, and basic inference working without supervision.
• Return a lightweight native result type or plain dict/list from minimal inference.
• Provide optional helpers to convert native outputs to sv.Detections when supervision is installed.
• Move annotation/video/visualization examples behind the documented extra.

Acceptance criteria:

• Base install can train and run basic image inference without supervision.
• sv.Detections support remains available through an optional extra.
• Missing optional dependency errors include clear install guidance.

Use case

No response

Additional

No response

Are you willing to submit a PR?

• Yes I'd like to help by submitting a PR!

[everglow01]

Hi @robmarkcole, I'd like to pick this up if no one's working on it yet.

After auditing the current supervision usage, I'd propose splitting this into two PRs, because the acceptance criteria
mix two changes of very different scope and risk:

PR 1 — Dependency decoupling (low-risk):

• Move supervision from core dependencies to an optional extra in pyproject.toml.
• Convert the remaining module-top-level imports to lazy imports with a clear, actionable ImportError (pointing to the
  install command). These are in export/_tflite/inference.py, export/_onnx/inference.py, datasets/synthetic.py, and
  datasets/save_grids.py. (detr.py, datasets/yolo.py, and visualize/data.py already import it lazily / under
  TYPE_CHECKING.)
• Guard the relevant tests so they skip cleanly when the extra isn't installed.

This satisfies criteria 2 (supervision behind an extra) and 3 (informative errors) without changing any public
behavior.

PR 2 — Public return-type change (needs design sign-off first):

Criterion 1 ("base install enables image inference without supervision") can't be met by lazy-importing alone, because
RFDETR.predict() currently returns sv.Detections as its public contract (detr.py). To run inference with supervision
uninstalled, we'd have to:

• change predict() to return a lightweight native type (dict/list)
• add an opt-in conversion helper to sv.Detections for when the extra is present.

That's a breaking change to the public API and touches downstream usage, docs, and examples, so I'd rather not bundle it
with the mechanical cleanup. Before implementing, I'd like your confirmation on the intended return shape — specifically:

1. What should the native return type look like (e.g. a dict with xyxy/confidence/class_id/mask, or a small dataclass)?
2. Should predict() switch to the native type unconditionally, or keep returning sv.Detections when the extra is
   installed (auto-detect) to avoid breaking existing users?
3. Where should the conversion helper live and what should it be called?

Happy to start on PR 1 right away while we align on the PR 2 design. Let me know if that split works for you.

Search before asking

• I have searched the RF-DETR issues and found no similar feature requests.

Description

RF-DETR currently requires supervision as a core dependency, mainly because public inference APIs return sv.Detections and docs/examples use Supervision annotators.

For users who only need model training or basic inference, this pulls in extra dependencies, including OpenCV transitively. It would be useful to support a minimal install path that can train and run inference without supervision.

Suggested direction:

• Move supervision out of base dependencies and into an extra
• Keep core model forward, training, and basic inference working without supervision.
• Return a lightweight native result type or plain dict/list from minimal inference.
• Provide optional helpers to convert native outputs to sv.Detections when supervision is installed.
• Move annotation/video/visualization examples behind the documented extra.

Acceptance criteria:

• Base install can train and run basic image inference without supervision.
• sv.Detections support remains available through an optional extra.
• Missing optional dependency errors include clear install guidance.

Use case

No response

Additional

No response

Are you willing to submit a PR?

• Yes I'd like to help by submitting a PR!

[robmarkcole]

@everglow01 lets get input from @Borda as there are a couple of related PR/issues