Create message_understanding.py

knowledge/message_understanding.py

@@ -0,0 +1,508 @@
+from typing import Optional
+
+
+def normalize_text(text: str) -> str:
+    return (text or "").strip().lower()
+
+
+def contains_any(text: str, keywords: list) -> bool:
+    return any(k in text for k in keywords)
+
+
+def is_yes(text: str) -> bool:
+    t = normalize_text(text)
+    return t in [
+        "نعم", "اه", "أه", "ايوه", "أيوه", "yes", "y",
+        "درست", "اه درست", "أيوه درست"
+    ]
+
+
+def is_no(text: str) -> bool:
+    t = normalize_text(text)
+    return t in [
+        "لا", "لأ", "لاا", "no", "n",
+        "مدرستش", "ما درستش", "لا مدرستش"
+    ]
+
+
+def is_new_student(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "طالب جديد", "جديد", "عميل جديد", "اول مرة", "أول مرة",
+        "لسه جديد", "مشترك جديد"
+    ])
+
+
+def is_current_student(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "طالب حالي", "حالي", "عميل حالي", "مشترك", "مشترك حالي",
+        "أنا طالب", "انا طالب عندكم", "انا مشترك"
+    ])
+
+
+def is_adults(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "كبار", "adult", "adults", "الكبار", "كورسات الكبار"
+    ])
+
+
+def is_children(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "اطفال", "أطفال", "طفل", "children", "kids",
+        "كورسات الأطفال", "كورسات الاطفال"
+    ])
+
+
+def is_support_request(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "استفسار", "سؤال", "عندي سؤال", "مشكلة", "مش فاهم",
+        "عايز اسأل", "عايزة اسأل", "محتاج مساعدة", "محتاجه مساعدة",
+        "support", "خدمة العملاء"
+    ])
+
+
+def is_next_level_booking(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "حجز", "احجز", "المستوى التالي", "مستوى تالي",
+        "next level", "احجز المستوى", "حجز مستوى"
+    ])
+
+
+def is_complaint(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "شكوى", "اشتكي", "اشتك", "مشكلة كبيرة", "complaint"
+    ])
+
+
+def wants_direct_support(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "تواصل", "اكلم", "عايز حد يكلمني", "عايزة حد يكلمني",
+        "عايز اكلم خدمة العملاء", "عايزة اكلم خدمة العملاء"
+    ])
+
+
+def wants_start(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "ابدأ", "ابدا", "مساعدة", "مساعده", "start", "menu", "القائمة"
+    ])
+
+
+def wants_restart(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "من جديد", "ابدأ من جديد", "restart", "مينيو", "القائمة", "ابدأ"
+    ])
+
+
+def wants_new_topic(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "عايز اسال عن حاجة تانية",
+        "عايزة اسال عن حاجة تانية",
+        "استفسار جديد",
+        "موضوع تاني",
+        "حاجة تانية"
+    ])
+
+
+def wants_courses_info(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "كورسات",
+        "الكورسات",
+        "ايه الكورسات",
+        "ما هي الكورسات",
+        "الأنواع",
+        "الانواع",
+        "عايز اعرف الكورسات",
+        "عايزة اعرف الكورسات",
+        "ايه الكورسات المتاحة",
+        "الكورسات المتاحة"
+    ])
+
+
+def asks_about_prior_study_case(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "لو كنت درست",
+        "لو كنت دارس",
+        "لو درست قبل كده",
+        "طب لو درست",
+        "ولو درست",
+        "اذا كنت درست",
+        "إذا كنت درست",
+        "اختبار تحديد مستوى",
+        "تحديد مستوى"
+    ])
+
+
+def asks_about_beginner_case(text: str) -> bool:
+    t = normalize_text(text)
+    return contains_any(t, [
+        "لو مكنتش درست",
+        "لو ما درستش",
+        "لو مدرستش",
+        "لو لسه جديد",
+        "لو مبتدئ",
+        "لو بادئ",
+        "لو اول مرة",
+        "لو أول مرة"
+    ])
+
+
+def detect_level(text: str) -> Optional[str]:
+    t = normalize_text(text)
+
+    if contains_any(t, ["1a", "a1", "a1.1", "1 a"]):
+        return "1A"
+
+    if contains_any(t, ["2a", "a2", "a1.2", "2 a"]):
+        return "2A"
+
+    if contains_any(t, ["1b", "b1", "b1.1", "1 b"]):
+        return "1B"
+
+    if contains_any(t, ["1c", "2b", "b2", "1c2/b", "1 c", "2 b"]):
+        return "1C2/B"
+
+    return None
+
+
+def detect_payment_method(text: str) -> Optional[str]:
+    t = normalize_text(text)
+
+    if contains_any(t, ["فرع", "فروع", "كاش", "cash"]):
+        return "branch_or_cash"
+
+    if contains_any(t, ["تحويل", "بنكي", "bank", "transfer"]):
+        return "bank_transfer"
+
+    if contains_any(t, ["فودافون", "vodafone", "vodafone cash"]):
+        return "vodafone_cash"
+
+    if contains_any(t, ["فيزا", "visa", "ماستر", "master", "credit card", "card"]):
+        return "card"
+
+    if contains_any(t, ["تقسيط", "value", "فاليو"]):
+        return "installments"
+
+    return None
+
+
+def classify_message(state: str, text: str, flow_data: dict | None = None):
+    """
+    Returns a structured classification:
+    {
+      "kind": "direct_answer" | "state_switch" | "topic_switch" | "unclear",
+      "value": str | None,
+      "confidence": float,
+      "entities": dict
+    }
+    """
+    flow_data = flow_data or {}
+    t = normalize_text(text)
+
+    # ===== Global topic switches =====
+    if wants_restart(t):
+        return {
+            "kind": "topic_switch",
+            "value": "restart",
+            "confidence": 0.99,
+            "entities": {}
+        }
+
+    if wants_new_topic(t):
+        return {
+            "kind": "topic_switch",
+            "value": "new_topic",
+            "confidence": 0.95,
+            "entities": {}
+        }
+
+    if is_complaint(t):
+        return {
+            "kind": "topic_switch",
+            "value": "complaint",
+            "confidence": 0.98,
+            "entities": {}
+        }
+
+    if wants_direct_support(t):
+        return {
+            "kind": "topic_switch",
+            "value": "direct_support",
+            "confidence": 0.95,
+            "entities": {}
+        }
+
+    if wants_courses_info(t):
+        return {
+            "kind": "topic_switch",
+            "value": "courses_info",
+            "confidence": 0.90,
+            "entities": {}
+        }
+
+    if is_children(t):
+        return {
+            "kind": "topic_switch",
+            "value": "children_courses",
+            "confidence": 0.88,
+            "entities": {"audience": "children"}
+        }
+
+    if is_adults(t):
+        return {
+            "kind": "topic_switch",
+            "value": "adults_courses",
+            "confidence": 0.88,
+            "entities": {"audience": "adults"}
+        }
+
+    if is_new_student(t):
+        return {
+            "kind": "topic_switch",
+            "value": "new_student",
+            "confidence": 0.90,
+            "entities": {"customer_type": "new"}
+        }
+
+    if is_current_student(t):
+        return {
+            "kind": "topic_switch",
+            "value": "current_student",
+            "confidence": 0.90,
+            "entities": {"customer_type": "current"}
+        }
+
+    # ===== State-specific understanding =====
+    if state == "WAITING_USER_TYPE":
+        if is_new_student(t):
+            return {
+                "kind": "direct_answer",
+                "value": "new_student",
+                "confidence": 0.95,
+                "entities": {"customer_type": "new"}
+            }
+        if is_current_student(t):
+            return {
+                "kind": "direct_answer",
+                "value": "current_student",
+                "confidence": 0.95,
+                "entities": {"customer_type": "current"}
+            }
+
+    if state == "WAITING_AUDIENCE":
+        if is_adults(t):
+            return {
+                "kind": "direct_answer",
+                "value": "adults",
+                "confidence": 0.95,
+                "entities": {"audience": "adults"}
+            }
+        if is_children(t):
+            return {
+                "kind": "direct_answer",
+                "value": "children",
+                "confidence": 0.95,
+                "entities": {"audience": "children"}
+            }
+
+    if state == "WAITING_PRIOR_STUDY":
+        if is_yes(t):
+            return {
+                "kind": "direct_answer",
+                "value": "prior_study_yes",
+                "confidence": 0.96,
+                "entities": {"prior_study": True}
+            }
+        if is_no(t):
+            return {
+                "kind": "direct_answer",
+                "value": "prior_study_no",
+                "confidence": 0.96,
+                "entities": {"prior_study": False}
+            }
+
+    if state in [
+        "WAITING_BEGINNER_SCHEDULE_CHOICE",
+        "WAITING_PDF_102_CONFIRMATION",
+        "WAITING_PLACEMENT_TEST_CONFIRMATION",
+    ]:
+        if asks_about_prior_study_case(t):
+            return {
+                "kind": "state_switch",
+                "value": "switch_to_prior_study_true",
+                "confidence": 0.92,
+                "entities": {"prior_study": True}
+            }
+
+        if asks_about_beginner_case(t):
+            return {
+                "kind": "state_switch",
+                "value": "switch_to_prior_study_false",
+                "confidence": 0.92,
+                "entities": {"prior_study": False}
+            }
+
+    if state == "WAITING_BEGINNER_SCHEDULE_CHOICE":
+        if contains_any(t, ["تم", "اخترت", "اختارت", "جاهز", "جاهزة"]):
+            return {
+                "kind": "direct_answer",
+                "value": "confirm_schedule_reviewed",
+                "confidence": 0.92,
+                "entities": {}
+            }
+
+        if contains_any(t, ["عايز احجز", "عايزة احجز", "احجز", "حجز", "اشترك", "اشتراك"]):
+            return {
+                "kind": "direct_answer",
+                "value": "proceed_booking",
+                "confidence": 0.90,
+                "entities": {}
+            }
+
+        if is_support_request(t):
+            return {
+                "kind": "state_switch",
+                "value": "support_needed",
+                "confidence": 0.88,
+                "entities": {}
+            }
+
+    if state == "WAITING_PDF_102_CONFIRMATION":
+        if contains_any(t, ["تم", "خلصت", "قريت", "اطلعت", "جاهز", "جاهزة"]):
+            return {
+                "kind": "direct_answer",
+                "value": "confirm_pdf_reviewed",
+                "confidence": 0.92,
+                "entities": {}
+            }
+
+        if is_support_request(t):
+            return {
+                "kind": "state_switch",
+                "value": "support_needed",
+                "confidence": 0.88,
+                "entities": {}
+            }
+
+    if state == "WAITING_PLACEMENT_TEST_CONFIRMATION":
+        if contains_any(t, ["تم", "اخترت", "اختارت", "جاهز", "جاهزة"]):
+            return {
+                "kind": "direct_answer",
+                "value": "confirm_placement_test_reviewed",
+                "confidence": 0.92,
+                "entities": {}
+            }
+
+        if is_support_request(t):
+            return {
+                "kind": "state_switch",
+                "value": "support_needed",
+                "confidence": 0.88,
+                "entities": {}
+            }
+
+    if state == "WAITING_CURRENT_STUDENT_ACTION":
+        if is_support_request(t):
+            return {
+                "kind": "direct_answer",
+                "value": "current_student_support",
+                "confidence": 0.92,
+                "entities": {}
+            }
+
+        if is_next_level_booking(t):
+            return {
+                "kind": "direct_answer",
+                "value": "current_student_next_level",
+                "confidence": 0.92,
+                "entities": {}
+            }
+
+    if state == "WAITING_SUPPORT_QUESTION":
+        if t:
+            return {
+                "kind": "direct_answer",
+                "value": "support_question_text",
+                "confidence": 0.85,
+                "entities": {"support_question": text}
+            }
+
+    if state == "WAITING_LEVEL_SELECTION":
+        level = detect_level(t)
+        if level:
+            return {
+                "kind": "direct_answer",
+                "value": "level_selected",
+                "confidence": 0.95,
+                "entities": {"selected_level": level}
+            }
+
+        if is_support_request(t) or contains_any(t, ["مش عارف", "مش متأكد", "مش متاكدة"]):
+            return {
+                "kind": "state_switch",
+                "value": "support_needed",
+                "confidence": 0.85,
+                "entities": {}
+            }
+
+    if state == "WAITING_PAYMENT_METHOD":
+        payment_method = detect_payment_method(t)
+        if payment_method:
+            return {
+                "kind": "direct_answer",
+                "value": "payment_method_selected",
+                "confidence": 0.95,
+                "entities": {"payment_method": payment_method}
+            }
+
+        if is_support_request(t):
+            return {
+                "kind": "state_switch",
+                "value": "support_needed",
+                "confidence": 0.85,
+                "entities": {}
+            }
+
+    if state == "WAITING_COMPLAINT_FORM":
+        if contains_any(t, ["تم", "خلصت", "سجلت", "قدمت", "بعت"]):
+            return {
+                "kind": "direct_answer",
+                "value": "complaint_form_submitted",
+                "confidence": 0.90,
+                "entities": {}
+            }
+
+    if state == "HANDOFF_DONE":
+        if contains_any(t, ["شكرا", "متشكر", "تسلم", "ميرسي"]):
+            return {
+                "kind": "direct_answer",
+                "value": "thanks",
+                "confidence": 0.95,
+                "entities": {}
+            }
+
+        if is_support_request(t):
+            return {
+                "kind": "topic_switch",
+                "value": "direct_support",
+                "confidence": 0.90,
+                "entities": {}
+            }
+
+    return {
+        "kind": "unclear",
+        "value": None,
+        "confidence": 0.30,
+        "entities": {}
+    }