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
Adds documentation for user-specified inputs
elijahbenizzy5fac793f4426
diff --git a/docs/concepts/actions.rst b/docs/concepts/actions.rstindex 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 actionseither through a class-based or function-based API. If actions implement `async def run` then will be run in anasynchronous 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`` mthe updated state. 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).+.. _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 constcustom_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:: pythonapp = 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.rstindex 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:: pythonfinal_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.----------Inspectiondiff --git a/docs/reference/actions.rst b/docs/reference/actions.rstindex 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