Upload ObjectModel-v1: code, README, assets (v1 checkpoint)

.gitattributes

@@ -33,3 +33,9 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/examples/family.jpg filter=lfs diff=lfs merge=lfs -text
+assets/examples/food_tray.jpg filter=lfs diff=lfs merge=lfs -text
+assets/examples/rodeo.jpg filter=lfs diff=lfs merge=lfs -text
+assets/examples/street_market.jpg filter=lfs diff=lfs merge=lfs -text
+assets/tracking_demo.gif filter=lfs diff=lfs merge=lfs -text
+assets/tracking_demo.mp4 filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 Bench Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,270 @@
+---
+license: apache-2.0
+tags:
+  - object-detection
+  - pytorch
+  - computer-vision
+  - research
+---
+
+# ObjectModel-v1
+
+ObjectModel-v1 is a clean-room, compact, end-to-end object detector from Bench Labs. It is a
+research implementation, not a benchmark claim. The model tests
+whether global semantic reasoning can be compressed into a small fixed latent memory while
+precise geometry is recovered by query-conditioned sampling from full-resolution pyramid
+features.
+
+The model is NMS-free. It predicts a fixed set of objects and is trained with Hungarian
+bipartite matching.
+
+This is v1: a single from-scratch training run with no pretraining, no hyperparameter search
+across seeds, and none of the ablations `RESEARCH.md` calls for. Treat everything below as a
+first checkpoint in an ongoing process, not a finished result. v2 is expected to do meaningfully
+better, whether that comes from more training compute, an architecture change informed by v1's
+ablations, or both.
+
+## Status
+
+- Architecture, COCO data path, losses, training, evaluation, profiling, and ONNX export are implemented.
+- Synthetic forward/loss/backward and data tests are included.
+- Full COCO2017 training is complete: 100 epochs on a single RTX 5090, peak val AP 0.358 at epoch 95.
+  See [Training Progress](#training-progress) below for the full curve.
+- No "state of the art" or "beats YOLO/DETR" claim is made. Final AP (0.358) is below the 40-50
+  range `RESEARCH.md` set as a competitiveness bar against 20-40M-parameter real-time detectors.
+  This is a real, single-seed, un-pretrained result, not a benchmark claim. See the
+  [Minimum Validation Protocol](#minimum-validation-protocol) for what a competitive claim actually
+  requires: controlled baselines, three seeds, and ablations, none of which have been run yet.
+
+## Training Progress
+
+<img src="assets/ap_progress.svg" alt="Validation AP by epoch across the full 100-epoch run, rising from near-zero to a peak of 0.358 at epoch 95" width="900">
+
+| | |
+|---|---|
+| Parameters | 40.8M |
+| Epochs | 100 / 100 (complete) |
+| Peak val AP (IoU 0.50:0.95) | 0.358 (epoch 95) |
+| Final val AP (epoch 100) | 0.356 |
+| Val AP50 / AP75 | 0.542 / 0.377 |
+| Val AP small / medium / large | 0.184 / 0.385 / 0.493 |
+| Val AR@100 | 0.573 |
+| Train loss | 4.11 (from 15.77 at epoch 1) |
+| Throughput | ~90-110 img/s, batch 32, RTX 5090 |
+| Single-frame inference | 30.7 ms / 32.5 FPS (batch 1, eager, RTX 5090) |
+
+Peak AP came at epoch 95 (0.3578), not the final epoch. That is normal late-training fluctuation,
+and `best.pt` correctly holds the epoch-95 weights rather than epoch 100's. Against the 40-50 AP
+range `RESEARCH.md` set as the competitiveness bar, this run falls short. It is a real result from
+a genuine from-scratch run, on the low end of what the project's own research memo was aiming for.
+The gap is exactly what the [Minimum Validation Protocol](#minimum-validation-protocol) exists to
+characterize properly: whether more decoder layers, more latents, longer training, or pretraining
+would close it is unknown without actually running those ablations.
+
+## Examples
+
+Six detections from the final EMA checkpoint (epoch 95, peak AP) on COCO val2017 images,
+confidence &ge; 0.35. Picked for variety, not cherry-picked for perfection.
+
+| | |
+|---|---|
+| ![A tray of Japanese desserts and a sake bottle, each item individually boxed](assets/examples/food_tray.jpg) | ![A child on a skateboard with a parent, skateboard detected at high confidence](assets/examples/skatepark.jpg) |
+| Dessert tray, bottle, bowl, and a dozen individually boxed items | Skate park, parent and child, skateboard at 0.93 confidence |
+| ![A street market with a person at 0.94 confidence and umbrella awning detected](assets/examples/street_market.jpg) | ![A rodeo scene with multiple people correctly boxed in a crowd](assets/examples/rodeo.jpg) |
+| Street market, person at 0.94, market umbrella | Rodeo, crowd of people, one animal still mislabeled |
+| ![A parent holding a baby at a table, with cup, chair, and bottle detected](assets/examples/family.jpg) | ![A rainbow kite in flight above a beach with people and a distant boat](assets/examples/kite_beach.jpg) |
+| Family at a table, cups, chair, bottle, two people | Beach, kite at 0.80, people along the shore, a distant boat |
+
+## Live Tracking Demo
+
+<img src="assets/tracking_demo.gif" alt="ObjectModel-v1 detections chained through a SORT tracker on real pedestrian footage, boxes and ids tracking people across frames" width="420">
+
+[Full-length video (20s, MP4)](assets/tracking_demo.mp4)
+
+ObjectModel-v1 itself has no temporal component. Every frame is detected independently. The clip
+above chains detections through a from-scratch SORT-style tracker (`src/objectmodel_v1/tracking.py`:
+constant-velocity Kalman motion model plus IoU/Hungarian frame-to-frame association) to give boxes
+a persistent id and a short motion trail. Source footage is `vtest.avi`, OpenCV's standard
+pedestrian test clip (BSD-3, ships with OpenCV), genuine video the model never trained on.
+
+This is the same clip run at three points in training, tracker unchanged throughout. Only the
+detector's checkpoint improved:
+
+| Checkpoint | Ids issued over 20s | Longest-lived ids |
+|---|---|---|
+| Epoch 13 (AP 0.227) | ~89 | none survive past a few seconds |
+| Epoch 26 (AP 0.288) | ~84 | 3 ids survive nearly the full clip |
+| Epoch 95 (AP 0.358, final) | 92 | 4 ids survive nearly the full clip |
+
+Track count issued does not fall much, since new people keep entering frame throughout the clip
+and each one earns a new id, which is correct behavior. Track persistence for people already in
+frame improved consistently instead. A separate test on a genuinely different scene, an eye-level
+warehouse clip not shown here, also surfaced a real and distinct limitation: the detector still
+occasionally hallucinates objects on plain background surfaces, reading a support pillar as
+"refrigerator", even at this final checkpoint. Tracking quality rides on detection quality, and
+detection quality on out-of-domain footage (camera angles, lighting, and compression that COCO's
+photos do not really cover) is visibly weaker than on COCO's own validation images.
+
+## Architecture
+
+```text
+image
+  -> compact convolutional backbone (strides 8/16/32)
+  -> top-down pyramid fusion
+  -> pooled multi-scale tokens
+  -> fixed latent memory (global semantics)
+  -> learned object queries
+       -> query self-attention
+       -> cross-attention to latent memory
+       -> local sampling around the current query box
+       -> iterative class and box prediction
+  -> object set (no anchors, no NMS)
+```
+
+The local sampling radius scales with each query's current width and height. Early decoder
+layers can search broadly; later layers focus naturally as boxes are refined. During training,
+an optional dense auxiliary head adds one-to-many spatial supervision. It is discarded for
+inference and must be evaluated as an ablation, not assumed to help.
+
+## Installation
+
+Use Python 3.11 or another PyTorch-supported Python version:
+
+```bash
+python3.11 -m venv .venv
+.venv/bin/pip install --upgrade pip
+.venv/bin/pip install -e '.[coco,export,dev]'
+```
+
+For a specific CUDA build, install the matching PyTorch wheel first using the command from
+<https://pytorch.org/get-started/locally/>, then install ObjectModel-v1.
+
+## Data
+
+The default configuration expects COCO 2017:
+
+```text
+/path/to/coco/
+  annotations/instances_train2017.json
+  annotations/instances_val2017.json
+  train2017/*.jpg
+  val2017/*.jpg
+```
+
+Category IDs are mapped to contiguous training labels and converted back during evaluation.
+Images without target objects are supported.
+
+## Commands
+
+Profile the model before allocating training compute:
+
+```bash
+objectmodel-profile --config configs/objectmodel_v1.yaml --device cuda
+```
+
+Overfit a small dataset first. A full single-GPU command is:
+
+```bash
+objectmodel-train \
+  --config configs/objectmodel_v1.yaml \
+  --data-root /path/to/coco \
+  --output outputs/objectmodel_v1
+```
+
+Distributed training:
+
+```bash
+torchrun --standalone --nproc_per_node=8 -m objectmodel_v1.train \
+  --config configs/objectmodel_v1.yaml \
+  --data-root /path/to/coco \
+  --output outputs/objectmodel_v1
+```
+
+Resume and override configuration values:
+
+```bash
+objectmodel-train \
+  --config outputs/objectmodel_v1/config.yaml \
+  --data-root /path/to/coco \
+  --output outputs/objectmodel_v1 \
+  --resume outputs/objectmodel_v1/last.pt \
+  --set train.batch_size=8
+```
+
+Evaluate the EMA checkpoint with canonical `pycocotools` metrics:
+
+```bash
+objectmodel-eval \
+  --config outputs/objectmodel_v1/config.yaml \
+  --checkpoint outputs/objectmodel_v1/best.pt \
+  --data-root /path/to/coco
+```
+
+Export raw logits and normalized `cxcywh` boxes to ONNX:
+
+```bash
+objectmodel-export \
+  --config outputs/objectmodel_v1/config.yaml \
+  --checkpoint outputs/objectmodel_v1/best.pt \
+  --output outputs/objectmodel_v1/objectmodel-v1.onnx
+```
+
+Track detections across video frames (see [Live Tracking Demo](#live-tracking-demo); this is a
+post-processing layer over independent per-frame detections, not a model capability):
+
+```python
+from objectmodel_v1.tracking import SortTracker
+
+tracker = SortTracker(iou_threshold=0.3, max_age=5, min_hits=2)
+for frame in video_frames:
+    boxes, labels, scores = detect(frame)  # your decode_predictions() call
+    for t in tracker.update(boxes, labels, scores):
+        print(t.id, t.box, t.label, t.score)
+```
+
+## Minimum Validation Protocol
+
+Before describing ObjectModel-v1 as competitive, run all models on the same COCO train2017 and
+val2017 data, image resolution, augmentation budget, training epochs, and hardware. Report:
+
+- COCO AP, AP50, AP75, APS, APM, and APL.
+- Parameters, FLOPs/MACs, FP32/FP16/INT8 artifact sizes.
+- End-to-end batch-1 median and p95 latency, including preprocessing and decoding.
+- Peak training and inference memory, GPU-hours, epochs, and images seen.
+- Three seeds for the principal result, with mean and standard deviation.
+- Results both from random initialization and with the same permitted pretraining.
+
+Required ablations:
+
+| Experiment | Question |
+|---|---|
+| latent memory vs flattened feature attention | Does compression preserve useful global context? |
+| local sampler disabled | Does high-resolution geometric evidence improve localization? |
+| fixed vs box-scaled offsets | Does coarse-to-fine sampling matter? |
+| dense auxiliary head disabled | Does added supervision improve convergence? |
+| 1/2/3 latent layers | Where is the accuracy/latency optimum? |
+| 32/64/96 latents | How aggressively can global context be compressed? |
+| 3/4/6 decoder layers | What is the anytime speed/accuracy curve? |
+
+Suggested external baselines are RT-DETR-R18, D-FINE-N/S, LW-DETR-T/S, and YOLOX-S. Use
+their official implementations and report their license and measurement setup separately.
+
+## Research Basis
+
+ObjectModel-v1 builds on published, independently attributable ideas:
+
+- DETR: set prediction and Hungarian matching.
+- Conditional and Deformable DETR: spatially conditioned/local sparse attention.
+- RT-DETR: efficient separation of multi-scale encoding and query decoding.
+- D-FINE: evidence that fine-grained iterative localization is valuable.
+- DEIM: evidence that one-to-one matching benefits from denser training supervision.
+- LW-DETR: evidence that compact transformer detectors can compete with real-time CNNs.
+
+ObjectModel-v1's specific hypothesis is the combination of a **fixed compressed global memory** and
+**box-scaled local pyramid sampling**. Publication novelty requires a broader prior-art search
+and empirical ablations; this repository does not claim that the combination is patent-new.
+
+## License
+
+Apache License 2.0. Dataset images, annotations, pretrained weights, and external baselines
+retain their own licenses and are not included.

RESEARCH.md

@@ -0,0 +1,56 @@
+# ObjectModel-v1 Research Decision
+
+## Decision
+
+Use a compact NMS-free set detector and target roughly 25-45M parameters, despite the stated
+150-200M ceiling. Current real-time detectors already demonstrate strong COCO results in the
+20-40M range. More parameters would weaken the deployment story without establishing novelty.
+
+## Evidence Reviewed
+
+| Family | Relevant result reported by its authors | Lesson for ObjectModel-v1 |
+|---|---|---|
+| RT-DETR | R18: 20M parameters and 46.5 COCO AP; R50: 42M and 53.1 AP | Efficient hybrid encoding plus query decoding is a strong baseline. |
+| D-FINE | L: 31M, 54.0 AP, 91 GFLOPs; FDR + GO-LSD adds 1.0 AP in its roadmap ablation | Localization representation and supervision remain high-value. |
+| DEIM | Dense O2O + matchability-aware loss improves convergence; D-FINE-L reaches 54.7 AP in the paper | Sparse one-to-one supervision is a training bottleneck. |
+| LW-DETR | Plain compact ViT plus shallow decoder is competitive in reported real-time comparisons | A detector need not use a large decoder or full multi-scale attention. |
+| YOLOX | Anchor-free decoupled detector with Apache-2.0 implementation | Strong permissive NMS-based baseline. |
+
+These are paper/repository claims under their stated training and latency setups. They are not
+ObjectModel-v1 results and should not be compared across papers as if hardware, data, and software
+were controlled.
+
+## Hypothesis
+
+Most detector features do not need expensive global interaction at native pyramid resolution.
+A fixed set of learned latents can carry global semantics, while each object query can recover
+precise local evidence from the original pyramid near its evolving box. This should make global
+reasoning cost independent of image token count after pooling, while preserving a direct path
+to small-object and boundary evidence.
+
+The hypothesis fails if any of the following occur:
+
+1. Flattened multi-scale attention at matched compute materially outperforms latent memory.
+2. Local sampling does not improve AP75 or small-object AP.
+3. Latent compression creates an accuracy drop larger than its measured latency benefit.
+4. Dense auxiliary supervision increases training complexity without improving convergence.
+
+## Claim Gate
+
+Do not use "revolutionary," "state of the art," or "beats YOLO/DETR" in public materials until:
+
+1. The controlled baseline and ablation matrix in `README.md` is complete.
+2. At least three seeds support the principal comparison.
+3. Latency is measured end to end on disclosed hardware and exported runtimes.
+4. Training data and pretraining are identical or differences are prominently disclosed.
+5. Failure cases and per-scale metrics are published.
+
+## Primary Sources
+
+- RT-DETR: <https://arxiv.org/abs/2304.08069>
+- D-FINE: <https://arxiv.org/abs/2410.13842>
+- DEIM: <https://arxiv.org/abs/2412.04234>
+- LW-DETR: <https://arxiv.org/abs/2406.03459>
+- DETR implementation: <https://github.com/facebookresearch/detr>
+- YOLOX implementation: <https://github.com/Megvii-BaseDetection/YOLOX>
+- COCO API: <https://github.com/cocodataset/cocoapi>

assets/tracking_demo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9385404ce1b0d53f9433a5666f314d9c4dc87de3628dd11496ffd39199bd2fdd
+size 2812004

configs/objectmodel_v1.yaml

@@ -0,0 +1,61 @@
+model:
+  num_classes: 80
+  input_size: 640
+  stem_channels: 64
+  backbone_channels: [96, 192, 384, 512]
+  backbone_depths: [2, 3, 6, 3]
+  hidden_dim: 384
+  fpn_depth: 2
+  latent_count: 64
+  latent_pool_sizes: [12, 6, 3]
+  latent_layers: 2
+  decoder_layers: 8
+  num_queries: 300
+  num_heads: 8
+  local_points: 4
+  dropout: 0.0
+  dense_aux: true
+
+loss:
+  cost_class: 2.0
+  cost_bbox: 5.0
+  cost_giou: 2.0
+  weight_class: 2.0
+  weight_bbox: 5.0
+  weight_giou: 2.0
+  weight_dense: 1.0
+  focal_alpha: 0.25
+  focal_gamma: 2.0
+  aux_weight: 1.0
+  dense_topk: 5
+
+train:
+  epochs: 150
+  batch_size: 16
+  eval_batch_size: 8
+  workers: 8
+  prefetch_factor: 4
+  lr: 0.0002
+  backbone_lr: 0.0001
+  min_lr_ratio: 0.05
+  weight_decay: 0.05
+  warmup_steps: 1500
+  clip_grad_norm: 0.1
+  amp: true
+  amp_dtype: bfloat16
+  channels_last: false
+  compile: false
+  ema_decay: 0.9998
+  seed: 42
+  eval_every: 1
+  print_freq: 50
+
+data:
+  train_image_dir: train2017
+  train_annotations: annotations/instances_train2017.json
+  val_image_dir: val2017
+  val_annotations: annotations/instances_val2017.json
+  hflip_prob: 0.5
+  scale_range: [0.65, 1.0]
+  mean: [0.485, 0.456, 0.406]
+  std: [0.229, 0.224, 0.225]

configs/objectmodel_v1_tiny.yaml

@@ -0,0 +1,56 @@
+model:
+  num_classes: 80
+  input_size: 384
+  stem_channels: 32
+  backbone_channels: [48, 96, 192, 256]
+  backbone_depths: [1, 2, 3, 2]
+  hidden_dim: 192
+  fpn_depth: 1
+  latent_count: 32
+  latent_pool_sizes: [8, 4, 2]
+  latent_layers: 1
+  decoder_layers: 3
+  num_queries: 100
+  num_heads: 6
+  local_points: 4
+  dropout: 0.0
+  dense_aux: true
+
+loss:
+  cost_class: 2.0
+  cost_bbox: 5.0
+  cost_giou: 2.0
+  weight_class: 2.0
+  weight_bbox: 5.0
+  weight_giou: 2.0
+  weight_dense: 1.0
+  focal_alpha: 0.25
+  focal_gamma: 2.0
+  aux_weight: 1.0
+  dense_topk: 3
+
+train:
+  epochs: 20
+  batch_size: 8
+  workers: 4
+  lr: 0.0002
+  backbone_lr: 0.0001
+  min_lr_ratio: 0.05
+  weight_decay: 0.05
+  warmup_steps: 200
+  clip_grad_norm: 0.1
+  amp: true
+  ema_decay: 0.9998
+  seed: 42
+  eval_every: 1
+  print_freq: 20
+
+data:
+  train_image_dir: train2017
+  train_annotations: annotations/instances_train2017.json
+  val_image_dir: val2017
+  val_annotations: annotations/instances_val2017.json
+  hflip_prob: 0.5
+  scale_range: [0.7, 1.0]
+  mean: [0.485, 0.456, 0.406]
+  std: [0.229, 0.224, 0.225]

pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "objectmodel-v1"
+version = "0.1.0"
+description = "ObjectModel-v1: compact end-to-end object detection research"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+dependencies = [
+  "numpy>=1.26",
+  "Pillow>=10.0",
+  "PyYAML>=6.0",
+  "scipy>=1.11",
+  "torch>=2.4",
+]
+
+[project.optional-dependencies]
+coco = ["pycocotools>=2.0.7"]
+export = ["onnx>=1.16", "onnxscript>=0.1"]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+objectmodel-train = "objectmodel_v1.train:main"
+objectmodel-eval = "objectmodel_v1.evaluate:main"
+objectmodel-export = "objectmodel_v1.export:main"
+objectmodel-profile = "objectmodel_v1.profile:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

src/objectmodel_v1.egg-info/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: objectmodel-v1
+Version: 0.1.0
+Summary: ObjectModel-v1: compact end-to-end object detection research
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: Pillow>=10.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: torch>=2.4
+Provides-Extra: coco
+Requires-Dist: pycocotools>=2.0.7; extra == "coco"
+Provides-Extra: export
+Requires-Dist: onnx>=1.16; extra == "export"
+Requires-Dist: onnxscript>=0.1; extra == "export"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# ObjectModel-v1
+
+ObjectModel-v1 is a clean-room, compact, end-to-end object detector from Bench Labs. It is a
+research implementation, not a benchmark claim. The model tests
+whether global semantic reasoning can be compressed into a small fixed latent memory while
+precise geometry is recovered by query-conditioned sampling from full-resolution pyramid
+features.
+
+The model is NMS-free. It predicts a fixed set of objects and is trained with Hungarian
+bipartite matching.
+
+## Status
+
+- Architecture, COCO data path, losses, training, evaluation, profiling, and ONNX export are implemented.
+- Synthetic forward/loss/backward and data tests are included.
+- No COCO training has been run in this repository yet.
+- No accuracy, speed, or "state of the art" claim is made before controlled benchmarks.
+
+## Architecture
+
+```text
+image
+  -> compact convolutional backbone (strides 8/16/32)
+  -> top-down pyramid fusion
+  -> pooled multi-scale tokens
+  -> fixed latent memory (global semantics)
+  -> learned object queries
+       -> query self-attention
+       -> cross-attention to latent memory
+       -> local sampling around the current query box
+       -> iterative class and box prediction
+  -> object set (no anchors, no NMS)
+```
+
+The local sampling radius scales with each query's current width and height. Early decoder
+layers can search broadly; later layers focus naturally as boxes are refined. During training,
+an optional dense auxiliary head adds one-to-many spatial supervision. It is discarded for
+inference and must be evaluated as an ablation, not assumed to help.
+
+## Installation
+
+Use Python 3.11 or another PyTorch-supported Python version:
+
+```bash
+python3.11 -m venv .venv
+.venv/bin/pip install --upgrade pip
+.venv/bin/pip install -e '.[coco,export,dev]'
+```
+
+For a specific CUDA build, install the matching PyTorch wheel first using the command from
+<https://pytorch.org/get-started/locally/>, then install ObjectModel-v1.
+
+## Data
+
+The default configuration expects COCO 2017:
+
+```text
+/path/to/coco/
+  annotations/instances_train2017.json
+  annotations/instances_val2017.json
+  train2017/*.jpg
+  val2017/*.jpg
+```
+
+Category IDs are mapped to contiguous training labels and converted back during evaluation.
+Images without target objects are supported.
+
+## Commands
+
+Profile the model before allocating training compute:
+
+```bash
+objectmodel-profile --config configs/objectmodel_v1.yaml --device cuda
+```
+
+Overfit a small dataset first. A full single-GPU command is:
+
+```bash
+objectmodel-train \
+  --config configs/objectmodel_v1.yaml \
+  --data-root /path/to/coco \
+  --output outputs/objectmodel_v1
+```
+
+Distributed training:
+
+```bash
+torchrun --standalone --nproc_per_node=8 -m objectmodel_v1.train \
+  --config configs/objectmodel_v1.yaml \
+  --data-root /path/to/coco \
+  --output outputs/objectmodel_v1
+```
+
+Resume and override configuration values:
+
+```bash
+objectmodel-train \
+  --config outputs/objectmodel_v1/config.yaml \
+  --data-root /path/to/coco \
+  --output outputs/objectmodel_v1 \
+  --resume outputs/objectmodel_v1/last.pt \
+  --set train.batch_size=8
+```
+
+Evaluate the EMA checkpoint with canonical `pycocotools` metrics:
+
+```bash
+objectmodel-eval \
+  --config outputs/objectmodel_v1/config.yaml \
+  --checkpoint outputs/objectmodel_v1/best.pt \
+  --data-root /path/to/coco
+```
+
+Export raw logits and normalized `cxcywh` boxes to ONNX:
+
+```bash
+objectmodel-export \
+  --config outputs/objectmodel_v1/config.yaml \
+  --checkpoint outputs/objectmodel_v1/best.pt \
+  --output outputs/objectmodel_v1/objectmodel-v1.onnx
+```
+
+## Minimum Validation Protocol
+
+Before describing ObjectModel-v1 as competitive, run all models on the same COCO train2017 and
+val2017 data, image resolution, augmentation budget, training epochs, and hardware. Report:
+
+- COCO AP, AP50, AP75, APS, APM, and APL.
+- Parameters, FLOPs/MACs, FP32/FP16/INT8 artifact sizes.
+- End-to-end batch-1 median and p95 latency, including preprocessing and decoding.
+- Peak training and inference memory, GPU-hours, epochs, and images seen.
+- Three seeds for the principal result, with mean and standard deviation.
+- Results both from random initialization and with the same permitted pretraining.
+
+Required ablations:
+
+| Experiment | Question |
+|---|---|
+| latent memory vs flattened feature attention | Does compression preserve useful global context? |
+| local sampler disabled | Does high-resolution geometric evidence improve localization? |
+| fixed vs box-scaled offsets | Does coarse-to-fine sampling matter? |
+| dense auxiliary head disabled | Does added supervision improve convergence? |
+| 1/2/3 latent layers | Where is the accuracy/latency optimum? |
+| 32/64/96 latents | How aggressively can global context be compressed? |
+| 3/4/6 decoder layers | What is the anytime speed/accuracy curve? |
+
+Suggested external baselines are RT-DETR-R18, D-FINE-N/S, LW-DETR-T/S, and YOLOX-S. Use
+their official implementations and report their license and measurement setup separately.
+
+## Research Basis
+
+ObjectModel-v1 builds on published, independently attributable ideas:
+
+- DETR: set prediction and Hungarian matching.
+- Conditional and Deformable DETR: spatially conditioned/local sparse attention.
+- RT-DETR: efficient separation of multi-scale encoding and query decoding.
+- D-FINE: evidence that fine-grained iterative localization is valuable.
+- DEIM: evidence that one-to-one matching benefits from denser training supervision.
+- LW-DETR: evidence that compact transformer detectors can compete with real-time CNNs.
+
+ObjectModel-v1's specific hypothesis is the combination of a **fixed compressed global memory** and
+**box-scaled local pyramid sampling**. Publication novelty requires a broader prior-art search
+and empirical ablations; this repository does not claim that the combination is patent-new.
+
+## License
+
+Apache License 2.0. Dataset images, annotations, pretrained weights, and external baselines
+retain their own licenses and are not included.

src/objectmodel_v1.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENSE
+README.md
+pyproject.toml
+src/objectmodel_v1/__init__.py
+src/objectmodel_v1/boxes.py
+src/objectmodel_v1/config.py
+src/objectmodel_v1/data.py
+src/objectmodel_v1/evaluate.py
+src/objectmodel_v1/export.py
+src/objectmodel_v1/losses.py
+src/objectmodel_v1/matching.py
+src/objectmodel_v1/model.py
+src/objectmodel_v1/postprocess.py
+src/objectmodel_v1/profile.py
+src/objectmodel_v1/train.py
+src/objectmodel_v1/utils.py
+src/objectmodel_v1.egg-info/PKG-INFO
+src/objectmodel_v1.egg-info/SOURCES.txt
+src/objectmodel_v1.egg-info/dependency_links.txt
+src/objectmodel_v1.egg-info/entry_points.txt
+src/objectmodel_v1.egg-info/requires.txt
+src/objectmodel_v1.egg-info/top_level.txt
+tests/test_boxes.py
+tests/test_data.py
+tests/test_model.py

src/objectmodel_v1.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/objectmodel_v1.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+objectmodel-eval = objectmodel_v1.evaluate:main
+objectmodel-export = objectmodel_v1.export:main
+objectmodel-profile = objectmodel_v1.profile:main
+objectmodel-train = objectmodel_v1.train:main

src/objectmodel_v1.egg-info/requires.txt

@@ -0,0 +1,16 @@
+numpy>=1.26
+Pillow>=10.0
+PyYAML>=6.0
+scipy>=1.11
+torch>=2.4
+
+[coco]
+pycocotools>=2.0.7
+
+[dev]
+pytest>=8.0
+ruff>=0.6
+
+[export]
+onnx>=1.16
+onnxscript>=0.1

src/objectmodel_v1.egg-info/top_level.txt

@@ -0,0 +1 @@
+objectmodel_v1

src/objectmodel_v1/__init__.py

@@ -0,0 +1,6 @@
+"""ObjectModel-v1 compact object detection research package."""
+
+from .model import ObjectModelV1, ObjectModelV1Spec, build_model
+
+__all__ = ["ObjectModelV1", "ObjectModelV1Spec", "build_model"]
+__version__ = "0.1.0"

src/objectmodel_v1/boxes.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import torch
+from torch import Tensor
+
+
+def box_cxcywh_to_xyxy(boxes: Tensor) -> Tensor:
+    cx, cy, width, height = boxes.unbind(-1)
+    return torch.stack(
+        (cx - 0.5 * width, cy - 0.5 * height, cx + 0.5 * width, cy + 0.5 * height),
+        dim=-1,
+    )
+
+
+def box_xyxy_to_cxcywh(boxes: Tensor) -> Tensor:
+    x0, y0, x1, y1 = boxes.unbind(-1)
+    return torch.stack(
+        ((x0 + x1) * 0.5, (y0 + y1) * 0.5, x1 - x0, y1 - y0), dim=-1
+    )
+
+
+def box_area(boxes: Tensor) -> Tensor:
+    return (boxes[..., 2] - boxes[..., 0]).clamp(min=0) * (
+        boxes[..., 3] - boxes[..., 1]
+    ).clamp(min=0)
+
+
+def box_iou(boxes1: Tensor, boxes2: Tensor) -> tuple[Tensor, Tensor]:
+    area1 = box_area(boxes1)
+    area2 = box_area(boxes2)
+    top_left = torch.maximum(boxes1[:, None, :2], boxes2[:, :2])
+    bottom_right = torch.minimum(boxes1[:, None, 2:], boxes2[:, 2:])
+    intersection = (bottom_right - top_left).clamp(min=0).prod(dim=-1)
+    union = area1[:, None] + area2 - intersection
+    return intersection / union.clamp(min=1e-7), union
+
+
+def generalized_box_iou(boxes1: Tensor, boxes2: Tensor) -> Tensor:
+    """Pairwise generalized IoU for boxes in x0, y0, x1, y1 format."""
+    iou, union = box_iou(boxes1, boxes2)
+    top_left = torch.minimum(boxes1[:, None, :2], boxes2[:, :2])
+    bottom_right = torch.maximum(boxes1[:, None, 2:], boxes2[:, 2:])
+    enclosing = (bottom_right - top_left).clamp(min=0).prod(dim=-1)
+    return iou - (enclosing - union) / enclosing.clamp(min=1e-7)
+
+
+def generalized_box_iou_batched(boxes1: Tensor, boxes2: Tensor) -> Tensor:
+    """Batched pairwise generalized IoU, boxes in x0, y0, x1, y1 format.
+
+    boxes1: [B, N, 4], boxes2: [B, M, 4] -> [B, N, M]
+    """
+    area1 = box_area(boxes1)
+    area2 = box_area(boxes2)
+    top_left = torch.maximum(boxes1[:, :, None, :2], boxes2[:, None, :, :2])
+    bottom_right = torch.minimum(boxes1[:, :, None, 2:], boxes2[:, None, :, 2:])
+    intersection = (bottom_right - top_left).clamp(min=0).prod(dim=-1)
+    union = area1[:, :, None] + area2[:, None, :] - intersection
+    iou = intersection / union.clamp(min=1e-7)
+    enc_top_left = torch.minimum(boxes1[:, :, None, :2], boxes2[:, None, :, :2])
+    enc_bottom_right = torch.maximum(boxes1[:, :, None, 2:], boxes2[:, None, :, 2:])
+    enclosing = (enc_bottom_right - enc_top_left).clamp(min=0).prod(dim=-1)
+    return iou - (enclosing - union) / enclosing.clamp(min=1e-7)
+
+
+def inverse_sigmoid(value: Tensor, eps: float = 1e-5) -> Tensor:
+    value = value.clamp(min=0.0, max=1.0)
+    return torch.log(value.clamp(min=eps) / (1.0 - value).clamp(min=eps))

src/objectmodel_v1/config.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_config(path: str | Path) -> dict[str, Any]:
+    with Path(path).open("r", encoding="utf-8") as handle:
+        config = yaml.safe_load(handle)
+    if not isinstance(config, dict):
+        raise ValueError(f"Configuration must be a mapping: {path}")
+    return config
+
+
+def apply_overrides(config: dict[str, Any], overrides: list[str]) -> dict[str, Any]:
+    result = deepcopy(config)
+    for item in overrides:
+        if "=" not in item:
+            raise ValueError(f"Override must have key=value form: {item}")
+        dotted_key, raw_value = item.split("=", 1)
+        keys = dotted_key.split(".")
+        node = result
+        for key in keys[:-1]:
+            if key not in node or not isinstance(node[key], dict):
+                raise KeyError(f"Unknown configuration path: {dotted_key}")
+            node = node[key]
+        if keys[-1] not in node:
+            raise KeyError(f"Unknown configuration key: {dotted_key}")
+        node[keys[-1]] = yaml.safe_load(raw_value)
+    return result
+
+
+def save_config(config: dict[str, Any], path: str | Path) -> None:
+    with Path(path).open("w", encoding="utf-8") as handle:
+        yaml.safe_dump(config, handle, sort_keys=False)

src/objectmodel_v1/data.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+import random
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from PIL import Image, ImageEnhance
+import torch
+from torch import Tensor
+from torch.utils.data import Dataset
+
+from .boxes import box_xyxy_to_cxcywh
+
+
+class CocoDetectionDataset(Dataset):
+    """Minimal COCO detection loader with deterministic category remapping."""
+
+    def __init__(
+        self,
+        image_dir: str | Path,
+        annotation_file: str | Path,
+        input_size: int,
+        training: bool,
+        hflip_prob: float = 0.5,
+        scale_range: tuple[float, float] = (0.65, 1.0),
+        mean: tuple[float, float, float] = (0.485, 0.456, 0.406),
+        std: tuple[float, float, float] = (0.229, 0.224, 0.225),
+    ) -> None:
+        self.image_dir = Path(image_dir)
+        self.annotation_file = Path(annotation_file)
+        self.input_size = input_size
+        self.training = training
+        self.hflip_prob = hflip_prob
+        self.scale_range = scale_range
+        self.mean = torch.tensor(mean, dtype=torch.float32)[:, None, None]
+        self.std = torch.tensor(std, dtype=torch.float32)[:, None, None]
+
+        with self.annotation_file.open("r", encoding="utf-8") as handle:
+            data = json.load(handle)
+        self.images = sorted(data["images"], key=lambda item: item["id"])
+        annotations: dict[int, list[dict[str, Any]]] = defaultdict(list)
+        for annotation in data["annotations"]:
+            if annotation.get("iscrowd", 0) == 0 and annotation["bbox"][2] > 0 and annotation["bbox"][3] > 0:
+                annotations[annotation["image_id"]].append(annotation)
+        self.annotations = annotations
+        category_ids = sorted(category["id"] for category in data["categories"])
+        self.category_to_label = {category_id: label for label, category_id in enumerate(category_ids)}
+        self.label_to_category = {label: category_id for category_id, label in self.category_to_label.items()}
+        self.categories = sorted(data["categories"], key=lambda item: self.category_to_label[item["id"]])
+
+    def __len__(self) -> int:
+        return len(self.images)
+
+    def _letterbox(
+        self, image: Image.Image, boxes: Tensor
+    ) -> tuple[Image.Image, Tensor, tuple[float, int, int]]:
+        width, height = image.size
+        scale_jitter = random.uniform(*self.scale_range) if self.training else 1.0
+        ratio = min(self.input_size / width, self.input_size / height) * scale_jitter
+        resized_width = max(1, round(width * ratio))
+        resized_height = max(1, round(height * ratio))
+        image = image.resize((resized_width, resized_height), Image.Resampling.BILINEAR)
+        max_x = self.input_size - resized_width
+        max_y = self.input_size - resized_height
+        if self.training:
+            offset_x = random.randint(0, max_x) if max_x else 0
+            offset_y = random.randint(0, max_y) if max_y else 0
+        else:
+            offset_x, offset_y = max_x // 2, max_y // 2
+        canvas = Image.new("RGB", (self.input_size, self.input_size), (114, 114, 114))
+        canvas.paste(image, (offset_x, offset_y))
+        if boxes.numel():
+            boxes = boxes * ratio
+            boxes[:, [0, 2]] += offset_x
+            boxes[:, [1, 3]] += offset_y
+        return canvas, boxes, (ratio, offset_x, offset_y)
+
+    def __getitem__(self, index: int) -> tuple[Tensor, dict[str, Tensor]]:
+        image_info = self.images[index]
+        image = Image.open(self.image_dir / image_info["file_name"]).convert("RGB")
+        original_width, original_height = image.size
+        records = self.annotations.get(image_info["id"], [])
+        boxes = []
+        labels = []
+        for record in records:
+            x, y, width, height = record["bbox"]
+            boxes.append((x, y, x + width, y + height))
+            labels.append(self.category_to_label[record["category_id"]])
+        box_tensor = torch.tensor(boxes, dtype=torch.float32).reshape(-1, 4)
+        label_tensor = torch.tensor(labels, dtype=torch.int64)
+
+        if self.training and random.random() < self.hflip_prob:
+            image = image.transpose(Image.Transpose.FLIP_LEFT_RIGHT)
+            if box_tensor.numel():
+                old_x0 = box_tensor[:, 0].clone()
+                box_tensor[:, 0] = original_width - box_tensor[:, 2]
+                box_tensor[:, 2] = original_width - old_x0
+        if self.training:
+            image = ImageEnhance.Color(image).enhance(random.uniform(0.8, 1.2))
+            image = ImageEnhance.Contrast(image).enhance(random.uniform(0.8, 1.2))
+        image, box_tensor, (ratio, offset_x, offset_y) = self._letterbox(image, box_tensor)
+        if box_tensor.numel():
+            box_tensor = box_xyxy_to_cxcywh(box_tensor) / self.input_size
+            valid = (box_tensor[:, 2] > 1e-4) & (box_tensor[:, 3] > 1e-4)
+            box_tensor = box_tensor[valid].clamp(0.0, 1.0)
+            label_tensor = label_tensor[valid]
+
+        image_array = np.asarray(image, dtype=np.float32).copy() / 255.0
+        image_tensor = torch.from_numpy(image_array).permute(2, 0, 1)
+        image_tensor = (image_tensor - self.mean) / self.std
+        target = {
+            "boxes": box_tensor,
+            "labels": label_tensor,
+            "image_id": torch.tensor(image_info["id"], dtype=torch.int64),
+            "original_size": torch.tensor([original_height, original_width], dtype=torch.int64),
+            "transform": torch.tensor([ratio, offset_x, offset_y], dtype=torch.float32),
+        }
+        return image_tensor, target
+
+
+def detection_collate(batch):
+    images, targets = zip(*batch, strict=True)
+    return torch.stack(images), list(targets)
+
+
+def build_dataset(config: dict, root: str | Path, split: str) -> CocoDetectionDataset:
+    data = config["data"]
+    root = Path(root)
+    training = split == "train"
+    return CocoDetectionDataset(
+        root / data[f"{split}_image_dir"],
+        root / data[f"{split}_annotations"],
+        input_size=int(config["model"]["input_size"]),
+        training=training,
+        hflip_prob=float(data.get("hflip_prob", 0.5)),
+        scale_range=tuple(data.get("scale_range", (0.65, 1.0))) if training else (1.0, 1.0),
+        mean=tuple(data.get("mean", (0.485, 0.456, 0.406))),
+        std=tuple(data.get("std", (0.229, 0.224, 0.225))),
+    )

src/objectmodel_v1/evaluate.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import torch
+from torch.utils.data import DataLoader
+
+from .boxes import box_cxcywh_to_xyxy
+from .config import apply_overrides, load_config
+from .data import build_dataset, detection_collate
+from .model import build_model
+
+
+@torch.inference_mode()
+def evaluate_coco(
+    model,
+    data_loader,
+    device: torch.device,
+    output_file: str | Path,
+    confidence: float = 0.001,
+    max_detections: int = 300,
+) -> dict[str, float]:
+    try:
+        from pycocotools.coco import COCO
+        from pycocotools.cocoeval import COCOeval
+    except ImportError as error:
+        raise RuntimeError("COCO evaluation requires: pip install -e '.[coco]'") from error
+
+    model.eval()
+    input_size = model.spec.input_size
+    predictions = []
+    label_to_category = data_loader.dataset.label_to_category
+    for images, targets in data_loader:
+        images = images.to(device, non_blocking=True)
+        outputs = model(images)
+        probabilities = outputs["pred_logits"].sigmoid()
+        normalized_boxes = box_cxcywh_to_xyxy(outputs["pred_boxes"]).clamp(0.0, 1.0)
+        for batch_index, target in enumerate(targets):
+            scores, labels = probabilities[batch_index].max(dim=-1)
+            count = min(max_detections, scores.numel())
+            scores, indices = scores.topk(count)
+            keep = scores >= confidence
+            scores, indices = scores[keep], indices[keep]
+            labels = labels[indices]
+            boxes = normalized_boxes[batch_index, indices] * input_size
+            ratio, offset_x, offset_y = target["transform"].tolist()
+            original_height, original_width = target["original_size"].tolist()
+            boxes[:, [0, 2]] = (boxes[:, [0, 2]] - offset_x) / ratio
+            boxes[:, [1, 3]] = (boxes[:, [1, 3]] - offset_y) / ratio
+            boxes[:, [0, 2]].clamp_(0, original_width)
+            boxes[:, [1, 3]].clamp_(0, original_height)
+            boxes[:, 2:] -= boxes[:, :2]
+            for box, score, label in zip(boxes.cpu(), scores.cpu(), labels.cpu(), strict=True):
+                predictions.append(
+                    {
+                        "image_id": int(target["image_id"]),
+                        "category_id": int(label_to_category[int(label)]),
+                        "bbox": [round(float(value), 3) for value in box],
+                        "score": float(score),
+                    }
+                )
+
+    output_file = Path(output_file)
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    with output_file.open("w", encoding="utf-8") as handle:
+        json.dump(predictions, handle)
+    ground_truth = COCO(str(data_loader.dataset.annotation_file))
+    if not predictions:
+        return {"AP": 0.0, "AP50": 0.0, "AP75": 0.0, "APS": 0.0, "APM": 0.0, "APL": 0.0}
+    detections = ground_truth.loadRes(str(output_file))
+    evaluator = COCOeval(ground_truth, detections, "bbox")
+    evaluator.params.imgIds = [int(item["id"]) for item in data_loader.dataset.images]
+    evaluator.evaluate()
+    evaluator.accumulate()
+    evaluator.summarize()
+    names = ("AP", "AP50", "AP75", "APS", "APM", "APL")
+    return {name: float(evaluator.stats[index]) for index, name in enumerate(names)}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Evaluate ObjectModel-v1 on COCO")
+    parser.add_argument("--config", default="configs/objectmodel_v1.yaml")
+    parser.add_argument("--checkpoint", required=True)
+    parser.add_argument("--data-root", required=True)
+    parser.add_argument("--output", default="outputs/predictions.json")
+    parser.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    parser.add_argument("--batch-size", type=int, default=8)
+    parser.add_argument("--workers", type=int, default=4)
+    parser.add_argument("--set", action="append", default=[])
+    args = parser.parse_args()
+    config = apply_overrides(load_config(args.config), args.set)
+    model = build_model(config)
+    checkpoint = torch.load(args.checkpoint, map_location="cpu", weights_only=False)
+    model.load_state_dict(checkpoint.get("ema", checkpoint.get("model", checkpoint)))
+    device = torch.device(args.device)
+    model.to(device)
+    dataset = build_dataset(config, args.data_root, "val")
+    loader = DataLoader(
+        dataset,
+        batch_size=args.batch_size,
+        shuffle=False,
+        num_workers=args.workers,
+        pin_memory=device.type == "cuda",
+        collate_fn=detection_collate,
+    )
+    print(json.dumps(evaluate_coco(model, loader, device, args.output), indent=2))
+
+
+if __name__ == "__main__":
+    main()

src/objectmodel_v1/export.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import torch
+from torch import nn
+
+from .config import apply_overrides, load_config
+from .model import build_model
+
+
+class ExportModel(nn.Module):
+    def __init__(self, model: nn.Module) -> None:
+        super().__init__()
+        self.model = model
+
+    def forward(self, images: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        outputs = self.model(images)
+        return outputs["pred_logits"], outputs["pred_boxes"]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Export ObjectModel-v1 to ONNX")
+    parser.add_argument("--config", default="configs/objectmodel_v1.yaml")
+    parser.add_argument("--checkpoint", required=True)
+    parser.add_argument("--output", default="objectmodel-v1.onnx")
+    parser.add_argument("--opset", type=int, default=20)
+    parser.add_argument("--set", action="append", default=[])
+    args = parser.parse_args()
+    config = apply_overrides(load_config(args.config), args.set)
+    model = build_model(config)
+    checkpoint = torch.load(args.checkpoint, map_location="cpu", weights_only=False)
+    model.load_state_dict(checkpoint.get("ema", checkpoint.get("model", checkpoint)))
+    model.eval()
+    wrapper = ExportModel(model)
+    size = model.spec.input_size
+    sample = torch.randn(1, 3, size, size)
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    torch.onnx.export(
+        wrapper,
+        (sample,),
+        output,
+        input_names=["images"],
+        output_names=["logits", "boxes"],
+        dynamic_axes={
+            "images": {0: "batch"},
+            "logits": {0: "batch"},
+            "boxes": {0: "batch"},
+        },
+        opset_version=args.opset,
+        dynamo=False,
+    )
+    print(f"Exported {output} ({output.stat().st_size / 1024**2:.2f} MiB)")
+
+
+if __name__ == "__main__":
+    main()

src/objectmodel_v1/losses.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import torch
+import torch.nn.functional as F
+from torch import Tensor, nn
+
+from .boxes import box_cxcywh_to_xyxy, generalized_box_iou
+from .matching import hungarian_match, hungarian_match_layers
+
+
+def sigmoid_focal_loss(
+    logits: Tensor, targets: Tensor, alpha: float = 0.25, gamma: float = 2.0
+) -> Tensor:
+    probabilities = logits.sigmoid()
+    ce = F.binary_cross_entropy_with_logits(logits, targets, reduction="none")
+    p_t = probabilities * targets + (1.0 - probabilities) * (1.0 - targets)
+    loss = ce * (1.0 - p_t).pow(gamma)
+    if alpha >= 0:
+        alpha_t = alpha * targets + (1.0 - alpha) * (1.0 - targets)
+        loss = alpha_t * loss
+    return loss
+
+
+class ObjectModelCriterion(nn.Module):
+    def __init__(self, config: dict) -> None:
+        super().__init__()
+        loss_config = config.get("loss", config)
+        self.cost_class = float(loss_config.get("cost_class", 2.0))
+        self.cost_bbox = float(loss_config.get("cost_bbox", 5.0))
+        self.cost_giou = float(loss_config.get("cost_giou", 2.0))
+        self.weight_class = float(loss_config.get("weight_class", 2.0))
+        self.weight_bbox = float(loss_config.get("weight_bbox", 5.0))
+        self.weight_giou = float(loss_config.get("weight_giou", 2.0))
+        self.weight_dense = float(loss_config.get("weight_dense", 1.0))
+        self.aux_weight = float(loss_config.get("aux_weight", 1.0))
+        self.dense_topk = int(loss_config.get("dense_topk", 5))
+        self.alpha = float(loss_config.get("focal_alpha", 0.25))
+        self.gamma = float(loss_config.get("focal_gamma", 2.0))
+
+    def _dense_targets(
+        self,
+        logits: Tensor,
+        targets: Sequence[dict[str, Tensor]],
+        level_index: int,
+    ) -> tuple[Tensor, Tensor, Tensor]:
+        batch, _, height, width = logits.shape
+        device = logits.device
+        target_logits = torch.zeros_like(logits)
+        target_boxes_hwc = torch.zeros(batch, height, width, 4, dtype=torch.float32, device=device)
+        positive = torch.zeros(batch, height, width, dtype=torch.float32, device=device)
+        offsets = torch.tensor(
+            [
+                (-1, -1),
+                (0, -1),
+                (1, -1),
+                (-1, 0),
+                (0, 0),
+                (1, 0),
+                (-1, 1),
+                (0, 1),
+                (1, 1),
+            ],
+            dtype=torch.int64,
+            device=device,
+        )
+        distances = offsets.square().sum(dim=1)
+        candidate_count = min(self.dense_topk, len(offsets))
+
+        nonempty = [(i, t) for i, t in enumerate(targets) if t["labels"].numel() > 0]
+        if not nonempty:
+            return target_logits, target_boxes_hwc.permute(0, 3, 1, 2), positive
+        all_boxes = torch.cat([t["boxes"] for _, t in nonempty])
+        all_labels = torch.cat([t["labels"] for _, t in nonempty])
+        all_batch = torch.cat(
+            [
+                torch.full((t["labels"].numel(),), i, dtype=torch.int64, device=device)
+                for i, t in nonempty
+            ]
+        )
+
+        areas = all_boxes[:, 2] * all_boxes[:, 3]
+        target_levels = torch.where(areas < 0.02, 0, torch.where(areas < 0.15, 1, 2))
+        level_mask = target_levels == level_index
+        if not bool(level_mask.any()):
+            return target_logits, target_boxes_hwc.permute(0, 3, 1, 2), positive
+
+        boxes = all_boxes[level_mask]
+        labels = all_labels[level_mask]
+        sel_batch = all_batch[level_mask]
+
+        grid = (boxes[:, :2] * boxes.new_tensor([width, height])).long()
+        grid[:, 0].clamp_(0, width - 1)
+        grid[:, 1].clamp_(0, height - 1)
+        x = (grid[:, None, 0] + offsets[None, :, 0]).clamp(0, width - 1)
+        y = (grid[:, None, 1] + offsets[None, :, 1]).clamp(0, height - 1)
+
+        sort_key = distances[None] * ((width + 1) * (height + 1))
+        sort_key = sort_key + x * (height + 1) + y
+        order = sort_key.argsort(dim=1, stable=True)[:, :candidate_count]
+        x = x.gather(1, order)
+        y = y.gather(1, order)
+
+        expanded_labels = labels[:, None].expand_as(x)
+        expanded_batch = sel_batch[:, None].expand_as(x)
+        target_logits[expanded_batch, expanded_labels, y, x] = 1.0
+
+        flat_cells = (expanded_batch * (height * width) + y * width + x).reshape(-1)
+        owners = torch.full((batch * height * width,), -1, dtype=torch.int64, device=device)
+        source_owners = torch.arange(boxes.shape[0], device=device)[:, None].expand_as(x).reshape(-1)
+        owners.scatter_reduce_(0, flat_cells, source_owners, reduce="amax", include_self=True)
+        occupied = owners >= 0
+        positive.view(-1)[occupied] = 1.0
+        target_boxes_hwc.view(-1, 4)[occupied] = boxes[owners[occupied]]
+        return target_logits, target_boxes_hwc.permute(0, 3, 1, 2), positive
+
+    def _set_loss(
+        self, outputs: dict[str, Tensor], targets: Sequence[dict[str, Tensor]], matches=None
+    ) -> dict[str, Tensor]:
+        logits = outputs["pred_logits"]
+        boxes = outputs["pred_boxes"]
+        if matches is None:
+            matches = hungarian_match(
+                outputs,
+                targets,
+                self.cost_class,
+                self.cost_bbox,
+                self.cost_giou,
+            )
+        device = logits.device
+        target_classes = torch.zeros_like(logits)
+        normalizer = max(sum(len(target["labels"]) for target in targets), 1)
+
+        nonempty = [
+            (batch_index, prediction_indices, target_indices)
+            for batch_index, (prediction_indices, target_indices) in enumerate(matches)
+            if prediction_indices.numel() > 0
+        ]
+        if nonempty:
+            batch_ids = torch.cat(
+                [torch.full_like(pred_idx, batch_index) for batch_index, pred_idx, _ in nonempty]
+            )
+            pred_idx_t = torch.cat([pred_idx for _, pred_idx, _ in nonempty])
+            tgt_idx_t = torch.cat([tgt_idx for _, _, tgt_idx in nonempty])
+
+            counts = torch.tensor([len(target["labels"]) for target in targets], device=device)
+            offsets = torch.cat([counts.new_zeros(1), counts.cumsum(0)[:-1]])
+            global_target_idx = tgt_idx_t + offsets[batch_ids]
+
+            all_target_boxes = torch.cat([target["boxes"] for target in targets])
+            all_target_labels = torch.cat([target["labels"] for target in targets])
+
+            labels = all_target_labels[global_target_idx]
+            target_classes[batch_ids, pred_idx_t, labels] = 1.0
+            predicted = boxes[batch_ids, pred_idx_t]
+            expected = all_target_boxes[global_target_idx]
+        else:
+            predicted = None
+            expected = None
+
+        class_loss = sigmoid_focal_loss(logits, target_classes, self.alpha, self.gamma).sum()
+        class_loss = class_loss / normalizer
+        if predicted is not None:
+            bbox_loss = F.l1_loss(predicted, expected, reduction="sum") / normalizer
+            giou = generalized_box_iou(box_cxcywh_to_xyxy(predicted), box_cxcywh_to_xyxy(expected))
+            giou_loss = (1.0 - giou.diag()).sum() / normalizer
+        else:
+            bbox_loss = boxes.sum() * 0.0
+            giou_loss = boxes.sum() * 0.0
+        return {
+            "loss_class": class_loss * self.weight_class,
+            "loss_bbox": bbox_loss * self.weight_bbox,
+            "loss_giou": giou_loss * self.weight_giou,
+        }
+
+    def _dense_loss(
+        self, outputs: list[dict[str, Tensor]], targets: Sequence[dict[str, Tensor]]
+    ) -> Tensor:
+        total = outputs[0]["logits"].sum() * 0.0
+        normalizer = max(sum(len(target["labels"]) for target in targets), 1)
+        for level_index, level_output in enumerate(outputs):
+            logits = level_output["logits"]
+            boxes = level_output["distances"].sigmoid()
+            target_logits, target_boxes, positive = self._dense_targets(
+                logits, targets, level_index
+            )
+            cls_loss = sigmoid_focal_loss(logits, target_logits, self.alpha, self.gamma)
+            cls_loss = cls_loss.sum() / normalizer
+            positive_mask = positive[:, None].expand_as(boxes)
+            box_loss = (F.l1_loss(boxes, target_boxes, reduction="none") * positive_mask).sum()
+            total = total + cls_loss + box_loss / normalizer
+        return total / len(outputs)
+
+    def forward(
+        self, outputs: dict[str, Tensor], targets: Sequence[dict[str, Tensor]]
+    ) -> dict[str, Tensor]:
+        layer_outputs = [outputs, *outputs.get("aux_outputs", [])]
+        layer_matches = hungarian_match_layers(
+            layer_outputs,
+            targets,
+            self.cost_class,
+            self.cost_bbox,
+            self.cost_giou,
+        )
+        primary = self._set_loss(outputs, targets, layer_matches[0])
+        total = sum(primary.values())
+        for auxiliary, matches in zip(
+            outputs.get("aux_outputs", []), layer_matches[1:], strict=True
+        ):
+            auxiliary_losses = self._set_loss(auxiliary, targets, matches)
+            total = total + self.aux_weight * sum(auxiliary_losses.values()) / max(
+                len(outputs["aux_outputs"]), 1
+            )
+        if "dense_outputs" in outputs:
+            dense = self._dense_loss(outputs["dense_outputs"], targets)
+            primary["loss_dense"] = dense * self.weight_dense
+            total = total + primary["loss_dense"]
+        primary["loss_total"] = total
+        return primary

src/objectmodel_v1/matching.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+import torch
+from scipy.optimize import linear_sum_assignment
+from torch import Tensor
+
+from .boxes import box_cxcywh_to_xyxy, generalized_box_iou_batched
+
+
+def hungarian_match(
+    outputs: dict[str, Tensor],
+    targets: Sequence[dict[str, Tensor]],
+    class_cost: float = 2.0,
+    bbox_cost: float = 5.0,
+    giou_cost: float = 2.0,
+) -> list[tuple[Tensor, Tensor]]:
+    """Match predictions to targets with a detached CPU Hungarian solve."""
+    return hungarian_match_layers([outputs], targets, class_cost, bbox_cost, giou_cost)[0]
+
+
+def hungarian_match_layers(
+    outputs: Sequence[dict[str, Tensor]],
+    targets: Sequence[dict[str, Tensor]],
+    class_cost: float = 2.0,
+    bbox_cost: float = 5.0,
+    giou_cost: float = 2.0,
+) -> list[list[tuple[Tensor, Tensor]]]:
+    """Match all decoder layers with one GPU-to-CPU synchronization."""
+    if not outputs:
+        return []
+
+    device = outputs[0]["pred_boxes"].device
+    target_sizes = [len(target["labels"]) for target in targets]
+    max_targets = max(target_sizes, default=0)
+    if max_targets == 0:
+        empty = torch.empty(0, dtype=torch.int64, device=device)
+        return [[(empty, empty) for _ in targets] for _ in outputs]
+
+    batch_size = len(targets)
+    padded_boxes = torch.zeros(batch_size, max_targets, 4, dtype=torch.float32, device=device)
+    padded_labels = torch.zeros(batch_size, max_targets, dtype=torch.int64, device=device)
+    for batch_index, target in enumerate(targets):
+        count = target_sizes[batch_index]
+        if count > 0:
+            padded_boxes[batch_index, :count] = target["boxes"]
+            padded_labels[batch_index, :count] = target["labels"]
+
+    padded_costs = []
+    for layer_output in outputs:
+        probabilities = layer_output["pred_logits"].sigmoid().detach()
+        boxes = layer_output["pred_boxes"].detach()
+        num_queries = boxes.shape[1]
+        gather_index = padded_labels[:, None, :].expand(-1, num_queries, -1)
+        class_term = -probabilities.gather(2, gather_index)
+        bbox_term = torch.cdist(boxes, padded_boxes, p=1)
+        giou_term = -generalized_box_iou_batched(
+            box_cxcywh_to_xyxy(boxes), box_cxcywh_to_xyxy(padded_boxes)
+        )
+        cost = (class_cost * class_term + bbox_cost * bbox_term + giou_cost * giou_term).float()
+        for batch_index in range(batch_size):
+            padded_costs.append(cost[batch_index])
+
+    costs = torch.stack(padded_costs).cpu().numpy()
+
+    cpu_matches: list[tuple[np.ndarray, np.ndarray]] = []
+    for cost, target_size in zip(costs, target_sizes * len(outputs), strict=True):
+        if target_size == 0:
+            empty = np.empty(0, dtype=np.int64)
+            cpu_matches.append((empty, empty))
+        else:
+            cpu_matches.append(linear_sum_assignment(cost[:, :target_size]))
+
+    lengths = [len(rows) for rows, _ in cpu_matches]
+    all_rows = torch.as_tensor(
+        np.concatenate([rows for rows, _ in cpu_matches]),
+        dtype=torch.int64,
+        device=device,
+    )
+    all_cols = torch.as_tensor(
+        np.concatenate([cols for _, cols in cpu_matches]),
+        dtype=torch.int64,
+        device=device,
+    )
+    flat_matches = []
+    offset = 0
+    for length in lengths:
+        flat_matches.append(
+            (all_rows[offset : offset + length], all_cols[offset : offset + length])
+        )
+        offset += length
+
+    batch_size = len(targets)
+    return [
+        flat_matches[start : start + batch_size]
+        for start in range(0, len(flat_matches), batch_size)
+    ]

src/objectmodel_v1/model.py

@@ -0,0 +1,413 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+import torch
+from torch import Tensor, nn
+import torch.nn.functional as F
+
+from .boxes import inverse_sigmoid
+
+
+class ConvNormAct(nn.Sequential):
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        kernel_size: int = 1,
+        stride: int = 1,
+        groups: int = 1,
+        activation: bool = True,
+    ) -> None:
+        padding = kernel_size // 2
+        layers: list[nn.Module] = [
+            nn.Conv2d(
+                in_channels,
+                out_channels,
+                kernel_size,
+                stride,
+                padding,
+                groups=groups,
+                bias=False,
+            ),
+            nn.BatchNorm2d(out_channels),
+        ]
+        if activation:
+            layers.append(nn.SiLU(inplace=True))
+        super().__init__(*layers)
+
+
+class GatedConvBlock(nn.Module):
+    """Inverted residual block with a cheap learned residual gate."""
+
+    def __init__(self, channels: int, expansion: float = 2.0) -> None:
+        super().__init__()
+        hidden = int(channels * expansion)
+        self.expand = ConvNormAct(channels, hidden)
+        self.depthwise = ConvNormAct(hidden, hidden, 3, groups=hidden)
+        self.project = ConvNormAct(hidden, channels, activation=False)
+        self.gate = nn.Parameter(torch.zeros(1))
+
+    def forward(self, inputs: Tensor) -> Tensor:
+        return inputs + torch.tanh(self.gate) * self.project(self.depthwise(self.expand(inputs)))
+
+
+class BackboneStage(nn.Sequential):
+    def __init__(self, in_channels: int, out_channels: int, depth: int, stride: int) -> None:
+        super().__init__(
+            ConvNormAct(in_channels, out_channels, 3, stride=stride),
+            *(GatedConvBlock(out_channels) for _ in range(depth)),
+        )
+
+
+class CompactBackbone(nn.Module):
+    def __init__(
+        self, stem_channels: int, channels: list[int], depths: list[int]
+    ) -> None:
+        super().__init__()
+        if len(channels) != 4 or len(depths) != 4:
+            raise ValueError("Backbone requires four channel and depth values")
+        self.stem = nn.Sequential(
+            ConvNormAct(3, stem_channels, 3, stride=2),
+            ConvNormAct(stem_channels, stem_channels, 3, stride=2),
+        )
+        stages: list[nn.Module] = []
+        in_channels = stem_channels
+        for index, (out_channels, depth) in enumerate(zip(channels, depths, strict=True)):
+            stages.append(
+                BackboneStage(in_channels, out_channels, depth, stride=1 if index == 0 else 2)
+            )
+            in_channels = out_channels
+        self.stages = nn.ModuleList(stages)
+        self.out_channels = channels[1:]
+
+    def forward(self, images: Tensor) -> list[Tensor]:
+        features = self.stem(images)
+        outputs = []
+        for index, stage in enumerate(self.stages):
+            features = stage(features)
+            if index > 0:
+                outputs.append(features)
+        return outputs
+
+
+class PyramidFusion(nn.Module):
+    def __init__(self, in_channels: list[int], hidden_dim: int, depth: int) -> None:
+        super().__init__()
+        self.lateral = nn.ModuleList(ConvNormAct(c, hidden_dim) for c in in_channels)
+        self.refine = nn.ModuleList(
+            nn.Sequential(*(GatedConvBlock(hidden_dim, expansion=1.5) for _ in range(depth)))
+            for _ in in_channels
+        )
+
+    def forward(self, inputs: list[Tensor]) -> list[Tensor]:
+        projected = [layer(x) for layer, x in zip(self.lateral, inputs, strict=True)]
+        outputs = list(projected)
+        for index in range(len(outputs) - 2, -1, -1):
+            outputs[index] = outputs[index] + F.interpolate(
+                outputs[index + 1], size=outputs[index].shape[-2:], mode="nearest"
+            )
+        return [block(x) for block, x in zip(self.refine, outputs, strict=True)]
+
+
+def sine_position_encoding(
+    height: int, width: int, dim: int, device: torch.device, dtype: torch.dtype
+) -> Tensor:
+    if dim % 4 != 0:
+        raise ValueError("Position encoding dimension must be divisible by four")
+    y, x = torch.meshgrid(
+        torch.linspace(0, 1, height, device=device, dtype=dtype),
+        torch.linspace(0, 1, width, device=device, dtype=dtype),
+        indexing="ij",
+    )
+    frequencies = torch.arange(dim // 4, device=device, dtype=dtype)
+    frequencies = 2.0 * torch.pi * (10000.0 ** (-frequencies / max(dim // 4, 1)))
+    x = x.flatten()[:, None] * frequencies[None]
+    y = y.flatten()[:, None] * frequencies[None]
+    return torch.cat((x.sin(), x.cos(), y.sin(), y.cos()), dim=-1)
+
+
+class FeedForward(nn.Sequential):
+    def __init__(self, dim: int, expansion: int = 4, dropout: float = 0.0) -> None:
+        super().__init__(
+            nn.Linear(dim, dim * expansion),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(dim * expansion, dim),
+            nn.Dropout(dropout),
+        )
+
+
+class LatentLayer(nn.Module):
+    def __init__(self, dim: int, num_heads: int, dropout: float) -> None:
+        super().__init__()
+        self.norm1 = nn.LayerNorm(dim)
+        self.attention = nn.MultiheadAttention(dim, num_heads, dropout, batch_first=True)
+        self.norm2 = nn.LayerNorm(dim)
+        self.ffn = FeedForward(dim, dropout=dropout)
+
+    def forward(self, inputs: Tensor) -> Tensor:
+        normalized = self.norm1(inputs)
+        inputs = inputs + self.attention(normalized, normalized, normalized, need_weights=False)[0]
+        return inputs + self.ffn(self.norm2(inputs))
+
+
+class LatentMemory(nn.Module):
+    """Compresses multi-scale maps into a fixed-size global reasoning memory."""
+
+    def __init__(
+        self,
+        dim: int,
+        latent_count: int,
+        pool_sizes: list[int],
+        layers: int,
+        num_heads: int,
+        dropout: float,
+    ) -> None:
+        super().__init__()
+        if len(pool_sizes) != 3:
+            raise ValueError("One latent pool size is required for each pyramid level")
+        self.pool_sizes = pool_sizes
+        self.latents = nn.Parameter(torch.empty(latent_count, dim))
+        self.level_embedding = nn.Parameter(torch.empty(len(pool_sizes), dim))
+        self.query_norm = nn.LayerNorm(dim)
+        self.token_norm = nn.LayerNorm(dim)
+        self.compress = nn.MultiheadAttention(dim, num_heads, dropout, batch_first=True)
+        self.layers = nn.ModuleList(LatentLayer(dim, num_heads, dropout) for _ in range(layers))
+        nn.init.normal_(self.latents, std=0.02)
+        nn.init.normal_(self.level_embedding, std=0.02)
+
+    def forward(self, features: list[Tensor]) -> Tensor:
+        tokens = []
+        for level, (feature, size) in enumerate(zip(features, self.pool_sizes, strict=True)):
+            pooled = F.adaptive_avg_pool2d(feature, (size, size)).flatten(2).transpose(1, 2)
+            position = sine_position_encoding(
+                size, size, feature.shape[1], feature.device, feature.dtype
+            )
+            tokens.append(pooled + position[None] + self.level_embedding[level][None, None])
+        token_memory = self.token_norm(torch.cat(tokens, dim=1))
+        latents = self.latents[None].expand(features[0].shape[0], -1, -1)
+        latents = latents + self.compress(
+            self.query_norm(latents), token_memory, token_memory, need_weights=False
+        )[0]
+        for layer in self.layers:
+            latents = layer(latents)
+        return latents
+
+
+class QueryLocalSampler(nn.Module):
+    """Samples high-resolution pyramid evidence around each evolving query box."""
+
+    def __init__(self, dim: int, num_levels: int, points: int) -> None:
+        super().__init__()
+        self.num_levels = num_levels
+        self.points = points
+        self.offsets = nn.Linear(dim, num_levels * points * 2)
+        self.weights = nn.Linear(dim, num_levels * points)
+        self.output = nn.Linear(dim, dim)
+        nn.init.zeros_(self.offsets.weight)
+        nn.init.zeros_(self.offsets.bias)
+        nn.init.zeros_(self.weights.weight)
+        nn.init.zeros_(self.weights.bias)
+
+    def forward(self, queries: Tensor, boxes: Tensor, features: list[Tensor]) -> Tensor:
+        batch, query_count, _ = queries.shape
+        offsets = self.offsets(queries).view(
+            batch, query_count, self.num_levels, self.points, 2
+        )
+        offsets = offsets.tanh() * boxes[..., None, None, 2:] * 0.5
+        centers = boxes[..., None, None, :2]
+        sample_points = (centers + offsets).clamp(0.0, 1.0)
+        weights = self.weights(queries).view(
+            batch, query_count, self.num_levels * self.points
+        )
+        weights = weights.softmax(dim=-1).view(
+            batch, query_count, self.num_levels, self.points
+        )
+
+        sampled_levels = []
+        for level, feature in enumerate(features):
+            grid = sample_points[:, :, level] * 2.0 - 1.0
+            sampled = F.grid_sample(
+                feature,
+                grid,
+                mode="bilinear",
+                padding_mode="zeros",
+                align_corners=False,
+            )
+            sampled = sampled.permute(0, 2, 3, 1)
+            sampled_levels.append(sampled)
+        sampled_features = torch.stack(sampled_levels, dim=2)
+        fused = (sampled_features * weights[..., None]).sum(dim=(2, 3))
+        return self.output(fused)
+
+
+class DecoderLayer(nn.Module):
+    def __init__(
+        self, dim: int, num_heads: int, num_levels: int, local_points: int, dropout: float
+    ) -> None:
+        super().__init__()
+        self.norm1 = nn.LayerNorm(dim)
+        self.self_attention = nn.MultiheadAttention(dim, num_heads, dropout, batch_first=True)
+        self.norm2 = nn.LayerNorm(dim)
+        self.global_attention = nn.MultiheadAttention(dim, num_heads, dropout, batch_first=True)
+        self.norm3 = nn.LayerNorm(dim)
+        self.local_sampler = QueryLocalSampler(dim, num_levels, local_points)
+        self.norm4 = nn.LayerNorm(dim)
+        self.ffn = FeedForward(dim, dropout=dropout)
+
+    def forward(
+        self, queries: Tensor, memory: Tensor, boxes: Tensor, features: list[Tensor]
+    ) -> Tensor:
+        normalized = self.norm1(queries)
+        queries = queries + self.self_attention(
+            normalized, normalized, normalized, need_weights=False
+        )[0]
+        queries = queries + self.global_attention(
+            self.norm2(queries), memory, memory, need_weights=False
+        )[0]
+        queries = queries + self.local_sampler(self.norm3(queries), boxes, features)
+        return queries + self.ffn(self.norm4(queries))
+
+
+class MLP(nn.Sequential):
+    def __init__(self, input_dim: int, hidden_dim: int, output_dim: int, layers: int) -> None:
+        modules: list[nn.Module] = []
+        for index in range(layers):
+            in_dim = input_dim if index == 0 else hidden_dim
+            out_dim = output_dim if index == layers - 1 else hidden_dim
+            modules.append(nn.Linear(in_dim, out_dim))
+            if index < layers - 1:
+                modules.append(nn.ReLU(inplace=True))
+        super().__init__(*modules)
+
+
+class DenseAuxiliaryHead(nn.Module):
+    def __init__(self, dim: int, num_classes: int) -> None:
+        super().__init__()
+        self.shared = nn.ModuleList(
+            nn.Sequential(ConvNormAct(dim, dim, 3, groups=dim), ConvNormAct(dim, dim))
+            for _ in range(3)
+        )
+        self.classification = nn.Conv2d(dim, num_classes, 1)
+        self.regression = nn.Conv2d(dim, 4, 1)
+
+    def forward(self, features: list[Tensor]) -> list[dict[str, Tensor]]:
+        outputs = []
+        for feature, tower in zip(features, self.shared, strict=True):
+            hidden = tower(feature)
+            outputs.append(
+                {
+                    "logits": self.classification(hidden),
+                    "distances": F.softplus(self.regression(hidden)),
+                }
+            )
+        return outputs
+
+
+@dataclass(frozen=True)
+class ObjectModelV1Spec:
+    num_classes: int = 80
+    input_size: int = 640
+    stem_channels: int = 48
+    backbone_channels: tuple[int, int, int, int] = (64, 128, 256, 384)
+    backbone_depths: tuple[int, int, int, int] = (2, 3, 6, 3)
+    hidden_dim: int = 256
+    fpn_depth: int = 2
+    latent_count: int = 64
+    latent_pool_sizes: tuple[int, int, int] = (12, 6, 3)
+    latent_layers: int = 2
+    decoder_layers: int = 6
+    num_queries: int = 300
+    num_heads: int = 8
+    local_points: int = 4
+    dropout: float = 0.0
+    dense_aux: bool = True
+
+
+class ObjectModelV1(nn.Module):
+    """NMS-free detector with compressed global memory and local geometric sampling."""
+
+    def __init__(self, spec: ObjectModelV1Spec) -> None:
+        super().__init__()
+        self.spec = spec
+        self.backbone = CompactBackbone(
+            spec.stem_channels, list(spec.backbone_channels), list(spec.backbone_depths)
+        )
+        self.neck = PyramidFusion(self.backbone.out_channels, spec.hidden_dim, spec.fpn_depth)
+        self.memory = LatentMemory(
+            spec.hidden_dim,
+            spec.latent_count,
+            list(spec.latent_pool_sizes),
+            spec.latent_layers,
+            spec.num_heads,
+            spec.dropout,
+        )
+        decoder_template = DecoderLayer(
+            spec.hidden_dim, spec.num_heads, 3, spec.local_points, spec.dropout
+        )
+        self.decoder = nn.ModuleList(deepcopy(decoder_template) for _ in range(spec.decoder_layers))
+        self.query_embedding = nn.Embedding(spec.num_queries, spec.hidden_dim)
+        self.reference_points = nn.Embedding(spec.num_queries, 4)
+        self.class_heads = nn.ModuleList(
+            nn.Linear(spec.hidden_dim, spec.num_classes) for _ in range(spec.decoder_layers)
+        )
+        self.box_heads = nn.ModuleList(
+            MLP(spec.hidden_dim, spec.hidden_dim, 4, 3) for _ in range(spec.decoder_layers)
+        )
+        self.dense_head = (
+            DenseAuxiliaryHead(spec.hidden_dim, spec.num_classes) if spec.dense_aux else None
+        )
+        self._reset_parameters()
+
+    def _reset_parameters(self) -> None:
+        prior_probability = 0.01
+        class_bias = -torch.log(torch.tensor((1.0 - prior_probability) / prior_probability))
+        for head in self.class_heads:
+            nn.init.constant_(head.bias, class_bias)
+        nn.init.zeros_(self.reference_points.weight)
+        with torch.no_grad():
+            self.reference_points.weight[:, 2:] = -2.0
+        for head in self.box_heads:
+            nn.init.zeros_(head[-1].weight)
+            nn.init.zeros_(head[-1].bias)
+        if self.dense_head is not None:
+            nn.init.constant_(self.dense_head.classification.bias, class_bias)
+            nn.init.zeros_(self.dense_head.regression.weight)
+            nn.init.constant_(self.dense_head.regression.bias, 1.0)
+
+    def forward(self, images: Tensor) -> dict[str, Any]:
+        features = self.neck(self.backbone(images))
+        memory = self.memory(features)
+        batch = images.shape[0]
+        queries = self.query_embedding.weight[None].expand(batch, -1, -1)
+        boxes = self.reference_points.weight.sigmoid()[None].expand(batch, -1, -1)
+        layer_outputs: list[dict[str, Tensor]] = []
+        for layer, class_head, box_head in zip(
+            self.decoder, self.class_heads, self.box_heads, strict=True
+        ):
+            queries = layer(queries, memory, boxes, features)
+            boxes = (inverse_sigmoid(boxes) + box_head(queries)).sigmoid()
+            layer_outputs.append({"pred_logits": class_head(queries), "pred_boxes": boxes})
+            boxes = boxes.detach() if self.training else boxes
+
+        output: dict[str, Any] = dict(layer_outputs[-1])
+        output["aux_outputs"] = layer_outputs[:-1]
+        if self.training and self.dense_head is not None:
+            output["dense_outputs"] = self.dense_head(features)
+        return output
+
+
+def build_model(config: dict[str, Any]) -> ObjectModelV1:
+    model_config = config.get("model", config)
+    fields = ObjectModelV1Spec.__dataclass_fields__
+    unknown = set(model_config) - set(fields)
+    if unknown:
+        raise ValueError(f"Unknown model configuration keys: {sorted(unknown)}")
+    values = dict(model_config)
+    for key in ("backbone_channels", "backbone_depths", "latent_pool_sizes"):
+        if key in values:
+            values[key] = tuple(values[key])
+    return ObjectModelV1(ObjectModelV1Spec(**values))

src/objectmodel_v1/postprocess.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import torch
+from torch import Tensor
+
+from .boxes import box_cxcywh_to_xyxy
+
+
+@torch.no_grad()
+def decode_predictions(
+    outputs: dict[str, Tensor],
+    image_sizes: list[tuple[int, int]],
+    confidence: float = 0.25,
+    top_k: int = 300,
+) -> list[dict[str, Tensor]]:
+    logits = outputs["pred_logits"].sigmoid()
+    boxes = box_cxcywh_to_xyxy(outputs["pred_boxes"]).clamp(0.0, 1.0)
+    results = []
+    for index, (height, width) in enumerate(image_sizes):
+        scores, labels = logits[index].max(dim=-1)
+        keep = scores >= confidence
+        if keep.sum() > top_k:
+            selected = scores.masked_fill(~keep, -1).topk(top_k).indices
+        else:
+            selected = torch.where(keep)[0]
+        selected_boxes = boxes[index, selected].clone()
+        selected_boxes[:, [0, 2]] *= width
+        selected_boxes[:, [1, 3]] *= height
+        results.append(
+            {"scores": scores[selected], "labels": labels[selected], "boxes": selected_boxes}
+        )
+    return results

src/objectmodel_v1/profile.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import argparse
+import json
+import time
+
+import torch
+
+from .config import apply_overrides, load_config
+from .model import build_model
+from .utils import trainable_parameter_count
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Profile ObjectModel-v1 parameters and latency")
+    parser.add_argument("--config", default="configs/objectmodel_v1.yaml")
+    parser.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    parser.add_argument("--warmup", type=int, default=10)
+    parser.add_argument("--runs", type=int, default=50)
+    parser.add_argument("--set", action="append", default=[])
+    args = parser.parse_args()
+    config = apply_overrides(load_config(args.config), args.set)
+    device = torch.device(args.device)
+    model = build_model(config).eval().to(device)
+    size = model.spec.input_size
+    sample = torch.randn(1, 3, size, size, device=device)
+    with torch.inference_mode():
+        for _ in range(args.warmup):
+            model(sample)
+        if device.type == "cuda":
+            torch.cuda.synchronize()
+        durations = []
+        for _ in range(args.runs):
+            start = time.perf_counter()
+            model(sample)
+            if device.type == "cuda":
+                torch.cuda.synchronize()
+            durations.append((time.perf_counter() - start) * 1000)
+    durations.sort()
+    parameters = trainable_parameter_count(model)
+    report = {
+        "parameters": parameters,
+        "parameters_millions": round(parameters / 1e6, 3),
+        "fp32_weight_megabytes": round(parameters * 4 / 1024**2, 2),
+        "input_size": size,
+        "device": str(device),
+        "latency_ms_median": round(durations[len(durations) // 2], 3),
+        "latency_ms_p95": round(durations[min(int(len(durations) * 0.95), len(durations) - 1)], 3),
+    }
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()

src/objectmodel_v1/tracking.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+
+def _box_to_state(box: np.ndarray) -> np.ndarray:
+    x0, y0, x1, y1 = box
+    width, height = x1 - x0, y1 - y0
+    cx, cy = x0 + width / 2.0, y0 + height / 2.0
+    scale = width * height
+    aspect = width / max(height, 1e-6)
+    return np.array([cx, cy, scale, aspect], dtype=np.float64)
+
+
+def _state_to_box(state: np.ndarray) -> np.ndarray:
+    cx, cy, scale, aspect = state[:4]
+    scale = max(scale, 1e-6)
+    width = np.sqrt(scale * aspect)
+    height = scale / max(width, 1e-6)
+    return np.array(
+        [cx - width / 2.0, cy - height / 2.0, cx + width / 2.0, cy + height / 2.0],
+        dtype=np.float64,
+    )
+
+
+def iou_matrix(boxes_a: np.ndarray, boxes_b: np.ndarray) -> np.ndarray:
+    if boxes_a.shape[0] == 0 or boxes_b.shape[0] == 0:
+        return np.zeros((boxes_a.shape[0], boxes_b.shape[0]), dtype=np.float64)
+    area_a = (boxes_a[:, 2] - boxes_a[:, 0]) * (boxes_a[:, 3] - boxes_a[:, 1])
+    area_b = (boxes_b[:, 2] - boxes_b[:, 0]) * (boxes_b[:, 3] - boxes_b[:, 1])
+    top_left = np.maximum(boxes_a[:, None, :2], boxes_b[None, :, :2])
+    bottom_right = np.minimum(boxes_a[:, None, 2:], boxes_b[None, :, 2:])
+    width_height = np.clip(bottom_right - top_left, 0, None)
+    intersection = width_height[..., 0] * width_height[..., 1]
+    union = area_a[:, None] + area_b[None, :] - intersection
+    return intersection / np.clip(union, 1e-9, None)
+
+
+class _KalmanBoxTracker:
+    """Constant-velocity Kalman filter over (cx, cy, scale, aspect) — the classic SORT state.
+
+    Aspect ratio is treated as constant (no velocity term for it), matching Bewley et al. 2016.
+    """
+
+    _next_id = 1
+
+    def __init__(self, box: np.ndarray, label: int, score: float) -> None:
+        self.state = np.zeros(7, dtype=np.float64)
+        self.state[:4] = _box_to_state(box)
+        self.covariance = np.eye(7) * 10.0
+        self.covariance[4:, 4:] *= 1000.0
+
+        self._transition = np.eye(7)
+        for i in range(3):
+            self._transition[i, i + 4] = 1.0
+        self._observation = np.zeros((4, 7))
+        self._observation[:4, :4] = np.eye(4)
+
+        self._process_noise = np.eye(7) * 1.0
+        self._process_noise[4:, 4:] *= 0.01
+        self._measurement_noise = np.eye(4) * 1.0
+
+        self.id = _KalmanBoxTracker._next_id
+        _KalmanBoxTracker._next_id += 1
+        self.label = label
+        self.score = score
+        self.hits = 1
+        self.age = 0
+        self.time_since_update = 0
+
+    def predict(self) -> np.ndarray:
+        self.state = self._transition @ self.state
+        self.covariance = self._transition @ self.covariance @ self._transition.T + self._process_noise
+        self.age += 1
+        self.time_since_update += 1
+        state = self.state.copy()
+        state[2] = max(state[2], 1e-6)
+        return _state_to_box(state)
+
+    def update(self, box: np.ndarray, label: int, score: float) -> None:
+        measurement = _box_to_state(box)
+        innovation = measurement - self._observation @ self.state
+        innovation_cov = self._observation @ self.covariance @ self._observation.T + self._measurement_noise
+        kalman_gain = self.covariance @ self._observation.T @ np.linalg.inv(innovation_cov)
+        self.state = self.state + kalman_gain @ innovation
+        self.covariance = (np.eye(7) - kalman_gain @ self._observation) @ self.covariance
+        self.label = label
+        self.score = score
+        self.hits += 1
+        self.time_since_update = 0
+
+    def current_box(self) -> np.ndarray:
+        return _state_to_box(self.state)
+
+
+@dataclass
+class Track:
+    id: int
+    box: tuple[float, float, float, float]
+    label: int
+    score: float
+    hits: int
+    age: int
+
+
+class SortTracker:
+    """Minimal SORT-style tracker: Kalman motion prediction + IoU/Hungarian association.
+
+    This sits *outside* the model as a post-processing layer over independent
+    per-frame detections — ObjectModel-v1 itself has no temporal component.
+    Gives detections a persistent id and lets a track survive a few frames of
+    missed detection (occlusion, a confidence dip) via `max_age`.
+    """
+
+    def __init__(self, iou_threshold: float = 0.3, max_age: int = 5, min_hits: int = 3) -> None:
+        self.iou_threshold = iou_threshold
+        self.max_age = max_age
+        self.min_hits = min_hits
+        self._trackers: list[_KalmanBoxTracker] = []
+
+    def update(self, boxes: np.ndarray, labels: np.ndarray, scores: np.ndarray) -> list[Track]:
+        """Advance one frame. `boxes` is [N, 4] xyxy, `labels`/`scores` are [N]."""
+        predicted = (
+            np.array([tracker.predict() for tracker in self._trackers])
+            if self._trackers
+            else np.zeros((0, 4))
+        )
+
+        matches, unmatched_detections, _ = self._associate(predicted, boxes)
+
+        for det_idx, trk_idx in matches:
+            self._trackers[trk_idx].update(boxes[det_idx], int(labels[det_idx]), float(scores[det_idx]))
+
+        for det_idx in unmatched_detections:
+            self._trackers.append(
+                _KalmanBoxTracker(boxes[det_idx], int(labels[det_idx]), float(scores[det_idx]))
+            )
+
+        self._trackers = [t for t in self._trackers if t.time_since_update <= self.max_age]
+
+        results = []
+        for tracker in self._trackers:
+            confirmed = tracker.hits >= self.min_hits or tracker.age <= self.min_hits
+            if tracker.time_since_update == 0 and confirmed:
+                x0, y0, x1, y1 = tracker.current_box()
+                results.append(
+                    Track(
+                        id=tracker.id,
+                        box=(x0, y0, x1, y1),
+                        label=tracker.label,
+                        score=tracker.score,
+                        hits=tracker.hits,
+                        age=tracker.age,
+                    )
+                )
+        return results
+
+    def _associate(
+        self, predicted: np.ndarray, detections: np.ndarray
+    ) -> tuple[list[tuple[int, int]], list[int], list[int]]:
+        if predicted.shape[0] == 0 or detections.shape[0] == 0:
+            return [], list(range(detections.shape[0])), list(range(predicted.shape[0]))
+
+        iou = iou_matrix(detections, predicted)
+        row_idx, col_idx = linear_sum_assignment(1.0 - iou)
+
+        matches: list[tuple[int, int]] = []
+        matched_detections: set[int] = set()
+        matched_trackers: set[int] = set()
+        for row, col in zip(row_idx, col_idx, strict=True):
+            if iou[row, col] >= self.iou_threshold:
+                matches.append((row, col))
+                matched_detections.add(row)
+                matched_trackers.add(col)
+
+        unmatched_detections = [i for i in range(detections.shape[0]) if i not in matched_detections]
+        unmatched_trackers = [i for i in range(predicted.shape[0]) if i not in matched_trackers]
+        return matches, unmatched_detections, unmatched_trackers

src/objectmodel_v1/train.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import time
+from pathlib import Path
+
+import torch
+import torch.distributed as dist
+from torch.nn.parallel import DistributedDataParallel
+from torch.optim import AdamW
+from torch.optim.lr_scheduler import LambdaLR
+from torch.utils.data import DataLoader, DistributedSampler
+
+from .config import apply_overrides, load_config, save_config
+from .data import build_dataset, detection_collate
+from .evaluate import evaluate_coco
+from .losses import ObjectModelCriterion
+from .model import build_model
+from .utils import (
+    ModelEMA,
+    learning_rate_factor,
+    move_targets,
+    save_checkpoint,
+    seed_everything,
+    trainable_parameter_count,
+)
+
+
+def distributed_context() -> tuple[int, int, int]:
+    world_size = int(os.environ.get("WORLD_SIZE", "1"))
+    rank = int(os.environ.get("RANK", "0"))
+    local_rank = int(os.environ.get("LOCAL_RANK", "0"))
+    if world_size > 1:
+        if not torch.cuda.is_available():
+            raise RuntimeError("Distributed training currently requires CUDA")
+        torch.cuda.set_device(local_rank)
+        dist.init_process_group(backend="nccl")
+    return rank, world_size, local_rank
+
+
+def build_optimizer(model, config: dict) -> AdamW:
+    train = config["train"]
+    backbone, other = [], []
+    for name, parameter in model.named_parameters():
+        if not parameter.requires_grad:
+            continue
+        (backbone if name.startswith("backbone.") else other).append(parameter)
+    return AdamW(
+        [
+            {"params": other, "lr": float(train["lr"])},
+            {"params": backbone, "lr": float(train.get("backbone_lr", train["lr"]))},
+        ],
+        weight_decay=float(train["weight_decay"]),
+    )
+
+
+def reduce_losses(losses: dict[str, torch.Tensor], world_size: int) -> dict[str, float]:
+    values = torch.stack([value.detach() for value in losses.values()])
+    if world_size > 1:
+        dist.all_reduce(values)
+        values /= world_size
+    return {name: float(value) for name, value in zip(losses, values, strict=True)}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Train ObjectModel-v1")
+    parser.add_argument("--config", default="configs/objectmodel_v1.yaml")
+    parser.add_argument("--data-root", required=True)
+    parser.add_argument("--output", default="outputs/objectmodel_v1")
+    parser.add_argument("--resume")
+    parser.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    parser.add_argument("--set", action="append", default=[])
+    args = parser.parse_args()
+
+    rank, world_size, local_rank = distributed_context()
+    config = apply_overrides(load_config(args.config), args.set)
+    train_config = config["train"]
+    seed_everything(int(train_config["seed"]) + rank)
+    device = torch.device(f"cuda:{local_rank}" if world_size > 1 else args.device)
+    if device.type == "cuda":
+        torch.backends.cudnn.benchmark = True
+        torch.backends.cuda.matmul.allow_tf32 = True
+        torch.backends.cudnn.allow_tf32 = True
+        torch.set_float32_matmul_precision("high")
+    channels_last = bool(train_config.get("channels_last", False))
+    compile_model = bool(train_config.get("compile", False))
+    output_dir = Path(args.output)
+    if rank == 0:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        save_config(config, output_dir / "config.yaml")
+
+    train_dataset = build_dataset(config, args.data_root, "train")
+    train_sampler = DistributedSampler(train_dataset, shuffle=True) if world_size > 1 else None
+    train_loader = DataLoader(
+        train_dataset,
+        batch_size=int(train_config["batch_size"]),
+        shuffle=train_sampler is None,
+        sampler=train_sampler,
+        num_workers=int(train_config["workers"]),
+        pin_memory=device.type == "cuda",
+        drop_last=True,
+        persistent_workers=int(train_config["workers"]) > 0,
+        prefetch_factor=int(train_config.get("prefetch_factor", 4))
+        if int(train_config["workers"]) > 0
+        else None,
+        collate_fn=detection_collate,
+    )
+    model = build_model(config).to(device)
+    if channels_last:
+        model = model.to(memory_format=torch.channels_last)
+    criterion = ObjectModelCriterion(config).to(device)
+    optimizer = build_optimizer(model, config)
+    total_steps = int(train_config["epochs"]) * len(train_loader)
+    scheduler = LambdaLR(
+        optimizer,
+        lambda step: learning_rate_factor(
+            step,
+            total_steps,
+            int(train_config["warmup_steps"]),
+            float(train_config["min_lr_ratio"]),
+        ),
+    )
+    ema = ModelEMA(model, float(train_config["ema_decay"])) if rank == 0 else None
+    start_epoch, global_step, best_ap = 0, 0, -1.0
+    if args.resume:
+        checkpoint = torch.load(args.resume, map_location="cpu", weights_only=False)
+        model.load_state_dict(checkpoint["model"])
+        optimizer.load_state_dict(checkpoint["optimizer"])
+        scheduler.load_state_dict(checkpoint["scheduler"])
+        start_epoch = int(checkpoint["epoch"]) + 1
+        global_step = int(checkpoint.get("global_step", start_epoch * len(train_loader)))
+        best_ap = float(checkpoint.get("best_ap", -1.0))
+        if ema is not None and "ema" in checkpoint:
+            ema.model.load_state_dict(checkpoint["ema"])
+    if rank == 0:
+        print(
+            json.dumps(
+                {
+                    "parameters": trainable_parameter_count(model),
+                    "world_size": world_size,
+                    "device": str(device),
+                    "steps_per_epoch": len(train_loader),
+                },
+                indent=2,
+            )
+        )
+
+    training_model = (
+        DistributedDataParallel(model, device_ids=[local_rank], find_unused_parameters=False)
+        if world_size > 1
+        else model
+    )
+    if compile_model:
+        training_model = torch.compile(training_model, dynamic=False, mode="reduce-overhead")
+    use_amp = bool(train_config.get("amp", True)) and device.type == "cuda"
+    amp_dtype = (
+        torch.bfloat16 if train_config.get("amp_dtype", "float16") == "bfloat16" else torch.float16
+    )
+    scaler = torch.amp.GradScaler("cuda", enabled=use_amp and amp_dtype == torch.float16)
+    history_path = output_dir / "metrics.jsonl"
+    for epoch in range(start_epoch, int(train_config["epochs"])):
+        if train_sampler is not None:
+            train_sampler.set_epoch(epoch)
+        training_model.train()
+        epoch_start = time.perf_counter()
+        log_start = epoch_start
+        running = torch.zeros((), device=device)
+        for batch_index, (images, targets) in enumerate(train_loader):
+            images = images.to(
+                device,
+                non_blocking=True,
+                memory_format=torch.channels_last if channels_last else torch.preserve_format,
+            )
+            targets = move_targets(targets, device)
+            optimizer.zero_grad(set_to_none=True)
+            with torch.autocast(device_type=device.type, dtype=amp_dtype, enabled=use_amp):
+                outputs = training_model(images)
+                losses = criterion(outputs, targets)
+            scaler.scale(losses["loss_total"]).backward()
+            scaler.unscale_(optimizer)
+            torch.nn.utils.clip_grad_norm_(
+                training_model.parameters(), float(train_config["clip_grad_norm"])
+            )
+            scaler.step(optimizer)
+            scaler.update()
+            scheduler.step()
+            global_step += 1
+            if ema is not None:
+                ema.update(model)
+            running += losses["loss_total"].detach()
+            if rank == 0 and (batch_index + 1) % int(train_config["print_freq"]) == 0:
+                now = time.perf_counter()
+                log_steps = int(train_config["print_freq"])
+                avg_loss = running / (batch_index + 1)
+                if world_size > 1:
+                    dist.all_reduce(avg_loss)
+                    avg_loss = avg_loss / world_size
+                print(
+                    f"epoch={epoch + 1} step={batch_index + 1}/{len(train_loader)} "
+                    f"loss={avg_loss.item():.4f} lr={scheduler.get_last_lr()[0]:.3e} "
+                    f"step_seconds={(now - log_start) / log_steps:.3f} "
+                    f"images_per_second={log_steps * len(images) / (now - log_start):.2f}",
+                    flush=True,
+                )
+                log_start = now
+
+        epoch_avg_loss = running / max(len(train_loader), 1)
+        if world_size > 1:
+            dist.all_reduce(epoch_avg_loss)
+            epoch_avg_loss = epoch_avg_loss / world_size
+        metrics: dict[str, float] = {
+            "epoch": epoch + 1,
+            "train_loss": epoch_avg_loss.item(),
+            "epoch_seconds": time.perf_counter() - epoch_start,
+        }
+        if world_size > 1:
+            dist.barrier()
+        should_evaluate = (epoch + 1) % int(train_config["eval_every"]) == 0
+        if rank == 0 and should_evaluate:
+            val_dataset = build_dataset(config, args.data_root, "val")
+            val_loader = DataLoader(
+                val_dataset,
+                batch_size=int(train_config.get("eval_batch_size", train_config["batch_size"])),
+                shuffle=False,
+                num_workers=int(train_config["workers"]),
+                pin_memory=device.type == "cuda",
+                collate_fn=detection_collate,
+            )
+            metrics.update(
+                evaluate_coco(
+                    ema.model if ema is not None else model,
+                    val_loader,
+                    device,
+                    output_dir / f"predictions_epoch_{epoch + 1:03d}.json",
+                )
+            )
+        if rank == 0:
+            state = {
+                "epoch": epoch,
+                "global_step": global_step,
+                "best_ap": max(best_ap, metrics.get("AP", -1.0)),
+                "model": model.state_dict(),
+                "ema": ema.model.state_dict() if ema is not None else model.state_dict(),
+                "optimizer": optimizer.state_dict(),
+                "scheduler": scheduler.state_dict(),
+                "config": config,
+            }
+            save_checkpoint(output_dir / "last.pt", **state)
+            if metrics.get("AP", -1.0) > best_ap:
+                best_ap = metrics["AP"]
+                state["best_ap"] = best_ap
+                save_checkpoint(output_dir / "best.pt", **state)
+            with history_path.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(metrics) + "\n")
+            print(json.dumps(metrics))
+        if world_size > 1:
+            dist.barrier()
+    if world_size > 1:
+        dist.destroy_process_group()
+
+
+if __name__ == "__main__":
+    main()

src/objectmodel_v1/utils.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+import math
+import random
+from copy import deepcopy
+from pathlib import Path
+
+import numpy as np
+import torch
+from torch import Tensor, nn
+
+
+def seed_everything(seed: int) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+
+
+def move_targets(targets: list[dict[str, Tensor]], device: torch.device):
+    return [
+        {key: value.to(device, non_blocking=True) for key, value in target.items()}
+        for target in targets
+    ]
+
+
+class ModelEMA:
+    def __init__(self, model: nn.Module, decay: float = 0.9998) -> None:
+        self.model = deepcopy(model).eval()
+        self.decay = decay
+        for parameter in self.model.parameters():
+            parameter.requires_grad_(False)
+        target = dict(self.model.state_dict())
+        self._float_names = [name for name, value in target.items() if value.is_floating_point()]
+        self._float_targets = [target[name] for name in self._float_names]
+        self._other = [(name, target[name]) for name in target if not target[name].is_floating_point()]
+        self._float_sources: list[Tensor] | None = None
+        self._other_sources: list[Tensor] | None = None
+
+    @torch.no_grad()
+    def update(self, model: nn.Module) -> None:
+        if self._float_sources is None:
+            source = dict(model.state_dict())
+            self._float_sources = [source[name].detach() for name in self._float_names]
+            self._other_sources = [source[name].detach() for name, _ in self._other]
+        torch._foreach_mul_(self._float_targets, self.decay)
+        torch._foreach_add_(self._float_targets, self._float_sources, alpha=1.0 - self.decay)
+        for (_, target_value), source_value in zip(self._other, self._other_sources):
+            target_value.copy_(source_value)
+
+
+def learning_rate_factor(step: int, total_steps: int, warmup_steps: int, min_ratio: float) -> float:
+    if warmup_steps > 0 and step < warmup_steps:
+        return max(step + 1, 1) / warmup_steps
+    progress = (step - warmup_steps) / max(total_steps - warmup_steps, 1)
+    cosine = 0.5 * (1.0 + math.cos(math.pi * min(max(progress, 0.0), 1.0)))
+    return min_ratio + (1.0 - min_ratio) * cosine
+
+
+def save_checkpoint(path: str | Path, **state) -> None:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    torch.save(state, temporary)
+    temporary.replace(path)
+
+
+def write_json(path: str | Path, value) -> None:
+    with Path(path).open("w", encoding="utf-8") as handle:
+        json.dump(value, handle, indent=2)
+
+
+def trainable_parameter_count(model: nn.Module) -> int:
+    return sum(parameter.numel() for parameter in model.parameters() if parameter.requires_grad)

tests/test_boxes.py

@@ -0,0 +1,20 @@
+import torch
+
+from objectmodel_v1.boxes import (
+    box_cxcywh_to_xyxy,
+    box_xyxy_to_cxcywh,
+    generalized_box_iou,
+)
+
+
+def test_box_conversion_roundtrip():
+    boxes = torch.tensor([[0.5, 0.4, 0.2, 0.6], [0.2, 0.3, 0.1, 0.1]])
+    restored = box_xyxy_to_cxcywh(box_cxcywh_to_xyxy(boxes))
+    torch.testing.assert_close(restored, boxes)
+
+
+def test_generalized_iou_identity_and_separation():
+    boxes = torch.tensor([[0.1, 0.1, 0.4, 0.4], [0.6, 0.6, 0.9, 0.9]])
+    giou = generalized_box_iou(boxes, boxes)
+    torch.testing.assert_close(giou.diag(), torch.ones(2))
+    assert giou[0, 1] < 0

tests/test_data.py

@@ -0,0 +1,36 @@
+import json
+
+from PIL import Image
+import torch
+
+from objectmodel_v1.data import CocoDetectionDataset, detection_collate
+
+
+def test_coco_dataset_and_empty_image(tmp_path):
+    image_dir = tmp_path / "images"
+    image_dir.mkdir()
+    Image.new("RGB", (100, 50), "white").save(image_dir / "one.jpg")
+    Image.new("RGB", (80, 80), "black").save(image_dir / "two.jpg")
+    annotations = {
+        "images": [
+            {"id": 1, "file_name": "one.jpg", "width": 100, "height": 50},
+            {"id": 2, "file_name": "two.jpg", "width": 80, "height": 80},
+        ],
+        "annotations": [
+            {"id": 1, "image_id": 1, "category_id": 7, "bbox": [10, 5, 20, 10], "iscrowd": 0}
+        ],
+        "categories": [{"id": 7, "name": "object"}],
+    }
+    annotation_file = tmp_path / "annotations.json"
+    annotation_file.write_text(json.dumps(annotations), encoding="utf-8")
+    dataset = CocoDetectionDataset(image_dir, annotation_file, 64, training=False)
+    image, target = dataset[0]
+    empty_image, empty_target = dataset[1]
+    assert image.shape == (3, 64, 64)
+    assert target["boxes"].shape == (1, 4)
+    assert target["labels"].tolist() == [0]
+    assert empty_target["boxes"].shape == (0, 4)
+    batch, targets = detection_collate([(image, target), (empty_image, empty_target)])
+    assert batch.shape == (2, 3, 64, 64)
+    assert len(targets) == 2
+    assert torch.isfinite(batch).all()

tests/test_losses.py

@@ -0,0 +1,75 @@
+import torch
+from test_model import tiny_config
+
+from objectmodel_v1.losses import ObjectModelCriterion
+
+
+def reference_dense_targets(criterion, logits, targets, level_index):
+    batch, _, height, width = logits.shape
+    target_logits = torch.zeros_like(logits)
+    target_boxes = torch.zeros(batch, 4, height, width, device=logits.device)
+    positive = torch.zeros(batch, height, width, device=logits.device)
+    for batch_index, target in enumerate(targets):
+        if target["labels"].numel() == 0:
+            continue
+        centers = target["boxes"][:, :2]
+        grid = (centers * torch.tensor([width, height], device=centers.device)).long()
+        grid[:, 0].clamp_(0, width - 1)
+        grid[:, 1].clamp_(0, height - 1)
+        areas = target["boxes"][:, 2] * target["boxes"][:, 3]
+        target_levels = torch.where(areas < 0.02, 0, torch.where(areas < 0.15, 1, 2))
+        for target_index in torch.where(target_levels == level_index)[0]:
+            center_x, center_y = grid[target_index]
+            label = target["labels"][target_index]
+            candidates = []
+            for dy in (-1, 0, 1):
+                for dx in (-1, 0, 1):
+                    x = int((center_x + dx).clamp(0, width - 1))
+                    y = int((center_y + dy).clamp(0, height - 1))
+                    candidates.append((dx * dx + dy * dy, x, y))
+            for _, x, y in sorted(candidates)[: criterion.dense_topk]:
+                target_logits[batch_index, label, y, x] = 1.0
+                target_boxes[batch_index, :, y, x] = target["boxes"][target_index]
+                positive[batch_index, y, x] = 1.0
+    return target_logits, target_boxes, positive
+
+
+def test_dense_targets_match_reference_with_boundaries_and_collisions():
+    criterion = ObjectModelCriterion(tiny_config())
+    logits = torch.randn(2, 5, 8, 8)
+    targets = [
+        {
+            "boxes": torch.tensor(
+                [
+                    [0.01, 0.01, 0.10, 0.10],
+                    [0.02, 0.02, 0.11, 0.11],
+                    [0.99, 0.99, 0.50, 0.50],
+                ]
+            ),
+            "labels": torch.tensor([1, 2, 3]),
+        },
+        {"boxes": torch.empty(0, 4), "labels": torch.empty(0, dtype=torch.long)},
+    ]
+
+    for level_index in range(3):
+        expected = reference_dense_targets(criterion, logits, targets, level_index)
+        actual = criterion._dense_targets(logits, targets, level_index)
+        for expected_tensor, actual_tensor in zip(expected, actual, strict=True):
+            assert torch.equal(expected_tensor, actual_tensor)
+
+
+def test_dense_targets_match_reference_for_production_topk():
+    config = tiny_config()
+    config["loss"]["dense_topk"] = 5
+    criterion = ObjectModelCriterion(config)
+    logits = torch.randn(2, 5, 12, 10)
+    targets = [
+        {"boxes": torch.rand(9, 4), "labels": torch.randint(0, 5, (9,))},
+        {"boxes": torch.rand(4, 4), "labels": torch.randint(0, 5, (4,))},
+    ]
+
+    for level_index in range(3):
+        expected = reference_dense_targets(criterion, logits, targets, level_index)
+        actual = criterion._dense_targets(logits, targets, level_index)
+        for expected_tensor, actual_tensor in zip(expected, actual, strict=True):
+            assert torch.equal(expected_tensor, actual_tensor)

tests/test_matching.py

@@ -0,0 +1,40 @@
+import torch
+
+from objectmodel_v1.matching import hungarian_match, hungarian_match_layers
+
+
+def test_layer_matcher_matches_individual_calls():
+    torch.manual_seed(7)
+    outputs = [
+        {
+            "pred_logits": torch.randn(3, 12, 5),
+            "pred_boxes": torch.rand(3, 12, 4),
+        }
+        for _ in range(3)
+    ]
+    targets = [
+        {"labels": torch.tensor([1, 3]), "boxes": torch.rand(2, 4)},
+        {"labels": torch.empty(0, dtype=torch.long), "boxes": torch.empty(0, 4)},
+        {"labels": torch.tensor([0, 2, 4]), "boxes": torch.rand(3, 4)},
+    ]
+
+    expected = [hungarian_match(output, targets) for output in outputs]
+    actual = hungarian_match_layers(outputs, targets)
+
+    for expected_layer, actual_layer in zip(expected, actual, strict=True):
+        for expected_match, actual_match in zip(expected_layer, actual_layer, strict=True):
+            assert torch.equal(expected_match[0], actual_match[0])
+            assert torch.equal(expected_match[1], actual_match[1])
+
+
+def test_layer_matcher_handles_all_empty_targets():
+    outputs = [{"pred_logits": torch.randn(2, 4, 3), "pred_boxes": torch.rand(2, 4, 4)}]
+    targets = [
+        {"labels": torch.empty(0, dtype=torch.long), "boxes": torch.empty(0, 4)},
+        {"labels": torch.empty(0, dtype=torch.long), "boxes": torch.empty(0, 4)},
+    ]
+
+    matches = hungarian_match_layers(outputs, targets)
+
+    assert len(matches) == 1
+    assert all(rows.numel() == 0 and cols.numel() == 0 for rows, cols in matches[0])

tests/test_model.py

@@ -0,0 +1,83 @@
+import torch
+
+from objectmodel_v1.losses import ObjectModelCriterion
+from objectmodel_v1.model import build_model
+from objectmodel_v1.postprocess import decode_predictions
+
+
+def tiny_config(dense_aux=True):
+    return {
+        "model": {
+            "num_classes": 5,
+            "input_size": 128,
+            "stem_channels": 16,
+            "backbone_channels": [24, 32, 48, 64],
+            "backbone_depths": [1, 1, 1, 1],
+            "hidden_dim": 48,
+            "fpn_depth": 1,
+            "latent_count": 8,
+            "latent_pool_sizes": [4, 2, 1],
+            "latent_layers": 1,
+            "decoder_layers": 2,
+            "num_queries": 12,
+            "num_heads": 4,
+            "local_points": 2,
+            "dropout": 0.0,
+            "dense_aux": dense_aux,
+        },
+        "loss": {
+            "cost_class": 2.0,
+            "cost_bbox": 5.0,
+            "cost_giou": 2.0,
+            "weight_class": 2.0,
+            "weight_bbox": 5.0,
+            "weight_giou": 2.0,
+            "weight_dense": 1.0,
+            "focal_alpha": 0.25,
+            "focal_gamma": 2.0,
+            "aux_weight": 1.0,
+            "dense_topk": 3,
+        },
+    }
+
+
+def test_forward_shapes_and_ranges():
+    model = build_model(tiny_config()).eval()
+    with torch.no_grad():
+        output = model(torch.randn(2, 3, 128, 128))
+    assert output["pred_logits"].shape == (2, 12, 5)
+    assert output["pred_boxes"].shape == (2, 12, 4)
+    assert len(output["aux_outputs"]) == 1
+    assert "dense_outputs" not in output
+    assert torch.all((output["pred_boxes"] >= 0) & (output["pred_boxes"] <= 1))
+
+
+def test_loss_backward_with_empty_target():
+    config = tiny_config()
+    model = build_model(config).train()
+    criterion = ObjectModelCriterion(config)
+    output = model(torch.randn(2, 3, 128, 128))
+    targets = [
+        {
+            "boxes": torch.tensor([[0.5, 0.5, 0.25, 0.3], [0.2, 0.2, 0.1, 0.1]]),
+            "labels": torch.tensor([1, 3]),
+        },
+        {"boxes": torch.empty(0, 4), "labels": torch.empty(0, dtype=torch.long)},
+    ]
+    losses = criterion(output, targets)
+    assert all(torch.isfinite(value) for value in losses.values())
+    losses["loss_total"].backward()
+    gradients = [parameter.grad for parameter in model.parameters() if parameter.grad is not None]
+    assert gradients
+    assert all(torch.isfinite(gradient).all() for gradient in gradients)
+
+
+def test_decode_is_nms_free_top_k_filter():
+    model = build_model(tiny_config(dense_aux=False)).eval()
+    with torch.no_grad():
+        output = model(torch.randn(1, 3, 128, 128))
+    result = decode_predictions(output, [(240, 320)], confidence=0.0, top_k=4)[0]
+    assert result["boxes"].shape == (4, 4)
+    assert result["scores"].shape == (4,)
+    assert torch.all(result["boxes"][:, [0, 2]] <= 320)
+    assert torch.all(result["boxes"][:, [1, 3]] <= 240)