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.

Adds more documentation on state loading

Stefan Krawczyk20031645d67b
diff --git a/burr/core/application.py b/burr/core/application.py
index 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 = initializer
self.resume_at_next_action = resume_at_next_action
@@ -1487,7 +1491,6 @@ class ApplicationBuilder:
# there was nothing to load -- use default state
self.state = self.state.update(**self.default_state)
self.sequence_id = None # has to start at None
- self.parent_id = None
else:
if load_result["state"] is None:
raise ValueError(
diff --git a/docs/concepts/state-persistence.rst b/docs/concepts/state-persistence.rst
index 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 you
to 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
_____________