Commit 4dcb9a7

DeepLabCut 3.0.2 is a patch release bringing several PyTorch workflows fixes,

improved config handling and export reliability, broadened compatibility for newer

NumPy / Matplotlib versions, and adding a machine-readable docs/API index for

agent-assisted interactions with the library.

- Forward-compatibility work for NumPy 2, pandas 3 CoW, and Matplotlib 3.9,

including releasing core NumPy / Matplotlib upper bounds (#3420, #3498,

#3502, #3508, #3499, #3445, #3394).

- More reliable COCO training: `model_cfg.metadata` is authoritative, with

fail-fast validation against annotation JSON (#3435).

- Safer legacy project configs: empty / `null` top-level YAML fields are treated

as unset; `ignore_empty` is removed (#3439).

- Normalized `export_model` pickles for downstream / real-time consumers (#3473).

- Detector `null` thresholds resolve to field defaults instead of crashing

(#3470, #3475).

- PyTorch `analyze_videos` / auto-track honor the `overwrite` argument instead of

hard-coding `overwrite=False` (#3514).

- Public LLM-friendly knowledge index (`llms.txt`, `docs.jsonl`, `api.jsonl`)

plus hardening follow-up and `AGENTS.md` (#3453, #3494, #3483).

Core installs no longer pin `numpy<2` or a Matplotlib upper bound. Also added

`numba>=0.60` and an explicit OpenCV dependency. TensorFlow extras still keep a

NumPy `<2` ceiling where the corresponding TensorFlow build requires it.

- #3420 — Prepare for NumPy 2 forward compatibility (including dense SVD for

tracklet ranking instead of randomized interpolative SVD)

- #3498 — Fix broken NumPy 2.0 compatibility in `crossvalutils` and

`predict_multianimal`

- #3502 — NumPy 2 + numba: take the real part of eig eigenvectors in

`EllipseFitter`

- #3508 — Follow-up NumPy 2 fixes (PyTorch snapshot metric loading /

`Assembly.affinity` typing; raise `numba` floor; declare OpenCV)

- #3499 — Remove core NumPy and Matplotlib upper bounds (NumPy `<2` remains

only where TensorFlow extras still require it; exclude broken Matplotlib

3.7 / 3.7.1)

- #3445 — Guard pandas 3 Copy-on-Write read-only `.to_numpy()` / `.values`

mutations

- #3394 — Matplotlib v3.9 compatibility

- #3509 — Tighten strict canary CI handling (`strict_cells` for same-repo

pushes/PRs; fork PRs stay non-blocking)

`bodyparts` / individuals capacity now come from `model_cfg.metadata`, matching

`DLCLoader`. Construction validates `train.json` and `test.json` and raises

`ValueError` if an image exceeds configured capacity or bodyparts do not match.

Projects that previously relied on capacity inferred only from the busiest

training image should set `max_individuals` (and bodyparts) explicitly.

Empty top-level YAML fields are treated as unset and emit an actionable warning.

`DLCBaseConfig.from_yaml(..., ignore_empty=...)` no longer accepts `ignore_empty`

(breaking for that optional parameter). Lower-level `read_config(..., ignore_empty=...)`

deprecates the argument.

`export_model` now calls `PoseConfig.to_dict(normalize=True)`, so pickles store

primitives (`Path` → `str`, enums → `str`, etc.). Prefer re-exporting models for

consumers that load the pickled config.

`analyze_videos` and the auto-track path now forward the caller’s `overwrite`

flag instead of always behaving as `overwrite=False`. Existing prediction files

are skipped only when `overwrite` is false.

- #3436 — Add `detector_eval_interval` to `train_from_coco`

- #3475 — Add `DefaultIfNone` config validator (`null` → field default)

- #3481 — Harden wandb logger error handling (validate before `wandb.init`)

Coding agents and LLM tools can now discover DeepLabCut knowledge without

scraping HTML.

CI builds and deploys a structured index with the docs site:

- `llms.txt` — [llmstxt.org](https://llmstxt.org)-style entry point at the docs

root ([published here](https://deeplabcut.github.io/DeepLabCut/llms.txt)

after deploy)

- `knowledge/manifest.json` — which API versions are indexed and which is current

- `knowledge/main/docs.jsonl` — one JSON object per user-docs page and heading

- `knowledge/<version>/api.jsonl` — one JSON object per documented API symbol

Also added: [`AGENTS.md`](https://github.com/DeepLabCut/DeepLabCut/blob/main/AGENTS.md),

shared guidance for humans and coding agents.

- #3453 — Knowledge indexing generator + CI deploy (`tools/knowledge_indexing`)

- #3494 — Follow-up hardening for the LLM knowledge index (dependency bounds,

stable vs `main` API links in `llms.txt`, safer skip/empty-dir publish

behavior, anchor/regression fixes)

- #3483 — Add `AGENTS.md` for AI-assisted development

- #3419 — Skip TensorFlow-backed tests cleanly when the `tf` extra is absent

- #3435 — Fix `COCOLoader`: treat `model_cfg.metadata` / `max_individuals` as

authoritative instead of inferring solely from `train.json`

- #3439 — Update `None`-type validation for legacy `ProjectConfig` templates;

remove `ignore_empty`

- #3441 — GUI config editor crash + shared deferred reload on `DefaultTab`

- #3447 — Evaluation visualization fixes, clean-up, and coverage improvements

- #3449 — Fix frame extraction failure with pathlib video selections

- #3452 — Fix incorrect SuperAnimal HumanBody rename mapping in ModelZoo /

Hugging Face download

- #3467 — Fix faulty `str` / `Path` conversions

- #3468 — Fix latent bugs and misleading errors in GUI `create_videos`

- #3469 — Fix `WandbLoggerConfig` so extra wandb kwargs validate (scoop into

`wandb_kwargs`)

- #3470 — Fix Faster R-CNN detector inference crashing on

`box_score_thresh: null`

- #3473 — Fix `export_model` dumping unnormalized objects in pickle

- #3480 — Fix GUI tests: use `config_path` after rename

- #3484 — Fix `tools` imports under a plain `pytest` invocation

- #3486 — Docs: fix dead Model Zoo link in `examples/README.md`

- #3514 — Fix hard-coded `overwrite=False` in PyTorch `analyze_videos` /

auto-track path

Please let us know if you face any issues with this release, especially related

to the latest forward compatibility efforts, we appreciate any issues or reports!