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
Cleans up logic for halting/return values
elijahbenizzyd31cfadcd5e5
diff --git a/README.md b/README.mdindex 3948df6e..c0bbe6c5 100644--- a/README.md+++ b/README.md@@ -38,7 +38,7 @@ built Burr as a _harness_ to handle state between executions of Hamilton DAGs,but realized that it has a wide array of applications and decided to release it.# Getting Started-+``To get started, install from `pypi`, using your favorite package manager:```bashdiff --git a/burr/core/application.py b/burr/core/application.pyindex da82f76e..89bb529a 100644--- a/burr/core/application.py+++ b/burr/core/application.py@@ -300,6 +300,78 @@ class Application:self._set_state(new_state)return next_action, result, new_state+ def _clean_iterate_params(+ self,+ halt_before: list[str] = None,+ halt_after: list[str] = None,+ inputs: Optional[Dict[str, Any]] = None,+ ) -> Tuple[list[str], list[str], Dict[str, Any]]:+ """Utility function to clean out iterate params so we have less duplication between iterate/aiterate+ and the logic is cleaner later.+ """+ if halt_before is None and halt_after is None:+ logger.warning(+ "No halt termination specified -- this has the possibility of running forever!"+ )+ if halt_before is None:+ halt_before = []+ if halt_after is None:+ halt_after = []+ if inputs is None:+ inputs = {}+ return halt_before, halt_after, inputs++ def has_next_action(self) -> bool:+ """Returns whether or not there is a next action to run.++ :return: True if there is a next action, False otherwise+ """+ return self.get_next_action() is not None++ def _should_halt_iterate(+ self, halt_before: list[str], halt_after: list[str], prior_action: Action+ ) -> bool:+ """Internal utility function to determine whether or not to halt during iteration"""+ if self.has_next_action() and self.get_next_action().name in halt_before:+ logger.debug(f"Halting before executing {self.get_next_action().name}")+ return True+ elif prior_action.name in halt_after:+ logger.debug(f"Halting after executing {prior_action.name}")+ return True+ return False++ def _return_value_iterate(+ self,+ halt_before: list[str],+ halt_after: list[str],+ prior_action: Optional[Action],+ result: Optional[dict],+ ) -> Tuple[Action, Optional[dict], State]:+ """Utility function to decide what to return for iterate/arun. Note that run() will delegate to the return value of+ iterate, whereas arun cannot delegate to the return value of aiterate (as async generators cannot return a value).+ We put the code centrally to clean up the logic.+ """+ if self.has_next_action() and self.get_next_action().name in halt_before:+ logger.debug(+ f"We have hit halt_before condition with next action: {self.get_next_action().name}. "+ f"Returning: next_action={self.get_next_action()}, None, and state"+ )+ return self.get_next_action(), None, self._state+ if prior_action is not None and prior_action.name in halt_after:+ prior_action_name = prior_action.name if prior_action is not None else None+ logger.debug(+ f"We have hit halt_after condition with prior action: {prior_action_name}. "+ f"Returning: prior_action={prior_action}, result, and state"+ )+ logger.warning(+ "We have it an undefined condition -- do not rely on this behavior. "+ "This is trying to return without having computed a single action -- "+ "we'll end up just returning some Nones. This means that nothing was executed "+ "(E.G. that the state machine had nowhere to go). Either fix the state machine or"+ f"the halt conditions, or both... Halt conditions are: halt_before={halt_before}, halt_after={halt_after}."+ )+ return prior_action, result, self._state+def iterate(self,*,@@ -311,40 +383,30 @@ class Application:of the system as it updates. Note this returns a generator, and also the final result(for convenience).- :param halt_before: The list of actions to halt before execution of. It will halt on the first one.- :param halt_after: The list of actions to halt after execution of. It will halt on the first one.+ Note the nuance with halt_before and halt_after. halt_before conditions will take precedence to halt_after. Furthermore,+ a single iteration will always be executed prior to testing for any halting conditions.++ :param halt_before: The list of actions to halt before execution of. It will halt prior to the execution of the first one it sees.+ :param halt_after: The list of actions to halt after execution of. It will halt after the execution of the first one it sees.:param inputs: Inputs to the action -- this is if this action requires an input that is passed in from the outside world.Note that this is only used for the first iteration -- subsequent iterations will not use this.- :return: Each iteration returns the result of running `step`- The final result is the action, result, current state,+ :return: Each iteration returns the result of running `step`. This generator also returns a tuple of+ [action, result, current state]"""- if not halt_before and not halt_after:- logger.warning("No halt termination specified -- running forever!")- if inputs is None:- inputs = {}+ halt_before, halt_after, inputs = self._clean_iterate_params(+ halt_before, halt_after, inputs+ )+result = None- action: Optional[Action] = None- while True:- state_output = self.step(inputs=inputs)+ prior_action: Optional[Action] = None+ while self.has_next_action():+ # self.step will only return None if there is no next action, so we can rely on tuple unpacking+ prior_action, result, state = self.step(inputs=inputs)inputs = {} # only pass inputs in the first time- if state_output is None:- break- action, result, state = state_output- yield action, result, state- if (- halt_before- and self.get_next_action()- and self.get_next_action().name in halt_before- ):- break- elif halt_after and action and action.name in halt_after:+ yield prior_action, result, state+ if self._should_halt_iterate(halt_before, halt_after, prior_action):break-- if action and halt_after and action.name in halt_after:- return action, result, self._state- elif self.get_next_action() and halt_before and self.get_next_action().name in halt_before:- return self.get_next_action(), None, self._state- return action, result, self._state+ return self._return_value_iterate(halt_before, halt_after, prior_action, result)async def aiterate(self,@@ -360,32 +422,19 @@ class Application::param halt_after: The list of actions to halt after execution of. It will halt on the first one.:param inputs: Inputs to the action -- this is if this action requires an input that is passed in from the outside world.Note that this is only used for the first iteration -- subsequent iterations will not use this.- :return: Each iteration returns the result of running `step`- The final result is the action, result, current state,+ :return: Each iteration returns the result of running `step`. This returns nothing -- it's an async generator which is not+ allowed to have a return value."""- if not halt_before and not halt_after:- logger.warning("No halt termination specified -- running forever!")- if inputs is None:- inputs = {}+ halt_before, halt_after, inputs = self._clean_iterate_params(+ halt_before, halt_after, inputs+ )- while True:- step_result = await self.astep(inputs=inputs)+ while self.has_next_action():+ # self.step will only return None if there is no next action, so we can rely on tuple unpacking+ prior_action, result, state = await self.astep(inputs=inputs)inputs = {} # only pass inputs in the first time- if step_result is None:- break- action, result, state = step_result- yield action, result, state- if (- halt_before- and self.get_next_action()- and self.get_next_action().name in halt_before- ):- yield self.get_next_action(), None, self._state- # we don't need to go around the loop again.- break- elif halt_after and action and action.name in halt_after:- # we've already yielded where we want to stop- # and we don't want to yield the same thing twice -- and there's no return in async generators+ yield prior_action, result, state+ if self._should_halt_iterate(halt_before, halt_after, prior_action):breakdef run(@@ -398,9 +447,10 @@ class Application:"""Runs your application through until completion. Doesnot give access to the state along the way -- if you want that, use iterate().- :param until: The list of actions to run until -- these must be strings- :param inputs: Inputs to the action -- this is if this action requires an input that is passed in from the outside world- :param gate: Gate to run until -- only accepts "any_complete" for now+ :param halt_before: The list of actions to halt before execution of. It will halt on the first one.+ :param halt_after: The list of actions to halt after execution of. It will halt on the first one.+ :param inputs: Inputs to the action -- this is if this action requires an input that is passed in from the outside world.+ Note that this is only used for the first iteration -- subsequent iterations will not use this.:return: The final state, and the results of running the actions in the order that they were specified."""gen = self.iterate(halt_before=halt_before, halt_after=halt_after, inputs=inputs)@@ -425,14 +475,13 @@ class Application::param inputs: Inputs to the action -- this is if this action requires an input that is passed in from the outside world:return: The final state, and the results of running the actions in the order that they were specified."""- state = self._state- action = None+ prior_action = Noneresult = None- async for action, result, state in self.aiterate(+ async for prior_action, result, state in self.aiterate(halt_before=halt_before, halt_after=halt_after, inputs=inputs):pass- return action, result, state+ return self._return_value_iterate(halt_before, halt_after, prior_action, result)def visualize(self,diff --git a/docs/concepts/state-machine.rst b/docs/concepts/state-machine.rstindex a7484d60..4101dcd0 100644--- a/docs/concepts/state-machine.rst+++ b/docs/concepts/state-machine.rst@@ -77,23 +77,32 @@ You can also run ``aiterate`` in an async context:async for action, result, state in application.aiterate():print(action.name, result)+In the synchronous context this also has a return value of a tuple of:-1. the action that was specified in `halt_after` or `halt_before`. In the `after` case the action will have already run.-In the `before` case the action will not have run.-2. The result of the action, in the `halt_after` case, else None in the `halt_before` case.-3. The state of the application at the time of halting.+++#. the action that was specified in ``halt_after`` or ``halt_before``. In the `after` case the action will have already run. In the ``before`` case the action will not have run.++#. The result of that action, in the ``halt_after`` case, else None in the ``halt_before`` case.++#. The state of the application at the time of halting.You can access this by looking at the ``value`` variable of the ``StopIteration`` exception that is thrown-at the end of the loop, as is standard for python.+at the end of the loop, as is standard for python generators.See the function implementation of ``run`` to show how this is done.-In the async context, this does not return anything-(asynchronous generators are not allowed a return value).+In the async context, this does not return anything (asynchronous generators are not allowed a return value).++If you want it to (attempt to) run forever, you can pass empty lists to ``halt_after`` and ``halt_before``... note::You can add inputs to ``iterate``/``aiterate`` by passing in a dictionary of inputs through the ``inputs`` parameter.This will only apply to the first action. Actions that are not the first but require inputs are considered undefined behavior.+.. warning::+ The state machine has the capability of halting even if it does not reach one of the specified conditions -- if there are+ no more transitions to take. This, however, is not a supported feature (and will log a warning). This is considered undefined behavior+ -- use at your own risk, and consider adding a halting condition, or a default transition to a terminal.``run``/``arun``----------------@@ -118,6 +127,8 @@ In the async context, you can run ``arun``:.. note::You can add inputs to ``run``/``arun`` in the same way as you can with ``iterate`` -- it will only apply to the first action.+``run`` and ``arun`` largely have the same behavior as ``iterate`` and ``aiterate``.+----------Inspection----------diff --git a/tests/core/test_application.py b/tests/core/test_application.pyindex d13a81dc..32b764c2 100644--- a/tests/core/test_application.py+++ b/tests/core/test_application.py@@ -621,6 +621,7 @@ def test_run_with_inputs():initial_step="counter",)action, result, state = app.run(halt_after=["result"], inputs={"additional_increment": 10})+ assert action.name == "result"assert state["counter"] == result["counter"] == 11@@ -638,6 +639,7 @@ async def test_arun():)action, result, state = await app.arun(halt_after=["result"])assert state["counter"] == result["counter"] == 10+ assert action.name == "result"async def test_arun_halt_before():@@ -674,6 +676,7 @@ async def test_arun_with_inputs():halt_after=["result"], inputs={"additional_increment": 10})assert state["counter"] == result["counter"] == 11+ assert action.name == "result"async def test_app_a_run_async_and_sync():