feat: Always Include Species filter; cap image attribution

- Add an "Always Include Species" list (Settings → Species Filter) that
  reports listed species even when the location filter rates them
  unlikely for the configured coordinates
- Cap bird image attribution to a single line

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Suncuss

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+- Added an "Always Include Species" list (Settings → Species Filter) that reports the listed species even when the location filter rates them unlikely for your coordinates
+
 ## [0.7.4] - 2026-05-31
 
 - Bird Gallery tab switches now show a loading spinner while an uncached tab's query runs, instead of leaving the previous tab's cards on screen until the (sometimes slow) query resolves. Revisiting a recently viewed tab is still instant and shows its cached cards while refreshing in the background

backend/config/settings.py

@@ -28,7 +28,8 @@ def _get_positive_int_env(name: str, default: int) -> int:
     "detection": {"sensitivity": 0.75, "cutoff": 0.60, "species_filter_threshold": DEFAULT_SPECIES_FILTER_THRESHOLD},
     "species_filter": {
         "allowed_species": [],   # If non-empty, ONLY detect these (bypasses location filter)
-        "blocked_species": []    # Never detect these species
+        "blocked_species": [],   # Never detect these species
+        "included_species": []   # Always detect these, even if the location filter excludes them
     },
     "audio": {
         "sources": [],

backend/model_service/inference_server.py

@@ -272,6 +272,7 @@ def process_audio_file(
     recording_length: float,
     allowed_species: list[str] | None,
     blocked_species: list[str] | None,
+    included_species: list[str] | None = None,
     species_filter_threshold: float = DEFAULT_SPECIES_FILTER_THRESHOLD
 ):
     """Process an audio file and return detected species.
@@ -283,6 +284,10 @@ def process_audio_file(
         lat, lon: Location coordinates for species filtering
         sensitivity: Confidence adjustment parameter
         cutoff: Minimum confidence threshold
+        allowed_species: If non-empty, detect ONLY these (bypasses location filter)
+        blocked_species: Never detect these (always wins)
+        included_species: Always detect these, even when the location filter
+            would exclude them (no effect while allowed_species is set)
 
     Returns:
         List of detection result dictionaries
@@ -349,6 +354,7 @@ def process_audio_file(
     # Normalize optional filter lists
     allowed_species = allowed_species or []
     blocked_species = blocked_species or []
+    included_species = included_species or []
 
     # Pre-compute loop-invariant values
     loc_active = location_context.source != 'disabled'
@@ -429,6 +435,10 @@ def process_audio_file(
                 filtered_species_list.append(species_detection)
             elif species_label in location_context.allowed_species:
                 filtered_species_list.append(species_detection)
+            elif included_species and scientific_name in included_species:
+                # Always-include list: keep despite low local probability
+                logger.debug("Species force-included", extra={'species': scientific_name})
+                filtered_species_list.append(species_detection)
             else:
                 logger.debug("Species not in local species list", extra={'species': scientific_name})
 
@@ -533,6 +543,7 @@ def analyze_audio_file():
         recording_length = audio_settings.get('recording_length', 9)
         allowed_species = species_filter_settings.get('allowed_species') or []
         blocked_species = species_filter_settings.get('blocked_species') or []
+        included_species = species_filter_settings.get('included_species') or []
 
         requested_model_type = runtime_settings.get('model', {}).get('type', settings.MODEL_TYPE)
         if requested_model_type != settings.MODEL_TYPE:
@@ -564,6 +575,7 @@ def analyze_audio_file():
             recording_length,
             allowed_species,
             blocked_species,
+            included_species,
             species_filter_threshold
         )
 

backend/tests/api/test_bird_image_api.py

@@ -609,6 +609,7 @@ def fake_get(url, params=None, headers=None, timeout=None):
     def test_candidates_surfaces_429_with_retry_after(self, candidates_client):
         """A 429 from Wikimedia becomes a structured error with status + Retry-After."""
         import requests as _requests
+
         from core import api as api_module
         api_module.image_cache.clear()
 
@@ -631,6 +632,7 @@ def test_concurrent_misses_share_one_upstream_fetch(self, candidates_client):
         """Single-flight: two concurrent cache-misses for the same key do one fetch."""
         import threading as _threading
         import time as _time
+
         from core import api as api_module
         api_module.image_cache.clear()
         api_module._wikimedia_inflight.clear()

backend/tests/audio/test_audio_manager.py

@@ -18,13 +18,14 @@
 import pytest
 
 from core.audio_manager import (
-    BaseRecorder,
-    PulseAudioRecorder,
     RTSP_PROBE_TIMEOUT_SECONDS,
     RTSP_SOCKET_TIMEOUT_US,
+    BaseRecorder,
+    PulseAudioRecorder,
     RtspRecorder,
     create_recorder,
 )
+
 # Aliased on import: the source name starts with "test_", so importing it
 # under that name makes pytest try to collect it as a test case.
 from core.audio_manager import test_stream_url as probe_stream_url

backend/tests/model_service/test_api_contract.py

@@ -247,7 +247,8 @@ def test_returns_empty_results_on_input_shape_mismatch(self, monkeypatch, caplog
                 overlap=0.0,
                 recording_length=9.0,
                 allowed_species=[],
-                blocked_species=[]
+                blocked_species=[],
+                included_species=[]
             )
 
         assert results == []
@@ -256,3 +257,118 @@ def test_returns_empty_results_on_input_shape_mismatch(self, monkeypatch, caplog
             "Skipping audio file due to model input shape mismatch" in record.message
             for record in caplog.records
         )
+
+
+class TestSpeciesFilterRules:
+    """Test the 3-tier species filter: blocked > allowed-whitelist > location+include.
+
+    The candidate species (a Scaly-breasted Munia) is acoustically detected but
+    excluded by the location filter — exactly the case the always-include list
+    is for. American Robin stands in for "what the location filter does allow".
+    """
+
+    MUNIA = "Lonchura punctulata_Scaly-breasted Munia"
+    MUNIA_SCI = "Lonchura punctulata"
+    ROBIN = "Turdus migratorius_American Robin"
+
+    def _detected_names(
+        self,
+        monkeypatch,
+        *,
+        allowed_species,
+        blocked_species,
+        included_species,
+        location_allows,
+        candidate_label=MUNIA,
+    ):
+        """Run process_audio_file with one detected candidate and return the
+        scientific names that survive filtering."""
+        from model_service import inference_server
+        from model_service.base_model import ChunkPrediction
+        from model_service.location_filter import LocationContext
+
+        model = MagicMock()
+        model.name = "birdnet"
+        model.version = "2.4"
+        model.sample_rate = 48000
+        model.chunk_length_seconds = 3.0
+        model.get_ebird_code.return_value = "lobmun"
+        model.predict_chunk.return_value = ChunkPrediction(
+            raw_top3=((candidate_label, 0.9),),
+            candidates=((candidate_label, 0.9),),
+        )
+
+        # Location filter is active but does NOT allow the candidate species.
+        location_filter = MagicMock()
+        location_filter.filter.return_value = LocationContext(
+            source="meta_model_v2.4",
+            threshold=0.03,
+            allowed_species=frozenset(location_allows),
+            probabilities={},
+        )
+
+        monkeypatch.setattr(
+            inference_server,
+            "split_audio",
+            lambda *args, **kwargs: [np.zeros(144000, dtype=np.float32)],
+        )
+
+        results = inference_server.process_audio_file(
+            model=model,
+            location_filter=location_filter,
+            audio_file_path="/tmp/20240615_103000.wav",
+            lat=29.76,
+            lon=-95.37,
+            sensitivity=0.75,
+            cutoff=0.60,
+            overlap=0.0,
+            recording_length=9.0,
+            allowed_species=allowed_species,
+            blocked_species=blocked_species,
+            included_species=included_species,
+        )
+        return [r["scientific_name"] for r in results]
+
+    def test_included_species_overrides_location_filter(self, monkeypatch):
+        """A species the location filter excludes is kept when always-included."""
+        names = self._detected_names(
+            monkeypatch,
+            allowed_species=[],
+            blocked_species=[],
+            included_species=[self.MUNIA_SCI],
+            location_allows={self.ROBIN},
+        )
+        assert names == [self.MUNIA_SCI]
+
+    def test_dropped_without_include(self, monkeypatch):
+        """Control: the same species is dropped when not always-included."""
+        names = self._detected_names(
+            monkeypatch,
+            allowed_species=[],
+            blocked_species=[],
+            included_species=[],
+            location_allows={self.ROBIN},
+        )
+        assert names == []
+
+    def test_blocked_beats_included(self, monkeypatch):
+        """Blocked always wins, even over the always-include list."""
+        names = self._detected_names(
+            monkeypatch,
+            allowed_species=[],
+            blocked_species=[self.MUNIA_SCI],
+            included_species=[self.MUNIA_SCI],
+            location_allows={self.ROBIN},
+        )
+        assert names == []
+
+    def test_included_is_noop_under_allowed_whitelist(self, monkeypatch):
+        """An active Allowed whitelist takes precedence; include is inert."""
+        names = self._detected_names(
+            monkeypatch,
+            allowed_species=["Turdus migratorius"],  # whitelist active; munia not on it
+            blocked_species=[],
+            included_species=[self.MUNIA_SCI],
+            location_allows={self.ROBIN},
+        )
+        assert names == []

frontend/src/components/BirdImageModal.vue

@@ -214,18 +214,21 @@
             <div class="mt-4 min-h-[2.5rem] text-sm text-gray-600">
               <p
                 v-if="attributionText"
-                class="leading-snug"
+                class="flex items-baseline leading-snug"
               >
-                {{ attributionText.prefix }}
+                <span class="shrink-0">{{ attributionText.prefix }}&nbsp;</span>
                 <a
                   v-if="attributionText.authorUrl"
                   :href="attributionText.authorUrl"
                   target="_blank"
                   rel="noopener noreferrer"
-                  class="text-blue-600 underline"
+                  class="text-blue-600 underline truncate min-w-0"
                 >{{ attributionText.authorName }}</a>
-                <span v-else>{{ attributionText.authorName }}</span>
-                {{ attributionText.suffix }}
+                <span
+                  v-else
+                  class="truncate min-w-0"
+                >{{ attributionText.authorName }}</span>
+                <span class="shrink-0">{{ attributionText.suffix }}</span>
               </p>
               <p
                 v-else-if="selectedKind === 'reset'"

frontend/src/views/BirdDetails.vue

@@ -73,14 +73,15 @@
             </div>
           </template>
           <template v-else>
-            <p>
-              Photo by <a
+            <p class="flex items-baseline">
+              <span class="shrink-0">Photo by&nbsp;</span>
+              <a
                 :href="birdImageData.authorUrl"
                 target="_blank"
                 rel="noopener noreferrer"
-                class="text-blue-600 underline"
-              >{{
-                birdImageData.authorName }}</a>, licensed under {{ birdImageData.licenseType }}
+                class="text-blue-600 underline truncate min-w-0"
+              >{{ birdImageData.authorName }}</a>
+              <span class="shrink-0">,&nbsp;licensed under {{ birdImageData.licenseType }}</span>
             </p>
           </template>
         </div>

frontend/src/views/BirdGallery.vue

@@ -86,7 +86,7 @@
               <p>Uploaded by you</p>
             </template>
             <template v-else>
-              <p>
+              <p class="truncate">
                 Photo by <a
                   :href="bird.authorUrl"
                   target="_blank"