fix(ml): create null detection markers only after real saves succeed

Issue #1310: null detections (empty-bbox sentinels marking "image processed,
nothing found") were created before create_detections / create_classifications /
create_and_update_occurrences_for_detections ran. Two consequences:

1. If any of those downstream steps failed, the image was already flagged as
   processed via the null marker — filter_processed_images would skip it on the
   next run, leaving the image permanently in a "processed but no detections"
   state. Observed on project 171 (400 captures with only null detections).
2. create_and_update_occurrences_for_detections iterated every detection
   including nulls, so each null marker spawned a phantom Occurrence with
   determination=NULL.

Fix in ami/ml/models/pipeline.py save_results:
- Run create_detections / create_classifications / create_and_update_occurrences
  on the real DetectionResponses only.
- After those succeed, build null DetectionResponses for images that ended up
  without any detections and persist them via a second create_detections call.
- Null responses never enter the classification / occurrence loops, so no
  phantom Occurrence is created even in the happy path.

Tests in ami/ml/tests.py TestPipeline:
- test_null_detection_does_not_create_phantom_occurrence: asserts the happy
  path "pipeline found nothing" creates the null marker but no Occurrence.
- test_captures_not_marked_processed_after_failure: asserts that when a
  downstream step (create_classifications) raises, the image without a real
  detection is left unmarked and filter_processed_images re-yields it.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: mihow

ami/ml/models/pipeline.py

@@ -952,15 +952,6 @@ def save_results(
             "Algorithms and category maps must be registered before processing, using /info endpoint."
         )
 
-    # Ensure all images have detections
-    # if not, add a NULL detection (empty bbox) to the results
-    null_detections = create_null_detections_for_undetected_images(
-        results=results,
-        detection_algorithm=detection_algorithm,
-        logger=job_logger,
-    )
-    results.detections = results.detections + null_detections
-
     detections = create_detections(
         detections=results.detections,
         algorithms_known=algorithms_known,
@@ -981,6 +972,22 @@ def save_results(
         logger=job_logger,
     )
 
+    # Mark images with no real detections as processed by creating null-bbox sentinels.
+    # Issue #1310: must run AFTER the real-detection / classification / occurrence steps
+    # so a failure earlier in the pipeline leaves the image unmarked (and therefore
+    # re-processed by filter_processed_images on the next run). Null DetectionResponses
+    # are kept out of the real-detection list so they bypass occurrence creation entirely.
+    null_detection_responses = create_null_detections_for_undetected_images(
+        results=results,
+        detection_algorithm=detection_algorithm,
+        logger=job_logger,
+    )
+    create_detections(
+        detections=null_detection_responses,
+        algorithms_known=algorithms_known,
+        logger=job_logger,
+    )
+
     # Update precalculated counts on source images and events
     source_images = list(source_images)
     logger.info(f"Updating calculated fields for {len(source_images)} source images")

ami/ml/tests.py

@@ -13,6 +13,7 @@
     Deployment,
     Detection,
     Event,
+    Occurrence,
     Project,
     SourceImage,
     SourceImageCollection,
@@ -1024,6 +1025,78 @@ def test_null_detection_deduplication_same_pipeline(self):
         null_detections = image.detections.filter(bbox__isnull=True)
         self.assertEqual(null_detections.count(), 1, "Same pipeline should not create duplicate null detections")
 
+    def test_null_detection_does_not_create_phantom_occurrence(self):
+        """
+        Issue #1310: a null detection (empty-bbox sentinel marking "image processed,
+        nothing found") must NOT spawn an Occurrence. Occurrences with no
+        determination and no real detections leak to the API as ghost rows.
+        """
+        image = self.test_images[0]
+        results = self.fake_pipeline_results([image], self.pipeline)
+        results.detections = []  # pipeline found nothing
+
+        save_results(results)
+
+        null_dets = image.detections.filter(bbox__isnull=True)
+        self.assertEqual(null_dets.count(), 1, "Null marker should still be created")
+        self.assertIsNone(
+            null_dets.first().occurrence,
+            "Null detection must NOT be associated with an Occurrence",
+        )
+        # No phantom Occurrence in DB tied to this image at all
+        phantom_occs = Occurrence.objects.filter(detections__source_image=image, determination__isnull=True)
+        self.assertEqual(
+            phantom_occs.count(),
+            0,
+            "No Occurrence with NULL determination should exist for an image that had no detections",
+        )
+
+    def test_captures_not_marked_processed_after_failure(self):
+        """
+        Issue #1310: null markers should only flag images as processed AFTER all
+        downstream save steps (classifications, occurrences) succeed. If any
+        downstream step raises, the image must remain unmarked so the next run
+        re-processes it.
+
+        Reproduces the field bug where 400 images ended up with null markers but
+        no real detections — created when null-creation ran ahead of a later step
+        that failed.
+        """
+        from unittest.mock import patch
+
+        from ami.ml.models.pipeline import filter_processed_images
+
+        # Mix: image_with_real has a detection in the response, image_without_real does not.
+        # The without-real image is the one that would get a null marker.
+        image_with_real, image_without_real = self.test_images
+        results = self.fake_pipeline_results(self.test_images, self.pipeline)
+        # Trim detections to only the first image so the second qualifies for null-marker creation
+        results.detections = [d for d in results.detections if str(d.source_image_id) == str(image_with_real.pk)]
+
+        # Inject failure in a step that runs AFTER detection bulk_create
+        with patch(
+            "ami.ml.models.pipeline.create_classifications",
+            side_effect=RuntimeError("simulated classification failure"),
+        ):
+            with self.assertRaises(RuntimeError):
+                save_results(results)
+
+        # The image with no real detection must NOT have a null marker —
+        # the run failed, so it should be re-tried.
+        null_dets = image_without_real.detections.filter(bbox__isnull=True)
+        self.assertEqual(
+            null_dets.count(),
+            0,
+            "Image without real detections must not be marked processed when downstream step fails",
+        )
+        # filter_processed_images should still yield it for the next run
+        retry_yield = list(filter_processed_images([image_without_real], self.pipeline))
+        self.assertEqual(
+            retry_yield,
+            [image_without_real],
+            "Image with failed run must be re-yielded for processing",
+        )
+
 
 class TestAlgorithmCategoryMaps(TestCase):
     def setUp(self):