feat: add Mothbot YOLO11m detection pipeline

pyproject.toml

@@ -3,7 +3,7 @@ name = "trapdata"
 version = "0.6.0"
 description = "Companion software for automated insect monitoring stations"
 authors = [{ name = "Michael Bunsen", email = "notbot@gmail.com" }]
-license = { text = "MIT" }
+license = { text = "AGPL-3.0" }
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
 urls = { Homepage = "https://github.com/RolnickLab/ami-data-companion", Repository = "https://github.com/RolnickLab/ami-data-companion" }
@@ -31,6 +31,7 @@ dependencies = [
     "torch>=2.5",
     "torchvision>=0.20",
     "typer>=0.12.3,<1",
+    "ultralytics>=8.3",
     "uvicorn>=0.20",
 ]
 

trapdata/antenna/registration.py

@@ -7,7 +7,7 @@
     AsyncPipelineRegistrationRequest,
     AsyncPipelineRegistrationResponse,
 )
-from trapdata.api.api import CLASSIFIER_CHOICES, initialize_service_info
+from trapdata.api.api import PIPELINE_CHOICES, initialize_service_info
 from trapdata.api.utils import get_http_session
 from trapdata.common.logs import logger
 from trapdata.settings import Settings, read_settings
@@ -134,7 +134,7 @@ def register_pipelines(
     successful_registrations = []
     failed_registrations = []
 
-    logger.info(f"Available pipelines to register: {list(CLASSIFIER_CHOICES.keys())}")
+    logger.info(f"Available pipelines to register: {list(PIPELINE_CHOICES.keys())}")
 
     for project in projects_to_process:
         project_id = project["id"]

trapdata/antenna/worker.py

@@ -14,7 +14,7 @@
 from trapdata.antenna.datasets import CUDAPrefetcher, get_rest_dataloader
 from trapdata.antenna.result_posting import ResultPoster
 from trapdata.antenna.schemas import AntennaTaskResult, AntennaTaskResultError
-from trapdata.api.api import CLASSIFIER_CHOICES, should_filter_detections
+from trapdata.api.api import PIPELINE_CHOICES, should_filter_detections
 from trapdata.api.models.classification import MothClassifierBinary
 from trapdata.api.models.localization import APIMothDetector
 from trapdata.api.schemas import (
@@ -425,7 +425,7 @@ def _process_job(
     detector = None
 
     # Check if binary filtering is needed once for the entire job
-    classifier_class = CLASSIFIER_CHOICES[pipeline]
+    classifier_class = PIPELINE_CHOICES[pipeline]
     use_binary_filter = should_filter_detections(classifier_class)
     binary_filter = None
 
@@ -464,7 +464,7 @@ def _process_job(
             # Defer instantiation of poster, detector and classifiers until we have data
             if not classifier:
                 classifier = classifier_class(source_images=[], detections=[])
-                detector = APIMothDetector([])
+                detector = classifier_class.detector_cls([])
                 result_poster = ResultPoster(max_pending=MAX_PENDING_POSTS)
 
                 if use_binary_filter:

trapdata/api/api.py

@@ -16,6 +16,7 @@
 from .models.classification import (
     APIMothClassifier,
     InsectOrderClassifier,
+    MothbotInsectOrderClassifier,
     MothClassifierBinary,
     MothClassifierGlobal,
     MothClassifierPanama,
@@ -52,7 +53,7 @@ async def lifespan(app: fastapi.FastAPI):
 app.add_middleware(GZipMiddleware)
 
 
-CLASSIFIER_CHOICES = {
+PIPELINE_CHOICES = {
     "panama_moths_2023": MothClassifierPanama,
     "panama_moths_2024": MothClassifierPanama2024,
     "quebec_vermont_moths_2023": MothClassifierQuebecVermont,
@@ -63,20 +64,22 @@ async def lifespan(app: fastapi.FastAPI):
     "global_moths_2024": MothClassifierGlobal,
     "moth_binary": MothClassifierBinary,
     "insect_orders_2025": InsectOrderClassifier,
+    "mothbot_insect_orders_2025": MothbotInsectOrderClassifier,
 }
-_classifier_choices = dict(
-    zip(CLASSIFIER_CHOICES.keys(), list(CLASSIFIER_CHOICES.keys()))
-)
+_classifier_choices = dict(zip(PIPELINE_CHOICES.keys(), list(PIPELINE_CHOICES.keys())))
 
 
 PipelineChoice = enum.Enum("PipelineChoice", _classifier_choices)
 
 
 def should_filter_detections(Classifier: type[APIMothClassifier]) -> bool:
-    if Classifier in [MothClassifierBinary, InsectOrderClassifier]:
+    # Classifiers that skip the binary moth/non-moth prefilter: the binary
+    # classifier itself (there's nothing downstream to filter for), and any
+    # order-level classifier (it already distinguishes non-moth insects,
+    # so a binary prefilter would discard signal).
+    if issubclass(Classifier, (MothClassifierBinary, InsectOrderClassifier)):
         return False
-    else:
-        return True
+    return True
 
 
 def make_category_map_response(
@@ -137,7 +140,7 @@ def make_pipeline_config_response(
     """
     algorithms = []
 
-    detector = APIMothDetector(
+    detector = Classifier.detector_cls(
         source_images=[],
     )
     algorithms.append(make_algorithm_config_response(detector))
@@ -216,9 +219,9 @@ async def process(data: PipelineRequest) -> PipelineResponse:
 
     start_time = time.time()
 
-    Classifier = CLASSIFIER_CHOICES[str(data.pipeline)]
+    Classifier = PIPELINE_CHOICES[str(data.pipeline)]
 
-    detector = APIMothDetector(
+    detector = Classifier.detector_cls(
         source_images=source_images,
         batch_size=settings.localization_batch_size,
         num_workers=settings.num_workers,
@@ -359,7 +362,7 @@ def initialize_service_info() -> ProcessingServiceInfoResponse:
     # @TODO This requires loading all models into memory! Can we avoid this?
     pipeline_configs = [
         make_pipeline_config_response(classifier_class, slug=key)
-        for key, classifier_class in CLASSIFIER_CHOICES.items()
+        for key, classifier_class in PIPELINE_CHOICES.items()
     ]
 
     _info = ProcessingServiceInfoResponse(

trapdata/api/models/classification.py

@@ -28,6 +28,7 @@
     SourceImage,
 )
 from .base import APIInferenceBaseClass
+from .localization import APIMothDetector, APIMothDetector_YOLO11m_Mothbot
 
 
 class APIMothClassifier(
@@ -36,6 +37,11 @@ class APIMothClassifier(
 ):
     task_type = "classification"
 
+    # The detector class this pipeline pairs with. Subclasses override
+    # to pair a specific classifier with a specific detector. Default is
+    # the FasterRCNN 2023 detector that all existing pipelines use.
+    detector_cls: type[APIInferenceBaseClass] = APIMothDetector
+
     def __init__(
         self,
         source_images: typing.Iterable[SourceImage],
@@ -231,3 +237,17 @@ class MothClassifierGlobal(APIMothClassifier, GlobalMothSpeciesClassifier):
 
 class InsectOrderClassifier(APIMothClassifier, InsectOrderClassifier2025):
     pass
+
+
+class MothbotInsectOrderClassifier(InsectOrderClassifier):
+    """Pair the Mothbot YOLO11m detector with our existing ConvNeXt order
+    classifier. Overrides the default detector_cls inherited from
+    APIMothClassifier.
+
+    The ``name`` is distinct from the parent so Antenna's pipeline registry
+    (which keys on name) treats this as a separate pipeline rather than
+    deduping against ``insect_orders_2025``.
+    """
+
+    name = "Insect Order Classifier (Mothbot YOLO detector)"
+    detector_cls = APIMothDetector_YOLO11m_Mothbot

trapdata/api/models/localization.py

@@ -1,7 +1,10 @@
 import datetime
 import typing
 
-from trapdata.ml.models.localization import MothObjectDetector_FasterRCNN_2023
+from trapdata.ml.models.localization import (
+    MothObjectDetector_FasterRCNN_2023,
+    MothObjectDetector_YOLO11m_Mothbot,
+)
 
 from ..datasets import LocalizationImageDataset
 from ..schemas import AlgorithmReference, BoundingBox, DetectionResponse, SourceImage
@@ -56,3 +59,53 @@ def save_detection(image_id, coords):
     def run(self) -> list[DetectionResponse]:
         super().run()
         return self.results
+
+
+class APIMothDetector_YOLO11m_Mothbot(
+    APIInferenceBaseClass, MothObjectDetector_YOLO11m_Mothbot
+):
+    task_type = "localization"
+
+    def __init__(self, source_images: typing.Iterable[SourceImage], *args, **kwargs):
+        self.source_images = source_images
+        self.results: list[DetectionResponse] = []
+        super().__init__(*args, **kwargs)
+
+    def reset(self, source_images: typing.Iterable[SourceImage]):
+        self.source_images = source_images
+        self.results = []
+
+    def get_dataset(self):
+        return LocalizationImageDataset(
+            self.source_images, self.get_transforms(), batch_size=self.batch_size
+        )
+
+    def get_source_image(self, source_image_id: int) -> SourceImage:
+        for source_image in self.source_images:
+            if source_image.id == source_image_id:
+                return source_image
+        raise ValueError(f"Source image with id {source_image_id} not found")
+
+    def save_results(self, item_ids, batch_output, seconds_per_item, *args, **kwargs):
+        """batch_output is a list (one per image) of list[YoloDetection]."""
+        detections: list[DetectionResponse] = []
+        for image_id, yolo_dets in zip(item_ids, batch_output):
+            for y in yolo_dets:
+                detections.append(
+                    DetectionResponse(
+                        source_image_id=image_id,
+                        bbox=BoundingBox(x1=y.x1, y1=y.y1, x2=y.x2, y2=y.y2),
+                        rotation=y.rotation,
+                        inference_time=seconds_per_item,
+                        algorithm=AlgorithmReference(
+                            name=self.name, key=self.get_key()
+                        ),
+                        timestamp=datetime.datetime.now(),
+                        crop_image_url=None,
+                    )
+                )
+        self.results += detections
+
+    def run(self) -> list[DetectionResponse]:
+        super().run()
+        return self.results

trapdata/api/schemas.py

@@ -114,6 +114,17 @@ class DetectionResponse(pydantic.BaseModel):
     timestamp: datetime.datetime
     crop_image_url: str | None = None
     classifications: list[ClassificationResponse] = []
+    rotation: float | None = pydantic.Field(
+        default=None,
+        description=(
+            "Rotation angle in degrees (cv2.minAreaRect convention), when "
+            "the detector produces oriented bounding boxes. FUTURE: "
+            "downstream classifiers may use this to crop a straightened "
+            "patch instead of the axis-aligned envelope. See "
+            "`docs/superpowers/specs/2026-04-14-mothbot-detection-pipeline-design.md` "
+            "for the proposed RotatedBoundingBox schema upgrade."
+        ),
+    )
 
 
 class SourceImageRequest(pydantic.BaseModel):

trapdata/api/tests/test_api.py

@@ -5,7 +5,7 @@
 from fastapi.testclient import TestClient
 
 from trapdata.api.api import (
-    CLASSIFIER_CHOICES,
+    PIPELINE_CHOICES,
     PipelineChoice,
     PipelineRequest,
     PipelineResponse,
@@ -15,7 +15,7 @@
 )
 from trapdata.api.schemas import PipelineConfigRequest
 from trapdata.api.tests.image_server import StaticFileTestServer
-from trapdata.api.tests.utils import get_test_images, get_pipeline_class
+from trapdata.api.tests.utils import get_pipeline_class, get_test_images
 from trapdata.tests import TEST_IMAGES_BASE_PATH
 
 logging.basicConfig(level=logging.INFO)
@@ -62,12 +62,12 @@ def test_pipeline_request(self):
 
     def test_pipeline_config_with_binary_classifier(self):
         binary_classifier_pipeline_choice = "moth_binary"
-        BinaryClassifier = CLASSIFIER_CHOICES[binary_classifier_pipeline_choice]
+        BinaryClassifier = PIPELINE_CHOICES[binary_classifier_pipeline_choice]
         binary_classifier_instance = BinaryClassifier(source_images=[], detections=[])
         BinaryClassifierResponse = make_algorithm_response(binary_classifier_instance)
 
         species_classifier_pipeline_choice = "quebec_vermont_moths_2023"
-        SpeciesClassifier = CLASSIFIER_CHOICES[species_classifier_pipeline_choice]
+        SpeciesClassifier = PIPELINE_CHOICES[species_classifier_pipeline_choice]
         species_classifier_instance = SpeciesClassifier(source_images=[], detections=[])
         SpeciesClassifierResponse = make_algorithm_response(species_classifier_instance)
 
@@ -99,7 +99,7 @@ def test_pipeline_config_with_binary_classifier(self):
     def test_processing_with_only_binary_classifier(self):
         binary_classifier_pipeline_choice = "moth_binary"
         binary_algorithm_key = "moth_nonmoth_classifier"
-        BinaryAlgorithmClass = CLASSIFIER_CHOICES[binary_classifier_pipeline_choice]
+        BinaryAlgorithmClass = PIPELINE_CHOICES[binary_classifier_pipeline_choice]
         # Create an instance to get the num_classes
         binary_algorithm = BinaryAlgorithmClass(source_images=[], detections=[])
 
@@ -231,3 +231,78 @@ def test_config_num_classification_predictions(self):
                 f"Number of logits ({len(classification.logits)}) should equal "
                 f"number of classes ({num_classes})"
             )
+
+    def test_existing_pipelines_default_to_apimothdetector(self):
+        """Pre-existing pipelines must keep using APIMothDetector.
+
+        New pipelines introduced with their own detector are exempt.
+        """
+        from trapdata.api.api import PIPELINE_CHOICES
+        from trapdata.api.models.localization import APIMothDetector
+
+        exempt = {"mothbot_insect_orders_2025"}
+        for slug, Classifier in PIPELINE_CHOICES.items():
+            if slug in exempt:
+                continue
+            self.assertIs(
+                Classifier.detector_cls,
+                APIMothDetector,
+                f"{slug} should default to APIMothDetector",
+            )
+
+    def test_mothbot_pipeline_uses_yolo_detector(self):
+        from trapdata.api.api import PIPELINE_CHOICES
+        from trapdata.api.models.localization import APIMothDetector_YOLO11m_Mothbot
+
+        assert "mothbot_insect_orders_2025" in PIPELINE_CHOICES
+        Classifier = PIPELINE_CHOICES["mothbot_insect_orders_2025"]
+        self.assertIs(Classifier.detector_cls, APIMothDetector_YOLO11m_Mothbot)
+
+    def test_mothbot_pipeline_skips_binary_filter(self):
+        from trapdata.api.api import PIPELINE_CHOICES, should_filter_detections
+
+        Classifier = PIPELINE_CHOICES["mothbot_insect_orders_2025"]
+        self.assertFalse(should_filter_detections(Classifier))
+
+    def test_detection_response_has_optional_rotation_field(self):
+        """The rotation field is opt-in for detectors that produce OBB."""
+        import datetime
+
+        from trapdata.api.schemas import (
+            AlgorithmReference,
+            BoundingBox,
+            DetectionResponse,
+        )
+
+        # Default: rotation is None
+        d = DetectionResponse(
+            source_image_id="img1",
+            bbox=BoundingBox(x1=0, y1=0, x2=10, y2=10),
+            algorithm=AlgorithmReference(name="x", key="x"),
+            timestamp=datetime.datetime.now(),
+        )
+        self.assertIsNone(d.rotation)
+
+        # Accepts a float
+        d2 = DetectionResponse(
+            source_image_id="img1",
+            bbox=BoundingBox(x1=0, y1=0, x2=10, y2=10),
+            algorithm=AlgorithmReference(name="x", key="x"),
+            timestamp=datetime.datetime.now(),
+            rotation=-42.5,
+        )
+        self.assertAlmostEqual(d2.rotation, -42.5)
+
+    def test_yolo_api_detector_instantiates(self):
+        """The new YOLO detector wrapper should construct with no source images
+        (matches the pattern the /info handler uses to read algorithm metadata).
+
+        This test exercises weight download + model load — it will be slow on
+        first run but cached thereafter.
+        """
+        from trapdata.api.models.localization import APIMothDetector_YOLO11m_Mothbot
+
+        detector = APIMothDetector_YOLO11m_Mothbot(source_images=[])
+        self.assertEqual(detector.name, "Mothbot YOLO11m Creature Detector")
+        self.assertEqual(detector.category_map, {0: "creature"})
+        self.assertEqual(detector.imgsz, 1600)