import math import secrets 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 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.") is_active = models.BooleanField(default=True) 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 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 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"