jrrribeiro commited on
Commit
b17d8d1
·
1 Parent(s): ed91682

feat: deploy latest local validation UX and demo audio fallback to Spaces

Browse files
src/services/audio_fetch_service.py CHANGED
@@ -1,5 +1,9 @@
1
  from dataclasses import dataclass
 
 
2
  from pathlib import Path
 
 
3
 
4
  from huggingface_hub import hf_hub_download
5
 
@@ -20,13 +24,27 @@ class AudioFetchService:
20
  def __init__(self, cache_manager: EphemeralCacheManager) -> None:
21
  self._cache = cache_manager
22
 
23
- def fetch(self, dataset_repo: str, audio_id: str) -> AudioFetchResult:
24
  cache_key = f"{dataset_repo}:{audio_id}"
25
  cached_path = self._cache.get(cache_key)
26
  if cached_path:
27
  return AudioFetchResult(cache_key=cache_key, local_path=str(cached_path), source="cache")
28
 
29
- target_filename, downloaded_path = self._resolve_remote_filename(dataset_repo=dataset_repo, audio_id=audio_id)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
30
  if downloaded_path is None:
31
  downloaded = hf_hub_download(repo_id=dataset_repo, repo_type="dataset", filename=target_filename)
32
  downloaded_path = Path(downloaded)
@@ -81,3 +99,35 @@ class AudioFetchService:
81
  continue
82
 
83
  raise FileNotFoundError(f"Unable to locate audio file for audio_id: {audio_id}")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  from dataclasses import dataclass
2
+ import io
3
+ import math
4
  from pathlib import Path
5
+ import struct
6
+ import wave
7
 
8
  from huggingface_hub import hf_hub_download
9
 
 
24
  def __init__(self, cache_manager: EphemeralCacheManager) -> None:
25
  self._cache = cache_manager
26
 
27
+ def fetch(self, dataset_repo: str, audio_id: str, allow_demo_fallback: bool = False) -> AudioFetchResult:
28
  cache_key = f"{dataset_repo}:{audio_id}"
29
  cached_path = self._cache.get(cache_key)
30
  if cached_path:
31
  return AudioFetchResult(cache_key=cache_key, local_path=str(cached_path), source="cache")
32
 
33
+ if allow_demo_fallback and self._is_seeded_demo_audio_id(audio_id):
34
+ fallback_bytes = self._build_demo_fallback_wav(audio_id=audio_id)
35
+ local_path = self._cache.put_bytes(cache_key, fallback_bytes, suffix=".wav")
36
+ return AudioFetchResult(cache_key=cache_key, local_path=str(local_path), source="demo-fallback")
37
+
38
+ try:
39
+ target_filename, downloaded_path = self._resolve_remote_filename(dataset_repo=dataset_repo, audio_id=audio_id)
40
+ except FileNotFoundError:
41
+ if not allow_demo_fallback:
42
+ raise
43
+
44
+ fallback_bytes = self._build_demo_fallback_wav(audio_id=audio_id)
45
+ local_path = self._cache.put_bytes(cache_key, fallback_bytes, suffix=".wav")
46
+ return AudioFetchResult(cache_key=cache_key, local_path=str(local_path), source="demo-fallback")
47
+
48
  if downloaded_path is None:
49
  downloaded = hf_hub_download(repo_id=dataset_repo, repo_type="dataset", filename=target_filename)
50
  downloaded_path = Path(downloaded)
 
99
  continue
100
 
101
  raise FileNotFoundError(f"Unable to locate audio file for audio_id: {audio_id}")
102
+
103
+ def _build_demo_fallback_wav(self, audio_id: str, duration_seconds: float = 4.0, sample_rate: int = 16000) -> bytes:
104
+ """Generate a short deterministic tone when demo audio files are missing."""
105
+ frame_count = max(1, int(duration_seconds * sample_rate))
106
+
107
+ # Derive deterministic frequencies from audio_id so each fallback sounds distinct.
108
+ seed = sum(ord(ch) for ch in audio_id) % 200
109
+ f1 = 440.0 + float(seed)
110
+ f2 = f1 + 180.0
111
+
112
+ with io.BytesIO() as buffer:
113
+ with wave.open(buffer, "wb") as wav_file:
114
+ wav_file.setnchannels(1)
115
+ wav_file.setsampwidth(2)
116
+ wav_file.setframerate(sample_rate)
117
+
118
+ frames = bytearray()
119
+ for i in range(frame_count):
120
+ t = i / float(sample_rate)
121
+ # Blend two sines and apply light envelope to avoid clicks.
122
+ env = min(1.0, i / 400.0, (frame_count - i) / 400.0)
123
+ sample = env * (0.55 * math.sin(2.0 * math.pi * f1 * t) + 0.45 * math.sin(2.0 * math.pi * f2 * t))
124
+ pcm = int(max(-1.0, min(1.0, sample)) * 32767)
125
+ frames.extend(struct.pack("<h", pcm))
126
+
127
+ wav_file.writeframes(bytes(frames))
128
+
129
+ return buffer.getvalue()
130
+
131
+ def _is_seeded_demo_audio_id(self, audio_id: str) -> bool:
132
+ normalized = audio_id.strip().lower()
133
+ return "_audio_" in normalized and normalized.endswith(("1001", "1002", "1003", "1004"))
src/ui/app_factory.py CHANGED
@@ -1,10 +1,15 @@
1
  import gradio as gr
2
  import hashlib
3
  import json
 
 
4
  from datetime import date, datetime
5
  from pathlib import Path
6
  from typing import Protocol
7
 
 
 
 
8
  from src.config.runtime_config import RuntimeConfig
9
  from src.cache.ephemeral_cache_manager import EphemeralCacheManager
10
  from src.domain.models import Detection, Project, Role
@@ -25,7 +30,12 @@ class _AudioFetchResultProtocol(Protocol):
25
 
26
 
27
  class _AudioServiceProtocol(Protocol):
28
- def fetch(self, dataset_repo: str, audio_id: str) -> _AudioFetchResultProtocol: ...
 
 
 
 
 
29
 
30
  def cleanup_after_validation(self, cache_key: str) -> None: ...
31
 
@@ -267,6 +277,7 @@ def _default_projects() -> list[Project]:
267
 
268
  def _default_user_access() -> dict[str, dict[str, Role]]:
269
  return {
 
270
  "admin_user": {"kenya-2024": Role.admin, "nairobi-2023": Role.admin},
271
  "validator_demo": {"demo-project": Role.validator, "kenya-2024": Role.validator},
272
  "validator_other": {"nairobi-2023": Role.validator},
@@ -595,6 +606,7 @@ def _fetch_selected_audio(
595
  rows: object,
596
  selected_index: int,
597
  previous_cache_key: str,
 
598
  ) -> tuple[str | None, str, str]:
599
  repo = dataset_repo.strip()
600
  if not repo:
@@ -602,7 +614,15 @@ def _fetch_selected_audio(
602
 
603
  try:
604
  audio_id = _extract_audio_id(rows=rows, selected_index=selected_index)
605
- result = audio_service.fetch(dataset_repo=repo, audio_id=audio_id)
 
 
 
 
 
 
 
 
606
  status = f"Audio loaded ({result.source}) for audio_id={audio_id}"
607
  return result.local_path, result.cache_key, status
608
  except Exception as exc:
@@ -611,6 +631,343 @@ def _fetch_selected_audio(
611
  return None, "", f"Failed to load audio: {exc}"
612
 
613
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
614
  def _cleanup_selected_audio(audio_service: _AudioServiceProtocol, cache_key: str) -> tuple[str, str | None]:
615
  if not cache_key:
616
  return "No cached audio to clean", None
@@ -629,6 +986,7 @@ def _save_selected_validation(
629
  validator: str,
630
  notes: str,
631
  cache_key: str,
 
632
  ) -> tuple[str, str, str | None]:
633
  validator_name = validator.strip()
634
  if not validator_name:
@@ -643,6 +1001,7 @@ def _save_selected_validation(
643
  status=status_value,
644
  validator=validator_name,
645
  notes=notes.strip(),
 
646
  expected_version=expected_version,
647
  )
648
  if cache_key:
@@ -679,6 +1038,7 @@ def _save_selected_validation_with_refresh(
679
  status_filter: str,
680
  updated_after: object,
681
  show_conflicts_only: bool,
 
682
  ) -> tuple[str, str, str | None, list[list[object]], int, int, str, str]:
683
  selected_key = ""
684
  try:
@@ -696,6 +1056,7 @@ def _save_selected_validation_with_refresh(
696
  validator=validator,
697
  notes=notes,
698
  cache_key=cache_key,
 
699
  )
700
 
701
  refreshed_rows, page_status, refreshed_page = _page_to_table(
@@ -1803,9 +2164,10 @@ def create_app() -> gr.Blocks:
1803
  # ===== TAB 4: Validation =====
1804
  with gr.Tab("✓ Validation", id="validation_tab"):
1805
  validation_status = gr.Markdown(
1806
- value="ℹ️ Login and select a project to start"
 
1807
  )
1808
- queue_badge = gr.HTML(value=_build_queue_badge(service_ref["queue"], None))
1809
  seed_warning_banner = gr.Markdown(value="", visible=False)
1810
 
1811
  def render_seed_warning(warning_text: str):
@@ -1873,71 +2235,121 @@ def create_app() -> gr.Blocks:
1873
  )
1874
 
1875
  gr.Markdown("---")
1876
- dataset_repo = gr.Textbox(label="Dataset repo", interactive=False)
1877
-
1878
- with gr.Row():
1879
- species_filter = gr.Textbox(label="Species filter", placeholder="Ex: Cyanocorax cyanopogon")
1880
- min_confidence = gr.Slider(label="Minimum confidence", minimum=0.0, maximum=1.0, step=0.01, value=0.0)
1881
- show_conflicts_only = gr.Checkbox(label="Show only conflicts", value=False)
1882
-
1883
- with gr.Row():
1884
- validator_filter = gr.Textbox(label="Validator filter", placeholder="Ex: validator-demo")
1885
- validation_status_filter = gr.Dropdown(
1886
- label="Status filter",
1887
- choices=["all", "pending", "positive", "negative", "uncertain", "skip"],
1888
- value="all",
1889
- )
1890
- updated_after_filter = gr.DateTime(label="Updated since", include_time=False, type="string")
1891
-
1892
- with gr.Row():
1893
- prev_btn = gr.Button("Previous page")
1894
- next_btn = gr.Button("Next page")
1895
- refresh_btn = gr.Button("Apply filters")
1896
-
1897
  page_state = gr.State(value=1)
1898
- table = gr.Dataframe(
1899
- headers=[
1900
- "detection_key",
1901
- "audio_id",
1902
- "scientific_name",
1903
- "confidence",
1904
- "start_time",
1905
- "end_time",
1906
- "validation_status",
1907
- "version",
1908
- "conflict_flag",
1909
- "conflict_severity",
1910
- ],
1911
- label="Detections",
1912
- interactive=False,
1913
- )
1914
- selected_index = gr.Number(label="Selected row", value=0, precision=0)
1915
-
1916
- with gr.Row():
1917
- load_audio_btn = gr.Button("Load selected audio")
1918
- clear_audio_btn = gr.Button("Clear cache after validation")
1919
-
1920
- with gr.Row():
1921
- validator_name = gr.Textbox(label="Validator", value="validator-demo")
1922
- validation_notes = gr.Textbox(label="Notes", placeholder="Optional")
 
 
 
 
 
 
1923
 
1924
- with gr.Row():
1925
- approve_btn = gr.Button("Mark positive")
1926
- reject_btn = gr.Button("Mark negative")
1927
- uncertain_btn = gr.Button("Uncertain")
1928
- skip_btn = gr.Button("Skip")
1929
- reapply_btn = gr.Button("Reapply validation after conflict")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1930
 
1931
- with gr.Row():
1932
- batch_approve_conflicts_btn = gr.Button("Approve all conflicts")
1933
- batch_reject_conflicts_btn = gr.Button("Reject all conflicts")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1934
 
1935
- report_btn = gr.Button("Generate validation report")
1936
- audio_player = gr.Audio(label="On-demand audio", type="filepath")
1937
  cache_key_state = gr.State(value="")
1938
  pending_status_state = gr.State(value="")
1939
  conflict_detection_key_state = gr.State(value="")
1940
- status = gr.Textbox(label="Status", interactive=False)
1941
  report_box = gr.Textbox(label="Report", interactive=False)
1942
 
1943
  def refresh(
@@ -1951,13 +2363,17 @@ def create_app() -> gr.Blocks:
1951
  only_conflicts: bool,
1952
  ):
1953
  if not project_slug:
1954
- return [], "Select a project to load the queue", 1
1955
- return _page_to_table(
 
 
 
 
1956
  service=service_ref["queue"],
1957
  snapshot_reader=validation_repository,
1958
  project_slug=project_slug,
1959
  page=page,
1960
- scientific_name=species,
1961
  min_confidence=confidence,
1962
  page_size=runtime_config.page_size,
1963
  validator_filter=validator_filter_value,
@@ -1965,6 +2381,8 @@ def create_app() -> gr.Blocks:
1965
  updated_after=updated_after_value,
1966
  show_conflicts_only=only_conflicts,
1967
  )
 
 
1968
 
1969
  def go_next(
1970
  project_slug: str,
@@ -2009,7 +2427,27 @@ def create_app() -> gr.Blocks:
2009
  )
2010
 
2011
  def refresh_for_selected_project(project_slug: str):
2012
- return refresh(project_slug, 1, "", 0.0, "", "all", "", False)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2013
 
2014
  def save_for_project(
2015
  project_slug: str,
@@ -2018,6 +2456,7 @@ def create_app() -> gr.Blocks:
2018
  idx: int,
2019
  name: str,
2020
  notes: str,
 
2021
  cache_key: str,
2022
  page: int,
2023
  species: str,
@@ -2040,6 +2479,7 @@ def create_app() -> gr.Blocks:
2040
  status_value=status_value,
2041
  validator=name,
2042
  notes=notes,
 
2043
  cache_key=cache_key,
2044
  page=int(page),
2045
  scientific_name=species,
@@ -2131,11 +2571,61 @@ def create_app() -> gr.Blocks:
2131
  return "Select a project to generate report"
2132
  return _build_validation_report(validation_repository, project_slug)
2133
 
2134
- def on_select(evt: gr.SelectData):
2135
- return evt.index[0]
 
 
 
 
 
 
2136
 
2137
- table.select(fn=on_select, inputs=None, outputs=[selected_index])
2138
- refresh_btn.click(
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2139
  fn=refresh,
2140
  inputs=[
2141
  selected_project_state,
@@ -2149,7 +2639,7 @@ def create_app() -> gr.Blocks:
2149
  ],
2150
  outputs=[table, status, page_state],
2151
  )
2152
- next_btn.click(
2153
  fn=go_next,
2154
  inputs=[
2155
  selected_project_state,
@@ -2163,7 +2653,7 @@ def create_app() -> gr.Blocks:
2163
  ],
2164
  outputs=[table, status, page_state],
2165
  )
2166
- prev_btn.click(
2167
  fn=go_prev,
2168
  inputs=[
2169
  selected_project_state,
@@ -2183,37 +2673,144 @@ def create_app() -> gr.Blocks:
2183
  inputs=[selected_dataset_repo_state],
2184
  outputs=[dataset_repo],
2185
  )
2186
- selected_project_state.change(
2187
  fn=refresh_for_selected_project,
2188
  inputs=[selected_project_state],
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2189
  outputs=[table, status, page_state],
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2190
  )
2191
 
2192
  load_audio_btn.click(
2193
- fn=lambda repo, rows, idx, cache_key: _fetch_selected_audio(
2194
  audio_service=audio_service,
2195
  dataset_repo=repo,
2196
  rows=rows,
2197
  selected_index=int(idx),
2198
  previous_cache_key=cache_key,
 
2199
  ),
2200
- inputs=[dataset_repo, table, selected_index, cache_key_state],
2201
- outputs=[audio_player, cache_key_state, status],
2202
  )
2203
  clear_audio_btn.click(
2204
- fn=lambda cache_key: _cleanup_selected_audio(audio_service=audio_service, cache_key=cache_key),
2205
  inputs=[cache_key_state],
2206
- outputs=[status, audio_player],
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2207
  )
2208
 
2209
- approve_btn.click(
2210
- fn=lambda project_slug, rows, idx, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: save_for_project(
 
 
 
 
 
 
2211
  project_slug,
2212
  "positive",
2213
  rows,
2214
  idx,
2215
  name,
2216
  notes,
 
2217
  cache_key,
2218
  page,
2219
  species,
@@ -2229,6 +2826,7 @@ def create_app() -> gr.Blocks:
2229
  selected_index,
2230
  validator_name,
2231
  validation_notes,
 
2232
  cache_key_state,
2233
  page_state,
2234
  species_filter,
@@ -2240,14 +2838,15 @@ def create_app() -> gr.Blocks:
2240
  ],
2241
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2242
  )
2243
- reject_btn.click(
2244
- fn=lambda project_slug, rows, idx, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: save_for_project(
2245
  project_slug,
2246
  "negative",
2247
  rows,
2248
  idx,
2249
  name,
2250
  notes,
 
2251
  cache_key,
2252
  page,
2253
  species,
@@ -2263,6 +2862,7 @@ def create_app() -> gr.Blocks:
2263
  selected_index,
2264
  validator_name,
2265
  validation_notes,
 
2266
  cache_key_state,
2267
  page_state,
2268
  species_filter,
@@ -2274,14 +2874,15 @@ def create_app() -> gr.Blocks:
2274
  ],
2275
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2276
  )
2277
- uncertain_btn.click(
2278
- fn=lambda project_slug, rows, idx, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: save_for_project(
2279
  project_slug,
2280
  "uncertain",
2281
  rows,
2282
  idx,
2283
  name,
2284
  notes,
 
2285
  cache_key,
2286
  page,
2287
  species,
@@ -2297,6 +2898,7 @@ def create_app() -> gr.Blocks:
2297
  selected_index,
2298
  validator_name,
2299
  validation_notes,
 
2300
  cache_key_state,
2301
  page_state,
2302
  species_filter,
@@ -2308,14 +2910,15 @@ def create_app() -> gr.Blocks:
2308
  ],
2309
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2310
  )
2311
- skip_btn.click(
2312
- fn=lambda project_slug, rows, idx, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: save_for_project(
2313
  project_slug,
2314
  "skip",
2315
  rows,
2316
  idx,
2317
  name,
2318
  notes,
 
2319
  cache_key,
2320
  page,
2321
  species,
@@ -2331,6 +2934,7 @@ def create_app() -> gr.Blocks:
2331
  selected_index,
2332
  validator_name,
2333
  validation_notes,
 
2334
  cache_key_state,
2335
  page_state,
2336
  species_filter,
@@ -2342,7 +2946,7 @@ def create_app() -> gr.Blocks:
2342
  ],
2343
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2344
  )
2345
- reapply_btn.click(
2346
  fn=lambda project_slug, rows, idx, pending_status, conflict_key, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: reapply_for_project(
2347
  project_slug,
2348
  rows,
@@ -2380,7 +2984,7 @@ def create_app() -> gr.Blocks:
2380
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2381
  )
2382
 
2383
- batch_approve_conflicts_btn.click(
2384
  fn=lambda project_slug, rows, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value: batch_for_project(
2385
  project_slug,
2386
  rows,
@@ -2410,7 +3014,7 @@ def create_app() -> gr.Blocks:
2410
  ],
2411
  outputs=[status, cache_key_state, audio_player, table, page_state],
2412
  )
2413
- batch_reject_conflicts_btn.click(
2414
  fn=lambda project_slug, rows, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value: batch_for_project(
2415
  project_slug,
2416
  rows,
@@ -2440,6 +3044,62 @@ def create_app() -> gr.Blocks:
2440
  ],
2441
  outputs=[status, cache_key_state, audio_player, table, page_state],
2442
  )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2443
  report_btn.click(
2444
  fn=build_report_for_project,
2445
  inputs=[selected_project_state],
 
1
  import gradio as gr
2
  import hashlib
3
  import json
4
+ import tempfile
5
+ import wave
6
  from datetime import date, datetime
7
  from pathlib import Path
8
  from typing import Protocol
9
 
10
+ import numpy as np
11
+ from PIL import Image
12
+
13
  from src.config.runtime_config import RuntimeConfig
14
  from src.cache.ephemeral_cache_manager import EphemeralCacheManager
15
  from src.domain.models import Detection, Project, Role
 
30
 
31
 
32
  class _AudioServiceProtocol(Protocol):
33
+ def fetch(
34
+ self,
35
+ dataset_repo: str,
36
+ audio_id: str,
37
+ allow_demo_fallback: bool = False,
38
+ ) -> _AudioFetchResultProtocol: ...
39
 
40
  def cleanup_after_validation(self, cache_key: str) -> None: ...
41
 
 
277
 
278
  def _default_user_access() -> dict[str, dict[str, Role]]:
279
  return {
280
+ "demo_user": {"demo-project": Role.validator, "birds-local": Role.validator},
281
  "admin_user": {"kenya-2024": Role.admin, "nairobi-2023": Role.admin},
282
  "validator_demo": {"demo-project": Role.validator, "kenya-2024": Role.validator},
283
  "validator_other": {"nairobi-2023": Role.validator},
 
606
  rows: object,
607
  selected_index: int,
608
  previous_cache_key: str,
609
+ allow_demo_fallback: bool = False,
610
  ) -> tuple[str | None, str, str]:
611
  repo = dataset_repo.strip()
612
  if not repo:
 
614
 
615
  try:
616
  audio_id = _extract_audio_id(rows=rows, selected_index=selected_index)
617
+ try:
618
+ result = audio_service.fetch(
619
+ dataset_repo=repo,
620
+ audio_id=audio_id,
621
+ allow_demo_fallback=allow_demo_fallback,
622
+ )
623
+ except TypeError:
624
+ # Backward compatibility for fake/mocked services used in tests.
625
+ result = audio_service.fetch(dataset_repo=repo, audio_id=audio_id)
626
  status = f"Audio loaded ({result.source}) for audio_id={audio_id}"
627
  return result.local_path, result.cache_key, status
628
  except Exception as exc:
 
631
  return None, "", f"Failed to load audio: {exc}"
632
 
633
 
634
+ def _load_pcm_wave(audio_path: Path) -> tuple[int, np.ndarray]:
635
+ with wave.open(str(audio_path), "rb") as wav_file:
636
+ sample_rate = wav_file.getframerate()
637
+ channels = wav_file.getnchannels()
638
+ sample_width = wav_file.getsampwidth()
639
+ frame_count = wav_file.getnframes()
640
+ raw = wav_file.readframes(frame_count)
641
+
642
+ if sample_width == 1:
643
+ audio = np.frombuffer(raw, dtype=np.uint8).astype(np.float32)
644
+ audio = (audio - 128.0) / 128.0
645
+ elif sample_width == 2:
646
+ audio = np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
647
+ elif sample_width == 4:
648
+ audio = np.frombuffer(raw, dtype=np.int32).astype(np.float32) / 2147483648.0
649
+ else:
650
+ raise ValueError(f"Unsupported PCM width: {sample_width}")
651
+
652
+ if channels > 1:
653
+ audio = audio.reshape(-1, channels).mean(axis=1)
654
+
655
+ return sample_rate, audio
656
+
657
+
658
+ def _magma_like_colormap(normalized: np.ndarray) -> np.ndarray:
659
+ # Lightweight gradient for spectrogram rendering (dark -> orange -> yellow).
660
+ anchors = np.array(
661
+ [
662
+ [0, 0, 4],
663
+ [28, 16, 68],
664
+ [79, 18, 123],
665
+ [129, 37, 129],
666
+ [181, 54, 122],
667
+ [229, 80, 100],
668
+ [251, 135, 97],
669
+ [254, 194, 135],
670
+ [252, 253, 191],
671
+ ],
672
+ dtype=np.float32,
673
+ )
674
+ indices = np.clip((normalized * (len(anchors) - 1)).astype(np.float32), 0, len(anchors) - 1)
675
+ lower = np.floor(indices).astype(np.int32)
676
+ upper = np.clip(lower + 1, 0, len(anchors) - 1)
677
+ blend = (indices - lower)[..., np.newaxis]
678
+ rgb = anchors[lower] * (1.0 - blend) + anchors[upper] * blend
679
+ return rgb.astype(np.uint8)
680
+
681
+
682
+ def _build_spectrogram_image(audio_path: str | None) -> str | None:
683
+ if not audio_path:
684
+ return None
685
+
686
+ source_path = Path(audio_path)
687
+ if not source_path.exists() or source_path.suffix.lower() != ".wav":
688
+ return None
689
+
690
+ try:
691
+ _, samples = _load_pcm_wave(source_path)
692
+ except Exception:
693
+ return None
694
+
695
+ if samples.size < 1024:
696
+ return None
697
+
698
+ window_size = 512
699
+ hop_size = 128
700
+ frame_count = 1 + max(0, (len(samples) - window_size) // hop_size)
701
+ if frame_count <= 0:
702
+ return None
703
+
704
+ frames = np.lib.stride_tricks.sliding_window_view(samples, window_shape=window_size)[::hop_size]
705
+ if frames.size == 0:
706
+ return None
707
+
708
+ window = np.hanning(window_size).astype(np.float32)
709
+ spectrum = np.abs(np.fft.rfft(frames * window, axis=1))
710
+ spectrum = np.maximum(spectrum, 1e-9)
711
+ db = 20.0 * np.log10(spectrum)
712
+ db = db.T
713
+ low = float(np.percentile(db, 5))
714
+ high = float(np.percentile(db, 99))
715
+ if high <= low:
716
+ return None
717
+
718
+ normalized = np.clip((db - low) / (high - low), 0.0, 1.0)
719
+ rgb = _magma_like_colormap(normalized)
720
+ rgb = np.flipud(rgb)
721
+
722
+ image = Image.fromarray(rgb, mode="RGB").resize((900, 320), resample=Image.Resampling.BICUBIC)
723
+ cache_name = hashlib.sha1(f"{audio_path}:{source_path.stat().st_mtime_ns}".encode("utf-8")).hexdigest()[:16]
724
+ output_path = Path(tempfile.gettempdir()) / f"birdnet_validator_spec_{cache_name}.png"
725
+ image.save(output_path)
726
+ return str(output_path)
727
+
728
+
729
+ def _fetch_selected_audio_with_spectrogram(
730
+ audio_service: _AudioServiceProtocol,
731
+ dataset_repo: str,
732
+ rows: object,
733
+ selected_index: int,
734
+ previous_cache_key: str,
735
+ allow_demo_fallback: bool = False,
736
+ ) -> tuple[str | None, str, str, str | None]:
737
+ audio_path, cache_key, status = _fetch_selected_audio(
738
+ audio_service=audio_service,
739
+ dataset_repo=dataset_repo,
740
+ rows=rows,
741
+ selected_index=selected_index,
742
+ previous_cache_key=previous_cache_key,
743
+ allow_demo_fallback=allow_demo_fallback,
744
+ )
745
+ spectrogram_path = _build_spectrogram_image(audio_path)
746
+ if audio_path and spectrogram_path is None:
747
+ status = f"{status} | Spectrogram unavailable (requires WAV)."
748
+ return audio_path, cache_key, status, spectrogram_path
749
+
750
+
751
+ def _build_validation_summary_cards(rows: object) -> str:
752
+ if hasattr(rows, "values"):
753
+ normalized_rows = [list(item) for item in rows.values.tolist()]
754
+ else:
755
+ normalized_rows = [list(item) for item in rows] if rows else []
756
+ total = len(normalized_rows)
757
+ positive = 0
758
+ negative = 0
759
+ for row in normalized_rows:
760
+ status_value = str(row[6]).strip().lower() if len(row) > 6 else ""
761
+ if status_value == "positive":
762
+ positive += 1
763
+ elif status_value == "negative":
764
+ negative += 1
765
+
766
+ return (
767
+ "<div style='display:grid;grid-template-columns:repeat(3,minmax(120px,1fr));gap:12px;margin:4px 0 12px 0;'>"
768
+ f"<div style='padding:10px 14px;border-radius:10px;background:#ececec;'><div style='font-size:12px;color:#555;'>Total</div><div style='font-size:24px;font-weight:700;color:#222;'>{total}</div></div>"
769
+ f"<div style='padding:10px 14px;border-radius:10px;background:#e7f4ea;'><div style='font-size:12px;color:#3f6c49;'>Positivo</div><div style='font-size:24px;font-weight:700;color:#215d2f;'>{positive}</div></div>"
770
+ f"<div style='padding:10px 14px;border-radius:10px;background:#fdeaea;'><div style='font-size:12px;color:#7b3a3a;'>Negativo</div><div style='font-size:24px;font-weight:700;color:#6f1f1f;'>{negative}</div></div>"
771
+ "</div>"
772
+ )
773
+
774
+
775
+ def _autofetch_first_row(
776
+ audio_service: _AudioServiceProtocol,
777
+ dataset_repo: str,
778
+ rows: object,
779
+ cache_key: str,
780
+ allow_demo_fallback: bool = False,
781
+ ) -> tuple[int, str | None, str, str, str | None]:
782
+ normalized_rows = _normalize_rows(rows)
783
+ if not normalized_rows:
784
+ return 0, None, "", "No detections available to auto-load audio", None
785
+
786
+ audio_path, updated_cache_key, status, spectrogram_path = _fetch_selected_audio_with_spectrogram(
787
+ audio_service=audio_service,
788
+ dataset_repo=dataset_repo,
789
+ rows=normalized_rows,
790
+ selected_index=0,
791
+ previous_cache_key=cache_key,
792
+ allow_demo_fallback=allow_demo_fallback,
793
+ )
794
+ return 0, audio_path, updated_cache_key, status, spectrogram_path
795
+
796
+
797
+ def _select_and_fetch_audio(
798
+ audio_service: _AudioServiceProtocol,
799
+ dataset_repo: str,
800
+ rows: object,
801
+ cache_key: str,
802
+ evt: gr.SelectData,
803
+ allow_demo_fallback: bool = False,
804
+ ) -> tuple[int, str | None, str, str, str | None]:
805
+ if isinstance(evt.index, tuple):
806
+ selected_index = int(evt.index[0])
807
+ elif isinstance(evt.index, int):
808
+ selected_index = int(evt.index)
809
+ else:
810
+ selected_index = 0
811
+
812
+ audio_path, updated_cache_key, status, spectrogram_path = _fetch_selected_audio_with_spectrogram(
813
+ audio_service=audio_service,
814
+ dataset_repo=dataset_repo,
815
+ rows=rows,
816
+ selected_index=selected_index,
817
+ previous_cache_key=cache_key,
818
+ allow_demo_fallback=allow_demo_fallback,
819
+ )
820
+ return selected_index, audio_path, updated_cache_key, status, spectrogram_path
821
+
822
+
823
+ def _normalize_rows(rows: object) -> list[list[object]]:
824
+ if hasattr(rows, "values"):
825
+ return [list(item) for item in rows.values.tolist()]
826
+ return [list(item) for item in rows] if rows else []
827
+
828
+
829
+ def _spectrogram_title(audio_path: str | None) -> str:
830
+ if not audio_path:
831
+ return "### Espectrograma"
832
+ return f"### Espectrograma - {Path(audio_path).name}"
833
+
834
+
835
+ def _paginate_rows(rows: list[list[object]], page: int, page_size: int) -> tuple[list[list[object]], int, int]:
836
+ total_items = len(rows)
837
+ total_pages = max(1, ((total_items - 1) // page_size) + 1) if total_items else 1
838
+ safe_page = max(1, min(page, total_pages))
839
+ start = (safe_page - 1) * page_size
840
+ end = start + page_size
841
+ return rows[start:end], safe_page, total_pages
842
+
843
+
844
+ def _extract_species_options_from_queue(
845
+ queue_service: _QueueServiceProtocol,
846
+ project_slug: str,
847
+ page_size: int,
848
+ ) -> list[str]:
849
+ if not project_slug:
850
+ return []
851
+
852
+ species_set: set[str] = set()
853
+ page = 1
854
+ while True:
855
+ page_result = queue_service.get_page(
856
+ project_slug=project_slug,
857
+ page=page,
858
+ page_size=page_size,
859
+ scientific_name=None,
860
+ min_confidence=None,
861
+ max_confidence=None,
862
+ )
863
+ for item in page_result.items:
864
+ name = str(item.scientific_name).strip()
865
+ if name:
866
+ species_set.add(name)
867
+ if not page_result.has_next:
868
+ break
869
+ page += 1
870
+
871
+ return sorted(species_set)
872
+
873
+
874
+ def _sort_rows_by_confidence_desc(rows: list[list[object]]) -> list[list[object]]:
875
+ return sorted(rows, key=lambda row: float(row[3]) if len(row) > 3 else 0.0, reverse=True)
876
+
877
+
878
+ def _fetch_selected_audio_with_title(
879
+ audio_service: _AudioServiceProtocol,
880
+ dataset_repo: str,
881
+ rows: object,
882
+ selected_index: int,
883
+ previous_cache_key: str,
884
+ allow_demo_fallback: bool = False,
885
+ ) -> tuple[str | None, str, str, str | None, str]:
886
+ audio_path, cache_key, status, spectrogram_path = _fetch_selected_audio_with_spectrogram(
887
+ audio_service=audio_service,
888
+ dataset_repo=dataset_repo,
889
+ rows=rows,
890
+ selected_index=selected_index,
891
+ previous_cache_key=previous_cache_key,
892
+ allow_demo_fallback=allow_demo_fallback,
893
+ )
894
+ return audio_path, cache_key, status, spectrogram_path, _spectrogram_title(audio_path)
895
+
896
+
897
+ def _select_and_fetch_audio_with_title(
898
+ audio_service: _AudioServiceProtocol,
899
+ dataset_repo: str,
900
+ rows: object,
901
+ cache_key: str,
902
+ evt: gr.SelectData,
903
+ allow_demo_fallback: bool = False,
904
+ ) -> tuple[int, str | None, str, str, str | None, str]:
905
+ selected_index, audio_path, updated_cache_key, status, spectrogram_path = _select_and_fetch_audio(
906
+ audio_service=audio_service,
907
+ dataset_repo=dataset_repo,
908
+ rows=rows,
909
+ cache_key=cache_key,
910
+ evt=evt,
911
+ allow_demo_fallback=allow_demo_fallback,
912
+ )
913
+ return (
914
+ selected_index,
915
+ audio_path,
916
+ updated_cache_key,
917
+ status,
918
+ spectrogram_path,
919
+ _spectrogram_title(audio_path),
920
+ )
921
+
922
+
923
+ def _autofetch_first_row_with_title(
924
+ audio_service: _AudioServiceProtocol,
925
+ dataset_repo: str,
926
+ rows: object,
927
+ cache_key: str,
928
+ allow_demo_fallback: bool = False,
929
+ ) -> tuple[int, str | None, str, str, str | None, str]:
930
+ selected_index, audio_path, updated_cache_key, status, spectrogram_path = _autofetch_first_row(
931
+ audio_service=audio_service,
932
+ dataset_repo=dataset_repo,
933
+ rows=rows,
934
+ cache_key=cache_key,
935
+ allow_demo_fallback=allow_demo_fallback,
936
+ )
937
+ return (
938
+ selected_index,
939
+ audio_path,
940
+ updated_cache_key,
941
+ status,
942
+ spectrogram_path,
943
+ _spectrogram_title(audio_path),
944
+ )
945
+
946
+
947
+ def _advance_to_next_row_with_title(
948
+ audio_service: _AudioServiceProtocol,
949
+ dataset_repo: str,
950
+ rows: object,
951
+ selected_index: int,
952
+ cache_key: str,
953
+ allow_demo_fallback: bool = False,
954
+ ) -> tuple[int, str | None, str, str, str | None, str]:
955
+ normalized_rows = _normalize_rows(rows)
956
+ if not normalized_rows:
957
+ return 0, None, cache_key, "No detections available", None, _spectrogram_title(None)
958
+
959
+ safe_index = max(0, min(int(selected_index) + 1, len(normalized_rows) - 1))
960
+ audio_path, updated_cache_key, status, spectrogram_path = _fetch_selected_audio_with_spectrogram(
961
+ audio_service=audio_service,
962
+ dataset_repo=dataset_repo,
963
+ rows=normalized_rows,
964
+ selected_index=safe_index,
965
+ previous_cache_key=cache_key,
966
+ allow_demo_fallback=allow_demo_fallback,
967
+ )
968
+ return safe_index, audio_path, updated_cache_key, status, spectrogram_path, _spectrogram_title(audio_path)
969
+
970
+
971
  def _cleanup_selected_audio(audio_service: _AudioServiceProtocol, cache_key: str) -> tuple[str, str | None]:
972
  if not cache_key:
973
  return "No cached audio to clean", None
 
986
  validator: str,
987
  notes: str,
988
  cache_key: str,
989
+ corrected_species: str | None = None,
990
  ) -> tuple[str, str, str | None]:
991
  validator_name = validator.strip()
992
  if not validator_name:
 
1001
  status=status_value,
1002
  validator=validator_name,
1003
  notes=notes.strip(),
1004
+ corrected_species=(corrected_species or "").strip() or None,
1005
  expected_version=expected_version,
1006
  )
1007
  if cache_key:
 
1038
  status_filter: str,
1039
  updated_after: object,
1040
  show_conflicts_only: bool,
1041
+ corrected_species: str | None = None,
1042
  ) -> tuple[str, str, str | None, list[list[object]], int, int, str, str]:
1043
  selected_key = ""
1044
  try:
 
1056
  validator=validator,
1057
  notes=notes,
1058
  cache_key=cache_key,
1059
+ corrected_species=corrected_species,
1060
  )
1061
 
1062
  refreshed_rows, page_status, refreshed_page = _page_to_table(
 
2164
  # ===== TAB 4: Validation =====
2165
  with gr.Tab("✓ Validation", id="validation_tab"):
2166
  validation_status = gr.Markdown(
2167
+ value="",
2168
+ visible=False,
2169
  )
2170
+ queue_badge = gr.HTML(value="", visible=False)
2171
  seed_warning_banner = gr.Markdown(value="", visible=False)
2172
 
2173
  def render_seed_warning(warning_text: str):
 
2235
  )
2236
 
2237
  gr.Markdown("---")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2238
  page_state = gr.State(value=1)
2239
+ project_species_state = gr.State(value=[])
2240
+ custom_corrected_species_state = gr.State(value={})
2241
+ favorite_detection_state = gr.State(value={})
2242
+
2243
+ with gr.Row(equal_height=False):
2244
+ with gr.Column(scale=8):
2245
+ validation_summary_cards = gr.HTML(value=_build_validation_summary_cards([]))
2246
+
2247
+ spectrogram_title = gr.Markdown("### Espectrograma")
2248
+ spectrogram_image = gr.Image(
2249
+ label="",
2250
+ type="filepath",
2251
+ interactive=False,
2252
+ height=330,
2253
+ )
2254
+ audio_player = gr.Audio(label="Audio selecionado", type="filepath", autoplay=True)
2255
+
2256
+ with gr.Row():
2257
+ approve_btn = gr.Button("Up - Positive", variant="primary")
2258
+ reject_btn = gr.Button("Down - Negative")
2259
+ uncertain_btn = gr.Button("Uncertain")
2260
+ skip_btn = gr.Button("Skip")
2261
+ favorite_btn = gr.Button("★ Favorite")
2262
+
2263
+ corrected_species_input = gr.Dropdown(
2264
+ label="Especie corrigida",
2265
+ choices=["Ruido", "Indeterminado"],
2266
+ allow_custom_value=True,
2267
+ filterable=True,
2268
+ value=None,
2269
+ )
2270
 
2271
+ table = gr.Dataframe(
2272
+ headers=[
2273
+ "detection_key",
2274
+ "audio_id",
2275
+ "scientific_name",
2276
+ "confidence",
2277
+ "start_time",
2278
+ "end_time",
2279
+ "validation_status",
2280
+ "version",
2281
+ "conflict_flag",
2282
+ "conflict_severity",
2283
+ ],
2284
+ label="Detections",
2285
+ interactive=False,
2286
+ )
2287
+ selected_index = gr.Number(label="Selected row", value=0, precision=0, visible=False)
2288
+ status = gr.Textbox(label="Status", interactive=False)
2289
+
2290
+ with gr.Column(scale=4):
2291
+ dataset_repo = gr.Textbox(label="Dataset repo", interactive=False)
2292
+ species_filter = gr.Dropdown(
2293
+ label="Especie para validar",
2294
+ choices=[],
2295
+ value=None,
2296
+ interactive=False,
2297
+ )
2298
 
2299
+ gr.Markdown("#### Navegacao")
2300
+ with gr.Row():
2301
+ prev_btn = gr.Button("Prev")
2302
+ next_btn = gr.Button("Next")
2303
+ refresh_btn = gr.Button("Apply")
2304
+
2305
+ gr.Markdown("#### Filtros")
2306
+ min_confidence = gr.Slider(label="Minimum confidence", minimum=0.0, maximum=1.0, step=0.01, value=0.0)
2307
+ validator_filter = gr.Textbox(label="Validator filter", placeholder="Ex: validator-demo")
2308
+ validation_status_filter = gr.Dropdown(
2309
+ label="Status filter",
2310
+ choices=["all", "pending", "positive", "negative", "uncertain", "skip"],
2311
+ value="all",
2312
+ )
2313
+ updated_after_filter = gr.DateTime(label="Updated since", include_time=False, type="string")
2314
+ show_conflicts_only = gr.Checkbox(label="Show only conflicts", value=False)
2315
+
2316
+ gr.Markdown("#### Acoes")
2317
+ validator_name = gr.Textbox(label="Validator", value="validator-demo")
2318
+ validation_notes = gr.Textbox(label="Notes", placeholder="Opcional", lines=4)
2319
+ load_audio_btn = gr.Button("Load selected audio")
2320
+ clear_audio_btn = gr.Button("Clear cached audio")
2321
+ reapply_btn = gr.Button("Reapply validation after conflict")
2322
+ batch_approve_conflicts_btn = gr.Button("Approve all conflicts")
2323
+ batch_reject_conflicts_btn = gr.Button("Reject all conflicts")
2324
+ report_btn = gr.Button("Generate validation report")
2325
+
2326
+ keyboard_shortcuts_info = gr.HTML(
2327
+ value="<div style='font-size:12px;color:#333;padding:8px 10px;background:#f5f5f5;border-radius:6px;margin-bottom:8px;'>"
2328
+ "<strong>Shortcuts:</strong> ArrowUp=Positive | ArrowDown=Negative | 1=Positive | 2=Negative | 3=Uncertain | 4=Skip | R=Reapply"
2329
+ "</div>"
2330
+ "<script>"
2331
+ "document.addEventListener('keydown', function(event) {"
2332
+ " if (event.target.tagName === 'INPUT' || event.target.tagName === 'TEXTAREA') return;"
2333
+ " const key = event.key;"
2334
+ " let buttonText = null;"
2335
+ " if (key === 'ArrowUp' || key === '1') buttonText = 'Up - Positive';"
2336
+ " else if (key === 'ArrowDown' || key === '2') buttonText = 'Down - Negative';"
2337
+ " else if (key === '3') buttonText = 'Uncertain';"
2338
+ " else if (key === '4') buttonText = 'Skip';"
2339
+ " else if (key.toLowerCase() === 'r') buttonText = 'Reapply validation after conflict';"
2340
+ " if (!buttonText) return;"
2341
+ " event.preventDefault();"
2342
+ " const buttons = document.querySelectorAll('button');"
2343
+ " for (const btn of buttons) {"
2344
+ " if ((btn.textContent || '').includes(buttonText)) { btn.click(); break; }"
2345
+ " }"
2346
+ "});"
2347
+ "</script>"
2348
+ )
2349
 
 
 
2350
  cache_key_state = gr.State(value="")
2351
  pending_status_state = gr.State(value="")
2352
  conflict_detection_key_state = gr.State(value="")
 
2353
  report_box = gr.Textbox(label="Report", interactive=False)
2354
 
2355
  def refresh(
 
2363
  only_conflicts: bool,
2364
  ):
2365
  if not project_slug:
2366
+ return [], "", 1
2367
+ species_name = (species or "").strip()
2368
+ if not species_name:
2369
+ return [], "Selecione uma especie para iniciar a validacao", 1
2370
+
2371
+ rows, status_text, updated_page = _page_to_table(
2372
  service=service_ref["queue"],
2373
  snapshot_reader=validation_repository,
2374
  project_slug=project_slug,
2375
  page=page,
2376
+ scientific_name=species_name,
2377
  min_confidence=confidence,
2378
  page_size=runtime_config.page_size,
2379
  validator_filter=validator_filter_value,
 
2381
  updated_after=updated_after_value,
2382
  show_conflicts_only=only_conflicts,
2383
  )
2384
+ rows = _sort_rows_by_confidence_desc(rows)
2385
+ return rows, status_text, updated_page
2386
 
2387
  def go_next(
2388
  project_slug: str,
 
2427
  )
2428
 
2429
  def refresh_for_selected_project(project_slug: str):
2430
+ if not project_slug:
2431
+ return gr.update(choices=[], value=None, interactive=False), [], "", 1, None, None, _spectrogram_title(None), _build_validation_summary_cards([]), gr.update(choices=["Ruido", "Indeterminado"], value=None), []
2432
+
2433
+ species_options = _extract_species_options_from_queue(
2434
+ queue_service=service_ref["queue"],
2435
+ project_slug=project_slug,
2436
+ page_size=max(32, runtime_config.page_size),
2437
+ )
2438
+ corrected_choices = species_options + ["Ruido", "Indeterminado"]
2439
+ return (
2440
+ gr.update(choices=species_options, value=None, interactive=True),
2441
+ [],
2442
+ "Selecione uma especie para iniciar a validacao",
2443
+ 1,
2444
+ None,
2445
+ None,
2446
+ _spectrogram_title(None),
2447
+ _build_validation_summary_cards([]),
2448
+ gr.update(choices=corrected_choices, value=None),
2449
+ species_options,
2450
+ )
2451
 
2452
  def save_for_project(
2453
  project_slug: str,
 
2456
  idx: int,
2457
  name: str,
2458
  notes: str,
2459
+ corrected_species_value: str | None,
2460
  cache_key: str,
2461
  page: int,
2462
  species: str,
 
2479
  status_value=status_value,
2480
  validator=name,
2481
  notes=notes,
2482
+ corrected_species=corrected_species_value,
2483
  cache_key=cache_key,
2484
  page=int(page),
2485
  scientific_name=species,
 
2571
  return "Select a project to generate report"
2572
  return _build_validation_report(validation_repository, project_slug)
2573
 
2574
+ def save_corrected_species_option(
2575
+ project_slug: str,
2576
+ corrected_value: str | None,
2577
+ detected_species: list[str],
2578
+ custom_by_project: dict[str, list[str]],
2579
+ ):
2580
+ base_choices = list(dict.fromkeys([*detected_species, "Ruido", "Indeterminado"]))
2581
+ value = (corrected_value or "").strip()
2582
 
2583
+ if not project_slug:
2584
+ return gr.update(choices=base_choices, value=value or None), custom_by_project
2585
+
2586
+ updated = {k: list(v) for k, v in (custom_by_project or {}).items()}
2587
+ custom_values = updated.get(project_slug, [])
2588
+ if value and value not in base_choices and value not in custom_values:
2589
+ custom_values.append(value)
2590
+ updated[project_slug] = custom_values
2591
+
2592
+ final_choices = list(dict.fromkeys([*base_choices, *updated.get(project_slug, [])]))
2593
+ return gr.update(choices=final_choices, value=value or None), updated
2594
+
2595
+ def toggle_favorite_detection(
2596
+ project_slug: str,
2597
+ rows: object,
2598
+ idx: int,
2599
+ favorite_map: dict[str, list[str]],
2600
+ ):
2601
+ normalized_rows = _normalize_rows(rows)
2602
+ if not project_slug or not normalized_rows:
2603
+ return "Nenhuma deteccao selecionada para favoritar", favorite_map
2604
+
2605
+ safe_idx = max(0, min(int(idx), len(normalized_rows) - 1))
2606
+ detection_key = str(normalized_rows[safe_idx][0]).strip()
2607
+ updated_map = {k: list(v) for k, v in (favorite_map or {}).items()}
2608
+ project_favs = set(updated_map.get(project_slug, []))
2609
+ if detection_key in project_favs:
2610
+ project_favs.remove(detection_key)
2611
+ action = "removida dos favoritos"
2612
+ else:
2613
+ project_favs.add(detection_key)
2614
+ action = "adicionada aos favoritos"
2615
+ updated_map[project_slug] = sorted(project_favs)
2616
+ return f"Deteccao {detection_key} {action}", updated_map
2617
+
2618
+ def on_table_select(repo: str, rows: object, cache_key: str, evt: gr.SelectData):
2619
+ return _select_and_fetch_audio_with_title(
2620
+ audio_service=audio_service,
2621
+ dataset_repo=repo,
2622
+ rows=rows,
2623
+ cache_key=cache_key,
2624
+ evt=evt,
2625
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
2626
+ )
2627
+
2628
+ refresh_event = refresh_btn.click(
2629
  fn=refresh,
2630
  inputs=[
2631
  selected_project_state,
 
2639
  ],
2640
  outputs=[table, status, page_state],
2641
  )
2642
+ next_event = next_btn.click(
2643
  fn=go_next,
2644
  inputs=[
2645
  selected_project_state,
 
2653
  ],
2654
  outputs=[table, status, page_state],
2655
  )
2656
+ prev_event = prev_btn.click(
2657
  fn=go_prev,
2658
  inputs=[
2659
  selected_project_state,
 
2673
  inputs=[selected_dataset_repo_state],
2674
  outputs=[dataset_repo],
2675
  )
2676
+ project_change_event = selected_project_state.change(
2677
  fn=refresh_for_selected_project,
2678
  inputs=[selected_project_state],
2679
+ outputs=[species_filter, table, status, page_state, audio_player, spectrogram_image, spectrogram_title, validation_summary_cards, corrected_species_input, project_species_state],
2680
+ )
2681
+
2682
+ species_filter.change(
2683
+ fn=lambda project_slug, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: refresh(
2684
+ project_slug,
2685
+ 1,
2686
+ species,
2687
+ confidence,
2688
+ validator_filter_value,
2689
+ status_filter_value,
2690
+ updated_after_value,
2691
+ only_conflicts,
2692
+ ),
2693
+ inputs=[
2694
+ selected_project_state,
2695
+ species_filter,
2696
+ min_confidence,
2697
+ validator_filter,
2698
+ validation_status_filter,
2699
+ updated_after_filter,
2700
+ show_conflicts_only,
2701
+ ],
2702
  outputs=[table, status, page_state],
2703
+ ).then(
2704
+ fn=lambda rows: _build_validation_summary_cards(rows),
2705
+ inputs=[table],
2706
+ outputs=[validation_summary_cards],
2707
+ ).then(
2708
+ fn=lambda repo, rows, cache_key: _autofetch_first_row_with_title(
2709
+ audio_service=audio_service,
2710
+ dataset_repo=repo,
2711
+ rows=rows,
2712
+ cache_key=cache_key,
2713
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
2714
+ ),
2715
+ inputs=[selected_dataset_repo_state, table, cache_key_state],
2716
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
2717
+ )
2718
+
2719
+ table.select(
2720
+ fn=on_table_select,
2721
+ inputs=[selected_dataset_repo_state, table, cache_key_state],
2722
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
2723
  )
2724
 
2725
  load_audio_btn.click(
2726
+ fn=lambda repo, rows, idx, cache_key: _fetch_selected_audio_with_title(
2727
  audio_service=audio_service,
2728
  dataset_repo=repo,
2729
  rows=rows,
2730
  selected_index=int(idx),
2731
  previous_cache_key=cache_key,
2732
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
2733
  ),
2734
+ inputs=[selected_dataset_repo_state, table, selected_index, cache_key_state],
2735
+ outputs=[audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
2736
  )
2737
  clear_audio_btn.click(
2738
+ fn=lambda cache_key: (*_cleanup_selected_audio(audio_service=audio_service, cache_key=cache_key), None),
2739
  inputs=[cache_key_state],
2740
+ outputs=[status, audio_player, spectrogram_image],
2741
+ ).then(
2742
+ fn=lambda: _spectrogram_title(None),
2743
+ inputs=None,
2744
+ outputs=[spectrogram_title],
2745
+ )
2746
+
2747
+ refresh_event.then(
2748
+ fn=lambda rows: _build_validation_summary_cards(rows),
2749
+ inputs=[table],
2750
+ outputs=[validation_summary_cards],
2751
+ ).then(
2752
+ fn=lambda repo, rows, cache_key: _autofetch_first_row_with_title(
2753
+ audio_service=audio_service,
2754
+ dataset_repo=repo,
2755
+ rows=rows,
2756
+ cache_key=cache_key,
2757
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
2758
+ ),
2759
+ inputs=[selected_dataset_repo_state, table, cache_key_state],
2760
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
2761
+ )
2762
+ next_event.then(
2763
+ fn=lambda rows: _build_validation_summary_cards(rows),
2764
+ inputs=[table],
2765
+ outputs=[validation_summary_cards],
2766
+ ).then(
2767
+ fn=lambda repo, rows, cache_key: _autofetch_first_row_with_title(
2768
+ audio_service=audio_service,
2769
+ dataset_repo=repo,
2770
+ rows=rows,
2771
+ cache_key=cache_key,
2772
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
2773
+ ),
2774
+ inputs=[selected_dataset_repo_state, table, cache_key_state],
2775
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
2776
+ )
2777
+ prev_event.then(
2778
+ fn=lambda rows: _build_validation_summary_cards(rows),
2779
+ inputs=[table],
2780
+ outputs=[validation_summary_cards],
2781
+ ).then(
2782
+ fn=lambda repo, rows, cache_key: _autofetch_first_row_with_title(
2783
+ audio_service=audio_service,
2784
+ dataset_repo=repo,
2785
+ rows=rows,
2786
+ cache_key=cache_key,
2787
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
2788
+ ),
2789
+ inputs=[selected_dataset_repo_state, table, cache_key_state],
2790
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
2791
+ )
2792
+
2793
+ favorite_btn.click(
2794
+ fn=toggle_favorite_detection,
2795
+ inputs=[selected_project_state, table, selected_index, favorite_detection_state],
2796
+ outputs=[status, favorite_detection_state],
2797
  )
2798
 
2799
+ corrected_species_input.change(
2800
+ fn=save_corrected_species_option,
2801
+ inputs=[selected_project_state, corrected_species_input, project_species_state, custom_corrected_species_state],
2802
+ outputs=[corrected_species_input, custom_corrected_species_state],
2803
+ )
2804
+
2805
+ approve_event = approve_btn.click(
2806
+ fn=lambda project_slug, rows, idx, name, notes, corrected_species_value, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: save_for_project(
2807
  project_slug,
2808
  "positive",
2809
  rows,
2810
  idx,
2811
  name,
2812
  notes,
2813
+ corrected_species_value,
2814
  cache_key,
2815
  page,
2816
  species,
 
2826
  selected_index,
2827
  validator_name,
2828
  validation_notes,
2829
+ corrected_species_input,
2830
  cache_key_state,
2831
  page_state,
2832
  species_filter,
 
2838
  ],
2839
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2840
  )
2841
+ reject_event = reject_btn.click(
2842
+ fn=lambda project_slug, rows, idx, name, notes, corrected_species_value, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: save_for_project(
2843
  project_slug,
2844
  "negative",
2845
  rows,
2846
  idx,
2847
  name,
2848
  notes,
2849
+ corrected_species_value,
2850
  cache_key,
2851
  page,
2852
  species,
 
2862
  selected_index,
2863
  validator_name,
2864
  validation_notes,
2865
+ corrected_species_input,
2866
  cache_key_state,
2867
  page_state,
2868
  species_filter,
 
2874
  ],
2875
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2876
  )
2877
+ uncertain_event = uncertain_btn.click(
2878
+ fn=lambda project_slug, rows, idx, name, notes, corrected_species_value, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: save_for_project(
2879
  project_slug,
2880
  "uncertain",
2881
  rows,
2882
  idx,
2883
  name,
2884
  notes,
2885
+ corrected_species_value,
2886
  cache_key,
2887
  page,
2888
  species,
 
2898
  selected_index,
2899
  validator_name,
2900
  validation_notes,
2901
+ corrected_species_input,
2902
  cache_key_state,
2903
  page_state,
2904
  species_filter,
 
2910
  ],
2911
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2912
  )
2913
+ skip_event = skip_btn.click(
2914
+ fn=lambda project_slug, rows, idx, name, notes, corrected_species_value, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: save_for_project(
2915
  project_slug,
2916
  "skip",
2917
  rows,
2918
  idx,
2919
  name,
2920
  notes,
2921
+ corrected_species_value,
2922
  cache_key,
2923
  page,
2924
  species,
 
2934
  selected_index,
2935
  validator_name,
2936
  validation_notes,
2937
+ corrected_species_input,
2938
  cache_key_state,
2939
  page_state,
2940
  species_filter,
 
2946
  ],
2947
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2948
  )
2949
+ reapply_event = reapply_btn.click(
2950
  fn=lambda project_slug, rows, idx, pending_status, conflict_key, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value, only_conflicts: reapply_for_project(
2951
  project_slug,
2952
  rows,
 
2984
  outputs=[status, cache_key_state, audio_player, table, page_state, selected_index, pending_status_state, conflict_detection_key_state],
2985
  )
2986
 
2987
+ batch_approve_event = batch_approve_conflicts_btn.click(
2988
  fn=lambda project_slug, rows, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value: batch_for_project(
2989
  project_slug,
2990
  rows,
 
3014
  ],
3015
  outputs=[status, cache_key_state, audio_player, table, page_state],
3016
  )
3017
+ batch_reject_event = batch_reject_conflicts_btn.click(
3018
  fn=lambda project_slug, rows, name, notes, cache_key, page, species, confidence, validator_filter_value, status_filter_value, updated_after_value: batch_for_project(
3019
  project_slug,
3020
  rows,
 
3044
  ],
3045
  outputs=[status, cache_key_state, audio_player, table, page_state],
3046
  )
3047
+
3048
+ approve_event.then(
3049
+ fn=lambda repo, rows, idx, cache_key: _advance_to_next_row_with_title(
3050
+ audio_service=audio_service,
3051
+ dataset_repo=repo,
3052
+ rows=rows,
3053
+ selected_index=int(idx),
3054
+ cache_key=cache_key,
3055
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
3056
+ ),
3057
+ inputs=[selected_dataset_repo_state, table, selected_index, cache_key_state],
3058
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
3059
+ ).then(fn=lambda rows: _build_validation_summary_cards(rows), inputs=[table], outputs=[validation_summary_cards])
3060
+
3061
+ reject_event.then(
3062
+ fn=lambda repo, rows, idx, cache_key: _advance_to_next_row_with_title(
3063
+ audio_service=audio_service,
3064
+ dataset_repo=repo,
3065
+ rows=rows,
3066
+ selected_index=int(idx),
3067
+ cache_key=cache_key,
3068
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
3069
+ ),
3070
+ inputs=[selected_dataset_repo_state, table, selected_index, cache_key_state],
3071
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
3072
+ ).then(fn=lambda rows: _build_validation_summary_cards(rows), inputs=[table], outputs=[validation_summary_cards])
3073
+
3074
+ uncertain_event.then(
3075
+ fn=lambda repo, rows, idx, cache_key: _advance_to_next_row_with_title(
3076
+ audio_service=audio_service,
3077
+ dataset_repo=repo,
3078
+ rows=rows,
3079
+ selected_index=int(idx),
3080
+ cache_key=cache_key,
3081
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
3082
+ ),
3083
+ inputs=[selected_dataset_repo_state, table, selected_index, cache_key_state],
3084
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
3085
+ ).then(fn=lambda rows: _build_validation_summary_cards(rows), inputs=[table], outputs=[validation_summary_cards])
3086
+
3087
+ skip_event.then(
3088
+ fn=lambda repo, rows, idx, cache_key: _advance_to_next_row_with_title(
3089
+ audio_service=audio_service,
3090
+ dataset_repo=repo,
3091
+ rows=rows,
3092
+ selected_index=int(idx),
3093
+ cache_key=cache_key,
3094
+ allow_demo_fallback=runtime_config.enable_demo_bootstrap,
3095
+ ),
3096
+ inputs=[selected_dataset_repo_state, table, selected_index, cache_key_state],
3097
+ outputs=[selected_index, audio_player, cache_key_state, status, spectrogram_image, spectrogram_title],
3098
+ ).then(fn=lambda rows: _build_validation_summary_cards(rows), inputs=[table], outputs=[validation_summary_cards])
3099
+
3100
+ reapply_event.then(fn=lambda rows: _build_validation_summary_cards(rows), inputs=[table], outputs=[validation_summary_cards])
3101
+ batch_approve_event.then(fn=lambda rows: _build_validation_summary_cards(rows), inputs=[table], outputs=[validation_summary_cards])
3102
+ batch_reject_event.then(fn=lambda rows: _build_validation_summary_cards(rows), inputs=[table], outputs=[validation_summary_cards])
3103
  report_btn.click(
3104
  fn=build_report_for_project,
3105
  inputs=[selected_project_state],
tests/unit/test_audio_fetch_service.py CHANGED
@@ -55,6 +55,29 @@ def test_fetch_without_extension_tries_supported_extensions(tmp_path: Path, monk
55
  assert any(path.endswith(".mp3") for path in attempts)
56
 
57
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
58
  def test_cleanup_after_validation_removes_cached_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
59
  remote_file = tmp_path / "remote.wav"
60
  remote_file.write_bytes(b"audio-bytes")
 
55
  assert any(path.endswith(".mp3") for path in attempts)
56
 
57
 
58
+ def test_fetch_uses_demo_fallback_when_remote_audio_is_missing(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
59
+ def fake_download(*, repo_id: str, repo_type: str, filename: str) -> str:
60
+ _ = repo_id
61
+ _ = repo_type
62
+ _ = filename
63
+ raise RuntimeError("not found")
64
+
65
+ monkeypatch.setattr("src.services.audio_fetch_service.hf_hub_download", fake_download)
66
+
67
+ cache = EphemeralCacheManager(cache_dir=str(tmp_path / "cache"), ttl_seconds=60, max_files=10)
68
+ service = AudioFetchService(cache)
69
+
70
+ result = service.fetch(
71
+ dataset_repo="org/project-dataset",
72
+ audio_id="missing_demo_audio_001",
73
+ allow_demo_fallback=True,
74
+ )
75
+
76
+ assert result.source == "demo-fallback"
77
+ assert Path(result.local_path).exists()
78
+ assert Path(result.local_path).suffix.lower() == ".wav"
79
+
80
+
81
  def test_cleanup_after_validation_removes_cached_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
82
  remote_file = tmp_path / "remote.wav"
83
  remote_file.write_bytes(b"audio-bytes")