The Substrate Python SDK is the recommended way to interact with the Substrate API from any Python application.

If you're just getting started, head to guides.substrate.run.

For a detailed API reference covering the nodes available on Substrate, see substrate.run/nodes.

For an interactive reference, check out explore.substrate.run. You can call Substrate.visualize(...nodes...) to generate an interactive visualization of any graph.

# install from PyPI
pip install substrate

from substrate import Substrate, GenerateText, sb

Initialize the Substrate client.

substrate = Substrate(api_key=SUBSTRATE_API_KEY)

Generate a story using the GenerateText node.

story = GenerateText({"prompt": "tell me a story"})

Summarize the output of the story node using another GenerateText node. Because story has not yet been run, we use sb.concat to work with its future output.

summary = GenerateText({"prompt": sb.concat("summarize this story in one sentence: ", story.future.text)})

Run the graph chaining story → summary. This is a simple example, but you can easily build arbitrarily complex branching workflows.

response = substrate.run(story, summary)

(To run the graph asynchronously, simply use async_run and await.)

response = await substrate.async_run(story, summary)

Get the output of the summary node by passing it to response.get.

summary_out = response.get(summary)
print(summary_out.text)
// Princess Lily, a kind-hearted young princess, discovers a book of spells and uses it to grant her family and kingdom happiness.

To run the above example as a notebook, navigate to the examples/notebooks directory and run:

make ensure                         # install dependencies
poetry run marimo edit basic.py     # run the notebook