feat(xla): test marker, extra + CPU-PJRT CI job

- register `@pytest.mark.xla` marker in pyproject.toml for XLA/torch_xla-runtime tests (any PJRT backend)
- add `xla` optional-dependency extra: `torch_xla>=2.5,<3.0; sys_platform == 'linux'` (linux-only wheels; coexists with torch)
- exclude xla-marked tests from CPU CI filter (`and not xla`) in ci-tests-cpu.yml
- add ci-tests-xla.yml: Linux CPU-PJRT lane (`PJRT_DEVICE=CPU`) running `-m "xla and not gpu"`, self-passes via pytest exit-5 guard until xla tests land

---
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: Borda

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

@@ -65,7 +65,7 @@ jobs:
       - name: 🧪 Run the Test
         run: |
           uv run --no-sync pytest src/ tests/ \
-            -n 2 -m "not gpu and not coco17 and not e2e_coreml and not e2e_executorch" \
+            -n 2 -m "not gpu and not coco17 and not e2e_coreml and not e2e_executorch and not xla" \
             --ignore=tests/run_smoke_all_models.py \
             --ignore=tests/legacy/test_checkpoint_compat.py \
             --cov=rfdetr --cov-report=xml \

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

@@ -0,0 +1,84 @@
+name: XLA tests Workflow
+
+# Hardware-free validation of the XLA code paths (grid_sample gather branch, all_gather device
+# probe, XLAPrecision selection, bool-mask dtype, keypoint host-sync gates, ...). torch_xla reports
+# device.type == "xla" on ANY PJRT backend, so PJRT_DEVICE=CPU exercises every device-gated branch
+# without a TPU. Real-TPU-only concerns (MXU/TFLOPS, bf16-MXU convergence parity) stay on Colab/Kaggle.
+#
+# torch_xla ships Linux x86_64 wheels only -> ubuntu runner. Its minor must match torch's minor;
+# floating both to the latest in torch>=2.2,<3 keeps them aligned (torch_xla 2.9 <-> torch 2.9).
+#
+# Trigger is manual + PR for now; the job self-passes while no @pytest.mark.xla tests exist yet
+# (pytest exit code 5 = "no tests collected"). Flip the guard off once Phase 1 lands xla tests.
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: ["main", "release/*", "develop"]
+    paths:
+      - "src/rfdetr/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/ci-tests-xla.yml"
+
+permissions:
+  contents: read
+defaults:
+  run:
+    shell: bash
+
+env:
+  UV_TORCH_BACKEND: "cpu" # CPU-only torch; works with 'uv pip'
+  PJRT_DEVICE: "CPU" # run XLA on the CPU PJRT plugin (no TPU, no libtpu)
+
+concurrency:
+  group: pytest-xla-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  run-xla-tests:
+    name: XLA CPU-PJRT testing
+    timeout-minutes: 25
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: 🐍 Install uv and set Python version 3.11
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          version: "0.9.26"
+          python-version: "3.11"
+          activate-environment: true
+
+      - name: 🚀 Install Packages (torch + torch_xla, CPU)
+        timeout-minutes: 8
+        # [xla] pulls torch_xla; UV_TORCH_BACKEND=cpu keeps torch CPU-only. Both float to the latest
+        # matching minor within torch>=2.2,<3, so torch_xla and torch stay ABI-aligned.
+        run: |
+          uv pip install -e ".[train,xla,cli]" --group tests
+
+      - name: 🔎 Verify torch_xla runtime
+        run: |
+          uv run --no-sync python -c "import torch, torch_xla, torch_xla.core.xla_model as xm; d = xm.xla_device(); print('torch', torch.__version__, '| torch_xla', torch_xla.__version__, '| device', d); assert str(d).startswith('xla')"
+
+      - name: 🧪 Run the XLA-marked Tests
+        run: |
+          set +e
+          uv run --no-sync pytest src/ tests/ \
+            -n 1 -m "xla and not gpu" \
+            --ignore=tests/run_smoke_all_models.py \
+            --ignore=tests/legacy/test_checkpoint_compat.py \
+            --timeout=420 \
+            --durations=50
+          rc=$?
+          set -e
+          if [ "$rc" -eq 5 ]; then
+            echo "No @pytest.mark.xla tests collected yet (Phase 1 not landed) — passing."
+            exit 0
+          fi
+          exit $rc
+
+      - name: Minimize uv cache
+        continue-on-error: true
+        run: uv cache prune --ci

pyproject.toml

@@ -132,6 +132,16 @@ visual = [
 ]
 cli = ["jsonargparse[signatures]>=4.27.7"]
 plus = ["rfdetr_plus>=1.0.1, <2.0.0"]
+# XLA backend for TPU training AND hardware-free XLA validation on CPU/GPU PJRT.
+# torch_xla is built on top of torch (NOT mutually exclusive — it requires torch present) and its
+# minor MUST match the installed torch minor (torch_xla 2.7.* <-> torch 2.7.*); it does not hard-pin
+# torch in requires_dist, so keep the two aligned yourself. Wheels are Linux x86_64 only (py3.10-3.13)
+# -> sys_platform marker keeps macOS/Windows installs of this extra a no-op. The bare wheel runs the
+# CPU PJRT plugin (PJRT_DEVICE=CPU) with no libtpu; real TPU adds torch_xla[tpu] (libtpu), GPU PJRT
+# needs the separate CUDA plugin wheel. Used by ci-tests-xla.yml to exercise @pytest.mark.xla paths.
+xla = [
+    "torch_xla>=2.5,<3.0; sys_platform == 'linux'",
+]
 
 [dependency-groups]
 # TODO: Temporary: GPU runner only has CUDA 12.8 driver (12080); torch>=2.11 requires a newer driver.
@@ -287,6 +297,7 @@ doctest_norecursedirs = ["tests/*"]
 pythonpath = ["src", "."]
 markers = [
     "gpu: tests that require GPU or are slow on CPU",
+    "xla: tests that require an XLA device or torch_xla runtime (TPU, or CPU/GPU PJRT)",
     "coco17: tests that require COCO 2017 images or annotations",
     # `flaky` is provided by pytest-rerunfailures; registered here too for clarity and to stay
     # safe under --strict-markers (used by tests/benchmarks/test_training_*.py).