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 overview to concepts + cleans up docs

elijahbenizzye4ee286f5238
diff --git a/docs/concepts/actions.rst b/docs/concepts/actions.rst
index fcd4a483..f43b47f2 100644
--- a/docs/concepts/actions.rst
+++ b/docs/concepts/actions.rst
@@ -35,7 +35,7 @@ Function-based actions
----------------------
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:
+can return either just the updated state or a tuple of the result and the state. For example:
.. code-block:: python
@@ -170,7 +170,7 @@ Note that if the action has inputs, you have to define the optional ``inputs`` p
return ["increment_by"]
-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
+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
@@ -182,41 +182,9 @@ of (required, optional) inputs. For example:
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.
+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
------------------------
-
-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`` only actions
-------------------------
-
-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")
- )...
-
-
-This simply grabs the value from the state and returns it as the result. It is purely a placeholder
-for an action that should just use the result, although you do not need it.
-
-Refer to :ref:`actions <actions>` for documentation.
+Refer to :ref:`actions <actions>` for more documentation.
.. _inputref:
diff --git a/docs/concepts/index.rst b/docs/concepts/index.rst
index a054e884..d5f76c6d 100644
--- a/docs/concepts/index.rst
+++ b/docs/concepts/index.rst
@@ -9,6 +9,7 @@ Overview of the concepts -- read these to get a mental model for how Burr works.
.. toctree::
:maxdepth: 2
+ overview
actions
state
state-machine
diff --git a/docs/concepts/overview.rst b/docs/concepts/overview.rst
index e69de29b..de587899 100644
--- a/docs/concepts/overview.rst
+++ b/docs/concepts/overview.rst
@@ -0,0 +1,14 @@
+===========
+Cheat Sheet
+===========
+
+This is a quick overview of Burr's design -- the concepts are explored in more detail in the following sections. Read over this for a very high-level overview, or use this as a cheat sheet later.
+
+- With Burr you write an :ref:`Application <applications>` -- this manages control flow (allowing for automated or user-blocking workflows), :ref:`persistence <state-persistence>` to DBs, logs :ref:`telemetry <tracking>`, and delegates to a variety of plugins/integrations.
+- Applications are composed of :ref:`actions <actions>` (functions that write to/read from state), and :ref:`transitions <transitions>` (functions that determine the next action to execute based on state).
+- :ref:`State <state>` is immutable and uses the special Burr :py:class:`State <burr.core.state.State>` API. You write to it by applying a state operation (e.g. ``state = state.update(key=value)``, which returns a new state instance with the updated value.
+- All other production/debugging concerns are implemented as :ref:`hooks <hooks>`, which are simple callbacks that are called at various points in the application lifecycle (store/retrieve state, log information, etc...).
+
+Note that we did not mention LLMs above at all! That's good -- you want your LLM frameworks to be ever-so-slightly decoupled from them for the best experience (all of AI is just software, plain and simple, after all...).
+
+And that's the basics! Let's dive into the details.
diff --git a/docs/concepts/planned-capabilities.rst b/docs/concepts/planned-capabilities.rst
index 5afdee5f..e0de7b6b 100644
--- a/docs/concepts/planned-capabilities.rst
+++ b/docs/concepts/planned-capabilities.rst
@@ -86,7 +86,7 @@ Here is what it would look liek in the current API:
result = {"output": None, "attempts": state["attempts"] + 1}
try:
result["output"] = call_some_api(...)
- excecpt APIException as e:
+ except APIException as e:
if state["attempts"] >= max_retries:
raise e
return state.update(**result)
diff --git a/docs/concepts/recursion.rst b/docs/concepts/recursion.rst
index dd0c3390..16422923 100644
--- a/docs/concepts/recursion.rst
+++ b/docs/concepts/recursion.rst
@@ -9,9 +9,9 @@ but we are actively working on building first-level constructs that allow this.
This can enable the following use-cases (among many others):
1. Parallel results to different LLMs for comparison
-2. Multi simultaneous tasks/chains for an LLM
+2. Multiple simultaneous tasks/chains for an LLM to answer at once
3. Black-boxing an action as a subset of tasks
-4. Running multiple queries simultaneously and getting an LLM to synthesize.
+4. Running multiple queries simultaneously and getting an LLM to synthesize
And so on. These can be arbitrarily complex and nested, allowing agents consisting of agents consisting of agents...
@@ -103,6 +103,9 @@ Note the following:
For persistence, you'll want to use (3) to ensure a stable hash -- have the sub-application load its own state from the ID, resuming where it left off.
+We currently don't wire through persisters, although we are planning to add that shortly. For the meanwhile, you'll want to leverage the right persister
+yourself.
+
When you track in the UI, you will see the following (in this example we're generating poems of different styles in parallel):
.. image:: ../_static/recursive_steps.png
@@ -114,7 +117,7 @@ Future Improvements
We are working on the following:
-1. A recursive application to allow for more ergonomic management of the above
+1. A first class way to define a recursive application application to allow for more ergonomic management of the above
2. Static visualization of the recursive application when using (1)
3. A more ergonomic way to pass through the tracker
diff --git a/docs/concepts/state.rst b/docs/concepts/state.rst
index 9da634fc..a710af71 100644
--- a/docs/concepts/state.rst
+++ b/docs/concepts/state.rst
@@ -9,7 +9,7 @@ State
Burr's ``State`` API enables actions to talk to each other, and enables you to persist data.
Burr has a ``State`` API that allows you to manipulate state in a functional way.
-The ``State`` class provides the ability to manipulate state for a given action. It is entirely immutable,
+The :py:class:`State <burr.core.state.State>` class provides the ability to manipulate state for a given action. It is entirely immutable,
meaning that you can only create new states from old ones, not modify them in place.