268 lines
16 KiB
Python
268 lines
16 KiB
Python
"""Natural-language understanding: Persian free text → typed intent + entities.
|
||
|
||
One chat/completions call per message with JSON-mode output. The prompt embeds
|
||
the current draft summary so the model can decide between "start a new
|
||
activity" and "refine the open draft" (update_draft with a partial patch).
|
||
"""
|
||
import hashlib
|
||
import json
|
||
import logging
|
||
import re
|
||
|
||
import httpx
|
||
|
||
from app import observability as obs
|
||
from app.config import Settings
|
||
|
||
logger = logging.getLogger("bot.nlu")
|
||
|
||
|
||
class NLUFailureError(Exception):
|
||
"""Raised when NLU understanding fails due to LLM / network failure."""
|
||
pass
|
||
|
||
PERSIAN_DIGITS = str.maketrans("۰۱۲۳۴۵۶۷۸۹٠١٢٣٤٥٦٧٨٩", "01234567890123456789")
|
||
|
||
|
||
def normalize_digits(text: str) -> str:
|
||
return (text or "").translate(PERSIAN_DIGITS)
|
||
|
||
|
||
ZWNJ = "\u200c"
|
||
|
||
MENTION_FIELDS = {"project", "supplier", "material", "brand", "spec", "unit"}
|
||
|
||
|
||
def sanitize_mentions(raw) -> list[dict]:
|
||
"""Keep only valid {field, variants} mention objects from the LLM output."""
|
||
out: list[dict] = []
|
||
if not isinstance(raw, list):
|
||
return out
|
||
for m in raw:
|
||
if not isinstance(m, dict):
|
||
continue
|
||
field = str(m.get("field") or "").strip()
|
||
variants = [str(v).strip() for v in (m.get("variants") or []) if str(v or "").strip()]
|
||
if field in MENTION_FIELDS and variants:
|
||
out.append({"field": field, "variants": variants[:6]})
|
||
return out
|
||
|
||
|
||
def normalize_text(text: str) -> str:
|
||
"""Normalize Persian text for fuzzy matching (ZWNJ, arabic ya/ka, spaces)."""
|
||
t = normalize_digits(text or "")
|
||
t = t.replace(ZWNJ, " ").replace("ي", "ی").replace("ك", "ک")
|
||
t = re.sub(r"\s+", " ", t).strip().lower()
|
||
return t
|
||
|
||
|
||
INTENTS = [
|
||
"register_quote", # ثبت استعلام/پیشنهاد جدید از یک تأمین‌کننده
|
||
"update_draft", # تکمیل/اصلاح پیش‌نویس باز (patch روی آن)
|
||
"commit_draft", # «ثبت کن» / «تأیید» — commit the open draft
|
||
"discard_draft", # «بی‌خیال» / «لغو»
|
||
"show_draft", # «وضعیت پیش‌نویس؟»
|
||
"add_supplier",
|
||
"add_material",
|
||
"add_project",
|
||
"status_query", # پرس‌وجو: استعلام‌های در انتظار / به‌زودی منقضی / ...
|
||
"accept_quote", # پذیرش یک استعلام
|
||
"arrive_items", # اعلام رسیدن اقلام
|
||
"help",
|
||
"unknown",
|
||
]
|
||
|
||
SYSTEM_PROMPT = """تو دستیار هوشمند تدارکات یک سیستم ERP ساختمانی و صنعتی در ایران هستی.
|
||
پیام‌های صوتی کاربران به زبان فارسی، با گویش و لهجه اصفهانی و با اصطلاحات محاوره‌ای کارگاهی و بازار بیان شده‌اند که نسخه‌های متنی متعددی توسط موتورهای تبدیل گفتار به متن (STT مانند Whisper و Vosk) از آن‌ها تولید شده است.
|
||
|
||
وظیفه تو تحلیل پیام، حل خطاهای شنیداری ناشی از لهجه و گویش، تولید متن اجماعی پالایش‌شده و استخراج دقیق داده‌های تدارکاتی است.
|
||
یک JSON و فقط JSON برگردان (بدون هرگونه متن، مارک‌داون یا توضیح اضافه) با این ساختار دقیق:
|
||
|
||
{
|
||
"consensus_text": "بیانیه رسمی، پالایش‌شده، فشرده و بدون تکیه‌کلام از تقاضای تدارکات کاربر",
|
||
"intent": یکی از {intents},
|
||
"patch": {شکل partial هر فعالیتی که کاربر داده},
|
||
"entity_mentions": [{"field": "project|supplier|material|brand|spec|unit", "variants": ["همه‌ی نگارش‌ها"]}],
|
||
"confidence": 0.0..1.0
|
||
}
|
||
|
||
قواعد حیاتی:
|
||
۱. قواعد آوایی و دستوری لهجه اصفهانی در رمزگشایی خطاهای STT:
|
||
- شناسه مفعولی پیوسته: پسوند «ـشا» یا «ش ها» در پایان کلمات (مانند پولشا، بارشا) به معنای «آن را / آن‌ها را» است.
|
||
- شناسه دوم شخص جمع (ت به د): پسوندهای «ـِدون»، «برادون»، «برهدون» به معنای «برایتان / به شما» هستند.
|
||
- تخمین زمانی و مقداری: کلمه «اینا» پس از اعداد یا زمان (مثلاً «۱۰ روز اینا»، «۴۰ تا اینا») قید تخمین و به معنای «حدوداً» است و نباید با کلمات نامربوط (مانند روزنامه) اشتباه گرفته شود.
|
||
- حذف حشوهای مکالمه: اصطلاحات پرکننده («عرض به خدمتتون»، «پامون درمیاد»، «دونه‌ای اینا»، «شبت بخیر»، «همین») باید کاملاً از consensus_text پالایش شوند.
|
||
- حل تعارض نام‌ها در مدل‌های STT: در صورت تفاوت املایی نام تأمین‌کننده یا کالا بین چند مدل، اولویت با نگارشی است که با واژگان معتبر فارسی، نام‌های خانوادگی استاندارد و اقلام صنعتی/ساختمانی تطابق دارد.
|
||
|
||
۲. ساخت فیلد consensus_text:
|
||
- متن consensus_text نباید انشا یا نقل‌قول داستانی پر از تعارفات و حواشی باشد.
|
||
- کلیه احوالپرسی‌ها، تعارفات و تکیه‌کلام‌ها را کاملاً حذف کن.
|
||
- این متن باید یک «بیانیه رسمی، تمیز و ساختاریافته تدارکاتی» باشد که شامل: نوع اقدام (استعلام/خرید)، اقلام، مقادیر، مشخصات، قیمت‌ها، نام تأمین‌کننده، نام پروژه‌ها، مهلت اعتبار و خلاصه نحوه پرداخت باشد.
|
||
مثال سبک بیانیه رسمی: «استعلام خرید ۱۲۰ شاخه لوله پلیکا ۶ اینچ (فی ۴۵۰,۰۰۰ تومان) از بازرگانی البرز برای پروژه پردیس. مهلت اعتبار پیش‌فاکتور: ۵ روز. شرایط پرداخت: نقد با ۵٪ تخفیف.»
|
||
|
||
۳. تفکیک وظایف محاسباتی با defaults.py:
|
||
- تو فقط ساختار مفهومی را در patch استخراج می‌کنی؛ محاسبات عددی اقساط و تاریخ‌های تقویم شمسی بر عهده توابع سیستم است.
|
||
- برای اقساط: تعداد اقساط را در installments_count استخراج کن (مثلاً ۴).
|
||
- برای پرداخت نقدی: درصد تخفیف را در discount_percent استخراج کن (مثلاً ۵).
|
||
- برای مهلت اعتبار: تعداد روز را در expiry_days بگذار (مثلاً ۵).
|
||
|
||
۴. قوانین استخراج پروژه‌ها و اقلام:
|
||
- پروژه‌ها: اگر کاربر چند پروژه را ذکر کرد (مانند «برای پردیس و کارگاه مرکزی»)، تمام نام‌ها را عیناً در آرایه project_names قرار بده: ["پردیس", "کارگاه مرکزی"]. پروژه‌ها را با برند اشتباه نگیر.
|
||
- اقلام: material_name فقط نام کلی کالا (مانند «لوله پلیکا» یا «میلگرد»)؛ مشخصات فنی (مانند «۶ اینچ» یا «آجدار») در آرایه specs؛ تعداد در quantity؛ واحد در unit_name؛ و قیمت واحد در unit_price (عددی خالص، مثلاً ۴۵۰ هزار = 450000).
|
||
|
||
۵. قوانین عمومی قصدها (Intents):
|
||
- اگر پیام کاربر اطلاعات جدیدی به پیش‌نویسِ باز اضافه می‌کند یا اصلاح می‌کند → intent="update_draft" و patch شامل فقط فیلدهای جدید/تغییریافته.
|
||
- اگر عبارت تأیید نهایی است (مثل «ثبت کن»، «همینه، ثبتش کن») → intent="commit_draft".
|
||
- اگر لغو است («بی‌خیال»، «لغو») → intent="discard_draft".
|
||
- اگر سؤال درباره وضعیت است → intent="status_query".
|
||
- اگر درباره پذیرش استعلام است → intent="accept_quote" و در patch.target نام تأمین‌کننده/استعلام.
|
||
- اگر درباره اعلام رسیدن اقلام است → intent="arrive_items" و در patch.target نام تأمین‌کننده/استعلام و در patch.arrivals مقادیر.
|
||
|
||
۶. استخراج موجودیت‌های قابل تطبیق (entity_mentions):
|
||
- فیلدهای مجاز: "project" | "supplier" | "material" | "brand" | "spec" | "unit"
|
||
- هر نام کالا/تأمین‌کننده/پروژه/برند/واحد و هر مشخصه که در پیام آمده، یک عضو جداگانه است.
|
||
- اگر در نسخه‌های مختلف STT همان نام با املاهای متفاوت پیاده شده (مثل «فولاد گستر»، «پولاد گستر»)،
|
||
همه را در variants همان یک عضو بگذار — نه چند عضو جداگانه.
|
||
- برای پیام متنی معمولی، variants یک عضو تک‌عنصر است.
|
||
- مشخصه (spec) و برند (brand) جدا از متریال و جدا از هم استخراج شوند.
|
||
- وظیفه‌ی تطبیق با موجودیت‌های سیستم بر عهده‌ی تو نیست؛ هیچ نامی را به نزدیک‌ترین نام موجود «حدس» نزن.
|
||
|
||
شکل patch برای intent="register_quote"/"update_draft":
|
||
{"supplier_name": str, "project_name": str, "project_names": [str], "is_official": bool, "notes": str, "expiry_days": int, "expiry_date": "YYYY-MM-DD",
|
||
"items": [{"material_name": str, "brand_name": str, "specs": [str], "quantity": number, "unit_name": str, "unit_price": number, "project_name": str, "notes": str}],
|
||
"payment_terms": [{"label": str, "type": "installments|cash_today|deferred_check|other", "installments_count": int, "is_today": bool, "discount_percent": number, "discount_type": "none|percent|fixed", "discount_value": number, "milestones": [{"due_date": "YYYY-MM-DD", "amount": number, "note": str}], "notes": str}]}
|
||
|
||
شکل patch برای intent="add_supplier":
|
||
{"supplier": {"name": str, "category_name": str, "phone": str, "location": str, "contact_person": str}}
|
||
|
||
شکل patch برای intent="add_material":
|
||
{"material": {"name": str, "unit_name": str, "topic": str}}
|
||
|
||
شکل patch برای intent="add_project":
|
||
{"project": {"name": str, "description": str}}
|
||
|
||
شکل patch برای intent="status_query":
|
||
{"query": {"kind": "pending|accepted|arrived|expiring|recent", "supplier_name": str, "project_name": str, "days": int}}
|
||
|
||
شکل patch برای intent="accept_quote"/"arrive_items":
|
||
{"target": {"supplier_name": str, "project_name": str, "quote_id": str},
|
||
"arrivals": [{"material_name": str, "quantity": number, "quality_note": str}]}
|
||
|
||
{draft_block}
|
||
"""
|
||
|
||
|
||
def _build_system_prompt(draft_summary: str | None) -> str:
|
||
intents = ", ".join(INTENTS)
|
||
prompt = SYSTEM_PROMPT.replace("{intents}", intents).replace("{draft_block}", "")
|
||
if draft_summary:
|
||
prompt += (
|
||
"\n\nپیش‌نویسِ باز فعلی کاربر (اگر مرتبط است به آن تکیه کن و فیلدهای تکراری را بازنویسی نکن):\n"
|
||
+ draft_summary
|
||
)
|
||
return prompt
|
||
|
||
|
||
def _extract_json(raw: str) -> dict | None:
|
||
raw = (raw or "").strip()
|
||
if raw.startswith("```"):
|
||
raw = re.sub(r"^```[a-zA-Z]*\n?", "", raw).rstrip("`").strip()
|
||
start = raw.find("{")
|
||
end = raw.rfind("}")
|
||
if start == -1 or end <= start:
|
||
return None
|
||
try:
|
||
return json.loads(raw[start : end + 1])
|
||
except json.JSONDecodeError:
|
||
return None
|
||
|
||
|
||
async def understand(settings: Settings, text: str | list[dict], draft_summary: str | None = None,
|
||
trace_id: str | None = None) -> dict:
|
||
"""Return {"consensus_text": ..., "intent": ..., "patch": {...}, "confidence": ...}; never raises."""
|
||
fallback = {"consensus_text": "", "intent": "unknown", "patch": {},
|
||
"entity_mentions": [], "confidence": 0.0}
|
||
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)
|
||
elif isinstance(text, str) and ("مدل 1" in text or "مدل ۱" in text) and ("مدل 2" in text or "مدل ۲" in text):
|
||
user_content = (
|
||
"پیام صوتی کاربر توسط چند مدل تبدیل گفتار به متن (STT) به صورت زیر پیاده‌سازی شده است:\n"
|
||
+ normalize_digits(text)
|
||
+ "\n\nبا تلفیق این نسخه‌ها و تصحیح خطاهای شنیداری، پیام را تحلیل کن و consensus_text را به همراه intent و patch بساز."
|
||
)
|
||
first_text = text
|
||
else:
|
||
user_content = normalize_digits(str(text))
|
||
first_text = str(text)
|
||
|
||
fallback["consensus_text"] = first_text
|
||
|
||
if not settings.AI_BASE_URL or not settings.AI_API_KEY:
|
||
logger.warning("AI provider not configured; cannot understand message")
|
||
return fallback
|
||
|
||
system_prompt = _build_system_prompt(draft_summary)
|
||
prompt_hash = hashlib.sha256(
|
||
f"{settings.OBS_PROMPT_VERSION}|{system_prompt}".encode()
|
||
).hexdigest()[:16]
|
||
await obs.event(trace_id, "nlu.request", model=settings.LLM_MODEL, payload={
|
||
"is_multi": isinstance(text, list),
|
||
"content": user_content[:2000],
|
||
"prompt_hash": prompt_hash,
|
||
"prompt_version": settings.OBS_PROMPT_VERSION,
|
||
})
|
||
|
||
try:
|
||
async with httpx.AsyncClient(timeout=settings.LLM_TIMEOUT_SECONDS) as client:
|
||
resp = await client.post(
|
||
f"{settings.AI_BASE_URL.rstrip('/')}/chat/completions",
|
||
headers={"Authorization": f"Bearer {settings.AI_API_KEY}"},
|
||
json={
|
||
"model": settings.LLM_MODEL,
|
||
"messages": [
|
||
{"role": "system", "content": system_prompt},
|
||
{"role": "user", "content": user_content},
|
||
],
|
||
"temperature": 0.1,
|
||
"response_format": {"type": "json_object"},
|
||
},
|
||
)
|
||
if resp.status_code != 200:
|
||
logger.error("LLM HTTP %s: %s", resp.status_code, resp.text[:300])
|
||
await obs.event(trace_id, "nlu.result", ok=False, model=settings.LLM_MODEL,
|
||
payload={"error": f"HTTP {resp.status_code}", "body": resp.text[:300]})
|
||
raise NLUFailureError(f"HTTP {resp.status_code}")
|
||
content = ((resp.json() or {}).get("choices") or [{}])[0].get("message", {}).get("content", "")
|
||
parsed = _extract_json(content)
|
||
if not parsed or parsed.get("intent") not in INTENTS:
|
||
logger.warning("unparseable LLM output: %r", content[:200])
|
||
await obs.event(trace_id, "nlu.result", ok=False, model=settings.LLM_MODEL,
|
||
payload={"error": "unparseable", "raw": content[:500]})
|
||
raise NLUFailureError("unparseable LLM output")
|
||
parsed.setdefault("patch", {})
|
||
parsed["entity_mentions"] = sanitize_mentions(parsed.get("entity_mentions"))
|
||
if not parsed.get("consensus_text"):
|
||
parsed["consensus_text"] = first_text
|
||
await obs.event(trace_id, "nlu.result", ok=True, model=settings.LLM_MODEL, payload={
|
||
"intent": parsed.get("intent"),
|
||
"confidence": parsed.get("confidence"),
|
||
"patch": parsed.get("patch"),
|
||
"consensus_text": parsed.get("consensus_text"),
|
||
"entity_mentions": parsed.get("entity_mentions"),
|
||
})
|
||
return parsed
|
||
except Exception as exc:
|
||
if isinstance(exc, NLUFailureError):
|
||
raise
|
||
logger.exception("NLU failure")
|
||
await obs.event(trace_id, "nlu.result", ok=False, model=settings.LLM_MODEL,
|
||
payload={"error": "exception", "details": str(exc)})
|
||
raise NLUFailureError(f"NLU exception: {exc}") from exc
|