Research
research proposes tracker code changes and scores them against a fixed
experiment and immutable build. Prepare its dependencies with
boxmot install --extra research; see Install dependencies.
It requires both inputs:
boxmot research \
--experiment mot17/ablation-yolox-lmbn.yaml \
--build BUILD_ID \
--tracker bytetrack \
--proposal-model openai/gpt-5.4 \
--max-metric-calls 24
The parent process validates the build before creating isolated workspaces. Each candidate replays selected keyed sequences through the live tracker API; candidate workspaces do not perform perception inference or mutate the build.
Run materialization separately when required:
There is no implicit build creation or latest-build lookup. This makes metric changes attributable to tracker code or parameters rather than changing detections and embeddings.
Arguments
boxmot research
Research tracker code changes with GEPA
Usage:
Options:
--experiment TEXT experiment YAML filename or path, e.g.
mot17/ablation-yolox-lmbn.yaml or
boxmot/configs/experiments/mot17/ablation-
yolox-lmbn.yaml
--build TEXT Materialized build ID or explicit build
directory. [required]
--build-root PATH Materialized-dataset root for build IDs and
shared detector cache; overrides
BOXMOT_BUILDS_DIR and defaults to
./runs/materializations.
--data-root PATH Base folder for dataset storage.root;
defaults to ./datasets/mot for built-in
datasets or the local YAML folder.
--project PATH save results to project/name
--name TEXT save results to project/name
--exist-ok existing project/name ok, do not increment
--ci reuse existing runs in CI (no UI)
--tracker [boosttrack|botsort|bytetrack|deepocsort|eagermot|hybridsort|maf_hda|occluboost|ocsort|sfsort|strongsort]
one of: boosttrack, botsort, bytetrack,
deepocsort, eagermot, hybridsort, maf_hda,
occluboost, ocsort, sfsort, strongsort
[default: bytetrack]
--variable-dt / --fixed-dt Use capture timestamps for Kalman
prediction; otherwise keep the tracker YAML
setting (default: fixed dt).
--verbose print detailed logs
--show-timing / --hide-timing print runtime timing summary after
evaluation [default: hide-timing]
--per-class track each class separately
--proposal-model TEXT proposal model identifier used by GEPA
reflections, e.g. openai/gpt-5.4,
anthropic/claude-sonnet-4-20250514,
openrouter/openai/gpt-5.4 [default:
openai/gpt-5.4]
--proposal-api-key TEXT proposal model API key; prefer shell env
vars in CI but this can inject the key at
runtime
--proposal-api-key-env TEXT environment variable name for --proposal-
api-key when the provider is not inferred,
e.g. OPENAI_API_KEY or ANTHROPIC_API_KEY
--max-metric-calls INTEGER maximum number of benchmark evaluations
during research [default: 24]
--eval-timeout FLOAT hard timeout in seconds for each benchmark
evaluation [default: 900.0]
--keep-workspace / --no-keep-workspace
preserve the temporary research workspace
after the run [default: no-keep-workspace]
--hota-penalty FLOAT penalty multiplier for combined HOTA
regression versus baseline [default: 0.0]
--idf1-penalty FLOAT penalty multiplier for combined IDF1
regression versus baseline [default: 1.0]
--mota-penalty FLOAT penalty multiplier for combined MOTA
regression versus baseline [default: 1.0]
--hota-tolerance FLOAT allowed combined HOTA drop before penalties
apply [default: 0.0]
--idf1-tolerance FLOAT allowed combined IDF1 drop before penalties
apply [default: 0.0]
--mota-tolerance FLOAT allowed combined MOTA drop before penalties
apply [default: 0.0]
--help Show this message and exit.