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 persistence
elijahbenizzy276e40963e69
diff --git a/docs/concepts/state-persistence.rst b/docs/concepts/state-persistence.rstindex 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.rstindex 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.rstindex 57c0ac94..2ee12ff9 100644--- a/docs/main.rst+++ b/docs/main.rst@@ -4,8 +4,6 @@ BurrWelcome 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.rstindex 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).