Skip to content

[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons

Python
31.4 KB
Raw Blame
"""Pick the facing-direction joint pair for each rig with a Language Model.

Complement to the rule-based :mod:`face_select_rule`: asks an LLM to choose ONE
bilaterally symmetric joint pair (hip / shoulder / wing / fin / ...) that
defines the rig's lateral axis for heading-angle computation. For serpentine
rigs with no bilateral symmetry, the LLM picks longitudinal body-axis
endpoints (head-tip / tail-tip) and sets ``body_axis: true``.

Backends (see :mod:`llm`): DeepSeek API (default: ``deepseek-v4-flash``),
OpenAI API, or a local HF causal LM.

Inputs :
    ``joint_names.json``       — ``{rig_id: [raw_joint_name, ...]}``
    ``clean_joint_names.json`` — ``{rig_id: [clean_joint_name, ...]}``
Output :
    ``face_joint_names.json``  — ``{rig_id: {r_hip, l_hip, source, [body_axis]}}``

Pipeline per rig:
  1. Pre-filter the joint list into four small buckets (Right / Left /
     Head / Tail candidates). Dozens-of-joint rigs collapse to a handful.
  2. Short-circuit 'empty' if no candidates survive (no LLM call).
  3. Otherwise send only the compact candidate list to the LLM, together
     with the rule-based pick as a hint, and ask it to apply a three-step
     decision (bilateral -> body-axis -> empty).
  4. Validate the response (raw names must appear verbatim in the input);
     retry with a structured correction on failure.
  5. Fall back to the rule-based resolver after max retries / timeout.

Usage:
    python -m data_process.joint_annotation.face_select_llm \\
        --input_dir <export_dir>                      # DeepSeek v4-flash (default)
    python -m data_process.joint_annotation.face_select_llm \\
        --input_dir <export_dir> --model gpt-5-mini
    python -m data_process.joint_annotation.face_select_llm \\
        --input_dir <export_dir> --model Qwen/Qwen3-8B
"""

import argparse
import json
import os
import re
import sys
import time

from loguru import logger
from tqdm import tqdm

_REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
if _REPO_ROOT not in sys.path:
    sys.path.insert(0, _REPO_ROOT)

from data_process.joint_annotation.llm import (  # noqa: E402
    FatalLLMError,
    LLMClient,
    MAX_RETRIES,
    RigTimeout,
    add_llm_args,
    append_id_list,
    install_rig_alarm,
    load_json,
    read_id_list,
    save_json,
    strip_llm_noise,
    uninstall_rig_alarm,
)
from data_process.joint_annotation.face_select_rule import (  # noqa: E402
    HEAD_KEYWORDS,
    TAIL_KEYWORDS,
    empty_entry,
    resolve_face_joints,
    strip_trailing_num,
)


# ─────────────────────────────────────────────────────────────────────────────
# System prompt
# ─────────────────────────────────────────────────────────────────────────────

SYSTEM_PROMPT = (
    "# TASK\n"
    "Pick the joint pair that defines one 3D rig's lateral facing axis. "
    "Rigs come from Objaverse (Mixamo, 3ds Max Biped, Maya QuickRig, "
    "Unreal mannequin, CAT, custom) and Truebones animals. All clean "
    "names are already normalised to a canonical vocabulary — reason on "
    "CLEAN names; RAW names are only for verbatim copy-back.\n\n"
    "# INPUT (user message)\n"
    "Four pre-filtered buckets (any may be empty):\n"
    "  RIGHT : rows whose clean name starts with 'Right '\n"
    "  LEFT  : rows whose clean name starts with 'Left '\n"
    "  HEAD  : rows whose clean name (minus any trailing ' N') is one of\n"
    "          {Head, Skull, Skull Base, Head End, Jaw, Upper Jaw,\n"
    "           Lower Jaw, Tongue, Muzzle, Nose, Chin}\n"
    "  TAIL  : rows whose clean name (minus any trailing ' N') is 'Tail'\n"
    "          or 'Tail Twist'\n"
    "Plus a 'Rule-based hint' JSON object — the deterministic resolver's "
    "pick. Use it as a sanity check, not ground truth (see HINT below).\n\n"
    "# ALGORITHM\n"
    "Execute the steps in order. Do not skip ahead.\n"
    "STEP 1. Compute OVERLAP.\n"
    "  - For each row in RIGHT, suffix = clean_name minus 'Right ' "
    "minus any trailing ' <digits>'. Collect into set R_SUFFIXES.\n"
    "  - For each row in LEFT,  suffix = clean_name minus 'Left ' "
    "minus any trailing ' <digits>'. Collect into set L_SUFFIXES.\n"
    "  - OVERLAP = R_SUFFIXES ∩ L_SUFFIXES.\n"
    "STEP 2. If OVERLAP is non-empty — APPLY RULE A AND RETURN.\n"
    "  a. Pick suffix `s` = first element of OVERLAP that appears in "
    "PRIORITY (see below). If none appear, pick the alphabetically "
    "first element of OVERLAP.\n"
    "  b. R_ROWS = RIGHT rows whose suffix == s; L_ROWS = LEFT rows "
    "whose suffix == s.\n"
    "  c. If len(R_ROWS)==1 and len(L_ROWS)==1, pair them.\n"
    "     Otherwise (chain duplicates, e.g. scorpion legs) match by "
    "DIGIT SIGNATURE: the tuple of ALL digit groups in the RAW name "
    "('Bip01_R_Thigh_4' -> (01,4)). Tier 1 — pair rows whose full "
    "signatures are equal. Tier 2 — no tier-1 match: drop the LAST "
    "group (the Objaverse per-joint global index: 'Bip01_R_Thigh_1_053' "
    "and 'Bip01_L_Thigh_1_054' both reduce to (01,1)) and pair on the "
    "rest. If neither tier matches, take R_ROWS[0] and L_ROWS[0].\n"
    "  d. Output: source = s.lower(); body_axis = false.\n"
    "  e. DO NOT consider HEAD or TAIL. Even if HEAD+TAIL look perfect, "
    "rule A wins whenever OVERLAP is non-empty.\n"
    "STEP 3. OVERLAP is empty. If HEAD is non-empty AND TAIL is non-"
    "empty — APPLY RULE B AND RETURN.\n"
    "  - r_hip = LAST HEAD row; l_hip = LAST TAIL row (chain endpoints).\n"
    "  - source = 'body_axis'; body_axis = true.\n"
    "STEP 4. Otherwise — APPLY RULE C (empty).\n"
    "  - Both hips are {raw: '', clean: ''}. source = 'empty'; "
    "body_axis = false.\n"
    "  - Vehicles, props, and abstract rigs land here. NEVER pair an "
    "unrelated Right/Left entry (e.g. lone 'Right Eye' without left "
    "mate) just to avoid emitting empty.\n\n"
    "# PRIORITY (highest → lowest; first match in OVERLAP wins)\n"
    "Hip-level  : thigh, shoulder, front shoulder, back hip, hip, "
    "scapula\n"
    "Whole-limb : upper arm, arm, front leg, hind leg, middle leg, "
    "back leg, wing, leg\n"
    "Aquatic    : pectoral fin, pelvic fin, fin, gill\n"
    "Arthropod  : pincer, mandible, large mandible, lower mandible, "
    "stinger, claw, hand claw, antenna\n"
    "Mid-limb   : forearm, shin, knee, elbow, ankle, wrist\n"
    "Extremity  : hand, palm, foot, heel, front paw, back paw, paw, "
    "front hoof, rear hoof, hoof, fetlock, cannon, metacarpus, "
    "pastern, toe\n"
    "Fingers    : thumb finger, index finger, middle finger, ring "
    "finger, pinky finger, finger, neck\n"
    "Weak       : eye, eyeball, eyelid, eyebrow, ear, horn, cheek, "
    "whisker, fang, barbel, tentacle, feather\n"
    "Last       : tail\n"
    "Suffix comparison is case-insensitive but uses the clean-name form "
    "('Upper Arm', 'Front Shoulder', 'Pectoral Fin'). Read the list above "
    "LITERALLY, left to right, top to bottom — it is exactly the order the "
    "rule-based resolver uses, so do not re-rank quadruped markers "
    "('Front Shoulder', 'Back Hip', 'Front Leg') against their plain "
    "counterparts ('Shoulder', 'Hip', 'Leg'). Note in particular that "
    "'shoulder' comes BEFORE 'front shoulder', while 'front leg' comes "
    "BEFORE 'leg'.\n\n"
    "# HINT\n"
    "The hint is the rule-based resolver's output. It is usually right "
    "but can err on edge cases:\n"
    "  - Hint says 'body_axis' or 'empty' yet OVERLAP is non-empty → "
    "hint is wrong, apply STEP 2 (rule A wins).\n"
    "  - Hint swapped sides (Right/Left in wrong fields) → fix.\n"
    "  - Hint chose a lower-priority suffix than STEP 2a finds → "
    "override with the higher-priority one.\n"
    "  - Hint paired mismatched chain indices on a multi-leg rig → fix "
    "via STEP 2c raw-suffix match.\n"
    "  - Your algorithm yields the same answer as the hint → return "
    "the hint verbatim.\n\n"
    "# OUTPUT\n"
    "Exactly one JSON object, no prose, no markdown fences, no comments:\n"
    '  {"r_hip":    {"raw": "<exact>", "clean": "<exact>"},\n'
    '   "l_hip":    {"raw": "<exact>", "clean": "<exact>"},\n'
    '   "source":   "<lowercase suffix or \'body_axis\' or \'empty\'>",\n'
    '   "body_axis": <true|false>}\n\n'
    "# INVARIANTS (verify before emitting)\n"
    "  I1. r_hip.raw != l_hip.raw, UNLESS both are '' (empty case).\n"
    "  I2. r_hip.raw and l_hip.raw each appear verbatim in the rig's "
    "input rows (copied character-for-character).\n"
    "  I3. r_hip always holds the Right (or head) side; l_hip always "
    "holds the Left (or tail) side. Never swap.\n"
    "  I4. body_axis == true  IFF  source == 'body_axis'.\n"
    "  I5. source is lowercase. If rule A fired, source is the suffix "
    "lowercased with single spaces (e.g. 'thigh', 'front shoulder', "
    "'pectoral fin').\n"
    "  I6. Unless body_axis, r_hip and l_hip mirror the SAME part: "
    "their clean names minus the side prefix and any trailing digits "
    "are identical. Never pair different parts ('Right Thigh' with "
    "'Left Shoulder' is invalid even though the sides are correct).\n\n"
    "# WORKED EXAMPLES\n"
    "## Ex1 — Mixamo humanoid (rule A, hip-level pick)\n"
    "RIGHT has 'Right Thigh' + 'Right Shoulder'; LEFT has the mirrors. "
    "OVERLAP = {Thigh, Shoulder}. Thigh outranks Shoulder → pick Thigh.\n"
    '  {"r_hip": {"raw": "mixamorig:RightUpLeg_056", "clean": '
    '"Right Thigh"},\n'
    '   "l_hip": {"raw": "mixamorig:LeftUpLeg_056",  "clean": '
    '"Left Thigh"},\n'
    '   "source": "thigh", "body_axis": false}\n'
    "## Ex2 — Objaverse quadruped (Front Shoulder beats Back Hip)\n"
    "No Thigh pair; OVERLAP = {Front Shoulder, Back Hip}. Front "
    "Shoulder outranks Back Hip.\n"
    '  {"r_hip": {"raw": "F_R_Shoulder_012", "clean": '
    '"Right Front Shoulder"},\n'
    '   "l_hip": {"raw": "F_L_Shoulder_012", "clean": '
    '"Left Front Shoulder"},\n'
    '   "source": "front shoulder", "body_axis": false}\n'
    "## Ex3 — Scorpion multi-leg (STEP 2c raw-suffix match)\n"
    "RIGHT has three 'Right Thigh' rows (Bip01_R_Thigh_1/_2/_4); LEFT "
    "the mirrors. OVERLAP = {Thigh}. Digit signatures: (01,1) on both "
    "sides -> tier-1 match.\n"
    '  {"r_hip": {"raw": "Bip01_R_Thigh_1", "clean": "Right Thigh"},\n'
    '   "l_hip": {"raw": "Bip01_L_Thigh_1", "clean": "Left Thigh"},\n'
    '   "source": "thigh", "body_axis": false}\n'
    "## Ex4 — OVERRIDE a mistaken body_axis hint\n"
    "RIGHT has 'Right Thigh'; LEFT has 'Left Thigh'; HEAD has 'Tongue'; "
    "TAIL has 'Tail'. Hint = body_axis Tongue+Tail. OVERLAP = {Thigh} "
    "is non-empty → STEP 2 wins, hint is wrong.\n"
    '  {"r_hip": {"raw": "RightUpLeg_033", "clean": "Right Thigh"},\n'
    '   "l_hip": {"raw": "LeftUpLeg_028",  "clean": "Left Thigh"},\n'
    '   "source": "thigh", "body_axis": false}\n'
    "## Ex5 — Snake / serpent (rule B fires)\n"
    "RIGHT and LEFT are empty; HEAD has 'Head'; TAIL has 'Tail_30'. "
    "STEP 3 applies.\n"
    '  {"r_hip": {"raw": "Head",    "clean": "Head"},\n'
    '   "l_hip": {"raw": "Tail_30", "clean": "Tail"},\n'
    '   "source": "body_axis", "body_axis": true}\n'
    "## Ex6 — Vehicle / prop (rule C fires)\n"
    "All sections empty, or only a lone 'Right Eye' with no left mate.\n"
    '  {"r_hip": {"raw": "", "clean": ""},\n'
    '   "l_hip": {"raw": "", "clean": ""},\n'
    '   "source": "empty", "body_axis": false}\n'
)


def prefilter_candidates(raw_names, clean_names):
    # type: (List[str], List[str]) -> Dict[str, List[Dict]]
    """Partition joints into LLM-relevant sections.

    Returns a dict with four keys — ``right``, ``left``, ``head``, ``tail``
    — each a list of ``{"raw": ..., "clean": ...}`` dicts preserving input
    order. Most rigs have 60+ joints but only a handful are candidates for
    the facing direction, so this drastically shortens the LLM's context.
    """
    buckets = {"right": [], "left": [], "head": [], "tail": []}
    for raw, clean in zip(raw_names, clean_names):
        if clean.startswith("Right "):
            buckets["right"].append({"raw": raw, "clean": clean})
            continue
        if clean.startswith("Left "):
            buckets["left"].append({"raw": raw, "clean": clean})
            continue
        base = strip_trailing_num(clean)
        if base in HEAD_KEYWORDS:
            buckets["head"].append({"raw": raw, "clean": clean})
        if base in TAIL_KEYWORDS:
            buckets["tail"].append({"raw": raw, "clean": clean})
    return buckets


def _format_section(name, rows):
    # type: (str, List[Dict]) -> str
    if not rows:
        return "{}: (none)".format(name)
    lines = ["{}:".format(name)]
    for row in rows:
        lines.append("  raw={!r:<40s} clean={!r}".format(row["raw"], row["clean"]))
    return "\n".join(lines)


def build_user_prompt(rig_id, candidates, rule_hint=None, correction=None):
    # type: (str, Dict[str, List[Dict]], Optional[Dict], Optional[str]) -> str
    sections = [
        "Rig identifier: {}".format(rig_id),
        "Candidate counts: right={}  left={}  head={}  tail={}".format(
            len(candidates["right"]), len(candidates["left"]),
            len(candidates["head"]), len(candidates["tail"])),
        "",
        _format_section("RIGHT", candidates["right"]),
        "",
        _format_section("LEFT", candidates["left"]),
        "",
        _format_section("HEAD", candidates["head"]),
        "",
        _format_section("TAIL", candidates["tail"]),
        "",
    ]
    if rule_hint is not None:
        sections.extend([
            "Rule-based hint (deterministic resolver's pick — HINT, not ground truth):",
            json.dumps(rule_hint, ensure_ascii=False, indent=2),
            "",
        ])
        sections.append(
            "Apply rules A -> B -> C and return the JSON object only. If the "
            "hint already satisfies A/B/C, return it verbatim; otherwise override."
        )
    else:
        sections.append(
            "Apply rules A -> B -> C and return the JSON object only."
        )
    prompt = "\n".join(sections)
    if correction:
        prompt += "\n\nIMPORTANT: " + correction
    return prompt


# ─────────────────────────────────────────────────────────────────────────────
# Response parsing
# ─────────────────────────────────────────────────────────────────────────────

def _hip_fields(hip, side):
    # type: (object, str) -> Tuple[str, str]
    if not isinstance(hip, dict):
        raise ValueError("{} is not a JSON object".format(side))
    raw = hip.get("raw", "")
    clean = hip.get("clean", "")
    if not isinstance(raw, str) or not isinstance(clean, str):
        raise ValueError("{} raw/clean must be strings".format(side))
    return raw, clean


def _clean_side(clean_name):
    # type: (str) -> Optional[str]
    """``"Left"`` / ``"Right"`` if the clean label carries a side, else None."""
    if clean_name.startswith("Left "):
        return "Left"
    if clean_name.startswith("Right "):
        return "Right"
    return None


def _validate_sides(r_clean, l_clean, body_axis):
    # type: (str, str, bool) -> None
    """Enforce invariant I3: ``r_hip`` holds the Right (or head) side and
    ``l_hip`` the Left (or tail) side.

    The prompt states I3 but a model can still return a swapped pair, and a
    swap is invisible downstream: ``get_root_facing_quat`` just builds the
    lateral axis the other way round, silently rotating every clip of that
    object type by 180 degrees. Raise ``ValueError`` so the caller retries
    with a correction and, if that fails too, falls back to the rule-based
    resolver.
    """
    if body_axis:
        if (strip_trailing_num(r_clean) in TAIL_KEYWORDS
                or strip_trailing_num(l_clean) in HEAD_KEYWORDS):
            raise ValueError(
                "body-axis pair is swapped: r_hip must be the HEAD end and "
                "l_hip the TAIL end, got r_hip={!r} / l_hip={!r}".format(
                    r_clean, l_clean))
        return
    if _clean_side(r_clean) == "Left" or _clean_side(l_clean) == "Right":
        raise ValueError(
            "left/right pair is swapped: r_hip must be the Right-side joint "
            "and l_hip the Left-side one, got r_hip={!r} / l_hip={!r}".format(
                r_clean, l_clean))


def parse_response(text, raw_names, clean_names):
    # type: (str, List[str], List[str]) -> Dict
    """Extract and validate a ``face_joint_names.json``-shaped object.

    Tolerates markdown fences and ``<think>…</think>`` blocks. Raises
    ``ValueError`` on structural mismatch so the caller can retry or fall
    back. Validation rules:

    - ``r_hip.raw`` / ``l_hip.raw`` must exist verbatim in ``raw_names``
      (or both be ``""`` for the empty sentinel).
    - ``r_hip.raw != l_hip.raw``.
    - The clean name is re-sourced from ``clean_names`` so the LLM can't
      drift the canonical label.
    - The sides are not swapped (invariant I3, see :func:`_validate_sides`).
    - ``body_axis``, when given, is a JSON boolean, true exactly when
      ``source`` is ``'body_axis'`` (invariant I4); omitted, it follows
      ``source``.
    """
    if not text or not text.strip():
        raise ValueError("empty response")

    cleaned = strip_llm_noise(text)
    try:
        data = json.loads(cleaned)
    except json.JSONDecodeError:
        start = cleaned.find("{")
        end = cleaned.rfind("}")
        if start == -1 or end == -1 or end <= start:
            raise ValueError("no JSON object found in response")
        data = json.loads(cleaned[start:end + 1])

    if not isinstance(data, dict):
        raise ValueError("response is not a JSON object")
    for key in ("r_hip", "l_hip", "source"):
        if key not in data:
            raise ValueError("missing key '{}'".format(key))

    r_raw, _ = _hip_fields(data["r_hip"], "r_hip")
    l_raw, _ = _hip_fields(data["l_hip"], "l_hip")
    source = str(data["source"]).strip().lower()
    body_axis = data.get("body_axis")

    if not r_raw and not l_raw:
        return empty_entry()
    if not r_raw or not l_raw:
        raise ValueError("one of r_hip/l_hip is empty; both must be filled "
                         "or both empty for 'empty' source")
    if r_raw == l_raw:
        raise ValueError("r_hip.raw == l_hip.raw ({!r}): pair must be two "
                         "distinct joints".format(r_raw))
    if r_raw not in raw_names:
        raise ValueError("r_hip.raw {!r} not in input raw joint list".format(r_raw))
    if l_raw not in raw_names:
        raise ValueError("l_hip.raw {!r} not in input raw joint list".format(l_raw))

    if body_axis is None:
        body_axis = source == "body_axis"
    elif not isinstance(body_axis, bool):
        # bool("false") is True: a string would turn a lateral pair into a
        # body axis and rotate every clip of the rig by 90 degrees.
        raise ValueError("body_axis must be a JSON boolean, got {!r}".format(body_axis))
    elif body_axis != (source == "body_axis"):
        # Invariant I4: body_axis iff source == 'body_axis'.
        raise ValueError("body_axis={} disagrees with source={!r}".format(
            body_axis, source))

    r_idx = raw_names.index(r_raw)
    l_idx = raw_names.index(l_raw)
    is_axis = body_axis
    _validate_sides(clean_names[r_idx], clean_names[l_idx], is_axis)
    if not is_axis:
        # Invariant I6: a lateral pair must mirror the SAME part — a
        # cross-part pair ('Right Thigh' + 'Left Shoulder') passes the side
        # check yet yields a skewed facing axis.
        r_base = strip_trailing_num(
            re.sub(r'^(Left|Right)\s+', '', clean_names[r_idx]))
        l_base = strip_trailing_num(
            re.sub(r'^(Left|Right)\s+', '', clean_names[l_idx]))
        if r_base.lower() != l_base.lower():
            raise ValueError(
                "r_hip and l_hip are different parts ({!r} vs {!r}); the "
                "pair must be the mirrored copies of one joint".format(
                    clean_names[r_idx], clean_names[l_idx]))
    entry = {
        "r_hip": {"raw": raw_names[r_idx], "clean": clean_names[r_idx]},
        "l_hip": {"raw": raw_names[l_idx], "clean": clean_names[l_idx]},
        "source": source or "pair",
    }
    if body_axis:
        entry["body_axis"] = True
    return entry


# ─────────────────────────────────────────────────────────────────────────────
# Per-rig resolver (retry + rule-based hint + fallback + timeout)
# ─────────────────────────────────────────────────────────────────────────────

def resolve_rig(rig_id, raw_names, clean_names, client, system_prompt=SYSTEM_PROMPT,
                max_tokens=512, max_retries=MAX_RETRIES, timeout_seconds=15,
                fallback_on_error=True, include_hint=True):
    # type: (...) -> Tuple[Dict, bool]
    """Pick the face-direction joint pair for one rig.

    Returns ``(entry, used_fallback)``. Rigs with no Right/Left or
    Head/Tail candidates short-circuit to the empty entry without an LLM
    call. On exhausted retries or timeout the rule-based pick is returned
    (or ``RuntimeError`` is raised when ``fallback_on_error`` is False and
    no timeout occurred).

    ``include_hint=False`` omits the rule-based hint from the prompt (it is
    still computed for the fallback path). The correction pass uses this:
    re-showing the very hint that already produced a wrong/empty entry
    anchors the model on it.
    """
    if not raw_names:
        return empty_entry(), False
    if len(raw_names) != len(clean_names):
        # clean_joint_names is indexed positionally against raw_names; a
        # stale/short list silently pairs the wrong bones (same guard as the
        # rule-based CLI). Abort instead of quietly emitting 'empty'.
        raise ValueError(
            "{!r}: {} cleaned names vs {} raw names — clean_joint_names.json "
            "is stale; re-run the joint-name cleaner.".format(
                rig_id, len(clean_names), len(raw_names)))

    candidates = prefilter_candidates(raw_names, clean_names)
    has_bilateral = bool(candidates["right"]) and bool(candidates["left"])
    has_body_axis = bool(candidates["head"]) and bool(candidates["tail"])
    if not has_bilateral and not has_body_axis:
        return empty_entry(), False

    # Rule-based hint (cheap, deterministic); also the fallback result.
    rule_hint = resolve_face_joints(clean_names, raw_names)

    last_err = None
    correction = None
    timed_out = False

    prev_handler = install_rig_alarm(timeout_seconds)
    try:
        for attempt in range(1, max_retries + 1):
            try:
                raw_text = client.generate(
                    system_prompt,
                    build_user_prompt(rig_id, candidates,
                                      rule_hint=rule_hint if include_hint else None,
                                      correction=correction),
                    max_tokens)
                return parse_response(raw_text, raw_names, clean_names), False
            except (RigTimeout, FatalLLMError):
                raise
            except Exception as err:  # noqa: BLE001 — retry on any backend/parse error
                last_err = err
                if isinstance(err, ValueError):
                    correction = (
                        "Your previous response failed validation ({}). Return "
                        "exactly one JSON object with keys r_hip, l_hip, source, "
                        "body_axis. r_hip and l_hip must be objects with 'raw' "
                        "and 'clean' string fields. 'raw' must be an exact copy "
                        "of one of the rig's raw joint names (or \"\" for the "
                        "'empty' source). r_hip.raw != l_hip.raw. r_hip MUST "
                        "be the Right-side joint (or, for body_axis, the HEAD "
                        "end) and l_hip the Left-side one (the TAIL end) — "
                        "never swap them, and both must mirror the SAME part. "
                        "No prose, no code fences."
                    ).format(err)
                logger.warning("[{}] attempt {}/{} failed: {}".format(
                    rig_id, attempt, max_retries, err))
                if attempt < max_retries:
                    time.sleep(1.5)
    except RigTimeout:
        timed_out = True
    finally:
        uninstall_rig_alarm(prev_handler)

    if not fallback_on_error and not timed_out:
        raise RuntimeError("LLM face-joint resolution failed for {}: {}".format(
            rig_id, last_err))

    if timed_out:
        logger.warning("[{}] exceeded {}s budget; using rule-based hint".format(
            rig_id, timeout_seconds))
    else:
        logger.error("[{}] all {} attempts failed ({}); falling back to "
                     "rule-based resolver".format(rig_id, max_retries, last_err))
    return rule_hint, True


# ─────────────────────────────────────────────────────────────────────────────
# Batch driver
# ─────────────────────────────────────────────────────────────────────────────

def _is_complete(entry):
    # type: (Dict) -> bool
    """A cached entry is complete if it's well-formed (even 'empty' counts)."""
    return (isinstance(entry, dict)
            and "r_hip" in entry and "l_hip" in entry and "source" in entry)


def resolve_all(raw_path, clean_path, output_path, client, system_prompt=SYSTEM_PROMPT,
                max_tokens=512, max_retries=MAX_RETRIES, timeout_seconds=15,
                fallback_on_error=True, failed_path=None):
    # type: (...) -> Dict[str, Dict]
    """Resolve face joints for every rig in ``raw_path`` / ``clean_path``.

    Resumes from a partial output file. Rig ids that fall back to the
    rule-based resolver are appended to ``failed_path`` (one per line).
    """
    with open(raw_path, "r") as f:
        raw_data = json.load(f)
    with open(clean_path, "r") as f:
        clean_data = json.load(f)

    result = load_json(output_path)
    rig_ids = sorted(set(raw_data.keys()) & set(clean_data.keys()))
    missing = set(raw_data) ^ set(clean_data)
    if missing:
        logger.warning("{} rig ids are not in both raw+clean; skipping: {}"
                       .format(len(missing), sorted(missing)[:5]))

    if failed_path is None:
        failed_path = os.path.join(
            os.path.dirname(output_path) or ".", "failed_face_joints.txt")
    already_failed = set(read_id_list(failed_path)) if os.path.exists(failed_path) else set()

    fallback_count = 0
    pbar = tqdm(rig_ids, desc="Resolving", unit="rig", dynamic_ncols=True)
    for rig_id in pbar:
        pbar.set_postfix_str(rig_id, refresh=False)
        if _is_complete(result.get(rig_id)):
            continue

        entry, used_fallback = resolve_rig(
            rig_id, raw_data[rig_id], clean_data[rig_id], client,
            system_prompt=system_prompt, max_tokens=max_tokens,
            max_retries=max_retries, timeout_seconds=timeout_seconds,
            fallback_on_error=fallback_on_error,
        )
        fallback_count += int(used_fallback)
        result[rig_id] = entry
        save_json(result, output_path)

        if used_fallback and rig_id not in already_failed:
            append_id_list(failed_path, [rig_id])
            already_failed.add(rig_id)

    logger.info("Done. {} rigs resolved ({} via rule-based fallback) -> {}"
                .format(len(result), fallback_count, output_path))
    if fallback_count:
        logger.info("Failed rig ids recorded at {}".format(failed_path))
    return result


def print_source_summary(result):
    # type: (Dict[str, Dict]) -> None
    sources = {}
    for rig_id, entry in result.items():
        sources.setdefault(entry["source"], []).append(rig_id)
    print("\nResolved {} rigs. Breakdown:".format(len(result)))
    for src, rigs in sorted(sources.items()):
        print("  [{}] {} rigs".format(src, len(rigs)))


# ─────────────────────────────────────────────────────────────────────────────
# CLI
# ─────────────────────────────────────────────────────────────────────────────

def main():
    parser = argparse.ArgumentParser(
        description="Pick facing-direction joint pairs via an LLM (local / openai / deepseek).")
    parser.add_argument("--input_dir", type=str, required=True,
                        help="Directory containing joint_names.json and clean_joint_names.json.")
    parser.add_argument("--raw_name", type=str, default="joint_names.json",
                        help="Filename of raw joint names inside --input_dir.")
    parser.add_argument("--clean_name", type=str, default="clean_joint_names.json",
                        help="Filename of cleaned joint names inside --input_dir.")
    parser.add_argument("--output_name", type=str, default="face_joint_names.json",
                        help="Output filename written inside --input_dir (ignored if "
                             "--output is set).")
    parser.add_argument("--output", type=str, default=None,
                        help="Explicit output path (default: <input_dir>/<output_name>).")
    parser.add_argument("--no_fallback", action="store_true",
                        help="Raise on LLM failure instead of falling back to the "
                             "rule-based resolver.")
    parser.add_argument("--failed_log", default=None,
                        help="Path to append rig ids that hit the rule-based fallback "
                             "(default: sibling 'failed_face_joints.txt').")
    parser.add_argument("--rig_timeout", type=int, default=15,
                        help="Per-rig wall-time budget in seconds (SIGALRM). 0 disables.")
    add_llm_args(parser, default_max_tokens=512)
    args = parser.parse_args()

    raw_path = os.path.join(args.input_dir, args.raw_name)
    clean_path = os.path.join(args.input_dir, args.clean_name)
    output_path = args.output or os.path.join(args.input_dir, args.output_name)
    client = LLMClient.from_args(args)
    logger.info("{} | Dir: {} | Output: {}".format(client, args.input_dir, output_path))

    result = resolve_all(
        raw_path=raw_path,
        clean_path=clean_path,
        output_path=output_path,
        client=client,
        max_tokens=args.max_tokens,
        max_retries=args.max_retries,
        timeout_seconds=args.rig_timeout,
        fallback_on_error=not args.no_fallback,
        failed_path=args.failed_log,
    )
    print_source_summary(result)


if __name__ == "__main__":
    main()