pydantic-graph

Graph and state machine library

pydantic-graph Permissive license MIT Active ★ 19,271 v2.29.0 released 2026-08-13

Install

pydantic-graph on PyPI

pip

pip install pydantic-graph

uv

uv add pydantic-graph

poetry

poetry add pydantic-graph

Package facts

License	MIT (permissive)
Python support	supports the current Python release (>=3.10)
Install friction	low — pure-Python wheel
Runtime dependencies	5 — anyio, httpx, logfire-api, pydantic, typing-inspection
Maintenance	actively maintained — 0 days since the last release
Last repo commit	2026-08-13
First released	2025-01-10
Popularity	one of the top 1,000 most-downloaded packages on PyPI (30-day window, as of 2026-08-13)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-13)

Evidence: pydantic_graph-2.29.0-py3-none-any.whl

Development Status :: 5 - Production/StableEnvironment :: ConsoleEnvironment :: MacOS XIntended Audience :: DevelopersIntended Audience :: Information TechnologyIntended Audience :: System AdministratorsLicense :: OSI Approved :: MIT LicenseOperating System :: POSIX :: LinuxOperating System :: UnixProgramming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Topic :: InternetTopic :: Software Development :: Libraries :: Python Modules

About pydantic-graph

from the package's own PyPI description — quoted content, verbatim

Pydantic Graph

CI (image) Coverage (image) PyPI (image) python versions (image) license (image)

Graph and finite state machine library.

This library is developed as part of Pydantic AI, however it has no dependency on pydantic-ai or related packages and can be considered as a pure graph-based state machine library. You may find it useful whether or not you're using Pydantic AI or even building with GenAI.

As with Pydantic AI, this library prioritizes type safety and use of common Python syntax over esoteric, domain-specific...

Read as markdown · JSON record · Source repository · Homepage · Docs

AI interpretation — verify before relying

AI-generated interpretation of the package facts above; every digit, version, license, or vulnerability id it cites is grounded in the facts already shown on this page

A type-safe graph and finite state machine library that lets you define stateful workflows using standard Python syntax, with edges inferred from return type hints.

Low friction: pure Python wheel with five well-established runtime dependencies (pydantic, httpx, anyio, logfire-api, typing-inspection). Active maintenance with a recent release and high repository engagement (19271 stars).

MIT license permits commercial and private use with minimal restrictions—only requiring license and copyright notice retention in distributions.

Usage

pip install pydantic-graph

from pydantic_graph import BaseNode, End, GraphBuilder, GraphRunContext

# Define nodes as dataclasses inheriting BaseNode
# Build graph with GraphBuilder, add nodes and edges
# Run with: result = await graph.run(inputs=value)

Requires Python 3.10 or later; async/await syntax required for node execution.

Verdict: Production-ready, actively maintained library from the Pydantic team with no known vulnerabilities. MIT licensing and low install friction make it accessible. Best suited for developers building type-safe, async-first state machines or workflow graphs where return-type-driven edge definition aligns with their design.

Needs verification

Whether the library's async-only execution model is a hard requirement or if synchronous alternatives exist.
Performance characteristics and scalability limits for large graphs or high-throughput scenarios.
Community adoption rate and real-world usage patterns beyond the Pydantic AI ecosystem.

graph state machine libraryfinite state machine pythontype-safe workflow graphsasync graph executionpython state machine frameworkdirected graph builderworkflow orchestration library