NABat Export Annotations (#173)

* inital export commit

* add regular export, swapt o csv + json files

* exporting migrations, task update

* basic exporting working

* add celery periodic task

* add celery periodic task

* rename nabat export task function

Author: BryonLewis

bats_ai/api.py

@@ -5,6 +5,7 @@
 
 from bats_ai.core.views import (
     ConfigurationRouter,
+    ExportAnnotationRouter,
     GRTSCellsRouter,
     GuanoMetadataRouter,
     ProcessingTaskRouter,
@@ -38,6 +39,7 @@ def global_auth(request):
 api.add_router('/grts/', GRTSCellsRouter)
 api.add_router('/guano/', GuanoMetadataRouter)
 api.add_router('/recording-annotation/', RecordingAnnotationRouter)
+api.add_router('/export-annotation/', ExportAnnotationRouter)
 api.add_router('/configuration/', ConfigurationRouter)
 api.add_router('/processing-task/', ProcessingTaskRouter)
 api.add_router('/nabat/recording/', NABatRecordingRouter)

bats_ai/core/admin/__init__.py

@@ -1,6 +1,7 @@
 from .annotations import AnnotationsAdmin
 from .compressed_spectrogram import CompressedSpectrogramAdmin
 from .configuration import ConfigurationAdmin
+from .exported_annotation import ExportedAnnotationFileAdmin
 from .grts_cells import GRTSCellsAdmin
 from .image import ImageAdmin
 from .nabat.admin import (
@@ -28,6 +29,7 @@
     'RecordingAnnotationAdmin',
     'ProcessingTaskAdmin',
     'ConfigurationAdmin',
+    'ExportedAnnotationFileAdmin',
     # NABat Models
     'NABatRecordingAnnotationAdmin',
     'NABatCompressedSpectrogramAdmin',

bats_ai/core/admin/exported_annotation.py

@@ -0,0 +1,37 @@
+from django.contrib import admin
+
+from bats_ai.core.models import ExportedAnnotationFile
+
+
+@admin.register(ExportedAnnotationFile)
+class ExportedAnnotationFileAdmin(admin.ModelAdmin):
+    list_display = (
+        'id',
+        'file',
+        'download_url',
+        'status',
+        'expires_at',
+        'created',
+        'modified',
+    )
+    list_filter = ('status', 'created', 'modified', 'expires_at')
+    search_fields = ('download_url', 'file')
+    ordering = ('-created',)
+    readonly_fields = ('created', 'modified')
+
+    fieldsets = (
+        (None, {'fields': ('file', 'download_url', 'status', 'expires_at')}),
+        (
+            'Filters Applied',
+            {
+                'classes': ('collapse',),
+                'fields': ('filters_applied',),
+            },
+        ),
+        (
+            'Timestamps',
+            {
+                'fields': ('created', 'modified'),
+            },
+        ),
+    )

bats_ai/core/migrations/0018_exportedannotationfile.py

@@ -0,0 +1,55 @@
+# Generated by Django 4.1.13 on 2025-06-03 18:07
+
+from django.db import migrations, models
+import django_extensions.db.fields
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('core', '0017_configuration_default_color_scheme_and_more'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ExportedAnnotationFile',
+            fields=[
+                (
+                    'id',
+                    models.BigAutoField(
+                        auto_created=True, primary_key=True, serialize=False, verbose_name='ID'
+                    ),
+                ),
+                (
+                    'created',
+                    django_extensions.db.fields.CreationDateTimeField(
+                        auto_now_add=True, verbose_name='created'
+                    ),
+                ),
+                (
+                    'modified',
+                    django_extensions.db.fields.ModificationDateTimeField(
+                        auto_now=True, verbose_name='modified'
+                    ),
+                ),
+                ('file', models.FileField(upload_to='exports/')),
+                ('download_url', models.URLField(blank=True, max_length=2048, null=True)),
+                ('filters_applied', models.JSONField(blank=True, null=True)),
+                ('expires_at', models.DateTimeField()),
+                (
+                    'status',
+                    models.CharField(
+                        choices=[
+                            ('pending', 'Pending'),
+                            ('complete', 'Complete'),
+                            ('failed', 'Failed'),
+                        ],
+                        default='pending',
+                        max_length=32,
+                    ),
+                ),
+            ],
+            options={
+                'ordering': ['-created'],
+            },
+        ),
+    ]

bats_ai/core/models/__init__.py

@@ -1,6 +1,7 @@
 from .annotations import Annotations
 from .compressed_spectrogram import CompressedSpectrogram
 from .configuration import Configuration
+from .exported_file import ExportedAnnotationFile
 from .grts_cells import GRTSCells
 from .image import Image
 from .processing_task import ProcessingTask, ProcessingTaskType
@@ -26,4 +27,5 @@
     'Configuration',
     'ProcessingTask',
     'ProcessingTaskType',
+    'ExportedAnnotationFile',
 ]

bats_ai/core/models/exported_file.py

@@ -0,0 +1,27 @@
+from django.db import models
+from django.dispatch import receiver
+from django_extensions.db.models import TimeStampedModel
+
+
+class ExportedAnnotationFile(TimeStampedModel):
+    file = models.FileField(upload_to='exports/')
+    download_url = models.URLField(blank=True, null=True, max_length=2048)
+    filters_applied = models.JSONField(
+        blank=True,
+        null=True,
+    )
+    expires_at = models.DateTimeField()
+    status = models.CharField(
+        max_length=32,
+        choices=[('pending', 'Pending'), ('complete', 'Complete'), ('failed', 'Failed')],
+        default='pending',
+    )
+
+    class Meta:
+        ordering = ['-created']
+
+
+@receiver(models.signals.pre_delete, sender=ExportedAnnotationFile)
+def delete_content(sender, instance, **kwargs):
+    if instance.file:
+        instance.file.delete(save=False)

bats_ai/core/views/__init__.py

@@ -1,5 +1,6 @@
 from .annotations import router as AnnotationRouter
 from .configuration import router as ConfigurationRouter
+from .export_annotation import router as ExportAnnotationRouter
 from .grts_cells import router as GRTSCellsRouter
 from .guanometadata import router as GuanoMetadataRouter
 from .processing_tasks import router as ProcessingTaskRouter
@@ -18,4 +19,5 @@
     'RecordingAnnotationRouter',
     'ConfigurationRouter',
     'ProcessingTaskRouter',
+    'ExportAnnotationRouter',
 ]

bats_ai/core/views/export_annotation.py

@@ -0,0 +1,66 @@
+from datetime import datetime
+import logging
+
+from django.http import JsonResponse
+from django.shortcuts import get_object_or_404
+from ninja import Router
+from pydantic import BaseModel
+
+from bats_ai.core.models import ExportedAnnotationFile
+
+logger = logging.getLogger(__name__)
+
+router = Router()
+
+
+class ExportedAnnotationFileSchema(BaseModel):
+    id: int
+    status: str
+    downloadUrl: str | None
+    created: datetime
+    expiresAt: datetime | None
+
+    class Config:
+        orm_mode = True
+
+
+@router.get('/', response=list[ExportedAnnotationFileSchema])
+def list_exports(request):
+    exports = ExportedAnnotationFile.objects.order_by('-created')
+    return [
+        ExportedAnnotationFileSchema(
+            id=e.id,
+            status=e.status,
+            downloadUrl=e.download_url if e.status == 'complete' else None,
+            created=e.created,
+            expiresAt=e.expires_at,
+        )
+        for e in exports
+    ]
+
+
+@router.get('/{export_id}', response=ExportedAnnotationFileSchema)
+def get_export_status(request, export_id: int):
+    export = get_object_or_404(ExportedAnnotationFile, pk=export_id)
+    return ExportedAnnotationFileSchema(
+        id=export.id,
+        status=export.status,
+        downloadUrl=export.download_url if export.status == 'complete' else None,
+        created=export.created,
+        expiresAt=export.expires_at,
+    )
+
+
+@router.delete('/{export_id}')
+def delete_export(request, export_id: int):
+    export = get_object_or_404(ExportedAnnotationFile, pk=export_id)
+
+    # Optional: block deleting exports still in progress
+    if export.status not in ('complete', 'failed', 'expired'):
+        return JsonResponse(
+            {'error': 'Cannot delete an export that is still in progress.'},
+            status=400,
+        )
+
+    export.delete()
+    return JsonResponse({'success': True})

bats_ai/core/views/nabat/nabat_configuration.py

@@ -1,4 +1,4 @@
-from datetime import datetime
+from datetime import date, datetime, timedelta
 import json
 import logging
 from typing import Any, Literal
@@ -8,11 +8,13 @@
 from django.contrib.gis.geos import Point, Polygon
 from django.db.models import Count
 from django.http import HttpRequest, JsonResponse
+from django.utils.timezone import now
 from ninja import Query, Router, Schema
 from ninja.pagination import paginate
 
-from bats_ai.core.models import ProcessingTask, ProcessingTaskType
+from bats_ai.core.models import ExportedAnnotationFile, ProcessingTask, ProcessingTaskType
 from bats_ai.core.models.nabat import NABatRecording, NABatRecordingAnnotation
+from bats_ai.tasks.nabat.nabat_export_task import export_nabat_annotations_task
 from bats_ai.tasks.nabat.nabat_update_species import update_nabat_species
 
 logger = logging.getLogger(__name__)
@@ -194,3 +196,25 @@ def get_stats(request: HttpRequest):
         'total_recordings': total_recordings,
         'total_annotations': total_annotations,
     }
+
+
+class AnnotationExportRequest(Schema):
+    start_date: date | None = None
+    end_date: date | None = None
+    recording_ids: list[int] | None = None
+    usernames: list[str] | None = None
+    min_confidence: float | None = None
+    max_confidence: float | None = None
+
+
+@router.post(
+    '/export',
+)
+def export_annotations(request: HttpRequest, filters: AnnotationExportRequest):
+    export = ExportedAnnotationFile.objects.create(
+        filters_applied=filters.dict(),
+        status='pending',
+        expires_at=now() + timedelta(hours=24),
+    )
+    export_nabat_annotations_task.delay(filters.dict(), export.id)
+    return export.id

bats_ai/settings.py

@@ -26,6 +26,13 @@ class BatsAiMixin(ConfigMixin):
     ]
     CELERY_RESULT_BACKEND = 'django-db'
 
+    CELERY_BEAT_SCHEDULE = {
+        'delete-expired-exported-files-daily': {
+            'task': 'bats_ai.tasks.periodic.delete_expired_exported_files',
+            'schedule': 86400,  # every 24 hours (in seconds)
+        },
+    }
+
     @staticmethod
     def mutate_configuration(configuration: ComposedConfiguration) -> None:
         # Install local apps first, to ensure any overridden resources are found first