gIO >ddlmZddlZddlZddlZddlmZddlm Z ddl m Z m Z ddl mZddlmZddlmZdd lmZmZmZmZmZmZddlZddlZddlZd d lmZmZm Z d d l!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'd d l(m)Z)m*Z*m+Z+m,Z,m-Z-m.Z. ddl/Z0ddlmZe0jbjdxjfe4ee5jljofz c_3dZ9ejtdZ;edZ< e dGddee,e#e'fZ=y#e8$rYCwxYw)) annotationsN)Sequence) ExitStack) dataclassfield)cached_property)Path) perf_counter) TYPE_CHECKING AnnotatedAnyCallableGenericTypeVar)_utils exceptionsmermaid)BaseNodeDepsTEndGraphRunContextNodeDefRunEndT)EndStep HistoryStepNodeStepStateTdeep_copy_statenodes_schema_var)Graphzpydantic-graph) otel_scopeTF)initc DeZdZUdZded<ded<ded<ed Zd ed <ed Zd ed <ed Zded<de je je dd d&dZ dddd d'dZ dddd d'dZdddd d(dZdd d)dZd*dZed+dZdddddej*ddd d,dZ d- d.dZdd d/d Zd0d!Zd1d"Z d2d#Zd$Zd3d%Zy)4r!uDefinition of a graph. In `pydantic-graph`, a graph is a collection of nodes that can be run in sequence. The nodes define their outgoing edges — e.g. which nodes may be run next, and thereby the structure of the graph. Here's a very simple example of a graph which increments a number by 1, but makes sure the number is never 42 at the end. ```py {title="never_42.py" noqa="I001" py="3.10"} from __future__ import annotations from dataclasses import dataclass from pydantic_graph import BaseNode, End, Graph, GraphRunContext @dataclass class MyState: number: int @dataclass class Increment(BaseNode[MyState]): async def run(self, ctx: GraphRunContext) -> Check42: ctx.state.number += 1 return Check42() @dataclass class Check42(BaseNode[MyState, None, int]): async def run(self, ctx: GraphRunContext) -> Increment | End[int]: if ctx.state.number == 42: return Increment() else: return End(ctx.state.number) never_42_graph = Graph(nodes=(Increment, Check42)) ``` _(This example is complete, it can be run "as is")_ See [`run`][pydantic_graph.graph.Graph.run] For an example of running graph, and [`mermaid_code`][pydantic_graph.graph.Graph.mermaid_code] for an example of generating a mermaid diagram from the graph. str | Nonenamez*dict[str, NodeDef[StateT, DepsT, RunEndT]] node_defsCallable[[StateT], StateT]snapshot_stateF)reprtype[StateT] | _utils.Unset _state_typetype[RunEndT] | _utils.Unset _run_end_typebool_auto_instrumentNT)r' state_type run_end_typer*auto_instrumentc||_||_||_||_||_t j tj}i|_ |D]}|j|||jy)aCreate a graph from a sequence of nodes. Args: nodes: The nodes which make up the graph, nodes need to be unique and all be generic in the same state type. name: Optional name for the graph, if not provided the name will be inferred from the calling frame on the first call to a graph method. state_type: The type of the state for the graph, this can generally be inferred from `nodes`. run_end_type: The type of the result of running the graph, this can generally be inferred from `nodes`. snapshot_state: A function to snapshot the state of the graph, this is used in [`NodeStep`][pydantic_graph.state.NodeStep] and [`EndStep`][pydantic_graph.state.EndStep] to record the state before each step. auto_instrument: Whether to create a span for the graph run and the execution of each node's run method. N) r'r-r/r1r*rget_parent_namespaceinspect currentframer(_register_node_validate_edges) selfnodesr'r2r3r*r4parent_namespacenodes I/var/www/openai/venv/lib/python3.12/site-packages/pydantic_graph/graph.py__init__zGraph.__init__\su0 %) /,!66w7K7K7MNEGD   &6 7 statedeps infer_namecK|r/|j#|jtjg}t 5}d}|j r5|j tjd|jxsd|}|} |j||||dd{}t|trF|jt|||jd||j|fcdddSt|t sHt"rt%j&|n,t)j*d t-|j.d 7#1swYyxYww) aRun the graph from a starting node until it ends. Args: start_node: the first node to run, since the graph definition doesn't define the entry point in the graph, you need to provide the starting node. state: The initial state of the graph. deps: The dependencies of the graph. infer_name: Whether to infer the graph name from the calling frame. Returns: The result type from ending the run and the history of the run. Here's an example of running the graph from [above][pydantic_graph.graph.Graph]: ```py {title="run_never_42.py" noqa="I001" py="3.10"} from never_42 import Increment, MyState, never_42_graph async def main(): state = MyState(1) _, history = await never_42_graph.run(Increment(), state=state) print(state) #> MyState(number=2) print(len(history)) #> 3 state = MyState(41) _, history = await never_42_graph.run(Increment(), state=state) print(state) #> MyState(number=43) print(len(history)) #> 5 ``` Nz{graph_name} run {start=}graph) graph_namestartFrB)resulthistoryzInvalid node return type: `z `. Expected `BaseNode` or `End`.)r' _infer_namer7r8rr1 enter_context_logfirespannext isinstancerappendr set_attributedatarr typing_extensions assert_neverrGraphRuntimeErrortype__name__) r; start_noderCrDrErKstackrun_span next_nodes r?runz Graph.runs<R $))+   W113 402 [E7;H$$ ..MM3#'99#7("#I"&))IweRVch)"ii i-NN7)#<=+ ..y'B$>>72%[&$Ix8$)66yA(::9$y/:R:R9SSsti[s2>E"A E E!AE1 E";AEEE"c|r/|j#|jtjt j j |j|||dS)aRun the graph synchronously. This is a convenience method that wraps [`self.run`][pydantic_graph.Graph.run] with `loop.run_until_complete(...)`. You therefore can't use this method inside async code or if there's an active event loop. Args: start_node: the first node to run, since the graph definition doesn't define the entry point in the graph, you need to provide the starting node. state: The initial state of the graph. deps: The dependencies of the graph. infer_name: Whether to infer the graph name from the calling frame. Returns: The result type from ending the run and the history of the run. FrB)r'rLr7r8asyncioget_event_looprun_until_completer^)r;rZrCrDrEs r?run_synczGraph.run_syncsW. $))+   W113 4%%':: HHZu4EH J  rAc xK|r/|j#|jtj|j }||j vrt jd|dt5}|jr'|jtjd||t||}tj} t!} |j#|d{} t!| z } ddd|j%t'||  |j( S7D#1swY6xYww)aRun a node in the graph and return the next node to run. Args: node: The node to run. history: The history of the graph run so far. NOTE: this will be mutated to add the new step. state: The current state of the graph. deps: The dependencies of the graph. infer_name: Whether to infer the graph name from the calling frame. Returns: The next node to run or [`End`][pydantic_graph.nodes.End] if the graph has finished. NzNode `z` is not in the graph.zrun node {node_id})node_idr>)rCr>start_tsdurationr*)r'rLr7r8get_idr(rrWrr1rMrNrOrrnow_utcr r^rRrr*) r;r>rKrCrDrErer[ctxrfrIr]rgs r?rPz Graph.nexts* $))+   W113 4++- $.. (..v=S/TU U [E$$##HMM2FPW^bM$cd!%.C~~'H NE"hhsm+I#~-H  5thbfbubu v  , [s1A3D:5A2D.'D,(D.93D:,D..D73D:indentc<|jj||S)zDump the history of a graph run as JSON. Args: history: The history of the graph run. indent: The number of spaces to indent the JSON. Returns: The JSON representation of the history. rk)history_type_adapter dump_json)r;rKrls r? dump_historyzGraph.dump_historys ((22762JJrAc8|jj|S)zLoad the history of a graph run from JSON. Args: json_bytes: The JSON representation of the history. Returns: The history of the graph run. )rn validate_json)r; json_bytess r? load_historyzGraph.load_historys((66zBBrAc|jjDcgc]}|j}}|j}|j }t j |} tjttt||ftjdf}t j||Scc}w#t j|wxYw)Nkind)r(valuesr>_get_state_type_get_run_end_typer setpydantic TypeAdapterlistr r Discriminatorreset)r;node_defr<state_tend_ttokentas r?rnzGraph.history_type_adapter(s/3~~/D/D/FG/F8/FG&&(&&( $$U+ *%%d9[%5PRZRhRhioRp5p+q&rsB  " "5 ) H  " "5 )sC(ACC)rZtitle edge_labelsnoteshighlighted_nodes highlight_cssrE directionc |r/|j#|jtj||jr |j}t j |||||xsd|||S)aaGenerate a diagram representing the graph as [mermaid](https://mermaid.js.org/) diagram. This method calls [`pydantic_graph.mermaid.generate_code`][pydantic_graph.mermaid.generate_code]. Args: start_node: The node or nodes which can start the graph. title: The title of the diagram, use `False` to not include a title. edge_labels: Whether to include edge labels. notes: Whether to include notes on each node. highlighted_nodes: Optional node or nodes to highlight. highlight_css: The CSS to use for highlighting nodes. infer_name: Whether to infer the graph name from the calling frame. direction: The direction of flow. Returns: The mermaid code for the graph, which can then be rendered as a diagram. Here's an example of generating a diagram for the graph from [above][pydantic_graph.graph.Graph]: ```py {title="never_42.py" py="3.10"} from never_42 import Increment, never_42_graph print(never_42_graph.mermaid_code(start_node=Increment)) ''' --- title: never_42_graph --- stateDiagram-v2 [*] --> Increment Increment --> Check42 Check42 --> Increment Check42 --> [*] ''' ``` The rendered diagram will look like this: ```mermaid --- title: never_42_graph --- stateDiagram-v2 [*] --> Increment Increment --> Check42 Check42 --> Increment Check42 --> [*] ``` N)rZrrrrrr)r'rLr7r8r generate_code) r;rZrrrrrrErs r? mermaid_codezGraph.mermaid_code4skx $))+   W113 4 =TYYIIE$$ !/'-4#  rAc |r/|j#|jtjd|vr|jr|j|d<t j |fi|S)aGenerate a diagram representing the graph as an image. The format and diagram can be customized using `kwargs`, see [`pydantic_graph.mermaid.MermaidConfig`][pydantic_graph.mermaid.MermaidConfig]. !!! note "Uses external service" This method makes a request to [mermaid.ink](https://mermaid.ink) to render the image, `mermaid.ink` is a free service not affiliated with Pydantic. Args: infer_name: Whether to infer the graph name from the calling frame. **kwargs: Additional arguments to pass to `mermaid.request_image`. Returns: The image bytes. r)r'rLr7r8r request_image)r;rEkwargss r? mermaid_imagezGraph.mermaid_imagesX& $))+   W113 4 & TYY"iiF7O$$T4V44rA)rEc |r/|j#|jtjd|vr|jr|j|d<t j ||fi|y)aGenerate a diagram representing the graph and save it as an image. The format and diagram can be customized using `kwargs`, see [`pydantic_graph.mermaid.MermaidConfig`][pydantic_graph.mermaid.MermaidConfig]. !!! note "Uses external service" This method makes a request to [mermaid.ink](https://mermaid.ink) to render the image, `mermaid.ink` is a free service not affiliated with Pydantic. Args: path: The path to save the image to. infer_name: Whether to infer the graph name from the calling frame. **kwargs: Additional arguments to pass to `mermaid.save_image`. Nr)r'rLr7r8r save_image)r;pathrErs r? mermaid_savezGraph.mermaid_savesW" $))+   W113 4 & TYY"iiF7O400rAcntj|jr |jS|jj D]c}t j |jD]?}t j|tust j|}|r |dccScetdS)Nr) ris_setr-r(rwrUget_original_basesr> get_originrget_argsrX)r;rbaseargss r?rxzGraph._get_state_types ==)) *## #--/H)<rrrlenis_neverrGraphSetupError)r;rrrts r?ryzGraph._get_run_end_types ==++ ,%% %--/H)< get_node_def)r;r>r=re existing_nodes r?r9zGraph._register_nodesy ++- NN..w7 7= 7,,G9$A-BTBTAUUZ[_Z`a '+&7&78H&IDNN7 #rAc J|jj}i}|jjD]N\}}|jjD],}||vs|j |gj d|d.P|r|jDcgc] \}}d|dt j|"}}}t|dk(rtj|dddjd|D} tjd| ycc}}w) N`z` is referenced by rrz but not included in the graph. c3&K|] }d| yw) N).0bes r? z(Graph._validate_edges..s@2"hszANodes are referenced in the graph but not included in the graph: ) r(keysitemsnext_node_edges setdefaultrRr comma_andrrrjoin) r;known_node_ids bad_edgesreredgekvbad_edges_listbs r?r:zGraph._validate_edgess%,,.*, !%!5!5!7 GX 00557~-((r299AgYa.I8"8 ZcZiZiZklZkRVRSUV!$78H8H8K7LMZkNl>"a' 00N14E3FFe1fggII@@@ 00XYZX[\ ls%Dc>|jJd||jx}ry|jjD]\}}||us ||_y|j|jk7r0|jjD]\}}||us ||_yyyyy)zInfer the agent name from the call frame. Usage should be `self._infer_name(inspect.currentframe())`. Copied from `Agent`. NzName already set)r'f_backf_localsr f_globals)r;function_frame parent_framer'items r?rLzGraph._infer_namesyy 4"44  %>;P;P+P<+P*3399; d4< $DI<$$ (>(>>"."8"8">">"@JD$t|$( #A? ,Q %rA) r<z0Sequence[type[BaseNode[StateT, DepsT, RunEndT]]]r'r&r2r,r3r.r*r)r4r0) r;Graph[StateT, DepsT, T]rZBaseNode[StateT, DepsT, T]rCrrDrrEr0returnz&tuple[T, list[HistoryStep[StateT, T]]])r;rr>rrKlist[HistoryStep[StateT, T]]rCrrDrrEr0rz%BaseNode[StateT, DepsT, Any] | End[T])r;rrKrrlz int | Nonerbytes)rszstr | bytes | bytearrayrz"list[HistoryStep[StateT, RunEndT]])rz8pydantic.TypeAdapter[list[HistoryStep[StateT, RunEndT]]])rZ6Sequence[mermaid.NodeIdent] | mermaid.NodeIdent | Nonerz-str | None | typing_extensions.Literal[False]rr0rr0rrrstrrEr0rz$mermaid.StateDiagramDirection | Nonerr)T)rEr0r/typing_extensions.Unpack[mermaid.MermaidConfig]rr)rz Path | strrEr0rrrNone)rz type[StateT])rz type[RunEndT])r;rr>z type[BaseNode[StateT, DepsT, T]]r=zdict[str, Any] | Nonerr)rztypes.FrameType | Nonerr)rY __module__ __qualname____doc____annotations__rr-r/r1rUNSETrr@r^rcrPrprtrrnrDEFAULT_HIGHLIGHT_CSSrrrrxryr9r:rLrrAr?r!r!)s(T 99../4%/@K,@27U2CM/C".d.  28,,5;\\5D $#@# # 0 # 3 #3##R F%F.F F  F  F 0FX  % .        0 D'%'('.'  '  '' /'Tgk K% K0L KYc K  K C  NR?C TX$:::>I KI = I  I  I RI I I 8I  I X"&551`5 54:>11261Ix1 1. p J% J. J0 J  J&rAr!)> __future__r _annotationsr`r7typescollections.abcr contextlibr dataclassesrr functoolsrpathlibr timer typingr r r rrr logfire_apir{rUrrrr<rrrrrrrCrrrrrr logfire._internal.stack_infologfire _internal stack_infoNON_USER_CODE_PREFIXESr__file__parentabsolute ImportError__all__LogfirerNr#r!rrAr?rs2 $ (%LL))JJ\\d'   77CX@U@U@^@^@`