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.

Adds documentation for user-specified inputs

elijahbenizzy5fac793f4426
diff --git a/docs/concepts/actions.rst b/docs/concepts/actions.rst
index 7a52723e..aa6100a3 100644
--- a/docs/concepts/actions.rst
+++ b/docs/concepts/actions.rst
@@ -5,7 +5,7 @@ Actions
.. _actions:
-Actions do any heavy-lifting in a workflow. They should contain all complex compute. You can define actions
+Actions do the heavy-lifting in a workflow. They should contain all complex compute. You can define actions
either through a class-based or function-based API. If actions implement `async def run` then will be run in an
asynchronous context (and thus require one of the async application functions).
@@ -18,6 +18,17 @@ The ``run`` method should return a dictionary of the result and the ``update`` m
the updated state. 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).
+.. _inputref:
+
+--------------
+Runtime inputs
+--------------
+
+Actions can declare inputs that are not part of the state. This is for the case that you want to pause workflow execution for human input.
+
+For instance, say you have a chatbot. The first step will declare the ``input`` parameter ``prompt`` -- it will take that, process it, and put
+it in the state. The subsequent steps will read the result of that from state.
+
There are two APIs for defining actions: class-based and function-based. They are largely equivalent, but differ in use.
- use the function-based API when you want to write something quick and terse that reads from a fixed set of state variables
@@ -58,6 +69,33 @@ You then pass the action to the ``ApplicationBuilder``:
custom_action=CustomAction()
)...
+
+Note that if the action has inputs, you have to define the optional `inputs` property:
+
+.. code-block:: python
+
+ from burr.core import Action, State
+
+ class CustomAction(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["var_from_state"]
+
+ def run(self, state: State, increment_by: int) -> dict:
+ return {"var_to_update": state["var_from_state"] + increment_by}
+
+ @property
+ def writes(self) -> list[str]:
+ return ["var_to_update"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.update(**result)
+
+ @property
+ def inputs(self) -> list[str]:
+ return ["increment_by"]
+
+
----------------------
Function-based actions
----------------------
@@ -90,20 +128,51 @@ Function-based actions can take in parameters which are akin to passing in const
custom_action=custom_action.bind(increment_by=2)
)...
-This is the same as ``functools.partial``, but it is more explicit and easier to read.
+This is the same as ``functools.partial``, but it is more explicit and easier to read. If an action has parameters that are not
+bound, they will be referred to as inputs. For example:
-Note that these combine the `reduce` and `run` methods into a single function, and they're both returned at the same time.
-----------------------
-Results
-----------------------
+.. 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)
+
+ app = ApplicationBuilder().with_actions(
+ custom_action=custom_action
+ )...
+
+Will require the inputs to be passed in at runtime.
+
+Note that these combine the ``reduce`` and ``run`` methods into a single function, and they're both returned at the same time.
+
+-----------
+``Inputs``
+-----------
+
+If you simply want a node to take in inputs and pass them to the state, you can use the `Input` action:
+
+.. code-block:: python
+
+ app = ApplicationBuilder().with_actions(
+ get_input=Input("var_from_state")
+ )...
+
+This will look for the `var_from_state` in the inputs and pass it to the state. Note this is just syntactic sugar
+for declaring inputs through one of the other APIs and adding it to state -- if you want to do anything more complex
+with the input, you should use other APIs.
+
+-----------
+``Results``
+-----------
If you just want to fill a result from the state, you can use the `Result` action:
.. code-block:: python
app = ApplicationBuilder().with_actions(
- get_result=Result(["var_from_state"])
+ get_result=Result("var_from_state")
)...
diff --git a/docs/concepts/state-machine.rst b/docs/concepts/state-machine.rst
index 1bcc5000..ca836092 100644
--- a/docs/concepts/state-machine.rst
+++ b/docs/concepts/state-machine.rst
@@ -52,6 +52,15 @@ If you're in an async context, you can run `astep` instead:
action, result, state = await application.astep()
+
+Step can also take in ``inputs`` as a dictionary, which will be passed to the action's run function as keyword arguments.
+This is specifically meant for a "human in the loop" scenario, where the action needs to ask for input from a user. In this case,
+the control flow is meant to be interrupted to allow for the user to provide input. See :ref:`inputs <inputref>` for more information.
+
+.. code-block:: python
+
+ action, result, state = application.step(inputs={"prompt": input()})
+
``iterate``/``aiterate``
------------------------
@@ -80,17 +89,32 @@ 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).
+.. 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.
+
+
``run``/``arun``
----------------
Run just calls out to ``iterate`` and returns the final state.
+The ``until`` variable is a ``or`` gate (E.G. ``any_complete``), although we will be adding an ``and`` gate (E.G. ``all_complete``),
+and the ability to run until the state machine naturally executes (``until=None``).
+
.. code-block:: python
final_state, results = application.run(until=["final_action_1", "final_action_2"])
-Currently the ``until`` variable is a ``or`` gate (E.G. ``any_complete``), although we will be adding an ``and`` gate (E.G. ``all_complete``),
-and the ability to run until the state machine naturally executes (``until=None``).
+
+In the async context, you can run ``arun``:
+
+.. code-block:: python
+
+ final_state = await application.arun(until=["final_action_1", "final_action_2"])
+
+.. 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.
----------
Inspection
diff --git a/docs/reference/actions.rst b/docs/reference/actions.rst
index 0e0f9bb6..2ca668e5 100644
--- a/docs/reference/actions.rst
+++ b/docs/reference/actions.rst
@@ -16,6 +16,12 @@ Actions
.. automethod:: __init__
+
+.. autoclass:: burr.core.action.Input
+ :members:
+
+ .. automethod:: __init__
+
.. autodecorator:: burr.core.action.action
.. autofunction:: burr.core.action.bind