Node reference (Python)

One constructor per node kind the Studio draws — all twenty-six. Every field name below is the field name the engine deserialises, and every default is that struct’s default.

Why constructors and not a free dict

A misspelled key in a dict is a config field the engine never sees and never complains about: it deserialises to the default and the node quietly does something else. Typing the arguments out moves that failure from a run with a strange number to a TypeError before anything is committed.

Required arguments are the fields the engine declares without a default. Everything else is omitted from the payload when left alone, so the server’s default is the one that applies — this package deliberately does not become a second place that decides them.

Every constructor also takes label= (defaults to the node’s id). Nodes that can fail take on_error= and on_fail=; nodes with sweepable fields take exposes=. See Defining a graph.

Flow

Constructor	Arguments	Notes
Input(id="input")	—	Where a run’s material arrives. An experiment seeds it from the dataset row’s input column.
Output(id="output")	—	The end of the flow.
Merge(id, ...)	strategy	concatenate, json_object, first, zip.
Template(id, template=...)	template	Renders {{…}} over the run’s context, no model.
Condition(id, ...)	mode	A tagged union: {"type": "regex", "pattern": …}, {"type": "json_path", "path": …, "expected": …}, {"type": "llm_judge", "prompt": …, "model": …}.
Loop(id, ...)	max_iterations, until_condition, body_node_ids, end_node_ids, flatten, sample	The body and the exit are named by node id.
Human(id, ...)	prompt_text	Pauses the run for a person.
Accumulator(id, ...)	key, mode	Gathers values across iterations under one key.
History(id, ...)	max_messages, format, roles, summarize, summary_model	Conversation history, optionally summarised. Takes exposes=.

Models and agents

Constructor	Arguments	Notes
Llm(id, ...)	model, prompt, system, temperature, max_tokens, reasoning_effort, output_schema	prompt is prompt_template and system is system_prompt — the two fields anyone reaches for first, spelled the short way here.
StructuredOutput(id, ...)	model, prompt, output_schema, max_retries	A JSON Schema the answer has to fit. The way to stop a good answer scoring zero for a formatting reason.
Agent(id, ...)	definition	A reference to an agent definition. Inert when executed — it exists to be convened. Pass it in members=, never in a chain.
SubAgent(id, ...)	definition, input_mapping, output_mapping, timeout_secs	One agent, run on data. This is the one that goes in a chain.
SubGraph(id, ...)	graph_id	Another graph, run as a step.
Panel(id, ...)	model, members, max_rounds, moderator_prompt	Round-table debate. model moderates; members is the roster. Takes exposes=.
Orchestrator(id, ...)	model, members, max_delegations, planning_prompt, adaptive	Hierarchical delegation over a roster. Takes exposes=.
AgentComm(id, ...)	target, message_template, timeout_secs, conversation_turns	One agent talking to another.

Agent vs SubAgent

Agent is a name on the canvas; SubAgent is a call. Putting an Agent in a chain is refused by build() precisely because the platform would accept it and run nothing.

Data

Constructor	Arguments	Notes
Tool(id, ...)	tool_name, params	A tool from the Library.
VectorDbQuery(id, ...)	query_template, collection, top_k, threshold	Retrieval. Takes exposes=.
FileRead(id, ...)	path_template, format, delimiter, has_headers, batch
FileWrite(id, ...)	path_template, format, delimiter, append, headers
DatasetRead(id, ...)	version_id, dataset_id, with_item_id	A version of a dataset, not the live table — a run exists so a number can be attributed to it, and reading the live table would give a number over rows nobody can name afterwards.
DatasetWrite(id, ...)	dataset_id, branch, message	Mints a dataset version from what arrives. The version’s verb is always from_run, and the server sets it.
DataFrame(id, ...)	sql_query, output_mode, preview_rows	SQL over what came in.
Flatten(id, ...)	mode, explode_field, depth

Keep row identity across a round trip

DatasetRead(with_item_id=True) — the default — carries each row’s identity out as a column. If it survives the SQL in the middle, DatasetWrite recognises it on the far side and the diff between the two dataset versions says this row was edited instead of one vanished and another appeared.

Analysis

Constructor	Arguments	Notes
Eval(id, ...)	metrics, prediction_var, reference_var, top_k, prediction_column, reference_column, nan_policy	metrics are the names the engine accepts — exact_match, f1, rouge_l and the rest. The live list is served at GET /api/eval-metrics.
Dashboard(id, ...)	tab_name, view_type, vega_spec, echarts_spec	A plot in the results tab.

The Eval trap

Eval resolves prediction_var against the context store and, when the variable does not resolve, falls back to whatever its predecessor said. So a typo in prediction_var does not raise — it scores the whole chain of reasoning against a single letter and reports a very confident 0.0. Check any number against a one-row preview run before you believe it.

Helpers

from chatty_lab import Retry, expose

Retry(times=0, *, continue_on_fail=False, timeout_secs=120) builds a node’s error policy. expose(field, *, label=None, param_type=None) builds one exposed parameter when the shorthand exposes=["model"] guesses the control wrong.

Where to go next

Node semantics What each node actually does at run time — the canvas-side reference.

Defining a graph How these constructors get wired together.

Panels & Orchestrators How a roster debates or delegates.

Experiments & Trials What exposed parameters are for.