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.

Add docs for async persister interface

jernejfrankc36877d6f1c6
diff --git a/docs/concepts/index.rst b/docs/concepts/index.rst
index e5b32f73..25fc88da 100644
--- a/docs/concepts/index.rst
+++ b/docs/concepts/index.rst
@@ -25,3 +25,4 @@ Overview of the concepts -- read these to get a mental model for how Burr works.
parallelism
recursion
planned-capabilities
+ sync-vs-async
diff --git a/docs/concepts/sync-vs-async.rst b/docs/concepts/sync-vs-async.rst
new file mode 100644
index 00000000..96b8eaa2
--- /dev/null
+++ b/docs/concepts/sync-vs-async.rst
@@ -0,0 +1,139 @@
+===========================
+Sync vs Async Applications
+===========================
+
+TL;DR
+------
+1. For applications with horizontal scaling: multiple users, lots of i/o throughput,... go with async. Check out:
+
+ * :py:meth:`.abuild() <.ApplicationBuilder.abuild()>`
+ * :py:meth:`.aiterate() <.Application.aiterate()>`
+ * :py:meth:`.arun() <.Application.arun()>`
+ * :py:meth:`.astream_result() <.Application.astream_result()>`
+
+2. For prototyping applications or high stakes operations,... go with sync.Check out:
+
+ * :py:meth:`.build() <.ApplicationBuilder.build()>`
+ * :py:meth:`.iterate() <.Application.iterate()>`
+ * :py:meth:`.run() <.Application.run()>`
+ * :py:meth:`.stream_result() <.Application.stream_result()>`
+
+
+Burr does both sync and async
+------------------------------
+Bellow we give a short breakdown when to consider each case.
+
+In general, Burr is equipped to handle both synchronous and asynchronous runs. We usually do that by
+providing both methods (see specific references for more detail and reach out if you feel like we
+are missing a specific implementation).
+
+We hope the switch from one to another is as convenient as possible; you only need to substitute
+functions/adapters/method calls.
+
+We highly encourage to make a decision to either commit fully to sync or async. Having said that,
+there are cases where a hybrid situation may be desirable or unavoidable (testing, prototyping,
+legacy code, ...) and we give some options to handle that. The table bellow shows the
+possibilities Burr now supports.
+
+
+.. table:: Cases Burr supports
+ :widths: auto
+
+ +------------------------------------------------+----------+----------------------------------+
+ | Cases | Works? | Comment |
+ +================================================+==========+==================================+
+ | Sync Hooks <> Sync Builder <> Sync App Run | ✅ | This is a standard use |
+ | | | case highlighted |
+ | | | in sync applications |
+ +------------------------------------------------+----------+----------------------------------+
+ | Sync Hooks <> Sync Builder <> Async App Run | ⚠️ | This will work for now, but it is|
+ | | | not recommended because there |
+ | | | will be blocking functions |
+ +------------------------------------------------+----------+----------------------------------+
+ | Async Hooks <> Sync Builder <> Sync App Run | ⚠️ | This will run (if the async hook |
+ | | | is not a persister), but the |
+ | | | async hooks are ignored -- will |
+ | | | be deprecated |
+ +------------------------------------------------+----------+----------------------------------+
+ | Async Hooks <> Sync Builder <> Async App Run | ⚠️ | This will run (if the async hook |
+ | | | is not a persister), but you |
+ | | | should really use the async |
+ | | | builder |
+ +------------------------------------------------+----------+----------------------------------+
+ | Async Hooks <> Async Builder <> Async App Run | ✅ | This is a standard use case |
+ | | | highlighted in async |
+ | | | applications |
+ +------------------------------------------------+----------+----------------------------------+
+ | Async Hooks <> Async Builder <> Sync App Run | ❌ | Use async run methods |
+ +------------------------------------------------+----------+----------------------------------+
+ | Sync Hooks <> Async Builder <> Sync App Run | ❌ | Use sync builder |
+ +------------------------------------------------+----------+----------------------------------+
+ | Sync Hooks <> Async Builder <> Async App Run | ⚠️ | This will run (if the sync hook |
+ | | | is not a persister), but you |
+ | | | should really use the sync |
+ | | | builder |
+ +------------------------------------------------+----------+----------------------------------+
+
+
+Synchronous Applications
+--------------------------
+A synchronous application processes tasks sequentially, where the user or calling system must wait for
+the agent to finish a task before proceeding.
+
+Advantages
+~~~~~~~~~~~~
+
+1. Simplicity:
+ * Easier to design and implement as the logic flows linearly.
+ * Debugging and maintenance are more straightforward.
+2. Deterministic Behavior:
+ * Results are predictable and occur in a defined sequence.
+ * Ideal for workflows where steps must be completed in strict order.
+3. Low Overhead:
+ * Useful for tasks that don’t require extensive multitasking or background processing.
+ * Rapid prototyping.
+
+
+Use Cases
+~~~~~~~~~~~
+
+1. Short, straightforward tasks:
+ * For example, fetching a single database entry or making a quick calculation.
+2. High-stakes operations:
+ * When the process must proceed step-by-step without the risk of race conditions or overlapping tasks.
+3. Interactive applications:
+ * Situations where the user must receive immediate feedback before taking the next step, like form validations.
+
+Asynchronous Application
+--------------------------
+An asynchronous application can perform tasks in parallel or handle multiple requests without waiting for
+one to finish before starting another.
+
+Advantages
+~~~~~~~~~~~~
+
+1. Efficiency:
+ * Makes better use of system resources by handling multiple tasks simultaneously.
+ * Reduces idle time, especially when dealing with I/O-bound or network-bound operations.
+2. Scalability:
+ * Handles large volumes of concurrent tasks more effectively.
+ * Useful in systems requiring high throughput, like web servers or chatbots.
+3. Non-blocking Execution:
+ * Allows other operations to continue while waiting for longer processes to complete.
+ * Provides a smoother experience in real-time systems.
+
+
+Use Cases
+~~~~~~~~~~~~
+
+1. Long-running processes:
+ * Training machine learning models.
+ * Data processing pipelines.
+2. I/O-bound tasks:
+ * Calling APIs.
+ * Retrieving data from remote servers or databases.
+3. High-concurrency systems:
+ * Chatbots serving multiple users.
+ * Customer support systems.
+4. Background processing:
+ * Notifications, logs, and analytics tasks running while the main application continues.
diff --git a/docs/reference/persister.rst b/docs/reference/persister.rst
index 06f4dde8..2c723d83 100644
--- a/docs/reference/persister.rst
+++ b/docs/reference/persister.rst
@@ -30,8 +30,8 @@ Internally, this interface combines the following two interfaces:
.. automethod:: __init__
-Supported Implementations
-=========================
+Supported Sync Implementations
+================================
.. _persistersref:
@@ -61,3 +61,16 @@ Currently we support the following, although we highly recommend you contribute
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).
+
+
+Supported Async Implementations
+================================
+
+Currently we support the following, although we highly recommend you contribute your own! We will be adding more shortly.
+
+.. _asyncpersistersref:
+
+.. autoclass:: burr.core.persistence.AsyncSQLitePersister
+ :members:
+
+ .. automethod:: __init__