Top-level exports
simpledet.__version__simpledet.train, simpledet.detect, simpledet.evaluatesimpledet.run_training, simpledet.run_inference, simpledet.run_evaluationsimpledet.predict_image, predict_batch, load_checkpoint_for_inference, export_predictionssimpledet.build_detector, build_backbone, build_neck, build_headsimpledet.list_detectors, list_heads, list_backbones, compile_native_detector_plansimpledet.nativesimpledet.ProjectLayoutsimpledet.DatasetConfig, simpledet.RuntimeConfig, simpledet.OptimizationConfig, CheckpointConfig, ExportConfigsimpledet.ProjectConfig, load_project_config, init_project_config, run_projectsimpledet.detectorssimpledet.suite
simpledet.suite
EncoderSpec
NeckSpec
HeadSpec
DecoderSpec
DetectorSpec
build_encoder(...)
build_custom_encoder(...)
build_backbone(...)
build_neck(...)
build_custom_neck(...)
build_head(...)
build_custom_head(...)
build_decoder(...)
build_custom_decoder(...)
build_detector(name="retinanet", num_classes=3, backbone="resnet50", build=False)
list_detectors(...)
list_heads(...)
list_backbones(...)
compile_native_detector_plan(spec)
The build_custom_* helpers are the public mechanism for registry-backed custom components. They pair a component type, explicit imports, and the config fields needed by the planner and runtime registry loader.
build_detector(...) returns a DetectorSpec by default. Pass build=True to assemble the native module immediately through the same runtime builder used by training and inference.
compile_native_detector_plan(...) produces the structured build plan consumed by the native runtime. Invalid public builder arguments raise ValueError with actionable messages.
Project config helpers
ProjectLayout(...)
DatasetConfig(...)
RuntimeConfig(...)
OptimizationConfig(...)
CheckpointConfig(...)
ExportConfig(...)
ProjectConfig(...)
project_config_template(...)
init_project_config(...)
load_project_config(...)
validate_project_config(...)
run_project(...)
Use the structured config objects when you want a repeatable project file and a single native entrypoint for build, train, test, and infer stages. ProjectConfig accepts TOML/JSON fields for detector, dataset, workdir, optimizer, scheduler, runtime, seed, stages, checkpoint, and export. run_project(...) validates dataset inputs before creating output and writes run-manifest.json in the workdir after a successful run.
Direct execution helpers
run_training(...)
run_inference(...)
run_evaluation(...)
Use these when you want native execution without creating a config file. They wrap the project-layout helpers and execute the relevant stages directly.
Public errors
SimpleDetError
OptionalDependencyError
RegistryLookupError
ConfigValidationError
DatasetError
TensorContractError
CheckpointError
Public setup, config, registry, dataset, tensor-contract, and checkpoint failures derive from SimpleDetError. Missing optional extras raise OptionalDependencyError with the exact install command, such as python -m pip install 'simpledet[timm]'. Unknown registry names raise RegistryLookupError with the registry kind, registered names, and nearby aliases instead of exposing raw mapping errors.
Image prediction helpers
load_checkpoint_for_inference(checkpoint, *, device="cpu", model_name=None, num_classes=None, class_names=None, score_threshold=0.05, max_detections=None)
predict_image(model, image_path, *, class_names=None, device="cpu", score_threshold=None, max_detections=None, metadata=None)
predict_batch(model, image_paths, *, class_names=None, device="cpu", score_threshold=None, max_detections=None, metadata=None)
export_predictions(predictions, output_path=None, *, indent=2)
predict_image(...) returns boxes, scores, labels, class_names, and metadata. Labels are the detector labels; with class_names=("wake", "ship"), label 1 maps to wake and label 2 maps to ship. Metadata includes the path, file name, channel count, height, width, and tensor shape.
Missing image paths raise FileNotFoundError with the path. Existing paths that cannot be decoded raise ImageLoadingError with the path. predict_batch(...) is fail-fast on the first unreadable image. export_predictions(...) returns and optionally writes {"format": "simpledet_predictions", "version": 1, "predictions": [...]}.
load_checkpoint_for_inference(...) is the lightweight checkpoint path for checkpoints compatible with the existing torchvision-based loader. It uses torch.load, so only load checkpoint files from trusted sources. Native pipeline checkpoints remain under the project runtime helpers.
simpledet.native
NativeProjectConfig(...)
NativeDataConfig(...)
NativeDetectionDataModule(...)
NativeDataValidationError
ConvNeXtBlock(...)
ConvNeXtFeatureBackbone(...)
run_native_training(...)
run_native_inference(...)
run_native_evaluation(...)
SingleStageDetector(...)
QueryDetector(...)
build_detector(name="retinanet", num_classes=3)
build_native_components(...)
This is the native Lightning-backed backend. The current native catalog supports retinanet, retina, fcos, atss, gfl, vfnet, fovea, foveabox, reppoints, yolof, centernet, cornernet, yolox, rtmdet, ssd, efficientdet, detr, conditional_detr, dab_detr, deformable_detr, dino, rpn, fast_rcnn, faster_rcnn, mask_rcnn, cascade_rcnn, cascade_mask_rcnn, grid_rcnn, libra_rcnn, double_head_rcnn, dynamic_rcnn, and sparse_rcnn.
SingleStageDetector is the native single-stage composition. build_detector(name="retinanet", num_classes=3) builds the default ResNet, FPN, and RetinaHead stack; ROI-only heads in single-stage configs are rejected before model construction. simpledet.native.cnn_blocks exposes reusable CNN blocks such as ConvNeXtBlock, ConvNeXtStage, and ConvNeXtFeatureBackbone; the convnext_tiny alias now uses these native blocks and requires only the CPU runtime extra.
Lightweight detector defaults are explicit: yolox uses CSPDarkNet, YOLOXPAFPN, and YOLOXHead; rtmdet uses CSPNeXt, YOLOXPAFPN, and RTMDetHead; ssd uses MobileNetV2, SSDNeck, and SSDHead; efficientdet_d0 uses EfficientNet-B0, BiFPN, and EfficientDetHead; centernet and cornernet use ResNet-18, FPN, and heatmap heads. YOLO-family specs require YOLOXPAFPN; passing an incompatible neck raises a validation error. EfficientDet native construction uses the TIMM-backed EfficientNet alias, so install simpledet[timm] when building the default model module rather than only compiling the spec.
QueryDetector is the native DETR-family composition. build_detector(name="deformable_detr", num_classes=3, num_queries=20) builds a query head that returns pred_logits, normalized pred_boxes, and decoded detection payloads. Transformer detector construction validates positional encoding settings and rejects planned unsupported variants such as DETR3D or v2 names instead of silently routing them to a different contract.
NativeDetectionDataModule is the Lightning-compatible data boundary for native training, validation, and testing. It reads normalized COCO adapter payloads, resolves train/val/test annotation files deterministically, collates batches as list[Tensor], list[dict], preserves target keys for boxes, labels, image_id, area, iscrowd, and metadata, supports shared or split-specific paired image/target transforms, can seed train shuffling with a torch.Generator, and raises NativeDataValidationError before trainer entry when a required split is empty.
Custom native detectors now grow through a detector-assembler layer. Register an assembler in simpledet.extensions.DETECTORS, create a spec with build_custom_detector(...), then call build_native_model(...) on that spec.
The native component registries expose a strict metadata contract for discovery. lookup(...) resolves canonical names and aliases case-insensitively, so detector aliases such as vfnet, VFNet, FoveaBox, and Grid R-CNN resolve to entries that include name, aliases, kind, factory, required optional dependencies, tensor contracts, and validation status. Unknown lookups report the registry kind plus nearby aliases, and missing optional dependencies identify the relevant install extra. tests/test_native_backend_plan.py covers this behavior so registry discovery stays aligned with native runtime assembly.
Head discovery is available through simpledet.api.list_heads(kind="dense"), simpledet.suite.list_heads(kind="dense"), and simpledet.suite.list_heads(kind="transformer"). The dense list includes canonical head names and aliases such as retina_head, fcos_head, atss_head, fsaf_head, fovea_head, free_anchor_head, centernet_head, cornernet_head, yolox_head, rtmdet_head, ssd_head, and efficientdet_head. The transformer list includes query heads such as detr_head, conditional_detr_head, dab_detr_head, deformable_detr_head, and dino_head.
simpledet.api
The public API now centers on ProjectConfig, run_project(...), and the direct helpers run_training(...), run_inference(...), and run_evaluation(...). Legacy pipeline/config-compilation helpers are no longer part of the public contract.
simpledet._model_resolution
list_available_encoders()list_available_heads()list_available_necks()apply_runtime_model_overrides()patch_backbone_input_channels()patch_model_num_classes()