Initial commit: Hermes-Houdini Bridge

- Shelf tool to open/close command port in Houdini - hhb client script (eval, script, get-selected, set-param, etc.) - Hermes skill with standard hou module workflows - Example: create pyro setup - hou module quick reference
2026-07-12 12:14:36 +00:00
commit dd2a1734eb
6 changed files with 621 additions and 0 deletions
@@ -0,0 +1,82 @@
+# Hermes-Houdini Bridge
+
+> Hermes Agent ↔ Houdini Python Bridge — remote node control, parameter editing, VEX injection, and scene querying via Houdini's built-in `hcommand` protocol.
+
+## Architecture
+
+```
+Hermes Agent (orange-desktop)          Houdini 21.0 (fedora.fritz.box)
+┌─────────────────────┐                ┌──────────────────────────────┐
+│  hhb eval "code"    │──SSH──────────→│  hcommand PORT "python code" │
+│  hhb script file.py │                │       ↓                      │
+│  hhb get-selected   │                │  hou module (running session) │
+└─────────────────────┘                └──────────────────────────────┘
+```
+
+No custom server needed — uses Houdini's built-in `openport` + `hcommand` protocol. The bridge wraps SSH and command quoting so Hermes can send Python code to your live Houdini session.
+
+## Quick Start
+
+### 1. Install the Shelf Tool (once)
+
+Copy `houdini/shelf/hermes_bridge.shelf` to your Houdini toolbar, or run the shelf script directly in Houdini's Python Shell.
+
+### 2. Open the Bridge (every session)
+
+Click the **Hermes Bridge** shelf button in Houdini. It opens port 12345 and shows a status dialog.
+
+### 3. Use from Hermes
+
+```bash
+# Get selected node info
+./hermes/bin/hhb get-selected
+
+# Set a parameter
+./hermes/bin/hhb eval "hou.selectedNodes()[0].parm('file').set('/path/to/file.abc')"
+
+# Query connections
+./hermes/bin/hhb eval "print(hou.selectedNodes()[0].inputConnections())"
+
+# Execute a complex Python script
+./hermes/bin/hhb script ./examples/create_pyro_setup.py
+```
+
+## Requirements
+
+- Houdini 20+ (tested with 21.0)
+- SSH access from Hermes host to Houdini workstation
+- Network connectivity (port 12345, default)
+
+## Project Structure
+
+```
+hermes-houdini-bridge/
+├── houdini/
+│   └── shelf/
+│       └── hermes_bridge.shelf    # Shelf tool: open/close port
+├── hermes/
+│   ├── bin/
+│   │   └── hhb                    # Client: send commands to Houdini
+│   └── skill/
+│       └── SKILL.md               # Hermes skill for standard workflows
+├── examples/
+│   └── create_pyro_setup.py       # Example: build a pyro sim
+├── docs/
+│   └── REFERENCE.md               # hou module cheat sheet
+└── README.md
+```
+
+## Security
+
+- Port 12345 opens on `0.0.0.0` — only use on trusted networks
+- To restrict to localhost: modify the shelf tool's `openport` call to `hou.hscript('openport 12345 +.+.+.+')`
+- The bridge uses Hermes' existing SSH key — no additional credentials needed
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `hcommand: connect failed` | Port not open. Click shelf button in Houdini. |
+| `hcommand: connection refused` | Houdini not running or port blocked by firewall. |
+| Python error in output | Code has syntax issues. Test in Houdini Python Shell first. |
+| `ModuleNotFoundError: No module named 'hou'` | Running hython directly, not through hcommand. Use `hhb`. |