US-001 audit

Current package surface

This audit records the package, docs, tests, dependency extras, detector aliases, and legacy references observed before the object-detection package expansion work.

Developer Guide API Reference Roadmap

Use this page as a factual baseline for later PRD stories. It does not update PRD status.

Package modules

The installable package lives under simpledet/simpledet/. Current modules are:

  • __init__.py, __main__.py, api.py, cli.py, bench.py, and _model_resolution.py
  • detectors/: dependency hints, CLI adapter, dataset adapters, training, inference, and evaluation helpers
  • extensions/: explicit registries for encoders, necks, heads, decoders, and detectors
  • suite/: public dataclass specs, builder helpers, native plan compiler, and architecture catalog
  • native/: backbone, neck, head, dense ops, ROI, transformer ops, Lightning engine, runtime, modeling, and assembler code

Public API surface

  • simpledet: lazy exports for train, detect, evaluate, suite, native, extensions, detectors, project config dataclasses, config helpers, image prediction helpers, and project/direct run helpers.
  • simpledet.api: ProjectLayout, DatasetConfig, RuntimeConfig, OptimizationConfig, CheckpointConfig, ExportConfig, ProjectConfig, load_project_config, project_config_template, init_project_config, validate_project_config, run_project, run_training, run_inference, run_evaluation, predict_image, predict_batch, load_checkpoint_for_inference, export_predictions, run_native_training, run_native_inference, run_native_evaluation, and list_available_* helpers.
  • simpledet.suite: EncoderSpec, NeckSpec, HeadSpec, DecoderSpec, DetectorSpec, component builders, custom builders, native registry list/inspect/resolve helpers, and compile_native_detector_plan.
  • simpledet.native: reusable CNN blocks, native component builders, model component assembly, dense and ROI model boundaries, Lightning runtime helpers, and native project execution helpers.
  • simpledet.detectors: legacy-compatible public helpers for train, detect, evaluate, dataset loading, and CLI forwarding.
  • simpledet.extensions: ExtensionRegistry, ENCODERS, NECKS, HEADS, DECODERS, and DETECTORS.
  • Console script: simpledet = simpledet.cli:main.

Optional extras

Scope or extra Current dependencies Audit note
Base install None Base install is intentionally lightweight and is not a named optional extra.
cpu torch, torchvision, pytorch-lightning, numpy, scipy, pycocotools, terminaltables CPU runtime dependencies only; TIMM, plotting, and geospatial libraries remain separate extras.
timm timm TIMM encoder support remains optional so base and CPU installs stay smaller.
geo pandas, rasterio, geopandas, shapely Geospatial data support remains optional.
plots SciencePlots, matplotlib Plotting support remains optional.
dev build, coverage, tomli for Python < 3.11, twine, ruff Development tooling only.
docs None Explicit documentation workflow extra reserved for future docs tooling.

Test coverage

  • tests/test_public_api.py and tests/test_api_model_resolution.py: project API, runtime delegation, model patch helpers, and registry list helpers.
  • tests/test_cli.py: CLI diagnostics, detector listing, project config commands, and direct train/infer/eval argument routing.
  • tests/test_suite.py and tests/test_native_backend_plan.py: suite specs, aliases, custom components, plan compilation, and registry primitives.
  • tests/test_native_components.py, tests/test_native_backbones.py, tests/test_native_runtime.py, and tests/test_native_api_routing.py: native component assembly, selected tensor-like smoke paths, ROI behavior, native runtime manifests, and API routing.
  • tests/test_data.py: CSV, JSON/JSONL, YOLO, COCO, and VOC dataset adapter behavior.
  • tests/test_deps.py: optional dependency error messages.
  • tests/test_packaging.py and tests/test_repo_audit.py: package metadata, dist contents, safe imports, Python compilation, and maintained-package legacy reference checks.

Legacy references

  • Maintained package code does not import or reference mmdet, mmcv, or mmengine; tests/test_repo_audit.py enforces this for package paths.
  • Docs and README do not present MMDetection or MMEngine as a runtime path.
  • Legacy MMDetection .py config paths fail with an explicit unsupported import/conversion error unless a specific converter is added.
  • Legacy references remain outside the maintained package surface, mainly in MyConfigs/, notebooks/, runscripts/, studies/, PLANS.md, deploy.sh, and ext.txt.
  • Those legacy configs and notebooks are evidence of historical experiments only. They must not be counted as supported detector families.

Detector alias audit

The current, user-facing detector/head/backbone/neck coverage table now lives in Model Coverage. This older audit remains a baseline snapshot.

Status Detector aliases Evidence and caveat
Native runtime registered retinanet, retina, fcos, atss, cornernet, rpn, fast_rcnn, fast-rcnn, faster_rcnn, faster-rcnn, mask_rcnn, mask-rcnn, cascade_rcnn, cascadercnn, cascade_mask_rcnn, cascademaskrcnn, grid_rcnn, gridrcnn, libra_rcnn, librarcnn, double_head_rcnn, doubleheadrcnn, dynamic_rcnn, dynamicrcnn, sparse_rcnn, sparsercnn Registered in native/assemblers.py and covered by suite/native tests. Runtime-validated metadata includes CornerNet paired-corner heatmap loss/decode and Sparse R-CNN learned proposal boxes/features without an RPN fallback.
Native compatible, not architecture-faithful yet gfl, vfnet, fovea, foveabox, reppoints, yolof, centernet, yolo, yolo3, yolo4, yolo_v3, yolov3, yolov4, yolov5, yolov6, yolov7, yolov8, yolov9, yolov10, yolox, rtmdet, rtmdet_tiny, rtmdet_s, rtmdet_m, rtmdet_l, ssd, ssd300, ssd512, ssdlite, efficientdet, efficientdet_d0, efficientdet_d1, efficientdet_d2, sabl, tood, solov2, solov2_light Aliases build native modules, with YOLOX, RTMDet, SSD, EfficientDet, and CenterNet now using explicit lightweight head, target, and decode paths. Several other families still reuse ATSS or FCOS-style losses/decoders or alias heads, so broader architecture-faithful claims still require family-specific validation.
Native transformer scaffold detr, conditional_detr, dab_detr, deformable_detr, dino Registered through one query-detector assembler with native DETR, Conditional DETR, DAB-DETR, Deformable DETR, and DINO heads, positional encoding validation, query logits, normalized boxes, and CPU forward coverage. Unsupported transformer variants such as DETR3D and v2 names now fail with planned-but-unsupported guidance.
Missing from package catalog/runtime FSAF, FreeAnchor, GFocalV2 as gfocalv2, PAA, DDOD, AutoAssign, NAS-FCOS No package-level catalog entry plus native assembler was found. Existing legacy configs, if any, do not count as support.
Config-only or historical Legacy MMDetection config files under MyConfigs/ and older notebooks/scripts These reference mmdet, mmcv, or mmengine and are outside the maintained package runtime.

Minimum next order

  1. Normalize packaging extras: split lightweight base, CPU runtime, TIMM, docs, geo, plots, and dev expectations. Maps to US-002, US-036, and US-040.
  2. Lock the registry contract: add explicit metadata for aliases, component kind, dependencies, tensor contracts, validation status, and duplicate-alias handling before adding more families. Maps to US-003 and US-027.
  3. Quarantine legacy runtime paths: keep MMDetection-era files out of maintained package claims and add explicit audit coverage for that boundary. Maps to US-004 and US-041.
  4. Add tensor-contract fixtures: create reusable CPU tensor fixtures before expanding heads, necks, losses, and detectors. Maps to US-005, US-042, US-043, and US-044.
  5. Build shared primitives first: backbones, TIMM adapter, necks, geometry, assignment, losses, and ROI utilities should precede family claims. Maps to US-006 through US-012.
  6. Promote detector claims by family: implement heads and detector composition in order: core dense, advanced dense, lightweight dense, transformer/query, ROI bbox, then mask/grid. Maps to US-013 through US-025.
  7. Expose and document only validated support: public builders, CLI discovery, model coverage docs, setup doctor, examples, architecture docs, error taxonomy, and release gates should follow validated runtime support. Maps to US-026 through US-046.