refactor(parts): split catalog into parts_data.py + add category schema

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

src/buddy_fusion/parts.py

@@ -1,81 +1,45 @@
-"""Hand-authored additive part templates for the template-assembly edit path.
+"""Helpers over the part catalog (data lives in parts_data.py).
 
 Each part's boxes are in LOCAL coordinates: x is the part's own left-right center
 (0), z is centered on 0, y is the part's bottom (0 = part base). The assembler
 (assembler.py) computes the target creature's bounding box and face-aligns the
-part to the chosen anchor, so local coords only describe the part's own shape.
-`symmetric` parts author the LEFT half (x<=0); the assembler mirrors across x.
+part to the chosen anchor. `symmetric` parts author the LEFT half (x<=0); the
+assembler mirrors across x.
 See docs/superpowers/specs/2026-06-15-template-part-assembly-edit-design.md.
 """
 from __future__ import annotations
 
+from .parts_data import PARTS
+
 ANCHORS = ("top", "rear", "front", "left", "right", "bottom")
 
-PARTS: dict[str, dict] = {
-    "horns": {
-        "desc": "a pair of curved horns",
-        "default_anchor": "top", "default_scale": 1, "symmetric": True,
-        "boxes": [
-            {"x": -1, "y": 0, "z": 0, "w": 1, "h": 2, "d": 1, "color": "#efe2c0"},
-            {"x": -1, "y": 2, "z": 1, "w": 1, "h": 1, "d": 1, "color": "#efe2c0"},
-        ],
-    },
-    "wings": {
-        "desc": "a pair of wings on the sides",
-        "default_anchor": "left", "default_scale": 1, "symmetric": True,
-        "boxes": [
-            {"x": -1, "y": 1, "z": 0, "w": 1, "h": 3, "d": 4, "color": "#cfe6ff"},
-        ],
-    },
-    "tail": {
-        "desc": "a long swishy tail at the back",
-        "default_anchor": "rear", "default_scale": 1, "symmetric": False,
-        "boxes": [
-            {"x": 0, "y": 1, "z": 0, "w": 1, "h": 1, "d": 3, "color": "#caa06f"},
-            {"x": 0, "y": 2, "z": 2, "w": 1, "h": 1, "d": 2, "color": "#caa06f"},
-        ],
-    },
-    "ears": {
-        "desc": "two pointy ears on top",
-        "default_anchor": "top", "default_scale": 1, "symmetric": True,
-        "boxes": [
-            {"x": -1, "y": 0, "z": 0, "w": 1, "h": 2, "d": 1, "color": "#caa06f"},
-        ],
-    },
-    "house": {
-        "desc": "a small house / hut",
-        "default_anchor": "rear", "default_scale": 2, "symmetric": False,
-        "boxes": [
-            {"x": 0, "y": 0, "z": 0, "w": 4, "h": 3, "d": 4, "color": "#d8b08c"},
-            {"x": 0, "y": 3, "z": 0, "w": 5, "h": 2, "d": 5, "color": "#b5532e"},
-            {"x": 0, "y": 0, "z": 2, "w": 1, "h": 2, "d": 1, "color": "#6b4423"},
-        ],
-    },
-    "hat": {
-        "desc": "a hat / cap on top of the head",
-        "default_anchor": "top", "default_scale": 1, "symmetric": False,
-        "boxes": [
-            {"x": 0, "y": 0, "z": 0, "w": 5, "h": 1, "d": 5, "color": "#3a3550"},
-            {"x": 0, "y": 1, "z": 0, "w": 3, "h": 2, "d": 3, "color": "#3a3550"},
-        ],
-    },
-    "crown": {
-        "desc": "a small crown on top",
-        "default_anchor": "top", "default_scale": 1, "symmetric": False,
-        "boxes": [
-            {"x": 0, "y": 0, "z": 0, "w": 4, "h": 1, "d": 4, "color": "#ffd34d"},
-            {"x": -1, "y": 1, "z": 0, "w": 1, "h": 1, "d": 1, "color": "#ffd34d"},
-            {"x": 1, "y": 1, "z": 0, "w": 1, "h": 1, "d": 1, "color": "#ffd34d"},
-            {"x": 0, "y": 1, "z": 0, "w": 1, "h": 1, "d": 1, "color": "#ffd34d"},
-        ],
-    },
-}
+# Display/grouping order for the catalog + the selector prompt.
+CATEGORIES = (
+    "horns", "ears", "tails", "wings", "headwear",
+    "face", "back", "limbs", "props", "accessories",
+)
 
 
 def part_ids() -> list[str]:
     return list(PARTS.keys())
 
 
+def parts_by_category() -> dict[str, list[str]]:
+    """category -> [part ids], in CATEGORIES order then insertion order. Any part
+    whose category is not in CATEGORIES is grouped under 'other'."""
+    out: dict[str, list[str]] = {c: [] for c in CATEGORIES}
+    for pid, p in PARTS.items():
+        cat = p.get("category", "other")
+        out.setdefault(cat, []).append(pid)
+    return {c: ids for c, ids in out.items() if ids}
+
+
 def catalog_text() -> str:
-    """One line per part: `id: desc` — fed to the selector so it picks by id."""
-    return "\n".join(f"- {pid}: {p['desc']}" for pid, p in PARTS.items())
+    """Catalog for the selector prompt, grouped under category headers so the
+    small model sees structure when picking from a large set."""
+    lines: list[str] = []
+    for cat, ids in parts_by_category().items():
+        lines.append(f"[{cat}]")
+        for pid in ids:
+            lines.append(f"- {pid}: {PARTS[pid]['desc']}")
+    return "\n".join(lines)

src/buddy_fusion/parts_data.py

@@ -0,0 +1,69 @@
+"""The part catalog data: ~100 hand-authored additive voxel parts, grouped by
+`category`. Box-layouts are in LOCAL coordinates (x,z = center, y = bottom);
+`symmetric` parts author the LEFT half (x<=0) and the assembler/renderer mirror
+across x. Kept separate from parts.py (helpers) like compendium_data.py.
+
+Schema per entry: {desc, category, default_anchor, default_scale, symmetric, boxes}.
+"""
+from __future__ import annotations
+
+# Filled in batches by category. Seeded with the original 7 so nothing regresses.
+PARTS: dict[str, dict] = {
+    "horns": {
+        "desc": "a pair of curved horns", "category": "horns",
+        "default_anchor": "top", "default_scale": 1, "symmetric": True,
+        "boxes": [
+            {"x": -1, "y": 0, "z": 0, "w": 1, "h": 2, "d": 1, "color": "#efe2c0"},
+            {"x": -1, "y": 2, "z": 1, "w": 1, "h": 1, "d": 1, "color": "#efe2c0"},
+        ],
+    },
+    "wings": {
+        "desc": "a pair of wings on the sides", "category": "wings",
+        "default_anchor": "left", "default_scale": 1, "symmetric": True,
+        "boxes": [
+            {"x": -1, "y": 1, "z": 0, "w": 1, "h": 3, "d": 4, "color": "#cfe6ff"},
+        ],
+    },
+    "tail": {
+        "desc": "a long swishy tail at the back", "category": "tails",
+        "default_anchor": "rear", "default_scale": 1, "symmetric": False,
+        "boxes": [
+            {"x": 0, "y": 1, "z": 0, "w": 1, "h": 1, "d": 3, "color": "#caa06f"},
+            {"x": 0, "y": 2, "z": 2, "w": 1, "h": 1, "d": 2, "color": "#caa06f"},
+        ],
+    },
+    "ears": {
+        "desc": "two pointy ears on top", "category": "ears",
+        "default_anchor": "top", "default_scale": 1, "symmetric": True,
+        "boxes": [
+            {"x": -1, "y": 0, "z": 0, "w": 1, "h": 2, "d": 1, "color": "#caa06f"},
+        ],
+    },
+    "house": {
+        "desc": "a small house / hut", "category": "props",
+        "default_anchor": "rear", "default_scale": 2, "symmetric": False,
+        "boxes": [
+            {"x": 0, "y": 0, "z": 0, "w": 4, "h": 3, "d": 4, "color": "#d8b08c"},
+            {"x": 0, "y": 3, "z": 0, "w": 5, "h": 2, "d": 5, "color": "#b5532e"},
+            {"x": 0, "y": 0, "z": 2, "w": 1, "h": 2, "d": 1, "color": "#6b4423"},
+        ],
+    },
+    "hat": {
+        "desc": "a hat / cap on top of the head", "category": "headwear",
+        "default_anchor": "top", "default_scale": 1, "symmetric": False,
+        "boxes": [
+            {"x": 0, "y": 0, "z": 0, "w": 5, "h": 1, "d": 5, "color": "#3a3550"},
+            {"x": 0, "y": 1, "z": 0, "w": 3, "h": 2, "d": 3, "color": "#3a3550"},
+        ],
+    },
+    "crown": {
+        "desc": "a small crown on top", "category": "headwear",
+        "default_anchor": "top", "default_scale": 1, "symmetric": False,
+        "boxes": [
+            {"x": 0, "y": 0, "z": 0, "w": 4, "h": 1, "d": 4, "color": "#ffd34d"},
+            {"x": -1, "y": 1, "z": 0, "w": 1, "h": 1, "d": 1, "color": "#ffd34d"},
+            {"x": 1, "y": 1, "z": 0, "w": 1, "h": 1, "d": 1, "color": "#ffd34d"},
+            {"x": 0, "y": 1, "z": 0, "w": 1, "h": 1, "d": 1, "color": "#ffd34d"},
+        ],
+    },
+}

tests/test_parts.py

@@ -1,4 +1,4 @@
-from buddy_fusion.parts import PARTS, part_ids, catalog_text, ANCHORS
+from buddy_fusion.parts import PARTS, part_ids, catalog_text, ANCHORS, CATEGORIES, parts_by_category
 
 
 def test_every_part_is_well_formed():
@@ -6,6 +6,8 @@ def test_every_part_is_well_formed():
     for pid, p in PARTS.items():
         assert p["desc"] and isinstance(p["desc"], str)
         assert p["default_anchor"] in ANCHORS
+        assert p["category"] in CATEGORIES, f"{pid}: bad category {p.get('category')!r}"
+        assert isinstance(p["symmetric"], bool)
         assert isinstance(p["boxes"], list) and p["boxes"]
         for b in p["boxes"]:
             for k in ("x", "y", "z", "w", "h", "d"):
@@ -14,7 +16,14 @@ def test_every_part_is_well_formed():
             assert isinstance(b["color"], str) and b["color"].startswith("#")
 
 
-def test_catalog_text_lists_every_part():
+def test_ids_unique_and_catalog_lists_every_part():
+    assert len(part_ids()) == len(set(part_ids()))
     text = catalog_text()
     for pid in part_ids():
         assert pid in text
+
+
+def test_parts_by_category_covers_all():
+    grouped = parts_by_category()
+    flat = [pid for ids in grouped.values() for pid in ids]
+    assert sorted(flat) == sorted(part_ids())