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 more documentation on state loading
Stefan Krawczyk20031645d67b
diff --git a/burr/core/application.py b/burr/core/application.pyindex da8ef31c..561df5bc 100644--- a/burr/core/application.py+++ b/burr/core/application.py@@ -1394,14 +1394,17 @@ class ApplicationBuilder:fork_from_sequence_id: int = None,) -> "ApplicationBuilder":"""Initializes the application we will build from some prior state object.- Note that you can *either* call this or use `with_state` and `with_entrypoint` -- this also assigns application ID,- partition key, and sequence ID.++ Note (1) that you can *either* call this or use `with_state` and `with_entrypoint`.++ Note (2) if you want to continue a prior application and don't want to fork it into a new application ID,+ the values in `.with_identifiers()` will be used to query for prior state.:param initializer: The persister object to use for initialization. Likely the same one called with ``with_state_persister``.:param resume_at_next_action: Whether to resume at the next action, or default to the ``default_entrypoint``:param default_state: The default state to use if it does not exist. This is a dictionary.:param default_entrypoint: The default entry point to use if it does not exist or you elect not to resume_at_next_action.- :param fork_from_app_id: The app ID to fork from. This is used to fork from a prior application run.+ :param fork_from_app_id: The app ID to fork from, not to be confused with the current app_id that is set with `.with_identifiers()`. This is used to fork from a prior application run.:param fork_from_partition_key: The partition key to fork from a prior application. Optional. `fork_from_app_id` required.:param fork_from_sequence_id: The sequence ID to fork from a prior application run. Optional, defaults to latest. `fork_from_app_id` required.:return: The application builder for future chaining.@@ -1415,7 +1418,8 @@ class ApplicationBuilder:if not fork_from_app_id and (fork_from_partition_key or fork_from_sequence_id):raise ValueError(ERROR_MESSAGE- + "If you set fork_from_partition_key or fork_from_sequence_id, you must also set fork_from_app_id."+ + "If you set fork_from_partition_key or fork_from_sequence_id, you must also set fork_from_app_id. "+ "See .initialize_from() documentation.")self.initializer = initializerself.resume_at_next_action = resume_at_next_action@@ -1487,7 +1491,6 @@ class ApplicationBuilder:# there was nothing to load -- use default stateself.state = self.state.update(**self.default_state)self.sequence_id = None # has to start at None- self.parent_id = Noneelse:if load_result["state"] is None:raise ValueError(diff --git a/docs/concepts/state-persistence.rst b/docs/concepts/state-persistence.rstindex 56faf568..6aeea0a8 100644--- a/docs/concepts/state-persistence.rst+++ b/docs/concepts/state-persistence.rst@@ -27,34 +27,41 @@ Burr `applications` are, by defult, keyed on two entities: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.+You set these values using the :py:meth:`with_identifiers() <burr.core.application.ApplicationBuilder.with_identifiers>` method.+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>`.+in the :py:class:`ApplicationBuilder <burr.core.application.ApplicationBuilder>`. Important API note: unless `fork_from_app_id` is specified+below, the values used to query for state are taken from the values provided to :py:meth:`with_identifiers() <burr.core.application.ApplicationBuilder.with_identifiers>`.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-- ``fork_from_app_id`` -- Optional. The app_id to fork from. This is useful if you want to start from a previous application's state.+- ``fork_from_app_id`` -- Optional. A prior app_id to fork state from. This is useful if you want to start from a previous application's state.- ``fork_from_partition_key`` -- Optional. The partition key to fork from. Goes with ``fork_from_app_id``.- ``fork_from_sequence_id`` -- Optional. The sequence_id to fork from. Goes with ``fork_from_app_id``.-Note that you cannot use this in conjunction with :py:meth:`with_state <burr.core.application.ApplicationBuilder.with_state>`+Note (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.-Either you load from state or you start from scratch.++Note (2): The loader will not error if no state is found, it will use the default state in this case.Forking State_____________-Note that 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+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,+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 youto rewind state and make different choices.+When you use the ``fork_from_app_id`` to load state, the values passed to :py:meth:`with_identifiers() <burr.core.application.ApplicationBuilder.with_identifiers>`+will then dictate where the new application state is ultimately stored.+Writing state_____________