cortex-solver 3.0.0__py3-none-any.whl

cortex/core/decomposer.py

@@ -0,0 +1,792 @@
+"""Decomposition engine — breaks subjects into part hierarchies and validates research data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cortex.types import (
+    DecomposeResult,
+    HierarchyNode,
+    MissingField,
+    ResearchItem,
+    ResearchResult,
+    ResearchWarning,
+)
+
+# ---------------------------------------------------------------------------
+# Sanity ranges per category (min, max in metres)
+# ---------------------------------------------------------------------------
+
+SANITY_RANGES: dict[str, tuple[float, float]] = {
+    "furniture": (0.1, 3.0),
+    "electronics": (0.01, 1.0),
+    "architecture": (1.0, 100.0),
+    "vehicle": (1.0, 20.0),
+    "small_props": (0.005, 0.5),
+}
+
+# ---------------------------------------------------------------------------
+# Template database — ~50 common objects
+# ---------------------------------------------------------------------------
+
+_T = dict[str, Any]  # shorthand for a template dict
+
+
+def _tpl(
+    category: str,
+    parts: dict[str, dict[str, Any]],
+) -> _T:
+    """Build a template entry.
+
+    *parts* maps name → {"parent": str|None, "connection": str, "children": []}.
+    The root part has parent=None.
+    """
+    return {"category": category, "parts": parts}
+
+
+def _p(
+    parent: str | None = None, connection: str = "", children: list[str] | None = None
+) -> dict[str, Any]:
+    return {"parent": parent, "connection": connection, "children": children or []}
+
+
+# fmt: off
+TEMPLATES: dict[str, _T] = {
+    # ── Furniture ──────────────────────────────────────────────
+    "chair": _tpl("furniture", {
+        "seat": _p(None, "", ["backrest", "leg_front_L", "leg_front_R", "leg_back_L", "leg_back_R"]),
+        "backrest": _p("seat", "stacked_top"),
+        "leg_front_L": _p("seat", "stacked_bottom"),
+        "leg_front_R": _p("seat", "stacked_bottom"),
+        "leg_back_L": _p("seat", "stacked_bottom"),
+        "leg_back_R": _p("seat", "stacked_bottom"),
+    }),
+    "table": _tpl("furniture", {
+        "tabletop": _p(None, "", ["leg_1", "leg_2", "leg_3", "leg_4"]),
+        "leg_1": _p("tabletop", "stacked_bottom"),
+        "leg_2": _p("tabletop", "stacked_bottom"),
+        "leg_3": _p("tabletop", "stacked_bottom"),
+        "leg_4": _p("tabletop", "stacked_bottom"),
+    }),
+    "desk": _tpl("furniture", {
+        "desktop": _p(None, "", ["leg_L", "leg_R", "drawer_unit", "back_panel"]),
+        "leg_L": _p("desktop", "stacked_bottom"),
+        "leg_R": _p("desktop", "stacked_bottom"),
+        "drawer_unit": _p("desktop", "stacked_bottom"),
+        "back_panel": _p("desktop", "flush_back"),
+    }),
+    "bench": _tpl("furniture", {
+        "seat": _p(None, "", ["backrest", "leg_front_L", "leg_front_R", "leg_back_L", "leg_back_R", "support_bar_front", "support_bar_back"]),
+        "backrest": _p("seat", "stacked_top"),
+        "leg_front_L": _p("seat", "stacked_bottom"),
+        "leg_front_R": _p("seat", "stacked_bottom"),
+        "leg_back_L": _p("seat", "stacked_bottom"),
+        "leg_back_R": _p("seat", "stacked_bottom"),
+        "support_bar_front": _p("leg_front_L", "stacked_bottom"),
+        "support_bar_back": _p("leg_back_L", "stacked_bottom"),
+    }),
+    "shelf": _tpl("furniture", {
+        "frame": _p(None, "", ["shelf_1", "shelf_2", "shelf_3", "side_L", "side_R"]),
+        "shelf_1": _p("frame", "inside"),
+        "shelf_2": _p("frame", "inside"),
+        "shelf_3": _p("frame", "inside"),
+        "side_L": _p("frame", "flush"),
+        "side_R": _p("frame", "flush"),
+    }),
+    "cabinet": _tpl("furniture", {
+        "body": _p(None, "", ["top_panel", "bottom_panel", "door_L", "door_R", "shelf_inner", "back_panel"]),
+        "top_panel": _p("body", "stacked_top"),
+        "bottom_panel": _p("body", "stacked_bottom"),
+        "door_L": _p("body", "flush_front"),
+        "door_R": _p("body", "flush_front"),
+        "shelf_inner": _p("body", "inside"),
+        "back_panel": _p("body", "flush_back"),
+    }),
+    "bed": _tpl("furniture", {
+        "frame": _p(None, "", ["headboard", "footboard", "mattress", "slats", "leg_1", "leg_2", "leg_3", "leg_4"]),
+        "headboard": _p("frame", "flush_back"),
+        "footboard": _p("frame", "flush_front"),
+        "mattress": _p("frame", "stacked_top"),
+        "slats": _p("frame", "inside"),
+        "leg_1": _p("frame", "stacked_bottom"),
+        "leg_2": _p("frame", "stacked_bottom"),
+        "leg_3": _p("frame", "stacked_bottom"),
+        "leg_4": _p("frame", "stacked_bottom"),
+    }),
+    "sofa": _tpl("furniture", {
+        "seat_cushion": _p(None, "", ["backrest_cushion", "armrest_L", "armrest_R", "frame_base"]),
+        "backrest_cushion": _p("seat_cushion", "stacked_top"),
+        "armrest_L": _p("seat_cushion", "flush_left"),
+        "armrest_R": _p("seat_cushion", "flush_right"),
+        "frame_base": _p("seat_cushion", "stacked_bottom"),
+    }),
+    "stool": _tpl("furniture", {
+        "seat": _p(None, "", ["leg_1", "leg_2", "leg_3", "footrest_ring"]),
+        "leg_1": _p("seat", "stacked_bottom"),
+        "leg_2": _p("seat", "stacked_bottom"),
+        "leg_3": _p("seat", "stacked_bottom"),
+        "footrest_ring": _p("leg_1", "centered"),
+    }),
+    "bookcase": _tpl("furniture", {
+        "frame": _p(None, "", ["shelf_1", "shelf_2", "shelf_3", "shelf_4", "side_L", "side_R", "back_panel"]),
+        "shelf_1": _p("frame", "inside"),
+        "shelf_2": _p("frame", "inside"),
+        "shelf_3": _p("frame", "inside"),
+        "shelf_4": _p("frame", "inside"),
+        "side_L": _p("frame", "flush_left"),
+        "side_R": _p("frame", "flush_right"),
+        "back_panel": _p("frame", "flush_back"),
+    }),
+
+    # ── Electronics ────────────────────────────────────────────
+    "headphones": _tpl("electronics", {
+        "headband_frame": _p(None, "", ["headband_cushion", "slider_L", "slider_R"]),
+        "headband_cushion": _p("headband_frame", "stacked_bottom"),
+        "slider_L": _p("headband_frame", "stacked_bottom"),
+        "slider_R": _p("headband_frame", "stacked_bottom"),
+        "hinge_L": _p("slider_L", "stacked_bottom"),
+        "hinge_R": _p("slider_R", "stacked_bottom"),
+        "earcup_shell_L": _p("hinge_L", "stacked_bottom"),
+        "earcup_shell_R": _p("hinge_R", "stacked_bottom"),
+        "cushion_L": _p("earcup_shell_L", "flush"),
+        "cushion_R": _p("earcup_shell_R", "flush"),
+    }),
+    "speaker": _tpl("electronics", {
+        "enclosure": _p(None, "", ["driver_woofer", "driver_tweeter", "grille", "port_tube", "base_pad"]),
+        "driver_woofer": _p("enclosure", "inside"),
+        "driver_tweeter": _p("enclosure", "inside"),
+        "grille": _p("enclosure", "flush_front"),
+        "port_tube": _p("enclosure", "flush_back"),
+        "base_pad": _p("enclosure", "stacked_bottom"),
+    }),
+    "monitor": _tpl("electronics", {
+        "panel": _p(None, "", ["bezel", "stand_neck", "backplate"]),
+        "bezel": _p("panel", "flush_front"),
+        "stand_neck": _p("panel", "stacked_bottom"),
+        "stand_base": _p("stand_neck", "stacked_bottom"),
+        "backplate": _p("panel", "flush_back"),
+    }),
+    "keyboard": _tpl("electronics", {
+        "base_plate": _p(None, "", ["key_cluster_main", "key_cluster_numpad", "top_cover", "feet"]),
+        "key_cluster_main": _p("base_plate", "stacked_top"),
+        "key_cluster_numpad": _p("base_plate", "stacked_top"),
+        "top_cover": _p("base_plate", "flush"),
+        "feet": _p("base_plate", "stacked_bottom"),
+    }),
+    "mouse": _tpl("electronics", {
+        "shell_top": _p(None, "", ["shell_bottom", "scroll_wheel", "button_L", "button_R"]),
+        "shell_bottom": _p("shell_top", "stacked_bottom"),
+        "scroll_wheel": _p("shell_top", "inside"),
+        "button_L": _p("shell_top", "flush_top"),
+        "button_R": _p("shell_top", "flush_top"),
+    }),
+    "laptop": _tpl("electronics", {
+        "base_body": _p(None, "", ["keyboard_area", "trackpad", "screen_lid", "hinge"]),
+        "keyboard_area": _p("base_body", "stacked_top"),
+        "trackpad": _p("base_body", "stacked_top"),
+        "screen_lid": _p("hinge", "stacked_top"),
+        "hinge": _p("base_body", "flush_back"),
+    }),
+    "phone": _tpl("electronics", {
+        "body": _p(None, "", ["screen", "back_cover", "camera_module"]),
+        "screen": _p("body", "flush_front"),
+        "back_cover": _p("body", "flush_back"),
+        "camera_module": _p("back_cover", "stacked_top"),
+    }),
+    "tablet": _tpl("electronics", {
+        "body": _p(None, "", ["screen", "back_panel", "camera"]),
+        "screen": _p("body", "flush_front"),
+        "back_panel": _p("body", "flush_back"),
+        "camera": _p("back_panel", "flush"),
+    }),
+    "camera": _tpl("electronics", {
+        "body": _p(None, "", ["lens_mount", "viewfinder", "grip", "top_plate", "bottom_plate"]),
+        "lens_mount": _p("body", "flush_front"),
+        "viewfinder": _p("body", "stacked_top"),
+        "grip": _p("body", "flush_right"),
+        "top_plate": _p("body", "stacked_top"),
+        "bottom_plate": _p("body", "stacked_bottom"),
+    }),
+    "microphone": _tpl("electronics", {
+        "capsule": _p(None, "", ["body_tube", "grille"]),
+        "body_tube": _p("capsule", "stacked_bottom"),
+        "grille": _p("capsule", "stacked_top"),
+        "mount_ring": _p("body_tube", "centered"),
+        "connector": _p("body_tube", "stacked_bottom"),
+    }),
+
+    # ── Architecture ───────────────────────────────────────────
+    "house": _tpl("architecture", {
+        "foundation": _p(None, "", ["walls", "floor"]),
+        "floor": _p("foundation", "stacked_top"),
+        "walls": _p("floor", "stacked_top", ["roof", "door_front", "window_1", "window_2"]),
+        "roof": _p("walls", "stacked_top"),
+        "door_front": _p("walls", "flush_front"),
+        "window_1": _p("walls", "inside"),
+        "window_2": _p("walls", "inside"),
+    }),
+    "building": _tpl("architecture", {
+        "foundation": _p(None, "", ["ground_floor", "upper_floors", "roof"]),
+        "ground_floor": _p("foundation", "stacked_top"),
+        "upper_floors": _p("ground_floor", "stacked_top"),
+        "roof": _p("upper_floors", "stacked_top"),
+        "entrance": _p("ground_floor", "flush_front"),
+    }),
+    "room": _tpl("architecture", {
+        "floor": _p(None, "", ["wall_N", "wall_S", "wall_E", "wall_W", "ceiling"]),
+        "wall_N": _p("floor", "stacked_top"),
+        "wall_S": _p("floor", "stacked_top"),
+        "wall_E": _p("floor", "stacked_top"),
+        "wall_W": _p("floor", "stacked_top"),
+        "ceiling": _p("wall_N", "stacked_top"),
+    }),
+    "wall": _tpl("architecture", {
+        "structure": _p(None, "", ["surface_front", "surface_back", "insulation"]),
+        "surface_front": _p("structure", "flush_front"),
+        "surface_back": _p("structure", "flush_back"),
+        "insulation": _p("structure", "inside"),
+    }),
+    "door": _tpl("architecture", {
+        "frame": _p(None, "", ["panel", "hinge_top", "hinge_bottom", "handle"]),
+        "panel": _p("frame", "inside"),
+        "hinge_top": _p("frame", "flush"),
+        "hinge_bottom": _p("frame", "flush"),
+        "handle": _p("panel", "flush"),
+    }),
+    "window": _tpl("architecture", {
+        "frame": _p(None, "", ["glass_pane", "sill", "latch"]),
+        "glass_pane": _p("frame", "inside"),
+        "sill": _p("frame", "stacked_bottom"),
+        "latch": _p("frame", "flush"),
+    }),
+    "stairs": _tpl("architecture", {
+        "stringer_L": _p(None, "", ["step_1", "step_2", "step_3", "step_4", "step_5", "handrail"]),
+        "stringer_R": _p("stringer_L", "symmetric"),
+        "step_1": _p("stringer_L", "inside"),
+        "step_2": _p("step_1", "stacked_top"),
+        "step_3": _p("step_2", "stacked_top"),
+        "step_4": _p("step_3", "stacked_top"),
+        "step_5": _p("step_4", "stacked_top"),
+        "handrail": _p("stringer_L", "stacked_top"),
+    }),
+    "roof": _tpl("architecture", {
+        "ridge_beam": _p(None, "", ["rafter_L", "rafter_R", "sheathing", "covering"]),
+        "rafter_L": _p("ridge_beam", "flush"),
+        "rafter_R": _p("ridge_beam", "flush"),
+        "sheathing": _p("rafter_L", "stacked_top"),
+        "covering": _p("sheathing", "stacked_top"),
+    }),
+    "column": _tpl("architecture", {
+        "shaft": _p(None, "", ["base_plinth", "capital"]),
+        "base_plinth": _p("shaft", "stacked_bottom"),
+        "capital": _p("shaft", "stacked_top"),
+    }),
+    "arch": _tpl("architecture", {
+        "keystone": _p(None, "", ["voussoir_L", "voussoir_R", "impost_L", "impost_R"]),
+        "voussoir_L": _p("keystone", "flush"),
+        "voussoir_R": _p("keystone", "flush"),
+        "impost_L": _p("voussoir_L", "stacked_bottom"),
+        "impost_R": _p("voussoir_R", "stacked_bottom"),
+    }),
+
+    # ── Vehicles ───────────────────────────────────────────────
+    "car": _tpl("vehicle", {
+        "chassis": _p(None, "", ["body_shell", "wheel_FL", "wheel_FR", "wheel_RL", "wheel_RR"]),
+        "body_shell": _p("chassis", "stacked_top", ["windshield", "door_L", "door_R"]),
+        "wheel_FL": _p("chassis", "stacked_bottom"),
+        "wheel_FR": _p("chassis", "stacked_bottom"),
+        "wheel_RL": _p("chassis", "stacked_bottom"),
+        "wheel_RR": _p("chassis", "stacked_bottom"),
+        "windshield": _p("body_shell", "flush_front"),
+        "door_L": _p("body_shell", "flush_left"),
+        "door_R": _p("body_shell", "flush_right"),
+    }),
+    "bicycle": _tpl("vehicle", {
+        "frame": _p(None, "", ["wheel_front", "wheel_rear", "seat", "handlebars", "pedals"]),
+        "wheel_front": _p("frame", "flush_front"),
+        "wheel_rear": _p("frame", "flush_back"),
+        "seat": _p("frame", "stacked_top"),
+        "handlebars": _p("frame", "stacked_top"),
+        "pedals": _p("frame", "centered"),
+    }),
+    "motorcycle": _tpl("vehicle", {
+        "frame": _p(None, "", ["engine", "wheel_front", "wheel_rear", "seat", "handlebars", "fuel_tank"]),
+        "engine": _p("frame", "inside"),
+        "wheel_front": _p("frame", "flush_front"),
+        "wheel_rear": _p("frame", "flush_back"),
+        "seat": _p("frame", "stacked_top"),
+        "handlebars": _p("frame", "stacked_top"),
+        "fuel_tank": _p("frame", "stacked_top"),
+    }),
+    "truck": _tpl("vehicle", {
+        "chassis": _p(None, "", ["cab", "cargo_bed", "wheel_FL", "wheel_FR", "wheel_RL", "wheel_RR"]),
+        "cab": _p("chassis", "stacked_top"),
+        "cargo_bed": _p("chassis", "stacked_top"),
+        "wheel_FL": _p("chassis", "stacked_bottom"),
+        "wheel_FR": _p("chassis", "stacked_bottom"),
+        "wheel_RL": _p("chassis", "stacked_bottom"),
+        "wheel_RR": _p("chassis", "stacked_bottom"),
+    }),
+    "bus": _tpl("vehicle", {
+        "chassis": _p(None, "", ["body", "wheel_FL", "wheel_FR", "wheel_RL", "wheel_RR"]),
+        "body": _p("chassis", "stacked_top", ["windshield", "door_front", "door_rear"]),
+        "wheel_FL": _p("chassis", "stacked_bottom"),
+        "wheel_FR": _p("chassis", "stacked_bottom"),
+        "wheel_RL": _p("chassis", "stacked_bottom"),
+        "wheel_RR": _p("chassis", "stacked_bottom"),
+        "windshield": _p("body", "flush_front"),
+        "door_front": _p("body", "flush_left"),
+        "door_rear": _p("body", "flush_left"),
+    }),
+    "airplane": _tpl("vehicle", {
+        "fuselage": _p(None, "", ["wing_L", "wing_R", "tail_vertical", "tail_horizontal", "nose_cone", "landing_gear"]),
+        "wing_L": _p("fuselage", "flush_left"),
+        "wing_R": _p("fuselage", "flush_right"),
+        "tail_vertical": _p("fuselage", "flush_back"),
+        "tail_horizontal": _p("fuselage", "flush_back"),
+        "nose_cone": _p("fuselage", "flush_front"),
+        "landing_gear": _p("fuselage", "stacked_bottom"),
+    }),
+    "boat": _tpl("vehicle", {
+        "hull": _p(None, "", ["deck", "cabin", "keel", "rudder"]),
+        "deck": _p("hull", "stacked_top"),
+        "cabin": _p("deck", "stacked_top"),
+        "keel": _p("hull", "stacked_bottom"),
+        "rudder": _p("hull", "flush_back"),
+    }),
+    "helicopter": _tpl("vehicle", {
+        "fuselage": _p(None, "", ["main_rotor", "tail_boom", "skid_L", "skid_R"]),
+        "main_rotor": _p("fuselage", "stacked_top"),
+        "tail_boom": _p("fuselage", "flush_back"),
+        "tail_rotor": _p("tail_boom", "flush"),
+        "skid_L": _p("fuselage", "stacked_bottom"),
+        "skid_R": _p("fuselage", "stacked_bottom"),
+    }),
+    "train": _tpl("vehicle", {
+        "chassis": _p(None, "", ["body", "bogie_front", "bogie_rear"]),
+        "body": _p("chassis", "stacked_top", ["windshield", "door_L", "door_R"]),
+        "bogie_front": _p("chassis", "stacked_bottom"),
+        "bogie_rear": _p("chassis", "stacked_bottom"),
+        "windshield": _p("body", "flush_front"),
+        "door_L": _p("body", "flush_left"),
+        "door_R": _p("body", "flush_right"),
+    }),
+    "scooter": _tpl("vehicle", {
+        "frame": _p(None, "", ["deck", "wheel_front", "wheel_rear", "handlebar", "stem"]),
+        "deck": _p("frame", "stacked_top"),
+        "wheel_front": _p("frame", "flush_front"),
+        "wheel_rear": _p("frame", "flush_back"),
+        "handlebar": _p("stem", "stacked_top"),
+        "stem": _p("frame", "stacked_top"),
+    }),
+
+    # ── Small Props ────────────────────────────────────────────
+    "cup": _tpl("small_props", {
+        "body": _p(None, "", ["handle", "base_ring"]),
+        "handle": _p("body", "flush"),
+        "base_ring": _p("body", "stacked_bottom"),
+    }),
+    "bottle": _tpl("small_props", {
+        "body": _p(None, "", ["neck", "base", "cap"]),
+        "neck": _p("body", "stacked_top"),
+        "base": _p("body", "stacked_bottom"),
+        "cap": _p("neck", "stacked_top"),
+    }),
+    "pen": _tpl("small_props", {
+        "barrel": _p(None, "", ["tip", "cap", "clip"]),
+        "tip": _p("barrel", "flush_front"),
+        "cap": _p("barrel", "flush_back"),
+        "clip": _p("cap", "flush"),
+    }),
+    "book": _tpl("small_props", {
+        "cover_front": _p(None, "", ["pages", "cover_back", "spine"]),
+        "pages": _p("cover_front", "stacked_bottom"),
+        "cover_back": _p("pages", "stacked_bottom"),
+        "spine": _p("cover_front", "flush"),
+    }),
+    "lamp": _tpl("small_props", {
+        "base": _p(None, "", ["stem", "shade"]),
+        "stem": _p("base", "stacked_top"),
+        "shade": _p("stem", "stacked_top"),
+        "bulb": _p("shade", "inside"),
+    }),
+    "clock": _tpl("small_props", {
+        "frame": _p(None, "", ["face", "glass", "hands"]),
+        "face": _p("frame", "inside"),
+        "glass": _p("frame", "flush_front"),
+        "hands": _p("face", "stacked_top"),
+    }),
+    "vase": _tpl("small_props", {
+        "body": _p(None, "", ["neck", "base", "rim"]),
+        "neck": _p("body", "stacked_top"),
+        "base": _p("body", "stacked_bottom"),
+        "rim": _p("neck", "stacked_top"),
+    }),
+    "plate": _tpl("small_props", {
+        "body": _p(None, "", ["rim", "base_ring"]),
+        "rim": _p("body", "flush"),
+        "base_ring": _p("body", "stacked_bottom"),
+    }),
+    "fork": _tpl("small_props", {
+        "handle": _p(None, "", ["neck", "head"]),
+        "neck": _p("handle", "flush_front"),
+        "head": _p("neck", "flush_front"),
+    }),
+    "knife": _tpl("small_props", {
+        "handle": _p(None, "", ["blade", "guard"]),
+        "blade": _p("handle", "flush_front"),
+        "guard": _p("handle", "flush"),
+    }),
+}
+# fmt: on
+
+# Variant modifiers — extra parts added for known variants
+VARIANT_MODS: dict[str, dict[str, dict[str, Any]]] = {
+    "gaming": {
+        "headrest": _p("backrest", "stacked_top"),
+        "armrest_pad_L": _p("armrest_L", "stacked_top")
+        if False
+        else _p("seat", "flush_left"),
+        "armrest_pad_R": _p("seat", "flush_right"),
+        "lumbar_support": _p("backrest", "flush_back"),
+    },
+    "ergonomic": {
+        "armrest_L": _p("seat", "flush_left"),
+        "armrest_R": _p("seat", "flush_right"),
+        "lumbar_support": _p("backrest", "inside"),
+    },
+    "modern": {},  # no extra parts — just a style tag
+    "industrial": {},
+    "minimalist": {},
+}
+
+# Required research fields per detail level
+RESEARCH_FIELDS: dict[str, list[str]] = {
+    "basic": ["dimensions"],
+    "detailed": ["dimensions", "material", "thickness"],
+    "exhaustive": [
+        "dimensions",
+        "material",
+        "thickness",
+        "construction_method",
+        "edge_treatment",
+        "source",
+    ],
+}
+
+
+# ---------------------------------------------------------------------------
+# Template lookup
+# ---------------------------------------------------------------------------
+
+
+def _find_template(subject: str) -> _T | None:
+    """Find the best-matching template for a subject string (case-insensitive)."""
+    subj = subject.lower().strip()
+    # Exact match first
+    if subj in TEMPLATES:
+        return TEMPLATES[subj]
+    # Plural → singular
+    if subj.endswith("s") and subj[:-1] in TEMPLATES:
+        return TEMPLATES[subj[:-1]]
+    # Substring match
+    for key, tpl in TEMPLATES.items():
+        if key in subj or subj in key:
+            return tpl
+    return None
+
+
+def _get_category(subject: str) -> str:
+    """Infer category from template match or fall back to 'furniture'."""
+    tpl = _find_template(subject)
+    return tpl["category"] if tpl else "furniture"
+
+
+# ---------------------------------------------------------------------------
+# Hierarchy building
+# ---------------------------------------------------------------------------
+
+
+def _build_hierarchy(
+    parts: dict[str, dict[str, Any]],
+    detail_level: str,
+) -> dict[str, HierarchyNode]:
+    """Convert template parts dict into HierarchyNode dict, respecting detail depth."""
+    max_depth = {"basic": 2, "detailed": 3, "exhaustive": 99}.get(detail_level, 3)
+
+    # Find root (parent=None)
+    root_name = next((n for n, p in parts.items() if p["parent"] is None), None)
+    if root_name is None:
+        return {}
+
+    nodes: dict[str, HierarchyNode] = {}
+    depth_map: dict[str, int] = {root_name: 0}
+
+    # BFS to honour max depth
+    queue = [root_name]
+    while queue:
+        name = queue.pop(0)
+        d = depth_map[name]
+        if d > max_depth:
+            continue
+        info = parts[name]
+        nodes[name] = HierarchyNode(
+            name=name,
+            parent=info["parent"],
+            connection=info["connection"],
+            children=[
+                c
+                for c in info.get("children", [])
+                if c in parts and depth_map.get(c, d + 1) <= max_depth
+            ],
+        )
+        for child_name in info.get("children", []):
+            if child_name in parts and child_name not in depth_map:
+                depth_map[child_name] = d + 1
+                queue.append(child_name)
+
+    # Fill in children for nodes whose children were added during BFS but not in the original template children list
+    for name, node in nodes.items():
+        for cname, cinfo in parts.items():
+            if (
+                cinfo["parent"] == name
+                and cname in nodes
+                and cname not in node.children
+            ):
+                node.children.append(cname)
+
+    return nodes
+
+
+def _generic_hierarchy(subject: str, detail_level: str) -> dict[str, HierarchyNode]:
+    """Generate a generic hierarchy for an unknown subject."""
+    root = subject.lower().replace(" ", "_")
+    children = ["main_body", "base", "top"]
+    if detail_level in ("detailed", "exhaustive"):
+        children.extend(["detail_A", "detail_B"])
+    if detail_level == "exhaustive":
+        children.extend(["detail_C", "accent_1", "accent_2"])
+
+    nodes: dict[str, HierarchyNode] = {
+        root: HierarchyNode(name=root, parent=None, connection="", children=children),
+    }
+    for c in children:
+        nodes[c] = HierarchyNode(name=c, parent=root, connection="attached")
+    return nodes
+
+
+def _topological_order(hierarchy: dict[str, HierarchyNode]) -> list[str]:
+    """Return build order (parent before children) via BFS."""
+    root = next((n for n, h in hierarchy.items() if h.parent is None), None)
+    if root is None:
+        return list(hierarchy.keys())
+    order: list[str] = []
+    queue = [root]
+    visited: set[str] = set()
+    while queue:
+        name = queue.pop(0)
+        if name in visited or name not in hierarchy:
+            continue
+        visited.add(name)
+        order.append(name)
+        for child in hierarchy[name].children:
+            if child not in visited:
+                queue.append(child)
+    # Add any remaining
+    for name in hierarchy:
+        if name not in visited:
+            order.append(name)
+    return order
+
+
+# ---------------------------------------------------------------------------
+# Public API: decompose
+# ---------------------------------------------------------------------------
+
+
+def decompose(
+    subject: str,
+    variant: str = "",
+    scope: str = "object",
+    detail_level: str = "detailed",
+) -> DecomposeResult:
+    """Decompose a subject into a hierarchical part tree."""
+    if scope == "scene":
+        return _decompose_scene(subject, detail_level)
+
+    tpl = _find_template(subject)
+    if tpl is not None:
+        parts = dict(tpl["parts"])
+        # Apply variant modifications
+        if variant and variant.lower() in VARIANT_MODS:
+            for pname, pinfo in VARIANT_MODS[variant.lower()].items():
+                if pname not in parts:
+                    parts[pname] = pinfo
+                    # Add to parent's children list
+                    parent = pinfo["parent"]
+                    if parent and parent in parts:
+                        if pname not in parts[parent].get("children", []):
+                            parts[parent].setdefault("children", []).append(pname)
+
+        hierarchy = _build_hierarchy(parts, detail_level)
+    else:
+        hierarchy = _generic_hierarchy(subject, detail_level)
+
+    category = tpl["category"] if tpl else "furniture"
+    detail = detail_level if detail_level in RESEARCH_FIELDS else "detailed"
+    fields = RESEARCH_FIELDS[detail]
+
+    research_required = [
+        ResearchItem(part=name, needed=list(fields)) for name in hierarchy
+    ]
+
+    build_order = _topological_order(hierarchy)
+
+    return DecomposeResult(
+        subject=subject,
+        hierarchy=hierarchy,
+        research_required=research_required,
+        total_parts=len(hierarchy),
+        build_order=build_order,
+    )
+
+
+def _decompose_scene(subject: str, detail_level: str) -> DecomposeResult:
+    """Decompose a scene subject into object-level hierarchy."""
+    # Generic scene decomposition
+    root = subject.lower().replace(" ", "_")
+    objects = ["ground_plane", "main_structure", "props", "lighting"]
+    if detail_level in ("detailed", "exhaustive"):
+        objects.extend(["vegetation", "furniture"])
+    if detail_level == "exhaustive":
+        objects.extend(["vehicles", "characters", "effects"])
+
+    hierarchy: dict[str, HierarchyNode] = {
+        root: HierarchyNode(name=root, parent=None, connection="", children=objects),
+    }
+    for obj in objects:
+        hierarchy[obj] = HierarchyNode(name=obj, parent=root, connection="placed_in")
+
+    build_order = [root] + objects
+    research_required = [
+        ResearchItem(part=name, needed=["dimensions"]) for name in hierarchy
+    ]
+
+    return DecomposeResult(
+        subject=subject,
+        hierarchy=hierarchy,
+        research_required=research_required,
+        total_parts=len(hierarchy),
+        build_order=build_order,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API: research
+# ---------------------------------------------------------------------------
+
+
+def research(
+    hierarchy: dict[str, Any],
+    filled_data: dict[str, Any] | None = None,
+) -> ResearchResult:
+    """Validate completeness and sanity of research data against a hierarchy."""
+    filled = filled_data or {}
+    missing: list[MissingField] = []
+    warnings: list[ResearchWarning] = []
+
+    # Determine category for sanity checks
+    category = "furniture"  # default
+    for cat, (lo, hi) in SANITY_RANGES.items():
+        # Heuristic: if any filled dimension fits this range, use it
+        for part_data in filled.values():
+            dims = part_data.get("dimensions", {})
+            for dim_key in ("w", "d", "h", "width", "depth", "height"):
+                val = dims.get(dim_key, 0)
+                if isinstance(val, (int, float)) and lo <= val <= hi:
+                    category = cat
+                    break
+
+    lo, hi = SANITY_RANGES.get(category, (0.001, 100.0))
+
+    # Determine required fields
+    detail_fields = ["dimensions", "material", "thickness"]
+
+    for part_name in hierarchy:
+        part_data = filled.get(part_name, {})
+
+        if not part_data:
+            missing.append(
+                MissingField(
+                    part=part_name,
+                    field="dimensions",
+                    hint=f"Provide width, depth, height for {part_name}",
+                )
+            )
+            continue
+
+        # Check dimensions
+        dims = part_data.get("dimensions", {})
+        if not dims:
+            missing.append(
+                MissingField(
+                    part=part_name,
+                    field="dimensions",
+                    hint=f"Provide width, depth, height for {part_name}",
+                )
+            )
+        else:
+            for dim_key, dim_label in [("w", "width"), ("d", "depth"), ("h", "height")]:
+                val = dims.get(dim_key, dims.get(dim_label, None))
+                if val is None:
+                    missing.append(
+                        MissingField(
+                            part=part_name,
+                            field=f"dimensions.{dim_label}",
+                            hint=f"Missing {dim_label} for {part_name}",
+                        )
+                    )
+                elif isinstance(val, (int, float)):
+                    if val <= 0:
+                        warnings.append(
+                            ResearchWarning(
+                                part=part_name,
+                                field=f"dimensions.{dim_label}",
+                                value=val,
+                                concern=f"{dim_label} must be positive",
+                            )
+                        )
+                    elif val < lo or val > hi:
+                        warnings.append(
+                            ResearchWarning(
+                                part=part_name,
+                                field=f"dimensions.{dim_label}",
+                                value=val,
+                                concern=f"{dim_label}={val}m outside expected range [{lo}, {hi}]m for {category}",
+                            )
+                        )
+
+        # Check other fields
+        for field_name in detail_fields[1:]:
+            if field_name not in part_data:
+                missing.append(
+                    MissingField(
+                        part=part_name,
+                        field=field_name,
+                        hint=f"Provide {field_name} for {part_name}",
+                    )
+                )
+
+    # ready_for_recipe = all parts have at minimum dimensions
+    dims_missing = any(
+        m.field == "dimensions" or m.field.startswith("dimensions.") for m in missing
+    )
+    complete = len(missing) == 0
+    ready = not dims_missing
+
+    return ResearchResult(
+        complete=complete,
+        missing=missing,
+        warnings=warnings,
+        ready_for_recipe=ready,
+    )