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
Improves persistence documentation
elijahbenizzyaeff00ea545e
diff --git a/docs/concepts/state-persistence.rst b/docs/concepts/state-persistence.rstindex 6aeea0a8..868776c0 100644--- a/docs/concepts/state-persistence.rst+++ b/docs/concepts/state-persistence.rst@@ -10,6 +10,15 @@ State Persistenceto save and load state automatically from a database. This enables you to launch an application,pause it, and restart where you left off. The API is customizable, and works with any database you want.+TL;DR+-----++Burr provides an API to save and load state from a database. This enables you to pause and restart applications where you left off.+You can implement a custom state persister or use one of the pre-built ones. You can fork state from a previous run to enable debugging/loading.+++Persisting State+----------------The key to writing a real life ``burr`` application is state persistence. For example, say you're building a chat bot and youwant to store the conversation history and then reload it when you restart. Or, you have a long running process/series of agents,@@ -19,7 +28,7 @@ and you want to store the state of the process after each action, and then reloaState Keys-----------Burr `applications` are, by defult, keyed on two entities:+Burr `applications` are, by default, keyed on two entities: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@@ -47,13 +56,15 @@ This action takes in an initializer (an implementation of :py:class:`StateInitiaNote (1): 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.+or :py:meth:`with_entrypoint <burr.core.application.ApplicationBuilder.with_entrypoint>` -- these are mutually exclusive. If you're+switching to use state persistence, all you need to do is remove the ``with_state`` and ``with_entrypoint`` calls and replace them with+the default state and entrypoint in the ``initialize_from`` call.Note (2): The loader will not error if no state is found, it will use the default state in this case.Forking State_____________-Here's an explicit section on forking state. When loading you can also fork state from a previous application. This is useful if you want to start from a previous application's state,+When loading you can also fork state from a previous application. This is useful if you want to start from a previous application's state,but don't want to add to it. The ``fork_from_app_id`` and ``fork_from_partition_key`` are used to identify the application to fork from, while``fork_from_sequence_id`` is used to identify the sequence_id to use. This is useful if you want to fork from a specific point in the application,rather than the latest state. This is especially useful for debugging, or building an application that enables you@@ -91,8 +102,8 @@ To make the above more concrete, let's look at a basic chatbot:("human_converse", "terminal", expr("'exit' in question")),("human_converse", "ai_converse", default),)- .initialize(- initializer=state_persister,+ .initialize_from(+ state_persister,resume_at_next_action=True,default_state={"chat_history" : []},default_entrypoint="human_converse@@ -106,6 +117,8 @@ In this case, we both read and write using the ``SQLLitePersistor``. Note that tHowever, 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______________________________See :ref:`available persisters here <persistersref>`.@@ -117,3 +130,39 @@ Customizing State PersistenceBurr 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.+++Loading from the Tracker+------------------------++You can use the tracking feature additionally as a persister. This enables you to load from prior+tracked runs. This is useful for debugging, or building an application that enables you to rewind state and make different choices.++.. code-block:: python++ tracker = LocalTrackingClient(project=project_name)+ 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_from(+ tracker,+ resume_at_next_action=True,+ default_state={"chat_history" : []},+ default_entrypoint="human_converse+ )+ .with_tracker(tracker)+ .with_identifiers(app_id=app_id)+ .build()+ )++In this case the ``LocalTrackingClient`` is used both as a persister and a loader. It will persist as it is+running (by tracking), and then load from the tracker if the application is restarted. This is useful for local development.