Help, I'm using Houdini

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 3 — Slow and Steady

If you've ever used Houdini for VFX, Procedural modelling, animation or CG content creation then you're probably familiar with its help-browser. Houdini's help-browser is a very useful source of documentation for any user looking for more information about all parts of Houdini. However, It is not context-aware, and does not know how a user's node networks are wired, or what parameter settings have been applied to a given or selected node. I built a new shelf tool that stays on that displays more details about actively selected nodes and uses the currently installed local-help file that shipped with the user's version of Houdini.

What I Built

houdini-wizard is a super-charged help-browser shelf tool. With any node selected, it will display organised documentation that updates based on what node is actively selected in the node network viewer. You can continue work in the network panel, while the tool is open and it will keep updating its help information or minimise it to avoid taking up screen-space.

The coolest features this tool has that you won't find in a standard help-browser:

• Update help documentation for newly selected nodes.
• Shows node's Input and Output connection status.
• Adopts Houdini's existing Parameter organisation.
• Enriches Parameter documentation by including their tooltips, keeping all this info in one panel and not just in the UI.
• Maintains existing UI helper-text that users can access on-hover of parameter settings.

GitHub repository: AbisoyeOnanuga/houdini-wizard

Demo

If you have not used Houdini before, a scene is built by wiring small boxes together in a network. Each box is a node, its settings are parameters, and each setting has a short hover tip. When a node cannot compute its result, Houdini raises a cook error.

The standard help browser opens the manual for that type of node, from the very top of the page. It does not know which node you clicked, what is wired into it, or which setting you are trying to understand.

houdini-wizard sits beside your work and reads the room. You can also open it with nothing selected to browse the full help library by category, and the moment you click a node in your network, the view switches to that node.

How it handles parameter tips:

• When the tip is already clear, it leaves it alone: On an Ocean Spectrum node, the Wind Speed tip already explains that "Higher wind speeds create larger low-frequency waves." The tool keeps that exact sentence and simply places the slider's range in front of it, so you see the numbers and the explanation together.
• When the tip is too thin, it makes it readable: On a Rotate parameter, the built-in tip is four words: "Rotate angles in degrees." That tells you the unit, not how the slider behaves. Here, the tool asks Gemma for one plain sentence using the slider's actual range (0 to 360): 0 means no rotation, and positive and negative values turn in opposite directions.
• When a node fails to cook: If the error message already names a parameter, the tool jumps straight to that section of the manual without calling the model. If the error is vague, Gemma picks the closest heading from that node's help file, and the tool quotes the manual directly.

Code

Most parameters never touch the model. If a tooltip already explains what happens when you raise or lower a value, rewriting it only wastes time and risks changing a good explanation.

This check is the gate in front of Gemma. It looks for cause-and-effect words that are already in the help text, and only lets short, label-like tips pass through:

def _needs_model(meaning: str) -> bool:
    if _effect_clause(meaning):
        return False
    words = re.findall(r"[A-Za-z0-9']+", meaning)
    return len(words) <= 6

Wind Speed contains "higher", so _effect_clause catches it and the original tooltip stays intact. "Rotate angles in degrees" has no effect words and is only four words long, so it gets the one-line value guide.

How I Built It

Each tool in the stack has one job, so the window stays fast while you are working in a scene:

• Houdini Python (hou) and PySide: Runs inside Houdini to read the active node, its live input and output wires, its parameter tabs, and the slider ranges on the node you have open.
• Installed Houdini Help ($HFS/houdini/help): Every node page, shelf step, and diagram is read directly from the zip archives that shipped with the user's installed version of Houdini, so the documentation always matches the software on screen.
• Gemma 3 4B (via Ollama): Runs locally to handle the two places where a static page falls short: matching an unclear cook error to a help heading, and turning bare four-word parameter labels into a readable sentence about the slider's range.
• Focused Skill Files: Instead of running an open-ended chat loop that might invent settings or try to art-direct the scene, Gemma is paired with two strict skill prompts. One only allows it to return an existing heading name from the file; the other only allows a single sentence using the numbers actually present on that parameter's slider.
• Temporal (Python SDK): Wraps the heading lookup in a durable workflow so a slow local model call can retry cleanly, and if Houdini closes mid-session, reopening the shelf on that node restores the same help card without re-running the model.
• Entire: Tracks the coding sessions behind the repo so you can query why specific guardrails exist—such as why the shelf skips Gemma whenever a parameter heading is already named.

A multi-process agent harness is for a loop: the model picks the next tool, and several processes keep a conversation going. This shelf does not need that. The path is already decided. Opening a node saves that card, whether or not the node is showing an error, a warning, or a message. Python quotes a heading that is already named, and that save does not call Gemma. Gemma runs inside a Temporal activity only when that text names no heading, and it may only return one heading from that file, or none. If the call times out, the same run tries again, up to three times, so a second call cannot also succeed. The browser stays closed until you click Session log or Developer monitor on the panel. Session log shows the newest node first, plus a Model view for tokens in and out, time spent, and model memory, and links to the public Entire session for how the code was built.

flowchart TD
  activeNode["active network node"] --> wizard["houdini-wizard shelf"]
  wizard --> helpFile["installed help file"]
  helpFile --> gemma["Gemma picks one heading, or a short value line"]
  gemma --> quote["wizard quotes that help section"]
  gemma --> noMatch["no match lists headings you can open"]
  quote --> temporal["Temporal keeps this card"]
  noMatch --> temporal
  temporal --> updated["you update the node"]

Why Does Open Innovation Matter

3D and VFX scenes are often under NDA, and artists regularly work on machines that cannot send scene data or node graphs to a cloud API. Just as important, Houdini changes from version to version—a generic web search or a cloud model trained on older forum posts will confidently point you to parameters that do not exist in your build.

Building this with open-weight and open-source tools solves both problems at once:

• Local and private by default: Running Gemma through Ollama on the artist's workstation means node names, cook errors, and studio paths never leave the machine.
• Grounded in the truth on disk: By pairing an open-weight model with the documentation archives already installed with Houdini, the tool improves how help is organised and read without inventing parameter values. It follows the same philosophy Saketh Balijepalli described in NannaDesk: An AI Assistant for My Dad That's Not Allowed to Guess: use the small local model for language, and keep the facts deterministic.
• Inspectable workflow and history: Using Temporal and Entire means both the runtime retries and the development decisions behind the tool are open, reproducible, and easy for another developer or TD to inspect.

The artist stays in control of the shot. houdini-wizard never changes a value, flips a flag, or wires a node for you—it makes the documentation you already have easier to read while you work.

Prize Categories

• Gemma: To match vague cook errors to the right section of the manual and turn short parameter labels into clear slider explanations, while running locally through Ollama.
• Temporal: To store the tool's lookup history, retry local model calls when they time out, and reopen that same help card if Houdini closes while you are working on a node.
• Entire: To record the agent sessions behind the build and make it easy to search why specific design choices and model guardrails exist in the codebase.