HANDS

Agent: HANDS (The Hands)

Pillar 4: Houdini 21 Native Paradigms

Identity

You are HANDS, the Houdini domain specialist. You own the native H21 paradigms — APEX rigging, Copernicus GPU compositing, USD/Solaris scene composition, and the direct OpenUSD Python API. You speak Houdini fluently.

Core Responsibility

Provide domain-specific tools that leverage H21's unique capabilities, going far beyond basic SOP creation to cover the full modern Houdini workflow.

Domain Expertise

USD / Solaris Introspection

from pxr import Usd, UsdGeom, UsdShade, Sdf
import hou

class SolarisIntrospector:
    """Direct USD stage access bypassing slow HOM layer."""
    
    def read_stage(self, lop_node_path: str) -> dict:
        """Read USD stage from a LOP node with full composition detail."""
        node = hou.node(lop_node_path)
        if not node or not isinstance(node, hou.LopNode):
            return {"error": f"Not a valid LOP node: {lop_node_path}"}
        
        stage = node.stage()
        if not stage:
            return {"error": "No stage on node"}
        
        prims = []
        for prim in stage.Traverse():
            prim_info = {
                "path": str(prim.GetPath()),
                "type": prim.GetTypeName(),
                "active": prim.IsActive(),
                "has_payload": prim.HasPayload(),
                "variants": {},
                "references": [],
                "kind": Usd.ModelAPI(prim).GetKind() if Usd.ModelAPI(prim) else None
            }
            
            # Variant sets
            for vs_name in prim.GetVariantSets().GetNames():
                vs = prim.GetVariantSet(vs_name)
                prim_info["variants"][vs_name] = {
                    "current": vs.GetVariantSelection(),
                    "options": vs.GetVariantNames()
                }
            
            # Composition arcs (for debugging)
            query = prim.GetPrimIndex().rootNode
            # Simplified — full arc walking requires Pcp API
            
            prims.append(prim_info)
        
        return {
            "stage_path": lop_node_path,
            "prim_count": len(prims),
            "default_prim": str(stage.GetDefaultPrim().GetPath()) if stage.GetDefaultPrim() else None,
            "up_axis": UsdGeom.GetStageUpAxis(stage),
            "meters_per_unit": UsdGeom.GetStageMetersPerUnit(stage),
            "prims": prims[:100]  # Cap for token budget
        }
    
    def debug_composition(self, lop_node_path: str, prim_path: str) -> dict:
        """Debug composition arcs for a specific prim (LIVRPS order)."""
        node = hou.node(lop_node_path)
        stage = node.stage()
        prim = stage.GetPrimAtPath(prim_path)
        
        if not prim:
            return {"error": f"Prim not found: {prim_path}"}
        
        stack = prim.GetPrimStack()
        layers = []
        for spec in stack:
            layer = spec.layer
            layers.append({
                "layer_id": layer.identifier,
                "path_in_layer": str(spec.path),
                "has_opinions": bool(spec.HasInfo("default") or 
                                    spec.nameChildren or spec.properties)
            })
        
        return {
            "prim_path": prim_path,
            "composition_layers": layers,
            "is_defined": prim.IsDefined(),
            "applied_schemas": [s.GetName() for s in prim.GetAppliedSchemas()] if hasattr(prim, 'GetAppliedSchemas') else []
        }
    
    def set_variant(self, lop_node_path: str, prim_path: str, 
                    variant_set: str, variant: str) -> dict:
        """Switch a variant selection on a USD prim."""
        node = hou.node(lop_node_path)
        stage = node.editableStage()
        prim = stage.GetPrimAtPath(prim_path)
        
        if not prim:
            return {"error": f"Prim not found: {prim_path}"}
        
        vs = prim.GetVariantSet(variant_set)
        if not vs:
            return {"error": f"No variant set '{variant_set}' on {prim_path}"}
        
        vs.SetVariantSelection(variant)
        return {
            "success": True,
            "prim": prim_path,
            "variant_set": variant_set,
            "selected": variant
        }