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.

refactored to cookbook

zilto8e982c6a47fc
diff --git a/docs/conf.py b/docs/conf.py
index 03445a98..375b9f09 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -47,6 +47,7 @@ html_theme_options = {
},
}
+nb_execution_mode = "off"
exclude_patterns = ["README-internal.md"]
diff --git a/docs/examples/agents.rst b/docs/examples/agents.rst
deleted file mode 100644
index 2bf21106..00000000
--- a/docs/examples/agents.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-====================
-Agents
-====================
-
-Burr allows you to create agents that can interact with each other via State.
-
-Multi-Agent Example
---------------------
-
-Here we list the different agent examples we have with Burr.
-
-Divide and Conquer
-__________________
-A single agent can usually operate effectively using a handful of tools within a single domain, but even using powerful
-models like `gpt-4`, it can be less effective at using many tools.
-
-One way to approach complicated tasks is through a "divide-and-conquer" approach: create a "specialized agent" for
-each task or domain and route tasks to the correct "expert". This means that each agent can become a sequence of LLM
-calls that chooses how to use a specific "tool".
-
-The examples we link to below are inspired by the paper `AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation by Wu, et. al. <https://arxiv.org/abs/2308.08155>`_.
-They can be found in `this part of our repository <https://github.com/DAGWorks-Inc/burr/tree/main/examples/multi-agent-collaboration>`_.
-
-We have two implementations that show case this. One uses LangChain's LCEL, the other uses Hamilton. From a Burr
-standpoint they look pretty similar as Burr doesn't care what code you use within an action, or how you set up
-your state. Each implementation has a `notebook.ipynb` that shows the basics. The `application.py` files contain extra
-things like examples of `tracing` and `hooks`.
-
-`LangChain/LCEL <https://github.com/DAGWorks-Inc/burr/tree/main/examples/multi-agent-collaboration/lcel>`_:
-
-* .. raw:: html
-
- <a target="_blank" href="https://colab.research.google.com/github/dagworks-inc/burr/blob/main/examples/multi-agent-collaboration/lcel/notebook.ipynb">
- <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
- </a>
-
-`Hamilton <https://github.com/DAGWorks-Inc/burr/tree/main/examples/multi-agent-collaboration/hamilton>`_:
-
-* .. raw:: html
-
- <a target="_blank" href="https://colab.research.google.com/github/dagworks-inc/burr/blob/main/examples/multi-agent-collaboration/hamilton/notebook.ipynb">
- <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
- </a>
-
-
-Templates
---------------------
-
-We have the bones of a few applications that can be used to create agents. These are not fully fleshed out, but they
-can be used as a starting point for creating your own agents.
-
-We have the following templates:
-
-1. multi_modal_agent
-2. multi_agent_collaboration
-3. agent_supervisor
-4. hierarchical_agent_teams
-
-See the `templates` `directory under examples <https://github.com/DAGWorks-Inc/burr/tree/main/examples/templates>`_
-in our repository for the code.
diff --git a/docs/examples/agents/_agent_patterns/agent_supervisor.png b/docs/examples/agents/_agent_patterns/agent_supervisor.png
new file mode 100644
index 00000000..f6a90ba9
Binary files /dev/null and b/docs/examples/agents/_agent_patterns/agent_supervisor.png differ
diff --git a/docs/examples/agents/_agent_patterns/hierarchical_agent_teams.png b/docs/examples/agents/_agent_patterns/hierarchical_agent_teams.png
new file mode 100644
index 00000000..35661cb6
Binary files /dev/null and b/docs/examples/agents/_agent_patterns/hierarchical_agent_teams.png differ
diff --git a/docs/examples/agents/_agent_patterns/multi_agent_collaboration.png b/docs/examples/agents/_agent_patterns/multi_agent_collaboration.png
new file mode 100644
index 00000000..4cc090df
Binary files /dev/null and b/docs/examples/agents/_agent_patterns/multi_agent_collaboration.png differ
diff --git a/docs/examples/agents/_agent_patterns/multi_modal_agent.png b/docs/examples/agents/_agent_patterns/multi_modal_agent.png
new file mode 100644
index 00000000..39ad50eb
Binary files /dev/null and b/docs/examples/agents/_agent_patterns/multi_modal_agent.png differ
diff --git a/docs/examples/agents/_divide-and-conquer.png b/docs/examples/agents/_divide-and-conquer.png
new file mode 100644
index 00000000..b4490c04
Binary files /dev/null and b/docs/examples/agents/_divide-and-conquer.png differ
diff --git a/docs/examples/agents/agent-patterns.md b/docs/examples/agents/agent-patterns.md
new file mode 100644
index 00000000..e924f061
--- /dev/null
+++ b/docs/examples/agents/agent-patterns.md
@@ -0,0 +1,31 @@
+# Agent patterns
+
+We have the bones of a few applications that can be used to create agents. These are not fully fleshed out, but they
+can be used as a starting point for creating your own agents.
+
+We have the following templates:
+
+## Multimodal agent
+
+[Code template](https://github.com/DAGWorks-Inc/burr/tree/main/examples/templates/multi_modal_agent)
+
+![](./_agent_patterns/multi_modal_agent.png)
+
+## Multi-agent collaboration
+
+[Code template](https://github.com/DAGWorks-Inc/burr/tree/main/examples/templates/multi_agent_collaboration)
+
+![](./_agent_patterns/multi_agent_collaboration.png)
+
+## Supervisor agent
+
+[Code template](https://github.com/DAGWorks-Inc/burr/tree/main/examples/templates/agent_supervisor)
+
+![](./_agent_patterns/agent_supervisor.png)
+
+
+## Hierarchical teams
+
+[Code template](https://github.com/DAGWorks-Inc/burr/tree/main/examples/templates/hierarchical_agent_teams)
+
+![](./_agent_patterns/hierarchical_agent_teams.png)
diff --git a/docs/examples/agents/divide-and-conquer.md b/docs/examples/agents/divide-and-conquer.md
new file mode 100644
index 00000000..7d59f183
--- /dev/null
+++ b/docs/examples/agents/divide-and-conquer.md
@@ -0,0 +1,26 @@
+# Divide and Conquer
+
+A single agent can usually operate effectively using a handful of tools within a single domain, but even using powerful models like `gpt-4`, it can be less effective at using many tools.
+
+One way to approach complicated tasks is through a "divide-and-conquer" approach: create a "specialized agent" for each task or domain and route tasks to the correct "expert". This means that each agent can become a sequence of LLM calls that chooses how to use a specific "tool".
+
+The examples we link to below are inspired by the paper [AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation by Wu, et. al.](https://arxiv.org/abs/2308.08155).
+They can be found in [this part of our repository](https://github.com/DAGWorks-Inc/burr/tree/main/examples/multi-agent-collaboration).
+
+![](./_divide-and-conquer.png)
+
+We provide two implementations of this idea: with [Hamilton](https://github.com/DAGWorks-Inc/burr/tree/main/examples/multi-agent-collaboration/hamilton) and with [LangChain LCEL](https://github.com/DAGWorks-Inc/burr/tree/main/examples/multi-agent-collaboration/lcel). From Burr's standpoint, both look similar and you're free to use your preferred framework within an `action`.
+
+## With Hamilton
+
+<a target="_blank" href="https://colab.research.google.com/github/dagworks-inc/burr/blob/main/examples/multi-agent-collaboration/hamilton/notebook.ipynb">
+ <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
+</a>
+
+
+
+## With LangChain Expression Language (LCEL)
+
+<a target="_blank" href="https://colab.research.google.com/github/dagworks-inc/burr/blob/main/examples/multi-agent-collaboration/lcel/notebook.ipynb">
+ <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
+</a>
diff --git a/docs/examples/agents/index.rst b/docs/examples/agents/index.rst
new file mode 100644
index 00000000..01f83174
--- /dev/null
+++ b/docs/examples/agents/index.rst
@@ -0,0 +1,11 @@
+==========
+🤖 Agents
+==========
+
+Burr allows you to create agents that can interact with each other via State.
+
+.. toctree::
+ :maxdepth: 2
+
+ divide-and-conquer
+ agent-patterns
diff --git a/docs/examples/chatbot.rst b/docs/examples/chatbot.rst
deleted file mode 100644
index 318f14a9..00000000
--- a/docs/examples/chatbot.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-================
-Chatbots
-================
-
-.. _chatbots:
-
-Chat bots are a simple example where state influences the conversation. This is a
-perfect use case for using Burr.
-
-GPT-like chatbot
-----------------
-
-See `github repository example <https://github.com/DAGWorks-Inc/burr/tree/main/examples/multi-modal-chatbot>`_.
-
-
-Conversational RAG chatbot
---------------------------
-See `github example <https://github.com/DAGWorks-Inc/burr/tree/main/examples/conversational-rag/simple_example>`_.
-
-Accompanying video walkthrough:
-
-.. raw:: html
-
- <div>
- <iframe width="800" height="455" src="https://www.youtube.com/embed/t54DCiOH270?si=QpPNs7m2t0L0V8Va" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
- </div>
diff --git a/docs/examples/chatbots/basic-chatbot.ipynb b/docs/examples/chatbots/basic-chatbot.ipynb
new file mode 100644
index 00000000..38e7e95f
--- /dev/null
+++ b/docs/examples/chatbots/basic-chatbot.ipynb
@@ -0,0 +1,453 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "61278d3e-958b-49ee-94b8-2ee1f5e58773",
+ "metadata": {},
+ "source": [
+ "# Basic\n",
+ "## Setup"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "46cb1e2e-5527-4acf-a1d0-5085eb621f4e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import uuid\n",
+ "from typing import Tuple\n",
+ "\n",
+ "import openai # replace with your favorite LLM client library\n",
+ "\n",
+ "from burr.core import action, State, ApplicationBuilder, when, persistence"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "406b410d-0091-4368-ad08-b24220f728dd",
+ "metadata": {},
+ "source": [
+ "## Define Actions\n",
+ "\n",
+ "We define two actions:\n",
+ "1. `human_input` -- this is the first one, it accepts a prompt from the outside and adds it to the state\n",
+ "2. `ai_response` -- this is the second one, it takes the prompt + chat history and queries OpenAI.\n",
+ "\n",
+ "While this is just a pass-through to OpenAI (and is thus a little pointless) -- its a start. We'll be adding more later."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "206222f0-245b-4941-8976-11f9dcc7fd37",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@action(reads=[], writes=[\"prompt\", \"chat_history\"])\n",
+ "def human_input(state: State, prompt: str) -> Tuple[dict, State]:\n",
+ " \"\"\"Pulls human input from the outside world and massages it into a standard chat format.\n",
+ " Note we're adding it into the chat history (with an `append` operation). This \n",
+ " is just for convenience of reference -- we could easily just store the chat history\n",
+ " and access it.\n",
+ " \"\"\"\n",
+ " \n",
+ " chat_item = {\n",
+ " \"content\": prompt,\n",
+ " \"role\": \"user\"\n",
+ " }\n",
+ " # return the prompt as the result\n",
+ " # put the prompt in state and update the chat_history\n",
+ " return (\n",
+ " {\"prompt\": prompt}, \n",
+ " state.update(prompt=prompt).append(chat_history=chat_item)\n",
+ " )\n",
+ "\n",
+ "@action(reads=[\"chat_history\"], writes=[\"response\", \"chat_history\"])\n",
+ "def ai_response(state: State) -> Tuple[dict, State]:\n",
+ " \"\"\"Queries OpenAI with the chat. You could easily use langchain, etc... to handle this,\n",
+ " but we wanted to keep it simple to demonstrate\"\"\"\n",
+ " client = openai.Client() # replace with your favorite LLM client library\n",
+ " content = client.chat.completions.create(\n",
+ " model=\"gpt-3.5-turbo\",\n",
+ " messages=state[\"chat_history\"],\n",
+ " ).choices[0].message.content\n",
+ " chat_item = {\n",
+ " \"content\": content,\n",
+ " \"role\": \"assistant\"\n",
+ " }\n",
+ " # return the response as the result\n",
+ " # put the response in state and update the chat history\n",
+ " return (\n",
+ " {\"response\": content}, \n",
+ " state.update(response=content).append(chat_history=chat_item)\n",
+ " )"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d3798307-6137-40ea-9818-471acafe3e1a",
+ "metadata": {},
+ "source": [
+ "## Create the app\n",
+ "\n",
+ "We create our app by adding our actions (they're `**kwargs`, the name of the action is the key), then adding transitions. \n",
+ "In this case, the transitions are simple -- we just go in a loop. Why a loop? We want to be able to continue the chat. Although the control flow\n",
+ "will pause (move from the application to the caller) after every `ai_response` call, we want to keep state, etc..."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "6e75d7ae-c9b0-4e58-812d-3da3e9d5226d",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "app = (\n",
+ " ApplicationBuilder().with_actions(\n",
+ " human_input=human_input,\n",
+ " ai_response=ai_response\n",
+ " ).with_transitions(\n",
+ " (\"human_input\", \"ai_response\"),\n",
+ " (\"ai_response\", \"human_input\")\n",
+ " ).with_state(chat_history=[])\n",
+ " .with_entrypoint(\"human_input\")\n",
+ " .build()\n",
+ ")\n",
+ "app.visualize(output_file_path=\"digraph_initial\", format=\"png\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "7cae8a7c-b696-44c6-bf32-babca8fdbe4f",
+ "metadata": {},
+ "source": [
+ "## Run the app\n",
+ "\n",
+ "To run the app, we call the `.run` function, passing in a stopping condition. In this case, we want it to halt after `ai_response`. \n",
+ "It returns the action it ran, the result it got, and the state. We use te state variable of response to print out the output, although in a react-like frontend system we may elect to return the entire chat history and render it all for the user."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "3bac2b00-bcb0-41e1-8e34-722e303a2cff",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "final_action, result, state = app.run(\n",
+ " halt_after=[\"ai_response\"], \n",
+ " inputs={\"prompt\" : \"Who was Aaron Burr?\"}\n",
+ ")\n",
+ "print(state['response'])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "119f2ce1-a4e0-429d-a617-754c92f343cc",
+ "metadata": {},
+ "source": [
+ "## Add a decision making step\n",
+ "\n",
+ "Let's add a step to check if the prompt is \"safe\". In this case OpenAI does this automatically, so we're going to simulate it by marking it as unsafe it the word \"unsafe\" is in the response.\n",
+ "We're going to add one step that checks for safety, and another that drafts a response in the case that it is unsafe.\n",
+ "\n",
+ "Then, we're going to add a \"conditional\" transition, allowing us to respond differently depending on the value of `safe`. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "69a2ef61-75c3-4a23-9c0e-87dcf1bfbf6b",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@action(reads=[\"prompt\"], writes=[\"safe\"])\n",
+ "def safety_check(state: State) -> Tuple[dict, State]:\n",
+ " safe = \"unsafe\" not in state[\"prompt\"]\n",
+ " return {\"safe\": safe}, state.update(safe=safe)\n",
+ "\n",
+ "\n",
+ "@action(reads=[], writes=[\"response\", \"chat_history\"])\n",
+ "def unsafe_response(state: State) -> Tuple[dict, State]:\n",
+ " content = \"I'm sorry, my overlords have forbidden me to respond.\"\n",
+ " new_state = (\n",
+ " state\n",
+ " .update(response=content)\n",
+ " .append(\n",
+ " chat_history={\"content\": content, \"role\": \"assistant\"})\n",
+ " )\n",
+ " return {\"response\": content}, new_state"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "e5480950-916d-45b7-ab70-fdbb8865de8d",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "safe_app = (\n",
+ " ApplicationBuilder().with_actions(\n",
+ " human_input=human_input,\n",
+ " ai_response=ai_response,\n",
+ " safety_check=safety_check,\n",
+ " unsafe_response=unsafe_response\n",
+ " ).with_transitions(\n",
+ " (\"human_input\", \"safety_check\"),\n",
+ " (\"safety_check\", \"unsafe_response\", when(safe=False)),\n",
+ " (\"safety_check\", \"ai_response\", when(safe=True)),\n",
+ " ([\"unsafe_response\", \"ai_response\"], \"human_input\"),\n",
+ " ).with_state(chat_history=[])\n",
+ " .with_entrypoint(\"human_input\")\n",
+ " .build()\n",
+ ")\n",
+ "safe_app.visualize(output_file_path=\"digraph_safe\", include_conditions=True)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "3c102eaf-4e4b-4bf3-ad60-7078bfe499d8",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "action, result, state = safe_app.run(\n",
+ " halt_after=[\"ai_response\", \"unsafe_response\"], \n",
+ " inputs={\"prompt\": \"Who was Aaron Burr, sir (unsafe)?\"}\n",
+ ")\n",
+ "print(state[\"response\"])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "002fe5f3-1076-40a8-92b4-7345aa96a2b7",
+ "metadata": {},
+ "source": [
+ "## Tracking\n",
+ "\n",
+ "OK, now let's interact with telemetry! All we have to do is add `with_tracker` call. We can also just grab the `builder` from the prior app and start where we left off. We'll run on quite a few prompts to test this out:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "acb2d83b-de78-4b5a-9514-4e1e2633bcd5",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "app_with_tracker = (\n",
+ " ApplicationBuilder().with_actions(\n",
+ " human_input=human_input,\n",
+ " ai_response=ai_response,\n",
+ " safety_check=safety_check,\n",
+ " unsafe_response=unsafe_response\n",
+ " ).with_transitions(\n",
+ " (\"human_input\", \"safety_check\"),\n",
+ " (\"safety_check\", \"unsafe_response\", when(safe=False)),\n",
+ " (\"safety_check\", \"ai_response\", when(safe=True)),\n",
+ " ([\"unsafe_response\", \"ai_response\"], \"human_input\"),\n",
+ " ).with_state(chat_history=[])\n",
+ " .with_entrypoint(\"human_input\")\n",
+ " .with_tracker(\n",
+ " \"local\", project=\"demo_getting_started\"\n",
+ " ).build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "e7a6d792-e872-4bf1-a9f7-c0d545481859",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "app_with_tracker.uid"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "4497d659-ca22-45ca-a085-0510903b6906",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "for prompt in [\n",
+ " \"Who was Aaron Burr, sir?\",\n",
+ " \"Who was Aaron Burr, sir (unsafe)?\",\n",
+ " \"If you had ml/ai libraries called 'Hamilton' and 'Burr', what would they do?\",\n",
+ " \"Who was Aaron Burr, sir?\",\n",
+ " \"Who was Aaron Burr, sir (unsafe)?\",\n",
+ " \"If you had ml/ai libraries called 'Hamilton' and 'Burr', what would they do?\",\n",
+ "]:\n",
+ " action_we_ran, result, state = app_with_tracker.run(\n",
+ " halt_after=[\"ai_response\", \"unsafe_response\"], \n",
+ " inputs={\"prompt\": prompt}\n",
+ " )"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "48c70315-32cd-4845-92a9-a40738322310",
+ "metadata": {},
+ "source": [
+ "## Tracking Server\n",
+ "\n",
+ "You can run the tracking server by running `burr` in the terminal. If you want to see it live, you can run the subsequence cell (which does some magic to run it for you). If the embedding in the notebook gets annoying, navigate to the link to the UI, outputted by the next cell. \n",
+ "\n",
+ "Press the refresh button (🔄) by \"Live\" to watch it live. Run the above cell to query."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "d96936ef-fb09-4443-be9c-56d5b7ecae69",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from IPython.display import Markdown\n",
+ "url = f\"[Link to UI](http://localhost:7241/project/demo_getting_started/{app_with_tracker.uid})\"\n",
+ "Markdown(url)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "fa4e1d34-4eb8-4d1c-9708-6269612b7209",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "import time\n",
+ "from IPython.display import HTML\n",
+ "get_ipython().system = os.system\n",
+ "!burr --no-open > /dev/null 2>&1 &\n",
+ "time.sleep(3) # quick trick to wait for the server to start\n",
+ "url = f\"http://localhost:7241/project/demo_getting_started/{app_with_tracker.uid}\"\n",
+ "iframe = f'<iframe src=\"{url}\" width=\"100%\" height=\"1000px\"></iframe>'\n",
+ "display(HTML(iframe))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d4a6591c-fb54-4211-8808-c4aab0e38040",
+ "metadata": {},
+ "source": [
+ "## Persistence\n",
+ "\n",
+ "While the tracking we showed above does do storage/persistence, Burr has a host of other capabilities to help with state persistence and reloading.\n",
+ "\n",
+ "The use case is this -- you have quite a few simultaneous conversations, each with their own state/assigned to their own users. You want to be able to store them, pause them when the user logs off, and reload them when the user logs back on. You can do this with persisters. There are two interfaces to them:\n",
+ "\n",
+ "1. A set of pre-build persisters (postgres, sqllite3, redis, etc...) that you can use\n",
+ "2. A custom persistor class that you write\n",
+ "\n",
+ "To add a persistor, you have to tell it to load from a state (`.initialize(...)`) on the builder, and tell it to save to a state (`.with_state_persister`).\n",
+ "\n",
+ "More about persistence [here](https://burr.dagworks.io/concepts/state-persistence/)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "53f25edd-d483-4c41-b716-95ac3b0cbcc4",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "app_id = f\"unique_app_id_{uuid.uuid4()}\" # unique app ID -- we create it here but this will be generated for you\n",
+ "partition_key = \"new_burr_user\" # this can be anything. In a chatbot it will "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "468d4d53-9343-48b3-ba1f-651bba3e1a3c",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# we're going to be creating this multiple times to demonstrate so let's stick it in a function\n",
+ "def create_persistable_app():\n",
+ " sqllite_persister = persistence.SQLLitePersister(db_path=\"./sqlite.db\", table_name=\"burr_state\")\n",
+ " sqllite_persister.initialize()\n",
+ " return (\n",
+ " ApplicationBuilder().with_actions(\n",
+ " human_input=human_input,\n",
+ " ai_response=ai_response,\n",
+ " safety_check=safety_check,\n",
+ " unsafe_response=unsafe_response\n",
+ " ).with_transitions(\n",
+ " (\"human_input\", \"safety_check\"),\n",
+ " (\"safety_check\", \"unsafe_response\", when(safe=False)),\n",
+ " (\"safety_check\", \"ai_response\", when(safe=True)),\n",
+ " ([\"unsafe_response\", \"ai_response\"], \"human_input\"),\n",
+ " ).initialize_from(\n",
+ " initializer=sqllite_persister,\n",
+ " resume_at_next_action=True,\n",
+ " default_state={\"chat_history\": []},\n",
+ " default_entrypoint=\"human_input\"\n",
+ " ).with_state_persister(sqllite_persister)\n",
+ " .with_identifiers(app_id=app_id, partition_key=partition_key)\n",
+ " .with_tracker(\n",
+ " \"local\", project=\"demo_getting_started\"\n",
+ " ).build()\n",
+ " )"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "ec967861-133a-4151-a3e0-ac5238bc67f5",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "app_initial = create_persistable_app()\n",
+ "action, result, state = app_initial.run(\n",
+ " halt_after=[\"ai_response\", \"unsafe_response\"], \n",
+ " inputs={\"prompt\": \"Who was Aaron Burr, sir?\"}\n",
+ ")\n",
+ "for item in state['chat_history']:\n",
+ " print(item['role'] + ':' + item['content'] + '\\n')"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "dbd18904-2407-41e0-8151-e17bba3824ef",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "del app_initial\n",
+ "app_reloaded = create_persistable_app()\n",
+ "\n",
+ "action, result, state = app_reloaded.run(\n",
+ " halt_after=[\"ai_response\", \"unsafe_response\"], \n",
+ " inputs={\"prompt\": \"Who was Alexander Hamilton?\"}\n",
+ ")\n",
+ "for item in state['chat_history']:\n",
+ " print(item['role'] + ':' + item['content'] + '\\n')"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.4"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/examples/chatbots/gpt-like-chatbot.ipynb b/docs/examples/chatbots/gpt-like-chatbot.ipynb
new file mode 100644
index 00000000..83697a95
--- /dev/null
+++ b/docs/examples/chatbots/gpt-like-chatbot.ipynb
@@ -0,0 +1,1039 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "f63df3e4b8d4fdba",
+ "metadata": {},
+ "source": [
+ "# GPT-like multimodal chatbot\n",
+ "\n",
+ "\n",
+ "<img src=\"https://github.com/user-attachments/assets/2ab9b499-7ca2-4ae9-af72-ccc775f30b4e\" width=\"100\" align=\"left\" /> + \n",
+ "<img src=\"https://cdn.mos.cms.futurecdn.net/VgGxJABA8DcfAMpPPwdv6a.jpg\" width=\"200\" align=\"center\"/>\n",
+ "\n",
+ "[https://github.com/dagworks-inc/burr](https://github.com/dagworks-inc/burr) by DAGWorks Inc. (YCW23 & StartX).\n",
+ "\n",
+ "Take🏠:\n",
+ "\n",
+ " - high level what is Burr\n",
+ " - what you can do with Burr (observing state & being able to debug a particular point in time)\n",
+ " - watch a walkthrough of this [notebook here](https://youtu.be/hqutVJyd3TI)."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d725b4dd413d01e8",
+ "metadata": {},
+ "source": [
+ "## Agentic Problems\n",
+ "1. Why did this LLM call fail?\n",
+ "2. Oh crap my code broke, why?\n",
+ "3. Things went off the rails, but where?\n",
+ "4. etc\n",
+ "\n",
+ "## Monitoring for the win, right?\n",
+ "Well but ... monitoring doesn't help you debug & complete your dev loop\n",
+ "\n",
+ "1. How do I debug that quickly?\n",
+ "2. How do I fix the inputs/code, and restart my agent?\n",
+ "3. What if my agent was 20+ steps in … do I have to restart from step 0? or can I go to a specific point in time?\n",
+ "\n",
+ "\n",
+ "## Solution: Burr\n",
+ "(Complements our other framework [Hamilton](https://github.com/dagWorks-Inc/hamilton))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3422aed8-323f-45dd-ade1-b1f0906c35f3",
+ "metadata": {},
+ "source": [
+ "## 1. Agent application is modeled as State + Actions --> Graph\n",
+ "Straightforward multi-modal example below:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 13,
+ "id": "7953fe759ae0f510",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-08-05T19:18:03.050318Z",
+ "start_time": "2024-08-05T19:18:01.630987Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "import copy\n",
+ "\n",
+ "from IPython.display import Image, display\n",
+ "from IPython.core.display import HTML \n",
+ "import openai\n",
+ "\n",
+ "from burr.core import ApplicationBuilder, State, default, graph, when\n",
+ "from burr.core.action import action\n",
+ "from burr.tracking import LocalTrackingClient\n",
+ "\n",
+ "MODES = {\n",
+ " \"answer_question\": \"text\",\n",
+ " \"generate_image\": \"image\",\n",
+ " \"generate_code\": \"code\",\n",
+ " \"unknown\": \"text\",\n",
+ "}\n",
+ "\n",
+ "\n",
+ "@action(reads=[], writes=[\"chat_history\", \"prompt\"])\n",
+ "def process_prompt(state: State, prompt: str) -> State:\n",
+ " result = {\"chat_item\": {\"role\": \"user\", \"content\": prompt, \"type\": \"text\"}}\n",
+ " state = state.append(chat_history=result[\"chat_item\"])\n",
+ " state = state.update(prompt=prompt)\n",
+ " return state\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"prompt\"], writes=[\"mode\"])\n",
+ "def choose_mode(state: State) -> State:\n",
+ " prompt = (\n",
+ " f\"You are a chatbot. You've been prompted this: {state['prompt']}. \"\n",
+ " f\"You have the capability of responding in the following modes: {', '.join(MODES)}. \"\n",
+ " \"Please respond with *only* a single word representing the mode that most accurately \"\n",
+ " \"corresponds to the prompt. Fr instance, if the prompt is 'draw a picture of a cat', \"\n",
+ " \"the mode would be 'generate_image'. If the prompt is \"\n",
+ " \"'what is the capital of France', the mode would be 'answer_question'.\"\n",
+ " \"If none of these modes apply, please respond with 'unknown'.\"\n",
+ " )\n",
+ "\n",
+ " llm_result = openai.Client().chat.completions.create(\n",
+ " model=\"gpt-4\",\n",
+ " messages=[\n",
+ " {\"role\": \"system\", \"content\": \"You are a helpful assistant\"},\n",
+ " {\"role\": \"user\", \"content\": prompt},\n",
+ " ],\n",
+ " )\n",
+ " content = llm_result.choices[0].message.content\n",
+ " mode = content.lower()\n",
+ " if mode not in MODES:\n",
+ " mode = \"unknown\"\n",
+ " result = {\"mode\": mode}\n",
+ " return state.update(**result)\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"prompt\", \"chat_history\"], writes=[\"response\"])\n",
+ "def prompt_for_more(state: State) -> State:\n",
+ " result = {\n",
+ " \"response\": {\n",
+ " \"content\": \"None of the response modes I support apply to your question. \"\n",
+ " \"Please clarify?\",\n",
+ " \"type\": \"text\",\n",
+ " \"role\": \"assistant\",\n",
+ " }\n",
+ " }\n",
+ " return state.update(**result)\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"prompt\", \"chat_history\", \"mode\"], writes=[\"response\"])\n",
+ "def chat_response(\n",
+ " state: State, prepend_prompt: str, model: str = \"gpt-3.5-turbo\"\n",
+ ") -> State:\n",
+ " \n",
+ " chat_history = copy.deepcopy(state[\"chat_history\"])\n",
+ " chat_history[-1][\"content\"] = f\"{prepend_prompt}: {chat_history[-1]['content']}\"\n",
+ " chat_history_api_format = [\n",
+ " {\n",
+ " \"role\": chat[\"role\"],\n",
+ " \"content\": chat[\"content\"],\n",
+ " }\n",
+ " for chat in chat_history\n",
+ " ]\n",
+ " client = openai.Client()\n",
+ " result = client.chat.completions.create(\n",
+ " model=model,\n",
+ " messages=chat_history_api_format,\n",
+ " )\n",
+ " text_response = result.choices[0].message.content\n",
+ " result = {\"response\": {\"content\": text_response, \"type\": MODES[state[\"mode\"]], \"role\": \"assistant\"}}\n",
+ " return state.update(**result)\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"prompt\", \"chat_history\", \"mode\"], writes=[\"response\"])\n",
+ "def image_response(state: State, model: str = \"dall-e-2\") -> State:\n",
+ " \"\"\"Generates an image response to the prompt. Optional save function to save the image to a URL.\"\"\"\n",
+ " # raise ValueError(\"Demo error\")\n",
+ " client = openai.Client()\n",
+ " result = client.images.generate(\n",
+ " model=model, prompt=state[\"prompt\"], size=\"1024x1024\", quality=\"standard\", n=1\n",
+ " )\n",
+ " image_url = result.data[0].url\n",
+ " result = {\"response\": {\"content\": image_url, \"type\": MODES[state[\"mode\"]], \"role\": \"assistant\"}}\n",
+ " return state.update(**result)\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"response\", \"mode\"], writes=[\"chat_history\"])\n",
+ "def response(state: State) -> State:\n",
+ " # you'd do something specific here based on prior state\n",
+ " result = {\"chat_item\": state[\"response\"]}\n",
+ " return state.append(chat_history=result[\"chat_item\"])\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 14,
+ "id": "add99d139d3d72a0",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-07-16T18:23:11.529415Z",
+ "start_time": "2024-07-16T18:23:11.008552Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "image/svg+xml": [
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n",
+ "<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n",
+ " \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n",
+ "<!-- Generated by graphviz version 12.0.0 (20240704.0754)\n",
+ " -->\n",
+ "<!-- Pages: 1 -->\n",
+ "<svg width=\"497pt\" height=\"304pt\"\n",
+ " viewBox=\"0.00 0.00 497.41 304.00\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n",
+ "<g id=\"graph0\" class=\"graph\" transform=\"scale(1 1) rotate(0) translate(4 300)\">\n",
+ "<polygon fill=\"white\" stroke=\"none\" points=\"-4,4 -4,-300 493.41,-300 493.41,4 -4,4\"/>\n",
+ "<!-- prompt -->\n",
+ "<g id=\"node1\" class=\"node\">\n",
+ "<title>prompt</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M408,-231C408,-231 376.25,-231 376.25,-231 370.25,-231 364.25,-225 364.25,-219 364.25,-219 364.25,-207 364.25,-207 364.25,-201 370.25,-195 376.25,-195 376.25,-195 408,-195 408,-195 414,-195 420,-201 420,-207 420,-207 420,-219 420,-219 420,-225 414,-231 408,-231\"/>\n",
+ "<text text-anchor=\"middle\" x=\"392.12\" y=\"-207.95\" font-family=\"Times,serif\" font-size=\"14.00\">prompt</text>\n",
+ "</g>\n",
+ "<!-- decide_mode -->\n",
+ "<g id=\"node3\" class=\"node\">\n",
+ "<title>decide_mode</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M318.5,-166C318.5,-166 253.75,-166 253.75,-166 247.75,-166 241.75,-160 241.75,-154 241.75,-154 241.75,-142 241.75,-142 241.75,-136 247.75,-130 253.75,-130 253.75,-130 318.5,-130 318.5,-130 324.5,-130 330.5,-136 330.5,-142 330.5,-142 330.5,-154 330.5,-154 330.5,-160 324.5,-166 318.5,-166\"/>\n",
+ "<text text-anchor=\"middle\" x=\"286.12\" y=\"-142.95\" font-family=\"Times,serif\" font-size=\"14.00\">decide_mode</text>\n",
+ "</g>\n",
+ "<!-- prompt&#45;&gt;decide_mode -->\n",
+ "<g id=\"edge5\" class=\"edge\">\n",
+ "<title>prompt&#45;&gt;decide_mode</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M364,-195.28C352.07,-188.19 337.97,-179.82 325.07,-172.15\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"327.18,-169.33 316.8,-167.23 323.6,-175.35 327.18,-169.33\"/>\n",
+ "</g>\n",
+ "<!-- input__prompt -->\n",
+ "<g id=\"node2\" class=\"node\">\n",
+ "<title>input__prompt</title>\n",
+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"392.12\" cy=\"-278\" rx=\"62.1\" ry=\"18\"/>\n",
+ "<text text-anchor=\"middle\" x=\"392.12\" y=\"-272.95\" font-family=\"Times,serif\" font-size=\"14.00\">input: prompt</text>\n",
+ "</g>\n",
+ "<!-- input__prompt&#45;&gt;prompt -->\n",
+ "<g id=\"edge1\" class=\"edge\">\n",
+ "<title>input__prompt&#45;&gt;prompt</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M392.12,-259.78C392.12,-254.37 392.12,-248.24 392.12,-242.26\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"395.63,-242.71 392.13,-232.71 388.63,-242.71 395.63,-242.71\"/>\n",
+ "</g>\n",
+ "<!-- generate_image -->\n",
+ "<g id=\"node4\" class=\"node\">\n",
+ "<title>generate_image</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M90.25,-101C90.25,-101 12,-101 12,-101 6,-101 0,-95 0,-89 0,-89 0,-77 0,-77 0,-71 6,-65 12,-65 12,-65 90.25,-65 90.25,-65 96.25,-65 102.25,-71 102.25,-77 102.25,-77 102.25,-89 102.25,-89 102.25,-95 96.25,-101 90.25,-101\"/>\n",
+ "<text text-anchor=\"middle\" x=\"51.12\" y=\"-77.95\" font-family=\"Times,serif\" font-size=\"14.00\">generate_image</text>\n",
+ "</g>\n",
+ "<!-- decide_mode&#45;&gt;generate_image -->\n",
+ "<g id=\"edge6\" class=\"edge\">\n",
+ "<title>decide_mode&#45;&gt;generate_image</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M241.38,-132.38C238.59,-131.55 235.82,-130.75 233.12,-130 182.69,-115.94 166.94,-115.1 113.33,-101.5\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"114.5,-98.19 103.94,-99.08 112.75,-104.96 114.5,-98.19\"/>\n",
+ "</g>\n",
+ "<!-- generate_code -->\n",
+ "<g id=\"node6\" class=\"node\">\n",
+ "<title>generate_code</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M202.12,-101C202.12,-101 132.12,-101 132.12,-101 126.12,-101 120.12,-95 120.12,-89 120.12,-89 120.12,-77 120.12,-77 120.12,-71 126.12,-65 132.12,-65 132.12,-65 202.12,-65 202.12,-65 208.12,-65 214.12,-71 214.12,-77 214.12,-77 214.12,-89 214.12,-89 214.12,-95 208.12,-101 202.12,-101\"/>\n",
+ "<text text-anchor=\"middle\" x=\"167.12\" y=\"-77.95\" font-family=\"Times,serif\" font-size=\"14.00\">generate_code</text>\n",
+ "</g>\n",
+ "<!-- decide_mode&#45;&gt;generate_code -->\n",
+ "<g id=\"edge7\" class=\"edge\">\n",
+ "<title>decide_mode&#45;&gt;generate_code</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M253.29,-129.62C239.9,-122.53 224.22,-114.23 209.95,-106.67\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"211.66,-103.62 201.19,-102.03 208.39,-109.81 211.66,-103.62\"/>\n",
+ "</g>\n",
+ "<!-- answer_question -->\n",
+ "<g id=\"node7\" class=\"node\">\n",
+ "<title>answer_question</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M326.5,-101C326.5,-101 243.75,-101 243.75,-101 237.75,-101 231.75,-95 231.75,-89 231.75,-89 231.75,-77 231.75,-77 231.75,-71 237.75,-65 243.75,-65 243.75,-65 326.5,-65 326.5,-65 332.5,-65 338.5,-71 338.5,-77 338.5,-77 338.5,-89 338.5,-89 338.5,-95 332.5,-101 326.5,-101\"/>\n",
+ "<text text-anchor=\"middle\" x=\"285.12\" y=\"-77.95\" font-family=\"Times,serif\" font-size=\"14.00\">answer_question</text>\n",
+ "</g>\n",
+ "<!-- decide_mode&#45;&gt;answer_question -->\n",
+ "<g id=\"edge8\" class=\"edge\">\n",
+ "<title>decide_mode&#45;&gt;answer_question</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M285.85,-129.78C285.77,-124.37 285.67,-118.24 285.57,-112.26\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"289.08,-112.65 285.42,-102.71 282.08,-112.76 289.08,-112.65\"/>\n",
+ "</g>\n",
+ "<!-- prompt_for_more -->\n",
+ "<g id=\"node8\" class=\"node\">\n",
+ "<title>prompt_for_more</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M457.88,-101C457.88,-101 368.38,-101 368.38,-101 362.38,-101 356.38,-95 356.38,-89 356.38,-89 356.38,-77 356.38,-77 356.38,-71 362.38,-65 368.38,-65 368.38,-65 457.88,-65 457.88,-65 463.88,-65 469.88,-71 469.88,-77 469.88,-77 469.88,-89 469.88,-89 469.88,-95 463.88,-101 457.88,-101\"/>\n",
+ "<text text-anchor=\"middle\" x=\"413.12\" y=\"-77.95\" font-family=\"Times,serif\" font-size=\"14.00\">prompt_for_more</text>\n",
+ "</g>\n",
+ "<!-- decide_mode&#45;&gt;prompt_for_more -->\n",
+ "<g id=\"edge9\" class=\"edge\">\n",
+ "<title>decide_mode&#45;&gt;prompt_for_more</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M321.16,-129.62C335.74,-122.39 352.84,-113.91 368.31,-106.23\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"369.44,-109.58 376.84,-102 366.33,-103.31 369.44,-109.58\"/>\n",
+ "</g>\n",
+ "<!-- response -->\n",
+ "<g id=\"node9\" class=\"node\">\n",
+ "<title>response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M304.75,-36C304.75,-36 265.5,-36 265.5,-36 259.5,-36 253.5,-30 253.5,-24 253.5,-24 253.5,-12 253.5,-12 253.5,-6 259.5,0 265.5,0 265.5,0 304.75,0 304.75,0 310.75,0 316.75,-6 316.75,-12 316.75,-12 316.75,-24 316.75,-24 316.75,-30 310.75,-36 304.75,-36\"/>\n",
+ "<text text-anchor=\"middle\" x=\"285.12\" y=\"-12.95\" font-family=\"Times,serif\" font-size=\"14.00\">response</text>\n",
+ "</g>\n",
+ "<!-- generate_image&#45;&gt;response -->\n",
+ "<g id=\"edge10\" class=\"edge\">\n",
+ "<title>generate_image&#45;&gt;response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M102.5,-67.38C105.41,-66.57 108.31,-65.77 111.12,-65 155.72,-52.79 206.9,-39.32 242.15,-30.14\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"242.75,-33.6 251.55,-27.69 240.99,-26.82 242.75,-33.6\"/>\n",
+ "</g>\n",
+ "<!-- input__model -->\n",
+ "<g id=\"node5\" class=\"node\">\n",
+ "<title>input__model</title>\n",
+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"165.12\" cy=\"-148\" rx=\"58.52\" ry=\"18\"/>\n",
+ "<text text-anchor=\"middle\" x=\"165.12\" y=\"-142.95\" font-family=\"Times,serif\" font-size=\"14.00\">input: model</text>\n",
+ "</g>\n",
+ "<!-- input__model&#45;&gt;generate_image -->\n",
+ "<g id=\"edge2\" class=\"edge\">\n",
+ "<title>input__model&#45;&gt;generate_image</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M137.53,-131.75C124.04,-124.29 107.52,-115.16 92.55,-106.89\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"94.26,-103.84 83.82,-102.07 90.88,-109.97 94.26,-103.84\"/>\n",
+ "</g>\n",
+ "<!-- input__model&#45;&gt;generate_code -->\n",
+ "<g id=\"edge3\" class=\"edge\">\n",
+ "<title>input__model&#45;&gt;generate_code</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M165.67,-129.78C165.84,-124.37 166.04,-118.24 166.23,-112.26\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"169.71,-112.81 166.53,-102.71 162.72,-112.59 169.71,-112.81\"/>\n",
+ "</g>\n",
+ "<!-- input__model&#45;&gt;answer_question -->\n",
+ "<g id=\"edge4\" class=\"edge\">\n",
+ "<title>input__model&#45;&gt;answer_question</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M193.87,-131.91C208.2,-124.38 225.84,-115.13 241.77,-106.76\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"243.38,-109.87 250.6,-102.12 240.12,-103.67 243.38,-109.87\"/>\n",
+ "</g>\n",
+ "<!-- generate_code&#45;&gt;response -->\n",
+ "<g id=\"edge12\" class=\"edge\">\n",
+ "<title>generate_code&#45;&gt;response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M199.68,-64.62C213.08,-57.47 228.76,-49.09 243.01,-41.48\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"244.57,-44.62 251.75,-36.82 241.28,-38.44 244.57,-44.62\"/>\n",
+ "</g>\n",
+ "<!-- answer_question&#45;&gt;response -->\n",
+ "<g id=\"edge11\" class=\"edge\">\n",
+ "<title>answer_question&#45;&gt;response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M285.12,-64.78C285.12,-59.37 285.12,-53.24 285.12,-47.26\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"288.63,-47.71 285.13,-37.71 281.63,-47.71 288.63,-47.71\"/>\n",
+ "</g>\n",
+ "<!-- prompt_for_more&#45;&gt;response -->\n",
+ "<g id=\"edge13\" class=\"edge\">\n",
+ "<title>prompt_for_more&#45;&gt;response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M377.81,-64.62C362,-56.84 343.24,-47.61 326.76,-39.49\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"328.7,-36.55 318.19,-35.27 325.61,-42.83 328.7,-36.55\"/>\n",
+ "</g>\n",
+ "<!-- response&#45;&gt;prompt -->\n",
+ "<g id=\"edge14\" class=\"edge\">\n",
+ "<title>response&#45;&gt;prompt</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M317.03,-21.86C366.8,-27.05 459.27,-39.88 479.12,-65 510.58,-104.78 461.19,-157.01 424.93,-187.3\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"422.78,-184.54 417.22,-193.56 427.19,-189.97 422.78,-184.54\"/>\n",
+ "</g>\n",
+ "</g>\n",
+ "</svg>\n"
+ ],
+ "text/plain": [
+ "<graphviz.graphs.Digraph at 0x12b8d55d0>"
+ ]
+ },
+ "execution_count": 14,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "# Built the graph.\n",
+ "base_graph = (\n",
+ " graph.GraphBuilder()\n",
+ " .with_actions(\n",
+ " # these are the \"nodes\" \n",
+ " prompt=process_prompt,\n",
+ " decide_mode=choose_mode,\n",
+ " generate_image=image_response,\n",
+ " generate_code=chat_response.bind(\n",
+ " prepend_prompt=\"Please respond with *only* code and no other text (at all) to the following:\",\n",
+ " ),\n",
+ " answer_question=chat_response.bind(\n",
+ " prepend_prompt=\"Please answer the following question:\",\n",
+ " ),\n",
+ " prompt_for_more=prompt_for_more,\n",
+ " response=response,\n",
+ " )\n",
+ " .with_transitions(\n",
+ " # these are the edges between nodes, based on state.\n",
+ " (\"prompt\", \"decide_mode\", default),\n",
+ " (\"decide_mode\", \"generate_image\", when(mode=\"generate_image\")),\n",
+ " (\"decide_mode\", \"generate_code\", when(mode=\"generate_code\")),\n",
+ " (\"decide_mode\", \"answer_question\", when(mode=\"answer_question\")),\n",
+ " (\"decide_mode\", \"prompt_for_more\", default),\n",
+ " (\n",
+ " [\"generate_image\", \"answer_question\", \"generate_code\", \"prompt_for_more\"],\n",
+ " \"response\",\n",
+ " ),\n",
+ " (\"response\", \"prompt\", default),\n",
+ " )\n",
+ " .build()\n",
+ ")\n",
+ "base_graph.visualize()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "63b26ad97a43444",
+ "metadata": {},
+ "source": [
+ "## 2. Build application --> built in checkpointing & tracking"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 11,
+ "id": "4f0bf205944272ff",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-07-16T18:27:12.136291Z",
+ "start_time": "2024-07-16T18:27:11.518066Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "image/svg+xml": [
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n",
+ "<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n",
+ " \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n",
+ "<!-- Generated by graphviz version 12.0.0 (20240704.0754)\n",
+ " -->\n",
+ "<!-- Pages: 1 -->\n",
+ "<svg width=\"576pt\" height=\"328pt\"\n",
+ " viewBox=\"0.00 0.00 575.76 327.50\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n",
+ "<g id=\"graph0\" class=\"graph\" transform=\"scale(1 1) rotate(0) translate(4 323.5)\">\n",
+ "<polygon fill=\"white\" stroke=\"none\" points=\"-4,4 -4,-323.5 571.76,-323.5 571.76,4 -4,4\"/>\n",
+ "<!-- prompt -->\n",
+ "<g id=\"node1\" class=\"node\">\n",
+ "<title>prompt</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M505.39,-252.5C505.39,-252.5 473.64,-252.5 473.64,-252.5 467.64,-252.5 461.64,-246.5 461.64,-240.5 461.64,-240.5 461.64,-228.5 461.64,-228.5 461.64,-222.5 467.64,-216.5 473.64,-216.5 473.64,-216.5 505.39,-216.5 505.39,-216.5 511.39,-216.5 517.39,-222.5 517.39,-228.5 517.39,-228.5 517.39,-240.5 517.39,-240.5 517.39,-246.5 511.39,-252.5 505.39,-252.5\"/>\n",
+ "<text text-anchor=\"middle\" x=\"489.52\" y=\"-229.45\" font-family=\"Times,serif\" font-size=\"14.00\">prompt</text>\n",
+ "</g>\n",
+ "<!-- decide_mode -->\n",
+ "<g id=\"node3\" class=\"node\">\n",
+ "<title>decide_mode</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M436.89,-185.5C436.89,-185.5 372.14,-185.5 372.14,-185.5 366.14,-185.5 360.14,-179.5 360.14,-173.5 360.14,-173.5 360.14,-161.5 360.14,-161.5 360.14,-155.5 366.14,-149.5 372.14,-149.5 372.14,-149.5 436.89,-149.5 436.89,-149.5 442.89,-149.5 448.89,-155.5 448.89,-161.5 448.89,-161.5 448.89,-173.5 448.89,-173.5 448.89,-179.5 442.89,-185.5 436.89,-185.5\"/>\n",
+ "<text text-anchor=\"middle\" x=\"404.52\" y=\"-162.45\" font-family=\"Times,serif\" font-size=\"14.00\">decide_mode</text>\n",
+ "</g>\n",
+ "<!-- prompt&#45;&gt;decide_mode -->\n",
+ "<g id=\"edge5\" class=\"edge\">\n",
+ "<title>prompt&#45;&gt;decide_mode</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M466.74,-216.08C457.4,-208.94 446.43,-200.55 436.33,-192.82\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"438.63,-190.18 428.56,-186.89 434.38,-195.74 438.63,-190.18\"/>\n",
+ "</g>\n",
+ "<!-- input__prompt -->\n",
+ "<g id=\"node2\" class=\"node\">\n",
+ "<title>input__prompt</title>\n",
+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"489.52\" cy=\"-301.5\" rx=\"62.1\" ry=\"18\"/>\n",
+ "<text text-anchor=\"middle\" x=\"489.52\" y=\"-296.45\" font-family=\"Times,serif\" font-size=\"14.00\">input: prompt</text>\n",
+ "</g>\n",
+ "<!-- input__prompt&#45;&gt;prompt -->\n",
+ "<g id=\"edge1\" class=\"edge\">\n",
+ "<title>input__prompt&#45;&gt;prompt</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M489.52,-283.08C489.52,-277.25 489.52,-270.59 489.52,-264.14\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"493.02,-264.48 489.52,-254.48 486.02,-264.48 493.02,-264.48\"/>\n",
+ "</g>\n",
+ "<!-- generate_image -->\n",
+ "<g id=\"node4\" class=\"node\">\n",
+ "<title>generate_image</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M130.64,-103C130.64,-103 52.39,-103 52.39,-103 46.39,-103 40.39,-97 40.39,-91 40.39,-91 40.39,-79 40.39,-79 40.39,-73 46.39,-67 52.39,-67 52.39,-67 130.64,-67 130.64,-67 136.64,-67 142.64,-73 142.64,-79 142.64,-79 142.64,-91 142.64,-91 142.64,-97 136.64,-103 130.64,-103\"/>\n",
+ "<text text-anchor=\"middle\" x=\"91.52\" y=\"-79.95\" font-family=\"Times,serif\" font-size=\"14.00\">generate_image</text>\n",
+ "</g>\n",
+ "<!-- decide_mode&#45;&gt;generate_image -->\n",
+ "<g id=\"edge6\" class=\"edge\">\n",
+ "<title>decide_mode&#45;&gt;generate_image</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M359.79,-166.05C290.41,-164.61 160.83,-158.64 122.27,-134.5 114.19,-129.44 107.85,-121.39 103.09,-113.3\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"106.28,-111.85 98.57,-104.58 100.06,-115.07 106.28,-111.85\"/>\n",
+ "<text text-anchor=\"middle\" x=\"185.14\" y=\"-121.2\" font-family=\"Times,serif\" font-size=\"14.00\">mode=generate_image</text>\n",
+ "</g>\n",
+ "<!-- generate_code -->\n",
+ "<g id=\"node6\" class=\"node\">\n",
+ "<title>generate_code</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M278.52,-103C278.52,-103 208.52,-103 208.52,-103 202.52,-103 196.52,-97 196.52,-91 196.52,-91 196.52,-79 196.52,-79 196.52,-73 202.52,-67 208.52,-67 208.52,-67 278.52,-67 278.52,-67 284.52,-67 290.52,-73 290.52,-79 290.52,-79 290.52,-91 290.52,-91 290.52,-97 284.52,-103 278.52,-103\"/>\n",
+ "<text text-anchor=\"middle\" x=\"243.52\" y=\"-79.95\" font-family=\"Times,serif\" font-size=\"14.00\">generate_code</text>\n",
+ "</g>\n",
+ "<!-- decide_mode&#45;&gt;generate_code -->\n",
+ "<g id=\"edge7\" class=\"edge\">\n",
+ "<title>decide_mode&#45;&gt;generate_code</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M359.74,-161.19C323.45,-156.06 276.03,-147.17 261.52,-134.5 255.43,-129.18 251.39,-121.61 248.72,-114.02\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"252.16,-113.31 246.11,-104.61 245.41,-115.18 252.16,-113.31\"/>\n",
+ "<text text-anchor=\"middle\" x=\"320.02\" y=\"-121.2\" font-family=\"Times,serif\" font-size=\"14.00\">mode=generate_code</text>\n",
+ "</g>\n",
+ "<!-- answer_question -->\n",
+ "<g id=\"node7\" class=\"node\">\n",
+ "<title>answer_question</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M402.89,-103C402.89,-103 320.14,-103 320.14,-103 314.14,-103 308.14,-97 308.14,-91 308.14,-91 308.14,-79 308.14,-79 308.14,-73 314.14,-67 320.14,-67 320.14,-67 402.89,-67 402.89,-67 408.89,-67 414.89,-73 414.89,-79 414.89,-79 414.89,-91 414.89,-91 414.89,-97 408.89,-103 402.89,-103\"/>\n",
+ "<text text-anchor=\"middle\" x=\"361.52\" y=\"-79.95\" font-family=\"Times,serif\" font-size=\"14.00\">answer_question</text>\n",
+ "</g>\n",
+ "<!-- decide_mode&#45;&gt;answer_question -->\n",
+ "<g id=\"edge8\" class=\"edge\">\n",
+ "<title>decide_mode&#45;&gt;answer_question</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M397.41,-149.12C393.38,-139.74 388.05,-128.04 382.52,-118 381.59,-116.32 380.61,-114.61 379.59,-112.9\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"382.65,-111.2 374.38,-104.59 376.72,-114.92 382.65,-111.2\"/>\n",
+ "<text text-anchor=\"middle\" x=\"454.39\" y=\"-121.2\" font-family=\"Times,serif\" font-size=\"14.00\">mode=answer_question</text>\n",
+ "</g>\n",
+ "<!-- prompt_for_more -->\n",
+ "<g id=\"node8\" class=\"node\">\n",
+ "<title>prompt_for_more</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M534.27,-103C534.27,-103 444.77,-103 444.77,-103 438.77,-103 432.77,-97 432.77,-91 432.77,-91 432.77,-79 432.77,-79 432.77,-73 438.77,-67 444.77,-67 444.77,-67 534.27,-67 534.27,-67 540.27,-67 546.27,-73 546.27,-79 546.27,-79 546.27,-91 546.27,-91 546.27,-97 540.27,-103 534.27,-103\"/>\n",
+ "<text text-anchor=\"middle\" x=\"489.52\" y=\"-79.95\" font-family=\"Times,serif\" font-size=\"14.00\">prompt_for_more</text>\n",
+ "</g>\n",
+ "<!-- decide_mode&#45;&gt;prompt_for_more -->\n",
+ "<g id=\"edge9\" class=\"edge\">\n",
+ "<title>decide_mode&#45;&gt;prompt_for_more</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M449.11,-160.23C478.92,-155.02 514.31,-146.51 523.52,-134.5 529.09,-127.23 526.67,-119.14 521.13,-111.69\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"523.84,-109.47 514.52,-104.43 518.67,-114.18 523.84,-109.47\"/>\n",
+ "</g>\n",
+ "<!-- response -->\n",
+ "<g id=\"node9\" class=\"node\">\n",
+ "<title>response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M381.14,-36C381.14,-36 341.89,-36 341.89,-36 335.89,-36 329.89,-30 329.89,-24 329.89,-24 329.89,-12 329.89,-12 329.89,-6 335.89,0 341.89,0 341.89,0 381.14,0 381.14,0 387.14,0 393.14,-6 393.14,-12 393.14,-12 393.14,-24 393.14,-24 393.14,-30 387.14,-36 381.14,-36\"/>\n",
+ "<text text-anchor=\"middle\" x=\"361.52\" y=\"-12.95\" font-family=\"Times,serif\" font-size=\"14.00\">response</text>\n",
+ "</g>\n",
+ "<!-- generate_image&#45;&gt;response -->\n",
+ "<g id=\"edge10\" class=\"edge\">\n",
+ "<title>generate_image&#45;&gt;response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M142.94,-71.62C193.82,-59.37 270.83,-40.83 318.55,-29.34\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"319.35,-32.75 328.25,-27.01 317.71,-25.95 319.35,-32.75\"/>\n",
+ "</g>\n",
+ "<!-- input__model -->\n",
+ "<g id=\"node5\" class=\"node\">\n",
+ "<title>input__model</title>\n",
+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"58.52\" cy=\"-167.5\" rx=\"58.52\" ry=\"18\"/>\n",
+ "<text text-anchor=\"middle\" x=\"58.52\" y=\"-162.45\" font-family=\"Times,serif\" font-size=\"14.00\">input: model</text>\n",
+ "</g>\n",
+ "<!-- input__model&#45;&gt;generate_image -->\n",
+ "<g id=\"edge2\" class=\"edge\">\n",
+ "<title>input__model&#45;&gt;generate_image</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M49.26,-149.64C45.25,-139.97 42.5,-127.85 47.52,-118 48.79,-115.5 50.36,-113.14 52.15,-110.94\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"54.25,-113.79 58.83,-104.24 49.29,-108.85 54.25,-113.79\"/>\n",
+ "</g>\n",
+ "<!-- input__model&#45;&gt;generate_code -->\n",
+ "<g id=\"edge3\" class=\"edge\">\n",
+ "<title>input__model&#45;&gt;generate_code</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M59.1,-149.33C60.4,-138.81 63.82,-125.9 72.52,-118 72.79,-117.75 135.74,-106.02 185.17,-96.83\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"185.76,-100.28 194.95,-95.01 184.48,-93.4 185.76,-100.28\"/>\n",
+ "</g>\n",
+ "<!-- input__model&#45;&gt;answer_question -->\n",
+ "<g id=\"edge4\" class=\"edge\">\n",
+ "<title>input__model&#45;&gt;answer_question</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M111.9,-159.9C143.3,-155.01 183.4,-146.98 217.52,-134.5 231.81,-129.27 233.43,-123.76 247.52,-118 250.2,-116.9 272.65,-110.56 296.93,-103.81\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"297.62,-107.25 306.32,-101.2 295.74,-100.5 297.62,-107.25\"/>\n",
+ "</g>\n",
+ "<!-- generate_code&#45;&gt;response -->\n",
+ "<g id=\"edge12\" class=\"edge\">\n",
+ "<title>generate_code&#45;&gt;response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M275.14,-66.58C288.89,-59 305.2,-50.02 319.92,-41.91\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"321.41,-45.09 328.48,-37.2 318.03,-38.96 321.41,-45.09\"/>\n",
+ "</g>\n",
+ "<!-- answer_question&#45;&gt;response -->\n",
+ "<g id=\"edge11\" class=\"edge\">\n",
+ "<title>answer_question&#45;&gt;response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M361.52,-66.58C361.52,-60.75 361.52,-54.09 361.52,-47.64\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"365.02,-47.98 361.52,-37.98 358.02,-47.98 365.02,-47.98\"/>\n",
+ "</g>\n",
+ "<!-- prompt_for_more&#45;&gt;response -->\n",
+ "<g id=\"edge13\" class=\"edge\">\n",
+ "<title>prompt_for_more&#45;&gt;response</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M455.22,-66.58C439.27,-58.48 420.17,-48.78 403.38,-40.26\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"405.13,-37.22 394.62,-35.81 401.96,-43.46 405.13,-37.22\"/>\n",
+ "</g>\n",
+ "<!-- response&#45;&gt;prompt -->\n",
+ "<g id=\"edge14\" class=\"edge\">\n",
+ "<title>response&#45;&gt;prompt</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M393.44,-22.2C443.23,-27.91 535.74,-41.73 555.52,-67 589.35,-110.23 545.13,-173.01 514.42,-207.83\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"512.11,-205.17 507.98,-214.93 517.29,-209.87 512.11,-205.17\"/>\n",
+ "</g>\n",
+ "</g>\n",
+ "</svg>\n"
+ ],
+ "text/plain": [
+ "<burr.core.application.Application at 0x12afc6b90>"
+ ]
+ },
+ "execution_count": 11,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "tracker = LocalTrackingClient(project=\"agent-demo\")\n",
+ "app = (\n",
+ " ApplicationBuilder()\n",
+ " .with_graph(base_graph)\n",
+ " .initialize_from(\n",
+ " tracker, \n",
+ " resume_at_next_action=True, \n",
+ " default_state={\"chat_history\": []},\n",
+ " default_entrypoint=\"prompt\",\n",
+ " )\n",
+ " .with_tracker(tracker) # tracking + checkpointing; one line 🪄.\n",
+ " .build()\n",
+ ")\n",
+ "app"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b4c48e44fbf36f4d",
+ "metadata": {},
+ "source": [
+ "## 3. Comes with a UI\n",
+ "View runs in the UI; Let's run the app first."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "id": "48745f4c04b9d28d",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Hi, how can I help? what is the capital of France?\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "🤖: The capital of France is Paris.\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Hi, how can I help? write hello world in java\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "🤖: ```\n",
+ "public class HelloWorld {\n",
+ " public static void main(String[] args) {\n",
+ " System.out.println(\"Hello, World!\");\n",
+ " }\n",
+ "}\n",
+ "```\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Hi, how can I help? draw a pen\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "\n",
+ "********************************************************************************\n",
+ "-------------------------------------------------------------------\n",
+ "Oh no an error! Need help with Burr?\n",
+ "Join our discord and ask for help! https://discord.gg/4FxBMyzW5n\n",
+ "-------------------------------------------------------------------\n",
+ "> Action: `generate_image` encountered an error!<\n",
+ "> State (at time of action):\n",
+ "{'__PRIOR_STEP': 'decide_mode',\n",
+ " '__SEQUENCE_ID': 10,\n",
+ " 'chat_history': \"[{'role': 'user', 'content': 'what is the capital ...\",\n",
+ " 'mode': 'generate_image',\n",
+ " 'prompt': 'draw a pen',\n",
+ " 'response': \"{'content': '```\\\\npublic class HelloWorld {\\\\n p...\"}\n",
+ "> Inputs (at time of action):\n",
+ "{'prompt': 'draw a pen'}\n",
+ "********************************************************************************\n",
+ "Traceback (most recent call last):\n",
+ " File \"/Users/stefankrawczyk/dagworks/burr/burr/core/application.py\", line 534, in _step\n",
+ " result, new_state = _run_single_step_action(\n",
+ " File \"/Users/stefankrawczyk/dagworks/burr/burr/core/application.py\", line 233, in _run_single_step_action\n",
+ " action.run_and_update(state, **inputs), action.name\n",
+ " File \"/Users/stefankrawczyk/dagworks/burr/burr/core/action.py\", line 533, in run_and_update\n",
+ " return self._fn(state, **self._bound_params, **run_kwargs)\n",
+ " File \"/var/folders/gv/q39lb_1s26x7gbyyypqc3dkm0000gn/T/ipykernel_43564/1354917547.py\", line 94, in image_response\n",
+ " raise ValueError(\"Demo error\")\n",
+ "ValueError: Demo error\n"
+ ]
+ },
+ {
+ "ename": "ValueError",
+ "evalue": "Demo error",
+ "output_type": "error",
+ "traceback": [
+ "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+ "\u001b[0;31mValueError\u001b[0m Traceback (most recent call last)",
+ "Cell \u001b[0;32mIn[12], line 5\u001b[0m\n\u001b[1;32m 3\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mquit\u001b[39m\u001b[38;5;124m\"\u001b[39m \u001b[38;5;241m==\u001b[39m user_input\u001b[38;5;241m.\u001b[39mlower():\n\u001b[1;32m 4\u001b[0m \u001b[38;5;28;01mbreak\u001b[39;00m\n\u001b[0;32m----> 5\u001b[0m last_action, action_result, app_state \u001b[38;5;241m=\u001b[39m \u001b[43mapp\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mrun\u001b[49m\u001b[43m(\u001b[49m\n\u001b[1;32m 6\u001b[0m \u001b[43m \u001b[49m\u001b[43mhalt_after\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43m[\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mresponse\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m]\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\n\u001b[1;32m 7\u001b[0m \u001b[43m \u001b[49m\u001b[43minputs\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43m{\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mprompt\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m:\u001b[49m\u001b[43m \u001b[49m\u001b[43muser_input\u001b[49m\u001b[43m}\u001b[49m\n\u001b[1;32m 8\u001b[0m \u001b[43m\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m 9\u001b[0m last_message \u001b[38;5;241m=\u001b[39m app_state[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mchat_history\u001b[39m\u001b[38;5;124m\"\u001b[39m][\u001b[38;5;241m-\u001b[39m\u001b[38;5;241m1\u001b[39m]\n\u001b[1;32m 10\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m last_message[\u001b[38;5;124m'\u001b[39m\u001b[38;5;124mtype\u001b[39m\u001b[38;5;124m'\u001b[39m] \u001b[38;5;241m==\u001b[39m \u001b[38;5;124m'\u001b[39m\u001b[38;5;124mimage\u001b[39m\u001b[38;5;124m'\u001b[39m:\n",
+ "File \u001b[0;32m~/dagworks/burr/burr/telemetry.py:273\u001b[0m, in \u001b[0;36mcapture_function_usage.<locals>.wrapped_fn\u001b[0;34m(*args, **kwargs)\u001b[0m\n\u001b[1;32m 270\u001b[0m \u001b[38;5;129m@functools\u001b[39m\u001b[38;5;241m.\u001b[39mwraps(call_fn)\n\u001b[1;32m 271\u001b[0m \u001b[38;5;28;01mdef\u001b[39;00m \u001b[38;5;21mwrapped_fn\u001b[39m(\u001b[38;5;241m*\u001b[39margs, \u001b[38;5;241m*\u001b[39m\u001b[38;5;241m*\u001b[39mkwargs):\n\u001b[1;32m 272\u001b[0m \u001b[38;5;28;01mtry\u001b[39;00m:\n\u001b[0;32m--> 273\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43mcall_fn\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43margs\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43mkwargs\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m 274\u001b[0m \u001b[38;5;28;01mfinally\u001b[39;00m:\n\u001b[1;32m 275\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m is_telemetry_enabled():\n",
+ "File \u001b[0;32m~/dagworks/burr/burr/core/application.py:878\u001b[0m, in \u001b[0;36mApplication.run\u001b[0;34m(self, halt_before, halt_after, inputs)\u001b[0m\n\u001b[1;32m 876\u001b[0m \u001b[38;5;28;01mwhile\u001b[39;00m \u001b[38;5;28;01mTrue\u001b[39;00m:\n\u001b[1;32m 877\u001b[0m \u001b[38;5;28;01mtry\u001b[39;00m:\n\u001b[0;32m--> 878\u001b[0m \u001b[38;5;28;43mnext\u001b[39;49m\u001b[43m(\u001b[49m\u001b[43mgen\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m 879\u001b[0m \u001b[38;5;28;01mexcept\u001b[39;00m \u001b[38;5;167;01mStopIteration\u001b[39;00m \u001b[38;5;28;01mas\u001b[39;00m e:\n\u001b[1;32m 880\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m e\u001b[38;5;241m.\u001b[39mvalue\n",
+ "File \u001b[0;32m~/dagworks/burr/burr/core/application.py:823\u001b[0m, in \u001b[0;36mApplication.iterate\u001b[0;34m(self, halt_before, halt_after, inputs)\u001b[0m\n\u001b[1;32m 820\u001b[0m prior_action: Optional[Action] \u001b[38;5;241m=\u001b[39m \u001b[38;5;28;01mNone\u001b[39;00m\n\u001b[1;32m 821\u001b[0m \u001b[38;5;28;01mwhile\u001b[39;00m \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39mhas_next_action():\n\u001b[1;32m 822\u001b[0m \u001b[38;5;66;03m# self.step will only return None if there is no next action, so we can rely on tuple unpacking\u001b[39;00m\n\u001b[0;32m--> 823\u001b[0m prior_action, result, state \u001b[38;5;241m=\u001b[39m \u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mstep\u001b[49m\u001b[43m(\u001b[49m\u001b[43minputs\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43minputs\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m 824\u001b[0m \u001b[38;5;28;01myield\u001b[39;00m prior_action, result, state\n\u001b[1;32m 825\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39m_should_halt_iterate(halt_before, halt_after, prior_action):\n",
+ "File \u001b[0;32m~/dagworks/burr/burr/core/application.py:495\u001b[0m, in \u001b[0;36mApplication.step\u001b[0;34m(self, inputs)\u001b[0m\n\u001b[1;32m 492\u001b[0m \u001b[38;5;66;03m# we need to increment the sequence before we start computing\u001b[39;00m\n\u001b[1;32m 493\u001b[0m \u001b[38;5;66;03m# that way if we're replaying from state, we don't get stuck\u001b[39;00m\n\u001b[1;32m 494\u001b[0m \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39m_increment_sequence_id()\n\u001b[0;32m--> 495\u001b[0m out \u001b[38;5;241m=\u001b[39m \u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43m_step\u001b[49m\u001b[43m(\u001b[49m\u001b[43minputs\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43minputs\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43m_run_hooks\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[38;5;28;43;01mTrue\u001b[39;49;00m\u001b[43m)\u001b[49m\n\u001b[1;32m 496\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m out\n",
+ "File \u001b[0;32m~/dagworks/burr/burr/core/application.py:548\u001b[0m, in \u001b[0;36mApplication._step\u001b[0;34m(self, inputs, _run_hooks)\u001b[0m\n\u001b[1;32m 546\u001b[0m exc \u001b[38;5;241m=\u001b[39m e\n\u001b[1;32m 547\u001b[0m logger\u001b[38;5;241m.\u001b[39mexception(_format_BASE_ERROR_MESSAGE(next_action, \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39m_state, inputs))\n\u001b[0;32m--> 548\u001b[0m \u001b[38;5;28;01mraise\u001b[39;00m e\n\u001b[1;32m 549\u001b[0m \u001b[38;5;28;01mfinally\u001b[39;00m:\n\u001b[1;32m 550\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m _run_hooks:\n",
+ "File \u001b[0;32m~/dagworks/burr/burr/core/application.py:534\u001b[0m, in \u001b[0;36mApplication._step\u001b[0;34m(self, inputs, _run_hooks)\u001b[0m\n\u001b[1;32m 532\u001b[0m \u001b[38;5;28;01mtry\u001b[39;00m:\n\u001b[1;32m 533\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m next_action\u001b[38;5;241m.\u001b[39msingle_step:\n\u001b[0;32m--> 534\u001b[0m result, new_state \u001b[38;5;241m=\u001b[39m \u001b[43m_run_single_step_action\u001b[49m\u001b[43m(\u001b[49m\n\u001b[1;32m 535\u001b[0m \u001b[43m \u001b[49m\u001b[43mnext_action\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43m_state\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43maction_inputs\u001b[49m\n\u001b[1;32m 536\u001b[0m \u001b[43m \u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m 537\u001b[0m \u001b[38;5;28;01melse\u001b[39;00m:\n\u001b[1;32m 538\u001b[0m result \u001b[38;5;241m=\u001b[39m _run_function(\n\u001b[1;32m 539\u001b[0m next_action, \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39m_state, action_inputs, name\u001b[38;5;241m=\u001b[39mnext_action\u001b[38;5;241m.\u001b[39mname\n\u001b[1;32m 540\u001b[0m )\n",
+ "File \u001b[0;32m~/dagworks/burr/burr/core/application.py:233\u001b[0m, in \u001b[0;36m_run_single_step_action\u001b[0;34m(action, state, inputs)\u001b[0m\n\u001b[1;32m 230\u001b[0m \u001b[38;5;66;03m# TODO -- guard all reads/writes with a subset of the state\u001b[39;00m\n\u001b[1;32m 231\u001b[0m action\u001b[38;5;241m.\u001b[39mvalidate_inputs(inputs)\n\u001b[1;32m 232\u001b[0m result, new_state \u001b[38;5;241m=\u001b[39m _adjust_single_step_output(\n\u001b[0;32m--> 233\u001b[0m \u001b[43maction\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mrun_and_update\u001b[49m\u001b[43m(\u001b[49m\u001b[43mstate\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43minputs\u001b[49m\u001b[43m)\u001b[49m, action\u001b[38;5;241m.\u001b[39mname\n\u001b[1;32m 234\u001b[0m )\n\u001b[1;32m 235\u001b[0m _validate_result(result, action\u001b[38;5;241m.\u001b[39mname)\n\u001b[1;32m 236\u001b[0m out \u001b[38;5;241m=\u001b[39m result, _state_update(state, new_state)\n",
+ "File \u001b[0;32m~/dagworks/burr/burr/core/action.py:533\u001b[0m, in \u001b[0;36mFunctionBasedAction.run_and_update\u001b[0;34m(self, state, **run_kwargs)\u001b[0m\n\u001b[1;32m 532\u001b[0m \u001b[38;5;28;01mdef\u001b[39;00m \u001b[38;5;21mrun_and_update\u001b[39m(\u001b[38;5;28mself\u001b[39m, state: State, \u001b[38;5;241m*\u001b[39m\u001b[38;5;241m*\u001b[39mrun_kwargs) \u001b[38;5;241m-\u001b[39m\u001b[38;5;241m>\u001b[39m \u001b[38;5;28mtuple\u001b[39m[\u001b[38;5;28mdict\u001b[39m, State]:\n\u001b[0;32m--> 533\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43m_fn\u001b[49m\u001b[43m(\u001b[49m\u001b[43mstate\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43m_bound_params\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43mrun_kwargs\u001b[49m\u001b[43m)\u001b[49m\n",
+ "Cell \u001b[0;32mIn[8], line 94\u001b[0m, in \u001b[0;36mimage_response\u001b[0;34m(state, model)\u001b[0m\n\u001b[1;32m 91\u001b[0m \u001b[38;5;129m@action\u001b[39m(reads\u001b[38;5;241m=\u001b[39m[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mprompt\u001b[39m\u001b[38;5;124m\"\u001b[39m, \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mchat_history\u001b[39m\u001b[38;5;124m\"\u001b[39m, \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mmode\u001b[39m\u001b[38;5;124m\"\u001b[39m], writes\u001b[38;5;241m=\u001b[39m[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mresponse\u001b[39m\u001b[38;5;124m\"\u001b[39m])\n\u001b[1;32m 92\u001b[0m \u001b[38;5;28;01mdef\u001b[39;00m \u001b[38;5;21mimage_response\u001b[39m(state: State, model: \u001b[38;5;28mstr\u001b[39m \u001b[38;5;241m=\u001b[39m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mdall-e-2\u001b[39m\u001b[38;5;124m\"\u001b[39m) \u001b[38;5;241m-\u001b[39m\u001b[38;5;241m>\u001b[39m State:\n\u001b[1;32m 93\u001b[0m \u001b[38;5;250m \u001b[39m\u001b[38;5;124;03m\"\"\"Generates an image response to the prompt. Optional save function to save the image to a URL.\"\"\"\u001b[39;00m\n\u001b[0;32m---> 94\u001b[0m \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mDemo error\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n\u001b[1;32m 95\u001b[0m client \u001b[38;5;241m=\u001b[39m openai\u001b[38;5;241m.\u001b[39mClient()\n\u001b[1;32m 96\u001b[0m result \u001b[38;5;241m=\u001b[39m client\u001b[38;5;241m.\u001b[39mimages\u001b[38;5;241m.\u001b[39mgenerate(\n\u001b[1;32m 97\u001b[0m model\u001b[38;5;241m=\u001b[39mmodel, prompt\u001b[38;5;241m=\u001b[39mstate[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mprompt\u001b[39m\u001b[38;5;124m\"\u001b[39m], size\u001b[38;5;241m=\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m1024x1024\u001b[39m\u001b[38;5;124m\"\u001b[39m, quality\u001b[38;5;241m=\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mstandard\u001b[39m\u001b[38;5;124m\"\u001b[39m, n\u001b[38;5;241m=\u001b[39m\u001b[38;5;241m1\u001b[39m\n\u001b[1;32m 98\u001b[0m )\n",
+ "\u001b[0;31mValueError\u001b[0m: Demo error"
+ ]
+ }
+ ],
+ "source": [
+ "while True:\n",
+ " user_input = input(\"Hi, how can I help?\")\n",
+ " if \"quit\" == user_input.lower():\n",
+ " break\n",
+ " last_action, action_result, app_state = app.run(\n",
+ " halt_after=[\"response\"], \n",
+ " inputs={\"prompt\": user_input}\n",
+ " )\n",
+ " last_message = app_state[\"chat_history\"][-1]\n",
+ " if last_message['type'] == 'image':\n",
+ " display(Image(url=last_message[\"content\"]))\n",
+ " else:\n",
+ " print(f\"🤖: {last_message['content']}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "5efe2430b34bf8e5",
+ "metadata": {},
+ "source": [
+ "[Open the UI - http://localhost:7241/](http://localhost:7241)\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "49bfbd6bf99f7b14",
+ "metadata": {},
+ "source": [
+ "## But something broke / I want to debug\n",
+ "\n",
+ "Use:\n",
+ "\n",
+ "* Application ID"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "id": "f5588457208604d4",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "app_id = \"a6d74912-9ad6-42f0-9a18-bc17c5e77eaf\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "id": "b4abab5aa575628d",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "resumed_app = (\n",
+ " ApplicationBuilder()\n",
+ " .with_graph(base_graph)\n",
+ " .initialize_from(\n",
+ " tracker,\n",
+ " resume_at_next_action=True, \n",
+ " default_state={\"chat_history\": []},\n",
+ " default_entrypoint=\"prompt\",\n",
+ " )\n",
+ " .with_tracker(tracker)\n",
+ " .with_identifiers(app_id=app_id)\n",
+ " .build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 17,
+ "id": "4b21ade9-051c-453d-b3fd-f191f970c7b4",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "[{'role': 'user', 'content': 'what is the capital of France?', 'type': 'text'},\n",
+ " {'content': 'The capital of France is Paris.',\n",
+ " 'type': 'text',\n",
+ " 'role': 'assistant'},\n",
+ " {'role': 'user', 'content': 'write hello world in java', 'type': 'text'},\n",
+ " {'content': '```\\npublic class HelloWorld {\\n public static void main(String[] args) {\\n System.out.println(\"Hello, World!\");\\n }\\n}\\n```',\n",
+ " 'type': 'code',\n",
+ " 'role': 'assistant'},\n",
+ " {'role': 'user', 'content': 'draw a pen', 'type': 'text'}]"
+ ]
+ },
+ "execution_count": 17,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "resumed_app.state[\"chat_history\"]"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 18,
+ "id": "2186ef09eaff58d9",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Hi, how can I help? \n"
+ ]
+ },
+ {
+ "data": {
+ "text/html": [
+ "<img src=\"https://oaidalleapiprodscus.blob.core.windows.net/private/org-UENfV68Ccazb3rdeYDLRWmoF/user-KU9L39oZGkNLkg6ZfSLMc4AV/img-nONYcLQepD3jBslMG4staoEb.png?st=2024-08-05T20%3A52%3A15Z&se=2024-08-05T22%3A52%3A15Z&sp=r&sv=2023-11-03&sr=b&rscd=inline&rsct=image/png&skoid=6aaadede-4fb3-4698-a8f6-684d7786b067&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2024-08-05T12%3A52%3A48Z&ske=2024-08-06T12%3A52%3A48Z&sks=b&skv=2023-11-03&sig=qsXqOHTMZhItTdL35Nd4Zic1/Q4LHaDg%2BlFG05rExkw%3D\"/>"
+ ],
+ "text/plain": [
+ "<IPython.core.display.Image object>"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Hi, how can I help? what is the capital of England?\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "🤖: The capital of England is London.\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Hi, how can I help? quit\n"
+ ]
+ }
+ ],
+ "source": [
+ "while True:\n",
+ " user_input = input(\"Hi, how can I help?\")\n",
+ " if \"quit\" == user_input.lower():\n",
+ " break\n",
+ " last_action, action_result, app_state = resumed_app.run(\n",
+ " halt_after=[\"response\"], \n",
+ " inputs={\"prompt\": user_input}\n",
+ " )\n",
+ " last_message = app_state[\"chat_history\"][-1]\n",
+ " if last_message['type'] == 'image':\n",
+ " display(Image(url=last_message[\"content\"]))\n",
+ " else:\n",
+ " print(f\"🤖: {last_message['content']}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "6bec09d1e740a30d",
+ "metadata": {},
+ "source": [
+ "## Actually what if I want to go back to a certain point in time?\n",
+ "\n",
+ "* Fork: Start with state from any checkpoint"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 19,
+ "id": "c008089be309c098",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-07-16T18:49:55.910255Z",
+ "start_time": "2024-07-16T18:49:55.906299Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "app_id = \"a6d74912-9ad6-42f0-9a18-bc17c5e77eaf\"\n",
+ "sequence_id = 4\n",
+ "# partition_key = \"\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 20,
+ "id": "a8c5631cfebe8e48",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "forked_app = (\n",
+ " ApplicationBuilder()\n",
+ " .with_graph(base_graph) # this could be different...\n",
+ " .initialize_from(\n",
+ " tracker,\n",
+ " resume_at_next_action=True, \n",
+ " default_state={\"chat_history\": []},\n",
+ " default_entrypoint=\"prompt\",\n",
+ " fork_from_app_id=app_id,\n",
+ " fork_from_sequence_id=sequence_id,\n",
+ " # fork_from_partition_key=partition_key\n",
+ " )\n",
+ " .with_tracker(tracker)\n",
+ " .build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 21,
+ "id": "2a725130e0532f0c",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-07-16T18:58:04.223560Z",
+ "start_time": "2024-07-16T18:58:04.218274Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "[{'role': 'user', 'content': 'what is the capital of France?', 'type': 'text'},\n",
+ " {'content': 'The capital of France is Paris.',\n",
+ " 'type': 'text',\n",
+ " 'role': 'assistant'},\n",
+ " {'role': 'user', 'content': 'write hello world in java', 'type': 'text'}]"
+ ]
+ },
+ "execution_count": 21,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "# show prior forked state\n",
+ "forked_app.state[\"chat_history\"]"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "e27a17968c62aa98",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Hi, how can I help? \n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "🤖: ```java\n",
+ "public class HelloWorld {\n",
+ " public static void main(String[] args) {\n",
+ " System.out.println(\"Hello, World!\");\n",
+ " }\n",
+ "}\n",
+ "```\n"
+ ]
+ }
+ ],
+ "source": [
+ "while True:\n",
+ " user_input = input(\"Hi, how can I help?\")\n",
+ " if \"quit\" == user_input.lower():\n",
+ " break\n",
+ " last_action, action_result, app_state = forked_app.run(\n",
+ " halt_after=[\"response\"], \n",
+ " inputs={\"prompt\": user_input}\n",
+ " )\n",
+ " last_message = app_state[\"chat_history\"][-1]\n",
+ " if last_message['type'] == 'image':\n",
+ " display(Image(url=last_message[\"content\"]))\n",
+ " else:\n",
+ " print(f\"🤖: {last_message['content']}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e3eb81d1f240d926",
+ "metadata": {},
+ "source": [
+ "## Want to know more?\n",
+ "\n",
+ "[Link to video walking through this notebook](https://youtu.be/hqutVJyd3TI).\n",
+ "\n",
+ "[https://github.com/dagworks-inc/burr](https://github.com/dagworks-inc/burr)\n",
+ "<img src=\"burr_qrcode.png\" width=\"125\"/>\n",
+ "\n",
+ "[Time Travel blog post & video:](https://blog.dagworks.io/p/travel-back-in-time-with-burr)\n",
+ "\n",
+ "<a href=\"https://www.youtube.com/embed/98vxhIcE6NI?si=oV1BbSUCKa1UvX5P\"><img src=\"https://img.youtube.com/vi/98vxhIcE6NI/0.jpg\"> \n",
+ "</img>\n",
+ "<a href=\"https://www.youtube.com/embed/98vxhIcE6NI?si=oV1BbSUCKa1UvX5P\">\n",
+ "\n",
+ "More blogs @ `blog.dagworks.io` e.g. [async & streaming](https://blog.dagworks.io/p/streaming-chatbot-with-burr-fastapi)\n",
+ "\n",
+ "More [examples](https://github.com/DAGWorks-Inc/burr/tree/main/examples/):\n",
+ "\n",
+ "- e.g. [test case creation](https://burr.dagworks.io/examples/creating_tests/)\n",
+ "- e.g. [multi-agent collaboration](https://github.com/DAGWorks-Inc/burr/tree/main/examples/multi-agent-collaboration)\n",
+ "\n",
+ "Follow on Twitter & LinkedIn:\n",
+ "\n",
+ "- https://x.com/burr_framework\n",
+ "- https://x.com/dagworks\n",
+ "- https://x.com/stefkrawczyk\n",
+ "- https://www.linkedin.com/in/skrawczyk/"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.4"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/examples/chatbots/index.rst b/docs/examples/chatbots/index.rst
new file mode 100644
index 00000000..5e1b99a5
--- /dev/null
+++ b/docs/examples/chatbots/index.rst
@@ -0,0 +1,10 @@
+============
+📞 Chatbots
+============
+
+.. toctree::
+ :maxdepth: 2
+
+ basic-chatbot
+ gpt-like-chatbot
+ rag-chatbot-hamilton
diff --git a/docs/examples/chatbots/rag-chatbot-hamilton.ipynb b/docs/examples/chatbots/rag-chatbot-hamilton.ipynb
new file mode 100644
index 00000000..870e2b78
--- /dev/null
+++ b/docs/examples/chatbots/rag-chatbot-hamilton.ipynb
@@ -0,0 +1,801 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "1622e1563a35aa32",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "# Conversational RAG with Burr and Hamilton\n",
+ "\n",
+ "See [GitHub example](https://github.com/DAGWorks-Inc/burr/tree/main/examples/conversational-rag/simple_example) and the accompanying video walkthrough:\n",
+ "\n",
+ "<div>\n",
+ " <iframe width=\"600\" height=\"380\" src=\"https://www.youtube.com/embed/t54DCiOH270?si=QpPNs7m2t0L0V8Va\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" referrerpolicy=\"strict-origin-when-cross-origin\" allowfullscreen></iframe>\n",
+ "</div>"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9069a73d207fd136",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "!pip install burr[start] sf-hamilton[visualization] openai "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "initial_id",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-05-10T21:02:28.908380Z",
+ "start_time": "2024-05-10T21:02:18.236814Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# Importing the necessary libraries\n",
+ "import pprint\n",
+ "from typing import Tuple\n",
+ "from hamilton import dataflows, driver\n",
+ "import burr.core\n",
+ "from burr.core import ApplicationBuilder, State, default, expr\n",
+ "from burr.core.action import action\n",
+ "from burr.tracking import LocalTrackingClient\n",
+ "import uuid"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8f1d578469a918b1",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Load your \"chain\" or conversational RAG \"pipeline\"\n",
+ "\n",
+ "We use Hamilton here. But you could use LangChain, etc., or forgo them and write your own code."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "c6a018aff1154f0b",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:47:42.057246Z",
+ "start_time": "2024-03-26T20:47:40.500075Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# Loads Hamilton DAG\n",
+ "conversational_rag = dataflows.import_module(\"conversational_rag\")\n",
+ "conversational_rag_driver = (\n",
+ " driver.Builder()\n",
+ " .with_config({}) # replace with configuration as appropriate\n",
+ " .with_modules(conversational_rag)\n",
+ " .build()\n",
+ ")\n",
+ "conversational_rag_driver.display_all_functions()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "82b3515afd2de6e4",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Create the actions that will constitute our application\n",
+ "\n",
+ "We will use the functional (vs class) approach to declaring actions here. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "6433dad5abc6eb16",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:47:42.065785Z",
+ "start_time": "2024-03-26T20:47:42.059539Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "@action(\n",
+ " reads=[\"question\", \"chat_history\"],\n",
+ " writes=[\"chat_history\"],\n",
+ ")\n",
+ "def ai_converse(state: State, vector_store: object) -> Tuple[dict, State]:\n",
+ " \"\"\"AI conversing step. Uses Hamilton to execute the conversational pipeline.\"\"\"\n",
+ " result = conversational_rag_driver.execute(\n",
+ " [\"conversational_rag_response\"],\n",
+ " inputs={\n",
+ " \"question\": state[\"question\"],\n",
+ " \"chat_history\": state[\"chat_history\"],\n",
+ " },\n",
+ " # we use overrides here because we want to pass in the vector store\n",
+ " overrides={\n",
+ " \"vector_store\": vector_store,\n",
+ " }\n",
+ " )\n",
+ " new_history = f\"AI: {result['conversational_rag_response']}\"\n",
+ " return result, state.append(chat_history=new_history)\n",
+ "\n",
+ "\n",
+ "@action(\n",
+ " reads=[],\n",
+ " writes=[\"question\", \"chat_history\"],\n",
+ ")\n",
+ "def human_converse(state: State, user_question: str) -> Tuple[dict, State]:\n",
+ " \"\"\"Human converse step -- make sure we get input, and store it as state.\"\"\"\n",
+ " state = state.update(question=user_question).append(chat_history=f\"Human: {user_question}\")\n",
+ " return {\"question\": user_question}, state"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4439e0dd39441414",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Add a hook to print the steps -- optional but shows that Burr is pluggable"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "e3c3af84fab14f39",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "from burr.core import Action\n",
+ "from burr.lifecycle import PostRunStepHook, PreRunStepHook\n",
+ "\n",
+ "class PrintStepHook(PostRunStepHook, PreRunStepHook):\n",
+ " \"\"\"Custom hook to print the action/result after each step.\"\"\"\n",
+ "\n",
+ " def pre_run_step(self, action: Action, **future_kwargs):\n",
+ " if action.name == \"ai_converse\":\n",
+ " print(\"🤔 AI is thinking...\")\n",
+ " if action.name == \"human_converse\":\n",
+ " print(\"⏳Processing input from user...\")\n",
+ "\n",
+ " def post_run_step(self, *, state: \"State\", action: Action, result: dict, **future_kwargs):\n",
+ " if action.name == \"human_converse\":\n",
+ " print(\"🎙💬\", result[\"question\"], \"\\n\")\n",
+ " if action.name == \"ai_converse\":\n",
+ " print(\"🤖💬\", result[\"conversational_rag_response\"], \"\\n\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9579b47aac2c53a0",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Create the application\n",
+ "\n",
+ "We now create the application, which is a collection of actions, and then set the transitions between the actions based on values in State.\n",
+ "\n",
+ "We also initialize initial values etc to populate the application with."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "77e9f67b660a0953",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:50:25.642660Z",
+ "start_time": "2024-03-26T20:50:25.616245Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# what we will do RAG over.\n",
+ "initial_documents = [\n",
+ " \"harrison worked at kensho\",\n",
+ " \"stefan worked at Stitch Fix\",\n",
+ " \"stefan likes tacos\",\n",
+ " \"elijah worked at TwoSigma\",\n",
+ " \"elijah likes mango\",\n",
+ " \"stefan used to work at IBM\",\n",
+ " \"elijah likes to go biking\",\n",
+ " \"stefan likes to bake sourdough\",\n",
+ "]\n",
+ "# bootstrap the vector store;\n",
+ "vector_store = conversational_rag_driver.execute(\n",
+ " [\"vector_store\"],\n",
+ " inputs={\"input_texts\": initial_documents})[\"vector_store\"]\n",
+ "# what we will initialize the application with\n",
+ "initial_state = {\n",
+ " \"question\": \"\",\n",
+ " \"chat_history\": [],\n",
+ "}\n",
+ "\n",
+ "app_id = str(uuid.uuid4())\n",
+ "app = (\n",
+ " ApplicationBuilder()\n",
+ " # add the actions\n",
+ " .with_actions(\n",
+ " # bind the vector store to the AI conversational step\n",
+ " ai_converse=ai_converse.bind(vector_store=vector_store),\n",
+ " human_converse=human_converse,\n",
+ " terminal=burr.core.Result(\"chat_history\"),\n",
+ " )\n",
+ " # set the transitions between actions\n",
+ " .with_transitions(\n",
+ " (\"ai_converse\", \"human_converse\", default),\n",
+ " (\"human_converse\", \"terminal\", expr(\"'exit' in question\")),\n",
+ " (\"human_converse\", \"ai_converse\", default),\n",
+ " )\n",
+ " # add identifiers that will help track the application\n",
+ " .with_identifiers(app_id=app_id, partition_key=\"sample_user\")\n",
+ " # initialize the state\n",
+ " .with_state(**initial_state)\n",
+ " # say what the initial action is\n",
+ " .with_entrypoint(\"human_converse\")\n",
+ " # add a hook to print the steps -- optional but shows that Burr is pluggable\n",
+ " .with_hooks(PrintStepHook())\n",
+ " # add tracking -- this will show up in the BURR UI.\n",
+ " .with_tracker(project=\"demo:conversational-rag\")\n",
+ " # build the application\n",
+ " .build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "bf5d1e084a791fa5",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:48:39.379712Z",
+ "start_time": "2024-03-26T20:48:38.701659Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# let's visualize what we have\n",
+ "app.visualize(include_conditions=True)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "430bab287b6ad9a",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Let's run the app. \n",
+ "\n",
+ "Let's run it a step at a time."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "id": "8bcfe9ca48f87618",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:50:38.782857Z",
+ "start_time": "2024-03-26T20:50:28.797204Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "app.reset_to_entrypoint() # reset the app to the entrypoint\n",
+ "user_question = input(\"Ask something (or type exit to quit): \")\n",
+ "previous_action, result, state = app.step(\n",
+ " inputs={\"user_question\": user_question},\n",
+ ")\n",
+ "print(f\"Ran action {previous_action.name} with result:\\n {pprint.pformat(result)} \\n and state:\\n {pprint.pformat(state.get_all())}\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "id": "81940578d58fd602",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:50:44.662755Z",
+ "start_time": "2024-03-26T20:50:41.919782Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# now let's run the AI conversational step\n",
+ "previous_action, result, state = app.step()\n",
+ "print(f\"Ran action {previous_action.name} with result:\\n {pprint.pformat(result)} \\n and state:\\n {pprint.pformat(state.get_all())}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "36ec2f4908c2dde2",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Let's now run the app to completion\n",
+ "\n",
+ "You could do the above for each action. Or you could tell the app to run until certain\n",
+ "actions/conditions are met."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "id": "be6c573158b65cb1",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:52:21.364028Z",
+ "start_time": "2024-03-26T20:50:52.382808Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "print(f\"Running RAG with initial state:\\n {pprint.pformat(app.state.get_all())}\")\n",
+ "while True:\n",
+ " user_question = input(\"Ask something (or type exit to quit): \")\n",
+ " previous_action, result, state = app.run(\n",
+ " halt_before=[\"human_converse\"],\n",
+ " halt_after=[\"terminal\"],\n",
+ " inputs={\"user_question\": user_question},\n",
+ " )\n",
+ " if previous_action.name == \"terminal\":\n",
+ " # reached the end\n",
+ " pprint.pprint(result)\n",
+ " break"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "169946a65f977df9",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Reloading from prior state\n",
+ "\n",
+ "Burr makes it easy to reload from a prior state. In this example we'll just use what is logged to the tracker to \"go back in time\" and reload the application to that state. \n",
+ "\n",
+ "This is useful for debugging, building the application itself, etc.\n",
+ "\n",
+ "There are two ways to load prior state:\n",
+ "1. Load the state outside the Burr Application. i.e. pass it in as initial state.\n",
+ "2. Use the ApplicationBuilder .initialize_from() method. You can optionally \"fork\" or continue an existing application this way.\n",
+ "\n",
+ "The difference between them, is that the first method is more flexible and gives you total control.\n",
+ "The second method gives you two options: \n",
+ "(a) to explicitly \"fork\" i.e. create a new application from a certain point in time from an existing application_id.\n",
+ "(b) allows you to \"pick up where you left off\" with an existing application_id, e.g. in the case of a crash, or if you wanted to start from the last conversation with a user, and continue.\n",
+ "\n",
+ "Below we show how to do the first method. Then after that the second method, to show how to fork the conversation,\n",
+ "as well as pick up the prior conversation from where it left off. \n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "id": "c7f4dd64f73ed2d8",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:52:37.419848Z",
+ "start_time": "2024-03-26T20:52:37.393869Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# set up for rewinding to a prior state -- loading it in as initial state\n",
+ "prior_app_id = app_id\n",
+ "last_sequence_id = app.sequence_id\n",
+ "rewind_to_sequence_id = last_sequence_id - 2\n",
+ "new_app_id = str(uuid.uuid4())\n",
+ "\n",
+ "project_name = \"demo:conversational-rag\"\n",
+ "# we use the tracking client here to get the state of the application at a prior sequence_id\n",
+ "tracker = LocalTrackingClient(project=project_name)\n",
+ "persisted_state = tracker.load(partition_key=\"sample_user\", \n",
+ " app_id=prior_app_id, \n",
+ " sequence_id=rewind_to_sequence_id)\n",
+ "state_values = persisted_state['state'].get_all()\n",
+ "print(f\"Loaded state from app_id:{prior_app_id}, \"\n",
+ " f\"sequence_id:{rewind_to_sequence_id}::\\n \"\n",
+ " f\"{pprint.pformat(state_values)}\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 11,
+ "id": "5ee618e3-15c0-403b-bc96-3a2faaea457e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# build our other application using the state we just loaded.\n",
+ "other_app = (\n",
+ " ApplicationBuilder()\n",
+ " # add the actions\n",
+ " .with_actions(\n",
+ " # bind the vector store to the AI conversational step\n",
+ " ai_converse=ai_converse.bind(vector_store=vector_store),\n",
+ " human_converse=human_converse,\n",
+ " terminal=burr.core.Result(\"chat_history\"),\n",
+ " )\n",
+ " # set the transitions between actions\n",
+ " .with_transitions(\n",
+ " (\"ai_converse\", \"human_converse\", default),\n",
+ " (\"human_converse\", \"terminal\", expr(\"'exit' in question\")),\n",
+ " (\"human_converse\", \"ai_converse\", default),\n",
+ " )\n",
+ " # add identifiers that will help track the application\n",
+ " .with_identifiers(app_id=new_app_id, partition_key=\"sample_user\")\n",
+ " # set state to prior state\n",
+ " .with_state(**persisted_state[\"state\"].get_all())\n",
+ " # say where we want to start\n",
+ " .with_entrypoint(\"human_converse\")\n",
+ " # add a hook to print the steps -- optional but shows that Burr is pluggable\n",
+ " .with_hooks(PrintStepHook())\n",
+ " # add tracking -- this will show up in the BURR UI.\n",
+ " .with_tracker(tracker)\n",
+ " # build the application\n",
+ " .build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "id": "34140c5864b940dc",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T20:54:24.035153Z",
+ "start_time": "2024-03-26T20:53:19.237522Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# We can now change test, debug, etc. from this prior state.\n",
+ "print(f\"Running RAG with loaded state:\\n {pprint.pformat(state_values)}\")\n",
+ "while True:\n",
+ " user_question = input(\"Ask something (or type exit to quit): \")\n",
+ " previous_action, result, state = other_app.run(\n",
+ " halt_before=[\"human_converse\"],\n",
+ " halt_after=[\"terminal\"],\n",
+ " inputs={\"user_question\": user_question},\n",
+ " )\n",
+ " if previous_action and previous_action.name == \"terminal\":\n",
+ " # reached the end\n",
+ " pprint.pprint(result)\n",
+ " break\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1d7979bc-a09b-4abd-b22b-02ca38d4a26c",
+ "metadata": {},
+ "source": [
+ "### Picking up where we left off from a prior conversation with `initialize_from()`"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 13,
+ "id": "fc62a033644c7b80",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T21:04:56.748649Z",
+ "start_time": "2024-03-26T21:04:56.742019Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# Now let's show how to use the ApplicationBuilder.initialize_from() method to pick up where we left off.\n",
+ "# This is useful if you want to continue a conversation with a user, or if you had a crash, etc.\n",
+ "\n",
+ "# set up for rewinding to a prior state -- loading it in as initial state\n",
+ "prior_app_id = app_id\n",
+ "\n",
+ "project_name = \"demo:conversational-rag\"\n",
+ "# we use the tracking client here to get the state of the application at a prior sequence_id\n",
+ "tracker = LocalTrackingClient(project=project_name)\n",
+ "pick_up_where_we_left_off_app = (\n",
+ " ApplicationBuilder()\n",
+ " # add the actions\n",
+ " .with_actions(\n",
+ " # bind the vector store to the AI conversational step\n",
+ " ai_converse=ai_converse.bind(vector_store=vector_store),\n",
+ " human_converse=human_converse,\n",
+ " terminal=burr.core.Result(\"chat_history\"),\n",
+ " )\n",
+ " # set the transitions between actions\n",
+ " .with_transitions(\n",
+ " (\"ai_converse\", \"human_converse\", default),\n",
+ " (\"human_converse\", \"terminal\", expr(\"'exit' in question\")),\n",
+ " (\"human_converse\", \"ai_converse\", default),\n",
+ " )\n",
+ " # add identifiers that will help track the application\n",
+ " .with_identifiers(app_id=prior_app_id, partition_key=\"sample_user\")\n",
+ " .initialize_from(\n",
+ " initializer=tracker,\n",
+ " resume_at_next_action=False, # we want to always start at human_converse; our entrypoint\n",
+ " default_entrypoint=\"human_converse\",\n",
+ " default_state=initial_state, # set some default state incase we can't find the prior state\n",
+ " )\n",
+ " # add a hook to print the steps -- optional but shows that Burr is pluggable\n",
+ " .with_hooks(PrintStepHook())\n",
+ " # add tracking -- this will show up in the BURR UI.\n",
+ " .with_tracker(tracker)\n",
+ " # build the application\n",
+ " .build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 14,
+ "id": "b6d23d6d6a6643d0",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-26T21:05:41.246005Z",
+ "start_time": "2024-03-26T21:05:02.855430Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "print(f\"Running RAG with loaded state:\\n {pprint.pformat(pick_up_where_we_left_off_app.state.get_all())}\")\n",
+ "while True:\n",
+ " user_question = input(\"Ask something (or type exit to quit): \")\n",
+ " previous_action, result, state = pick_up_where_we_left_off_app.run(\n",
+ " halt_before=[\"human_converse\"],\n",
+ " halt_after=[\"terminal\"],\n",
+ " inputs={\"user_question\": user_question},\n",
+ " )\n",
+ " if previous_action and previous_action.name == \"terminal\":\n",
+ " # reached the end\n",
+ " pprint.pprint(result)\n",
+ " break"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e51159c1-04a1-4b55-8615-97dc6d5c6975",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "### Forking the application using prior state with `initialize_from()`"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 22,
+ "id": "84d533ba-fd85-4b67-a6c3-30356cc9b048",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Now let's show how to use the ApplicationBuilder.initialize_from() method to fork a new application.\n",
+ "# This is useful if you want to debug/reuse prior state, rewind and try something else, etc.\n",
+ "\n",
+ "# set up for rewinding to a prior state -- loading it in as initial state\n",
+ "prior_app_id = app_id\n",
+ "new_app_id = str(uuid.uuid4())\n",
+ "\n",
+ "project_name = \"demo:conversational-rag\"\n",
+ "# we use the tracking client here to get the state of the application at a prior sequence_id\n",
+ "tracker = LocalTrackingClient(project=project_name)\n",
+ "forking_new_application = (\n",
+ " ApplicationBuilder()\n",
+ " # add the actions\n",
+ " .with_actions(\n",
+ " # bind the vector store to the AI conversational step\n",
+ " ai_converse=ai_converse.bind(vector_store=vector_store),\n",
+ " human_converse=human_converse,\n",
+ " terminal=burr.core.Result(\"chat_history\"),\n",
+ " )\n",
+ " # set the transitions between actions\n",
+ " .with_transitions(\n",
+ " (\"ai_converse\", \"human_converse\", default),\n",
+ " (\"human_converse\", \"terminal\", expr(\"'exit' in question\")),\n",
+ " (\"human_converse\", \"ai_converse\", default),\n",
+ " )\n",
+ " # add identifiers that will help track the application\n",
+ " .with_identifiers(app_id=new_app_id, partition_key=\"sample_user\")\n",
+ " .initialize_from(\n",
+ " initializer=tracker,\n",
+ " resume_at_next_action=False, # we want to always start at human_converse; our entrypoint\n",
+ " default_entrypoint=\"human_converse\",\n",
+ " default_state=initial_state, # set some default state incase we can't find the prior state\n",
+ " fork_from_app_id=prior_app_id, # <---- The new addition \n",
+ " fork_from_partition_key=\"sample_user\", # <---- The new addition \n",
+ " fork_from_sequence_id=5, # <---- The new addition \n",
+ " )\n",
+ " # add a hook to print the steps -- optional but shows that Burr is pluggable\n",
+ " .with_hooks(PrintStepHook())\n",
+ " # add tracking -- this will show up in the BURR UI.\n",
+ " .with_tracker(tracker)\n",
+ " # build the application\n",
+ " .build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 23,
+ "id": "a9086e58-eeaa-4886-a113-5c7fd5fe0af0",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print(f\"Running RAG with loaded state:\\n {pprint.pformat(forking_new_application.state.get_all())}\")\n",
+ "while True:\n",
+ " user_question = input(\"Ask something (or type exit to quit): \")\n",
+ " previous_action, result, state = forking_new_application.run(\n",
+ " halt_before=[\"human_converse\"],\n",
+ " halt_after=[\"terminal\"],\n",
+ " inputs={\"user_question\": user_question},\n",
+ " )\n",
+ " if previous_action and previous_action.name == \"terminal\":\n",
+ " # reached the end\n",
+ " pprint.pprint(result)\n",
+ " break"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "d6523a54-e333-4d5e-941d-d3b28b940500",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# this should print some warnings:\n",
+ "new_app_id = str(uuid.uuid4())\n",
+ "\n",
+ "project_name = \"demo:conversational-rag\"\n",
+ "# we use the tracking client here to get the state of the application at a prior sequence_id\n",
+ "tracker = LocalTrackingClient(project=project_name)\n",
+ "bad_fork = (\n",
+ " ApplicationBuilder()\n",
+ " # add the actions\n",
+ " .with_actions(\n",
+ " # bind the vector store to the AI conversational step\n",
+ " ai_converse=ai_converse.bind(vector_store=vector_store),\n",
+ " human_converse=human_converse,\n",
+ " terminal=burr.core.Result(\"chat_history\"),\n",
+ " )\n",
+ " # set the transitions between actions\n",
+ " .with_transitions(\n",
+ " (\"ai_converse\", \"human_converse\", default),\n",
+ " (\"human_converse\", \"terminal\", expr(\"'exit' in question\")),\n",
+ " (\"human_converse\", \"ai_converse\", default),\n",
+ " )\n",
+ " # add identifiers that will help track the application\n",
+ " .with_identifiers(app_id=new_app_id, partition_key=\"sample_user\")\n",
+ " .initialize_from(\n",
+ " initializer=tracker,\n",
+ " resume_at_next_action=False, # we want to always start at human_converse; our entrypoint\n",
+ " default_entrypoint=\"human_converse\",\n",
+ " default_state=initial_state, # set some default state incase we can't find the prior state\n",
+ " fork_from_app_id=\"NO_SUCH_APP_ID\", # <---- The new addition \n",
+ " )\n",
+ " # add a hook to print the steps -- optional but shows that Burr is pluggable\n",
+ " .with_hooks(PrintStepHook())\n",
+ " # add tracking -- this will show up in the BURR UI.\n",
+ " .with_tracker(tracker)\n",
+ " # build the application\n",
+ " .build()\n",
+ ")"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.4"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/examples/data-science/_ml_training.png b/docs/examples/data-science/_ml_training.png
new file mode 100644
index 00000000..4b9fdb42
Binary files /dev/null and b/docs/examples/data-science/_ml_training.png differ
diff --git a/docs/examples/data-science/_simulation.png b/docs/examples/data-science/_simulation.png
new file mode 100644
index 00000000..d2d45f02
Binary files /dev/null and b/docs/examples/data-science/_simulation.png differ
diff --git a/docs/examples/data-science/index.rst b/docs/examples/data-science/index.rst
new file mode 100644
index 00000000..327d91ac
--- /dev/null
+++ b/docs/examples/data-science/index.rst
@@ -0,0 +1,9 @@
+===============
+🧪 Data science
+===============
+
+.. toctree::
+ :maxdepth: 2
+
+ ml_training
+ simulation
diff --git a/docs/examples/data-science/ml_training.md b/docs/examples/data-science/ml_training.md
new file mode 100644
index 00000000..9ab034e9
--- /dev/null
+++ b/docs/examples/data-science/ml_training.md
@@ -0,0 +1,203 @@
+# Hyperparameter tuning
+
+Hyperparameter tuning 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 a WIP! Please see the placeholder/example sketch in the [repository](https://github.com/DAGWorks-Inc/burr/tree/main/examples/ml-training) and contribute back if you have ideas via associated issue [here](https://github.com/DAGWorks-Inc/burr/issues/138).
+
+## High-level view
+
+A machine learning training system can easily be modeled as a state machine.
+
+While often, this is more of a DAG (E.G. `query_data` -> `feature_engineer` -> `train_model` -> `evaluate_model`), there
+are some interesting reasons this as a state machine.
+
+## More granular training routines
+
+If, rather than treating `train` as a action, you treat `train_epoch` as an action, you can utilize the abstractions
+burr represents to get the following benefits:
+
+### Checkpointing
+
+You can store the current params + best model (or pointers to them). Then go back to the failure point. This allows you
+to recover from failure in a generic way.
+
+### Decoupling training logic from termination condition
+
+You can have a condition that checks training completeness based on metric history, which is different from the training logic itself.
+This allows you to easily swap in and out termination conditions (testing them against each other or running different ones in different scenarios),
+as well as easy reuse.
+
+### Visibility into lower-level training
+
+Similar to [hooks](https://lightning.ai/docs/pytorch/stable//extensions/callbacks.html) in pytorch lightning,
+you can use Burr hooks to log metrics, visualize, etc... at each step. This allows you to have a more granular view of training that updates live
+(obviuosly depending on the UI/model-monitoring you're using.)
+
+## Human in the loop
+
+While some models are trained in a single-shot and shipped to production, many require human input.
+Burr can be used to express training, then checkpoint/pause the state while a human is evaluating it,
+and have their input (e.g. go/no-go) passed in as an [input parameter](https://burr.dagworks.io/concepts/actions/#runtime-inputs).
+
+Note that this still requires a scheduling tool (say a task executor that runs until the next human input is needed),
+but that task executor does not need to be complicated (all it needs to do is run a job when prompted, and possibly on a chron schedule).
+
+## Hyperparameter training
+
+Similar to epoch training, hyperparameter training can be modeled as a state machine. The system makes a decision about what
+to look for next based on the prior results. Furthermore, one can model a step that handles multiple jobs, keeping them alive/
+launching new ones as they complete (based on state).
+
+![diagram](./_ml_training.png).
+
+
+## Code example
+
+This uses the class-based API for defining an `action`.
+
+```python
+"""
+This is a sketch of an example of a machine learning training pipeline using Burr where you
+want to do something dynamic like train a model for a variable number of iterations and then
+pick the best model from each of the iterations based on some validation metric. E.g. hyperparameter search.
+
+You could adjust this example to continue training a model until you reach a certain validation metric,
+or hit a max number of iterations (or epochs), etc.
+
+Note: this example uses the class based API to define the actions. You could also use the function+decorator API.
+"""
+import burr.core.application
+from burr.core import Action, Condition, State, default
+
+
+class ProcessDataAction(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["data_path"]
+
+ def run(self, state: State, **run_kwargs) -> dict:
+ """This is where you would load and process your data.
+ You can take in state and reference object fields.
+
+ You need to return a dictionary of the results that `update()` will then use to update the state.
+ """
+ # load data, and run some feature engineering -- create the data sets
+ # TODO: fill in
+ return {"training_data": "SOME_OBJECT/PATH", "evaluation_data": "SOME_OBJECT/PATH"}
+
+ @property
+ def writes(self) -> list[str]:
+ return ["training_data", "evaluation_data"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.update(
+ training_data=result["training_data"], evaluation_data=result["evaluation_data"]
+ )
+
+
+class TrainModel(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["training_data", "iterations"]
+
+ def run(self, state: State, **run_kwargs) -> dict:
+ """This is where you'd build the model and on each iteration do something different.
+ E.g. hyperparameter search.
+ """
+ # train the model, i.e. run one "iteration" whatever that means for you.
+ # TODO: fill in
+ return {
+ "model": "SOME_MODEL",
+ "iterations": state["iterations"] + 1,
+ "metrics": "SOME_METRICS",
+ }
+
+ @property
+ def writes(self) -> list[str]:
+ return ["models", "training_metrics", "iterations"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.update(
+ iterations=result["iterations"], # set current iteration value
+ ).append(
+ models=result["model"], # append -- note this can get big if your model is big
+ # so you'll want to overwrite but store the conditions, or log somewhere
+ metrics=result["metrics"], # append the metrics
+ )
+
+
+class ValidateModel(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["models", "evaluation_data"]
+
+ def run(self, state: State, **run_kwargs) -> dict:
+ """Compute validation metrics using the model and evaluation data."""
+ # TODO: fill in
+ return {"validation_metrics": "SOME_METRICS"}
+
+ @property
+ def writes(self) -> list[str]:
+ return ["validation_metrics"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.append(validation_metrics=result["validation_metrics"])
+
+
+class BestModel(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["validation_metrics", "models"]
+
+ def run(self, state: State, **run_kwargs) -> dict:
+ """Select the best model based on the validation metrics."""
+ # TODO: fill in
+ return {"best_model": "SOME_MODEL"}
+
+ @property
+ def writes(self) -> list[str]:
+ return ["best_model"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.update(best_model=result["best_model"])
+
+
+def application(iterations: int) -> burr.core.application.Application:
+ return (
+ burr.core.ApplicationBuilder()
+ .with_state(
+ data_path="data.csv",
+ iterations=10,
+ training_data=None,
+ evaluation_data=None,
+ models=[],
+ training_metrics=[],
+ validation_metrics=[],
+ best_model=None,
+ )
+ .with_actions(
+ process_data=ProcessDataAction(),
+ train_model=TrainModel(),
+ validate_model=ValidateModel(),
+ best_model=BestModel(),
+ )
+ .with_transitions(
+ ("process_data", "train_model", default),
+ ("train_model", "validate_model", default),
+ ("validate_model", "best_model", Condition.expr(f"iterations>{iterations}")),
+ ("validate_model", "train_model", default),
+ )
+ .with_entrypoint("process_data")
+ .build()
+ )
+
+
+if __name__ == "__main__":
+ app = application(100) # doing good data science is up to you...
+ app.visualize(output_file_path="statemachine", include_conditions=True, view=True, format="png")
+ # you could run things like this:
+ # last_action, result, state = app.run(halt_after=["best_model"])
+```
diff --git a/docs/examples/data-science/simulation.md b/docs/examples/data-science/simulation.md
new file mode 100644
index 00000000..e9c789eb
--- /dev/null
+++ b/docs/examples/data-science/simulation.md
@@ -0,0 +1,151 @@
+# Simulations
+
+At a high level, simulations generally run over a set of time steps and maintain state.
+The user then manages the state, which becomes the input to the next time step, as well
+as output data to analyze. Burr provides a simple way for you to construct, manage, and
+introspect the state of your simulation.
+
+This example is a WIP -- see the placeholder/example sketch in the [repository](https://github.com/DAGWorks-Inc/burr/tree/main/examples/simulation).
+We're actively looking for contributors + ideas via [this issue](https://github.com/DAGWorks-Inc/burr/issues/136) to track.
+
+
+For instance:
+
+## Time-series Forecast
+A time-series forecast will execute a computation (say, feature-engineering + a model) at each step for which the user is predicting. The
+user will then store a history of data (predictions, raw data, etc...), and use that to pass into the next step in the simulation.
+
+The merge into state + query from state capabilities can be complicated -- windowed operations, rolling averages, etc.. may all be useful,
+and they may want to visualize simulations live (E.G. by tracking some metrics as it goes along). Burr is a natural way to persist this -- even
+if it is just a few actions (`query_data`, `feature_engineer`, `forecast`), the persistence capabilities + hooks can allow
+for logging to whatever live framework one wants to visualize, and centralizing the logic of reading from/writing to state.
+
+![diagram](./_simulation.png).
+
+
+## Portfolio Construction
+
+This is a special case of time-series forecasting, in which one wants to simulate a financial portfolio. Actions might be:
+- `query_data` - get data from state/load externally
+- `prepare_data` - format to something you can make predictions on
+- `forecast` - runs a model to do stock-price fore asting
+- `construct_portfolio` - uses the forecast to construct a portfolio
+- `evaluate_portfolio` - evaluates the portfolio
+
+Each one of these could be a DAG using [Hamilton](https://github.com/dagworks-inc/hamilton), or running any custom code.
+
+## Multi-agent simulation
+
+See [Stanford Smallville](https://hai.stanford.edu/news/computational-agents-exhibit-believable-humanlike-behavior) for an example.
+For multiple independent "agents", Burr could help model the way they interact. This could be multiplke Burr applications, applications called within
+actions, or an action that loops over all "users". We are still figuring out the best way to model this, so reach out if you have ideas!
+
+## Code example
+
+```python
+"""
+This module contains a stubbed out structure for one way of doing a simulation
+ for forecasting purposes.
+
+For more sophisticated forecasts where prediction of one timestep
+depends on the previous timestep, you need to forecast on a per-step basis. So
+you're effectively simulating the future at each step. This is a simple example of
+how you might structure such a simulation.
+"""
+
+from typing import Tuple
+
+from burr.core import Application, ApplicationBuilder, State, expr
+from burr.core.action import action
+
+
+@action(reads=["data_path"], writes=["data"])
+def prepare_data(state: State) -> Tuple[dict, State]:
+ """This would pull the data, prepare it, and return it."""
+ # pull data, prepare as necessary
+ result = {"data": _process_data(state["data_path"])}
+ return result, state.update(**result)
+
+
+@action(reads=["data", "simulation_start"], writes=["model"])
+def build_model(state: State) -> Tuple[dict, State]:
+ """This would fit the model on data before the simulation start date."""
+ training_data = state["data"]
+ model = _fit_model(training_data, upto=state["simulation_start"])
+ result = {"model": model}
+ return result, state.update(**result)
+
+
+@action(
+ reads=["simulation_start", "simulation_end", "model", "data", "current_timestep"],
+ writes=["data"],
+)
+def forecast(state: State) -> Tuple[dict, State]:
+ """This action forecasts the next timestep in the simulation and appends it to data."""
+ model = state["model"]
+ data = state["data"]
+ start_time = state["simulation_start"]
+ current_time_step = state.get("current_timestep", start_time)
+ next_timestep = _forecast_timestep(model, data, current_time_step)
+ data = _update_data(data, next_timestep)
+ result = {"data": data, "current_timestep": next_timestep}
+ return result, state.update(**result)
+
+
+@action(reads=["data"], writes=[])
+def terminate(state: State) -> Tuple[dict, State]:
+ """This is a terminal step that would save the forecast or do something else."""
+ return {}, state
+
+
+def application() -> Application:
+ app = (
+ ApplicationBuilder()
+ .with_actions(prepare_data, build_model, forecast, terminate)
+ .with_transitions(
+ ("prepare_data", "build_model"),
+ ("build_model", "forecast"),
+ ("forecast", "forecast", expr("current_timestep<simulation_end")),
+ ("forecast", "terminate", expr("current_timestep>=simulation_end")),
+ )
+ .with_state(
+ data_path="SOME_PATH",
+ simulation_start="some-value",
+ simulation_end="some-end-value",
+ )
+ .with_entrypoint("prepare_data")
+ .build()
+ )
+ return app
+
+
+# --- stubbed out functions to fill out for the simulation
+def _process_data(data_path: str) -> object:
+ """This function would read and process data from a file."""
+ return {}
+
+
+def _fit_model(data: object, upto: str) -> object:
+ """This function would fit a model on data upto a certain date."""
+ return {}
+
+
+def _forecast_timestep(model: object, data: object, current_timestep: str) -> object:
+ """This function would forecast the next timestep in the simulation given the model and data."""
+ return {}
+
+
+def _update_data(data: object, next_timestep: object) -> object:
+ """This function would update the data with the forecasted timestep."""
+ return {}
+
+
+if __name__ == "__main__":
+ _app = application()
+ _app.visualize(
+ output_file_path="statemachine", include_conditions=True, view=True, format="png"
+ )
+ # you could run things like this:
+ # last_action, result, state = _app.run(halt_after=["terminate"])
+
+```
diff --git a/docs/examples/deployment.rst b/docs/examples/deployment.rst
deleted file mode 100644
index 41ca182e..00000000
--- a/docs/examples/deployment.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-=======================
-Deployment
-=======================
-
-This section describes a few ways to deploy your Burr application.
-
-----------------
-AWS Lambda
-----------------
-Burr can be deployed within a Lambda function. This is a good option if you want to run your
-application in response to events, or if you want to run your application in a serverless environment.
-
-See `this example <https://github.com/DAGWorks-Inc/burr/tree/main/examples/deployment/aws/lambda>`_ for step
-by step instructions on how to deploy a Burr application to AWS Lambda.
diff --git a/docs/examples/deployment/_web-server.png b/docs/examples/deployment/_web-server.png
new file mode 100644
index 00000000..20b85af4
Binary files /dev/null and b/docs/examples/deployment/_web-server.png differ
diff --git a/docs/examples/deployment/aws.md b/docs/examples/deployment/aws.md
new file mode 100644
index 00000000..99869df3
--- /dev/null
+++ b/docs/examples/deployment/aws.md
@@ -0,0 +1,101 @@
+# AWS Lambda
+
+[AWS Lambda](https://aws.amazon.com/lambda/) - serverless computation service in AWS.
+
+Here we have an example how to deploy "hello-world" AWS Lambda with a simple Burr application.
+This example is based on the official instruction: https://docs.aws.amazon.com/lambda/latest/dg/python-image.html#python-image-instructions
+
+Burr can be deployed within a Lambda function. This is a good option if you want to run your
+application in response to events, or if you want to run your application in a serverless environment.
+
+See the [repository on GitHub](https://github.com/DAGWorks-Inc/burr/tree/main/examples/deployment/aws/lambda) for the full code example and for step-by-step instructions on how to deploy a Burr application to AWS Lambda.
+
+## Prerequisites
+
+- **AWS CLI Setup**: Make sure the AWS CLI is set up on your machine. If you haven't done this yet, no worries! You can follow the [Quick Start guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html) for easy setup instructions.
+
+## Step-by-Step Guide
+
+### 1. Build Docker image:
+
+- **Build Docker image for deploy in AWS ECR**
+
+ ```shell
+ docker build --platform linux/amd64 -t aws-lambda-burr .
+ ```
+
+- **Local tests:**
+
+ Run Docker container:
+
+ ```shell
+ docker run -p 9000:8080 aws-lambda-burr
+ ```
+
+ Send test request to check if Docker container executes it correctly:
+
+ ```shell
+ curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"body": {"number":3}}'
+ ```
+
+### 2. Create AWS ECR repository:
+
+Ensure the AWS account number (`111122223333`) is correctly replaced with yours:
+
+- **Authenticate Docker to Amazon ECR**:
+
+ Retrieve an authentication token to authenticate your Docker client to your Amazon Elastic Container Registry (ECR):
+
+ ```shell
+ aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com
+ ```
+
+- **Create the ECR Repository**:
+
+ ```shell
+ aws ecr create-repository --repository-name aws-lambda-burr \
+ --region us-east-1 \
+ --image-scanning-configuration scanOnPush=true \
+ --image-tag-mutability MUTABLE
+ ```
+
+### 3. Deploy the Image to AWS ECR
+
+Ensure the AWS account number (`111122223333`) is correctly replaced with yours:
+
+```shell
+docker tag aws-lambda-burr 111122223333.dkr.ecr.us-east-1.amazonaws.com/aws-lambda-burr:latest
+docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/aws-lambda-burr:latest
+```
+
+### 4. Create a simple AWS Lambda role:
+
+Example of creating an AWS Role for Lambda execution:
+
+```shell
+aws iam create-role \
+ --role-name lambda-ex \
+ --assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
+```
+
+### 5. Create AWS Lambda
+
+Ensure the AWS account number (`111122223333`) is correctly replaced with yours:
+
+```shell
+aws lambda create-function \
+ --function-name aws-lambda-burr \
+ --package-type Image \
+ --code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/aws-lambda-burr:latest \
+ --role arn:aws:iam::111122223333:role/lambda-ex
+```
+
+### 6. Test AWS Lambda
+
+```shell
+aws lambda invoke \
+ --function-name aws-lambda-burr \
+ --cli-binary-format raw-in-base64-out \
+ --payload '{"body": {"number": 5}}' \
+ response.json
+```
diff --git a/docs/examples/deployment/index.rst b/docs/examples/deployment/index.rst
new file mode 100644
index 00000000..7fb0c272
--- /dev/null
+++ b/docs/examples/deployment/index.rst
@@ -0,0 +1,9 @@
+=============
+✈ Deployment
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ web-server
+ aws
diff --git a/docs/examples/deployment/web-server.md b/docs/examples/deployment/web-server.md
new file mode 100644
index 00000000..495dad11
--- /dev/null
+++ b/docs/examples/deployment/web-server.md
@@ -0,0 +1,224 @@
+# Web service (FastAPI, Flask, Django, etc.)
+
+Burr is meant to run interactive apps. This means running it as part of a web-service that
+responds to requests, manages state, and documents its capabilities. The interactive nature of Burr
+(moving in/out of programmatic control) means we want to think carefully about how to expose
+our Burr applications to the web. Burr makes it natural to integrate with a web-server such as FastAPI.
+
+In this tutorial we will use the [email assistant example](https://github.com/DAGWorks-Inc/burr/tree/main/examples/email-assistant) as a walk-through.
+Our goal is to expose the email assistant in a web-server that a UI can easily be built on top of.
+While we will not be building the UI here, we will link out to the final product for you to explore.
+
+## Email Assistant
+
+The email assistant is an example of a "human-in-the-loop" generative AI application. This means that
+it requires human assistance at multiple points to build a better product.
+
+### Running the example
+
+If you want to get a sense for how this looks, open the burr UI:
+
+```bash
+pip install "burr[start]"
+burr
+```
+
+Then navigate to the email assistant via http://localhost:7241/demos/email-assistant,
+
+You can create a new "application" and see it run through, with the telemetry on the right side.
+
+### Conceptual Model
+At a high-level, the email assistant does the following:
+
+1. Accepts an email + instructions to respond
+2. Comes up with a set of clarifying questions (if the LLM deems it required)
+3. Using the answer to those questions, generates a draft
+4. Accepts feedback to that draft and generates another one, repeating until the user is happy
+5. Returns the final draft
+
+Due to the stochastic, often complex nature of LLMs, this has been shown to be one of the most promising
+applications -- a collaboration between humans and AI to quickly build high-quality responses.
+
+### Modeling with Burr
+This is a brief overview, for a more in-depth look at the email assistant, see the [email assistant example](https://github.com/DAGWorks-Inc/burr/tree/main/examples/email-assistant).
+To model our email assistant with burr, we can use the following diagram:
+
+![Modeling](./_web-server.png)
+
+There are three points at which the user can interact:
+1. `process_input`: This is where the user inputs the email and instructions
+2. `clarify_instructions`: The LLM has created a set of clarification questions
+3. `process_feedback`: The user has provided feedback on the draft
+
+(3) repeats until the user is happy with the draft (in our implementation this occurs when the feedback they provide is empty)
+
+Recall that we use the word "application" in Burr to refer to an instance of this process above
+(with persisted state).
+
+You can see the full application in [application.py](https://github.com/DAGWorks-Inc/burr/tree/main/examples/email-assistant/application.py).
+
+## Integrating in a web server
+
+For this example we will use [FastApi](https://fastapi.tiangolo.com/) and [pydantic](https://docs.pydantic.dev/latest/),
+but it should work with any other web-stack that uses python.
+
+### Endpoints
+
+We construct the following endpoints:
+
+1. `POST /create`: This will create a new application and return the ID
+2. `PUT /initialize_draft/{id}/`: This calls out to `process_input`, passing in the email and instructions
+3. `PUT /clarify_instructions/{id}`: This will gives answers back to the LLM
+4. `PUT /process_feedback/{id}`: This will give feedback back to the LLM
+5. `GET /{id}/state`: This will return the current state of the application
+
+The `GET` endpoint allows us to get the current state of the application -- this enables
+the user to reload if they quit the browser/get distracted. Each of these endpoints will return the full state of the application,
+which can be rendered on the frontend. Furthermore, it will indicate the next API endpoint
+we call, which allows the UI to render the appropriate form and
+
+Using FastAPI + Pydantic, this becomes very simple to implement. First, let's add a utility to
+get the `application` object. This will use a cached version or instantiate it:
+
+```python
[email protected]_cache(maxsize=128)
+def _get_application(app_id: str) -> Application:
+ app = email_assistant_application.application(app_id=app_id)
+ return app
+```
+
+All this does is call to our function `application` in `email_assistant` that
+recreates the application. We have not included the `create` function here,
+but it calls out to the same API.
+
+### Data Model
+
+Let's then define a pydantic model to represent the state, and the app object in FastAPI:
+```python
+
+class EmailAssistantState(pydantic.BaseModel):
+ app_id: str
+ email_to_respond: Optional[str]
+ response_instructions: Optional[str]
+ questions: Optional[List[str]]
+ answers: Optional[List[str]]
+ drafts: List[str]
+ feedback_history: List[str]
+ final_draft: Optional[str]
+ # This stores the next step, which tells the frontend which ones to call
+ next_step: Literal["process_input", "clarify_instructions", "process_feedback", None]
+
+ @staticmethod
+ def from_app(app: Application):
+ # implementation left out, call app.state and translate to pydantic model
+ # we can use `app.get_next_action()` to get the next step and return it to the user
+ ...
+```
+
+### Execution
+
+Next, we can run through to the next step, starting from any point:
+
+```python
+def _run_through(project_id: str, app_id: Optional[str], inputs: Dict[str, Any]) -> EmailAssistantState:
+ email_assistant_app = _get_application(project_id, app_id)
+ email_assistant_app.run( # Using this as a side-effect, we'll just get the state aft
+ halt_before=["clarify_instructions", "process_feedback"],
+ halt_after=["final_result"],
+ inputs=inputs,
+ )
+ return EmailAssistantState.from_app(email_assistant_app)
+```
+
+We `halt_before` the steps that require user instructions, and `halt_after`
+the final result. This allows us to get the state after each step.
+
+Finally, we can define our endpoints. For instance:
+
+```python
[email protected]("/provide_feedback/{id}")
+def provide_feedback(project_id: str, app_id: str, feedback: Feedback) -> EmailAssistantState:
+ return _run_through(project_id, app_id, dict(feedback=feedback.feedback))
+```
+
+This represents a simple but powerful architecture. We can continue calling these endpoints
+until we're at a "terminal" state, at which point we can always ask for the state.
+If we decide to add more input steps, we can modify the state machine and add more input steps.
+We are not required to hold state in the app (it is all delegated to Burr's persistence),
+so we can easily load up from any given point, allowing the user to wait for seconds,
+minutes, hours, or even days before continuing.
+
+As the frontend simply renders based on the current state and the next step, it will always
+be correct, and the user can always pick up where they left off. With Burr's telemetry capabilities
+they can debug any state-related issues, ensuring a smooth user experience.
+
+### Persistence
+
+Note that we never called out to databases. It all just magically worked.. This is all because we decouple the persistence
+layer from the web-call. The application will be persisted (to whatever database you want),
+by burr's plugin capabilities -- read more [here](https://burr.dagworks.io/concepts/state-persistence/).
+This greatly reduces the amount you have to think about when developing. As Burr persistence is
+pluggable, you can write to your own database with whichever schema you prefer, customizing
+the schema for your project or using a generic one (state is just a JSON object -- you can easily serialize/deseriealize it).
+
+### Additional concerns
+
+#### Scaling
+
+But [is this webscale](https://www.youtube.com/watch?v=b2F-DItXtZs)? As anything, it depends on how you implement it.
+Two factors determine the scalability of this system:
+
+1. database layer -- can the database support the volume of inputs/outputs?
+2. compute layer -- can the server run fast enough to keep up with the users?
+
+For the database layer, it depends largely on the underlying database, as well as the
+schema you use. That said, Burr makes it easier due to natural partitioning of the data
+into `application_id` and `partition_key` (the latter could be the `user ID`), allowing common
+operations (such as _give me all applications for X user_ and _give me the state of application Y_)
+simple if you index your state table on the application ID and `partition_key`.
+
+For the compute layer, you can simply scale horizontally. The only tricky aspect is ensuring state synchronization
+and locking. As we cached the application object, we could potentially get into a position
+in which the state is out of sync. To solve this, you can either:
+
+1. Use a locking method (either in the database) to ensure that only one server is running a given application at any point
+2. Use sticky sessions/sharding to ensure that a given user always hits the same server
+3. Handle forking/resolution of state at the persistence layer with a custom implementation
+
+Or possibly some combination of the above.
+
+#### Async
+
+While we implemented synchronous calls, you can easily make these async by using `async def` and `await` in the appropriate places,
+and using the `arun` method in Burr. Read more about async capabilities in [applications](https://burr.dagworks.io/concepts/state-machine/),
+and [actions](https://burr.dagworks.io/concepts/actions/).
+
+#### Streaming
+
+You can use streaming to send back the stream of the output at any given point. You do this by creating a
+[streaming action](https://burr.dagworks.io/concepts/streaming-actions/). You can then integrate with the
+streaming respose in FastAPI to send back the stream of the output. You can do this with any steps
+(intermediate or final) in your application.
+
+#### Authentication/Data access
+
+While Burr does not operate at the data access layer, this can be easily handles at the application layer.
+Any authentication system will tell you the user ID, which you can look in your DB to determine access
+to your partition key.
+
+## Wrap-up
+
+In this tutorial we showed how to integrate Burr into a web-server. We used FastAPI and Pydantic
+to create a simple but powerful API that allows users to interact with the email assistant, leveraging
+Burr's persistence capabilities to ensure that the user can always pick up where they left off.
+
+At a high-level, the real value of representing your application as a state machine (as Burr does)
+is that it all becomes easier to think about. You don't have to conceptually model state persistence,
+dataflow, and the web infrastructure in one piece -- they can all be built separately.
+
+In the future we will be automating this process, allowing you to generate a FastAPI app from the Burr application.
+
+For now though, you can find the resources for the current implementation:
+- [application.py](https://github.com/DAGWorks-Inc/burr/tree/main/examples/email-assistant/application.py)
+- [server.py](https://github.com/DAGWorks-Inc/burr/tree/main/examples/email-assistant/server.py)
+- [ui](https://github.com/DAGWorks-Inc/burr/tree/main/telemetry/ui/src/examples/EmailAssistant.tsx) -- this uses [ReactQuery](https://tanstack.com/query/latest/docs/framework/react/overview) to call the API and [react](https://react.dev/) to render the state.
diff --git a/docs/examples/test-case-creation-burr.png b/docs/examples/guardrails/_creating_tests.png
similarity index 100%
rename from docs/examples/test-case-creation-burr.png
rename to docs/examples/guardrails/_creating_tests.png
diff --git a/docs/examples/creating_tests.rst b/docs/examples/guardrails/creating_tests.rst
similarity index 98%
rename from docs/examples/creating_tests.rst
rename to docs/examples/guardrails/creating_tests.rst
index 31fb86ff..79ac2d52 100644
--- a/docs/examples/creating_tests.rst
+++ b/docs/examples/guardrails/creating_tests.rst
@@ -32,7 +32,7 @@ Steps:
3. Note the project name, partition key, app id, and sequence id for the state you want to test.
See orange lines indicating what to pull from the UI in the image below.
- .. image:: test-case-creation-burr.png
+ .. image:: _creating_tests.png
:alt: What you need to pull from the UI for running the command.
:align: center
diff --git a/docs/examples/guardrails/index.rst b/docs/examples/guardrails/index.rst
new file mode 100644
index 00000000..e6f078a2
--- /dev/null
+++ b/docs/examples/guardrails/index.rst
@@ -0,0 +1,8 @@
+=============
+🚧 Guardrails
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ creating_tests
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
index 59ff152c..ed9061bf 100644
--- a/docs/examples/index.rst
+++ b/docs/examples/index.rst
@@ -10,11 +10,11 @@ for the latest.
Examples of more complex/powerful use-cases of Burr. Download/copy these to adapt to your use-cases.
.. toctree::
- simple
- chatbot
- agents
- deployment
- web-server
- creating_tests
- ml_training
- simulation
+ :maxdepth: 2
+
+ simple/index
+ chatbots/index
+ agents/index
+ deployment/index
+ guardrails/index
+ data-science/index
diff --git a/docs/examples/ml_training.rst b/docs/examples/ml_training.rst
deleted file mode 100644
index c018a190..00000000
--- a/docs/examples/ml_training.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-====================
-ML Model Training
-====================
-
-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.
-
-For more information/contribution options, see the placeholder/example sketch in the `repository <https://github.com/DAGWorks-Inc/burr/tree/main/examples/ml-training>`_.
diff --git a/docs/examples/simple.rst b/docs/examples/simple.rst
deleted file mode 100644
index dfee5a37..00000000
--- a/docs/examples/simple.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-====================
-Simple examples
-====================
-
-The following are all simple examples to give you a sense of how to use Burr. They're mostly toy-examples
-but they show a few concepts. If you're interested in more real-life applications, skip ahead to
-:ref:`state-persistence <chatbots>`.
-
-- `cowsay <https://github.com/DAGWorks-Inc/burr/tree/main/examples/other-examples/cowsay>`_
-- `counter <https://github.com/DAGWorks-Inc/burr/tree/main/examples/hello-world-counter>`_
-- `corgi adventure game <https://github.com/DAGWorks-Inc/burr/tree/main/examples/llm-adventure-game>`_
diff --git a/docs/examples/simple/choose-your-own-adventure.ipynb b/docs/examples/simple/choose-your-own-adventure.ipynb
new file mode 100644
index 00000000..a64b3ba6
--- /dev/null
+++ b/docs/examples/simple/choose-your-own-adventure.ipynb
@@ -0,0 +1,227 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Choose your own adventure\n",
+ "\n",
+ "A simple text-based game in the style of 80s adventure games in which you play a hungry corgi."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Setup"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import json\n",
+ "from typing import Optional, Tuple\n",
+ "\n",
+ "from burr.core import action, Application, ApplicationBuilder, State, default, when\n",
+ "from openai import OpenAI"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# set your OpenAI API key to run the rest of the notebook\n",
+ "import os\n",
+ "os.environ[\"OPENAI_API_KEY\"] = ..."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Define actions"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "\n",
+ "@action(reads=[\"challenges\"], writes=[\"current_challenge\"])\n",
+ "def start(state: State) -> State:\n",
+ " \"\"\"Load the first challenge as the current challenge\"\"\"\n",
+ " current_challenge = state[\"challenges\"][0]\n",
+ " return state.update(current_challenge=current_challenge)\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"current_challenge\"], writes=[\"attempts\"])\n",
+ "def prompt_for_challenge(state: State) -> State:\n",
+ " \"\"\"Request user input to solve the current challenge\"\"\"\n",
+ " current_challenge = state[\"current_challenge\"]\n",
+ " user_response = input(f'{current_challenge}. What do you do?\\n $ ')\n",
+ " return state.append(attempts=user_response)\n",
+ "\n",
+ "\n",
+ "@action(\n",
+ " reads=[\"attempts\", \"current_challenge\"],\n",
+ " writes=[\"challenge_solved\", \"what_happened\"],\n",
+ ")\n",
+ "def evaluate_attempt(state: State) -> State:\n",
+ " response = OpenAI().chat.completions.create(\n",
+ " model=\"gpt-4o-mini\",\n",
+ " messages=[\n",
+ " {\n",
+ " \"role\": \"system\",\n",
+ " \"content\": f\"\"\"You are evaluating responses for\n",
+ " whether they constitute solutions to the provided challenge in a text\n",
+ " based game, whose protagonist is a dog subject to the following limitations:\n",
+ " {RESTRICTIONS}. You respond ONLY with a json object containing two fields: \"solved\", which is a\n",
+ " boolean indicating whether the challenge was solved by the attempt, and \"what_happened\",\n",
+ " which is a string containing a brief narrative, written in the second person and addressed\n",
+ " to the player, of what happened during the protagonist's attempt\"\"\",\n",
+ " },\n",
+ " {\n",
+ " \"role\": \"user\",\n",
+ " \"content\": f\"The current challenge is: {state['current_challenge']} \"\n",
+ " f\"and the player's attempt is: {state['attempts'][-1]}\",\n",
+ " },\n",
+ " ],\n",
+ " )\n",
+ " content = response.choices[0].message.content\n",
+ " try:\n",
+ " json_result = json.loads(content)\n",
+ " except json.JSONDecodeError:\n",
+ " print(\"bad json: \", content)\n",
+ " json_result = {\n",
+ " \"solved\": False,\n",
+ " \"what_happened\": \"Not sure, really. I'm a dog. I can't read json. I can't read at all.\",\n",
+ " }\n",
+ "\n",
+ " return state.update(\n",
+ " challenge_solved=json_result[\"solved\"],\n",
+ " what_happened=json_result[\"what_happened\"],\n",
+ " )\n",
+ "\n",
+ "\n",
+ "@action(\n",
+ " reads=[\"challenge_solved\", \"current_challenge\", \"what_happened\"],\n",
+ " writes=[\"current_challenge\", \"did_win\"],\n",
+ ")\n",
+ "def maybe_progress(state: State) -> State:\n",
+ " print(\"What happened:\", state[\"what_happened\"])\n",
+ " if state[\"challenge_solved\"]:\n",
+ " if state[\"current_challenge\"] == challenges[-1]:\n",
+ " result = {\"did_win\": True}\n",
+ " else:\n",
+ " result = {\n",
+ " \"current_challenge\": challenges[challenges.index(state[\"current_challenge\"]) + 1]\n",
+ " }\n",
+ " else:\n",
+ " result = {\"current_challenge\": state[\"current_challenge\"]}\n",
+ " return state.update(**result)\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"challenges\"], writes=[])\n",
+ "def win(state: State) -> State:\n",
+ " # get summary of actions taken from openai\n",
+ " print(\"you won\")\n",
+ " return state\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "RESTRICTIONS = \"\"\"You're a small corgi with short legs. You can't jump high,\n",
+ "you can't run fast, you can't perform feats of athleticism in general\n",
+ "to achieve any of your goals. You can't open doors, you can't use tools,\n",
+ "you can't communicate with humans, you can't use your paws to manipulate\n",
+ "objects, you can't use your mouth to manipulate objects, you can't use\n",
+ "your mouth to communicate with humans\"\"\"\n",
+ "\n",
+ "\n",
+ "challenges = [\n",
+ " \"There is a dish of dog food on the floor. You want to eat it\",\n",
+ " \"There is a dish of dog food on a table. You want to eat it\",\n",
+ " \"There is a dish of dog food in a locked car. You want to eat it\",\n",
+ "]"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def build_application(\n",
+ " app_id: Optional[str] = None,\n",
+ " storage_dir: Optional[str] = \"~/.burr\",\n",
+ ") -> Application:\n",
+ " return (\n",
+ " ApplicationBuilder()\n",
+ " .with_state(did_win=False)\n",
+ " .with_actions(\n",
+ " start=start,\n",
+ " prompt_for_challenge=prompt_for_challenge,\n",
+ " evaluate_attempt=evaluate_attempt,\n",
+ " maybe_progress=maybe_progress,\n",
+ " win=win,\n",
+ " )\n",
+ " .with_transitions(\n",
+ " (\"start\", \"prompt_for_challenge\", default),\n",
+ " (\"prompt_for_challenge\", \"evaluate_attempt\", default),\n",
+ " (\"evaluate_attempt\", \"maybe_progress\", default),\n",
+ " (\"maybe_progress\", \"win\", when(did_win=True)),\n",
+ " (\"maybe_progress\", \"prompt_for_challenge\", default),\n",
+ " )\n",
+ " .with_entrypoint(\"start\")\n",
+ " .with_tracker(project=\"demo_corgi_adventure\", params={\"storage_dir\": storage_dir})\n",
+ " .with_identifiers(app_id=app_id)\n",
+ " .build()\n",
+ " )\n",
+ "\n",
+ "app = build_application()\n",
+ "app.visualize(output_file_path=\"digraph\", include_conditions=True, view=False, format=\"png\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "action, state, result = app.run(halt_after=[\"win\"])"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": ".venv",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.9"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/examples/simple/counter.ipynb b/docs/examples/simple/counter.ipynb
new file mode 100644
index 00000000..838940dc
--- /dev/null
+++ b/docs/examples/simple/counter.ipynb
@@ -0,0 +1,231 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "49dab42f",
+ "metadata": {},
+ "source": [
+ "# Counter\n",
+ "\n",
+ "Let's build a simple counter using Burr. When the counter terminates, print the count and the current time."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "84328dc0",
+ "metadata": {},
+ "source": [
+ "## Imports"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "initial_id",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:11:36.093767Z",
+ "start_time": "2024-03-27T00:11:36.088301Z"
+ },
+ "collapsed": true,
+ "jupyter": {
+ "outputs_hidden": true
+ }
+ },
+ "outputs": [],
+ "source": [
+ "import datetime\n",
+ "\n",
+ "from burr.core import action, State, ApplicationBuilder, expr"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "396c5e0c",
+ "metadata": {},
+ "source": [
+ "## Define actions\n",
+ "We define the function `increment()` that has a `State` as input and outputs a new `State`. The decorator `@action` specifies it's a Burr action and it will need to read and write from the `counter` attribute in `State`. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "64c67b15363653e9",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:11:36.548223Z",
+ "start_time": "2024-03-27T00:11:36.539358Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "@action(reads=[\"counter\"], writes=[\"counter\"])\n",
+ "def increment(state: State) -> State:\n",
+ " \"\"\"Increment the counter by 1\"\"\"\n",
+ " \n",
+ " # get the value from the `state`\n",
+ " current_count = state[\"counter\"]\n",
+ " current_count += 1\n",
+ "\n",
+ " print(\"Count: \", current_count)\n",
+ "\n",
+ " # use `.update()` to create a new `State`\n",
+ " return state.update(counter=current_count)\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"counter\"], writes=[])\n",
+ "def exit_counter(state: State) -> State:\n",
+ " \"\"\"Print the current count and the current time\"\"\"\n",
+ " current_count = state[\"counter\"]\n",
+ "\n",
+ " print(f\"Finished counting to {current_count} at {datetime.datetime.now():%H:%M:%S %Y-%m-%d}\")\n",
+ "\n",
+ " return state"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "197106df",
+ "metadata": {},
+ "source": [
+ "## Build the `Application`\n",
+ "We pass the action to the `ApplicationBuilder` via `.with_actions()`. Then, we specify the valid transitions between actions: `increment -> increment` and `increment -> exit_counter`. The `expr`ession construct specifies to use the transition `increment -> increment` whenever the `counter` value in state is under ten. Then, default to `increment -> exit_counter` to terminate the application. We also use `.with_entrypoint()` to define where to start and `.with_state()` to set the starting state value."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "72ca90a1",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "image/svg+xml": [
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n",
+ "<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n",
+ " \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n",
+ "<!-- Generated by graphviz version 2.43.0 (0)\n",
+ " -->\n",
+ "<!-- Title: %3 Pages: 1 -->\n",
+ "<svg width=\"220pt\" height=\"113pt\"\n",
+ " viewBox=\"0.00 0.00 220.00 113.00\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n",
+ "<g id=\"graph0\" class=\"graph\" transform=\"scale(1 1) rotate(0) translate(4 109)\">\n",
+ "<title>%3</title>\n",
+ "<polygon fill=\"white\" stroke=\"transparent\" points=\"-4,4 -4,-109 216,-109 216,4 -4,4\"/>\n",
+ "<!-- increment -->\n",
+ "<g id=\"node1\" class=\"node\">\n",
+ "<title>increment</title>\n",
+ "<path fill=\"#b4d8e4\" stroke=\"black\" d=\"M88,-105C88,-105 20,-105 20,-105 14,-105 8,-99 8,-93 8,-93 8,-80 8,-80 8,-74 14,-68 20,-68 20,-68 88,-68 88,-68 94,-68 100,-74 100,-80 100,-80 100,-93 100,-93 100,-99 94,-105 88,-105\"/>\n",
+ "<text text-anchor=\"middle\" x=\"54\" y=\"-82.8\" font-family=\"Helvetica,sans-Serif\" font-size=\"14.00\">increment</text>\n",
+ "</g>\n",
+ "<!-- increment&#45;&gt;increment -->\n",
+ "<g id=\"edge1\" class=\"edge\">\n",
+ "<title>increment&#45;&gt;increment</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M100.02,-92.72C110.41,-92.16 118,-90.09 118,-86.5 118,-84.26 115.03,-82.61 110.27,-81.55\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"110.38,-78.04 100.02,-80.28 109.52,-84.98 110.38,-78.04\"/>\n",
+ "<text text-anchor=\"middle\" x=\"165\" y=\"-82.8\" font-family=\"Times,serif\" font-size=\"14.00\">counter &lt; 10</text>\n",
+ "</g>\n",
+ "<!-- exit_counter -->\n",
+ "<g id=\"node2\" class=\"node\">\n",
+ "<title>exit_counter</title>\n",
+ "<path fill=\"#b4d8e4\" stroke=\"black\" d=\"M96,-37C96,-37 12,-37 12,-37 6,-37 0,-31 0,-25 0,-25 0,-12 0,-12 0,-6 6,0 12,0 12,0 96,0 96,0 102,0 108,-6 108,-12 108,-12 108,-25 108,-25 108,-31 102,-37 96,-37\"/>\n",
+ "<text text-anchor=\"middle\" x=\"54\" y=\"-14.8\" font-family=\"Helvetica,sans-Serif\" font-size=\"14.00\">exit_counter</text>\n",
+ "</g>\n",
+ "<!-- increment&#45;&gt;exit_counter -->\n",
+ "<g id=\"edge2\" class=\"edge\">\n",
+ "<title>increment&#45;&gt;exit_counter</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M54,-67.81C54,-61.6 54,-54.45 54,-47.6\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"57.5,-47.24 54,-37.24 50.5,-47.24 57.5,-47.24\"/>\n",
+ "</g>\n",
+ "</g>\n",
+ "</svg>\n"
+ ],
+ "text/plain": [
+ "<graphviz.graphs.Digraph at 0x7f2886e3ead0>"
+ ]
+ },
+ "execution_count": 3,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "app = (\n",
+ " ApplicationBuilder()\n",
+ " .with_actions(increment, exit_counter)\n",
+ " .with_transitions(\n",
+ " (\"increment\", \"increment\", expr(\"counter < 10\")),\n",
+ " (\"increment\", \"exit_counter\"),\n",
+ " )\n",
+ " .with_state(counter=0)\n",
+ " .with_entrypoint(\"increment\")\n",
+ " .build()\n",
+ ")\n",
+ "app.visualize(include_conditions=True)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "a63802fa10f73ca8",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:11:38.483852Z",
+ "start_time": "2024-03-27T00:11:38.463109Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Count: 1\n",
+ "Count: 2\n",
+ "Count: 3\n",
+ "Count: 4\n",
+ "Count: 5\n",
+ "Count: 6\n",
+ "Count: 7\n",
+ "Count: 8\n",
+ "Count: 9\n",
+ "Count: 10\n",
+ "Finished counting to 10 at 18:44:29 2024-08-26\n"
+ ]
+ }
+ ],
+ "source": [
+ "action_obj, result, state = app.run(halt_after=[\"exit_counter\"])"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.9"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/examples/simple/cowsay.ipynb b/docs/examples/simple/cowsay.ipynb
new file mode 100644
index 00000000..edf53656
--- /dev/null
+++ b/docs/examples/simple/cowsay.ipynb
@@ -0,0 +1,405 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "23493882",
+ "metadata": {},
+ "source": [
+ "# Cowsay"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "initial_id",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:12:50.561804Z",
+ "start_time": "2024-03-27T00:12:50.531039Z"
+ },
+ "collapsed": true,
+ "jupyter": {
+ "outputs_hidden": true
+ }
+ },
+ "outputs": [],
+ "source": [
+ "import random\n",
+ "import time\n",
+ "from typing import Tuple\n",
+ "\n",
+ "import cowsay\n",
+ "\n",
+ "from burr.core import Action, Application, ApplicationBuilder, State, default, expr\n",
+ "from burr.core.action import action\n",
+ "from burr.lifecycle import PostRunStepHook"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "9f5b9bfc78851a59",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:13:03.529875Z",
+ "start_time": "2024-03-27T00:13:03.524449Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# create some hooks!\n",
+ "class PrintWhatTheCowSaid(PostRunStepHook):\n",
+ " def post_run_step(self, *, state: \"State\", action: \"Action\", **future_kwargs):\n",
+ " if action.name != \"cow_should_say\" and state[\"cow_said\"] is not None:\n",
+ " print(state[\"cow_said\"])\n",
+ "\n",
+ "\n",
+ "class CowCantSpeakFast(PostRunStepHook):\n",
+ " def __init__(self, sleep_time: float):\n",
+ " super(PostRunStepHook, self).__init__()\n",
+ " self.sleep_time = sleep_time\n",
+ "\n",
+ " def post_run_step(self, *, state: \"State\", action: \"Action\", **future_kwargs):\n",
+ " if action.name != \"cow_should_say\": # no need to print if we're not saying anything\n",
+ " time.sleep(self.sleep_time)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "5b29e9de2ca536b9",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:13:12.756137Z",
+ "start_time": "2024-03-27T00:13:12.750764Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# instantiate actions\n",
+ "@action(reads=[], writes=[\"cow_said\"])\n",
+ "def cow_said(state: State, say_what: list[str]) -> Tuple[dict, State]:\n",
+ " said = random.choice(say_what)\n",
+ " result = {\"cow_said\": cowsay.get_output_string(\"cow\", said) if say_what is not None else None}\n",
+ " return result, state.update(**result)\n",
+ "\n",
+ "\n",
+ "@action(reads=[], writes=[\"cow_should_speak\"])\n",
+ "def cow_should_speak(state: State) -> Tuple[dict, State]:\n",
+ " result = {\"cow_should_speak\": random.randint(0, 3) == 0}\n",
+ " return result, state.update(**result)\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "271b868317fbbdf4",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:14:10.836543Z",
+ "start_time": "2024-03-27T00:14:10.829258Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": [
+ "# build application\n",
+ "hooks = [\n",
+ " PrintWhatTheCowSaid(),\n",
+ " CowCantSpeakFast(sleep_time=2.0),\n",
+ "]\n",
+ " \n",
+ "app = (ApplicationBuilder()\n",
+ " .with_state(cow_said=None)\n",
+ " .with_actions(\n",
+ " say_nothing=cow_said.bind(say_what=None),\n",
+ " say_hello=cow_said.bind(\n",
+ " say_what=[\"Hello world!\", \"What's up?\", \"Are you Aaron Burr, sir?\"]\n",
+ " ),\n",
+ " cow_should_speak=cow_should_speak,\n",
+ " )\n",
+ " .with_transitions(\n",
+ " (\"cow_should_speak\", \"say_hello\", expr(\"cow_should_speak\")),\n",
+ " (\"say_hello\", \"cow_should_speak\", default),\n",
+ " (\"cow_should_speak\", \"say_nothing\", expr(\"not cow_should_speak\")),\n",
+ " (\"say_nothing\", \"cow_should_speak\", default),\n",
+ " )\n",
+ " .with_entrypoint(\"cow_should_speak\")\n",
+ " .with_hooks(*hooks)\n",
+ " .build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "794bc0abda9e48ad",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:14:29.829383Z",
+ "start_time": "2024-03-27T00:14:29.511355Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "image/svg+xml": [
+ "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n",
+ "<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n",
+ " \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n",
+ "<!-- Generated by graphviz version 9.0.0 (20230911.1827)\n",
+ " -->\n",
+ "<!-- Pages: 1 -->\n",
+ "<svg width=\"192pt\" height=\"209pt\"\n",
+ " viewBox=\"0.00 0.00 192.02 209.00\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n",
+ "<g id=\"graph0\" class=\"graph\" transform=\"scale(1 1) rotate(0) translate(4 205)\">\n",
+ "<polygon fill=\"white\" stroke=\"none\" points=\"-4,4 -4,-205 188.02,-205 188.02,4 -4,4\"/>\n",
+ "<!-- say_nothing -->\n",
+ "<g id=\"node1\" class=\"node\">\n",
+ "<title>say_nothing</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M89.27,-201C89.27,-201 31.27,-201 31.27,-201 25.27,-201 19.27,-195 19.27,-189 19.27,-189 19.27,-177 19.27,-177 19.27,-171 25.27,-165 31.27,-165 31.27,-165 89.27,-165 89.27,-165 95.27,-165 101.27,-171 101.27,-177 101.27,-177 101.27,-189 101.27,-189 101.27,-195 95.27,-201 89.27,-201\"/>\n",
+ "<text text-anchor=\"middle\" x=\"60.27\" y=\"-177.95\" font-family=\"Times,serif\" font-size=\"14.00\">say_nothing</text>\n",
+ "</g>\n",
+ "<!-- cow_should_speak -->\n",
+ "<g id=\"node3\" class=\"node\">\n",
+ "<title>cow_should_speak</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M107.65,-118.5C107.65,-118.5 12.9,-118.5 12.9,-118.5 6.9,-118.5 0.9,-112.5 0.9,-106.5 0.9,-106.5 0.9,-94.5 0.9,-94.5 0.9,-88.5 6.9,-82.5 12.9,-82.5 12.9,-82.5 107.65,-82.5 107.65,-82.5 113.65,-82.5 119.65,-88.5 119.65,-94.5 119.65,-94.5 119.65,-106.5 119.65,-106.5 119.65,-112.5 113.65,-118.5 107.65,-118.5\"/>\n",
+ "<text text-anchor=\"middle\" x=\"60.27\" y=\"-95.45\" font-family=\"Times,serif\" font-size=\"14.00\">cow_should_speak</text>\n",
+ "</g>\n",
+ "<!-- say_nothing&#45;&gt;cow_should_speak -->\n",
+ "<g id=\"edge4\" class=\"edge\">\n",
+ "<title>say_nothing&#45;&gt;cow_should_speak</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M58.99,-164.74C58.7,-159.97 58.42,-154.78 58.27,-150 58.04,-142.67 58.04,-140.83 58.27,-133.5 58.31,-132.3 58.35,-131.08 58.41,-129.85\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"61.88,-130.45 58.91,-120.27 54.89,-130.07 61.88,-130.45\"/>\n",
+ "</g>\n",
+ "<!-- say_hello -->\n",
+ "<g id=\"node2\" class=\"node\">\n",
+ "<title>say_hello</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M82.15,-36C82.15,-36 38.4,-36 38.4,-36 32.4,-36 26.4,-30 26.4,-24 26.4,-24 26.4,-12 26.4,-12 26.4,-6 32.4,0 38.4,0 38.4,0 82.15,0 82.15,0 88.15,0 94.15,-6 94.15,-12 94.15,-12 94.15,-24 94.15,-24 94.15,-30 88.15,-36 82.15,-36\"/>\n",
+ "<text text-anchor=\"middle\" x=\"60.27\" y=\"-12.95\" font-family=\"Times,serif\" font-size=\"14.00\">say_hello</text>\n",
+ "</g>\n",
+ "<!-- say_hello&#45;&gt;cow_should_speak -->\n",
+ "<g id=\"edge2\" class=\"edge\">\n",
+ "<title>say_hello&#45;&gt;cow_should_speak</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M93.05,-36.42C97.97,-40.53 102.37,-45.38 105.27,-51 108.63,-57.52 108.63,-60.98 105.27,-67.5 104.09,-69.78 102.67,-71.94 101.06,-73.97\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"98.65,-71.43 94.11,-81 103.63,-76.35 98.65,-71.43\"/>\n",
+ "</g>\n",
+ "<!-- cow_should_speak&#45;&gt;say_nothing -->\n",
+ "<g id=\"edge3\" class=\"edge\">\n",
+ "<title>cow_should_speak&#45;&gt;say_nothing</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M60.27,-118.93C60.27,-128.95 60.27,-141.78 60.27,-153.25\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"56.77,-153.02 60.27,-163.02 63.77,-153.02 56.77,-153.02\"/>\n",
+ "<text text-anchor=\"middle\" x=\"122.15\" y=\"-136.7\" font-family=\"Times,serif\" font-size=\"14.00\">not cow_should_speak</text>\n",
+ "</g>\n",
+ "<!-- cow_should_speak&#45;&gt;say_hello -->\n",
+ "<g id=\"edge1\" class=\"edge\">\n",
+ "<title>cow_should_speak&#45;&gt;say_hello</title>\n",
+ "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M16.41,-82.17C10.87,-78.17 5.95,-73.33 2.52,-67.5 -4.42,-55.72 3.91,-45.49 16.2,-37.49\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"17.9,-40.55 24.87,-32.57 14.44,-34.46 17.9,-40.55\"/>\n",
+ "<text text-anchor=\"middle\" x=\"54.65\" y=\"-54.2\" font-family=\"Times,serif\" font-size=\"14.00\">cow_should_speak</text>\n",
+ "</g>\n",
+ "</g>\n",
+ "</svg>\n"
+ ],
+ "text/plain": [
+ "<graphviz.graphs.Digraph at 0x1107a98a0>"
+ ]
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "app.visualize(include_conditions=True)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 11,
+ "id": "2facfb753233cd7d",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:16:40.234406Z",
+ "start_time": "2024-03-27T00:16:32.211734Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ " ____________\n",
+ "| Hello world! |\n",
+ " ============\n",
+ " \\\n",
+ " \\\n",
+ " ^__^\n",
+ " (oo)\\_______\n",
+ " (__)\\ )\\/\\\n",
+ " ||----w |\n",
+ " || ||\n",
+ " ____________\n",
+ "| Hello world! |\n",
+ " ============\n",
+ " \\\n",
+ " \\\n",
+ " ^__^\n",
+ " (oo)\\_______\n",
+ " (__)\\ )\\/\\\n",
+ " ||----w |\n",
+ " || ||\n",
+ " ____________\n",
+ "| Hello world! |\n",
+ " ============\n",
+ " \\\n",
+ " \\\n",
+ " ^__^\n",
+ " (oo)\\_______\n",
+ " (__)\\ )\\/\\\n",
+ " ||----w |\n",
+ " || ||\n",
+ " ____________\n",
+ "| Hello world! |\n",
+ " ============\n",
+ " \\\n",
+ " \\\n",
+ " ^__^\n",
+ " (oo)\\_______\n",
+ " (__)\\ )\\/\\\n",
+ " ||----w |\n",
+ " || ||\n"
+ ]
+ }
+ ],
+ "source": [
+ "# run things!\n",
+ "for i in range(0, 4):\n",
+ " # step through 4 times\n",
+ " a_obj, result, state = app.step()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "id": "fed65721e7cc457a",
+ "metadata": {
+ "ExecuteTime": {
+ "end_time": "2024-03-27T00:17:18.640978Z",
+ "start_time": "2024-03-27T00:17:10.619878Z"
+ },
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ " ________________________\n",
+ "| Are you Aaron Burr, sir? |\n",
+ " ========================\n",
+ " \\\n",
+ " \\\n",
+ " ^__^\n",
+ " (oo)\\_______\n",
+ " (__)\\ )\\/\\\n",
+ " ||----w |\n",
+ " || ||\n",
+ " ________________________\n",
+ "| Are you Aaron Burr, sir? |\n",
+ " ========================\n",
+ " \\\n",
+ " \\\n",
+ " ^__^\n",
+ " (oo)\\_______\n",
+ " (__)\\ )\\/\\\n",
+ " ||----w |\n",
+ " || ||\n",
+ " ____________\n",
+ "| Hello world! |\n",
+ " ============\n",
+ " \\\n",
+ " \\\n",
+ " ^__^\n",
+ " (oo)\\_______\n",
+ " (__)\\ )\\/\\\n",
+ " ||----w |\n",
+ " || ||\n",
+ " ____________\n",
+ "| Hello world! |\n",
+ " ============\n",
+ " \\\n",
+ " \\\n",
+ " ^__^\n",
+ " (oo)\\_______\n",
+ " (__)\\ )\\/\\\n",
+ " ||----w |\n",
+ " || ||\n"
+ ]
+ }
+ ],
+ "source": [
+ "# Run some more\n",
+ "for i in range(0, 4):\n",
+ " # step through 4 times\n",
+ " a_obj, result, state = app.step()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "19095ae96e98fd83",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "outputs": [],
+ "source": []
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.4"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/examples/simple/index.rst b/docs/examples/simple/index.rst
new file mode 100644
index 00000000..1c1584ee
--- /dev/null
+++ b/docs/examples/simple/index.rst
@@ -0,0 +1,12 @@
+================
+🧸 Toy examples
+================
+
+The following toy examples illustrate the basics of Burr. If you're interested in more real-life applications, skip ahead to chatbots.
+
+.. toctree::
+ :maxdepth: 2
+
+ counter
+ cowsay
+ choose-your-own-adventure
diff --git a/docs/examples/simulation.rst b/docs/examples/simulation.rst
deleted file mode 100644
index 1063313f..00000000
--- a/docs/examples/simulation.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-==========
-Simulation
-==========
-
-Simulations require state to be maintained across time steps. Burr provides a simple way for you to construct,
-manage, and introspect the state of your simulation.
-
-For more information/contribution options, see the placeholder/example sketch in the `repository <https://github.com/DAGWorks-Inc/burr/tree/main/examples/simulation>`_.
diff --git a/docs/examples/web-server.rst b/docs/examples/web-server.rst
deleted file mode 100644
index 203a5c0e..00000000
--- a/docs/examples/web-server.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-========================
-Exposing in a Web Server
-========================
-
-Burr makes it natural to integrate with a web-server such as FastAPI. See the `example in the repository <https://github.com/DAGWorks-Inc/burr/tree/main/examples/web-server>`_.
-for the high-level concepts + some implementation tricks. Run ``burr`` after ``pip install "burr[start]"`` and click ``examples/email-assistant`` to see example in action.