[Draft] Add project-based representative occurrence for Taxon

ami/main/api/serializers.py

@@ -9,7 +9,7 @@
 from ami.base.fields import DateStringField
 from ami.base.serializers import DefaultSerializer, MinimalNestedModelSerializer, get_current_user, reverse_with_params
 from ami.jobs.models import Job
-from ami.main.models import Tag, create_source_image_from_upload
+from ami.main.models import Tag, create_source_image_from_upload, get_media_url
 from ami.ml.models import Algorithm
 from ami.ml.serializers import AlgorithmSerializer
 from ami.users.models import User
@@ -25,18 +25,27 @@
     Occurrence,
     Page,
     Project,
+    ProjectTaxon,
     S3StorageSource,
     Site,
     SourceImage,
     SourceImageCollection,
     SourceImageUpload,
     TaxaList,
     Taxon,
-    get_media_url,
     validate_filename_timestamp,
 )
 
 
+def build_image_entry(path, title, caption=None):
+    url = get_media_url(path) if path else None
+    return {
+        "title": title,
+        "caption": caption,
+        "sizes": {"original": url if url else None},
+    }
+
+
 class ProjectNestedSerializer(DefaultSerializer):
     class Meta:
         model = Project
@@ -449,6 +458,16 @@ def get_occurrences(self, obj):
         )
 
 
+class ProjectTaxonNestedSerializer(DefaultSerializer):
+    class Meta:
+        model = ProjectTaxon
+        fields = [
+            "id",
+            # "project_id",
+            # "featured_occcurence_id",
+        ]
+
+
 class TaxonNoParentNestedSerializer(DefaultSerializer):
     class Meta:
         model = Taxon
@@ -521,9 +540,35 @@ class TaxonListSerializer(DefaultSerializer):
     occurrences = serializers.SerializerMethodField()
     parents = TaxonParentSerializer(many=True, read_only=True, source="parents_json")
     parent_id = serializers.PrimaryKeyRelatedField(queryset=Taxon.objects.all(), source="parent")
-    cover_image_url = serializers.SerializerMethodField()
+    featured_occurrences = serializers.SerializerMethodField()
+    images = serializers.SerializerMethodField()
+    cover_image_url = serializers.SerializerMethodField()  # Deprecated, use images instead @TODO
     tags = serializers.SerializerMethodField()
 
+    def get_images(self, obj):
+        images = {
+            "external_reference": build_image_entry(
+                obj.cover_image_url, "External reference image", obj.cover_image_credit
+            ),
+            "most_recently_featured": build_image_entry(
+                getattr(obj, "featured_detection_path", None),
+                "Featured occurrence",
+            ),
+            "highest_determination_score": build_image_entry(
+                getattr(obj, "highest_score_detection_path", None),
+                "Most confident prediction",
+            ),
+        }
+
+        return images
+
+    def get_featured_occurrences(self, obj):
+        """
+        Return the prefetched featured occurrences attached via `to_attr="prefetched_featured_occurrences"`.
+        """
+        featured = getattr(obj, "prefetched_featured_occurrences", [])
+        return TaxonOccurrenceNestedSerializer(featured, many=True, context=self.context).data
+
     def get_tags(self, obj):
         tag_list = getattr(obj, "prefetched_tags", [])
         return TagSerializer(tag_list, many=True, context=self.context).data
@@ -539,13 +584,15 @@ class Meta:
             "details",
             "occurrences_count",
             "occurrences",
+            "featured_occurrences",
             "tags",
             "last_detected",
             "best_determination_score",
             "cover_image_url",
             "unknown_species",
             "created_at",
             "updated_at",
+            "images",
         ]
 
     def get_occurrences(self, obj):
@@ -758,9 +805,44 @@ class TaxonSerializer(DefaultSerializer):
     parent = TaxonNoParentNestedSerializer(read_only=True)
     parent_id = serializers.PrimaryKeyRelatedField(queryset=Taxon.objects.all(), source="parent", write_only=True)
     parents = TaxonParentSerializer(many=True, read_only=True, source="parents_json")
-    cover_image_url = serializers.SerializerMethodField()
+    featured_occurrences = serializers.SerializerMethodField()
+    images = serializers.SerializerMethodField()
+    cover_image_url = serializers.SerializerMethodField()  # Deprecated, use images instead @TODO
     tags = serializers.SerializerMethodField()
 
+    def get_images(self, obj):
+        images = {
+            "external_reference": build_image_entry(
+                obj.cover_image_url, "External reference image", obj.cover_image_credit
+            ),
+            "most_recently_featured": build_image_entry(
+                getattr(obj, "featured_detection_path", None),
+                "Featured occurrence",
+            ),
+            "highest_determination_score": build_image_entry(
+                getattr(obj, "highest_score_detection_path", None),
+                "Most confident prediction",
+            ),
+        }
+
+        return images
+
+    def get_featured_occurrences(self, obj):
+        """
+        Return a list of featured occurrences from prefetched featured occurrences.
+        """
+        featured = [occ for occ in getattr(obj, "prefetched_featured_occurrences", [])]
+        return TaxonOccurrenceNestedSerializer(featured, many=True, context=self.context).data
+
+    def _get_best_detection_image_url(self, occurrence):
+        """
+        Given an occurrence, return the public URL of its best detection's source image.
+        """
+        detection = getattr(occurrence, "best_detection", None)
+        if detection and detection.source_image:
+            return detection.source_image.public_url
+        return None
+
     def get_tags(self, obj):
         # Use prefetched tags
         tag_list = getattr(obj, "prefetched_tags", [])
@@ -785,7 +867,11 @@ class Meta:
             "fieldguide_id",
             "cover_image_url",
             "cover_image_credit",
+            "featured_occurrences",
+            # "featured_detection_image_url",
             "unknown_species",
+            "last_detected",  # @TODO this has performance impact, review
+            "images",
         ]
 
     def get_cover_image_url(self, obj):
@@ -1281,6 +1367,7 @@ class Meta:
             "first_appearance_time",
             "duration",
             "duration_label",
+            "featured",
             "determination",
             "detections_count",
             "detection_images",

ami/main/api/views.py

@@ -1127,6 +1127,49 @@ def get_queryset(self) -> QuerySet["Occurrence"]:
 
         return qs
 
+    @action(detail=True, methods=["post", "delete"], url_path="feature")
+    def feature(self, request, pk=None):
+        """
+        Set this occurrence as the representative example for its taxon in the current project.
+        """
+        occurrence = self.get_object()
+        if not occurrence:
+            return Response({"detail": "This occurrence does not exist."}, status=status.HTTP_404_NOT_FOUND)
+
+        # Ensure the occurrence has a determination (taxon)
+        taxon = occurrence.determination
+        if not taxon:
+            return Response(
+                {"detail": "This occurrence has no taxon assigned (determination)."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Ensure the occurrence is assigned to a project
+        project = occurrence.project
+        if not project:
+            return Response(
+                {"detail": "This occurrence is not associated with any project."}, status=status.HTTP_400_BAD_REQUEST
+            )
+
+        # Get or create the ProjectTaxon entry
+        try:
+            # Feature or unfeature the occurrence based on the request method
+            if request.method == "DELETE":
+                # Unfeature the occurrence
+                occurrence.featured = False
+            else:
+                # Feature the occurrence
+                occurrence.featured = True
+            # Set featured at to current date time
+            occurrence.featured_at = timezone.now()
+            occurrence.save(update_determination=False)
+            return Response({"detail": "Representative occurrence updated successfully."}, status=status.HTTP_200_OK)
+
+        except Exception as e:
+            raise e
+            return Response({"detail": f"Error: {str(e)}"}, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+
+    @extend_schema(parameters=[project_id_doc_param])
     @extend_schema(
         parameters=[
             project_id_doc_param,
@@ -1372,7 +1415,10 @@ def get_queryset(self) -> QuerySet:
 
         if project:
             include_unobserved = True  # Show detail views for unobserved taxa instead of 404
-            # @TODO move to a QuerySet manager
+            qs = qs.with_featured_occurrences(project=project)  # type: ignore
+            qs = qs.with_example_image_paths(project=project)
+
+            # @TODO deprecated in favor of with_example_image_paths
             qs = qs.annotate(
                 best_detection_image_path=models.Subquery(
                     Occurrence.objects.filter(
@@ -1384,6 +1430,7 @@ def get_queryset(self) -> QuerySet:
                     output_field=models.TextField(),
                 )
             )
+
             if self.action == "list":
                 include_unobserved = self.request.query_params.get("include_unobserved", False)
             qs = self.get_taxa_observed(qs, project, include_unobserved=include_unobserved)

ami/main/migrations/0067_tag_taxon_tags.py → ami/main/migrations/0066_tag_taxon_tags.py

@@ -27,7 +27,7 @@ def add_inital_tags(apps, schema_editor):
 
 class Migration(migrations.Migration):
     dependencies = [
-        ("main", "0066_populate_cached_occurence_fields"),
+        ("main", "0065_detection_favorite_occurrence_best_detection_and_more"),
     ]
 
     operations = [

ami/main/migrations/0067_rename_favorite_detection_featured_and_more.py

@@ -0,0 +1,90 @@
+# Generated by Django 4.2.10 on 2025-05-16 16:14
+
+from django.db import migrations, models
+import django.db.models.deletion
+import pgvector.django.vector
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("ml", "0023_alter_algorithm_task_type"),
+        ("main", "0066_tag_taxon_tags"),
+    ]
+
+    operations = [
+        migrations.RenameField(
+            model_name="detection",
+            old_name="favorite",
+            new_name="featured",
+        ),
+        migrations.AddField(
+            model_name="detection",
+            name="featured_at",
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name="occurrence",
+            name="featured",
+            field=models.BooleanField(default=False, help_text="Use this occurrence to represent a Taxon in the UI"),
+        ),
+        migrations.AddField(
+            model_name="occurrence",
+            name="featured_at",
+            field=models.DateTimeField(
+                blank=True, help_text="The date and time this occurrence was featured", null=True
+            ),
+        ),
+        migrations.AlterField(
+            model_name="taxon",
+            name="projects",
+            field=models.ManyToManyField(blank=True, related_name="taxa", to="main.project"),
+        ),
+        migrations.CreateModel(
+            name="ProjectTaxon",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "mean_feature_vector",
+                    pgvector.django.vector.VectorField(
+                        default=None,
+                        dimensions=2048,
+                        help_text="Cluster center for this taxon in this project",
+                        null=True,
+                    ),
+                ),
+                (
+                    "featured_detection",
+                    models.ForeignKey(
+                        blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to="main.detection"
+                    ),
+                ),
+                (
+                    "featured_occcurence",
+                    models.ForeignKey(
+                        blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to="main.occurrence"
+                    ),
+                ),
+                (
+                    "mean_feature_vector_algorithm",
+                    models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, to="ml.algorithm"),
+                ),
+                (
+                    "project",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE, related_name="project_taxa", to="main.project"
+                    ),
+                ),
+                (
+                    "taxon",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE, related_name="project_taxa", to="main.taxon"
+                    ),
+                ),
+            ],
+            options={
+                "unique_together": {("taxon", "project")},
+            },
+        ),
+    ]