feat(reid): appearance ReID association via standalone reid package

.github/workflows/ci-integrations.yml

@@ -28,7 +28,7 @@ jobs:
           activate-environment: true
 
       - name: 🚀 Install Packages
-        run: uv sync --frozen --group dev
+        run: uv sync --frozen --group dev --extra reid
 
 
       - name: 🧪 Run Integration Tests

.github/workflows/ci-reid-prerelease.yml

@@ -0,0 +1,31 @@
+name: ReID Pre-release Compatibility
+
+on:
+  schedule:
+    - cron: "17 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  reid-integration-smoke:
+    name: ReID Integration Smoke
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: 🐍 Install uv and set Python version
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          python-version: "3.12"
+          activate-environment: true
+
+      - name: 🚀 Install Packages with the latest allowed reid pre-release
+        run: uv sync --group dev --extra reid --upgrade-package reid
+
+      - name: 🧪 Smoke-test the trackers to reid boundary
+        run: uv run pytest tests/core/test_botsort_reid.py::TestBoTSORTTrackerReID::test_real_reid_model_runs_over_frames -v --tb=short

README.md

@@ -18,6 +18,7 @@
 - **Benchmarked across four datasets.** MOT17, SportsMOT, SoccerNet, and DanceTrack — at default parameters and after hyperparameter tuning (McByte: defaults only, by design), so you know what to expect before you deploy.
 - **Tunable with one extra.** Optuna-based hyperparameter search via `trackers tune` (`pip install "trackers[tune]"`) so you can optimize for your specific scene and detector.
 - **Camera motion compensation.** BoT-SORT and McByte handle moving cameras natively, keeping track IDs stable even when the whole frame shifts.
+- **Optional appearance ReID.** BoT-SORT can fuse visual embeddings with motion for harder association scenes: install `trackers[reid]` (pulls in the [`reid`](https://github.com/roboflow/re-ID) package), pass a `reid.ReIDModel` as `reid_model`, and supply `frame=` to `update()`.
 
 ## Install
 

docs/adr/0001-model-backend-externalization.md

@@ -0,0 +1,33 @@
+---
+title: 'ADR: Model-backend externalization: vendor vs external package'
+description: Decision criteria for keeping model-backend integration in Trackers or consuming it from a separate package.
+---
+
+# Model-backend externalization: vendor vs external package
+
+- Status: Accepted
+- Date: 2026-08-14
+
+## Context
+
+Trackers needs learned-model backends without making them part of its core tracking API. The existing mask pipeline keeps its SAM and Cutie integration in `trackers.core.masks`: Trackers owns checkpoint discovery, preprocessing, inference lifecycle, and conversion to the mask protocols. The upstream model packages and weights remain optional dependencies; “vendor” here means owning the backend integration code, not copying upstream model source.
+
+Appearance ReID has a different boundary. Trackers owns the `ReIDEncoder` protocol, feature bank, association helpers, and threshold-analysis tools. Model architectures, pretrained checkpoints, preprocessing, training, and gallery evaluation live in the standalone `reid` package, installed by the `reid` extra.
+
+## Decision
+
+Keep the ReID model backend in the external `reid` package. Trackers consumes it through the small `ReIDEncoder.extract_features(detections, frame)` contract and does not duplicate model-loading or model-catalog code.
+
+Choose the ownership boundary for future learned backends using these criteria:
+
+- Keep integration in Trackers when it is tightly coupled to tracker state or frame-to-frame lifecycle, and a small, stable set of backends implements a Trackers-owned protocol.
+- Use an external package when model architectures, training, preprocessing, checkpoint catalogs, or release cadence form a substantial product surface independent of multi-object tracking.
+- In both cases, import heavy optional dependencies lazily, expose a lightweight protocol from Trackers, and keep tracker behavior usable without the extra.
+- Revisit an in-repo backend if its integration grows an independently useful model API; revisit an external backend if its boundary cannot express required tracker lifecycle semantics without leaking implementation details.
+
+## Consequences
+
+- `trackers` stays focused on tracking and association while `reid` can evolve models and training independently.
+- Users install `trackers[reid]` for the supported ReID backend; custom encoders may implement `ReIDEncoder` without depending on that package.
+- Compatibility is enforced at the protocol and optional-dependency version range, so cross-package changes require coordinated tests and releases.
+- The masks and ReID layouts remain intentionally asymmetric: mask lifecycle adapters are Trackers-owned, while ReID model implementations are external.

docs/api/reid.md

@@ -0,0 +1,75 @@
+---
+description: Python API reference for the ReID encoder protocol, feature bank, appearance association utilities, and threshold-selection plots in Roboflow Trackers.
+---
+
+# ReID API
+
+Requires the `reid` extra (`pip install "trackers[reid]"`, see the [install guide](../guides/install.md)).
+
+This page covers the `ReIDEncoder` protocol, `FeatureBank`, appearance association helpers, and the threshold-selection plots in `trackers.core.reid`. For enabling appearance on BoT-SORT and for benchmark results, see the [ReID appearance guide](../guides/reid.md). Model loading and gallery evaluation are in the standalone [`reid`](https://github.com/roboflow/re-ID) package.
+
+## ReIDEncoder
+
+::: trackers.core.reid.encoder.ReIDEncoder
+
+## FeatureBank
+
+::: trackers.core.reid.feature_bank.FeatureBank
+
+## appearance_similarity
+
+::: trackers.core.reid.appearance.appearance_similarity
+
+## extract_detection_embeddings
+
+::: trackers.core.reid.appearance.extract_detection_embeddings
+
+## Choosing a threshold
+
+Measure your own encoder on your own footage instead of inheriting a threshold from a paper. These helpers embed a labeled dataset, sample the distances a tracker actually sees, plot them, and report separability. Plotting needs `matplotlib`, which ships with the `reid` extra.
+
+Both plot functions take their reference lines as `ThresholdLines`, either a sequence of values or a mapping from value to annotation.
+
+```python
+from trackers.core.reid import (
+    extract_ground_truth_embeddings,
+    plot_appearance_distances,
+    plot_frame_gap_sweep,
+    sample_appearance_distances,
+    sweep_frame_gap,
+)
+
+embeddings, ids, frame_ids, sequence_ids = extract_ground_truth_embeddings(model, "mot17/val", keep_classes=(1,))
+distances = sample_appearance_distances(embeddings, ids, frame_ids, sequence_ids)
+same_id_rate, different_id_rate = distances.rates_at(0.25)
+plot_appearance_distances(distances, thresholds={0.20: "selected", 0.25: "default"})
+plot_frame_gap_sweep(sweep_frame_gap(embeddings, ids, frame_ids, sequence_ids))
+```
+
+### extract_ground_truth_embeddings
+
+::: trackers.core.reid.appearance.extract_ground_truth_embeddings
+
+### AppearanceDistances
+
+::: trackers.core.reid.thresholds.AppearanceDistances
+
+### sample_appearance_distances
+
+::: trackers.core.reid.thresholds.sample_appearance_distances
+
+### sweep_frame_gap
+
+::: trackers.core.reid.thresholds.sweep_frame_gap
+
+### roc_auc
+
+::: trackers.core.reid.thresholds.roc_auc
+
+### plot_appearance_distances
+
+::: trackers.core.reid.thresholds.plot_appearance_distances
+
+### plot_frame_gap_sweep
+
+::: trackers.core.reid.thresholds.plot_frame_gap_sweep