Merge pull request 'feat(precedents): citation_formatted דטרמיניסטי בקוד — Gemini מחלץ רכיבים, לא מעצב (#145)' (#262) from worktree-precedent-deterministic-citation into main

mcp-server/src/legal_mcp/services/precedent_metadata_extractor.py

@@ -1,12 +1,18 @@
 """Auto-extract precedent metadata from a freshly-uploaded ruling.
 
-Runs after chunking. Reads the precedent's full_text and asks Claude to
+Runs after chunking. Reads the precedent's full_text and asks Gemini to
 fill in the metadata fields that an upload form usually leaves empty:
 short case_name, summary, headnote, key_quote, subject_tags,
 appeal_subtype, decision_date, precedent_level, court — plus
 chair_name + district for internal_committee rows (which the upload
 path stamps with PLACEHOLDER_PENDING_EXTRACTION when missing).
 
+The full citation (citation_formatted) is NOT formatted by the LLM — a Flash
+model reliably extracts the party line but drops the formatted string outright
+(#145). Instead the LLM extracts COMPONENTS (parties, citation_prefix) and
+``apply_to_record`` assembles the citation deterministically via
+``db.format_precedent_citation`` (X1 §3 / INV-ID2 — a derived display field).
+
 Caller policy: only empty user-supplied fields are filled. Anything the
 chair already typed in the upload form is preserved. This is enforced
 in ``apply_to_record``.
@@ -64,7 +70,8 @@ METADATA_EXTRACTION_PROMPT = """אתה מסייע משפטי בכיר. קרא א
   "case_number_clean": "מספר הערר/תיק כפי שמופיע בכותרת — רק הספרות והאלכסון, למשל '1062/24' או '8031/21'. ללא המילה 'ערר', ללא שם הצדדים, ללא סוגריים. אם יש כמה עררים מאוחדים — הרשום הראשון. מחרוזת ריקה אם לא ניתן לזהות.",
   "chair_name": "שם יו\\\"ר ההרכב — רלוונטי **רק להחלטות ועדת ערר**, לא לפסקי בית משפט. חפש בכותרת/חתימה: 'עו\\\"ד דפנה תמיר, יו\\\"ר ועדת הערר', 'בפני: עו\\\"ד פלוני אלמוני (יו\\\"ר)'. השאר שם פרטי+משפחה בלי תוארים ('עו\\\"ד', 'אדריכל'). אם זה פסק דין של בית משפט — מחרוזת ריקה.",
   "district": "מחוז ועדת הערר — רלוונטי **רק להחלטות ועדת ערר**. ערכים מותרים: 'ירושלים', 'תל אביב', 'מרכז', 'חיפה', 'צפון', 'דרום', 'ארצית'. זהה מהכותרת ('ועדת הערר לתכנון ובניה — מחוז ירושלים' → 'ירושלים'; 'ועדות ערר - תכנון ובנייה תל אביב-יפו' → 'תל אביב'). אם זה פסק דין של בית משפט — מחרוזת ריקה.",
-  "citation_formatted": "המראה מקום המלא לפי **כללי הציטוט האחיד**, בפורמט Markdown — שמות הצדדים בלבד מוקפים בכפול-כוכבית (`**…**`), הכל השאר רגיל. ראה כללים מפורטים בסעיף 12 למטה."
+  "parties": "שמות הצדדים בשורה אחת בצורה 'עורר נ\\' משיב' — בדיוק כפי שמופיעים בכותרת/רובריקה. בלי הדגשה, בלי מספר-תיק, בלי תוארים מיותרים. למשל 'ישיבת חברת אהבת שלום נ\\' תאיה' או 'ראם חיים נ\\' הוועדה המקומית לתכנון ובניה ירושלים'. אם הצדדים אינם מופיעים בטקסט (למשל החלטה שמתחילה בגוף בלי רובריקה) — מחרוזת ריקה. **אל תמציא שמות.**",
+  "citation_prefix": "קידומת-ההליך של פסיקת בית-משפט בלבד, כפי שמופיעה בראש הכותרת: ע\\"א / רע\\"א / בג\\"ץ / עע\\"מ / עת\\"מ / ע\\"פ / דנ\\"א / ת\\"א וכד'. **רק לפסקי בית-משפט (עליון/מנהלי)** — להחלטות ועדת-ערר השאר ריק (הקוד גוזר 'ערר'/'בל\\"מ' מעצמו). אם לא ברור — מחרוזת ריקה."
 }
 
 ## כללי איכות
@@ -80,22 +87,10 @@ METADATA_EXTRACTION_PROMPT = """אתה מסייע משפטי בכיר. קרא א
 10. **court** — מהכותרת הראשית של הפסק. ניסוח מלא (לא קיצור). מחרוזת ריקה אם לא ניתן לזהות.
 11. **proceeding_type** — חובה לזהות עבור החלטות ועדת ערר; ריק עבור פסיקת בית משפט. הסימן הברור: בכותרת הראשונה של המסמך כתוב "ערר (ועדות ערר ...) NNNN/YY" → 'ערר'; "בל\"מ NNNN/YY" או הנושא "בקשה להארכת מועד להגשת ערר" → 'בל\"מ'. שני הסוגים יכולים לחלוק אותו מספר תיק — לכן חשוב להבחין מפורשות.
 12. **chair_name / district** — חובה למלא רק עבור החלטות ועדת ערר (source_type='appeals_committee'). chair_name נמצא בכותרת ("בפני: עו\"ד פלוני אלמוני, יו\"ר") או בחתימה. district = מחוז הוועדה, מתוך רשימה סגורה. עבור פסקי בית משפט — שני השדות ריקים.
-13. **citation_formatted — כללי הציטוט האחיד הישראלי**. הרכב את המראה מקום במחרוזת אחת בפורמט Markdown, **כשרק שמות הצדדים מודגשים** (מוקפים ב-`**…**`). כל השאר — קיצור הערכאה, סוגריים של הרכב/מחוז, מספר תיק, מאגר/תאריך — **רגיל ללא הדגשה**.
-
-   תבניות לסוגי פסיקה:
-   * **בית משפט עליון — לא פורסם:** `ע"א 1234/56 **פלוני נ' אלמוני** (נבו 1.2.3456)`
-   * **בית משפט עליון — פורסם:** `ע"א 1234/56 **פלוני נ' אלמוני**, פ"ד יב(3) 456 (1990)`
-   * **בית משפט מנהלי:** `עת"מ (י-ם) 1234/56 **פלוני נ' הוועדה** (נבו 1.2.3456)` — "(י-ם)" / "(ת"א)" / וכד' = קיצור המחוז
-   * **ועדת ערר תכנון ובנייה (מחוזית):** `ערר (ועדות ערר - תכנון ובנייה ת"א-יפו) 81002-01-21 **אברהם אגסי נ' הועדה המקומית לתכנון ובנייה תל אביב** (נבו 25.9.2025)`
-   * **בל"מ (בקשה להארכת מועד):** `בל"מ (ועדות ערר - ירושלים) 1028/20 **חלוואני ריאד נ' רשות הרישוי - הוועדה המקומית ירושלים** (נבו 7.1.2021)`
-   * **ועדת ערר ארצית:** `ערר ארצי 8047/23 **פלוני נ' אלמוני** (נבו 1.2.3456)`
-
-   כללים:
-   - **הצדדים מודגשים בלבד** — כל השאר רגיל. אל תדגיש את "ע"א" / "ערר" / מספר התיק / "(נבו ...)" / "פ"ד".
-   - הצדדים = מי שמופיע **בין מספר התיק לבין הסוגריים הסופיים** (תאריך/מאגר), כלומר "[עורר/מבקש] נ' [משיב]".
-   - תאריך בסוגריים סופיים בפורמט עברי "(נבו 25.9.2025)" — יום.חודש.שנה ללא אפסים מובילים.
-   - אם המאגר הוא נבו והפסיקה לא פורסמה ב-פ"ד — השתמש ב-"(נבו DATE)". אם פורסמה ב-פ"ד — הוסף את ההפניה הפורמלית אחרי הצדדים: `..., פ"ד יב(3) 456 (1990)`.
-   - אם לא ניתן לזהות איזשהו רכיב במדויק — השאר את **כל** השדה ריק. אל תניח / תמציא.
+13. **parties / citation_prefix — רכיבי המראה-מקום (לא המראה-מקום עצמו)**. אינך מרכיב את הציטוט המעוצב — המערכת מרכיבה אותו דטרמיניסטית מהרכיבים. עליך רק **לחלץ** שני רכיבים נקיים:
+   - **parties** — שורת הצדדים "[עורר/מבקש] נ' [משיב]" כפי שמופיעה בכותרת/רובריקה. בלי מספר-תיק, בלי קידומת-הליך, בלי הדגשה. הצדדים = מי שמופיע בין מספר-התיק לבין שם-הערכאה/התאריך. אם אין רובריקה עם צדדים (החלטה שפותחת ישר בגוף) — השאר ריק; **אל תמציא שמות**.
+   - **citation_prefix** — קידומת-ההליך **רק לפסקי בית-משפט** (ע"א / רע"א / בג"ץ / עע"מ / עת"מ / ע"פ / דנ"א / ת"א…), כפי שכתובה בראש הכותרת. להחלטות ועדת-ערר — ריק (המערכת גוזרת 'ערר'/'בל"מ' מ-proceeding_type).
+   - שניהם רשות; ריק עדיף על ניחוש (INV-AH — abstention על המצאה).
 """
 
 
@@ -210,14 +205,14 @@ async def extract_metadata(case_law_id: UUID | str) -> dict:
         # silently storing free-text in what callers treat as a filter facet.
         if d in {"ירושלים", "תל אביב", "מרכז", "חיפה", "צפון", "דרום", "ארצית"}:
             out["district"] = d
-    if isinstance(result.get("citation_formatted"), str):
-        cf = result["citation_formatted"].strip()
-        # Sanity check: a valid citation should contain at least one bold
-        # marker pair (the parties) AND a closing paren (the reporter/date).
-        # If the LLM returned a half-formed string, drop it rather than
-        # store junk that the UI then has to special-case.
-        if cf.count("**") >= 2 and ")" in cf:
-            out["citation_formatted"] = cf
+    # parties / citation_prefix — COMPONENTS of the citation, not the formatted
+    # string. citation_formatted itself is assembled deterministically by
+    # db.format_precedent_citation in apply_to_record (#145): a Flash model reliably
+    # extracts the party line but dropped the formatted citation outright.
+    if isinstance(result.get("parties"), str):
+        out["parties"] = result["parties"].strip()
+    if isinstance(result.get("citation_prefix"), str):
+        out["citation_prefix"] = result["citation_prefix"].strip()
     return out
 
 
@@ -371,12 +366,12 @@ async def apply_to_record(
     ):
         fields_to_update["case_number"] = cn_clean
 
-    # citation_formatted — full citation per Israeli citation rules. Only
-    # fill if empty; user edits in /precedents/[id] are preserved.
-    if not (record.get("citation_formatted") or "").strip():
-        s = (suggested.get("citation_formatted") or "").strip()
-        if s:
-            fields_to_update["citation_formatted"] = s
+    # parties — store the extracted "עורר נ' משיב" line (the re-derivable basis for
+    # the deterministic citation). Only fill when empty; chair edits are preserved.
+    if not (record.get("parties") or "").strip():
+        p = (suggested.get("parties") or "").strip()
+        if p:
+            fields_to_update["parties"] = p
 
     # chair_name / district — only for internal_committee rows. The DB CHECK
     # forces these to be non-empty, so the upload endpoint stamps the row
@@ -414,6 +409,25 @@ async def apply_to_record(
         if eff_st != derived_st:
             fields_to_update["source_type"] = derived_st
 
+    # citation_formatted — DERIVED deterministically from the effective record
+    # (db.format_precedent_citation), NEVER formatted by the LLM (#145, INV-ID2).
+    # Built last, so it sees this run's component updates (case_number/date/level/
+    # source_type/district/proceeding_type/parties). Only fill when empty so chair
+    # edits in /precedents/[id] are preserved; abstains (no write) when a component
+    # is missing.
+    if not (record.get("citation_formatted") or "").strip():
+        eff = {**record, **fields_to_update}
+        eff_parties = (
+            fields_to_update.get("parties") or record.get("parties") or ""
+        ).strip()
+        cit = db.format_precedent_citation(
+            eff,
+            parties=eff_parties,
+            court_prefix=(suggested.get("citation_prefix") or "").strip(),
+        )
+        if cit:
+            fields_to_update["citation_formatted"] = cit
+
     if not fields_to_update:
         return {"updated": False, "fields": []}