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
Updates documentation for optional arguments
elijahbenizzycc1bae2f9161
diff --git a/burr/core/action.py b/burr/core/action.pyindex 7cbeff56..ed6755e3 100644--- a/burr/core/action.py+++ b/burr/core/action.py@@ -48,13 +48,13 @@ class Function(abc.ABC):@propertydef inputs(self) -> Union[list[str], tuple[list[str], list[str]]]:"""Represents inputs that are used for this to run.- These correspond to the `**function_kwargs` in `run` above.+ These correspond to the ``**run_kwargs`` in `run` above.Note that this has two possible return values:1. A list of strings -- these are the keys that are required to run the function2. A tuple of two lists of strings -- the first list is the required keys, the second is the optional keys- :return:+ :return: Either a list of strings (required inputs) or a tuple of two lists of strings (required and optional inputs)"""return []@@ -406,11 +406,11 @@ class FunctionBasedAction(SingleStepAction):ACTION_FUNCTION = "action_function"def __init__(- self,- fn: Callable,- reads: List[str],- writes: List[str],- bound_params: dict = None,+ self,+ fn: Callable,+ reads: List[str],+ writes: List[str],+ bound_params: dict = None,):"""Instantiates a function-based action with the given function, reads, and writes.The function must take in a state and return a tuple of (result, new_state).@@ -550,11 +550,11 @@ class StreamingResultContainer(Iterator[dict]):return next(self.generator())def __init__(- self,- streaming_result_generator: Generator[dict, None, Tuple[dict, State]],- initial_state: State,- process_result: Callable[[dict, State], Tuple[dict, State]],- callback: Callable[[Optional[dict], State, Optional[Exception]], None],+ self,+ streaming_result_generator: Generator[dict, None, Tuple[dict, State]],+ initial_state: State,+ process_result: Callable[[dict, State], Tuple[dict, State]],+ callback: Callable[[Optional[dict], State, Optional[Exception]], None],):"""Initializes a ``StreamingResultContainer``. This is meant to be used internally@@ -613,7 +613,7 @@ class SingleStepStreamingAction(SingleStepAction, abc.ABC):@abc.abstractmethoddef stream_run_and_update(- self, state: State, **run_kwargs+ self, state: State, **run_kwargs) -> Generator[dict, None, Tuple[dict, State]]:"""Streaming version of the run and update function. Thisreturn type is a generator that streams in a result, has no "send"@@ -642,11 +642,11 @@ class FunctionBasedStreamingAction(SingleStepStreamingAction):_fn: Callable[..., Generator[dict, None, Tuple[dict, State]]]def __init__(- self,- fn: Callable[..., Generator[dict, None, Tuple[dict, State]]],- reads: List[str],- writes: List[str],- bound_params: dict = None,+ self,+ fn: Callable[..., Generator[dict, None, Tuple[dict, State]]],+ reads: List[str],+ writes: List[str],+ bound_params: dict = None,):"""Instantiates a function-based streaming action with the given function, reads, and writes.The function must take in a state (and inputs) and return a generator of (result, new_state).@@ -662,7 +662,7 @@ class FunctionBasedStreamingAction(SingleStepStreamingAction):self._bound_params = bound_params if bound_params is not None else {}def stream_run_and_update(- self, state: State, **run_kwargs+ self, state: State, **run_kwargs) -> Generator[dict, None, Tuple[dict, State]]:return (yield from self._fn(state, **self._bound_params, **run_kwargs))@@ -765,9 +765,8 @@ def action(reads: List[str], writes: List[str]) -> Callable[[Callable], Functionall cases.If parameters are not bound, they will be interpreted as inputs and must- be passed in at runtime. If they have default values, they will *not* be- interpreted as inputs (all inputs are required to be present). They can- still be bound, however.+ be passed in at runtime. If they have default values, they will be recorded+ as optional inputs. These can (optionally) be provided at runtime.:param reads: Items to read from the state:param writes: Items to write to the state@@ -783,7 +782,7 @@ def action(reads: List[str], writes: List[str]) -> Callable[[Callable], Functiondef streaming_action(- reads: List[str], writes: List[str]+ reads: List[str], writes: List[str]) -> Callable[[Callable], FunctionRepresentingAction]:"""Decorator to create a streaming function-based action. This is user-facing.diff --git a/docs/concepts/actions.rst b/docs/concepts/actions.rstindex 0f74b1d6..15d4fc57 100644--- a/docs/concepts/actions.rst+++ b/docs/concepts/actions.rst@@ -48,6 +48,9 @@ You can also define actions by decorating a function with the :py:func:`@actioncustom_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@@ -64,7 +67,6 @@ Function-based actions can take in parameters which are akin to passing in constThis is the same as ``functools.partial``, but it is more explicit and easier to read. If an action has parameters that are notbound, they will be referred to as inputs. For example:-.. code-block:: python@action(reads=["var_from_state"], writes=["var_to_update"])@@ -76,10 +78,20 @@ bound, they will be referred to as inputs. For example:custom_action=custom_action)...-Will require the inputs to be passed in at runtime. See below for how to do that.+Will require the inputs to be passed in at runtime. See below for how to do that. You can use default values to set optional inputs as well:-Note that these combine the ``update`` and ``run`` methods into a single function, and they're both executed at the same time.+.. code-block:: python++ @action(reads=["var_from_state"], writes=["var_to_update"])+ def custom_action(state: State, increment_by: int = 1) -> 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+ )...+This means that the application does not *need* the inputs to be set.-------------------Class-Based Actions@@ -143,7 +155,19 @@ Note that if the action has inputs, you have to define the optional ``inputs`` preturn ["increment_by"]-See below for how to pass in inputs at runtime.+See below for how to pass in inputs at runtime. If you want to use optional inputs with the class-based API, `inputs` will return a tuple+of (required, optional) inputs. For example:++.. code-block:: python++ from burr.core import Action, State++ class CustomAction(Action):+ ...+ def inputs(self) -> Tuple[list[str], list[str]]:+ return ["increment_by"], ["optional_input"]++Note your code will have to handle the case where `optional_input` is not passed in (e.g. by setting the appropriate kwargs to the `run(...)` method.-----------------------``Inputs`` only actions