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

ai procurement/app/nlu.py

@@ -51,12 +51,19 @@ SYSTEM_PROMPT = """تو دستیار تدارکات یک ERP فارسی هستی
 یک JSON و فقط JSON برگردان (بدون توضیح اضافه) با این شکل:
 
 {
+  "consensus_text": "متن تجمیع‌شده و اصلاح‌شده کاربر (فارسی روان و بدون غلط شنیداری)",
   "intent": یکی از {intents},
   "patch": {شکل partial هر فعالیتی که کاربر داده},
   "confidence": 0.0..1.0
 }
 
 قوانین:
+- اگر ورودی شامل چند نسخه تبدیل گفتار به متن (STT) از یک پیام صوتی کاربر است:
+  ۱. این نسخه‌ها از چند مدل مختلف برای افزایش دقت به دست آمده‌اند. آن‌ها را با هم مقایسه و مقابله کن.
+  ۲. خطاهای شنیداری هر نسخه را بر مبنای منطق تدارکات (نام کالاها، برندها، مشخصات فنی و واحدهای اندازه‌گیری) تصحیح و حل تعارض کن.
+  ۳. متن نهایی اصلاح و تجمیع‌شده را در فیلد consensus_text قرار بده.
+  ۴. استخراج قصد (intent) و موجودیت‌ها (patch) را بر اساس همین متن دقیق انجام بده.
+- اگر ورودی یک متن عادی است، همان متن را در consensus_text قرار بده.
 - اگر پیام کاربر اطلاعات جدیدی به پیش‌نویسِ باز اضافه می‌کند یا اصلاح می‌کند → intent="update_draft" و patch شامل فقط فیلدهای جدید/تغییریافته.
 - اگر عبارت تأیید نهایی است (مثل «ثبت کن»، «همینه، ثبتش کن») → intent="commit_draft".
 - اگر لغو است («بی‌خیال»، «لغو») → intent="discard_draft".
@@ -113,12 +120,28 @@ def _extract_json(raw: str) -> dict | None:
         return None
 
 
-async def understand(settings: Settings, text: str, draft_summary: str | None = None) -> dict:
-    """Return {"intent": ..., "patch": {...}, "confidence": ...}; never raises."""
-    fallback = {"intent": "unknown", "patch": {}, "confidence": 0.0}
+async def understand(settings: Settings, text: str | list[dict], draft_summary: str | None = None) -> dict:
+    """Return {"consensus_text": ..., "intent": ..., "patch": {...}, "confidence": ...}; never raises."""
+    fallback = {"consensus_text": "", "intent": "unknown", "patch": {}, "confidence": 0.0}
     if not settings.AI_BASE_URL or not settings.AI_API_KEY:
         logger.warning("AI provider not configured; cannot understand message")
         return fallback
+
+    if isinstance(text, list):
+        first_text = text[0].get("text") if text else ""
+        lines = ["پیام صوتی کاربر توسط چند مدل تبدیل گفتار به متن (STT) به صورت زیر پیاده‌سازی شده است:"]
+        for idx, item in enumerate(text, start=1):
+            name = item.get("name") or f"مدل {idx}"
+            t = normalize_digits(item.get("text") or "")
+            lines.append(f"- نسخه {idx} ({name}): «{t}»")
+        lines.append("\nبا تلفیق این نسخه‌ها و تصحیح خطاهای شنیداری، پیام را تحلیل کن و consensus_text را به همراه intent و patch بساز.")
+        user_content = "\n".join(lines)
+    else:
+        user_content = normalize_digits(str(text))
+        first_text = str(text)
+
+    fallback["consensus_text"] = first_text
+
     try:
         async with httpx.AsyncClient(timeout=settings.LLM_TIMEOUT_SECONDS) as client:
             resp = await client.post(
@@ -128,7 +151,7 @@ async def understand(settings: Settings, text: str, draft_summary: str | None =
                     "model": settings.LLM_MODEL,
                     "messages": [
                         {"role": "system", "content": _build_system_prompt(draft_summary)},
-                        {"role": "user", "content": normalize_digits(text)},
+                        {"role": "user", "content": user_content},
                     ],
                     "temperature": 0.1,
                     "response_format": {"type": "json_object"},
@@ -143,6 +166,8 @@ async def understand(settings: Settings, text: str, draft_summary: str | None =
             logger.warning("unparseable LLM output: %r", content[:200])
             return fallback
         parsed.setdefault("patch", {})
+        if not parsed.get("consensus_text"):
+            parsed["consensus_text"] = first_text
         return parsed
     except (httpx.HTTPError, json.JSONDecodeError, KeyError, TypeError):
         logger.exception("NLU failure")