langgraph-codegen 3.0.0

Generate runnable LangGraph code from a concise graph notation

langgraph-codegen

Generate runnable LangGraph code from a concise graph notation.

Write a graph like this (plan_and_execute.lgraph):

# Plan and Execute Agent
START:PlanExecute -> plan_step -> execute_step -> replan_step
replan_step -> is_done ? END : execute_step

and lgcodegen plan_and_execute turns it into a runnable LangGraph program with a state class, node stubs, conditional edge functions, and the compiled graph — all with mock implementations you replace incrementally with real code.

The full notation is specified in graph_notation.md. The short version:

Pattern	Meaning
START:StateClass -> node	Entry point (or bare START to derive the class name from the file name)
a -> b -> c	Chained edges
a -> b, c -> d	Fan-out then fan-in
a -> cond ? b : c	Boolean conditional routing
a -> switch(b, c, END)	Switch routing (function returns the next node name)
a -> field | worker -> b	Parallel workers over a state list field (Send API)
STATE: ClassName + field: type	Explicit state field declarations

Here are the five graphs from the LangChain "Building Effective Agents" video in this notation:

# Agent
START:MessagesState -> llm_call
llm_call -> should_continue ? environment : END
environment -> llm_call

# Evaluator Optimizer
START:State -> llm_call_generator -> llm_call_evaluator
llm_call_evaluator -> route_joke ? END : llm_call_generator

# Orchestrator Worker
START:State -> orchestrator
orchestrator -> sections | llm_call -> synthesizer -> END

# Parallelization
START:State -> call_llm_1, call_llm_2, call_llm_3 -> aggregator -> END

# Prompt Chaining
START:State -> generate_joke
generate_joke -> check_punchline ? improve_joke : END
improve_joke -> polish_joke -> END

Install

pip install langgraph-codegen

Or from source:

git clone https://github.com/jojohannsen/langgraph-codegen
cd langgraph-codegen
pip install -e ".[dev]"

Quick Start

# List built-in examples (shown in --help epilog)
lgcodegen --help

# Show a built-in example's notation
lgcodegen plan_and_execute --show

# Generate everything into a plan_and_execute/ folder
lgcodegen plan_and_execute

# Run it (mock nodes print their names and track state)
cd plan_and_execute && python main.py

Output of the run — every node is a working mock, conditions route randomly:

NODE: plan_step
NODE: execute_step
NODE: replan_step
CONDITION: is_done. Result: False
NODE: execute_step
NODE: replan_step
CONDITION: is_done. Result: True
{'nodes_visited': ['plan_step', 'execute_step', 'replan_step', 'execute_step', 'replan_step'], 'counter': 5}

CLI

lgcodegen my_workflow.lgraph            # generate all files into my_workflow/
lgcodegen my_workflow.lgraph --state    # state class only
lgcodegen my_workflow.lgraph --nodes    # node functions only
lgcodegen my_workflow.lgraph --graph    # graph builder only
lgcodegen my_workflow.lgraph --stdout   # print instead of writing files
lgcodegen my_workflow.lgraph --show     # print the spec and exit
lgcodegen my_workflow.lgraph --verify   # check generated files execute
lgcodegen my_workflow.lgraph -o outdir  # custom output directory

Generated files for input my_workflow.lgraph:

File	Contents
my_workflow_state.py	State class (TypedDict) with reducers and initialize_state()
my_workflow_nodes.py	Node function stubs (working mocks)
my_workflow_graph.py	Conditions, workers, and the compiled StateGraph
main.py	Entry point: draws the graph PNG and invokes it
my_workflow.lgraphx	Expanded intermediate form of the notation

Replace any mock by editing the generated node functions — the graph wiring stays the same.

Library API

from langgraph_codegen import gen_graph

graph_spec = """
START:StateClass -> first_node
first_node -> should_go_on ? second_node : END
second_node -> END
"""

print(gen_graph("my_graph", graph_spec))

Other generators: gen_state, gen_nodes, gen_conditions, gen_worker_functions, plus parse_spec for the parsed representation.

Development

pip install -e ".[dev]"
pytest              # unit tests
./testit            # generate + execute all 14 examples, writes run.md
./clean             # remove generated example folders

Requires Python 3.10+ and langgraph >= 1.0.