RenderedInput and build_rendered_input are not part of the top-level neograph namespace; import them from neograph.renderers (from neograph.renderers import RenderedInput, build_rendered_input).
Every public symbol, generated from the library itself (signature + fields) so this
table never drifts from the code. Headings are stable anchors — link to any symbol
as /reference/api/#<name> (colliding names are disambiguated, e.g. #node-function
vs #node-model). Errors live in the Error Hierarchy below.
lint() reports these issue kinds. Severity and meaning are manifest-owned (generated from LINT_KIND_META in lint.py), so this table never drifts from what lint() actually emits.
Kind
Severity
Meaning
act_mode_all_idempotent_tools
WARN
mode='act' (mutations) but all tools are idempotent=True (read-only) — probably a misclassification; use mode='agent' unless a tool is a genuinely idempotent mutation.
ask_human_in_mutating_node
WARN
An act-mode (mutating) tool calls ask_human(); a non-idempotent side effect before the mid-loop pause can double-fire on resume. Make any pre-pause mutation idempotent, or move it after the pause.
config_key_unmatched
ERROR
A key in the config= passed to lint() that matches no DI binding in the construct, so nothing reads it. A key accepted because it is present rather than because a binding names it is how a padded config silences a real unsatisfiable binding: the linter then agrees with a description of the world it was handed, not with the graph.
from_config
varies
Annotated[T, FromConfig] — resolved from config['configurable'], passed directly in config=.
from_config_model
varies
Bundled BaseModel via FromConfig — each model field must exist in config.
from_input
varies
Annotated[T, FromInput] — resolved from config['configurable'], originally from run(input={...}).
from_input_model
varies
Bundled BaseModel via FromInput — each model field must exist in config.
from_input_unsatisfiable
ERROR
A FromInput/FromConfig parameter whose value is the Each-fanned item or the Loop carry. No caller can supply it, so the run fails in the DI preflight — and padding a config to silence it makes every branch compute from the padded value. Bind it as a port parameter instead.
llm_kwargs_missing
WARN
LLM-mode nodes require llm_factory and prompt_compiler at compile() time. Pass these kwargs to compile() (or configure via configure_llm(), legacy).
loop_condition_none_unsafe
WARN/ERROR
Loop when callable raises when called with None. ERROR for registered string conditions (always crash), WARN for user-supplied callables (may handle None via other means).
loop_condition_unregistered
ERROR
Loop when is a string that is not registered in the condition registry.
output_field_unconsumed
WARN
A field of a node’s typed output that nothing reads: no downstream node takes the model, no template reads it by name, and it is not the graph’s terminal output. It costs tokens on every call and cannot affect the answer.
resource_hydration_kind_unmatched
ERROR
A node hydrates a manifest kind via FromResource(ref=...) but the construct has no upstream agent/act node that can emit a resource_link, so the manifest is guaranteed empty at runtime.
template_input_unreferenced
WARN
A bound input, DI parameter, or context field that the node’s own template never references. The value reaches the node and the model never sees it. Demand is read from the template text, so a prompt_compiler that composes the message may consume the name without naming it.
template_placeholder_known_vars_only
WARN
Placeholder only resolvable via known_template_vars, not from actual @node parameter names. Advisory: verify the consumer bridge supplies it at runtime.
template_placeholder_unresolvable
ERROR
Prompt placeholder not found in predicted input keys or known extras.
template_var_requires_async_driver
WARN
A template var is a FromResource DI param whose fetch is awaited, so it resolves only under the async arun() driver (sync run() fails loud). Drive the graph with arun().
tool_requires_async_driver
WARN
An agent/act node is bound to an async-only tool (e.g. an MCP tool) that cannot run under the sync run() driver. Drive the graph with arun().
node |Loop(when=lambdad: d isNoneor d.score <0.8,max_iterations=5)
construct |Loop(when=lambdad: d isNoneor d.score <0.8,max_iterations=10)
The merge_prompt path on Oracle receives upstream context as a dict {"variants": [...], upstream_key: val, ...} instead of a bare variant list; templates use ${variants} for the variant list and ${upstream.field} for upstream data. Each(over, key) fans out over a dotted-path collection, keying results by getattr(item, key). Operator(when) is a human-in-the-loop interrupt whose when is a registered condition name. Loop(when, ...) is a cycle modifier: on a Node it self-loops (output feeds back as input); on a Construct the sub-construct re-runs with its output as the next input. when receives the latest output (which may be None on the first iteration, so the callable must be None-safe, e.g. lambda d: d is None or d.score < 0.8). A self-loop node’s output field is itself an append-list of every iteration, so result[node] is the full iteration history (last element is the final value).
When output != input on a Construct Loop, the sub-construct re-reads original inputs from parent state on each iteration instead of feeding output back — this enables produce+validate patterns. The | syntax returns a new Node/Construct with the modifier appended, so you can chain: node | Oracle(...) | Operator(...).
compile() returns a CompiledNeograph facade over the underlying LangGraph graph. Beyond run()/arun()/stream()/astream(), the facade delegates a closed set of methods for inspection, streaming, and state editing — sync: invoke, stream, get_state, get_state_history, get_graph, update_state; async: ainvoke, astream, astream_events, aget_state, aget_state_history, aupdate_state. The raw LangGraph graph is available as .graph for anything outside this set.
The programmatic / runtime-constructed surface references scripted functions, conditions, and tool factories by string name. Supply the implementations as dicts to compile() — there are no global registration functions:
These are only needed for the programmatic API. @node, @tool, and @merge_fn handle wiring automatically. See Pipeline Spec Format for the YAML/JSON spec surface loaded by load_spec.
Parentage follows one rule, by lifecycle phase: a failure raised while the graph is executing subclasses ExecutionError; an assembly/validation failure is a ConstructError; a compile() failure is a CompileError; a bad or missing configuration (including a resume-time precondition mismatch) is a ConfigurationError. This means a single except ExecutionError around run() catches every runtime failure — including resource-expiry and non-idempotent-replay.
│ └── CheckpointSchemaError — checkpoint state schema mismatch on resume
└── ExecutionError — runtime failures during a run
├── PromptVarMissing — strict prompt placeholder had no value
├── PromptInputError — a prompt_compiler read a field off already-rendered text
├── StateMissingError — required state read missed
├── NodeOutputError — a node ran and produced None vs its declared output
├── NonIdempotentReplayError — refused to replay a non-idempotent producing tool
└── ResourceExpiredError — a manifest ResourceRef could not be hydrated
CheckpointSchemaError — raised when resuming from a checkpoint whose state schema fingerprint differs from the current graph. Has an invalidated_nodes: set[str] attribute listing which state fields changed. Only raised when auto_resume=False; when auto_resume=True (the default), run() automatically rewinds instead. It subclasses ConfigurationError, not ExecutionError: it fires at resume, before any node re-executes, as a precondition check on the persisted checkpoint against the current graph — a configuration mismatch you resolve with a new thread_id or a schema migration, not a retry of node logic.
All errors are importable: from neograph import ConstructError, CompileError, ConfigurationError, CheckpointSchemaError, ExecutionError, PromptVarMissing, PromptInputError, NonIdempotentReplayError, ResourceExpiredError.