Merge branch 'main' into feat/add-backend-dev-compose-override

# Conflicts:
#	README.md

Author: f-PLT

.envs/.ci/.django

@@ -16,3 +16,6 @@ MINIO_DEFAULT_BUCKET=ami-ci
 MINIO_STORAGE_USE_HTTPS=False
 MINIO_TEST_BUCKET=ami-test-ci
 MINIO_BROWSER_REDIRECT_URL=http://minio:9001
+
+DEFAULT_PROCESSING_SERVICE_NAME=Test Processing Service
+DEFAULT_PROCESSING_SERVICE_ENDPOINT=http://ml_backend:2000

.envs/.local/.django

@@ -37,3 +37,8 @@ MINIO_DEFAULT_BUCKET=ami
 MINIO_STORAGE_USE_HTTPS=False
 MINIO_TEST_BUCKET=ami-test
 MINIO_BROWSER_REDIRECT_URL=http://minio:9001
+
+# Default processing service (local)
+DEFAULT_PROCESSING_SERVICE_NAME=Local Processing Service
+DEFAULT_PROCESSING_SERVICE_ENDPOINT=http://ml_backend:2000
+# DEFAULT_PIPELINES_ENABLED=random,constant  # When set to None, all pipelines will be enabled.

.envs/.production/.django-example

@@ -53,3 +53,8 @@ DJANGO_ACCOUNT_ALLOW_REGISTRATION=True
 # Gunicorn
 # ------------------------------------------------------------------------------
 WEB_CONCURRENCY=4
+
+# Default processing service
+DEFAULT_PROCESSING_SERVICE_NAME="AMI Data Companion"
+DEFAULT_PROCESSING_SERVICE_ENDPOINT=https://ml.antenna.insectai.org/
+DEFAULT_PIPELINES_ENABLED=global_moths_2024,quebec_vermont_moths_2023,panama_moths_2023,uk_denmark_moths_2023

.vscode/launch.json

@@ -0,0 +1,20 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Remote Attach",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "."
+                }
+            ]
+        }
+    ]
+}

README.md

@@ -8,7 +8,7 @@ Platform for processing and reviewing images from automated insect monitoring st
 
 Antenna uses [Docker](https://docs.docker.com/get-docker/) & [Docker Compose](https://docs.docker.com/compose/install/) to run all services locally for development.
 
-1) Install Docker for your host operating (Linux, macOS, Windows)
+1) Install Docker for your host operating (Linux, macOS, Windows). Docker Compose `v2.38.2` or later recommended.
 
 2) Add the following to your `/etc/hosts` file in order to see and process the demo source images. This makes the hostname `minio` and `django` alias for `localhost` so the same image URLs can be viewed in the host machine's web browser and be processed by the ML services. This can be skipped if you are using an external image storage service.
 
@@ -25,6 +25,9 @@ Antenna uses [Docker](https://docs.docker.com/get-docker/) & [Docker Compose](ht
       # To stream the logs
       docker compose logs -f django celeryworker ui
       # Ctrl+c to close the logs
+
+      NOTE: If you see docker build errors such as `At least one invalid signature was encountered`, these could happen if docker runs out of space. Commands like `docker image prune -f` and `docker system prune` can be helpful to clean up space.
+
       ```
       To update the UI Docker container, use the following command to rebuild the frontend and load the new changes
       (and remember to refresh your browser after!).
@@ -49,12 +52,15 @@ docker compose -f processing_services/example/docker-compose.yml up -d
 # Once running, in Antenna register a new processing service called: http://ml_backend_example:2000
 ```
 
-5) Access the platform the following URLs:
+5) Access the platform with the following URLs:
 
 - Primary web interface: http://localhost:4000
 - API browser: http://localhost:8000/api/v2/
 - Django admin: http://localhost:8000/admin/
 - OpenAPI / Swagger documentation: http://localhost:8000/api/v2/docs/
+- Minio UI: http://minio:9001, Minio service: http://minio:9000
+
+NOTE: If one of these services is not working properly, it could be due another process is using the port. You can check for this with `lsof -i :<PORT_NUMBER>`.
 
 A default user will be created with the following credentials. Use these to log into the web UI or the Django admin.
 

ami/base/filters.py

@@ -1,5 +1,6 @@
 from django.db.models import F, OrderBy
-from rest_framework.filters import OrderingFilter
+from django.forms import FloatField
+from rest_framework.filters import BaseFilterBackend, OrderingFilter
 
 
 class NullsLastOrderingFilter(OrderingFilter):
@@ -8,3 +9,56 @@ def get_ordering(self, request, queryset, view):
         if not values:
             return values
         return [OrderBy(F(value.lstrip("-")), descending=value.startswith("-"), nulls_last=True) for value in values]
+
+
+class ThresholdFilter(BaseFilterBackend):
+    """
+    Filter a numeric field by a minimum value.
+
+    Usage:
+
+    Filter occurrences by their determination score:
+    GET /occurrences/?score=0.5
+    This will return all occurrences with a determination score greater than or equal to 0.5.
+
+    Customize the query_param and filter_param to match your API and model fields using
+    the create method.
+
+    Example:
+
+    DeterminationScoreFilter = ThresholdFilter.create(
+        query_param="classification_threshold",
+        filter_param="determination_score",
+    )
+    OODScoreFilter = ThresholdFilter.create("determination_ood_score")
+
+    class OccurrenceViewSet(DefaultViewSet):
+        filter_backends = DefaultViewSetMixin.filter_backends + [
+            DeterminationScoreFilter,
+            OODScoreFilter,
+        ]
+    """
+
+    query_param = "score"
+    filter_param = "score"
+
+    def filter_queryset(self, request, queryset, view):
+        value = FloatField(required=False).clean(request.query_params.get(self.query_param))
+        if value:
+            filters = {f"{self.filter_param}__gte": value}
+            queryset = queryset.filter(**filters)
+        return queryset
+
+    @classmethod
+    def create(cls, query_param: str, filter_param: str | None = None) -> type["ThresholdFilter"]:
+        class_name = f"{cls.__name__}_{query_param}"
+        if filter_param is None:
+            filter_param = query_param
+        return type(
+            class_name,
+            (cls,),
+            {
+                "query_param": query_param,
+                "filter_param": filter_param,
+            },
+        )

ami/base/models.py

@@ -1,4 +1,6 @@
+from django.contrib.auth.models import AbstractUser, AnonymousUser
 from django.db import models
+from guardian.shortcuts import get_perms
 
 import ami.tasks
 
@@ -29,5 +31,94 @@ def update_calculated_fields(self, *args, **kwargs):
         """Update calculated fields specific to each model."""
         pass
 
+    def _get_object_perms(self, user):
+        """
+        Get the object-level permissions for the user on this instance.
+        This method retrieves permissions like `update_modelname`, `create_modelname`, etc.
+        """
+        project = self.get_project()
+        if not project:
+            return []
+
+        model_name = self._meta.model_name
+        all_perms = get_perms(user, project)
+        object_perms = [perm for perm in all_perms if perm.endswith(f"_{model_name}")]
+        return object_perms
+
+    def check_permission(self, user: AbstractUser | AnonymousUser, action: str) -> bool:
+        """
+        Check if the user has permission to perform the action
+        on this instance.
+        This method is used to determine if the user can perform
+        CRUD operations or custom actions on the model instance.
+        """
+        project = self.get_project() if hasattr(self, "get_project") else None
+        if not project:
+            return False
+        if action == "retrieve":
+            # Allow view
+            return True
+
+        model = self._meta.model_name
+        crud_map = {
+            "create": f"create_{model}",
+            "update": f"update_{model}",
+            "partial_update": f"update_{model}",
+            "destroy": f"delete_{model}",
+        }
+
+        if action in crud_map:
+            return user.has_perm(crud_map[action], project)
+
+        # Delegate to model-specific logic
+        return self.check_custom_permission(user, action)
+
+    def check_custom_permission(self, user: AbstractUser | AnonymousUser, action: str) -> bool:
+        """Check custom permissions for the user on this instance.
+        This is used for actions that are not standard CRUD operations.
+        """
+        assert self._meta.model_name is not None, "Model must have a model_name defined in Meta class."
+        model_name = self._meta.model_name.lower()
+        permission_codename = f"{action}_{model_name}"
+        project = self.get_project() if hasattr(self, "get_project") else None
+
+        return user.has_perm(permission_codename, project)
+
+    def get_user_object_permissions(self, user) -> list[str]:
+        """
+        Returns a list of object-level permissions the user has on this instance.
+        This is used by frontend to determine what actions the user can perform.
+        """
+        # Return all permissions for superusers
+        if user.is_superuser:
+            allowed_custom_actions = self.get_custom_user_permissions(user)
+            return ["update", "delete"] + allowed_custom_actions
+
+        object_perms = self._get_object_perms(user)
+        # Check for update and delete permissions
+        allowed_actions = set()
+        for perm in object_perms:
+            action = perm.split("_", 1)[0]
+            if action in {"update", "delete"}:
+                allowed_actions.add(action)
+
+        allowed_custom_actions = self.get_custom_user_permissions(user)
+        allowed_actions.update(set(allowed_custom_actions))
+        return list(allowed_actions)
+
+    def get_custom_user_permissions(self, user: AbstractUser | AnonymousUser) -> list[str]:
+        """
+        Returns a list of custom permissions (not standard CRUD actions) that the user has on this instance.
+        """
+        object_perms = self._get_object_perms(user)
+        custom_perms = set()
+        # Extract custom permissions that are not standard CRUD actions
+        for perm in object_perms:
+            action = perm.split("_", 1)[0]
+            # Make sure to exclude standard CRUD actions
+            if action not in ["view", "create", "update", "delete"]:
+                custom_perms.add(action)
+        return list(custom_perms)
+
     class Meta:
         abstract = True