pydantic-graph 0.0.1__tar.gz

pydantic_graph-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+site
+.python-version
+.venv
+dist
+__pycache__
+*.env
+/scratch/
+/.coverage
+env*/
+/TODO.md
+/postgres-data/
+.DS_Store
+examples/pydantic_ai_examples/.chat_app_messages.sqlite
+.cache/
+.vscode/

pydantic_graph-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: pydantic-graph
+Version: 0.0.1
+Summary: Graph and state machine library
+Author-email: Samuel Colvin <samuel@pydantic.dev>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: logfire-api>=1.2.0
+Requires-Dist: pydantic>=2.10
+Description-Content-Type: text/markdown
+
+# Pydantic Graph
+
+[![CI](https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml?query=branch%3Amain)
+[![Coverage](https://coverage-badge.samuelcolvin.workers.dev/pydantic/pydantic-ai.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/pydantic/pydantic-ai)
+[![PyPI](https://img.shields.io/pypi/v/pydantic-graph.svg)](https://pypi.python.org/pypi/pydantic-graph)
+[![versions](https://img.shields.io/pypi/pyversions/pydantic-graph.svg)](https://github.com/pydantic/pydantic-ai)
+[![license](https://img.shields.io/github/license/pydantic/pydantic-ai.svg?v)](https://github.com/pydantic/pydantic-ai/blob/main/LICENSE)
+
+Graph and finite state machine library.
+
+This library is developed as part of the [PydanticAI](https://ai.pydantic.dev), however it has no dependency
+on `pydantic-ai` or related packages and does and can be considered as a pure graph library.
+
+As with PydanticAI, this library prioritizes type safety and use of common Python syntax over esoteric, domain-specific use of Python syntax.
+
+`pydantic-graph` allows you to define graphs using simple Python syntax. In particular, edges are defined using the return type hint of nodes.

pydantic_graph-0.0.1/README.md

@@ -0,0 +1,16 @@
+# Pydantic Graph
+
+[![CI](https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml?query=branch%3Amain)
+[![Coverage](https://coverage-badge.samuelcolvin.workers.dev/pydantic/pydantic-ai.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/pydantic/pydantic-ai)
+[![PyPI](https://img.shields.io/pypi/v/pydantic-graph.svg)](https://pypi.python.org/pypi/pydantic-graph)
+[![versions](https://img.shields.io/pypi/pyversions/pydantic-graph.svg)](https://github.com/pydantic/pydantic-ai)
+[![license](https://img.shields.io/github/license/pydantic/pydantic-ai.svg?v)](https://github.com/pydantic/pydantic-ai/blob/main/LICENSE)
+
+Graph and finite state machine library.
+
+This library is developed as part of the [PydanticAI](https://ai.pydantic.dev), however it has no dependency
+on `pydantic-ai` or related packages and does and can be considered as a pure graph library.
+
+As with PydanticAI, this library prioritizes type safety and use of common Python syntax over esoteric, domain-specific use of Python syntax.
+
+`pydantic-graph` allows you to define graphs using simple Python syntax. In particular, edges are defined using the return type hint of nodes.

pydantic_graph-0.0.1/pydantic_graph/__init__.py

@@ -0,0 +1,14 @@
+from .graph import Graph
+from .nodes import BaseNode, End, GraphContext
+from .state import AbstractState, EndEvent, HistoryStep, NodeEvent
+
+__all__ = (
+    'Graph',
+    'BaseNode',
+    'End',
+    'GraphContext',
+    'AbstractState',
+    'EndEvent',
+    'HistoryStep',
+    'NodeEvent',
+)

pydantic_graph-0.0.1/pydantic_graph/_utils.py

@@ -0,0 +1,70 @@
+from __future__ import annotations as _annotations
+
+import sys
+import types
+from datetime import datetime, timezone
+from typing import Any, Union, get_args, get_origin
+
+from typing_extensions import TypeAliasType
+
+
+def get_union_args(tp: Any) -> tuple[Any, ...]:
+    """Extract the arguments of a Union type if `response_type` is a union, otherwise return the original type."""
+    # similar to `pydantic_ai_slim/pydantic_ai/_result.py:get_union_args`
+    if isinstance(tp, TypeAliasType):
+        tp = tp.__value__
+
+    origin = get_origin(tp)
+    if origin_is_union(origin):
+        return get_args(tp)
+    else:
+        return (tp,)
+
+
+# same as `pydantic_ai_slim/pydantic_ai/_result.py:origin_is_union`
+if sys.version_info < (3, 10):
+
+    def origin_is_union(tp: type[Any] | None) -> bool:
+        return tp is Union
+
+else:
+
+    def origin_is_union(tp: type[Any] | None) -> bool:
+        return tp is Union or tp is types.UnionType
+
+
+def comma_and(items: list[str]) -> str:
+    """Join with a comma and 'and' for the last item."""
+    if len(items) == 1:
+        return items[0]
+    else:
+        # oxford comma ¯\_(ツ)_/¯
+        return ', '.join(items[:-1]) + ', and ' + items[-1]
+
+
+_NoneType = type(None)
+
+
+def type_arg_name(arg: Any) -> str:
+    if arg is _NoneType:
+        return 'None'
+    else:
+        return arg.__name__
+
+
+def get_parent_namespace(frame: types.FrameType | None) -> dict[str, Any] | None:
+    """Attempt to get the namespace where the graph was defined.
+
+    If the graph is defined with generics `Graph[a, b]` then another frame is inserted, and we have to skip that
+    to get the correct namespace.
+    """
+    if frame is not None:
+        if back := frame.f_back:
+            if back.f_code.co_filename.endswith('/typing.py'):
+                return get_parent_namespace(back)
+            else:
+                return back.f_locals
+
+
+def now_utc() -> datetime:
+    return datetime.now(tz=timezone.utc)

pydantic_graph-0.0.1/pydantic_graph/graph.py

@@ -0,0 +1,135 @@
+from __future__ import annotations as _annotations
+
+import inspect
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from time import perf_counter
+from typing import TYPE_CHECKING, Any, Generic
+
+import logfire_api
+from typing_extensions import Never, ParamSpec, TypeVar, Unpack, assert_never
+
+from . import _utils, mermaid
+from ._utils import get_parent_namespace
+from .nodes import BaseNode, End, GraphContext, NodeDef
+from .state import EndEvent, HistoryStep, NodeEvent, StateT
+
+__all__ = ('Graph',)
+
+_logfire = logfire_api.Logfire(otel_scope='pydantic-graph')
+
+RunSignatureT = ParamSpec('RunSignatureT')
+RunEndT = TypeVar('RunEndT', default=None)
+NodeRunEndT = TypeVar('NodeRunEndT', covariant=True, default=Never)
+
+
+@dataclass(init=False)
+class Graph(Generic[StateT, RunEndT]):
+    """Definition of a graph."""
+
+    name: str | None
+    nodes: tuple[type[BaseNode[StateT, RunEndT]], ...]
+    node_defs: dict[str, NodeDef[StateT, RunEndT]]
+
+    def __init__(
+        self,
+        *,
+        nodes: Sequence[type[BaseNode[StateT, RunEndT]]],
+        state_type: type[StateT] | None = None,
+        name: str | None = None,
+    ):
+        self.name = name
+
+        _nodes_by_id: dict[str, type[BaseNode[StateT, RunEndT]]] = {}
+        for node in nodes:
+            node_id = node.get_id()
+            if (existing_node := _nodes_by_id.get(node_id)) and existing_node is not node:
+                raise ValueError(f'Node ID "{node_id}" is not unique — found in {existing_node} and {node}')
+            else:
+                _nodes_by_id[node_id] = node
+        self.nodes = tuple(_nodes_by_id.values())
+
+        parent_namespace = get_parent_namespace(inspect.currentframe())
+        self.node_defs: dict[str, NodeDef[StateT, RunEndT]] = {}
+        for node in self.nodes:
+            self.node_defs[node.get_id()] = node.get_node_def(parent_namespace)
+
+        self._validate_edges()
+
+    def _validate_edges(self):
+        known_node_ids = set(self.node_defs.keys())
+        bad_edges: dict[str, list[str]] = {}
+
+        for node_id, node_def in self.node_defs.items():
+            node_bad_edges = node_def.next_node_ids - known_node_ids
+            for bad_edge in node_bad_edges:
+                bad_edges.setdefault(bad_edge, []).append(f'"{node_id}"')
+
+        if bad_edges:
+            bad_edges_list = [f'"{k}" is referenced by {_utils.comma_and(v)}' for k, v in bad_edges.items()]
+            if len(bad_edges_list) == 1:
+                raise ValueError(f'{bad_edges_list[0]} but not included in the graph.')
+            else:
+                b = '\n'.join(f' {be}' for be in bad_edges_list)
+                raise ValueError(f'Nodes are referenced in the graph but not included in the graph:\n{b}')
+
+    async def next(
+        self, state: StateT, node: BaseNode[StateT, RunEndT], history: list[HistoryStep[StateT, RunEndT]]
+    ) -> BaseNode[StateT, Any] | End[RunEndT]:
+        node_id = node.get_id()
+        if node_id not in self.node_defs:
+            raise TypeError(f'Node "{node}" is not in the graph.')
+
+        history_step: NodeEvent[StateT, RunEndT] | None = NodeEvent(state, node)
+        history.append(history_step)
+
+        ctx = GraphContext(state)
+        with _logfire.span('run node {node_id}', node_id=node_id, node=node):
+            start = perf_counter()
+            next_node = await node.run(ctx)
+            history_step.duration = perf_counter() - start
+        return next_node
+
+    async def run(
+        self,
+        state: StateT,
+        node: BaseNode[StateT, RunEndT],
+    ) -> tuple[End[RunEndT], list[HistoryStep[StateT, RunEndT]]]:
+        history: list[HistoryStep[StateT, RunEndT]] = []
+
+        with _logfire.span(
+            '{graph_name} run {start=}',
+            graph_name=self.name or 'graph',
+            start=node,
+        ) as run_span:
+            while True:
+                next_node = await self.next(state, node, history=history)
+                if isinstance(next_node, End):
+                    history.append(EndEvent(state, next_node))
+                    run_span.set_attribute('history', history)
+                    return next_node, history
+                elif isinstance(next_node, BaseNode):
+                    node = next_node
+                else:
+                    if TYPE_CHECKING:
+                        assert_never(next_node)
+                    else:
+                        raise TypeError(f'Invalid node type: {type(next_node)}. Expected `BaseNode` or `End`.')
+
+    def mermaid_code(
+        self,
+        *,
+        start_node: Sequence[mermaid.NodeIdent] | mermaid.NodeIdent | None = None,
+        highlighted_nodes: Sequence[mermaid.NodeIdent] | mermaid.NodeIdent | None = None,
+        highlight_css: str = mermaid.DEFAULT_HIGHLIGHT_CSS,
+    ) -> str:
+        return mermaid.generate_code(
+            self, start_node=start_node, highlighted_nodes=highlighted_nodes, highlight_css=highlight_css
+        )
+
+    def mermaid_image(self, **kwargs: Unpack[mermaid.MermaidConfig]) -> bytes:
+        return mermaid.request_image(self, **kwargs)
+
+    def mermaid_save(self, path: Path | str, /, **kwargs: Unpack[mermaid.MermaidConfig]) -> None:
+        mermaid.save_image(path, self, **kwargs)

pydantic_graph-0.0.1/pydantic_graph/mermaid.py

@@ -0,0 +1,210 @@
+from __future__ import annotations as _annotations
+
+import base64
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any, Literal
+
+from annotated_types import Ge, Le
+from typing_extensions import TypeAlias, TypedDict, Unpack
+
+from .nodes import BaseNode
+
+if TYPE_CHECKING:
+    from .graph import Graph
+
+
+NodeIdent: TypeAlias = 'type[BaseNode[Any, Any]] | BaseNode[Any, Any] | str'
+DEFAULT_HIGHLIGHT_CSS = 'fill:#fdff32'
+
+
+def generate_code(
+    graph: Graph[Any, Any],
+    /,
+    *,
+    start_node: Sequence[NodeIdent] | NodeIdent | None = None,
+    highlighted_nodes: Sequence[NodeIdent] | NodeIdent | None = None,
+    highlight_css: str = DEFAULT_HIGHLIGHT_CSS,
+) -> str:
+    """Generate Mermaid code for a graph.
+
+    Args:
+        graph: The graph to generate the image for.
+        start_node: Identifiers of nodes that start the graph.
+        highlighted_nodes: Identifiers of nodes to highlight.
+        highlight_css: CSS to use for highlighting nodes.
+
+    Returns: The Mermaid code for the graph.
+    """
+    start_node_ids = set(node_ids(start_node or ()))
+    for node_id in start_node_ids:
+        if node_id not in graph.node_defs:
+            raise LookupError(f'Start node "{node_id}" is not in the graph.')
+
+    node_order = {node_id: index for index, node_id in enumerate(graph.node_defs)}
+
+    lines = ['graph TD']
+    for node in graph.nodes:
+        node_id = node.get_id()
+        node_def = graph.node_defs[node_id]
+
+        # we use round brackets (rounded box) for nodes other than the start and end
+        mermaid_name = f'({node_id})'
+        if node_id in start_node_ids:
+            lines.append(f'  START --> {node_id}{mermaid_name}')
+        if node_def.returns_base_node:
+            for next_node_id in graph.nodes:
+                lines.append(f'  {node_id}{mermaid_name} --> {next_node_id}')
+        else:
+            for _, next_node_id in sorted((node_order[node_id], node_id) for node_id in node_def.next_node_ids):
+                lines.append(f'  {node_id}{mermaid_name} --> {next_node_id}')
+        if node_def.returns_end:
+            lines.append(f'  {node_id}{mermaid_name} --> END')
+
+    if highlighted_nodes:
+        lines.append('')
+        lines.append(f'classDef highlighted {highlight_css}')
+        for node_id in node_ids(highlighted_nodes):
+            if node_id not in graph.node_defs:
+                raise LookupError(f'Highlighted node "{node_id}" is not in the graph.')
+            lines.append(f'class {node_id} highlighted')
+
+    return '\n'.join(lines)
+
+
+def node_ids(node_idents: Sequence[NodeIdent] | NodeIdent) -> Iterable[str]:
+    """Get the node IDs from a sequence of node identifiers."""
+    if isinstance(node_idents, str):
+        node_iter = (node_idents,)
+    elif isinstance(node_idents, Sequence):
+        node_iter = node_idents
+    else:
+        node_iter = (node_idents,)
+
+    for node in node_iter:
+        if isinstance(node, str):
+            yield node
+        else:
+            yield node.get_id()
+
+
+class MermaidConfig(TypedDict, total=False):
+    """Parameters to configure mermaid chart generation."""
+
+    start_node: Sequence[NodeIdent] | NodeIdent
+    """Identifiers of nodes that start the graph."""
+    highlighted_nodes: Sequence[NodeIdent] | NodeIdent
+    """Identifiers of nodes to highlight."""
+    highlight_css: str
+    """CSS to use for highlighting nodes."""
+    image_type: Literal['jpeg', 'png', 'webp', 'svg', 'pdf']
+    """The image type to generate. If unspecified, the default behavior is `'jpeg'`."""
+    pdf_fit: bool
+    """When using image_type='pdf', whether to fit the diagram to the PDF page."""
+    pdf_landscape: bool
+    """When using image_type='pdf', whether to use landscape orientation for the PDF.
+
+    This has no effect if using `pdf_fit`.
+    """
+    pdf_paper: Literal['letter', 'legal', 'tabloid', 'ledger', 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6']
+    """When using image_type='pdf', the paper size of the PDF."""
+    background_color: str
+    """The background color of the diagram.
+
+    If None, the default transparent background is used. The color value is interpreted as a hexadecimal color
+    code by default (and should not have a leading '#'), but you can also use named colors by prefixing the
+    value with `'!'`. For example, valid choices include `background_color='!white'` or `background_color='FF0000'`.
+    """
+    theme: Literal['default', 'neutral', 'dark', 'forest']
+    """The theme of the diagram. Defaults to 'default'."""
+    width: int
+    """The width of the diagram."""
+    height: int
+    """The height of the diagram."""
+    scale: Annotated[float, Ge(1), Le(3)]
+    """The scale of the diagram.
+
+    The scale must be a number between 1 and 3, and you can only set a scale if one or both of width and height are set.
+    """
+
+
+def request_image(
+    graph: Graph[Any, Any],
+    /,
+    **kwargs: Unpack[MermaidConfig],
+) -> bytes:
+    """Generate an image of a Mermaid diagram using [mermaid.ink](https://mermaid.ink).
+
+    Args:
+        graph: The graph to generate the image for.
+        **kwargs: Additional parameters to configure mermaid chart generation.
+
+    Returns: The image data.
+    """
+    import httpx
+
+    code = generate_code(
+        graph,
+        start_node=kwargs.get('start_node'),
+        highlighted_nodes=kwargs.get('highlighted_nodes'),
+        highlight_css=kwargs.get('highlight_css', DEFAULT_HIGHLIGHT_CSS),
+    )
+    code_base64 = base64.b64encode(code.encode()).decode()
+
+    params: dict[str, str | bool] = {}
+    if kwargs.get('image_type') == 'pdf':
+        url = f'https://mermaid.ink/pdf/{code_base64}'
+        if kwargs.get('pdf_fit'):
+            params['fit'] = True
+        if kwargs.get('pdf_landscape'):
+            params['landscape'] = True
+        if pdf_paper := kwargs.get('pdf_paper'):
+            params['paper'] = pdf_paper
+    elif kwargs.get('image_type') == 'svg':
+        url = f'https://mermaid.ink/svg/{code_base64}'
+    else:
+        url = f'https://mermaid.ink/img/{code_base64}'
+
+        if image_type := kwargs.get('image_type'):
+            params['type'] = image_type
+
+    if background_color := kwargs.get('background_color'):
+        params['bgColor'] = background_color
+    if theme := kwargs.get('theme'):
+        params['theme'] = theme
+    if width := kwargs.get('width'):
+        params['width'] = str(width)
+    if height := kwargs.get('height'):
+        params['height'] = str(height)
+    if scale := kwargs.get('scale'):
+        params['scale'] = str(scale)
+
+    response = httpx.get(url, params=params)
+    response.raise_for_status()
+    return response.content
+
+
+def save_image(
+    path: Path | str,
+    graph: Graph[Any, Any],
+    /,
+    **kwargs: Unpack[MermaidConfig],
+) -> None:
+    """Generate an image of a Mermaid diagram using [mermaid.ink](https://mermaid.ink) and save it to a local file.
+
+    Args:
+        path: The path to save the image to.
+        graph: The graph to generate the image for.
+        **kwargs: Additional parameters to configure mermaid chart generation.
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    if 'image_type' not in kwargs:
+        ext = path.suffix.lower()[1:]
+        # no need to check for .jpeg/.jpg, as it is the default
+        if ext in ('png', 'webp', 'svg', 'pdf'):
+            kwargs['image_type'] = ext
+
+    image_data = request_image(graph, **kwargs)
+    path.write_bytes(image_data)

pydantic_graph-0.0.1/pydantic_graph/nodes.py

@@ -0,0 +1,93 @@
+from __future__ import annotations as _annotations
+
+from abc import abstractmethod
+from dataclasses import dataclass
+from functools import cache
+from typing import Any, Generic, get_origin, get_type_hints
+
+from typing_extensions import Never, TypeVar
+
+from . import _utils
+from .state import StateT
+
+__all__ = 'GraphContext', 'BaseNode', 'End', 'NodeDef'
+
+RunEndT = TypeVar('RunEndT', default=None)
+NodeRunEndT = TypeVar('NodeRunEndT', covariant=True, default=Never)
+
+
+@dataclass
+class GraphContext(Generic[StateT]):
+    """Context for a graph."""
+
+    state: StateT
+
+
+class BaseNode(Generic[StateT, NodeRunEndT]):
+    """Base class for a node."""
+
+    @abstractmethod
+    async def run(self, ctx: GraphContext[StateT]) -> BaseNode[StateT, Any] | End[NodeRunEndT]: ...
+
+    @classmethod
+    @cache
+    def get_id(cls) -> str:
+        return cls.__name__
+
+    @classmethod
+    def get_node_def(cls, local_ns: dict[str, Any] | None) -> NodeDef[StateT, NodeRunEndT]:
+        type_hints = get_type_hints(cls.run, localns=local_ns)
+        try:
+            return_hint = type_hints['return']
+        except KeyError:
+            raise TypeError(f'Node {cls} is missing a return type hint on its `run` method')
+
+        next_node_ids: set[str] = set()
+        returns_end: bool = False
+        returns_base_node: bool = False
+        for return_type in _utils.get_union_args(return_hint):
+            return_type_origin = get_origin(return_type) or return_type
+            if return_type_origin is End:
+                returns_end = True
+            elif return_type_origin is BaseNode:
+                # TODO: Should we disallow this?
+                returns_base_node = True
+            elif issubclass(return_type_origin, BaseNode):
+                next_node_ids.add(return_type.get_id())
+            else:
+                raise TypeError(f'Invalid return type: {return_type}')
+
+        return NodeDef(
+            cls,
+            cls.get_id(),
+            next_node_ids,
+            returns_end,
+            returns_base_node,
+        )
+
+
+@dataclass
+class End(Generic[RunEndT]):
+    """Type to return from a node to signal the end of the graph."""
+
+    data: RunEndT
+
+
+@dataclass
+class NodeDef(Generic[StateT, NodeRunEndT]):
+    """Definition of a node.
+
+    Used by [`Graph`][pydantic_graph.graph.Graph] to store information about a node, and when generating
+    mermaid graphs.
+    """
+
+    node: type[BaseNode[StateT, NodeRunEndT]]
+    """The node definition itself."""
+    node_id: str
+    """ID of the node."""
+    next_node_ids: set[str]
+    """IDs of the nodes that can be called next."""
+    returns_end: bool
+    """The node definition returns an `End`, hence the node can end the run."""
+    returns_base_node: bool
+    """The node definition returns a `BaseNode`, hence any node in the next can be called next."""

pydantic_graph-0.0.1/pydantic_graph/state.py

@@ -0,0 +1,82 @@
+from __future__ import annotations as _annotations
+
+import copy
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Generic, Literal, Self, Union
+
+from typing_extensions import Never, TypeVar
+
+from . import _utils
+
+__all__ = 'AbstractState', 'StateT', 'NodeEvent', 'EndEvent', 'HistoryStep'
+
+if TYPE_CHECKING:
+    from pydantic_graph import BaseNode
+    from pydantic_graph.nodes import End
+
+
+class AbstractState(ABC):
+    """Abstract class for a state object."""
+
+    @abstractmethod
+    def serialize(self) -> bytes | None:
+        """Serialize the state object."""
+        raise NotImplementedError
+
+    def deep_copy(self) -> Self:
+        """Create a deep copy of the state object."""
+        return copy.deepcopy(self)
+
+
+RunEndT = TypeVar('RunEndT', default=None)
+NodeRunEndT = TypeVar('NodeRunEndT', covariant=True, default=Never)
+StateT = TypeVar('StateT', bound=Union[None, AbstractState], default=None)
+
+
+@dataclass
+class NodeEvent(Generic[StateT, RunEndT]):
+    """History step describing the execution of a node in a graph."""
+
+    state: StateT
+    node: BaseNode[StateT, RunEndT]
+    start_ts: datetime = field(default_factory=_utils.now_utc)
+    duration: float | None = None
+
+    kind: Literal['step'] = 'step'
+
+    def __post_init__(self):
+        # Copy the state to prevent it from being modified by other code
+        self.state = _deep_copy_state(self.state)
+
+    def summary(self) -> str:
+        return str(self.node)
+
+
+@dataclass
+class EndEvent(Generic[StateT, RunEndT]):
+    """History step describing the end of a graph run."""
+
+    state: StateT
+    result: End[RunEndT]
+    ts: datetime = field(default_factory=_utils.now_utc)
+
+    kind: Literal['end'] = 'end'
+
+    def __post_init__(self):
+        # Copy the state to prevent it from being modified by other code
+        self.state = _deep_copy_state(self.state)
+
+    def summary(self) -> str:
+        return str(self.result)
+
+
+def _deep_copy_state(state: StateT) -> StateT:
+    if state is None:
+        return state
+    else:
+        return state.deep_copy()
+
+
+HistoryStep = Union[NodeEvent[StateT, RunEndT], EndEvent[StateT, RunEndT]]

pydantic_graph-0.0.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pydantic-graph"
+version = "0.0.1"
+description = "Graph and state machine library"
+authors = [
+    { name = "Samuel Colvin", email = "samuel@pydantic.dev" },
+]
+license = "MIT"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Unix",
+    "Operating System :: POSIX :: Linux",
+    "Environment :: Console",
+    "Environment :: MacOS X",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.27.2",
+    "logfire-api>=1.2.0",
+    "pydantic>=2.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["pydantic_graph"]