Make it possible to add tags to taxa (#892)

* Add support for Taxa Tags (#830)

* feat: added support for tag creation for a given taxon

* chore: moved Tag<->Taxon many2many to the Taxon model

* feat: added the Tag admin model

* feat: added custom assign_tags action to the TaxonViewSet to assign tags for a given taxon and return the assigned tags filtered by project

* fixed formatting

* merged migrations

* feat: added tags to the Taxon admin model

* feat: added global tags

* added db migration

* feat: show global tags if there is an active project

* feat: added or based taxon filtering by tag_id

* chore: renamed TaxonTagFilterBackend

* fix: fixed filtering tags by project_id in the TaxonViewSet list

* Add frontend support for taxa tags (#828)

* feat: setup UI for taxon tags

* feat: prepare UI controls for tag filtering

* feat: hook up UI tags with backend

* fix: update filter key from tag -> tag_id

* fixed Taxon List tags column name

* feat: added tags inverse filter

* feat: return global tags with project tags

* chore: reset tag migrations, add default tags

* fix: remove invalid field in taxa list query

* chore: add type hints for reverse relationships

---------

Co-authored-by: Anna Viklund <annamariaviklund@gmail.com>
Co-authored-by: Michael Bunsen <notbot@gmail.com>

* chore: remove unused import

* fix: pass project ID when assigning tags

* chore: skip adding initial tags to the database

* fix: update migration deps

* fix: revert caption update to fix build

* feat: put tags feature behind feature flag

* feat: disable tag filters if no tags for project

* chore: fix migration ordering

* feat: store feature flags with project

* fix: return feature flags as a dictionary in API response

* style: simplify tags form

---------

Co-authored-by: Mohamed Elabbas <hack1996man@gmail.com>
Co-authored-by: Michael Bunsen <notbot@gmail.com>

Author: 3 people

ami/main/admin.py

@@ -26,6 +26,7 @@
     Site,
     SourceImage,
     SourceImageCollection,
+    Tag,
     TaxaList,
     Taxon,
 )
@@ -77,7 +78,18 @@ def save_related(self, request, form, formsets, change):
     inlines = [ProjectPipelineConfigInline]
 
     fieldsets = (
-        (None, {"fields": ("name", "description", "priority", "active")}),
+        (
+            None,
+            {
+                "fields": (
+                    "name",
+                    "description",
+                    "priority",
+                    "active",
+                    "feature_flags",
+                )
+            },
+        ),
         (
             "Ownership & Access",
             {
@@ -455,6 +467,7 @@ class TaxonAdmin(admin.ModelAdmin[Taxon]):
         "rank",
         "parent",
         "parent_names",
+        "tag_list",
         "list_names",
         "created_at",
         "updated_at",
@@ -475,10 +488,10 @@ def get_queryset(self, request):
 
         return qs.annotate(occurrence_count=models.Count("occurrences")).order_by("-occurrence_count")
 
-    @admin.display(
-        description="Occurrences",
-        ordering="occurrence_count",
-    )
+    @admin.display(description="Tags")
+    def tag_list(self, obj) -> str:
+        return ", ".join([tag.name for tag in obj.tags.all()])
+
     def occurrence_count(self, obj) -> int:
         return obj.occurrence_count
 
@@ -596,3 +609,10 @@ def populate_collection_async(self, request: HttpRequest, queryset: QuerySet[Sou
 
     # Hide images many-to-many field from form. This would list all source images in the database.
     exclude = ("images",)
+
+
+@admin.register(Tag)
+class TagAdmin(admin.ModelAdmin):
+    list_display = ("id", "name", "project")
+    list_filter = ("project",)
+    search_fields = ("name",)

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 create_source_image_from_upload
+from ami.main.models import Tag, create_source_image_from_upload
 from ami.ml.models import Algorithm
 from ami.ml.serializers import AlgorithmSerializer
 from ami.users.models import User
@@ -274,14 +274,21 @@ class Meta:
 
 class ProjectSerializer(DefaultSerializer):
     deployments = DeploymentNestedSerializerWithLocationAndCounts(many=True, read_only=True)
+    feature_flags = serializers.SerializerMethodField()
     owner = UserNestedSerializer(read_only=True)
 
+    def get_feature_flags(self, obj):
+        if obj.feature_flags:
+            return obj.feature_flags.dict()
+        return {}
+
     class Meta:
         model = Project
         fields = ProjectListSerializer.Meta.fields + [
             "deployments",
             "summary_data",  # @TODO move to a 2nd request, it's too slow
             "owner",
+            "feature_flags",
         ]
 
 
@@ -497,11 +504,32 @@ class Meta:
         ]
 
 
+class TagSerializer(DefaultSerializer):
+    project = ProjectNestedSerializer(read_only=True)
+    project_id = serializers.PrimaryKeyRelatedField(queryset=Project.objects.all(), source="project", write_only=True)
+    taxa_ids = serializers.PrimaryKeyRelatedField(
+        queryset=Taxon.objects.all(), many=True, source="taxa", write_only=True, required=False
+    )
+    taxa = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Tag
+        fields = ["id", "name", "project", "project_id", "taxa_ids", "taxa"]
+
+    def get_taxa(self, obj):
+        return [{"id": taxon.id, "name": taxon.name} for taxon in obj.taxa.all()]
+
+
 class TaxonListSerializer(DefaultSerializer):
     # latest_detection = DetectionNestedSerializer(read_only=True)
     occurrences = serializers.SerializerMethodField()
     parents = TaxonNestedSerializer(read_only=True)
     parent_id = serializers.PrimaryKeyRelatedField(queryset=Taxon.objects.all(), source="parent")
+    tags = serializers.SerializerMethodField()
+
+    def get_tags(self, obj):
+        tag_list = getattr(obj, "prefetched_tags", [])
+        return TagSerializer(tag_list, many=True, context=self.context).data
 
     class Meta:
         model = Taxon
@@ -514,6 +542,7 @@ class Meta:
             "details",
             "occurrences_count",
             "occurrences",
+            "tags",
             "last_detected",
             "best_determination_score",
             "created_at",
@@ -718,6 +747,12 @@ 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")
+    tags = serializers.SerializerMethodField()
+
+    def get_tags(self, obj):
+        # Use prefetched tags
+        tag_list = getattr(obj, "prefetched_tags", [])
+        return TagSerializer(tag_list, many=True, context=self.context).data
 
     class Meta:
         model = Taxon
@@ -733,6 +768,7 @@ class Meta:
             "events_count",
             "occurrences",
             "gbif_taxon_key",
+            "tags",
             "last_detected",
             "best_determination_score",
         ]

ami/main/api/views.py

@@ -42,6 +42,7 @@
 )
 from ami.base.serializers import FilterParamsSerializer, SingleParamSerializer
 from ami.base.views import ProjectMixin
+from ami.main.api.serializers import TagSerializer
 from ami.utils.requests import get_active_classification_threshold, project_id_doc_param
 from ami.utils.storages import ConnectionTestResult
 
@@ -61,6 +62,7 @@
     SourceImage,
     SourceImageCollection,
     SourceImageUpload,
+    Tag,
     TaxaList,
     Taxon,
     User,
@@ -1158,6 +1160,29 @@ def filter_queryset(self, request, queryset, view):
 TaxonBestScoreFilter = ThresholdFilter.create("best_determination_score")
 
 
+class TaxonTagFilter(filters.BaseFilterBackend):
+    """FilterBackend that allows OR-based filtering of taxa by tag ID."""
+
+    def filter_queryset(self, request, queryset, view):
+        tag_ids = request.query_params.getlist("tag_id")
+        if tag_ids:
+            queryset = queryset.filter(tags__id__in=tag_ids).distinct()
+        return queryset
+
+
+class TagInverseFilter(filters.BaseFilterBackend):
+    """
+    Exclude taxa that have any of the specified tag IDs using `not_tag_id`.
+    Example: /api/v2/taxa/?not_tag_id=1&not_tag_id=2
+    """
+
+    def filter_queryset(self, request, queryset, view):
+        not_tag_ids = request.query_params.getlist("not_tag_id")
+        if not_tag_ids:
+            queryset = queryset.exclude(tags__id__in=not_tag_ids)
+        return queryset.distinct()
+
+
 class TaxonViewSet(DefaultViewSet, ProjectMixin):
     """
     API endpoint that allows taxa to be viewed or edited.
@@ -1170,6 +1195,8 @@ class TaxonViewSet(DefaultViewSet, ProjectMixin):
         TaxonCollectionFilter,
         TaxonTaxaListFilter,
         TaxonBestScoreFilter,
+        TaxonTagFilter,
+        TagInverseFilter,
     ]
     filterset_fields = [
         "name",
@@ -1294,6 +1321,7 @@ def get_queryset(self) -> QuerySet:
         """
         qs = super().get_queryset()
         project = self.get_active_project()
+        qs = self.attach_tags_by_project(qs, project)
 
         if project:
             # Allow showing detail views for unobserved taxa
@@ -1377,6 +1405,43 @@ def get_taxa_observed(self, qs: QuerySet, project: Project, include_unobserved=F
             )
         return qs
 
+    def attach_tags_by_project(self, qs: QuerySet, project: Project) -> QuerySet:
+        """
+        Prefetch and override the `.tags` attribute on each Taxon
+        with only the tags belonging to the given project.
+        """
+        # Include all tags if no project is passed
+        if project is None:
+            tag_qs = Tag.objects.all()
+        else:
+            # Prefetch only the tags that belong to the project or are global
+            tag_qs = Tag.objects.filter(models.Q(project=project) | models.Q(project__isnull=True))
+
+        tag_prefetch = Prefetch("tags", queryset=tag_qs, to_attr="prefetched_tags")
+
+        return qs.prefetch_related(tag_prefetch)
+
+    @action(detail=True, methods=["post"])
+    def assign_tags(self, request, pk=None):
+        """
+        Assign tags to a taxon
+        """
+        taxon = self.get_object()
+        tag_ids = request.data.get("tag_ids")
+        logger.info(f"Tag IDs: {tag_ids}")
+        if not isinstance(tag_ids, list):
+            return Response({"detail": "tag_ids must be a list of IDs."}, status=status.HTTP_400_BAD_REQUEST)
+
+        tags = Tag.objects.filter(id__in=tag_ids)
+        logger.info(f"Tags: {tags}, len: {len(tags)}")
+        taxon.tags.set(tags)  # replaces all tags for this taxon
+        taxon.save()
+        logger.info(f"Tags after assingment : {len(taxon.tags.all())}")
+        return Response(
+            {"taxon_id": taxon.id, "assigned_tag_ids": [tag.pk for tag in tags]},
+            status=status.HTTP_200_OK,
+        )
+
     @extend_schema(parameters=[project_id_doc_param])
     def list(self, request, *args, **kwargs):
         return super().list(request, *args, **kwargs)
@@ -1395,6 +1460,20 @@ def get_queryset(self):
     serializer_class = TaxaListSerializer
 
 
+class TagViewSet(DefaultViewSet, ProjectMixin):
+    queryset = Tag.objects.all()
+    serializer_class = TagSerializer
+    filterset_fields = ["taxa"]
+
+    def get_queryset(self):
+        qs = super().get_queryset()
+        project = self.get_active_project()
+        if project:
+            # Filter by project, but also include global tags
+            return qs.filter(models.Q(project=project) | models.Q(project__isnull=True))
+        return qs
+
+
 class ClassificationViewSet(DefaultViewSet, ProjectMixin):
     """
     API endpoint for viewing and adding classification results from a model.

ami/main/migrations/0061_tag_taxon_tags.py

@@ -0,0 +1,40 @@
+# Generated by Django 4.2.10 on 2025-05-15 21:23
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("main", "0060_alter_sourceimagecollection_method"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Tag",
+            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)),
+                ("name", models.CharField(max_length=255)),
+                (
+                    "project",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="tags",
+                        to="main.project",
+                    ),
+                ),
+            ],
+            options={
+                "unique_together": {("name", "project")},
+            },
+        ),
+        migrations.AddField(
+            model_name="taxon",
+            name="tags",
+            field=models.ManyToManyField(blank=True, related_name="taxa", to="main.tag"),
+        ),
+    ]

ami/main/migrations/0062_project_feature_flags.py

@@ -0,0 +1,21 @@
+# Generated by Django 4.2.10 on 2025-07-28 19:05
+
+import ami.main.models
+from django.db import migrations
+import django_pydantic_field.fields
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("main", "0061_tag_taxon_tags"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="project",
+            name="feature_flags",
+            field=django_pydantic_field.fields.PydanticSchemaField(
+                blank=True, config=None, default={"tags": False}, schema=ami.main.models.ProjectFeatureFlags
+            ),
+        ),
+    ]