# 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. Clone & Install (once)

```bash
cd ~/houdini21.0
git clone https://git.niklashmotion.art/Hermes/hermes-houdini-bridge.git hermes_houdini_bridge
cd hermes_houdini_bridge
bash install.sh
```

`install.sh` generates a Houdini package descriptor in `~/houdini21.0/packages/`. The plugin lives directly inside the Houdini prefs directory — no CGI project pollution.

### 2. Open the Panel (every session)

Restart Houdini, then: **Windows → Hermes Bridge**

The panel lets you:
- Choose a port number
- Open/Close the bridge with one click
- Copy a ready-to-use prompt: *"Hey Hermes, I have a Houdini session running on [hostname] (port 12345)"*

### 3. Update

```bash
cd hermes-houdini-bridge && git pull
```

### 4. Uninstall

```bash
rm ~/houdini21.0/packages/hermes_houdini_bridge.json
```

```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`. |