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 overview to concepts + cleans up docs
elijahbenizzye4ee286f5238
diff --git a/docs/concepts/actions.rst b/docs/concepts/actions.rstindex 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`` preturn ["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 tupleof (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.rstindex 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+ overviewactionsstatestate-machinediff --git a/docs/concepts/overview.rst b/docs/concepts/overview.rstindex 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.rstindex 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 ereturn state.update(**result)diff --git a/docs/concepts/recursion.rst b/docs/concepts/recursion.rstindex 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 once3. 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 synthesizeAnd 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 ImprovementsWe 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 above2. Static visualization of the recursive application when using (1)3. A more ergonomic way to pass through the trackerdiff --git a/docs/concepts/state.rst b/docs/concepts/state.rstindex 9da634fc..a710af71 100644--- a/docs/concepts/state.rst+++ b/docs/concepts/state.rst@@ -9,7 +9,7 @@ StateBurr'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.