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.

added instructor + burr example

ziltoe467e3f3a37f
diff --git a/examples/youtube-to-social-media-post/README.md b/examples/youtube-to-social-media-post/README.md
new file mode 100644
index 00000000..cd09ce15
--- /dev/null
+++ b/examples/youtube-to-social-media-post/README.md
@@ -0,0 +1,12 @@
+# Build trustworthy LLM agents & applications for production with Instructor + Burr
+
+The challenge with large language models (LLMs) is handling the 5% of the time they say crazy things. Being able to debug why an output is bad and having tools for fixing are critical requirements for making LLM features / agents trustworthy and available to users.
+
+In this example, you'll learn how `instructor` can make LLM reliability produce structured outputs, and `burr` helps you introspect and debug your application.
+
+In a few lines of code, you can query an LLM API and can create powerful productivity utilities. However, user-facing features deserve much more scrutiny, which requires tooling and solving complex engineering problems.
+
+Building our app with Burr provides several benefits that we'll detail next:
+- **Observability**: monitor in real-time and log the execution of your `Application` and view it in Burr's web user interface.
+- **Persistence**: At any point, you can save the application `State`. This allows to create user sessions (e.g., the conversation history menu in ChatGPT), which helps developers investigate bugs and test potential solutions.
+- **Portability**: your `Application` can run in a notebook, as a script, as a web service, or anywhere Python runs. We'll show how to use Burr with [FastAPI](https://fastapi.tiangolo.com/).
diff --git a/examples/youtube-to-social-media-post/application.py b/examples/youtube-to-social-media-post/application.py
new file mode 100644
index 00000000..683cec3e
--- /dev/null
+++ b/examples/youtube-to-social-media-post/application.py
@@ -0,0 +1,154 @@
+import textwrap
+from typing import Union
+
+import instructor
+import openai
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+from youtube_transcript_api import YouTubeTranscriptApi
+
+from burr.core import Application, ApplicationBuilder, State, action
+from burr.core.persistence import SQLLitePersister
+
+
+class Concept(BaseModel):
+ term: str = Field(description="A key term or concept mentioned.")
+ definition: str = Field(description="A brief definition or explanation of the term.")
+ timestamp: float = Field(description="Timestamp when the concept is explained.")
+
+ def display(self):
+ minutes, seconds = divmod(self.timestamp, 60)
+ return f"{int(minutes)}:{int(seconds)} - {self.term}: {self.definition}"
+
+
+class SocialMediaPost(BaseModel):
+ """A social media post about a YouTube video generated its transcript"""
+
+ topic: str = Field(description="Main topic discussed.")
+ hook: str = Field(
+ description="Statement to grab the attention of the reader and announce the topic."
+ )
+ body: str = Field(
+ description="The body of the social media post. It should be informative and make the reader curious about viewing the video."
+ )
+ concepts: list[Concept] = Field(
+ description="Important concepts about Hamilton or Burr mentioned in this post.",
+ min_items=1,
+ max_items=3,
+ )
+ key_takeaways: list[str] = Field(
+ description="A list of informative key takeways for the reader.",
+ min_items=1,
+ max_items=4,
+ )
+ youtube_url: SkipJsonSchema[Union[str, None]] = None
+
+ def display(self) -> str:
+ formatted_takeways = " ".join([t for t in self.key_takeaways])
+ formatted_concepts = "CONCEPTS\n" + "\n".join([c.display() for c in self.concepts])
+ link = f"link: {self.youtube_url}\n\n" if self.youtube_url else ""
+
+ return (
+ textwrap.dedent(
+ f"""\
+ TOPIC: {self.topic}
+
+ {self.hook}
+
+ {self.body}
+
+ {formatted_takeways}
+
+ """
+ )
+ + link
+ + formatted_concepts
+ )
+
+
+@action(reads=[], writes=["transcript"])
+def get_youtube_transcript(state: State, youtube_url: str) -> State:
+ """Get the official YouTube transcript for a video given it's URL"""
+ _, _, video_id = youtube_url.partition("?v=")
+
+ transcript = YouTubeTranscriptApi.get_transcript(video_id, languages=["en"])
+ full_transcript = " ".join([f"ts={entry['start']} - {entry['text']}" for entry in transcript])
+
+ # store the transcript in state
+ return state.update(transcript=full_transcript)
+
+
+@action(reads=["transcript"], writes=["post"])
+def generate_post(state: State, llm_client) -> State:
+ """Use the Instructor LLM client to generate `SocialMediaPost` from the YouTube transcript."""
+
+ # read the transcript from state
+ transcript = state["transcript"]
+
+ response = llm_client.chat.completions.create(
+ model="gpt-4o-mini",
+ response_model=SocialMediaPost,
+ messages=[
+ {
+ "role": "system",
+ "content": "Analyze the given YouTube transcript and generate a compelling social media post.",
+ },
+ {"role": "user", "content": transcript},
+ ],
+ )
+
+ # store the chapters in state
+ return state.update(post=response)
+
+
+@action(reads=["post"], writes=["post"])
+def rewrite_post(state: State, llm_client, user_prompt: str):
+ post = state["post"]
+
+ response = llm_client.chat.completions.create(
+ model="gpt-4o-mini",
+ response_model=SocialMediaPost,
+ messages=[
+ {
+ "role": "system",
+ "content": f"Take the previously generated social media post and modify it according to the following instructions: {user_prompt}",
+ },
+ {"role": "user", "content": post.model_dump_json()},
+ ],
+ )
+
+ # pass the youtube_url from the previous post version
+ response.youtube_url = post.youtube_url
+
+ return state.update(post=response)
+
+
+def build_application() -> Application:
+ llm_client = instructor.from_openai(openai.OpenAI())
+ return (
+ ApplicationBuilder()
+ .with_actions(
+ get_youtube_transcript,
+ generate_post.bind(llm_client=llm_client),
+ rewrite_post.bind(llm_client=llm_client),
+ )
+ .with_transitions(
+ ("get_youtube_transcript", "generate_post"),
+ ("generate_post", "rewrite_post"),
+ ("rewrite_post", "rewrite_post"),
+ )
+ .with_state_persister(SQLLitePersister(db_path=".burr.db", table_name="state"))
+ .with_entrypoint("get_youtube_transcript")
+ .with_tracker(project="youtube-post")
+ .build()
+ )
+
+
+if __name__ == "__main__":
+ app = build_application()
+ app.visualize(output_file_path="statemachine.png")
+
+ _, _, state = app.run(
+ halt_after=["generate_post"],
+ inputs={"youtube_url": "https://www.youtube.com/watch?v=hqutVJyd3TI"},
+ )
diff --git a/examples/youtube-to-social-media-post/notebook.ipynb b/examples/youtube-to-social-media-post/notebook.ipynb
new file mode 100644
index 00000000..1491e5c9
--- /dev/null
+++ b/examples/youtube-to-social-media-post/notebook.ipynb
@@ -0,0 +1,774 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Build trustworthy LLM agents & applications for production with Instructor + Burr\n",
+ "\n",
+ "The challenge with large language models (LLMs) is handling the 5% of the time they say crazy things. Being able to debug why an output is bad and having tools for fixing are critical requirements for making LLM features / agents trustworthy and available to users.\n",
+ "\n",
+ "In this notebook, you'll learn how `instructor` can make LLM reliability produce structured outputs, and `burr` helps you introspect and debug your application."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Instructor 101\n",
+ "Instructor is a tool to help you prompt LLM and constraint its outputs. First, you specify the desired output using a **model** with typed fields and textual descriptions; you can think of it as a template that the LLM will fill. This greatly improves the reliability of the content and format of generated text.\n",
+ "\n",
+ "To introduce Instructor, we'll write code to generate a social media post from the transcript of a YouTube video. \n",
+ "\n",
+ "> This post on the Instructor blog is also a great introduction: [Analyzing Youtube Transcripts with Instructor](https://python.useinstructor.com/blog/2024/07/11/youtube-transcripts/)."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 1. Define the `response_model`\n",
+ "\n",
+ "Instructor uses [Pydantic](https://docs.pydantic.dev/latest/) to create the response model. A model needs to inherit the `BaseModel` class and we use the `Field()` object to give a textual description.\n",
+ "\n",
+ "- `Field()` objects allow to specify constraints to the generated output. For instance, we want \"1 to 3 concepts\" and \"1 to 4 key takeaways\" generated per `SocialMediaPost`\n",
+ "- Notice that you can nest models. Indeed, `SocialMediaPost.concepts` is a list of `Concept` models.\n",
+ "- We use `SkipJsonSchema` on the `youtube_url` field to specify that this shouldn't be generated by the LLM. Instead, we'll manually pass it.\n",
+ "\n",
+ "Tip: We're adding a `.display()` method to format the text to be more easily human-readable. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import textwrap\n",
+ "from typing import Union\n",
+ "\n",
+ "from pydantic import BaseModel, Field\n",
+ "from pydantic.json_schema import SkipJsonSchema\n",
+ "\n",
+ "class Concept(BaseModel):\n",
+ " term: str = Field(description=\"A key term or concept mentioned.\")\n",
+ " definition: str = Field(description=\"A brief definition or explanation of the term.\")\n",
+ " timestamp: float = Field(description=\"Timestamp when the concept is explained.\")\n",
+ "\n",
+ " def display(self):\n",
+ " minutes, seconds = divmod(self.timestamp, 60)\n",
+ " return f\"{int(minutes)}:{int(seconds)} - {self.term}: {self.definition}\"\n",
+ "\n",
+ "\n",
+ "class SocialMediaPost(BaseModel):\n",
+ " \"\"\"A social media post about a YouTube video generated its transcript\"\"\"\n",
+ "\n",
+ " topic: str = Field(description=\"Main topic discussed.\")\n",
+ " hook: str = Field(description=\"Statement to grab the attention of the reader and announce the topic.\")\n",
+ " body: str = Field(description=\"The body of the social media post. It should be informative and make the reader curious about viewing the video.\")\n",
+ " concepts: list[Concept] = Field(\n",
+ " description=\"Important concepts about Hamilton or Burr mentioned in this post.\",\n",
+ " min_items=1,\n",
+ " max_items=3,\n",
+ " )\n",
+ " key_takeaways: list[str] = Field(\n",
+ " description=\"A list of informative key takeways for the reader.\",\n",
+ " min_items=1,\n",
+ " max_items=4,\n",
+ " )\n",
+ " youtube_url: SkipJsonSchema[Union[str, None]] = None\n",
+ "\n",
+ " def display(self) -> str:\n",
+ " formatted_takeways = \" \".join([t for t in self.key_takeaways])\n",
+ " formatted_concepts = \"CONCEPTS\\n\" + \"\\n\".join([c.display() for c in self.concepts])\n",
+ " link = f\"link: {self.youtube_url}\\n\\n\" if self.youtube_url else \"\"\n",
+ "\n",
+ " return textwrap.dedent(\n",
+ " f\"\"\"\\\n",
+ " TOPIC: {self.topic}\n",
+ "\n",
+ " {self.hook}\n",
+ "\n",
+ " {self.body}\n",
+ "\n",
+ " {formatted_takeways}\n",
+ "\n",
+ " \"\"\"\n",
+ " ) + link + formatted_concepts"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 2. Write the application logic\n",
+ "\n",
+ "Instructor is not opiniated about how you write your application; it's only in contact with your LLM client. Here, we write a script in a few lines of code to retrieve a YouTube transcript."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from youtube_transcript_api import YouTubeTranscriptApi\n",
+ "\n",
+ "# get the video id from a YouTube url\n",
+ "youtube_url = \"https://www.youtube.com/watch?v=hqutVJyd3TI\" \n",
+ "_, _, video_id = youtube_url.partition(\"?v=\")\n",
+ "\n",
+ "# get the available YouTube transcript for the video\n",
+ "transcript = YouTubeTranscriptApi.get_transcript(video_id)\n",
+ "# join the transcript into a single block of text\n",
+ "full_transcript = \" \".join([f\"ts={entry['start']} - {entry['text']}\" for entry in transcript])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Wrap the LLM client\n",
+ "To use Instructor, we need to wrap the OpenAI client, creating a special client. \n",
+ "\n",
+ "> NOTE: If you have the environment variable `OPENAI_API_KEY` set, the client will be automatically created. Otherwise, you'll need to manually pass the key to `OpenAI(api_key=...)`."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import instructor\n",
+ "from openai import OpenAI\n",
+ "\n",
+ "llm_client = instructor.from_openai(OpenAI())"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "#### Use the LLM client with the `response_model`\n",
+ "\n",
+ "1. Use the LLM client with `.create` to call the LLM API\n",
+ "2. Pass `SocialMediaPost` as the response model, enabling structured outputs.\n",
+ "3. The `messages` include the `system` message with the task instruction for the LLM and\n",
+ "the `user` message with the input content. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "response = llm_client.chat.completions.create(\n",
+ " model=\"gpt-4o-mini\",\n",
+ " response_model=SocialMediaPost,\n",
+ " messages=[\n",
+ " {\n",
+ " \"role\": \"system\",\n",
+ " \"content\": \"Analyze the given YouTube transcript and generate a compelling social media post.\",\n",
+ " },\n",
+ " {\"role\": \"user\", \"content\": full_transcript},\n",
+ " ],\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "`response` will have the type of the provided `response_model`, `SocialMediaPost` in this case. You can use `Model.model_dump()` to get a Python dictionary."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "<class '__main__.SocialMediaPost'>\n",
+ "{'topic': 'Agent Development and Debugging', 'hook': 'Ever faced challenges while developing AI agents? Fixing bugs can be a nightmare!', 'body': 'Join us in our latest video where we dive into the tools and techniques that can streamline your agent development, especially when things go off the rails. Discover the functionalities of Burr, a framework designed to help debug your agent applications without starting from scratch. From creating flowcharts to tracking your state, learn how to build and monitor your agent’s performance effectively!', 'concepts': [{'term': 'Burr Framework', 'definition': 'A framework that helps in building and debugging agent applications by modeling actions and states in a graph structure.', 'timestamp': 83.0}, {'term': 'Local Tracker', 'definition': 'A feature that allows you to initialize from a previous state and track or introspect the running application.', 'timestamp': 260.0}, {'term': 'Graph Structure', 'definition': 'A representation in which agents can model their actions and states, allowing for efficient debugging and flow control.', 'timestamp': 105.0}], 'key_takeaways': ['Streamline your AI agent debugging process.', 'Utilize the Burr framework to manage states and actions effectively.', \"Learn to visualize and control your agent's behavior through graph structures.\"], 'youtube_url': None}\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(type(response))\n",
+ "print(response.model_dump())"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can also use the `.display()` method we've defined!"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "TOPIC: Agent Development and Debugging\n",
+ "\n",
+ "Ever faced challenges while developing AI agents? Fixing bugs can be a nightmare!\n",
+ "\n",
+ "Join us in our latest video where we dive into the tools and techniques that can streamline your agent development, especially when things go off the rails. Discover the functionalities of Burr, a framework designed to help debug your agent applications without starting from scratch. From creating flowcharts to tracking your state, learn how to build and monitor your agent’s performance effectively!\n",
+ "\n",
+ "Streamline your AI agent debugging process. Utilize the Burr framework to manage states and actions effectively. Learn to visualize and control your agent's behavior through graph structures.\n",
+ "\n",
+ "CONCEPTS\n",
+ "1:23 - Burr Framework: A framework that helps in building and debugging agent applications by modeling actions and states in a graph structure.\n",
+ "4:20 - Local Tracker: A feature that allows you to initialize from a previous state and track or introspect the running application.\n",
+ "1:45 - Graph Structure: A representation in which agents can model their actions and states, allowing for efficient debugging and flow control.\n"
+ ]
+ }
+ ],
+ "source": [
+ "print(response.display())"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Burr 101\n",
+ "Burr is a tool to build LLM applications, solving many challenges to get to production (monitoring, persistence, streaming, and more). With the concepts of \"state\" and \"action\", you can define complex apps that are easy-to-understand and debug.\n",
+ "\n",
+ "To show this, we'll rewrite the previous application logic with Burr."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 1. Define `actions`\n",
+ "\n",
+ "First, you need to define the different actions your agent can take. This is done by writing Python functions with the `@action` decorator. The decorator must specify the information that can be read from state. Also, the function needs to take a `State` object as first argument and return a `State` object."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from burr.core import State, action\n",
+ "\n",
+ "\n",
+ "@action(reads=[], writes=[\"transcript\"])\n",
+ "def get_youtube_transcript(state: State, youtube_url: str) -> State:\n",
+ " \"\"\"Get the official YouTube transcript for a video given it's URL\"\"\"\n",
+ " _, _, video_id = youtube_url.partition(\"?v=\")\n",
+ " \n",
+ " transcript = YouTubeTranscriptApi.get_transcript(video_id, languages=[\"en\"])\n",
+ " full_transcript = \" \".join([f\"ts={entry['start']} - {entry['text']}\" for entry in transcript])\n",
+ "\n",
+ " # store the transcript in state\n",
+ " return state.update(transcript=full_transcript, youtube_url=youtube_url)\n",
+ "\n",
+ "\n",
+ "@action(reads=[\"transcript\"], writes=[\"post\"])\n",
+ "def generate_post(state: State, llm_client) -> State:\n",
+ " \"\"\"Use the Instructor LLM client to generate `SocialMediaPost` from the YouTube transcript.\"\"\"\n",
+ "\n",
+ " # read the transcript from state\n",
+ " transcript = state[\"transcript\"]\n",
+ "\n",
+ " response = llm_client.chat.completions.create(\n",
+ " model=\"gpt-4o-mini\",\n",
+ " response_model=SocialMediaPost,\n",
+ " messages=[\n",
+ " {\n",
+ " \"role\": \"system\",\n",
+ " \"content\": \"Analyze the given YouTube transcript and generate a compelling social media post.\",\n",
+ " },\n",
+ " {\"role\": \"user\", \"content\": transcript},\n",
+ " ],\n",
+ " )\n",
+ "\n",
+ " # add the youtube_url found in state to the SocialMediaPost\n",
+ " response.youtube_url = state[\"youtube_url\"]\n",
+ "\n",
+ " # store the chapters in state\n",
+ " return state.update(post=response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 2. Assemble the `Application`\n",
+ "\n",
+ "To create a Burr agent, we need to assemble the `actions` into an `Application`. This requires specifying the valid `transitions` between actions using tuples of action names `(from, to)` and defining an `entrypoint` from where to begin execution. Then, we can visualize the graph of possible states and actions.\n",
+ "\n",
+ "Notice that we create the Instructor LLM client *outside* the application and pass it to the `generate_chapters` action via the `.bind()` method. This method follows the same logic as the standard library `functools.partial()`."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "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=\"200pt\" height=\"174pt\"\n",
+ " viewBox=\"0.00 0.00 200.38 174.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 170)\">\n",
+ "<title>%3</title>\n",
+ "<polygon fill=\"white\" stroke=\"transparent\" points=\"-4,4 -4,-170 196.38,-170 196.38,4 -4,4\"/>\n",
+ "<!-- get_youtube_transcript -->\n",
+ "<g id=\"node1\" class=\"node\">\n",
+ "<title>get_youtube_transcript</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M175.19,-101C175.19,-101 17.19,-101 17.19,-101 11.19,-101 5.19,-95 5.19,-89 5.19,-89 5.19,-77 5.19,-77 5.19,-71 11.19,-65 17.19,-65 17.19,-65 175.19,-65 175.19,-65 181.19,-65 187.19,-71 187.19,-77 187.19,-77 187.19,-89 187.19,-89 187.19,-95 181.19,-101 175.19,-101\"/>\n",
+ "<text text-anchor=\"middle\" x=\"96.19\" y=\"-79.3\" font-family=\"Times,serif\" font-size=\"14.00\">get_youtube_transcript</text>\n",
+ "</g>\n",
+ "<!-- generate_post -->\n",
+ "<g id=\"node3\" class=\"node\">\n",
+ "<title>generate_post</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M143.19,-36C143.19,-36 49.19,-36 49.19,-36 43.19,-36 37.19,-30 37.19,-24 37.19,-24 37.19,-12 37.19,-12 37.19,-6 43.19,0 49.19,0 49.19,0 143.19,0 143.19,0 149.19,0 155.19,-6 155.19,-12 155.19,-12 155.19,-24 155.19,-24 155.19,-30 149.19,-36 143.19,-36\"/>\n",
+ "<text text-anchor=\"middle\" x=\"96.19\" y=\"-14.3\" font-family=\"Times,serif\" font-size=\"14.00\">generate_post</text>\n",
+ "</g>\n",
+ "<!-- get_youtube_transcript&#45;&gt;generate_post -->\n",
+ "<g id=\"edge2\" class=\"edge\">\n",
+ "<title>get_youtube_transcript&#45;&gt;generate_post</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M96.19,-64.78C96.19,-59.09 96.19,-52.61 96.19,-46.34\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"99.69,-46.19 96.19,-36.19 92.69,-46.19 99.69,-46.19\"/>\n",
+ "</g>\n",
+ "<!-- input__youtube_url -->\n",
+ "<g id=\"node2\" class=\"node\">\n",
+ "<title>input__youtube_url</title>\n",
+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"96.19\" cy=\"-148\" rx=\"96.38\" ry=\"18\"/>\n",
+ "<text text-anchor=\"middle\" x=\"96.19\" y=\"-144.3\" font-family=\"Times,serif\" font-size=\"14.00\">input: youtube_url</text>\n",
+ "</g>\n",
+ "<!-- input__youtube_url&#45;&gt;get_youtube_transcript -->\n",
+ "<g id=\"edge1\" class=\"edge\">\n",
+ "<title>input__youtube_url&#45;&gt;get_youtube_transcript</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M96.19,-129.78C96.19,-124.09 96.19,-117.61 96.19,-111.34\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"99.69,-111.19 96.19,-101.19 92.69,-111.19 99.69,-111.19\"/>\n",
+ "</g>\n",
+ "</g>\n",
+ "</svg>\n"
+ ],
+ "text/plain": [
+ "<graphviz.graphs.Digraph at 0x7fb343313b80>"
+ ]
+ },
+ "execution_count": 9,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "from burr.core import ApplicationBuilder\n",
+ "\n",
+ "application = (\n",
+ " ApplicationBuilder()\n",
+ " .with_actions(\n",
+ " get_youtube_transcript,\n",
+ " generate_post.bind(llm_client=llm_client),\n",
+ " )\n",
+ " .with_transitions(\n",
+ " (\"get_youtube_transcript\", \"generate_post\"),\n",
+ " )\n",
+ " .with_entrypoint(\"get_youtube_transcript\")\n",
+ " .build()\n",
+ ")\n",
+ "application.visualize()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 3. Launch the application\n",
+ "\n",
+ "Using `application.run()` will make our application iterate through actions and state until it hits a `halt` condition. Here, we will simply halt after completing the `generate_post` action. This will return a tuple of (the last action take, the result of the last action, the state of the app). We also need to pass a `youtube_url` since it's a required input to the `get_youtube_transcript` action."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "TOPIC: Burr Framework for Agent Applications\n",
+ "\n",
+ "Unlock the potential of your AI agents with Burr!\n",
+ "\n",
+ "Ever faced frustrating failures when building your AI agent applications? Explore how the Burr framework provides robust observability and state management that lets you debug effectively and even revisit previous states. Learn how you can create dynamic action graphs that not only streamline your Dev Loop but also help you track and fix errors without starting from scratch! Dive into our latest video to see Burr in action and discover how it can revolutionize your agent-building process!\n",
+ "\n",
+ "Burr enables dynamic action modeling and enhances state management. Debugging is simplified by tracking actions over time and allowing state forking. You can run applications seamlessly without starting from scratch after adjustments.\n",
+ "\n",
+ "link: https://www.youtube.com/watch?v=hqutVJyd3TI\n",
+ "\n",
+ "CONCEPTS\n",
+ "2:25 - State Management: A method to handle state data within applications, crucial for debugging and managing application flow.\n",
+ "2:10 - Action Graphs: A representation of various actions and their interdependencies, similar to flowcharts, used for modeling AI behavior.\n",
+ "0:42 - Observability: The ability to monitor and understand system state and behavior in real-time, facilitating easier debugging.\n"
+ ]
+ }
+ ],
+ "source": [
+ "last_action, result, state = application.run(\n",
+ " halt_after=[\"generate_post\"],\n",
+ " inputs={\"youtube_url\": \"https://www.youtube.com/watch?v=hqutVJyd3TI\"},\n",
+ ")\n",
+ "\n",
+ "# print `post` stored in state\n",
+ "print(state[\"post\"].display())"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Why create a Burr application?\n",
+ "\n",
+ "In a few lines of code, you can query an LLM API and can create powerful productivity utilities. However, user-facing features deserve much more scrutiny, which requires tooling and solving complex engineering problems.\n",
+ "\n",
+ "Building our app with Burr provides several benefits that we'll detail next:\n",
+ "- **Observability**: monitor in real-time and log the execution of your `Application` and view it in Burr's web user interface.\n",
+ "- **Persistence**: At any point, you can save the application `State`. This allows to create user sessions (e.g., the conversation history menu in ChatGPT), which helps developers investigate bugs and test potential solutions.\n",
+ "- **Portability**: your `Application` can run in a notebook, as a script, as a web service, or anywhere Python runs. We'll show how to use Burr with [FastAPI](https://fastapi.tiangolo.com/)."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 1. Observability\n",
+ "\n",
+ "Add the clause `.with_tracker(project=...)` to the `ApplicationBuilder()` to track execution. \n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 11,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from burr.core import ApplicationBuilder\n",
+ "\n",
+ "application = (\n",
+ " ApplicationBuilder()\n",
+ " .with_actions(\n",
+ " get_youtube_transcript,\n",
+ " generate_post.bind(llm_client=llm_client),\n",
+ " )\n",
+ " .with_transitions(\n",
+ " (\"get_youtube_transcript\", \"generate_post\"),\n",
+ " )\n",
+ " .with_entrypoint(\"get_youtube_transcript\")\n",
+ " .with_tracker(project=\"youtube-post\")\n",
+ " .build()\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "last_action, result, state = application.run(\n",
+ " halt_after=[\"generate_post\"],\n",
+ " inputs={\"youtube_url\": \"https://www.youtube.com/watch?v=hqutVJyd3TI\"},\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Then, you can launch the web UI via the CLI command `burr`"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 2. Persistence\n",
+ "\n",
+ "To showcase this feature, we'll add a `rewrite()` action. It sends to the LLM the social media post and a user input to tweak its content. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@action(reads=[\"post\"], writes=[\"post\"])\n",
+ "def rewrite_post(state: State, llm_client, user_prompt: str):\n",
+ " post = state[\"post\"]\n",
+ "\n",
+ " response = llm_client.chat.completions.create(\n",
+ " model=\"gpt-4o-mini\",\n",
+ " response_model=SocialMediaPost,\n",
+ " messages=[\n",
+ " {\n",
+ " \"role\": \"system\",\n",
+ " \"content\": f\"Take the previously generated social media post and modify it according to the following instructions: {user_prompt}\",\n",
+ " },\n",
+ " {\"role\": \"user\", \"content\": post.model_dump_json()},\n",
+ " ],\n",
+ " )\n",
+ "\n",
+ " # pass the youtube_url from the previous post version\n",
+ " response.youtube_url = post.youtube_url\n",
+ "\n",
+ " return state.update(post=response)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "By adding the transition `(\"rewrite_post\", \"rewrite_post\")`, we are introducing a graph cycle. Observability and persistence becomes particularly valuable to ensure that the LLM doesn't spiral into non-sense. If that's the case, it could be due to the prompts / instructions in the application code, but also user inputs.\n",
+ "\n",
+ "We also add a `.with_persister()` clause to store our results"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 26,
+ "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=\"409pt\" height=\"239pt\"\n",
+ " viewBox=\"0.00 0.00 408.93 239.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 235)\">\n",
+ "<title>%3</title>\n",
+ "<polygon fill=\"white\" stroke=\"transparent\" points=\"-4,4 -4,-235 404.93,-235 404.93,4 -4,4\"/>\n",
+ "<!-- get_youtube_transcript -->\n",
+ "<g id=\"node1\" class=\"node\">\n",
+ "<title>get_youtube_transcript</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M383.74,-166C383.74,-166 225.74,-166 225.74,-166 219.74,-166 213.74,-160 213.74,-154 213.74,-154 213.74,-142 213.74,-142 213.74,-136 219.74,-130 225.74,-130 225.74,-130 383.74,-130 383.74,-130 389.74,-130 395.74,-136 395.74,-142 395.74,-142 395.74,-154 395.74,-154 395.74,-160 389.74,-166 383.74,-166\"/>\n",
+ "<text text-anchor=\"middle\" x=\"304.74\" y=\"-144.3\" font-family=\"Times,serif\" font-size=\"14.00\">get_youtube_transcript</text>\n",
+ "</g>\n",
+ "<!-- generate_post -->\n",
+ "<g id=\"node3\" class=\"node\">\n",
+ "<title>generate_post</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M351.74,-101C351.74,-101 257.74,-101 257.74,-101 251.74,-101 245.74,-95 245.74,-89 245.74,-89 245.74,-77 245.74,-77 245.74,-71 251.74,-65 257.74,-65 257.74,-65 351.74,-65 351.74,-65 357.74,-65 363.74,-71 363.74,-77 363.74,-77 363.74,-89 363.74,-89 363.74,-95 357.74,-101 351.74,-101\"/>\n",
+ "<text text-anchor=\"middle\" x=\"304.74\" y=\"-79.3\" font-family=\"Times,serif\" font-size=\"14.00\">generate_post</text>\n",
+ "</g>\n",
+ "<!-- get_youtube_transcript&#45;&gt;generate_post -->\n",
+ "<g id=\"edge3\" class=\"edge\">\n",
+ "<title>get_youtube_transcript&#45;&gt;generate_post</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M304.74,-129.78C304.74,-124.09 304.74,-117.61 304.74,-111.34\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"308.24,-111.19 304.74,-101.19 301.24,-111.19 308.24,-111.19\"/>\n",
+ "</g>\n",
+ "<!-- input__youtube_url -->\n",
+ "<g id=\"node2\" class=\"node\">\n",
+ "<title>input__youtube_url</title>\n",
+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"304.74\" cy=\"-213\" rx=\"96.38\" ry=\"18\"/>\n",
+ "<text text-anchor=\"middle\" x=\"304.74\" y=\"-209.3\" font-family=\"Times,serif\" font-size=\"14.00\">input: youtube_url</text>\n",
+ "</g>\n",
+ "<!-- input__youtube_url&#45;&gt;get_youtube_transcript -->\n",
+ "<g id=\"edge1\" class=\"edge\">\n",
+ "<title>input__youtube_url&#45;&gt;get_youtube_transcript</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M304.74,-194.78C304.74,-189.09 304.74,-182.61 304.74,-176.34\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"308.24,-176.19 304.74,-166.19 301.24,-176.19 308.24,-176.19\"/>\n",
+ "</g>\n",
+ "<!-- rewrite_post -->\n",
+ "<g id=\"node4\" class=\"node\">\n",
+ "<title>rewrite_post</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M250.24,-36C250.24,-36 167.24,-36 167.24,-36 161.24,-36 155.24,-30 155.24,-24 155.24,-24 155.24,-12 155.24,-12 155.24,-6 161.24,0 167.24,0 167.24,0 250.24,0 250.24,0 256.24,0 262.24,-6 262.24,-12 262.24,-12 262.24,-24 262.24,-24 262.24,-30 256.24,-36 250.24,-36\"/>\n",
+ "<text text-anchor=\"middle\" x=\"208.74\" y=\"-14.3\" font-family=\"Times,serif\" font-size=\"14.00\">rewrite_post</text>\n",
+ "</g>\n",
+ "<!-- generate_post&#45;&gt;rewrite_post -->\n",
+ "<g id=\"edge4\" class=\"edge\">\n",
+ "<title>generate_post&#45;&gt;rewrite_post</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M278.76,-64.95C267.88,-57.81 255.06,-49.4 243.39,-41.74\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"245.02,-38.62 234.74,-36.06 241.18,-44.48 245.02,-38.62\"/>\n",
+ "</g>\n",
+ "<!-- rewrite_post&#45;&gt;rewrite_post -->\n",
+ "<g id=\"edge5\" class=\"edge\">\n",
+ "<title>rewrite_post&#45;&gt;rewrite_post</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M262.37,-29.47C272.82,-28.13 280.24,-24.31 280.24,-18 280.24,-13.96 277.19,-10.93 272.26,-8.93\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"272.92,-5.49 262.37,-6.53 271.26,-12.29 272.92,-5.49\"/>\n",
+ "</g>\n",
+ "<!-- input__rewrite_prompt -->\n",
+ "<g id=\"node5\" class=\"node\">\n",
+ "<title>input__rewrite_prompt</title>\n",
+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"113.74\" cy=\"-83\" rx=\"113.98\" ry=\"18\"/>\n",
+ "<text text-anchor=\"middle\" x=\"113.74\" y=\"-79.3\" font-family=\"Times,serif\" font-size=\"14.00\">input: rewrite_prompt</text>\n",
+ "</g>\n",
+ "<!-- input__rewrite_prompt&#45;&gt;rewrite_post -->\n",
+ "<g id=\"edge2\" class=\"edge\">\n",
+ "<title>input__rewrite_prompt&#45;&gt;rewrite_post</title>\n",
+ "<path fill=\"none\" stroke=\"black\" d=\"M139.2,-65.12C149.97,-57.97 162.69,-49.54 174.28,-41.85\"/>\n",
+ "<polygon fill=\"black\" stroke=\"black\" points=\"176.48,-44.59 182.88,-36.15 172.61,-38.76 176.48,-44.59\"/>\n",
+ "</g>\n",
+ "</g>\n",
+ "</svg>\n"
+ ],
+ "text/plain": [
+ "<graphviz.graphs.Digraph at 0x7fb318a68c70>"
+ ]
+ },
+ "execution_count": 26,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "from burr.core import ApplicationBuilder\n",
+ "from burr.core.persistence import SQLLitePersister\n",
+ "\n",
+ "application = (\n",
+ " ApplicationBuilder()\n",
+ " .with_actions(\n",
+ " get_youtube_transcript,\n",
+ " generate_post.bind(llm_client=llm_client),\n",
+ " rewrite_post.bind(llm_client=llm_client),\n",
+ " )\n",
+ " .with_transitions(\n",
+ " (\"get_youtube_transcript\", \"generate_post\"),\n",
+ " (\"generate_post\", \"rewrite_post\"),\n",
+ " (\"rewrite_post\", \"rewrite_post\"),\n",
+ " )\n",
+ " .with_state_persister(\n",
+ " SQLLitePersister(db_path=\".burr.db\", table_name=\"state\")\n",
+ " )\n",
+ " .with_entrypoint(\"get_youtube_transcript\")\n",
+ " .with_tracker(project=\"youtube-post\")\n",
+ " .build()\n",
+ ")\n",
+ "application.visualize(output_file_path=\"statemachine.png\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 23,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "LAST ACTION : generate_post: transcript -> post \n",
+ "\n",
+ "TOPIC: Debugging and Observability in Agent Applications with Burr\n",
+ "\n",
+ "🚀 Struggling to debug your AI agent? Meet Burr!\n",
+ "\n",
+ "In this video, we dive into how Burr can transform your debugging experience for AI agents. Discover how it helps you monitor, debug, and handle errors without starting from scratch. With its unique approach to state management and action modeling, Burr simplifies navigating through failures and understanding your code's behavior. Let's explore the power of visualizing your application as a graph and how you can seamlessly fix issues without losing your progress! 🎥✨\n",
+ "\n",
+ "Burr offers an innovative way to visualize action flows in AI agents. Debugging becomes easier by allowing developers to fix bugs without restarting the whole application. Explore how using a state object facilitates communication between different actions in your code.\n",
+ "\n",
+ "link: https://www.youtube.com/watch?v=hqutVJyd3TI\n",
+ "\n",
+ "CONCEPTS\n",
+ "2:25 - State Object: A state object is used for reading and writing state, allowing actions within the application to communicate effectively.\n",
+ "1:58 - Graph Structure: A representation of the agent's actions and states as nodes and edges, enabling clear visual tracking of the application's flow.\n",
+ "4:16 - Local Tracker: A feature that helps to track and introspect your application's state during debugging and monitoring phases.\n"
+ ]
+ }
+ ],
+ "source": [
+ "# this will run \n",
+ "last_action, result, state = application.run(\n",
+ " halt_after=[\"generate_post\"],\n",
+ " inputs={\"youtube_url\": \"https://www.youtube.com/watch?v=hqutVJyd3TI\"},\n",
+ ")\n",
+ "print(\"LAST ACTION :\", last_action, \"\\n\")\n",
+ "print(state[\"post\"].display())"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 24,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "LAST ACTION : rewrite_post: post -> post \n",
+ "\n",
+ "TOPIC: Debugging and Observability in Agent Applications with Burr\n",
+ "\n",
+ "🚀 Struggling to debug your AI agent? Meet Burr!\n",
+ "\n",
+ "In this informative video, we explore how Burr can enhance your debugging experience for AI agents. Learn about its capabilities in monitoring, debugging, and managing errors without the need to start from scratch. Discover the role of state management and action modeling in simplifying the navigation through failures and understanding your code's behavior. We will also discuss how visualizing your application as a graph can help in seamlessly addressing issues while retaining progress. Click the link to learn more! 🎥✨\n",
+ "\n",
+ "Burr offers an innovative way to visualize action flows in AI agents. Debugging becomes easier by allowing developers to fix bugs without restarting the whole application. Explore how using a state object facilitates communication between different actions in your code.\n",
+ "\n",
+ "CONCEPTS\n",
+ "2:25 - State Object: A state object is used for reading and writing state, allowing actions within the application to communicate effectively.\n",
+ "1:58 - Graph Structure: A representation of the agent's actions and states as nodes and edges, enabling clear visual tracking of the application's flow.\n",
+ "4:16 - Local Tracker: A feature that helps to track and introspect your application's state during debugging and monitoring phases.\n"
+ ]
+ }
+ ],
+ "source": [
+ "last_action, result, state = application.step(\n",
+ " inputs={\"user_prompt\": \"Adopt a professional tone that avoids incredible claims. Stay close to the facts, but demonstrate enthusiasm\"},\n",
+ ")\n",
+ "\n",
+ "print(\"LAST ACTION :\", last_action, \"\\n\")\n",
+ "print(state[\"post\"].display())"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### 3. Portability\n",
+ "\n",
+ "In the GitHub repository, you can find the same Burr `Application` defined in `application.py`, which can be executed via `python application.py`. Also, we provide a boilerplate FastAPI application in `server.py` which imports the `Application` defined in `application.py`"
+ ]
+ }
+ ],
+ "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": 4
+}
diff --git a/examples/youtube-to-social-media-post/server.py b/examples/youtube-to-social-media-post/server.py
new file mode 100644
index 00000000..75b8a4d4
--- /dev/null
+++ b/examples/youtube-to-social-media-post/server.py
@@ -0,0 +1,46 @@
+import contextlib
+import logging
+from typing import Optional
+
+import application
+import fastapi
+import uvicorn
+
+from burr.core import Application
+
+logger = logging.getLogger(__name__)
+
+# define a global `burr_app` variable
+burr_app: Optional[Application] = None
+
+
+def get_burr_app() -> Application:
+ """Retrieve the global Burr app."""
+ if burr_app is None:
+ raise RuntimeError("Burr app wasn't instantiated.")
+ return burr_app
+
+
+async def lifespan(app: fastapi.FastAPI):
+ """Instantiate the Burr application on FastAPI startup."""
+ # set value for the global `burr_app` variable
+ global burr_app
+ burr_app = application.build_application()
+ yield
+
+
+app = fastapi.FastAPI(lifespan=lifespan)
+
+
[email protected]("/social_media_post")
+def social_media_post(youtube_url: str, burr_app: Application = fastapi.Depends(get_burr_app)):
+ """Creates a completion for the chat message"""
+ _, _, state = burr_app.run(halt_after=["generate_post"], inputs={"youtube_url": youtube_url})
+
+ post = state["post"]
+ return {"formatted_post": post.display(), "post": post.model_dump()}
+
+
+if __name__ == "__main__":
+ uvicorn.run("server:app", host="127.0.0.1", port=7443, reload=True)
diff --git a/examples/youtube-to-social-media-post/statemachine.png b/examples/youtube-to-social-media-post/statemachine.png
new file mode 100644
index 00000000..bdf72f90
Binary files /dev/null and b/examples/youtube-to-social-media-post/statemachine.png differ