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
Allows actions to output just "State" rather than a tuple
elijahbenizzyc19cf061597b
diff --git a/burr/core/application.py b/burr/core/application.pyindex dd5ef4f4..62f33557 100644--- a/burr/core/application.py+++ b/burr/core/application.py@@ -77,6 +77,19 @@ def _validate_result(result: dict, name: str) -> None:)+def _adjust_single_step_output(output: Union[State, Tuple[dict, State]]):+ """Adjusts the output of a single step action to be a tuple of (result, state)"""+ if isinstance(output, tuple):+ return output+ if isinstance(output, State):+ return {}, output+ raise ValueError(+ ERROR_MESSAGE+ + "Single step action must return either *just* the state update or a tuple of (result, state). "+ f"Got: {output} of type {type(output)} instead."+ )++def _run_function(function: Function, state: State, inputs: Dict[str, Any], name: str) -> dict:"""Runs a function, returning the result of running the function.Note this restricts the keys in the state to only those that the@@ -223,7 +236,7 @@ def _run_single_step_action("""# TODO -- guard all reads/writes with a subset of the stateaction.validate_inputs(inputs)- result, new_state = action.run_and_update(state, **inputs)+ result, new_state = _adjust_single_step_output(action.run_and_update(state, **inputs))_validate_result(result, action.name)out = result, _state_update(state, new_state)_validate_result(result, action.name)@@ -345,7 +358,9 @@ async def _arun_single_step_action("""Runs a single step action in async. See the synchronous version for more details."""state_to_use = stateaction.validate_inputs(inputs)- result, new_state = await action.run_and_update(state_to_use, **inputs)+ result, new_state = _adjust_single_step_output(+ await action.run_and_update(state_to_use, **inputs)+ )_validate_result(result, action.name)_validate_reducer_writes(action, new_state, action.name)return result, _state_update(state, new_state)diff --git a/docs/concepts/actions.rst b/docs/concepts/actions.rstindex 15d4fc57..fcd4a483 100644--- a/docs/concepts/actions.rst+++ b/docs/concepts/actions.rst@@ -21,7 +21,8 @@ Actions have two primary responsibilities:2. ``update`` -- modify the stateThe ``run`` method should return a dictionary of the result and the ``update`` method should return-the updated state. They declare their dependencies so the framework knows *which* state variables they read and write. This allows the+the updated state, given the results of the ``run`` method.+They declare their dependencies so the framework knows *which* state variables they read and write. This allows theframework to optimize the execution of the workflow. We call (1) a ``Function`` and (2) a ``Reducer`` (similar to `Redux <https://redux.js.org/>`_, if you're familiar with frontend UI technology).There are two APIs for defining actions: class-based and function-based. They are largely equivalent, but differ in use.@@ -33,32 +34,47 @@ There are two APIs for defining actions: class-based and function-based. They arFunction-based actions-----------------------You can also define actions by decorating a function with the :py:func:`@action <burr.core.action.action>` decorator:+You can define actions by decorating a function with the :py:func:`@action <burr.core.action.action>` decorator. These+can return either just the state or a tuple of the result and the state. For example:.. code-block:: pythonfrom burr.core import action, State@action(reads=["var_from_state"], writes=["var_to_update"])- def custom_action(state: State) -> Tuple[dict, State]:- result = {"var_to_update": state["var_from_state"] + 1}- return result, state.update(**result)+ def custom_action(state: State) -> State:+ return state.update(var_to_update=state["var_from_state"] + 1)++ app = ApplicationBuilder().with_actions(+ custom_action=custom_action+ )...+++Conceptually, these combine the ``update`` and ``run`` methods into a single function, and they're both executed at the same time.+You also have the option of returning the intermediate results, which is useful for tracking/debugging. The code+above is equivalent to returning an empty dictionary instead of the results.++.. code-block:: python++ from burr.core import action, State++ @action(reads=["var_from_state"], writes=["var_to_update"])+ def custom_action(state: State) -> State+ return results, state.update(var_to_update=var_from_state + 1)app = ApplicationBuilder().with_actions(custom_action=custom_action)...-Note that these combine the ``update`` and ``run`` methods into a single function, and they're both executed at the same time.Function-based actions can take in parameters which are akin to passing in constructor parameters. This is done through the :py:meth:`bind <burr.core.action.bind>` method:.. code-block:: python@action(reads=["var_from_state"], writes=["var_to_update"])- def custom_action(state: State, increment_by: int) -> Tuple[dict, State]:- result = {"var_to_update": state["var_from_state"] + increment_by}- return result, state.update(**result)+ def custom_action(state: State, increment_by: int) -> State:+ return state.update(var_to_update=state["var_from_state"] + increment_by)app = ApplicationBuilder().with_actions(custom_action=custom_action.bind(increment_by=2)@@ -70,9 +86,8 @@ bound, they will be referred to as inputs. For example:.. code-block:: python@action(reads=["var_from_state"], writes=["var_to_update"])- def custom_action(state: State, increment_by: int) -> Tuple[dict, State]:- result = {"var_to_update": state["var_from_state"] + increment_by}- return result, state.update(**result)+ def custom_action(state: State, increment_by: int) -> State:+ return state.update(var_to_update=state["var_from_state"] + increment_by)app = ApplicationBuilder().with_actions(custom_action=custom_action@@ -83,9 +98,9 @@ Will require the inputs to be passed in at runtime. See below for how to do that.. code-block:: python@action(reads=["var_from_state"], writes=["var_to_update"])- def custom_action(state: State, increment_by: int = 1) -> Tuple[dict, State]:+ def custom_action(state: State, increment_by: int = 1) -> State:result = {"var_to_update": state["var_from_state"] + increment_by}- return result, state.update(**result)+ return state.update(var_to_update=state["var_from_state"] + increment_by)app = ApplicationBuilder().with_actions(custom_action=custom_action@@ -220,11 +235,11 @@ For example using the function based API, consider the following action:.. code-block:: python@action(reads=["..."], writes=["..."])- def my_action(state: State, client: Client, prompt: str) -> Tuple[dict, State]:+ def my_action(state: State, client: Client, prompt: str) -> State:"""client & `prompt` here are something we need to pass in."""context = client.get_data(state["..."])result = llm_call(prompt, context) # some LLM call...- return result, state.update(**result)+ return state.update(**result)We need to pass in `client` and `prompt` somehow. Here are the ways to do that:diff --git a/docs/concepts/additional-visibility.rst b/docs/concepts/additional-visibility.rstindex 20f69488..90e3cedf 100644--- a/docs/concepts/additional-visibility.rst+++ b/docs/concepts/additional-visibility.rst@@ -27,14 +27,14 @@ For the function-based API, this would look as follows:from burr.core import action@action(reads=['input_var'], writes=['output_var'])- def my_action(state: State, __tracer: TracingFactory) -> Tuple[dict, State]:+ def my_action(state: State, __tracer: TracingFactory) -> State:with __tracer('process_data'):initial_data = _process_data(state['input_var'])with __tracer('validate_data'):_validate(initial_data)with __tracer('transform_data', dependencies=['process_data']):transformed_data = _transform(initial_data)- return {'output_var': transformed_data}, state.update({'output_var': transformed_data})+ return state.update({'output_var': transformed_data})This would create the following traces:@@ -77,7 +77,7 @@ For instance:state: State,__tracer: TracingFactory,__logger: ArtifactLogger- ) -> Tuple[dict, State]:+ ) -> State:with __tracer('process_data'):initial_data = _process_data(state['input_var'])with __tracer('validate_data'):@@ -87,7 +87,7 @@ For instance:transformed_data = _transform(initial_data)__logger.log_artifact(transformed_data_size=len(transformed_data))- return {'output_var': transformed_data}, state.update({'output_var': transformed_data})+ return state.update(output_var=transformed_data)The output can be any "json-dumpable" object (or pydantic model). This will be stored along with the span and can be used for debugging or analysis.diff --git a/docs/concepts/planned-capabilities.rst b/docs/concepts/planned-capabilities.rstindex 664c958d..5afdee5f 100644--- a/docs/concepts/planned-capabilities.rst+++ b/docs/concepts/planned-capabilities.rst@@ -31,9 +31,9 @@ against that state.qux: str@action(reads=["foo", "bar"], writes=["baz"])- def my_action(state: State[InputState]) -> Tuple[dict, State[OutputState]]:+ def my_action(state: State[InputState]) -> State[OutputState]:result = {"baz": state["foo"] + 1, "qux": state["bar"] + "!"}- return result, state.update(**result)+ return state.update(**result)The above could also be dataclasses/pydantic models. We could also add something as simple as:@@ -82,23 +82,23 @@ Here is what it would look liek in the current API:.. code-block:: python@action(reads=["attempts"], writes=["output", "attempts"])- def some_flaky_action(state: State, max_retries: int=3) -> Tuple[dict, State]:+ def some_flaky_action(state: State, max_retries: int=3) -> State:result = {"output": None, "attempts": state["attempts"] + 1}try:result["output"] = call_some_api(...)excecpt APIException as e:if state["attempts"] >= max_retries:raise e- return result, state.update(**result)+ return state.update(**result)One could imagine adding it as a condition (a few possibilities).. code-block:: python@action(reads=[], writes=["output"])- def some_flaky_action(state: State) -> Tuple[dict, State]:+ def some_flaky_action(state: State) -> Stateresult = {"output": call_some_api(...)}- return result, state.update(**result)+ return state.update(**result)builder.with_actions(some_flaky_action=some_flaky_actiondiff --git a/docs/concepts/recursion.rst b/docs/concepts/recursion.rstindex d15884e9..dd0c3390 100644--- a/docs/concepts/recursion.rst+++ b/docs/concepts/recursion.rst@@ -39,7 +39,7 @@ After creating a simple application (1)/(2) above, you can wire through the trac.. code-block:: python@action(reads=["parameters_to_map"], writes=["joined_results"])- def run_multiple_sub_apps(state: State, __context: ApplicationContext) -> Tuple[dict, State]:+ def run_multiple_sub_apps(state: State, __context: ApplicationContext) -> State:# for every parameter incoming, run a sub-applicationresults = []for parameter_set in state["parameters_to_map"]:@@ -61,7 +61,7 @@ After creating a simple application (1)/(2) above, you can wire through the tracjoined = _join(results)- return {"joined_results": joined}, state.update(joined_results=joined)+ return state.update(joined_results= _join(results))Note we're simply passing through the tracker to the next app, which sets a link between them.The tracker knows how to record the link so its in the UI.@@ -72,7 +72,7 @@ Parallel and delayed functions, but you can use whatever tooling you want (multi.. code-block:: python@action(reads=["parameters_to_map"], writes=["joined_results"])- def run_multiple_sub_apps(state: State, __context: ApplicationContext) -> Tuple[dict, State]:+ def run_multiple_sub_apps(state: State, __context: ApplicationContext) -> State:def run_subapp(parameter_set):subapp = (ApplicationBuilder()@@ -93,7 +93,7 @@ Parallel and delayed functions, but you can use whatever tooling you want (multiresults = Parallel(n_jobs=-1)(delayed(run_subapp)(parameter_set) for parameter_set in state["parameters_to_map"])joined = _join(results)- return {"joined_results": joined}, state.update(joined_results=joined)+ return state.update(joined_results=joined)Note the following:diff --git a/docs/getting_started/simple-example.rst b/docs/getting_started/simple-example.rstindex 905687c2..5ca96e55 100644--- a/docs/getting_started/simple-example.rst+++ b/docs/getting_started/simple-example.rst@@ -54,18 +54,16 @@ We define two actions:client = openai.Client()@action(reads=[], writes=["prompt", "chat_history"])- def human_input(state: State, prompt: str) -> Tuple[dict, State]:+ def human_input(state: State, prompt: str) -> State:chat_item = {"content": prompt,"role": "user"}- return (- {"prompt": prompt},- state.update(prompt=prompt).append(chat_history=chat_item)- )+ return state.update(prompt=prompt).append(chat_history=chat_item)+@action(reads=["chat_history"], writes=["response", "chat_history"])- def ai_response(state: State) -> Tuple[dict, State]:+ def ai_response(state: State) -> State:content = client.chat.completions.create(model="gpt-3.5-turbo",messages=state["chat_history"],@@ -74,18 +72,21 @@ We define two actions:"content": content,"role": "assistant"}- return (- {"response": content},- state.update(response=content).append(chat_history=chat_item)- )+ return state.update(response=content).append(chat_history=chat_item)+Before we proceed, let's note the following about how we define these actions:1. State is a dictionary -- actions declare input fields (as strings) and write values to those fields2. Actions use a specific *immutable* state object and call operations on it (``.append(...)``, ``.update(...)``)-3. Functions can do whatever you want -- they can use plain python, or delegate to `langchain <langchain.io>`_, `hamilton <https://github.com/dagworks-inc/hamilton>`_, etc...+3. Functions can do whatever you want -- they can use plain python, or delegate to `langchain <langchain.io>`_, `hamilton <https://github.com/dagworks-inc/hamilton>`_, etc... All they have to do is return the new state.4. We declare the parameter ``prompt``, meaning that we will expect the user to pass ``prompt`` every time they run the graph.+.. note::++ The action API has a few different forms. We've shown the simplest above, but it can also return a tuple of ``result, state`` (where ``result``+ the intermediate result of the computation), to help with debugging. There are also multiple class-based APIs. See the :ref:`actions <actions>` section for more details.+Next, let's piece together our application. To do this, we'll use an ``ApplicationBuilder``.. code-block:: python@@ -110,7 +111,7 @@ We can visualize the application (note you need ``burr[graphviz]`` installed):.. image:: ../_static/chatbot.png:align: center-Let's note the following about how we define the application+Let's note the following about how we define the application:1. It is an infinite loop! It is meant to pause for new prompt input.2. We're just using the function names as the action names. You can also name them if you want ``with_actions(human_input=human_input, ai_response=ai_response)``.@@ -143,27 +144,23 @@ If you want to copy/paste, you can open up the following code block and add to a.. code-block:: pythonimport uuid- from typing import Tupleimport openai- from burr.core import action, State, ApplicationBuilder, when, persistence+ from burr.core import action, State, ApplicationBuilderclient = openai.Client()@action(reads=[], writes=["prompt", "chat_history"])- def human_input(state: State, prompt: str) -> Tuple[dict, State]:+ def human_input(state: State, prompt: str) -> State:chat_item = {"content": prompt,"role": "user"}- return (- {"prompt": prompt},- state.update(prompt=prompt).append(chat_history=chat_item)- )+ return state.update(prompt=prompt).append(chat_history=chat_item)@action(reads=["chat_history"], writes=["response", "chat_history"])- def ai_response(state: State) -> Tuple[dict, State]:+ def ai_response(state: State) -> State:content = client.chat.completions.create(model="gpt-3.5-turbo",messages=state["chat_history"],@@ -172,10 +169,7 @@ If you want to copy/paste, you can open up the following code block and add to a"content": content,"role": "assistant"}- return (- {"response": content},- state.update(response=content).append(chat_history=chat_item)- )+ return state.update(response=content).append(chat_history=chat_item)app = (ApplicationBuilder().with_actions(human_input, ai_response)@@ -186,6 +180,7 @@ If you want to copy/paste, you can open up the following code block and add to a.with_entrypoint("human_input").build())+app.visualize("./graph", format="png")*_, state = app.run(halt_after=["ai_response"], inputs={"prompt": "Who was Aaron Burr?"})print("answer:", app.state["response"])