feat(extraction): map_roles — orchestrateur VLM ancrage strict (client injectable)

build_role_prompt (modes libre / guidé par rôles), parse_vlm_json (robuste :
tolère les fences, {} si invalide), map_roles (prompt -> VLM -> parse -> reconstruct).
Client VLM injecté => testable hors-ligne. 6 tests unit ajoutés (15 au total).
Non branché au runtime (brique validée isolément).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

core/extraction/role_mapper.py

@@ -12,8 +12,9 @@ est orchestré ailleurs (et mockable), pour rester testable hors-ligne.
 """
 from __future__ import annotations
 
+import json
 from dataclasses import dataclass
-from typing import List, Optional, Sequence, Tuple
+from typing import Callable, List, Optional, Sequence, Tuple
 
 BBox = Tuple[int, int, int, int]  # (x_min, y_min, x_max, y_max)
 
@@ -121,3 +122,86 @@ def reconstruct_fields(
             invalid_ids=invalid,
         ))
     return out
+
+
+# --- Orchestration VLM (client injectable pour rester testable hors-ligne) ---
+
+# Un client VLM est un callable (image_path, prompt) -> texte de réponse.
+VlmClient = Callable[[str, str], str]
+
+
+def build_role_prompt(
+    tokens: Sequence[OcrToken],
+    roles: Optional[Sequence[str]] = None,
+) -> str:
+    """Construit le prompt d'attribution de rôles (ancrage strict par ids).
+
+    Mode *guidé* si `roles` est fourni (rôles attendus de l'écran), sinon *libre*
+    (le VLM nomme lui-même les champs). Dans les deux cas le VLM ne renvoie que
+    des `value_ids` — jamais de texte recopié.
+    """
+    ocr_list = [{"id": t.id, "text": t.text} for t in tokens]
+    if roles:
+        roles_line = (
+            "Rôles attendus sur cet écran (associe chacun s'il est présent) : "
+            + ", ".join(roles) + ".\n"
+        )
+    else:
+        roles_line = (
+            "Identifie librement les champs présents — le 'label' est le rôle du champ.\n"
+        )
+    return (
+        "Tu reçois une capture d'écran d'un dossier patient et la liste des tokens "
+        "détectés par OCR (chaque token : id, text).\n"
+        + roles_line +
+        "Pour chaque champ, désigne les tokens OCR qui composent sa VALEUR.\n"
+        "RÈGLES STRICTES :\n"
+        "- Tu ne recopies AUCUN texte. Tu renvoies seulement 'value_ids' : la liste "
+        "des id de tokens OCR (dans l'ordre de lecture) qui forment la valeur.\n"
+        "- 'label' = le rôle du champ. N'invente aucun champ.\n"
+        "- Réponds UNIQUEMENT en JSON PLAT :\n"
+        '{"ecran":"<type en 3 mots>","champs":[{"label":"...","value_ids":[<int>,...]}]}\n\n'
+        "Tokens OCR :\n" + json.dumps(ocr_list, ensure_ascii=False)
+    )
+
+
+def parse_vlm_json(text: str) -> dict:
+    """Extrait le 1er objet JSON d'une réponse VLM (tolère les fences ```json).
+
+    Robuste : renvoie `{}` si la réponse n'est pas du JSON exploitable (pas de
+    crash en batch).
+    """
+    if not text:
+        return {}
+    s = text.strip()
+    if "```" in s:
+        parts = s.split("```")
+        if len(parts) >= 2:
+            s = parts[1]
+            if s.lstrip().lower().startswith("json"):
+                s = s.lstrip()[4:]
+    a, b = s.find("{"), s.rfind("}")
+    if a < 0 or b <= a:
+        return {}
+    try:
+        return json.loads(s[a:b + 1])
+    except (ValueError, TypeError):
+        return {}
+
+
+def map_roles(
+    image_path: str,
+    tokens: Sequence[OcrToken],
+    vlm_client: VlmClient,
+    roles: Optional[Sequence[str]] = None,
+) -> List[MappedField]:
+    """Orchestre l'attribution de rôles : prompt → VLM → parse → reconstruction ancrée.
+
+    `vlm_client` est injecté (testable hors-ligne). Le résultat est toujours
+    ancré sur l'OCR via `reconstruct_fields`.
+    """
+    prompt = build_role_prompt(tokens, roles)
+    raw = vlm_client(image_path, prompt)
+    data = parse_vlm_json(raw)
+    vlm_fields = data.get("champs", []) if isinstance(data, dict) else []
+    return reconstruct_fields(tokens, vlm_fields)