feat(stt): support multi-model STT with parallel execution and consensus NLU extraction

ai procurement/app/stt.py

@@ -37,11 +37,45 @@ def _to_mp3(raw: bytes, suffix: str) -> bytes:
         return dst.read_bytes()
 
 
-async def transcribe(settings: Settings, audio: bytes, mime_type: str | None = None,
-                     filename: str | None = None) -> str:
-    """Return the Persian transcript for a voice note (empty string on silence)."""
-    if not settings.stt_base_url or not settings.stt_api_key:
-        raise RuntimeError("STT provider is not configured (PROCUREMENT_BOT_STT_BASE_URL / _AI_BASE_URL)")
+async def _call_single_stt(client: httpx.AsyncClient, provider: dict, converted_mp3: bytes) -> dict | None:
+    name = provider.get("name") or "stt"
+    base_url = (provider.get("base_url") or "").rstrip("/")
+    api_key = provider.get("api_key") or ""
+    model = provider.get("model") or "whisper-1"
+    language = provider.get("language") or "fa"
+    timeout = float(provider.get("timeout") or _STT_TIMEOUT)
+
+    url = f"{base_url}/audio/transcriptions"
+    try:
+        resp = await client.post(
+            url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            files={"file": ("voice.mp3", converted_mp3, "audio/mpeg")},
+            data={"model": model, "language": language},
+            timeout=timeout,
+        )
+        if resp.status_code == 200:
+            txt = str((resp.json() or {}).get("text") or "").strip()
+            if txt:
+                logger.info("STT provider %s succeeded: %r", name, txt[:60])
+                return {"name": name, "text": txt, "model": model}
+        else:
+            logger.warning("STT provider %s returned HTTP %s: %s", name, resp.status_code, resp.text[:200])
+    except Exception as exc:
+        logger.warning("STT provider %s failed: %s", name, exc)
+    return None
+
+
+async def transcribe_multi(settings: Settings, audio: bytes, mime_type: str | None = None,
+                           filename: str | None = None) -> list[dict]:
+    """Transcribe audio with all configured STT providers in parallel.
+
+    Returns a list of candidate dicts: [{"name": str, "text": str, "model": str}, ...]
+    Empty list if all failed or silence.
+    """
+    providers = settings.stt_providers
+    if not providers:
+        raise RuntimeError("No STT providers are configured (PROCUREMENT_BOT_STT_*)")
 
     suffix = Path(filename or "").suffix
     if not suffix and mime_type:
@@ -49,14 +83,20 @@ async def transcribe(settings: Settings, audio: bytes, mime_type: str | None = N
                   "audio/mp4": ".m4a", "audio/wav": ".wav"}.get(mime_type.split(";")[0].strip(), ".ogg")
     converted = await asyncio.to_thread(_to_mp3, audio, suffix)
 
-    url = f"{settings.stt_base_url.rstrip('/')}/audio/transcriptions"
     async with httpx.AsyncClient(timeout=_STT_TIMEOUT) as client:
-        resp = await client.post(
-            url,
-            headers={"Authorization": f"Bearer {settings.stt_api_key}"},
-            files={"file": ("voice.mp3", converted, "audio/mpeg")},
-            data={"model": settings.STT_MODEL, "language": settings.STT_LANGUAGE},
-        )
-    if resp.status_code != 200:
-        raise RuntimeError(f"STT provider returned HTTP {resp.status_code}: {resp.text[:300]}")
-    return str((resp.json() or {}).get("text") or "").strip()
+        tasks = [_call_single_stt(client, p, converted) for p in providers]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    valid_transcripts: list[dict] = []
+    for r in results:
+        if isinstance(r, dict) and r.get("text"):
+            valid_transcripts.append(r)
+
+    return valid_transcripts
+
+
+async def transcribe(settings: Settings, audio: bytes, mime_type: str | None = None,
+                     filename: str | None = None) -> str:
+    """Return the Persian transcript for a voice note (empty string on silence)."""
+    transcripts = await transcribe_multi(settings, audio, mime_type=mime_type, filename=filename)
+    return transcripts[0]["text"] if transcripts else ""