Vibrante-Node v2.4.0 — Introduction

Vibrante-Node is a Python node-based visual framework for building modular systems through connected nodes and data flows. It provides an intuitive graph interface where complex logic can be constructed visually by linking nodes together.

The platform focuses on flexibility, extensibility, and developer productivity — making it suitable for building visual pipelines, automation workflows, and data-processing graphs across any domain. Node-based systems allow complex operations to be organized as interconnected components rather than traditional linear code structures, improving clarity and scalability in large workflows.

Vibrante-Node supports multiple interaction patterns:

• Visual Workflow Orchestration — build, run, and inspect complex multi-step workflows by wiring together reusable node blocks on an interactive PyQt5 canvas. Data flows left-to-right, execution flows via exec pins, and every wire value is inspectable after a run.
• Programmatic Automation — drive the execution engine via the scripting console or Python API without UI interaction.
• DCC Integration — build and control Houdini, Maya, and Blender scenes through live bridge and headless executor nodes.
• AI-Assisted Orchestration (optional advanced feature) — Claude, Codex CLI, Cursor, or any MCP-compatible AI client connects to the built-in MCP server (scripts/run_vibrante_mcp.py), accessing tools for scene inspection, planning, validation, and structured scene execution.

---

Table of Contents

1. Core Philosophy
2. Who Is This For
3. Feature Overview
4. Why Visual Node Graphs
5. Beyond VFX — General Automation
6. Supported Integrations
7. Architecture Overview
8. Version History
9. Documentation Map

---

Core Philosophy

Why Node-Based?

Scripts are linear. Node graphs are not. When a pipeline task grows beyond a handful of steps — conditional branching, parallel tracks, optional DCC calls, error routing — a script becomes a wall of nested if statements and callback chains that is hard to read, hard to modify, and impossible to hand off to a non-programmer. A node graph externalises the control flow into a visual structure that anyone can understand at a glance: data flows left to right, execution flows top to bottom, and every node is an isolated contract with defined inputs and outputs.

Vibrante-Node adopts the Unreal Engine Blueprint model of exec pins alongside data pins. Exec pins (the white square connectors) explicitly wire the order of operations. Data pins (the coloured circles) carry values between nodes. This dual-channel approach lets you build workflows that are simultaneously readable as flowcharts and correct as programs.

Why Async?

DCC operations — cooking a Houdini geometry, rendering a Maya scene, querying a Prism Pipeline project database — can take seconds or minutes. A synchronous engine would freeze the UI and prevent you from monitoring progress, reading log output, or stopping a runaway task. Vibrante-Node runs the execution engine on a dedicated asyncio event loop driven by a zero-interval QTimer on the Qt main thread (_EventLoopRunner in src/ui/window.py). Every node's execute() method is a Python coroutine (async def). This means:

• The UI stays responsive during execution.
• Long-running nodes can await external results without blocking.
• The Stop button works immediately.
• Multiple parallel execution branches can run concurrently.

Why Extensible?

No automation platform ships with every node you will ever need. Vibrante-Node is designed so that adding a new node requires exactly one file: a .json file containing the port definitions and the Python code. There is no registration step, no recompile, no plugin manifest beyond dropping the file in the nodes/ directory. The NodeRegistry discovers and registers it automatically on startup. For DCC-specific nodes, the Houdini plugin package (plugins/houdini/) adds nodes from v_nodes_houdini/ and scripts from v_scripts_houdini/ via environment variables — no changes to the core application.

Build Once → Reuse Everywhere

The GroupNode (Ctrl+Shift+G) collapses any selected sub-workflow into a single reusable node. Group nodes expose only the ports you choose, hide internal complexity, and can be nested inside other group nodes. A studio can build a prism_publish_asset group node once and reuse it as a black-box building block in every shot workflow across all projects — without copying the logic.

Workflow files are plain JSON. They can be checked into version control, diffed, merged, and shared across teams. A workflow that runs on one artist's machine runs identically on another with the same node library installed.

---

Who Is This For

Vibrante-Node is built for three overlapping audiences.

Visual Users and Technical Artists

Artists who need to automate repetitive tasks — renaming files, batch-exporting assets, running Houdini geometry operations — but do not want to write Python scripts. They build workflows by dragging nodes from the Library panel, connecting them on the canvas, and pressing F5. The node library is organised by category, searchable by name, and produces immediate visual feedback through the log panel and live wire value inspector.

Typical tasks: batch asset export, scene setup automation, file organisation, render submission.

Pipeline TDs and Studio Engineers

Technical Directors who build and maintain shared workflows for a team. They author custom nodes using the Node Builder or by editing JSON files directly, package them as Houdini plugin additions or standalone nodes/ files, and distribute them to artists. They integrate with Prism Pipeline for project/asset/shot management and with Deadline for render farm submission.

Typical tasks: pipeline integration nodes, studio-specific workflow templates, Prism entity queries, Deadline job configuration.

Python Developers

Developers who want to build automated systems with a visual interface without writing a UI framework from scratch. They subclass BaseNode, implement async def execute(self, inputs), and return a dict. The engine, canvas, log panel, autosave, and all other infrastructure are provided. They can also drive Vibrante-Node programmatically via the automation API (AUTOMATION_API.md).

Typical tasks: custom automation tooling, CI/CD pipeline steps, data processing workflows, service integrations.

AI Developers and ML Engineers

Developers who want Claude, Codex CLI, Cursor, or another MCP-compatible AI to build, inspect, and modify Houdini scenes autonomously under human supervision. They run scripts/run_vibrante_mcp.py, configure their AI client, and then describe in natural language what they want built. The AI uses the planning and validation tools; the human reviews the generated plan and approves high-risk operations before execution.

Typical tasks: AI-driven scene assembly, iterative procedural content generation, natural-language Houdini automation, multi-agent production pipelines.

---

Feature Overview

Advanced Runtime Extensions (optional — v2.4.0)

Available when mcp>=1.0.0 is installed. Headless — no Qt or display server required.

---

Why Visual Node Graphs

The Problem with Plain Scripts

Consider a pipeline task: open a Maya scene, export alembic geometry, import it into Houdini, run a simulation, export the result, and submit a Deadline render job — but only if the simulation produces more than 1000 points, otherwise skip the render and log a warning. In a Python script this requires careful state management, nested conditionals, error handling at every step, and careful documentation so the next person can understand what it does.

In Vibrante-Node, this is five to ten nodes on a canvas. The conditional branch is visible as two exec paths. Error handling is a separate exec path from exec_fail. Anyone can understand the flow in ten seconds.

Specific Benefits

Discoverability. Every available operation is in the node library, searchable by name. There is no need to remember function names or read API documentation to get started.

Reusability. A GroupNode packages any sub-workflow into a single named block that can be duplicated, shared, or nested. Workflows can be saved as templates and reused across projects.

Live inspection. The live wire inspector shows the last value that flowed through every connection after execution. There is no need to add print statements and re-run to debug data flow — hover the wire.

Non-destructive iteration. Bypass a node with Ctrl+B to skip it without deleting it. Reconnect differently. The canvas is a whiteboard that invites experimentation.

Team collaboration. A workflow file is a JSON document. It can be checked into version control, diffed, and merged. Artists can build workflows without writing code; developers can build nodes without building UIs.

---

Beyond VFX — General Automation

While Vibrante-Node ships with deep VFX and animation pipeline integrations, the core platform is entirely domain-agnostic. The execution engine, canvas, node library, and file format do not have any VFX-specific logic. Any Python task can become a node.

Examples of non-VFX use cases:

• File processing pipelines — watch a folder, process new files, move or rename outputs, write a report.
• Data transformation — load JSON or CSV, filter, transform, write results. The python_script node runs arbitrary Python inline.
• API orchestration — call REST APIs in sequence, pass results between calls, handle errors on separate branches.
• Build and deployment automation — run shell commands via python_script, check exit codes via compare or logical_gate, conditionally proceed.
• Machine learning experiments — string together data loading, preprocessing, model training, and evaluation steps with visual control flow.
• Database workflows — query databases, transform results, insert or update records, log summaries.
• Report generation — pull data from multiple sources, aggregate, format, write files.

Any step that can be expressed as a Python function with typed inputs and outputs can be a Vibrante-Node node.

---

Supported Integrations

Houdini (Interactive Bridge)

The Houdini integration runs a JSON-RPC server (vibrante_hou_server.py) inside a live Houdini session over a local TCP socket. Vibrante-Node nodes call bridge.create_node(), bridge.set_parm(), bridge.cook_node(), and other methods to build and run Houdini networks interactively. The bridge supports all common Houdini operations: create/delete nodes, set parameters, wire connections, cook, save hip files, set keyframes, run arbitrary Python code inside Houdini via bridge.run_code().

The Houdini plugin is installed by placing plugins/houdini/vibrante_node.json in the Houdini packages folder. It adds the Vibrante-Node menu to Houdini's menu bar, loads a shelf tool, and provides Launch Vibrante-Node and Reconnect commands.

Maya (Headless Executor)

Maya nodes follow an "action list" pattern. Each maya_action_* node appends a dictionary to a list. The maya_headless node receives the completed action list and passes it to a headless Maya subprocess (mayapy) that executes each action in sequence. This approach does not require a running Maya session — it is suitable for batch processing and render farm pipelines.

Actions include: open/save/new scene, import/export alembic/FBX/OBJ, import/export camera, reference scene, assign material, create render layer, set AOVs, set render settings, set frame range, playblast, and custom Python.

Blender (Headless Executor)

Blender nodes use the same action-list pattern as Maya. Each blender_action_* node appends an action dict. The executor runs Blender in background mode (blender --background --python). Actions include: open/save/new blend file, import/export alembic/FBX/glTF/OBJ/USD, render, set render settings, set frame range, scene info, and custom Python.

Prism Pipeline

Prism Pipeline is a studio-grade project management system. Vibrante-Node ships with over 60 Prism nodes covering the full Prism API surface: initialise PrismCore, list/create/switch projects, query assets/shots/sequences, get product versions, export paths, save scene versions, create playblasts, manage USD layers, trigger callbacks, and more.

PrismCore is resolved automatically from a shared cache — there is no need to wire a core output between every Prism node. Place a prism_core_init node anywhere in the graph and all prism_* nodes find the same instance.

Deadline (Thinkbox)

Deadline submission nodes (deadline_maya_submit, deadline_houdini_submit, deadline_blender_submit) wrap the Deadline command-line client to submit render jobs with configurable job name, pool, priority, frame range, and renderer settings.

MCP Runtime (Advanced)

Vibrante-Node can run as a headless MCP server. An external AI client (Claude Desktop, Codex CLI, Cursor) connects via stdio and receives tools for scene inspection, planning, validation, and structured scene execution. No display server or Qt required. See AI Runtime & MCP Integration in the full documentation for setup and the complete tool list.

---

Architecture Overview

Vibrante-Node has a layered architecture. The visual canvas drives the execution engine, which runs nodes that call integrations and utilities. The Advanced Runtime Extensions are an optional layer used by hou_mcp_* nodes and the headless MCP server.

+------------------------------- VISUAL CANVAS ------------------------------+
|  LAYER 1  MainWindow (PyQt5)                                              |
|  Menu | Toolbar | Tab Bar | Library Panel | Log Panel | Scripting Console |
+------------------------------------+--------------------------------------+
                                     | F5 -> WorkflowModel
                                     v
+------------------------------- EXECUTION ENGINE ---------------------------+
|  LAYER 2  Core                                                            |
|  NetworkExecutor (asyncio) | GraphManager (DAG+toposort)                 |
|  NodeRegistry | WorkflowModel (Pydantic) | Persistence (JSON)            |
+------------------------------------+--------------------------------------+
                                     | calls execute()
                                     v
+------------------------------- NODE LIBRARY --------------------------------+
|  LAYER 3  Nodes  (nodes/ + plugins/)                                      |
|  BaseNode subclasses: General | Houdini | Maya | Blender | Prism | MCP   |
+-------------------+------------------------+------------------------------+
                    |                        |
                    v                        v
+------- UTILS & INTEGRATIONS (4a) -----+  +--- Headless Subprocesses (4b)--+
|  src/utils/                           |  |  mayapy / blender --bg         |
|  HouBridge (TCP/JSON-RPC, port 18811) |  |  PrismCore (shared singleton)  |
|  EnvManager | qt_compat               |  +--------------------------------+
+---------------------------------------+
                                     |
                    (optional) ──────v
+-------------------- ADVANCED RUNTIME EXTENSIONS --------------------------+
|  OPTIONAL  src/runtime/  ← used only by hou_mcp_* nodes and MCP server  |
|  MCP server | AI planning | transactions | validation | analytics        |
+----------------------------------------------------------------------------+

Execution flow (F5):

1. The user builds a workflow on the canvas — nodes connected by exec and data pins.
2. On F5, MainWindow serialises the scene to a WorkflowModel, builds a GraphManager (DAG), and creates a NetworkExecutor.
3. The executor fires entry-node execute() coroutines and follows exec_out connections in topological order.
4. Results broadcast via Qt signals: node_output → live wire inspector, node_log → log panel.

---

Version History

---

Documentation Map

Primary Guides (root-level docs)

Portal Documentation (this site)

Release Notes

---

Vibrante-Node v2.4.0 — Released 2026-05-26