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
Documentation Updates
elijahbenizzy29121ec3b4b6
diff --git a/README.md b/README.mdindex be2e5b01..f31feb28 100644--- a/README.md+++ b/README.md@@ -5,7 +5,7 @@Burr is a state machine for data/AI projects. You can (and should!) use it for anything where managing state can be hard. Hint: managing stateis always hard!-You can find the documentation [here](https://studious-spork-n8kznlw.pages.github.io/).+Link to [documentation](https://studious-spork-n8kznlw.pages.github.io/).## What can you do with Burr?diff --git a/docs/concepts/actions.rst b/docs/concepts/actions.rstindex 164cee04..7a52723e 100644--- a/docs/concepts/actions.rst+++ b/docs/concepts/actions.rst@@ -11,21 +11,23 @@ asynchronous context (and thus require one of the async application functions).Actions have two primary responsibilities:-1. Compute a result from the state-2. Update the state with the result+1. ``run`` -- compute a result+2. ``update`` -- modify the state-We call (1) a ``Function`` and (2) a ``Reducer`` (similar to Redux). The ``run`` method is the function and the ``update``-method is the reducer. The `run` method should return a dictionary of the result and the ``update`` method should return+The ``run`` method should return a dictionary of the result and the ``update`` method should returnthe 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.+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).-In the case of a function-based action, the function returns both at the same time.+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+- use the class-based API when you want to leverage inheritance or parameterize the action in more powerful ways-------------------Class-based actions--------------------You can define an action by implementing the `Action` class:+You can define an action by implementing the ``Action`` class:.. code-block:: python@@ -90,6 +92,8 @@ 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.+Note that these combine the `reduce` and `run` methods into a single function, and they're both returned at the same time.+----------------------Results----------------------diff --git a/docs/concepts/hooks.rst b/docs/concepts/hooks.rstindex 5f47ed96..a670eb2b 100644--- a/docs/concepts/hooks.rst+++ b/docs/concepts/hooks.rst@@ -4,8 +4,8 @@ Hooks.. _hooks:-Burr has a system of lifecycle adapters (adapted from [Hamilton's](https://github.com/dagworks-inc/hamilton) similar concept, which allow you to run tooling before and after-various places in a node's execution. For instance, you could (many of these are yet to be implemented):+Burr has a system of lifecycle adapters (adapted from the similar `Hamilton <https://github.com/dagworks-inc/hamilton>`_ concept), which allow you to run tooling before and after+various places in a node's execution. For instance, you could:1. Log every step as a trace in datadog2. Add a time-delay to your steps to allow for rendering@@ -13,6 +13,8 @@ various places in a node's execution. For instance, you could (many of these are4. Synchronize state/updates to an external database5. Put results on a queue to feed to some monitoring system+Note some of the above are yet to be implemented.+To implement hooks, you subclass any number of the :ref:`available lifecycle hooks <hooksref>`.These have synchronous and asynchronous versions, and your hook can subclass as many as you want(as long as it doesn't do both the synchronous and asynchronous versions of the same hook).diff --git a/docs/concepts/state-machine.rst b/docs/concepts/state-machine.rstindex 7a506911..a34cc324 100644--- a/docs/concepts/state-machine.rst+++ b/docs/concepts/state-machine.rst@@ -41,6 +41,7 @@ There are three APIs for executing an application.------------------Returns the tuple of the action, the result of that action, and the new state. Call this if you want to run the application step-by-step.+.. code-block:: pythonaction, result, state = application.step()diff --git a/docs/concepts/state.rst b/docs/concepts/state.rstindex 4ef6fc0d..1490a59b 100644--- a/docs/concepts/state.rst+++ b/docs/concepts/state.rst@@ -20,7 +20,7 @@ interface, but there are a few extra:.. code-block:: pythonstate.subset(["foo", "bar"]) # return a new state with only the keys "foo" and "bar"- state.get_all() # return a dictionary of all the state+ state.get_all() # return a dictionary with every key/value of the stateWhen an update action is run, the state is first subsetted to get just the keys that are being read from,then the action is run, and a new state is written to. This state is merged back into the original statediff --git a/docs/concepts/transitions.rst b/docs/concepts/transitions.rstindex 90980df3..a207d78f 100644--- a/docs/concepts/transitions.rst+++ b/docs/concepts/transitions.rst@@ -4,7 +4,8 @@ Transitions.. _transitions:-Transitions move between actions. You can think of them as edges in a graph.+Transitions define explicitly how actions are connected and which action is available next for any given state.+You can think of them as edges in a graph.They have three main components:- The ``from`` state@@ -32,4 +33,4 @@ when determining which action to run next.Note that if no condition evaluates to ``True``, the application execution will stop early.-See the :ref: `transitions docs <transitionref>` for more information on the transition API.+See the :ref:`transition docs <transitionref>` for more information on the transition API.diff --git a/docs/getting_started/install.rst b/docs/getting_started/install.rstindex 0d32cd08..547afc82 100644--- a/docs/getting_started/install.rst+++ b/docs/getting_started/install.rst@@ -2,8 +2,7 @@Installing==========-Burr requires almost no dependencies. Every "extra"/"plugin" is an additional install target. Note, if you're using ``zsh``,-you'll need to add quotes around the install target, like `pip install "burr[graphviz]"`.+Burr requires almost no dependencies. Every "extra"/"plugin" is an additional install target... code-block:: bash@@ -22,3 +21,5 @@ And to visualize your state machines on streamlit, you can install the `burr[strpip install burr[streamlit]Don't worry, you can always install these extras later if you need them.++Note, if you're using ``zsh``, you'll need to add quotes around the install target, like `pip install "burr[graphviz]"`.diff --git a/docs/getting_started/why-burr.rst b/docs/getting_started/why-burr.rstindex 3a16ddec..be48ae7c 100644--- a/docs/getting_started/why-burr.rst+++ b/docs/getting_started/why-burr.rst@@ -11,15 +11,15 @@ Why do you need a state machine for your applications? Won't the normal programmYes, until a point. Let's look at a chatbot as an example. Here's a simple design of something gpt-like:#. Accept a prompt from the user-#. Does some simple checks/validations on that prompt (is it safe/within the terms of service)-#. If (2) it then decides the mode to which to respond to that prompt from a set of capabilities. Else respond accordingly:+#. Perform some simple checks/validations on that prompt (is it safe/within the terms of service)+#. If (2) then decide the mode to which to respond to that prompt from a set of capabilities. Else responds accordingly:* Generate an image* Answer a question* Write some code* ...-#. It then queries the appropriate model with the prompt, formatted as expected-#. If this fails, we present an error message-#. If this succeeds, we present the response to the user+#. Query the appropriate model with the prompt, formatted as expected+ * On failure, present an error message+ * On success, present the response to the user#. Await a new prompt, GOTO (1)Visually, we might have an implementation/spec that looks like this:@@ -29,7 +29,9 @@ Visually, we might have an implementation/spec that looks like this:While this involves multiple API calls, error-handling, etc... it is definitely possible to get a prototype-that looks slick out without too much abstraction. Let's get this to production, however. We need to:+that looks slick out without too much abstraction.++Now, let's get this to production. We need to:#. Add monitoring to figure out if/why any of our API calls return strange results#. Understand the decisions made by the application -- E.G. why it chose certain modes, why it formatted a response correctly. This involves:diff --git a/docs/reference/conditions.rst b/docs/reference/conditions.rstindex 56bed0f3..2f8b797f 100644--- a/docs/reference/conditions.rst+++ b/docs/reference/conditions.rst@@ -2,7 +2,7 @@Conditions/Transitions=======================-.. transitionref:+.. _transitionref:Conditions represent choices to move between actions -- these are read by the application builder when executing the graph.Note that these will always be specified in order -- the first condition that evaluates to ``True`` will be the selected action.