Proposal: avoid unsupported TorchScript on Python 3.14

[cdeil]

Hi! While checking RF-DETR on Python 3.14, I saw this warning during a normal top-level import with PyTorch 2.13:

DeprecationWarning: `torch.jit.script` is not supported in Python 3.14+ and may break. Please switch to `torch.compile` or `torch.export`.

Would you be interested in handling it with the conditional eager fallback proposed here?

Evidence

Importing rfdetr executes four module-level torch.jit.script calls:

• batch_dice_loss and batch_sigmoid_ce_loss
• dice_loss and sigmoid_ce_loss

With the warning promoted to an error, current develop stops at the first site:

$ python -c "import warnings; warnings.filterwarnings('error', message=r'.*torch\\.jit\\.script.*', category=DeprecationWarning); import rfdetr"
...
  File "src/rfdetr/utilities/box_ops.py", line 210, in <module>
    batch_dice_loss_jit = torch.jit.script(batch_dice_loss)
DeprecationWarning: `torch.jit.script` is not supported in Python 3.14+ and may break.

The existing dependency-resolution matrix includes Python 3.14, but it only performs an install-plan dry run. The executable CPU test matrix currently stops at Python 3.13, so it cannot observe an import-time warning. A fresh install using the CPU workflow's command currently resolves PyTorch 2.13 and reproduces it.

Proposed behavior

• Keep the existing scripted aliases on Python 3.10–3.13.
• Use the original eager loss functions on Python 3.14+, where TorchScript is unsupported.
• Add Ubuntu/Python 3.14 to the CPU matrix and a targeted subprocess import regression test.
• Advertise Python 3.14 in the package classifier and contributor docs now that the real suite executes there.

This does not appear to be a performance issue at import time: seven fresh-process imports were effectively unchanged (1.982 s vs. 1.970 s median), and the four top-level scripting calls accounted for roughly 8 ms. A small CPU loss microbenchmark also showed identical outputs and only microseconds of eager overhead (Dice: 21.9 vs. 20.0 µs; sigmoid CE: 44.8 vs. 44.7 µs). The motivation is avoiding an explicitly unsupported path before it becomes a failure.

Validation

• Red: the targeted warning-as-error import fails on current develop at box_ops.py:210.
• Green: 4,394 CPU tests passed and 80 skipped on CPython 3.14.6 with PyTorch 2.13.0.
• Green: pre-commit run --all-files passed in the documented Python 3.10 tooling environment.

Would this conditional eager fallback be the compatibility policy you prefer, or would you rather remove or replace these TorchScript aliases more broadly?

[cdeil]

I have read the CLA Document and I sign the CLA.

[Copilot]

Pull request overview

This PR makes RF-DETR’s top-level import compatible with Python 3.14+ by avoiding module-import-time TorchScript compilation (torch.jit.script), while keeping the existing scripted aliases on currently supported Python versions.

Changes:

• Add a Python-version-gated eager fallback for the four import-time TorchScripted loss helpers in box_ops.py and criterion.py.
• Add a subprocess regression test that fails if a torch.jit.script deprecation warning is emitted during import rfdetr.
• Expand CPU CI to include Python 3.14 and update package/documentation metadata to advertise 3.14 support.

Reviewed changes

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

Show a summary per file

File	Description
tests/utilities/test_package.py	Adds an import-time warning-as-error subprocess regression test for torch.jit.script.
src/rfdetr/utilities/box_ops.py	Avoids torch.jit.script at import time on Python 3.14+ via eager alias fallback.
src/rfdetr/models/criterion.py	Avoids torch.jit.script at import time on Python 3.14+ and updates in-file commentary about the eager alias boundary.
pyproject.toml	Adds the Python 3.14 classifier.
AGENTS.md	Updates stated tested Python range and CI CPU workflow description to include 3.14.
.github/workflows/ci-tests-cpu.yml	Adds Python 3.14 to the Ubuntu CPU test matrix.
.github/CONTRIBUTING.md	Updates contributor docs to list Python 3.14 as supported/tested.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86%. Comparing base (6674d85) to head (ae91778).
⚠️ Report is 21 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #1406   +/-   ##
=======================================
- Coverage       86%     86%   -0%     
=======================================
  Files          114     114           
  Lines        14880   14882    +2     
=======================================
- Hits         12835   12784   -51     
- Misses        2045    2098   +53     

🚀 New features to boost your workflow:

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

[Copilot]

🟢 Approval recommended

The compatibility fallback and CI coverage are coherent; feedback is limited to minor documentation wording.

Review details

Suppressed comments (1)

.github/CONTRIBUTING.md:295

• With 3.14 now the upper supported version, “boundary versions” implies that Windows and macOS also test 3.14, but the matrix includes those OSes only for 3.10 and 3.13. Please name the exact versions here (or add 3.14 jobs) so the contributor documentation matches the workflow.

- **ci-tests-cpu.yml** — CPU tests on Ubuntu across Python 3.10–3.14, plus Windows and macOS boundary versions

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Balanced