Nodes.

Open a project in Kaitoi Studio and what is on the canvas is nodes. Almost everything you do in the app is done by adding one, wiring it to another, or changing what one of them is set to, so being able to read a node at a glance is most of being able to read the work.

This page is about one node: what its parts are, how its pins decide what can connect to what, and when it runs. The wider argument about why a graph is worth having at all is on Graphs and nodes.

#A node is not only a model call

The easiest thing to assume is that a node is one call to one AI model, because that is the most visible case. It is narrower than the truth. A node can be a model call, a piece of Python you wrote, a call out to an external service, a file operation, a piece of domain tooling, or a small application with its own interface embedded in the node.

That matters here for a practical reason rather than a philosophical one: all of them are drawn the same way. The picture below is not the picture of a model node, it is the picture of a node, and the same seven parts are in the same seven places whether the node is calling a video model or adding two numbers.

#The parts of a node

A node is a small panel with seven parts. Along the top is a title bar carrying the node's name, and at its right end the run controls: a switch for automatic re-running and a button that runs the node now. Under that is the preview, which shows the node's own result at whatever size you left it. The body holds the pins. Each input pin on the left is one typed way in, coloured by its type, and an input that has nothing wired into it shows a parameter widget next to it instead, so you can type a value by hand. Output pins sit on the right, labelled and coloured the same way. Along the bottom is a status strip that reports whether the node calls a cloud service, what its last run cost in credits, how long it took, and whether it runs on your own machine.

The title is editable. What a node is called defaults to its type, but you can rename an instance, and on a graph with four resize nodes in it you will want to.

#The toolbar

Hover a node, or select it, and a small toolbar appears above it. Most of what is on it acts on the node:

• Open preview (Space) opens the result full size.
• Lock freezes the node on its current output. A locked node is skipped when the graph runs and hands its stored result downstream instead, which is how you keep an expensive generation still while you iterate on everything after it.
• History (/) lists this node's previous runs, so you can go back to an earlier result.
• Edit script opens the node's Python. On a built-in node this clones it first, so you are editing your copy rather than the original.
• Duplicate (⌘D) and Delete (⌫).
• Create subgraph folds the selection into one node. On a node that is already a subgraph, the same button becomes Explode, which unpacks it.
• Save outputs writes the node's results out to files.

One of them changes how the node looks rather than what it does.

#Hiding the pins

Toggle pins (M) collapses a node down to its result. This is how a graph full of working nodes becomes something you can show someone: the title bar, the status strip, the labels, the widgets and the rows of pins all go, and the preview becomes the whole card. A collapsed node is its output and nothing else.

The title bar and the status strip are one decision rather than two: they go together, and they come back together. There is a canvas setting that brings the title bar back while you hover a collapsed node, and it is off unless you turn it on.

Nothing is removed. The pins move to the node's border, where a connected one shows as a bare dot on the edge and an unconnected one appears only when you bring the pointer to that side of the node. The wires still land where they always did.

With its pins shown, an Upscale node lists three inputs, each with a label, and each unconnected one with a widget: a connected image, a strength value of 0.65, and a seed. It carries a title bar above and a status strip below. Hide the pins and both of those go, along with the labels and the widgets, and the preview fills the card. The connected image input becomes a bare dot on the node's left border. The unconnected seed input is not drawn at all until you hover that edge. strength is the exception: its label was clicked, which exposes it, so it keeps its label and its widget in the body of the collapsed node. An exposed pin is drawn with a ring around it in both states.

#Exposing a pin

Click a pin's label and the pin becomes exposed. It gains a ring, and nothing else appears to happen. What the ring means depends entirely on what you do with the node next, because one flag answers three different questions:

• When you fold the node into a subgraph, the exposed pins are the ones that become the subgraph node's own inputs and outputs. Everything else stays inside, wired up and invisible. This is how you decide what a reusable component's interface is: you do not declare it, you point at it.
• When you hide the node's pins, the exposed ones stay in the body with their labels and their widgets. That is the figure above. A collapsed node with one exposed number is a panel with one knob on it.
• When you publish a template as an API endpoint, the exposed pins are pre-selected as the endpoint's parameters and return values. You can still change the selection there, but the work of deciding what the outside world should see has usually already been done on the canvas.

Those three are worth reading as one idea rather than three features. Exposing a pin is how you say this is the part that matters, and Kaitoi then uses that answer wherever the question comes up.

#Pins carry typed values

Every pin has a type, and the colour of the pin is that type. The colours are the same everywhere in Kaitoi, which is what lets you follow a graph without opening anything: a wire's colour tells you what is travelling along it.

Types match exactly. An image output goes into an image input and into nothing else. There is no quiet conversion anywhere in the system, so an int does not become a float on the way, and a string does not become text because the names are close. When the types do not agree, the wire simply does not land.

Try to wire an image output into a prompt input that takes a string and nothing happens: Kaitoi refuses the connection rather than converting the value. The same image output drops cleanly into a reference input that takes an image, or into a mask input that also takes an image. A mismatch is not an error to be fixed later, it is a connection that cannot be made, and the way through it is a conversion node in between that takes one type and returns the other.

This is deliberate, and it is the reason a graph that ran yesterday runs the same way today. A system that coerces types is a system where the meaning of a wire depends on what happened to be at the other end of it.

Three more rules follow from the same idea:

• An output can feed as many inputs as you like. Generate an image once and send it to an upscaler, a preview and a file writer at the same time.
• An ordinary input takes one connection. Wire something new into an input that is already connected and the new wire replaces the old one.
• Some inputs take many values. An input that accepts an array is drawn as a tall rounded bar rather than a circle, and it accumulates connections rather than replacing them, up to whatever limit the node declares.

A node cannot connect to itself.

#Parameters, and what a connection replaces

An input pin and a parameter are the same thing seen from two sides. When nothing is wired into an input, the node shows a widget for it and the value is whatever you type, choose or drag there. Wire a connection into that same pin and the widget disappears, because the value now comes from upstream.

That is worth knowing before you go looking for a setting that has vanished. It has not vanished; something is connected to it. Disconnect the wire and the widget comes back with the value it had.

#When a node runs

Running a graph does not run its nodes in the order you added them or in the order they sit on the canvas. Kaitoi takes every node whose inputs are all satisfied, runs that whole set at the same time, removes it, and looks again. A graph with no dependencies between its branches therefore runs those branches together rather than one after the other.

The second half of the story is that a node which has not changed since its last run does not run again. Its stored output is reused and the node is skipped. Running a large graph twice in a row can do almost nothing, which is what makes a large graph workable.

Given a graph where Load Image and Prompt feed a chain through Describe and Generate into Save, the run goes in four layers. First Load Image and Prompt, together, because neither depends on anything; Load Image has not changed since its last run, so its cached output is reused instead of being recomputed. Then Describe, once the image it needs exists. Then Generate, once both of its inputs have finished. Then Save. A node never starts before everything it reads from has finished, and nodes in the same layer start together.

There are three ways a node comes to run:

• You run it. The button in its title bar runs that node and anything upstream of it that needs redoing first.
• You run the graph. Everything that needs redoing, in the order above.
• It runs itself. The switch next to the run button puts a node in automatic mode, where it re-runs whenever something it depends on changes. Useful on a cheap node you are iterating on, and worth leaving off on an expensive one.

#Reading state at a glance

The run button is also the node's status light. Amber means there is work to do: something upstream changed, or you edited a parameter, and the output on screen is out of date. Green means the output is current. While a node is running the button becomes a progress ring, and a node waiting its turn shows a clock.

The status strip along the bottom is the other half. A cloud means the node calls a service over the network. A coin, with a number next to it, is what the last run actually cost. A timer is how long that run took. A disk means the node runs on your own machine through the local runtime rather than in the cloud.

Between the two you can answer the question that matters most in front of a graph you did not build: what is out of date, what is expensive, and what is about to happen if you press run.

#What a node costs

A node that calls a managed model spends credits from your account balance, and what it spends depends on the model and on what you asked it for. The status strip reports the real figure after the fact rather than an estimate before it, because for most generative work the cost is not known until the work is done.

A node that runs locally, through the Kaitoi CLI's runtime, costs nothing in credits. It costs your own machine's time instead. Which one a node is doing is the difference between the cloud icon and the disk icon in its status strip.