Skip to content

armgit / burr

Public Imported from GitHub
0

Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.

Allows actions to output just "State" rather than a tuple

elijahbenizzyc19cf061597b
diff --git a/burr/core/application.py b/burr/core/application.py
index 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 state
action.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 = state
action.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.rst
index 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 state
The ``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 the
framework 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 ar
Function-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:: python
from 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.rst
index 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.rst
index 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) -> State
result = {"output": call_some_api(...)}
- return result, state.update(**result)
+ return state.update(**result)
builder.with_actions(
some_flaky_action=some_flaky_action
diff --git a/docs/concepts/recursion.rst b/docs/concepts/recursion.rst
index 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-application
results = []
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 trac
joined = _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 (multi
results = 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.rst
index 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 fields
2. 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:: python
import uuid
- from typing import Tuple
import openai
- from burr.core import action, State, ApplicationBuilder, when, persistence
+ from burr.core import action, State, ApplicationBuilder
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"],
@@ -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"])