The Assistant 

The Assistant is an AI agent built into Ornatrix App. You describe what you want in plain language and it builds it: it adds operators, tunes their parameters, renders the viewport to check its own work, and adjusts until the result matches what you asked for. It works on your live groom, so everything it does appears in the Operator Stack exactly as if you had done it by hand, and everything is undoable.

The Assistant is experimental. It runs on either Claude (Anthropic) or an OpenAI model, whichever you choose, and requires your own API key from that vendor: Ornatrix does not include or resell access to the models, and usage is billed to your own Anthropic or OpenAI account.

 

Requirements 

• The AI Assistant component of Ornatrix App, offered by the installer when it asks which components to install. It is selected by default and adds about 300 MB. Part of it is downloaded while the installer runs, so the machine needs an internet connection at that point.
• An API key from the vendor you choose: an Anthropic key from https://platform.claude.com for Claude, or an OpenAI key from https://platform.openai.com for an OpenAI model. The key is yours; you are billed for what the Assistant uses.
• An internet connection while you use it. The Assistant sends your requests to the chosen vendor's servers to be processed.

 

Choosing a provider and entering your API key 

There is nothing to switch on: the Assistant's controls are always there. It cannot run anything until it has your key, which you enter once and Ornatrix remembers.

1. Open the Console panel and tick Assistant in its toolbar.
2. A provider list appears next to the checkbox, offering Claude and OpenAI. Pick the one you have a key for.
3. A password field follows it. Paste that vendor's API key there. Each vendor's key is stored separately in your local settings, so switching between them later loses neither, and a key is sent only to the vendor it belongs to.

The Claude choice uses Anthropic's current model; the OpenAI choice uses OpenAI's current model. To name a specific model instead, enter it under Model in Settings -> Interface; leave the field empty to stay on the default. Changing the provider, the key or the model restarts the Assistant, so do it between requests rather than while one is running.

The command line at the bottom of the Console now accepts plain language instead of Python. The hint text changes to confirm this.

Should you make a request before entering a key - from the Console, or from the Auto button described below - the Assistant opens the Console for you, ticks Assistant and puts the cursor in the key field, so the answer is where you are already looking. If the AI Assistant component was never installed, a dialog says so instead, and tells you which part of it is missing.

 

Using it 

Type what you want and press Enter. Some examples that work well:

• "Create a furry sphere."
• "Make the hair longer and curlier."
• "This looks too uniform - add some variation to the length."
• "Show me a render."

Two things are worth knowing to get good results:

• It works on the current groom. If you want it to start fresh, clear the scene first, or say so in your request.
• It can see its own renders. Asking it to "check" or "show" the result makes it render and look at the image, which noticeably improves what it produces on visual requests such as curliness or density.

Everything the Assistant does goes through the normal command stack, so it is all undoable. By default a whole request is folded into a single undo step named after what you asked for, so Ctrl+Z takes the groom back to how it was before the request and Ctrl+Y brings all of it back. Anything you changed yourself while the Assistant was working is part of that same step. See Undoing a request below.

 

Asking to be shown 

Ask the Assistant to show you something - "show me how to add a Curl operator", "where do I change the hair colour?", "walk me through making the hair longer" - and instead of changing the groom behind the scenes it works the application's own interface in front of you: a pointer in the Assistant's colour travels to each control, the control is highlighted, and a short caption beside the pointer says what the step is for. It opens the same menus, panels and fields you would use yourself, so what you watch is what you would do, and the badge at the top of the window reads "Working the interface" with the caption of the current step.

Which of the two it does is decided by how you ask. Asking for a result ("make the hair curlier") gets the result, directly; asking to be shown gets the demonstration. Preparation nobody needs to see, such as loading a groom or framing the view, is still done directly, and the Assistant checks the outcome of what it showed the same way it checks any other request.

Your mouse and keyboard stay yours throughout. If you move the mouse over the window or press a key while a step is being shown, the Assistant stops at once, the pointer is handed back to you, and a card in the bottom-right corner asks whether it should continue or stop. Continue resumes the demonstration from the step it was on; Stop ends the request, and the changes made so far are handled as for any cancelled request.

The Assistant cannot operate the file dialogs (opening, saving, browsing for a file), so those steps are done directly rather than shown.

 

Authoring a groom's parameters 

A groom can present a small panel of parameters of its own - a handful of named controls such as Length, Curliness or Random Seed - which stand in front of the operator stack, so the groom can be used, and handed to someone else, without their having to know which operator each value belongs to. These appear in the Groom Properties panel, and in the properties of a Groom operator which references the groom. Which parameters a groom has is decided by whoever built it, and writing them out by hand is the fiddly part: each one has to name the operator parameter it drives, along with a range and a default.

The Assistant can do that work for you. The Groom Properties panel carries an Auto button beside Edit, which opens a menu of three entries: Parameters, which authors the panel; Variations, which uses the panel to make several different looks of the groom, each saved as a preset; and Both, which does the one and then the other.

 

Detail levels 

The Parameters entry offers five levels of detail:

1. Minimal
2. Basic
3. Standard
4. Detailed
5. Exhaustive

Picking one asks the Assistant to go through the groom's operators and build the panel at roughly that size. A Minimal panel exposes only the few values that matter most; an Exhaustive one covers everything that noticeably changes the look of the character, grouped into categories. In between, the number of parameters is chosen to stay readable in the panel rather than to be complete. The Assistant tries out the parameters it picks in order to settle on a sensible range for each, so this is a real piece of work rather than an instant one; the badge at the top of the window reports what it is doing, as with any other request.

Existing parameters are not thrown away. If the groom already has some, the Assistant checks them, corrects anything broken, and builds the new ones on top - so you can ask for Minimal, adjust the result by hand, and later ask for Exhaustive to expand on what you kept.

 

Refining what is there 

The last entry under Parameters, Refine..., is for a single change to a panel you are otherwise happy with. It opens a dialog where you describe what you want in your own words, for example:

Add the gradient map's middle parameter as a "Color Blend" param

Only what you describe is changed. Every other parameter keeps its name, type, expression, range, default, group and position: the Assistant is told not to rename, regroup, reorder or re-range anything to tidy the panel up, and not to add parameters you did not ask for. If it notices a problem elsewhere while it works, it mentions it in its reply and leaves it alone for you to decide about. When it is done it says in a sentence or two what it changed, so you can see the edit stayed within what you asked.

Ctrl+Enter submits your description. Enter starts a new line, so a longer request can be laid out over several. The next time you open the dialog your previous request is offered again, selected, since a follow-up is usually a variation on the one before; typing replaces it outright when it is not.

If the groom has no parameters yet, Refine... creates them from your description alone, covering what you asked for and nothing beyond it. That is the way to get one specific small panel without going through a detail level first.

 

Making variations of the look 

Once a groom has a panel, Variations asks the Assistant to use it: to dial the parameters into several distinct looks of the same hair style - shorter and longer, straight against wavy against curly, sparser and fuller, another colour where colour is exposed - and to save each one as a preset of the groom, under a name a stylist would use. The entry asks how many looks you want: 2, 5, 10, 20, or Custom... for a number of your own. The count includes the Default, the groom as it is now, so asking for five produces four new presets.

The Assistant changes nothing but the values of the exposed parameters: the parameters themselves, the operators and the graph are left exactly as they are, which is what keeps every look a preset you can step in and out of. It renders each look and judges it before saving it, and the one requirement it works to is that a look reads as intentional - no strands through the scalp, nothing exploded or empty, nothing that looks like a mistake. When it is done it puts the parameters back where they were, so the groom is as you left it, and the new presets are waiting in the preset drop-down at the top of the panel. Presets saved this way are ordinary groom presets: they are stored inside the groom, travel with it, and are offered as variations when the groom is used as a graft groom.

A panel with only one or two parameters gives the Assistant little to work with; if it cannot make distinct looks from what is exposed it says so, rather than saving near identical presets. Author a fuller panel first, or use Both.

 

Both 

Both authors the parameters and then makes the variations, as a single request: the panel is built at the detail level last picked under Parameters (Standard until you have picked one; the entry's heading says which), and the variations follow from the panel that produces. It offers the same counts as Variations. Because the two run as one request, one Ctrl+Z takes back both the panel and the presets.

Any of these requests goes to the same Assistant as the Console does, so the work appears in the Console, the badge and border behave as described below, and the whole request is one undo step. If the Assistant is already busy, your request is queued behind the current one.

 

While it is working 

A request is rarely instant. A single one usually becomes several operations: the Assistant looks at the current scene, makes a change, renders the viewport to see the result, and then refines. While that is happening the application makes it plain that an agent is in control.

• The window is framed. A coloured border runs around the whole application and pulses about once a second for as long as the Assistant is working. It stops pulsing and holds steady when the Assistant is waiting for an answer from you, so a glance at the edge of the screen tells you whose turn it is.
• A badge appears at the top of the window, naming what the Assistant is doing right now - "Adding an operator", "Rendering the groom" - and how long the request has been running.
• The Console records each operation, so you can follow the work in detail while it happens and read it back afterwards. Long replies are shortened to their first line; hover it to read the whole reply, and copying the line copies the full text.

 

Cancelling 

The badge carries a Cancel button, and a second one appears at the end of the Console command line while a request is running. Either one abandons the request.

The Assistant stops a moment later rather than instantly, so a cancelled request has usually changed something already. Ornatrix asks what to do with those changes: a dialog names the step and offers Keep Changes, which leaves them in place as one undo step you can still undo by hand, or Undo Changes, which takes the groom straight back to how it was before the request. Undoing this way is not destructive - the whole request stays on the redo stack, so Ctrl+Y brings it back if you change your mind.

Tick Don't ask again in that dialog to always do whatever you chose, without being asked in future. The choice can be changed later from the settings described below.

 

Typing while it works 

You do not have to wait for a request to finish before typing the next one. A message sent while the Assistant is busy is queued rather than lost, and goes out as soon as the current request ends; the badge shows how many messages are waiting. Cancelling discards the queue along with the request.

 

Undoing a request 

A single request usually becomes many operations, and undoing them one at a time would be tedious and easy to get wrong. Ornatrix therefore records the whole of a request as one undo step, named after what you asked for, so the Edit menu reads for example "Undo: AI: make the hair curly". One Ctrl+Z returns the groom to the state it was in before you pressed Enter, and one Ctrl+Y reapplies the entire request.

The step covers everything that happened while the Assistant was working, including changes you made alongside it. That is deliberate: while a request runs you are free to keep working, and undoing partway into a shared stretch of history would leave the groom in a state neither of you produced.

If a request is followed by further messages you typed while it was running, all of them belong to the same step, and its name says so.

Occasionally a request cannot honestly be described as one step, and Ornatrix then leaves its operations as separate undo entries rather than promising something it cannot deliver. That happens when the Assistant replaces the whole groom more than once during a request (each replacement discards the previous one, which no later undo can bring back), and when it undoes further back than the point its own request started from.

Two settings under Interface -> Assistant control this:

• Group AI Assistant changes into a single undo step - on by default. Turn it off to have every operation stay its own undo entry, as any other edit would.
• When an AI Assistant action is cancelled - what happens to the changes of a cancelled request: Ask what to do (the default, described under Cancelling above), Keep the changes, or Undo the changes.

 

Notes and questions 

The Assistant can also put messages on screen instead of only in the Console. They appear as cards in the bottom-right corner, labelled Assistant.

• Passing notes fade away on their own after a few seconds. They report something the Assistant has just done and that you can safely miss.
• Pinned notes stay until you close them. The Assistant uses these for something worth reading after the fact: what it changed and why, a caveat, or a result you need to act on.
• Questions offer a row of answers to choose from, and the Assistant waits for your choice before carrying on. Use them: a question means the request was genuinely ambiguous, and answering it gets you what you meant rather than a guess. If you close a question instead of answering it, the Assistant is told that you declined, picks the most reasonable option itself, and tells you which one it took.

Each of these is written to the Console as well, so the conversation stays complete once a card is gone.

 

What it can and cannot do 

The Assistant can only operate on grooms. It can inspect the scene and the operator graph, create operators and connect them, read and change operator parameters, read and rewrite the groom's own parameters panel, set the values of those parameters and save, apply and delete the groom's presets, load and save grooms, resolve asset search paths, render the viewport, manage operator plugins, and work the application's interface in front of you (see Asking to be shown).

Beyond that it has no shell access and no way to browse the web: it cannot run commands, and it reaches nothing but your groom and the vendor you chose. It can read files, which is what lets it follow a skill you have added in the folder the button beside the API key field opens, but it cannot write them unless you turn on Let the Assistant write files under Interface -> Assistant. That switch is off by default and exists mainly so the Assistant can record a skill of its own; with it on, it can write anywhere that folder reaches. It also cannot close the application.

 

Cost and privacy 

The Assistant sends your typed requests, a description of your groom's structure (operator names, types and parameter values), and any viewport renders it takes, to the vendor you chose (Anthropic or OpenAI) for processing. It does not send your groom files or your source meshes.

Because you supply your own API key, all usage is billed directly to your own Anthropic or OpenAI account. A single request that involves several renders costs more than a simple question. If cost matters to you, prefer specific requests over open-ended ones, and cancel a request that has clearly gone the wrong way rather than letting it finish.

 

Troubleshooting 

It says the AI Assistant is not installed. The AI Assistant component was not selected when Ornatrix App was installed, or the part of it which is downloaded during installation never arrived - most often because the machine was offline at the time, or a proxy or firewall blocked the download. The dialog says which of the two it is. Run the installer again with AI Assistant ticked to add it.

"ANTHROPIC_API_KEY is not set" or "OPENAI_API_KEY is not set". No key has been entered for the provider currently selected next to the Assistant checkbox. Each provider has its own key field; switching provider shows that provider's key.

It reports that the application is unreachable. The Assistant reaches your groom through the same local control endpoint described in Using Ornatrix with Claude, which starts along with the application. This normally means the endpoint could not start - most often because its port is already in use by another running copy of Ornatrix App.

It seems to be taking a long time. The badge at the top of the window says what it is doing and for how long. A request that involves several renders legitimately takes a while. If it is not going anywhere, press Cancel.

Nothing happens when I type. Check the badge: if a request is already running, your message has been queued and will be sent when that request finishes. If the border is steady rather than pulsing, the Assistant is waiting for you to answer a question card in the bottom-right corner.

It stops responding partway through a request. Operations that change the scene have to wait for the application to draw a frame. If the application is busy with a very heavy groom, an operation can time out and the request will stop. Simplify the groom or reduce the hair count and try again.

For anything else, the Assistant writes a diagnostic log named assistant_sidecar.log next to the Ornatrix App executable, recording every operation it attempted and any error. Include it when reporting a problem.

 

Related 

• Using Ornatrix with Claude - drive Ornatrix from Claude Desktop or other AI tools instead of the built-in panel.
• Scripting with the Python Console - the same panel, in scripting mode.
• The Operator Stack - where the Assistant's work appears.

Missing Something? Let us know if this page needs more information about the topic.