import math import secrets from django.conf import settings from django.contrib.auth.hashers import check_password, make_password from django.core.exceptions import ValidationError from django.core.files.storage import default_storage from django.db import models, transaction from django.utils import timezone from django.utils.translation import gettext_lazy as _ class Sensor(models.Model): """A physical recorder authorised to submit audio to the device API.""" name = models.CharField(max_length=100, unique=True, help_text=_("A recognisable device name, e.g. Garden ESP32.")) owner = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True, on_delete=models.SET_NULL, related_name="sensors") is_active = models.BooleanField(default=True) archived_at = models.DateTimeField(null=True, blank=True, editable=False) token_prefix = models.CharField(max_length=15, blank=True, editable=False) token_hash = models.CharField(max_length=256, blank=True, editable=False) last_heartbeat = models.DateTimeField(null=True, blank=True, editable=False) last_submission = models.DateTimeField(null=True, blank=True, editable=False) created_at = models.DateTimeField(auto_now_add=True) class Meta: ordering = ["name"] def __str__(self): return self.name def issue_token(self): """Return a secret once; only a salted password hash is persisted.""" token = f"ss_{secrets.token_urlsafe(32)}" self.token_prefix = token[:15] self.token_hash = make_password(token) self.save(update_fields=["token_prefix", "token_hash"]) return token def token_matches(self, token): return bool(self.token_hash) and check_password(token, self.token_hash) def heartbeat_status(self): if not self.last_heartbeat: return "never", _("Never seen") age = (timezone.now() - self.last_heartbeat).total_seconds() if age <= 300: return "online", _("Online") if age <= 900: return "delayed", _("Delayed") return "offline", _("Offline") def archive(self): self.archived_at = timezone.now() self.is_active = False self.token_hash = "" self.token_prefix = "" self.save(update_fields=["archived_at", "is_active", "token_hash", "token_prefix"]) def record_heartbeat(self, submission=False): now = timezone.now() self.last_heartbeat = now fields = ["last_heartbeat"] if submission: self.last_submission = now fields.append("last_submission") self.save(update_fields=fields) class ClassificationRule(models.Model): """A configurable inclusion or exclusion rule for a classification label.""" class RuleType(models.TextChoices): WHITELIST = "whitelist", _("Whitelist") BLACKLIST = "blacklist", _("Blacklist") value = models.CharField(max_length=255) rule_type = models.CharField(max_length=10, choices=RuleType.choices) enabled = models.BooleanField(default=True) class Meta: ordering = ["value"] constraints = [ models.UniqueConstraint(fields=["value", "rule_type"], name="unique_classification_rule"), ] def __str__(self): return f"{self.value} ({self.get_rule_type_display()})" class BrowserProcessingSettings(models.Model): """Single site-wide switch for experimental browser processing.""" browser_processing_beta_enabled = models.BooleanField(default=False) class Meta: verbose_name = _("Browser-side media processing (Beta)") verbose_name_plural = _("Browser-side media processing (Beta)") def save(self, *args, **kwargs): self.pk = 1 return super().save(*args, **kwargs) @classmethod def enabled(cls): return bool(cls.objects.filter(pk=1).values_list("browser_processing_beta_enabled", flat=True).first()) def __str__(self): return str(_("Browser-side media processing (Beta)")) class ClassifiedAudio(models.Model): """Shared fields for a classifier response and its original audio upload.""" class SourceType(models.TextChoices): SENSOR = "sensor", _("Sensor") MANUAL = "manual", _("Manual report") audio_file = models.FileField(upload_to="fireworks_audio/%Y/%m/%d", blank=True) sensor = models.ForeignKey(Sensor, null=True, blank=True, on_delete=models.SET_NULL, related_name="%(class)s_records") original_filename = models.CharField(max_length=255) classifier_response = models.JSONField() source_type = models.CharField(max_length=10, choices=SourceType.choices, default=SourceType.SENSOR) occurrences = models.PositiveIntegerField(default=1) location = models.CharField(max_length=255, blank=True) latitude = models.DecimalField(max_digits=9, decimal_places=6, null=True, blank=True) longitude = models.DecimalField(max_digits=9, decimal_places=6, null=True, blank=True) h3_cell = models.CharField(max_length=20, blank=True, db_index=True) visually_confirmed = models.BooleanField(default=False) direction_degrees = models.FloatField(null=True, blank=True) direction_accuracy_degrees = models.FloatField(null=True, blank=True) direction_source = models.CharField(max_length=32, blank=True) created_at = models.DateTimeField(auto_now_add=True) class Meta: abstract = True ordering = ["-created_at"] def __str__(self): return self.original_filename def clean(self): super().clean() errors = {} if self.direction_degrees is not None and ( not math.isfinite(self.direction_degrees) or not 0 <= self.direction_degrees < 360 ): errors["direction_degrees"] = _("Direction must be a finite value from 0 up to, but not including, 360 degrees.") if self.direction_accuracy_degrees is not None and ( not math.isfinite(self.direction_accuracy_degrees) or self.direction_accuracy_degrees < 0 ): errors["direction_accuracy_degrees"] = _("Compass accuracy must be a finite, non-negative value.") if errors: raise ValidationError(errors) @property def direction_cardinal(self): if self.direction_degrees is None: return None directions = ("N", "NE", "E", "SE", "S", "SW", "W", "NW") return directions[int((self.direction_degrees + 22.5) % 360 // 45)] @property def direction_display(self): if self.direction_degrees is None: return "—" return f"{self.direction_degrees:g}° ({self.direction_cardinal})" @property def predictions(self): predictions = self.classifier_response.get("predictions", []) return predictions if isinstance(predictions, list) else [] @property def primary_prediction(self): return self.predictions[0] if self.predictions else {} @property def primary_label(self): return self.primary_prediction.get("class", _("No prediction")) @property def primary_score(self): try: return f"{float(self.primary_prediction.get('score', 0)) * 100:.1f}%" except (TypeError, ValueError): return "—" @property def duration(self): return self.classifier_response.get("duration_seconds", "—") def _preview_items(self, key): preview = [] for item in self.classifier_response.get(key, []): label = str(item.get("class", "Unknown")) lowered = label.lower() kind = "speech" if any(term in lowered for term in ("speech", "conversation", "narration", "monologue", "whisper")) else "firework" if any(term in lowered for term in ("firework", "firecracker", "explosion", "bang", "boom", "hiss", "crackle")) else "default" preview.append({**item, "label": label, "kind": kind, "score_display": f"{float(item.get('score', 0)) * 100:.1f}%"}) return preview @property def admin_predictions(self): return self._preview_items("predictions") @property def admin_peaks(self): return self._preview_items("peak_predictions") @property def admin_audio_route(self): return "fireworks_detect:pending_audio" if self._meta.model_name == "pendingevent" else "fireworks_detect:event_audio" class PendingEvent(ClassifiedAudio): """A submitted classification awaiting a human review in Django admin.""" class Meta(ClassifiedAudio.Meta): verbose_name = _("Pending event") verbose_name_plural = _("Pending") @transaction.atomic def approve(self): event = Event.objects.create( audio_file=self.audio_file.name, sensor=self.sensor, original_filename=self.original_filename, classifier_response=self.classifier_response, source_type=self.source_type, occurrences=self.occurrences, location=self.location, latitude=self.latitude, longitude=self.longitude, h3_cell=self.h3_cell, visually_confirmed=self.visually_confirmed, direction_degrees=self.direction_degrees, direction_accuracy_degrees=self.direction_accuracy_degrees, direction_source=self.direction_source, ) self.delete() return event def deny(self): file_name = self.audio_file.name self.delete() if file_name: default_storage.delete(file_name) class Event(ClassifiedAudio): """A reviewed classification that is safe to appear in the event feed.""" approved_at = models.DateTimeField(auto_now_add=True) class Meta(ClassifiedAudio.Meta): verbose_name = _("Event") verbose_name_plural = _("Events")