Skip to content

nodestep

nodestep is a Python library for LLM agents and workflows built as graphs: nodes are plain functions, async or sync, that read a typed state and return an update. You declare how they connect, and nodestep runs them step by step, can store every step and can pause for a person.

In development

Alpha (0.1.0a1). Anything may change between releases without a deprecation period, so pin a tag or a commit, as the Install page shows. nodestep is not on PyPI yet.

Install

uv add "nodestep @ git+https://github.com/nodestep-ai/nodestep"

Install covers the extras and how to pin a version.

A first graph

from nodestep import END, START, BaseState, Graph, node


class Greeting(BaseState):
    name: str = ""
    text: str = ""


@node
def greet(state: Greeting) -> dict:
    return {"text": f"Hello, {state.name}!"}


graph = Graph(Greeting).flow(START >> greet, greet >> END)

print(graph.invoke({"name": "Ada"}).state.text)

Hello, Ada!

The state holds the data, nodes do the work, and the flow says what runs next. The Quickstart builds a larger graph step by step and needs no API key.

Core concepts

  • Graphs and flow: how nodes connect, how a run is routed, and how to draw the graph.
  • State: the typed data a graph works on, and the reducers that merge updates into it.
  • Nodes and context: what a node receives and what it can return.
  • Running: invoke() and stream(), supersteps, limits and timeouts.

Capabilities

  • Streaming: per-task updates, the full state, custom events, model tokens and debug events while the graph runs.
  • Persistence and time travel: threads, history and forks, in memory or on disk.
  • Interrupts: a node pauses for a person and continues with the answer.
  • Agents and tools: chat models through the Chat protocol, built-in chat integrations, ScriptedChat for tests, tools from typed functions and a ready-made agent.
  • Middleware: hooks around graphs, nodes, tools and model calls, and built-in middleware for tool approvals, tool-call limits, summarization, to-do lists, skills and memory.
  • Sub-agents: other graphs that a node runs, inside its step or in the background.
  • Workspace and memory: files for tools, on disk or in memory, and long-term memory for a model.

How-to

License

MIT. The source is on GitHub.