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.

Updates documentation for persistence

elijahbenizzy276e40963e69
diff --git a/docs/concepts/state-persistence.rst b/docs/concepts/state-persistence.rst
index 75a5b419..3e7d7e68 100644
--- a/docs/concepts/state-persistence.rst
+++ b/docs/concepts/state-persistence.rst
@@ -4,21 +4,89 @@ State Persistence
.. _state-persistence:
-Key to writing a real life `burr` application is state persistence. E.g. you're building a chat bot and you
-want to store the conversation history and then reload it when you restart. Or, you have a long running process,
-or series of agents, and you want to store the state of the process after each action, and then reload it if it fails, etc.
+The key to writing a real life ``burr`` application is state persistence. For example, say you're building a chat bot and you
+want to store the conversation history and then reload it when you restart. Or, you have a long running process/series of agents,
+and you want to store the state of the process after each action, and then reload it if it fails, etc....
-Here we'll walk through how to add state persistence to a `burr` application. The following walk through the relevant
-ApplicationBuilder() methods, and then a full toy example.
+``Burr`` provides a few simple interfaces to do this with minimal changes. Let's walk through a simple chatbot example as we're explaining concepts:
-.initialize_from() method
-_________________________
-TODO:
+State Keys
+----------
+Burr `applications` are, by defult, keyed on two entities:
-.with_persister() method
-________________________
-TODO:
+1. ``app_uid`` - A unique identifier for the application. This is used to identify the application in the persistence layer.
+2. ``partition_key`` - An identifier for grouping (partitioning) applications
+
+In the case of a chatbot, the ``app_uid`` could be a uuid, and the ``partition_key`` could be the user's name.
+Note that ``partition_key`` can be `None` if this is not relevant. A UUID is always generated for the ``app_uid`` if not provided.
+
+Initializing state
+------------------
+
+To initialize state from a database, you can employ the :py:meth:`initialize_from <burr.core.application.ApplicationBuilder.initialize_from>` method
+in the :py:class:`ApplicationBuilder <burr.core.application.ApplicationBuilder>`.
+
+This action takes in an initializer (an implementation of :py:class:`StateInitializer <burr.core.persistence.BaseStateLoader>`) a well as:
+
+- ``resume_at_next_action`` -- a boolean that says whether to start where you left off, or go back to the ``default_entrypoint``.
+- ``default_entrypoint`` -- the entry point to start at if ``resume_at_next_action`` is False, or no state is found
+- ``default_state`` -- the default state to use if no state is found
+
+Note that you cannot use this in conjunction with :py:meth:`with_state <burr.core.application.ApplicationBuilder.with_state>`
+or :py:meth:`with_entrypoint <burr.core.application.ApplicationBuilder.with_entrypoint>` -- these are mutually exclusive.
+Either you load from state or you start from scratch.
+
+Writing state
+_____________
+
+To write state to a database, you can use the :py:meth:`with_state_persister <burr.core.application.ApplicationBuilder.with_state_persister>` method in the
+:py:class:`ApplicationBuilder <burr.core.application.ApplicationBuilder>`. This takes in a persister (an implementation of
+:py:class:`StatePersister <burr.core.persistence.BaseStatePersister>`). It writes state to the database after each action.
+
+
+An example
+__________
+
+To make the above more concrete, let's look at a basic chatbot:
+
+.. code-block:: python
+
+ state_persister = SQLLitePersister(db_path=".sqllite.db", table_name="table")
+ app = (
+ ApplicationBuilder()
+ .with_actions(
+ ai_converse=ai_converse,
+ human_converse=human_converse,
+ terminal=burr.core.Result("chat_history"),
+ )
+ .with_transitions(
+ ("ai_converse", "human_converse", default),
+ ("human_converse", "terminal", expr("'exit' in question")),
+ ("human_converse", "ai_converse", default),
+ )
+ .initialize(
+ initializer=state_persister,
+ resume_at_next_action=True,
+ default_state={"chat_history" : []},
+ default_entrypoint="human_converse
+ )
+ .with_state_persister(state_persister)
+ .with_identifiers(app_id=app_id)
+ .build()
+ )
+
+In this case, we both read and write using the ``SQLLitePersistor``. Note that this is the most common case.
+However, if you want to just read (E.G. for debugging), or you want to just write (if you're always creating a new app),
+you can leave out ``initialize`` or ``with_state_persister`` respectively.
Supported Persistence Backends
______________________________
-TODO:
+We currently have only implemented the :py:class:`SQLLitePersister <burr.core.persistence.SQLLitePersister>` for state persistence.
+Note that the tracker also allows reloading from a file, but this is not recommended for production use.
+
+
+Customizing State Persistence
+-----------------------------
+
+Burr exposes the :py:class:`BaseStatePersister <burr.core.persistence.BaseStatePersister>` API for custom state persistence. Implement,
+pass into the above functions, and you can write to whatever database you want! Please contribute back to the community if you do so.
diff --git a/docs/examples/ml_training.rst b/docs/examples/ml_training.rst
index ed3b3fe3..d6621f66 100644
--- a/docs/examples/ml_training.rst
+++ b/docs/examples/ml_training.rst
@@ -2,9 +2,9 @@
ML Model Training
====================
-Hyperparameter Optimization is a key part of training machine learning models. For more sophisticated examples that
-aren't grid search, `burr` is a quick and easy way to implement hyperparameter optimization. You want to keep
-track of hyperparameters and metrics, feeding these into a decision function to determine where to look next,
-and `burr` can help you write and manage that process.
+Hyperparameter Optimization is a key part of training machine learning models. For use-cases ranging from grid-search
+to gaussian processes, `burr` is a simple way to implement robust, failure-resistant hyperparameter optimization. This involves keeping
+track of hyperparameters and metrics and feeding these into a decision function to determine where to look next.
+``burr``'s state machine can help you write and manage that process.
This is still a WIP -- come back soon, or `contribute your own example <https://github.com/DAGWorks-Inc/burr/issues/new>`_!
diff --git a/docs/main.rst b/docs/main.rst
index 57c0ac94..2ee12ff9 100644
--- a/docs/main.rst
+++ b/docs/main.rst
@@ -4,8 +4,6 @@ Burr
Welcome to Burr's documentation, the state machine for managing complex data/LLM projects.
-TODO: VIDEO.
-
You'll find this documentation separated into three sections.
- If you don't know where to start, go to :ref:`getting started <gettingstarted>`.
diff --git a/docs/reference/persister.rst b/docs/reference/persister.rst
index e7723daa..887bf057 100644
--- a/docs/reference/persister.rst
+++ b/docs/reference/persister.rst
@@ -2,20 +2,43 @@
State Persistence
=================
-This is an interface one should implement to provide state persistence for your
-application.
+Burr provides a set of tools to make loading and saving state easy. These are functions
+that will be used by lifecycle hooks to save and load state.
-.. autoclass:: burr.core.state.BasicStatePersistence
+If you want to implement your own state persister (to bridge it with a database), you should implement
+the ``BaseStatePersister`` interface.
+
+.. autoclass:: burr.core.persistence.BaseStatePersister
:members:
+ :show-inheritance:
+ :inherited-members:
.. automethod:: __init__
+Internally, this interface combines the following two interfaces:
+
+.. autoclass:: burr.core.persistence.BaseStateLoader
+ :members:
+
+ .. automethod:: __init__
+
+.. autoclass:: burr.core.persistence.BaseStateSaver
+ :members:
+ :show-inheritance:
+ :inherited-members:
+
+ .. automethod:: __init__
+
Supported Implementations
=========================
+Currently we support the following, although we highly recommend you contribute your own! We will be adding more shortly.
-.. autoclass:: burr.core.state.SQLLitePersistence
+.. autoclass:: burr.core.persistence.SQLLitePersister
:members:
.. automethod:: __init__
+
+Note that the :py:class:`LocalTrackingClient <burr.tracking.client.LocalTrackingClient>` leverages the :py:class:`BaseStateLoader <burr.core.persistence.BaseStateLoader>` to allow loading state,
+although it uses different mechanisms to save state (as it tracks more than just state).