Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.
Python aiburrchatbot-frameworkdagsgenerative-aigraphshacktoberfestllmopsllmsmlopspersistent-data-structurestate-machinestate-managementvisibility
Decouples application from Graph API
elijahbenizzyf1d935bea2f7
diff --git a/burr/core/application.py b/burr/core/application.pyindex 28dd9b36..69591f00 100644--- a/burr/core/application.py+++ b/burr/core/application.py@@ -1,8 +1,6 @@-import collectionsimport contextvarsimport dataclassesimport functools-import inspectimport loggingimport pprintimport uuid@@ -25,7 +23,7 @@ from typing import (from burr import telemetry, visibilityfrom burr.common import types as burr_types-from burr.core import persistence+from burr.core import persistence, validationfrom burr.core.action import (Action,AsyncStreamingAction,@@ -37,11 +35,11 @@ from burr.core.action import (SingleStepStreamingAction,StreamingAction,StreamingResultContainer,- create_action,- default,)+from burr.core.graph import Graph, GraphBuilderfrom burr.core.persistence import BaseStateLoader, BaseStateSaverfrom burr.core.state import State+from burr.core.validation import BASE_ERROR_MESSAGEfrom burr.lifecycle.base import LifecycleAdapterfrom burr.lifecycle.internal import LifecycleAdapterSet@@ -50,26 +48,9 @@ if TYPE_CHECKING:logger = logging.getLogger(__name__)--class Transition:- """Internal, utility class"""-- from_: Action- to: Action- condition: Condition--PRIOR_STEP = "__PRIOR_STEP"SEQUENCE_ID = "__SEQUENCE_ID"-ERROR_MESSAGE = (- "-------------------------------------------------------------------\n"- "Oh no an error! Need help with Burr?\n"- "Join our discord and ask for help! https://discord.gg/4FxBMyzW5n\n"- "-------------------------------------------------------------------\n"-)-def _validate_result(result: dict, name: str) -> None:if not isinstance(result, dict):@@ -81,7 +62,7 @@ def _validate_result(result: dict, name: str) -> None:def _raise_fn_return_validation_error(output: Any, action_name: str):raise ValueError(- ERROR_MESSAGE+ BASE_ERROR_MESSAGE+ f"Single step action: {action_name} must return either *just* the newly updated State or a tuple of (result: dict, state: State). "f"Got: {output} of type {type(output)} instead, which is not valid.")@@ -223,9 +204,9 @@ def _create_dict_string(kwargs: dict) -> str:return input_string-def _format_error_message(action: Action, input_state: State, inputs: dict) -> str:+def _format_BASE_ERROR_MESSAGE(action: Action, input_state: State, inputs: dict) -> str:"""Formats the error string, given that we're inside an action"""- message = ERROR_MESSAGE+ message = BASE_ERROR_MESSAGEmessage += f"> Action: `{action.name}` encountered an error!"padding = " " * (80 - len(message) - 1)message += padding + "<"@@ -381,7 +362,7 @@ async def _arun_single_step_action(@dataclasses.dataclass-class ApplicationGraph:+class ApplicationGraph(Graph):"""User-facing representation of the state machine. This has#. All the action objects@@ -389,8 +370,6 @@ class ApplicationGraph:#. The entrypoint action"""- actions: List[Action]- transitions: List[Transition]entrypoint: Action@@ -434,12 +413,11 @@ _application_context = contextvars.ContextVar[Optional[ApplicationContext]](class Application:def __init__(self,- actions: List[Action],- transitions: List[Transition],+ graph: Graph,state: State,- initial_step: str,partition_key: Optional[str],uid: str,+ entrypoint: str,sequence_id: Optional[int] = None,adapter_set: Optional[LifecycleAdapterSet] = None,builder: Optional["ApplicationBuilder"] = None,@@ -462,14 +440,16 @@ class Application:"""self._partition_key = partition_keyself._uid = uid- self._action_map = {action.name: action for action in actions}- self._adjacency_map = Application._create_adjacency_map(transitions)- self._transitions = transitions- self._actions = actions- self._initial_step = initial_step+ self.entrypoint = entrypoint++ self._graph = graph+ self._public_facing_graph = ApplicationGraph(+ actions=graph.actions,+ transitions=graph.transitions,+ entrypoint=graph.get_action(entrypoint),+ )self._state = stateself._adapter_set = adapter_set if adapter_set is not None else LifecycleAdapterSet()- self._graph = self._create_graph()# TODO -- consider adding global inputs + global input factories to the builderself._tracker = tracker@@ -487,7 +467,7 @@ class Application:self._adapter_set.call_all_lifecycle_hooks_sync("post_application_create",state=self._state,- application_graph=self._graph,+ application_graph=self._public_facing_graph,app_id=self._uid,partition_key=self._partition_key,parent_pointer=fork_parent_pointer,@@ -564,7 +544,7 @@ class Application:self._set_state(new_state)except Exception as e:exc = e- logger.exception(_format_error_message(next_action, self._state, inputs))+ logger.exception(_format_BASE_ERROR_MESSAGE(next_action, self._state, inputs))raise efinally:if _run_hooks:@@ -598,7 +578,7 @@ class Application:starting_with_double_underscore = {key for key in inputs.keys() if key.startswith("__")}if len(starting_with_double_underscore) > 0:raise ValueError(- ERROR_MESSAGE+ BASE_ERROR_MESSAGE+ f"Inputs starting with a double underscore ({starting_with_double_underscore}) "f"are reserved for internal use/injected inputs.""Please do not use keys"@@ -703,7 +683,7 @@ class Application:self._set_state(new_state)except Exception as e:exc = e- logger.exception(_format_error_message(next_action, self._state, inputs))+ logger.exception(_format_BASE_ERROR_MESSAGE(next_action, self._state, inputs))raise efinally:if _run_hooks:@@ -743,13 +723,15 @@ class Application:def _validate_halt_conditions(self, halt_before: list[str], halt_after: list[str]) -> None:"""Utility function to validate halt conditions"""- missing_actions = set(halt_before + halt_after) - set(self._action_map.keys())+ missing_actions = set(halt_before + halt_after) - set(+ action.name for action in self.graph.actions+ )if len(missing_actions) > 0:raise ValueError(- ERROR_MESSAGE+ BASE_ERROR_MESSAGE+ f"Halt conditions {missing_actions} are not registered actions. Please ensure that they have been "f"registered as actions in the application and that you've spelled them correctly!"- f"Valid actions are: {self._action_map.keys()}"+ f"Valid actions are: {[action.name for action in self.graph.actions]}")def has_next_action(self) -> bool:@@ -1391,77 +1373,20 @@ class Application::param engine_kwargs: Additional kwargs to pass to the engine:return: The graphviz object"""- if engine != "graphviz":- raise ValueError(f"Only graphviz is supported for now, not {engine}")- try:- import graphviz # noqa: F401- except ModuleNotFoundError:- logger.exception(- " graphviz is required for visualizing the application graph. Install it with:"- '\n\n pip install "burr[graphviz]" or pip install graphviz \n\n'- )- return- digraph_attr = dict(- graph_attr=dict(- rankdir="TB",- ranksep="0.4",- compound="false",- concentrate="false",- ),+ return self.graph.visualize(+ output_file_path=output_file_path,+ include_conditions=include_conditions,+ include_state=include_state,+ view=view,+ engine=engine,+ **engine_kwargs,)- for g_key, g_value in engine_kwargs.items():- if isinstance(g_value, dict):- digraph_attr[g_key].update(**g_value)- else:- digraph_attr[g_key] = g_value- digraph = graphviz.Digraph(**digraph_attr)- for action in self._actions:- label = (- action.name- if not include_state- else f"{action.name}({', '.join(action.reads)}): {', '.join(action.writes)}"- )- digraph.node(action.name, label=label, shape="box", style="rounded")- required_inputs, optional_inputs = action.optional_and_required_inputs- for input_ in required_inputs | optional_inputs:- if input_.startswith("__"):- # These are internally injected by the framework- continue- input_name = f"input__{input_}"- digraph.node(input_name, shape="oval", style="dashed", label=f"input: {input_}")- digraph.edge(input_name, action.name)- for transition in self._transitions:- condition = transition.condition- digraph.edge(- transition.from_.name,- transition.to.name,- label=condition.name if include_conditions and condition is not default else None,- style="dashed" if transition.condition is not default else "solid",- )- if output_file_path:- digraph.render(output_file_path, view=view)- return digraph-- @staticmethod- def _create_adjacency_map(transitions: List[Transition]) -> dict:- adjacency_map = collections.defaultdict(list)- for transition in transitions:- from_ = transition.from_- to = transition.to- adjacency_map[from_.name].append((to.name, transition.condition))- return adjacency_mapdef _set_state(self, new_state: State):self._state = new_statedef get_next_action(self) -> Optional[Action]:- if PRIOR_STEP not in self._state:- return self._action_map[self._initial_step]- possibilities = self._adjacency_map[self._state[PRIOR_STEP]]- for next_action, condition in possibilities:- if condition.run(self._state)[Condition.KEY]:- return self._action_map[next_action]- return None+ return self._graph.get_next_node(self._state.get(PRIOR_STEP), self._state, self.entrypoint)def update_state(self, new_state: State):"""Updates state -- this is meant to be called if you need to do@@ -1507,15 +1432,6 @@ class Application:"""return self._spawning_parent_pointer- def _create_graph(self) -> ApplicationGraph:- """Internal-facing utility function for creating an ApplicationGraph"""- all_actions = {action.name: action for action in self._actions}- return ApplicationGraph(- actions=self._actions,- transitions=self._transitions,- entrypoint=all_actions[self._initial_step],- )-@propertydef graph(self) -> ApplicationGraph:"""Application graph object -- if you want to inspect, visualize, etc..@@ -1523,7 +1439,7 @@ class Application::return: The application graph object"""- return self._graph+ return self._public_facing_graph@propertydef sequence_id(self) -> Optional[int]:@@ -1596,42 +1512,16 @@ class Application:return dot._repr_mimebundle_(include=include, exclude=exclude, **kwargs)-def _assert_set(value: Optional[Any], field: str, method: str):- if value is None:+def _validate_app_id(app_id: Optional[str]):+ if app_id is None:raise ValueError(- ERROR_MESSAGE- + f"Must set `{field}` before building application! Do so with ApplicationBuilder.{method}"+ "App ID was None. Please ensure that you set an app ID using with_identifiers(app_id=...), or default"+ "not setting it and letting the system generate one for you.")-def _validate_transitions(- transitions: Optional[List[Tuple[str, str, Condition]]], actions: Set[str]-):- _assert_set(transitions, "_transitions", "with_transitions")- exhausted = {} # items for which we have seen a default transition- for from_, to, condition in transitions:- if from_ not in actions:- raise ValueError(- f"Transition source: `{from_}` not found in actions! "- f"Please add to actions using with_actions({from_}=...)"- )- if to not in actions:- raise ValueError(- f"Transition target: `{to}` not found in actions! "- f"Please add to actions using with_actions({to}=...)"- )- if condition.name == "default": # we have seen a default transition- if from_ in exhausted:- raise ValueError(- f"Transition `{from_}` -> `{to}` is redundant -- "- f"a default transition has already been set for `{from_}`"- )- exhausted[from_] = True- return True--def _validate_start(start: Optional[str], actions: Set[str]):- _assert_set(start, "_start", "with_entrypoint")+ validation.assert_set(start, "_start", "with_entrypoint")if start not in actions:raise ValueError(f"Entrypoint: {start} not found in actions. Please add "@@ -1639,26 +1529,10 @@ def _validate_start(start: Optional[str], actions: Set[str]):)-def _validate_app_id(app_id: Optional[str]):- if app_id is None:- raise ValueError(- "App ID was None. Please ensure that you set an app ID using with_identifiers(app_id=...), or default"- "not setting it and letting the system generate one for you."- )---def _validate_actions(actions: Optional[List[Action]]):- _assert_set(actions, "_actions", "with_actions")- if len(actions) == 0:- raise ValueError("Must have at least one action in the application!")--class ApplicationBuilder:def __init__(self):+ self.start = Noneself.state: Optional[State] = None- self.transitions: Optional[List[Tuple[str, str, Condition]]] = None- self.actions: Optional[List[Action]] = None- self.start: Optional[str] = Noneself.lifecycle_adapters: List[LifecycleAdapter] = list()self.app_id: str = str(uuid.uuid4())self.partition_key: Optional[str] = None@@ -1674,6 +1548,8 @@ class ApplicationBuilder:self.spawn_from_sequence_id: Optional[int] = Noneself.loaded_from_fork: bool = Falseself.tracker = None+ self.graph_builder = None+ self.prebuilt_graph = Nonedef with_identifiers(self, app_id: str = None, partition_key: str = None, sequence_id: int = None@@ -1706,7 +1582,7 @@ class ApplicationBuilder:"""if self.initializer is not None:raise ValueError(- ERROR_MESSAGE + "You cannot set state if you are loading state"+ BASE_ERROR_MESSAGE + "You cannot set state if you are loading state""the .initialize_from() API. Either allow the persister to set the ""state, or set the state manually.")@@ -1716,6 +1592,39 @@ class ApplicationBuilder:self.state = State(kwargs)return self+ def with_graph(self, graph: Graph) -> "ApplicationBuilder":+ """Adds a prebuilt graph -- this is an alternative to using the with_actions and with_transitions methods.+ While you will likely use with_actions and with_transitions, you may want this in a few cases:++ 1. You want to reuse the same graph object for different applications+ 2. You want the logic that constructs the graph to be separate from that which constructs the application+ 3. You want to serialize/deserialize a graph object and run it in an application++ :param graph: Graph object built with the :py:class:`GraphBuilder <burr.core.graph.GraphBuilder>`+ :return: The application builder for future chaining.+ """+ if self.graph_builder is not None:+ raise ValueError(+ BASE_ERROR_MESSAGE+ + "You have already called `with_actions`, or `with_transitions` -- you currently "+ "cannot use the with_graph method along with that. Use `with_graph` or the other methods, not both"+ )+ self.prebuilt_graph = graph+ return self++ def _ensure_no_prebuilt_graph(self):+ if self.prebuilt_graph is not None:+ raise ValueError(+ BASE_ERROR_MESSAGE + "You have already called `with_graph` -- you currently "+ "cannot use the with_actions, or with_transitions method along with that. "+ "Use `with_graph` or the other methods, not both."+ )+ return self++ def _initialize_graph_builder(self):+ if self.graph_builder is None:+ self.graph_builder = GraphBuilder()+def with_entrypoint(self, action: str) -> "ApplicationBuilder":"""Adds an entrypoint to the application. This is the action that will be run first.This can only be called once.@@ -1723,10 +1632,9 @@ class ApplicationBuilder::param action: The name of the action to set as the entrypoint:return: The application builder for future chaining."""- # TODO -- validate only called onceif self.start is not None:raise ValueError(- ERROR_MESSAGE+ BASE_ERROR_MESSAGE+ "You cannot set the entrypoint if you are loading a persister using ""the .initialize_from() API. Either allow the persister to set the ""entrypoint/provide a default, or set the entrypoint + state manually."@@ -1745,21 +1653,9 @@ class ApplicationBuilder::param action_dict: Actions to add, keyed by name:return: The application builder for future chaining."""- if self.actions is None:- self.actions = []- for action_value in action_list:- if inspect.isfunction(action_value):- self.actions.append(create_action(action_value, action_value.__name__))- elif isinstance(action_value, Action):- if not action_value.name:- raise ValueError(- ERROR_MESSAGE + f"Action: {action_value} must have a name set. "- "If you hit this, you should probably be using the "- "**kwargs parameter (or call with_name(your_name) on the action)."- )- self.actions.append(action_value)- for key, value in action_dict.items():- self.actions.append(create_action(value, key))+ self._ensure_no_prebuilt_graph()+ self._initialize_graph_builder()+ self.graph_builder = self.graph_builder.with_actions(*action_list, **action_dict)return selfdef with_transitions(@@ -1779,22 +1675,9 @@ class ApplicationBuilder::param transitions: Transitions to add:return: The application builder for future chaining."""- if self.transitions is None:- self.transitions = []- for transition in transitions:- from_, to_, *conditions = transition- if len(conditions) > 0:- condition = conditions[0]- else:- condition = default- if not isinstance(from_, list):- from_ = [from_]- for action in from_:- if not isinstance(action, str):- raise ValueError(f"Transition source must be a string, not {action}")- if not isinstance(to_, str):- raise ValueError(f"Transition target must be a string, not {to_}")- self.transitions.append((action, to_, condition))+ self._ensure_no_prebuilt_graph()+ self._initialize_graph_builder()+ self.graph_builder = self.graph_builder.with_transitions(*transitions)return selfdef with_hooks(self, *adapters: LifecycleAdapter) -> "ApplicationBuilder":@@ -1879,13 +1762,13 @@ class ApplicationBuilder:"""if self.start is not None or self.state is not None:raise ValueError(- ERROR_MESSAGE+ BASE_ERROR_MESSAGE+ "Cannot call initialize_from if you have already set state or an entrypoint! ""You can either use the initializer *or* set the state and entrypoint manually.")if not fork_from_app_id and (fork_from_partition_key or fork_from_sequence_id):raise ValueError(- ERROR_MESSAGE+ BASE_ERROR_MESSAGE+ "If you set fork_from_partition_key or fork_from_sequence_id, you must also set fork_from_app_id. ""See .initialize_from() documentation.")@@ -1954,7 +1837,7 @@ class ApplicationBuilder:if self.fork_from_app_id is not None:if self.app_id == self.fork_from_app_id:raise ValueError(- ERROR_MESSAGE + "Cannot fork and save to the same app_id. "+ BASE_ERROR_MESSAGE + "Cannot fork and save to the same app_id. ""Please update the app_id passed in via with_identifiers(), ""or don't pass in a fork_from_app_id value to `initialize_from()`.")@@ -1984,7 +1867,7 @@ class ApplicationBuilder:self.loaded_from_fork = Trueif load_result["state"] is None:raise ValueError(- ERROR_MESSAGE+ BASE_ERROR_MESSAGE+ f"Error: {self.initializer.__class__.__name__} returned {load_result} for "f"partition_key:{_partition_key}, app_id:{_app_id}, "f"sequence_id:{_sequence_id}, "@@ -2013,6 +1896,17 @@ class ApplicationBuilder:def reset_to_entrypoint(self):self.state = self.state.wipe(delete=[PRIOR_STEP])+ def _get_built_graph(self) -> Graph:+ if self.graph_builder is None and self.prebuilt_graph is None:+ raise ValueError(+ BASE_ERROR_MESSAGE+ + "You must set the graph using with_graph, or use with_entrypoint, with_actions, and with_transitions"+ "to build the graph."+ )+ if self.graph_builder is not None:+ return self.graph_builder.build()+ return self.prebuilt_graph+@telemetry.capture_function_usagedef build(self) -> Application:"""Builds the application.@@ -2021,33 +1915,22 @@ class ApplicationBuilder::return: The application object"""- _validate_actions(self.actions)- actions_by_name = {action.name: action for action in self.actions}- all_actions = set(actions_by_name.keys())- _validate_transitions(self.transitions, all_actions)+_validate_app_id(self.app_id)if self.state is None:self.state = State()if self.initializer:# sets state, sequence_id, and maybe startself._load_from_persister()- _validate_start(self.start, all_actions)-+ graph = self._get_built_graph()+ _validate_start(self.start, {action.name for action in graph.actions})return Application(- actions=self.actions,- transitions=[- Transition(- from_=actions_by_name[from_],- to=actions_by_name[to],- condition=condition,- )- for from_, to, condition in self.transitions- ],+ graph=graph,state=self.state,- initial_step=self.start,uid=self.app_id,partition_key=self.partition_key,sequence_id=self.sequence_id,+ entrypoint=self.start,adapter_set=LifecycleAdapterSet(*self.lifecycle_adapters),builder=self,fork_parent_pointer=burr_types.ParentPointer(diff --git a/burr/core/graph.py b/burr/core/graph.pynew file mode 100644index 00000000..7ad98bb6--- /dev/null+++ b/burr/core/graph.py@@ -0,0 +1,265 @@+import collections+import dataclasses+import inspect+import logging+from typing import Any, Callable, List, Literal, Optional, Set, Tuple, Union++from burr import telemetry+from burr.core.action import Action, Condition, create_action, default+from burr.core.state import State+from burr.core.validation import BASE_ERROR_MESSAGE, assert_set++logger = logging.getLogger(__name__)+++class Transition:+ """Internal, utility class"""++ from_: Action+ to: Action+ condition: Condition+++def _validate_actions(actions: Optional[List[Action]]):+ assert_set(actions, "_actions", "with_actions")+ if len(actions) == 0:+ raise ValueError("Must have at least one action in the application!")+++def _validate_transitions(+ transitions: Optional[List[Tuple[str, str, Condition]]], actions: Set[str]+):+ assert_set(transitions, "_transitions", "with_transitions")+ exhausted = {} # items for which we have seen a default transition+ for from_, to, condition in transitions:+ if from_ not in actions:+ raise ValueError(+ f"Transition source: `{from_}` not found in actions! "+ f"Please add to actions using with_actions({from_}=...)"+ )+ if to not in actions:+ raise ValueError(+ f"Transition target: `{to}` not found in actions! "+ f"Please add to actions using with_actions({to}=...)"+ )+ if condition.name == "default": # we have seen a default transition+ if from_ in exhausted:+ raise ValueError(+ f"Transition `{from_}` -> `{to}` is redundant -- "+ f"a default transition has already been set for `{from_}`"+ )+ exhausted[from_] = True+ return True+++class Graph:+ """Graph class allows you to specify actions and transitions between them.+ You will never instantiate this directly, just through the GraphBuilder,+ or indirectly through the ApplicationBuilder."""++ actions: List[Action]+ transitions: List[Transition]++ def __post_init__(self):+ """Sets up initial state for easy graph operations later"""+ self._action_map = {action.name: action for action in self.actions}+ self._adjacency_map = Graph._create_adjacency_map(self.transitions)++ @staticmethod+ def _create_adjacency_map(transitions: List[Transition]) -> dict:+ adjacency_map = collections.defaultdict(list)+ for transition in transitions:+ from_ = transition.from_+ to = transition.to+ adjacency_map[from_.name].append((to.name, transition.condition))+ return adjacency_map++ def get_next_node(+ self, prior_step: Optional[str], state: State, entrypoint: str+ ) -> Optional[Action]:+ """Gives the next node to execute given state + prior step."""+ if prior_step is None:+ return self._action_map[entrypoint]+ possibilities = self._adjacency_map[prior_step]+ for next_action, condition in possibilities:+ if condition.run(state)[Condition.KEY]:+ return self._action_map[next_action]+ return None++ def get_action(self, action_name: str) -> Optional[Action]:+ """Gets an action object given the action name"""+ if action_name not in self._action_map:+ raise ValueError(+ BASE_ERROR_MESSAGE + f"Action: {action_name} not found in graph. "+ f"Actions are: {self._action_map.keys()}"+ )+ return self._action_map.get(action_name)++ @telemetry.capture_function_usage+ def visualize(+ self,+ output_file_path: Optional[str] = None,+ include_conditions: bool = False,+ include_state: bool = False,+ view: bool = False,+ engine: Literal["graphviz"] = "graphviz",+ **engine_kwargs: Any,+ ) -> Optional["graphviz.Digraph"]: # noqa: F821+ """Visualizes the graph using graphviz. This will render the graph.++ :param output_file_path: The path to save this to, None if you don't want to save. Do not pass an extension+ for graphviz, instead pass `format` in `engine_kwargs` (e.g. `format="png"`)+ :param include_conditions: Whether to include condition strings on the edges (this can get noisy)+ :param include_state: Whether to indicate the action "signature" (reads/writes) on the nodes+ :param view: Whether to bring up a view+ :param engine: The engine to use -- only graphviz is supported for now+ :param engine_kwargs: Additional kwargs to pass to the engine+ :return: The graphviz object+ """+ if engine != "graphviz":+ raise ValueError(f"Only graphviz is supported for now, not {engine}")+ try:+ import graphviz # noqa: F401+ except ModuleNotFoundError:+ logger.exception(+ " graphviz is required for visualizing the application graph. Install it with:"+ '\n\n pip install "burr[graphviz]" or pip install graphviz \n\n'+ )+ return+ digraph_attr = dict(+ graph_attr=dict(+ rankdir="TB",+ ranksep="0.4",+ compound="false",+ concentrate="false",+ ),+ )+ for g_key, g_value in engine_kwargs.items():+ if isinstance(g_value, dict):+ digraph_attr[g_key].update(**g_value)+ else:+ digraph_attr[g_key] = g_value+ digraph = graphviz.Digraph(**digraph_attr)+ for action in self.actions:+ label = (+ action.name+ if not include_state+ else f"{action.name}({', '.join(action.reads)}): {', '.join(action.writes)}"+ )+ digraph.node(action.name, label=label, shape="box", style="rounded")+ required_inputs, optional_inputs = action.optional_and_required_inputs+ for input_ in required_inputs | optional_inputs:+ if input_.startswith("__"):+ # These are internally injected by the framework+ continue+ input_name = f"input__{input_}"+ digraph.node(input_name, shape="oval", style="dashed", label=f"input: {input_}")+ digraph.edge(input_name, action.name)+ for transition in self.transitions:+ condition = transition.condition+ digraph.edge(+ transition.from_.name,+ transition.to.name,+ label=condition.name if include_conditions and condition is not default else None,+ style="dashed" if transition.condition is not default else "solid",+ )+ if output_file_path:+ digraph.render(output_file_path, view=view)+ return digraph+++class GraphBuilder:+ """GraphBuilder class. This allows you to construct a graph without considering application concerns.+ While you can (and at first, should) use the ApplicationBuidler (which has the same API), this is lower level+ and allows you to decouple concerns, reuse the same graph object, etc..."""++ def __init__(self):+ """Initializes the graph builder."""+ self.transitions: Optional[List[Tuple[str, str, Condition]]] = None+ self.actions: Optional[List[Action]] = None++ def with_actions(+ self, *action_list: Union[Action, Callable], **action_dict: Union[Action, Callable]+ ) -> "GraphBuilder":+ """Adds an action to the application. The actions are granted names (using the with_name)+ method post-adding, using the kw argument. If it already has a name (or you wish to use the function name, raw, and+ it is a function-based-action), then you can use the *args* parameter. This is the only supported way to add actions.++ :param action_list: Actions to add -- these must have a name or be function-based (in which case we will use the function-name)+ :param action_dict: Actions to add, keyed by name+ :return: The application builder for future chaining.+ """+ if self.actions is None:+ self.actions = []+ for action_value in action_list:+ if inspect.isfunction(action_value):+ self.actions.append(create_action(action_value, action_value.__name__))+ elif isinstance(action_value, Action):+ if not action_value.name:+ raise ValueError(+ BASE_ERROR_MESSAGE + f"Action: {action_value} must have a name set. "+ "If you hit this, you should probably be using the "+ "**kwargs parameter (or call with_name(your_name) on the action)."+ )+ self.actions.append(action_value)+ for key, value in action_dict.items():+ self.actions.append(create_action(value, key))+ return self++ def with_transitions(+ self,+ *transitions: Union[+ Tuple[Union[str, list[str]], str], Tuple[Union[str, list[str]], str, Condition]+ ],+ ) -> "GraphBuilder":+ """Adds transitions to the graph. Transitions are specified as tuples of either:+ 1. (from, to, condition)+ 2. (from, to) -- condition is set to DEFAULT (which is a fallback)++ Transitions will be evaluated in order of specification -- if one is met, the others will not be evaluated.+ Note that one transition can be terminal -- the system doesn't have+++ :param transitions: Transitions to add+ :return: The application builder for future chaining.+ """+ if self.transitions is None:+ self.transitions = []+ for transition in transitions:+ from_, to_, *conditions = transition+ if len(conditions) > 0:+ condition = conditions[0]+ else:+ condition = default+ if not isinstance(from_, list):+ from_ = [from_]+ for action in from_:+ if not isinstance(action, str):+ raise ValueError(f"Transition source must be a string, not {action}")+ if not isinstance(to_, str):+ raise ValueError(f"Transition target must be a string, not {to_}")+ self.transitions.append((action, to_, condition))+ return self++ def build(self) -> Graph:+ """Builds/finalizes the graph.++ :return: The graph object+ """+ _validate_actions(self.actions)+ actions_by_name = {action.name: action for action in self.actions}+ all_actions = set(actions_by_name.keys())+ _validate_transitions(self.transitions, all_actions)+ return Graph(+ actions=self.actions,+ transitions=[+ Transition(+ from_=actions_by_name[from_],+ to=actions_by_name[to],+ condition=condition,+ )+ for from_, to, condition in self.transitions+ ],+ )diff --git a/burr/core/validation.py b/burr/core/validation.pynew file mode 100644index 00000000..e1e95514--- /dev/null+++ b/burr/core/validation.py@@ -0,0 +1,16 @@+from typing import Any, Optional++BASE_ERROR_MESSAGE = (+ "-------------------------------------------------------------------\n"+ "Oh no an error! Need help with Burr?\n"+ "Join our discord and ask for help! https://discord.gg/4FxBMyzW5n\n"+ "-------------------------------------------------------------------\n"+)+++def assert_set(value: Optional[Any], field: str, method: str):+ if value is None:+ raise ValueError(+ BASE_ERROR_MESSAGE+ + f"Must set `{field}` before building application! Do so with ApplicationBuilder.{method}"+ )diff --git a/burr/tracking/common/models.py b/burr/tracking/common/models.pyindex bb926e4a..c66b7641 100644--- a/burr/tracking/common/models.py+++ b/burr/tracking/common/models.py@@ -3,7 +3,8 @@ from typing import Any, Dict, List, Literal, Optionalfrom burr.common import types as burr_typesfrom burr.core import Action-from burr.core.application import ApplicationGraph, Transition+from burr.core.application import ApplicationGraph+from burr.core.graph import Transitionfrom burr.integrations.base import require_plugintry:diff --git a/docs/concepts/state-machine.rst b/docs/concepts/state-machine.rstindex 621683db..48ff62d6 100644--- a/docs/concepts/state-machine.rst+++ b/docs/concepts/state-machine.rst@@ -141,6 +141,36 @@ In the async context, you can run ``arun``:These allow you to stream responses back. Note they work best with streaming actions.Read about them in the :ref:`streaming <streaming>` section.+---------+Graph API+---------++The application exposes a graph API, allowing you to specify it as a graph separate from application concerns.+While you likely won't use this in your first few applications, it will become useful when you want ito run it+in a web-server (create a graph once, application many times), import the graph from another context, or run it in multiple contexts.+++.. code-block:: python++ from burr.core import ApplicationBuilder, default, expr+ graph = (+ GraphBuilder()+ .with_actions(human_input, ai_response)+ .with_transitions(+ ("human_input", "ai_response"),+ ("ai_response", "human_input")+ ).build()+ )+ app = (+ ApplicationBuilder()+ .with_graph(graph)+ with_state(chat_history=[])+ .with_entrypoint("human_input")+ .build()+ )++You can read more about it in the :py:class:`GraphBuilder docs <burr.core.graph.GraphBuilder>`.+----------Inspection----------diff --git a/docs/reference/application.rst b/docs/reference/application.rstindex 0a1fac54..f6dfc3b9 100644--- a/docs/reference/application.rst+++ b/docs/reference/application.rst@@ -1,6 +1,6 @@-=================+============Applications-=================+============Use this to build and manage a state Machine. You should only ever instantiate the ``ApplicationBuilder`` class,and not the ``Application`` class directly.@@ -21,3 +21,19 @@ and not the ``Application`` class directly... autoclass:: burr.core.application.ApplicationContext:members:++==========+Graph APIs+==========++You can, optionally, use the graph API along with the :py:meth:`burr.core.application.ApplicationBuilder.with_graph`+method. While this is a little more verbose, it helps decouple application logic from graph logic, and is useful in a host+of situations.++The ``GraphBuilder`` class is used to build a graph, and the ``Graph`` class can be passed to the application builder.++.. autoclass:: burr.core.graph.GraphBuilder+ :members:++.. autoclass:: burr.core.graph.Graph+ :members:diff --git a/tests/core/test_application.py b/tests/core/test_application.pyindex 34cca0f4..d6c4257a 100644--- a/tests/core/test_application.py+++ b/tests/core/test_application.py@@ -26,22 +26,19 @@ from burr.core.application import (Application,ApplicationBuilder,ApplicationContext,- Transition,_adjust_single_step_output,_arun_function,_arun_multi_step_streaming_action,_arun_single_step_action,_arun_single_step_streaming_action,- _assert_set,_run_function,_run_multi_step_streaming_action,_run_reducer,_run_single_step_action,_run_single_step_streaming_action,- _validate_actions,_validate_start,- _validate_transitions,)+from burr.core.graph import Graph, Transitionfrom burr.core.persistence import BaseStatePersister, DevNullPersister, PersistedStateDatafrom burr.lifecycle import (PostRunStepHook,@@ -869,13 +866,15 @@ def test_app_step():"""Tests that we can run a step in an app"""counter_action = base_counter_action.with_name("counter")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)action, result, state = app.step()assert app.sequence_id == 1@@ -888,13 +887,15 @@ def test_app_step_with_inputs():"""Tests that we can run a step in an app"""counter_action = base_single_step_counter_with_inputs.with_name("counter")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State({"count": 0, "tracker": []}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)action, result, state = app.step(inputs={"additional_increment": 1})assert action.name == "counter"@@ -906,13 +907,15 @@ def test_app_step_with_inputs_missing():"""Tests that we can run a step in an app"""counter_action = base_single_step_counter_with_inputs.with_name("counter")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State({"count": 0, "tracker": []}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)with pytest.raises(ValueError, match="missing required inputs"):app.step(inputs={})@@ -922,13 +925,15 @@ def test_app_step_broken(caplog):"""Tests that we can run a step in an app"""broken_action = base_broken_action.with_name("broken_action_unique_name")app = Application(- actions=[broken_action],- transitions=[Transition(broken_action, broken_action, default)],state=State({}),- initial_step="broken_action_unique_name",+ entrypoint="broken_action_unique_name",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[broken_action],+ transitions=[Transition(broken_action, broken_action, default)],+ ),)with caplog.at_level(logging.ERROR): # it should say the name, that's the only contract for nowwith pytest.raises(BrokenStepException):@@ -940,13 +945,15 @@ def test_app_step_done():"""Tests that when we cannot run a step, we return None"""counter_action = base_counter_action.with_name("counter")app = Application(- actions=[counter_action],- transitions=[],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[],+ ),)app.step()assert app.step() is None@@ -956,13 +963,15 @@ async def test_app_astep():"""Tests that we can run an async step in an app"""counter_action = base_counter_action_async.with_name("counter_async")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State({}),- initial_step="counter_async",+ entrypoint="counter_async",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)action, result, state = await app.astep()assert app.sequence_id == 1@@ -975,13 +984,15 @@ async def test_app_astep_with_inputs():"""Tests that we can run an async step in an app"""counter_action = base_single_step_counter_with_inputs_async.with_name("counter_async")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State({"count": 0, "tracker": []}),- initial_step="counter_async",+ entrypoint="counter_async",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)action, result, state = await app.astep(inputs={"additional_increment": 1})assert action.name == "counter_async"@@ -993,13 +1004,15 @@ async def test_app_astep_with_inputs_missing():"""Tests that we can run an async step in an app"""counter_action = base_single_step_counter_with_inputs_async.with_name("counter_async")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State({"count": 0, "tracker": []}),- initial_step="counter_async",+ entrypoint="counter_async",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)with pytest.raises(ValueError, match="missing required inputs"):await app.astep(inputs={})@@ -1009,13 +1022,15 @@ async def test_app_astep_broken(caplog):"""Tests that we can run a step in an app"""broken_action = base_broken_action_async.with_name("broken_action_unique_name")app = Application(- actions=[broken_action],- transitions=[Transition(broken_action, broken_action, default)],state=State({}),- initial_step="broken_action_unique_name",+ entrypoint="broken_action_unique_name",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[broken_action],+ transitions=[Transition(broken_action, broken_action, default)],+ ),)with caplog.at_level(logging.ERROR): # it should say the name, that's the only contract for nowwith pytest.raises(BrokenStepException):@@ -1027,13 +1042,15 @@ async def test_app_astep_done():"""Tests that when we cannot run a step, we return None"""counter_action = base_counter_action_async.with_name("counter_async")app = Application(- actions=[counter_action],- transitions=[],state=State({}),- initial_step="counter_async",+ entrypoint="counter_async",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[],+ ),)await app.astep()assert await app.astep() is None@@ -1043,13 +1060,15 @@ async def test_app_astep_done():def test_app_many_steps():counter_action = base_counter_action.with_name("counter")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)action, result = None, Nonefor i in range(100):@@ -1061,13 +1080,15 @@ def test_app_many_steps():async def test_app_many_a_steps():counter_action = base_counter_action_async.with_name("counter_async")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State({}),- initial_step="counter_async",+ entrypoint="counter_async",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)action, result = None, Nonefor i in range(100):@@ -1080,16 +1101,18 @@ def test_iterate():result_action = Result("count").with_name("result")counter_action = base_counter_action.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)res = []gen = app.iterate(halt_after=["result"])@@ -1118,16 +1141,18 @@ def test_iterate_with_inputs():result_action = Result("count").with_name("result")counter_action = base_counter_action_with_inputs.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 2")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 2")),+ Transition(counter_action, result_action, default),+ ],+ ),)gen = app.iterate(halt_after=["result"], inputs={"additional_increment": 10}@@ -1145,16 +1170,18 @@ async def test_aiterate():result_action = Result("count").with_name("result")counter_action = base_counter_action_async.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)gen = app.aiterate(halt_after=["result"])assert app.sequence_id == 0@@ -1175,16 +1202,18 @@ async def test_aiterate_halt_before():result_action = Result("count").with_name("result")counter_action = base_counter_action_async.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)gen = app.aiterate(halt_before=["result"])counter = 0@@ -1203,16 +1232,18 @@ async def test_app_aiterate_with_inputs():result_action = Result("count").with_name("result")counter_action = base_counter_action_with_inputs_async.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)gen = app.aiterate(halt_after=["result"], inputs={"additional_increment": 10})async for action_, result, state in gen:@@ -1226,16 +1257,18 @@ def test_run():result_action = Result("count").with_name("result")counter_action = base_counter_action.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)action, result, state = app.run(halt_after=["result"])assert state["count"] == 10@@ -1246,16 +1279,18 @@ def test_run_halt_before():result_action = Result("count").with_name("result")counter_action = base_counter_action.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)action, result, state = app.run(halt_before=["result"])assert state["count"] == 10@@ -1267,16 +1302,18 @@ def test_run_with_inputs():result_action = Result("count").with_name("result")counter_action = base_counter_action_with_inputs.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)action_, result, state = app.run(halt_after=["result"], inputs={"additional_increment": 10})assert action_.name == "result"@@ -1289,18 +1326,20 @@ def test_run_with_inputs_multiple_actions():counter_action1 = base_counter_action_with_inputs.with_name("counter1")counter_action2 = base_counter_action_with_inputs.with_name("counter2")app = Application(- actions=[counter_action1, counter_action2, result_action],- transitions=[- Transition(counter_action1, counter_action1, Condition.expr("count < 10")),- Transition(counter_action1, counter_action2, Condition.expr("count >= 10")),- Transition(counter_action2, counter_action2, Condition.expr("count < 20")),- Transition(counter_action2, result_action, default),- ],state=State({}),- initial_step="counter1",+ entrypoint="counter1",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action1, counter_action2, result_action],+ transitions=[+ Transition(counter_action1, counter_action1, Condition.expr("count < 10")),+ Transition(counter_action1, counter_action2, Condition.expr("count >= 10")),+ Transition(counter_action2, counter_action2, Condition.expr("count < 20")),+ Transition(counter_action2, result_action, default),+ ],+ ),)action_, result, state = app.run(halt_after=["result"], inputs={"additional_increment": 8})assert action_.name == "result"@@ -1312,16 +1351,18 @@ async def test_arun():result_action = Result("count").with_name("result")counter_action = base_counter_action_async.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)action_, result, state = await app.arun(halt_after=["result"])assert state["count"] == result["count"] == 10@@ -1332,16 +1373,18 @@ async def test_arun_halt_before():result_action = Result("count").with_name("result")counter_action = base_counter_action_async.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)action_, result, state = await app.arun(halt_before=["result"])assert state["count"] == 10@@ -1353,16 +1396,18 @@ async def test_arun_with_inputs():result_action = Result("count").with_name("result")counter_action = base_counter_action_with_inputs_async.with_name("counter")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, counter_action, Condition.expr("count < 10")),- Transition(counter_action, result_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, counter_action, Condition.expr("count < 10")),+ Transition(counter_action, result_action, default),+ ],+ ),)action_, result, state = await app.arun(halt_after=["result"], inputs={"additional_increment": 10}@@ -1376,18 +1421,20 @@ async def test_arun_with_inputs_multiple_actions():counter_action1 = base_counter_action_with_inputs_async.with_name("counter1")counter_action2 = base_counter_action_with_inputs_async.with_name("counter2")app = Application(- actions=[counter_action1, counter_action2, result_action],- transitions=[- Transition(counter_action1, counter_action1, Condition.expr("count < 10")),- Transition(counter_action1, counter_action2, Condition.expr("count >= 10")),- Transition(counter_action2, counter_action2, Condition.expr("count < 20")),- Transition(counter_action2, result_action, default),- ],state=State({}),- initial_step="counter1",+ entrypoint="counter1",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action1, counter_action2, result_action],+ transitions=[+ Transition(counter_action1, counter_action1, Condition.expr("count < 10")),+ Transition(counter_action1, counter_action2, Condition.expr("count >= 10")),+ Transition(counter_action2, counter_action2, Condition.expr("count < 20")),+ Transition(counter_action2, result_action, default),+ ],+ ),)action_, result, state = await app.arun(halt_after=["result"], inputs={"additional_increment": 8}@@ -1402,17 +1449,19 @@ async def test_app_a_run_async_and_sync():counter_action_sync = base_counter_action_async.with_name("counter_sync")counter_action_async = base_counter_action_async.with_name("counter_async")app = Application(- actions=[counter_action_sync, counter_action_async, result_action],- transitions=[- Transition(counter_action_sync, counter_action_async, Condition.expr("count < 20")),- Transition(counter_action_async, counter_action_sync, default),- Transition(counter_action_sync, result_action, default),- ],state=State({}),- initial_step="counter_sync",+ entrypoint="counter_sync",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action_sync, counter_action_async, result_action],+ transitions=[+ Transition(counter_action_sync, counter_action_async, Condition.expr("count < 20")),+ Transition(counter_action_async, counter_action_sync, default),+ Transition(counter_action_sync, result_action, default),+ ],+ ),)action_, result, state = await app.arun(halt_after=["result"])assert state["count"] > 20@@ -1424,15 +1473,17 @@ def test_stream_result_halt_after_unique_ordered_sequence_id():counter_action = base_streaming_counter.with_name("counter")counter_action_2 = base_streaming_counter.with_name("counter_2")app = Application(- actions=[counter_action, counter_action_2],- transitions=[- Transition(counter_action, counter_action_2, default),- ],state=State({"count": 0}),- initial_step="counter",+ entrypoint="counter",adapter_set=LifecycleAdapterSet(action_tracker),partition_key="test",uid="test-123",+ graph=Graph(+ actions=[counter_action, counter_action_2],+ transitions=[+ Transition(counter_action, counter_action_2, default),+ ],+ ),)action_, streaming_container = app.stream_result(halt_after=["counter_2"])results = list(streaming_container)@@ -1459,15 +1510,17 @@ async def test_astream_result_halt_after_unique_ordered_sequence_id():counter_action = base_streaming_counter_async.with_name("counter")counter_action_2 = base_streaming_counter_async.with_name("counter_2")app = Application(- actions=[counter_action, counter_action_2],- transitions=[- Transition(counter_action, counter_action_2, default),- ],state=State({"count": 0}),- initial_step="counter",+ entrypoint="counter",adapter_set=LifecycleAdapterSet(action_tracker),partition_key="test",uid="test-123",+ graph=Graph(+ actions=[counter_action, counter_action_2],+ transitions=[+ Transition(counter_action, counter_action_2, default),+ ],+ ),)action_, streaming_async_container = await app.astream_result(halt_after=["counter_2"])results = [@@ -1499,15 +1552,17 @@ def test_stream_result_halt_after_run_through_streaming():counter_action = base_streaming_single_step_counter.with_name("counter")counter_action_2 = base_streaming_single_step_counter.with_name("counter_2")app = Application(- actions=[counter_action, counter_action_2],- transitions=[- Transition(counter_action, counter_action_2, default),- ],state=State({"count": 0}),- initial_step="counter",+ entrypoint="counter",adapter_set=LifecycleAdapterSet(action_tracker),partition_key="test",uid="test-123",+ graph=Graph(+ actions=[counter_action, counter_action_2],+ transitions=[+ Transition(counter_action, counter_action_2, default),+ ],+ ),)action_, streaming_container = app.stream_result(halt_after=["counter_2"])results = list(streaming_container)@@ -1536,15 +1591,17 @@ async def test_astream_result_halt_after_run_through_streaming():assert counter_action.is_async()assert counter_action_2.is_async()app = Application(- actions=[counter_action, counter_action_2],- transitions=[- Transition(counter_action, counter_action_2, default),- ],state=State({"count": 0}),- initial_step="counter",+ entrypoint="counter",adapter_set=LifecycleAdapterSet(action_tracker),partition_key="test",uid="test-123",+ graph=Graph(+ actions=[counter_action, counter_action_2],+ transitions=[+ Transition(counter_action, counter_action_2, default),+ ],+ ),)action_, streaming_container = await app.astream_result(halt_after=["counter_2"])results = [@@ -1576,16 +1633,18 @@ def test_stream_result_halt_after_run_through_non_streaming():counter_streaming = base_streaming_single_step_counter.with_name("counter_streaming")app = Application(- actions=[counter_non_streaming, counter_streaming],- transitions=[- Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),- Transition(counter_non_streaming, counter_streaming, default),- ],state=State({"count": 0}),- initial_step="counter_non_streaming",+ entrypoint="counter_non_streaming",adapter_set=LifecycleAdapterSet(action_tracker),partition_key="test",uid="test-123",+ graph=Graph(+ actions=[counter_non_streaming, counter_streaming],+ transitions=[+ Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),+ Transition(counter_non_streaming, counter_streaming, default),+ ],+ ),)action_, streaming_container = app.stream_result(halt_after=["counter_streaming"])results = list(streaming_container)@@ -1616,16 +1675,18 @@ async def test_astream_result_halt_after_run_through_non_streaming():counter_streaming = base_streaming_single_step_counter_async.with_name("counter_streaming")app = Application(- actions=[counter_non_streaming, counter_streaming],- transitions=[- Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),- Transition(counter_non_streaming, counter_streaming, default),- ],state=State({"count": 0}),- initial_step="counter_non_streaming",+ entrypoint="counter_non_streaming",adapter_set=LifecycleAdapterSet(action_tracker),partition_key="test",uid="test-123",+ graph=Graph(+ actions=[counter_non_streaming, counter_streaming],+ transitions=[+ Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),+ Transition(counter_non_streaming, counter_streaming, default),+ ],+ ),)action_, async_streaming_container = await app.astream_result(halt_after=["counter_streaming"])results = [@@ -1659,16 +1720,18 @@ def test_stream_result_halt_after_run_through_final_non_streaming():counter_final_non_streaming = base_counter_action.with_name("counter_final_non_streaming")app = Application(- actions=[counter_non_streaming, counter_final_non_streaming],- transitions=[- Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),- Transition(counter_non_streaming, counter_final_non_streaming, default),- ],state=State({"count": 0}),- initial_step="counter_non_streaming",+ entrypoint="counter_non_streaming",adapter_set=LifecycleAdapterSet(action_tracker),partition_key="test",uid="test-123",+ graph=Graph(+ actions=[counter_non_streaming, counter_final_non_streaming],+ transitions=[+ Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),+ Transition(counter_non_streaming, counter_final_non_streaming, default),+ ],+ ),)action, streaming_container = app.stream_result(halt_after=["counter_final_non_streaming"])results = list(streaming_container)@@ -1700,16 +1763,18 @@ async def test_astream_result_halt_after_run_through_final_streaming():counter_final_non_streaming = base_counter_action_async.with_name("counter_final_non_streaming")app = Application(- actions=[counter_non_streaming, counter_final_non_streaming],- transitions=[- Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),- Transition(counter_non_streaming, counter_final_non_streaming, default),- ],state=State({"count": 0}),- initial_step="counter_non_streaming",+ entrypoint="counter_non_streaming",adapter_set=LifecycleAdapterSet(action_tracker),partition_key="test",uid="test-123",+ graph=Graph(+ actions=[counter_non_streaming, counter_final_non_streaming],+ transitions=[+ Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),+ Transition(counter_non_streaming, counter_final_non_streaming, default),+ ],+ ),)action, streaming_container = await app.astream_result(halt_after=["counter_final_non_streaming"]@@ -1744,16 +1809,18 @@ def test_stream_result_halt_before():counter_streaming = base_streaming_single_step_counter.with_name("counter_final")app = Application(- actions=[counter_non_streaming, counter_streaming],- transitions=[- Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),- Transition(counter_non_streaming, counter_streaming, default),- ],state=State({"count": 0}),- initial_step="counter_non_streaming",+ entrypoint="counter_non_streaming",partition_key="test",uid="test-123",adapter_set=LifecycleAdapterSet(action_tracker),+ graph=Graph(+ actions=[counter_non_streaming, counter_streaming],+ transitions=[+ Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),+ Transition(counter_non_streaming, counter_streaming, default),+ ],+ ),)action, streaming_container = app.stream_result(halt_after=[], halt_before=["counter_final"])results = list(streaming_container)@@ -1776,16 +1843,18 @@ async def test_astream_result_halt_before():counter_streaming = base_streaming_single_step_counter_async.with_name("counter_final")app = Application(- actions=[counter_non_streaming, counter_streaming],- transitions=[- Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),- Transition(counter_non_streaming, counter_streaming, default),- ],state=State({"count": 0}),- initial_step="counter_non_streaming",+ entrypoint="counter_non_streaming",partition_key="test",uid="test-123",adapter_set=LifecycleAdapterSet(action_tracker),+ graph=Graph(+ actions=[counter_non_streaming, counter_streaming],+ transitions=[+ Transition(counter_non_streaming, counter_non_streaming, expr("count < 10")),+ Transition(counter_non_streaming, counter_streaming, default),+ ],+ ),)action, streaming_container = await app.astream_result(halt_after=[], halt_before=["counter_final"]@@ -1809,13 +1878,15 @@ async def test_astream_result_halt_before():def test_app_set_state():counter_action = base_counter_action.with_name("counter")app = Application(- actions=[counter_action],- transitions=[Transition(counter_action, counter_action, default)],state=State(),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[Transition(counter_action, counter_action, default)],+ ),)assert "counter" not in app.state # initial valueapp.step()@@ -1830,17 +1901,19 @@ def test_app_get_next_step():counter_action_2 = base_counter_action.with_name("counter_2")counter_action_3 = base_counter_action.with_name("counter_3")app = Application(- actions=[counter_action_1, counter_action_2, counter_action_3],- transitions=[- Transition(counter_action_1, counter_action_2, default),- Transition(counter_action_2, counter_action_3, default),- Transition(counter_action_3, counter_action_1, default),- ],state=State(),- initial_step="counter_1",+ entrypoint="counter_1",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action_1, counter_action_2, counter_action_3],+ transitions=[+ Transition(counter_action_1, counter_action_2, default),+ Transition(counter_action_2, counter_action_3, default),+ Transition(counter_action_3, counter_action_1, default),+ ],+ ),)# uninitialized -- counter_1assert app.get_next_action().name == "counter_1"@@ -1866,41 +1939,12 @@ def test_application_builder_complete():.with_entrypoint("counter").build())- assert len(app._actions) == 2- assert len(app._transitions) == 2+ graph = app.graph+ assert len(graph.actions) == 2+ assert len(graph.transitions) == 2assert app.get_next_action().name == "counter"-def test__validate_transitions_correct():- _validate_transitions(- [("counter", "counter", Condition.expr("count < 10")), ("counter", "result", default)],- {"counter", "result"},- )---def test__validate_transitions_missing_action():- with pytest.raises(ValueError, match="not found"):- _validate_transitions(- [- ("counter", "counter", Condition.expr("count < 10")),- ("counter", "result", default),- ],- {"counter"},- )---def test__validate_transitions_redundant_transition():- with pytest.raises(ValueError, match="redundant"):- _validate_transitions(- [- ("counter", "counter", Condition.expr("count < 10")),- ("counter", "result", default),- ("counter", "counter", default), # this is unreachable as we already have a default- ],- {"counter", "result"},- )--def test__validate_start_valid():_validate_start("counter", {"counter", "result"})@@ -1910,15 +1954,6 @@ def test__validate_start_not_found():_validate_start("counter", {"result"})-def test__validate_actions_valid():- _validate_actions([Result("test")])---def test__validate_actions_empty():- with pytest.raises(ValueError, match="at least one"):- _validate_actions([])--def test__adjust_single_step_output_result_and_state():state = State({"count": 1})result = {"count": 1}@@ -1943,15 +1978,6 @@ def test__adjust_single_step_output_errors_incorrect_result_type():_adjust_single_step_output((state, result), "test_action")-def test__assert_set():- _assert_set("foo", "foo", "bar")---def test__assert_set_unset():- with pytest.raises(ValueError, match="foo"):- _assert_set(None, "foo", "bar")--def test_application_builder_unset():with pytest.raises(ValueError):ApplicationBuilder().build()@@ -1962,17 +1988,19 @@ def test_application_run_step_hooks_sync():counter_action = base_counter_action.with_name("counter")result_action = Result("count").with_name("result")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, result_action, Condition.expr("count >= 10")),- Transition(counter_action, counter_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",adapter_set=internal.LifecycleAdapterSet(tracker),partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, result_action, Condition.expr("count >= 10")),+ Transition(counter_action, counter_action, default),+ ],+ ),)app.run(halt_after=["result"])assert set(dict(tracker.pre_called).keys()) == {"counter", "result"}@@ -2007,17 +2035,19 @@ async def test_application_run_step_hooks_async():counter_action = base_counter_action.with_name("counter")result_action = Result("count").with_name("result")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, result_action, Condition.expr("count >= 10")),- Transition(counter_action, counter_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",adapter_set=internal.LifecycleAdapterSet(tracker),partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, result_action, Condition.expr("count >= 10")),+ Transition(counter_action, counter_action, default),+ ],+ ),)await app.arun(halt_after=["result"])assert set(dict(tracker.pre_called).keys()) == {"counter", "result"}@@ -2049,16 +2079,18 @@ async def test_application_run_step_runs_hooks():counter_action = base_counter_action.with_name("counter")app = Application(- actions=[counter_action],- transitions=[- Transition(counter_action, counter_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",adapter_set=internal.LifecycleAdapterSet(*hooks),partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action],+ transitions=[+ Transition(counter_action, counter_action, default),+ ],+ ),)await app.astep()assert len(hooks[0].pre_called) == 1@@ -2115,17 +2147,19 @@ def test_application_post_application_create_hook():counter_action = base_counter_action.with_name("counter")result_action = Result("count").with_name("result")Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, result_action, Condition.expr("count >= 10")),- Transition(counter_action, counter_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",adapter_set=internal.LifecycleAdapterSet(tracker),partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, result_action, Condition.expr("count >= 10")),+ Transition(counter_action, counter_action, default),+ ],+ ),)assert "state" in tracker.called_argsassert "application_graph" in tracker.called_args@@ -2136,16 +2170,18 @@ async def test_application_gives_graph():counter_action = base_counter_action.with_name("counter")result_action = Result("count").with_name("result")app = Application(- actions=[counter_action, result_action],- transitions=[- Transition(counter_action, result_action, Condition.expr("count >= 10")),- Transition(counter_action, counter_action, default),- ],state=State({}),- initial_step="counter",+ entrypoint="counter",partition_key="test",uid="test-123",sequence_id=0,+ graph=Graph(+ actions=[counter_action, result_action],+ transitions=[+ Transition(counter_action, result_action, Condition.expr("count >= 10")),+ Transition(counter_action, counter_action, default),+ ],+ ),)graph = app.graphassert len(graph.actions) == 2diff --git a/tests/core/test_graph.py b/tests/core/test_graph.pynew file mode 100644index 00000000..7fe6df56--- /dev/null+++ b/tests/core/test_graph.py@@ -0,0 +1,117 @@+from typing import Callable++import pytest++from burr.core import Action, Condition, Result, State, default+from burr.core.graph import GraphBuilder, _validate_actions, _validate_transitions+++# TODO -- share versions among tests, this is duplicated in test_application.py+class PassedInAction(Action):+ def __init__(+ self,+ reads: list[str],+ writes: list[str],+ fn: Callable[..., dict],+ update_fn: Callable[[dict, State], State],+ inputs: list[str],+ ):+ super(PassedInAction, self).__init__()+ self._reads = reads+ self._writes = writes+ self._fn = fn+ self._update_fn = update_fn+ self._inputs = inputs++ def run(self, state: State, **run_kwargs) -> dict:+ return self._fn(state, **run_kwargs)++ @property+ def inputs(self) -> list[str]:+ return self._inputs++ def update(self, result: dict, state: State) -> State:+ return self._update_fn(result, state)++ @property+ def reads(self) -> list[str]:+ return self._reads++ @property+ def writes(self) -> list[str]:+ return self._writes+++def test__validate_transitions_correct():+ _validate_transitions(+ [("counter", "counter", Condition.expr("count < 10")), ("counter", "result", default)],+ {"counter", "result"},+ )+++def test__validate_transitions_missing_action():+ with pytest.raises(ValueError, match="not found"):+ _validate_transitions(+ [+ ("counter", "counter", Condition.expr("count < 10")),+ ("counter", "result", default),+ ],+ {"counter"},+ )+++def test__validate_transitions_redundant_transition():+ with pytest.raises(ValueError, match="redundant"):+ _validate_transitions(+ [+ ("counter", "counter", Condition.expr("count < 10")),+ ("counter", "result", default),+ ("counter", "counter", default), # this is unreachable as we already have a default+ ],+ {"counter", "result"},+ )+++def test__validate_actions_valid():+ _validate_actions([Result("test")])+++def test__validate_actions_empty():+ with pytest.raises(ValueError, match="at least one"):+ _validate_actions([])+++base_counter_action = PassedInAction(+ reads=["count"],+ writes=["count"],+ fn=lambda state: {"count": state.get("count", 0) + 1},+ update_fn=lambda result, state: state.update(**result),+ inputs=[],+)+++def test_graph_builder_builds():+ graph = (+ GraphBuilder()+ .with_actions(counter=base_counter_action, result=Result("count"))+ .with_transitions(+ ("counter", "counter", Condition.expr("count < 10")), ("counter", "result")+ )+ .build()+ )+ assert len(graph.actions) == 2+ assert len(graph.transitions) == 2+++def test_graph_builder_get_next_node():+ graph = (+ GraphBuilder()+ .with_actions(counter=base_counter_action, result=Result("count"))+ .with_transitions(+ ("counter", "counter", Condition.expr("count < 10")), ("counter", "result")+ )+ .build()+ )+ assert len(graph.actions) == 2+ assert len(graph.transitions) == 2+ assert graph.get_next_node(None, State({"count": 0}), entrypoint="counter").name == "counter"diff --git a/tests/core/test_validation.py b/tests/core/test_validation.pynew file mode 100644index 00000000..21866be6--- /dev/null+++ b/tests/core/test_validation.py@@ -0,0 +1,12 @@+import pytest++from burr.core.validation import assert_set+++def test__assert_set():+ assert_set("foo", "foo", "bar")+++def test__assert_set_unset():+ with pytest.raises(ValueError, match="foo"):+ assert_set(None, "foo", "bar")