refactor(deps): make supervision an optional dependency

[everglow01]

What does this PR do?

Moves supervision from a required core dependency to an optional one, so
users who only train or run inference aren't forced to pull in supervision (and
its transitive opencv) when they don't need annotation or Detections output.

Concretely:

• pyproject.toml: removed supervision from core dependencies; added it to
  the extras whose code actually uses it — train, onnx, tflite, visual
  (the same duplication pattern already used for peft, polygraphy, onnx). CI
  installs [train,visual], so the test matrix is unaffected.
• Deferred imports: the four modules that imported supervision eagerly
  (export/_onnx/inference, export/_tflite/inference, datasets/save_grids,
  datasets/synthetic) now import it lazily, with TYPE_CHECKING guards for
  annotations.
• New helper rfdetr/utilities/optional_imports.py::import_supervision()
  raises a friendly ImportError with an install hint instead of a cryptic
  ModuleNotFoundError, reused everywhere supervision is needed (incl.
  predict(), yolo.to_detections, visualize.data).

predict() still returns sv.Detections | list[sv.Detections] — no public API
change. The only behavioral difference is for a bare pip install rfdetr
followed by predict(): it now raises a clear ImportError telling the user to
install supervision, instead of relying on it being implicitly present. This
matches the issue's "clear error messages" acceptance criterion.

This is the safe half of #1074. The other half — returning native dict/list
when supervision is absent, plus to_supervision() conversion helpers and
reworked doc examples — changes the documented public return type and is
intentionally left to a follow-up PR pending maintainer sign-off on the API
direction.

Related Issue(s): Part of #1074 (intentionally not Closes, since the
native-types half is deferred).

Type of Change

• Other: Dependency/packaging change — makes supervision optional. No public API
  change; one narrow behavioral nuance (bare-install predict() now raises a clear
  ImportError) is described above.

Testing

• I have tested this change locally
• I have added/updated tests for this change

Test details:

• Added tests/utilities/test_optional_imports.py covering import_supervision():
  returns the module when present, and raises an ImportError containing the
  pip install supervision hint when absent (simulated via sys.modules).
• Guarded the three supervision-dependent test modules (tests/models/test_predict,
  tests/export/test_tflite_inference, tests/datasets/test_synthetic) with
  pytest.importorskip("supervision").
• Full CPU suite (pytest src/ tests/ -m "not gpu" …): 2022 passed, 43 skipped.
  (Local-only errors were COCO-download fixture timeouts in
  tests/benchmarks/test_inference_coco.py, unrelated to this change.)
• Manually verified import rfdetr succeeds with supervision blocked, and that
  supervision-producing paths raise the friendly ImportError.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in hard-to-understand areas
• My changes generate no new warnings or errors
• I have updated the documentation accordingly (if applicable) — doc/example
  updates are deferred to the follow-up PR together with the native-types change

Additional Context

• pre-commit run --all-files passes clean (ruff, mypy, docformatter, license
  headers, etc.).
• Duplicating supervision across the train/onnx/tflite/visual extras keeps
  each functional install working out of the box and avoids any CI workflow change.
  Open to a dedicated [supervision]/[detections] extra instead if you prefer.

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

This PR makes supervision an optional dependency by moving it out of core pyproject.toml dependencies and introducing a centralized lazy import helper (import_supervision()) that provides a user-friendly install hint when supervision isn’t available. This reduces the baseline install footprint for users who don’t need sv.Detections/annotation utilities, while preserving the existing public return types.

Changes:

• Moved supervision from required dependencies into relevant extras (train, onnx, tflite, visual) and updated supervision-dependent code paths to import lazily.
• Added rfdetr.utilities.optional_imports.import_supervision() and wired it into inference/export/visualization/dataset utilities.
• Updated tests to (a) validate the helper behavior and (b) skip supervision-dependent test modules when supervision is not installed.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/utilities/test_optional_imports.py	Adds coverage for the new import_supervision() helper.
tests/models/test_predict.py	Skips predict tests when supervision is unavailable.
tests/export/test_tflite_inference.py	Skips TFLite inference tests when supervision is unavailable.
tests/datasets/test_synthetic.py	Skips synthetic dataset tests when supervision is unavailable.
src/rfdetr/visualize/data.py	Switches eager supervision import to import_supervision().
src/rfdetr/utilities/optional_imports.py	Introduces a shared optional-import helper with a friendly error message.
src/rfdetr/export/_tflite/inference.py	Defers supervision import until detections creation.
src/rfdetr/export/_onnx/inference.py	Defers supervision import until detections creation.
src/rfdetr/detr.py	Makes predict() use import_supervision() and documents ImportError.
src/rfdetr/datasets/yolo.py	Makes to_detections() use import_supervision().
src/rfdetr/datasets/synthetic.py	Defers supervision usage to runtime (incl. colors) via import_supervision().
src/rfdetr/datasets/save_grids.py	Defers supervision usage to runtime via import_supervision().
pyproject.toml	Removes supervision from core deps and adds it to relevant extras.

[codecov]

Codecov Report

❌ Patch coverage is 91.66667% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 77%. Comparing base (680b586) to head (94d59c1).

❌ Your project check has failed because the head coverage (77%) is below the target coverage (95%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #1090   +/-   ##
=======================================
  Coverage       77%     77%           
=======================================
  Files          102     103    +1     
  Lines         9104    9125   +21     
=======================================
+ Hits          7037    7056   +19     
- Misses        2067    2069    +2     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[everglow01]

Hi @Borda 👋 — thanks for the autofix commit, I've rebased on top of it.

PR1 status (this PR):

• supervision is now optional: lazy imports + a friendly ImportError. predict() still returns sv.Detections, so no public API change.
• Fixed the failing Validate model instantiation job: scipy is used in models/matcher.py on the core import path but was only satisfied transitively via supervision. Moved scipy into core dependencies, and the integration job now installs [plus,visual] so supervision is present for the predict() check. Bare pip install rfdetr imports cleanly again.

I think this is ready for review.

Question on the follow-up (PR2): the second half of #1074 — returning native Python types when supervision is absent (plus a to_supervision() helper) — changes the documented return type, so I'd like your guidance before implementing. Preferred shape: (a) keep returning sv.Detections when installed, native dataclass only when absent (backwards-compatible union), or (b) a unified native type with .to_supervision()? Happy to open a separate issue to discuss if that's easier.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[everglow01]

Thanks! I'd prefer to leave this un-memoized:

1. Python already caches the module in sys.modules, so after the first call import supervision is just a dict lookup + name binding (microseconds). The helper is also called once per predict() / _run_inference(), not per-sample, so there's no hot-loop cost in practice.
2. functools.lru_cache would cache the successful module object and break tests/utilities/test_optional_imports.py::test_raises_with_install_hint_when_missing, which relies on monkeypatch.setitem(sys.modules, "supervision", None) to force the missing-package path after a prior successful import. Working around that (a cache_clear() in the test) adds complexity for a non-issue.

Happy to revisit if profiling ever shows this on a hot path.

[everglow01]

Good catch, quoted it. The install line now uses uv pip install -e ".[plus,visual]", matching the style already used in ci-tests-cpu.yml (".[train,cli,visual,kornia]").

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

[Anawaert]

Yes but some contexts of lazy import can be upgraded again after the release of Python 3.15. Python 3.15 adds the significant feature, and usage is following:

lazy import supervision as sv

Maybe you can try it in the future?😂

[Borda]

Yes but some contexts of lazy import can be upgraded again after the release of Python 3.15. Python 3.15 adds the significant feature, and usage is following:

lazy import supervision as sv

Maybe you can try it in the future?😂

We still need to support wide range of python versions...