Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.
Python aiburrchatbot-frameworkdagsgenerative-aigraphshacktoberfestllmopsllmsmlopspersistent-data-structurestate-machinestate-managementvisibility
Documentation + cleanup for @action.pydantic
elijahbenizzy3863673d953f
diff --git a/burr/core/action.py b/burr/core/action.pyindex 7f99f48e..cb9a7ac5 100644--- a/burr/core/action.py+++ b/burr/core/action.py@@ -1189,6 +1189,19 @@ class action:state_input_type: Optional[Type["BaseModel"]] = None,state_output_type: Optional[Type["BaseModel"]] = None,) -> Callable:+ """Action that specifies inputs/outputs using pydantic models.+ This should make it easier to develop with guardrails.++ :param reads: keys that this model reads. Note that this will be a subset of the pydantic model with which this is decorated.+ We will be validating that the keys are present in the model.+ :param writes: keys that this model writes. Note that this will be a subset of the pydantic model with which this is decorated.+ We will be validating that the keys are present in the model.+ :param state_input_type: The pydantic model type that is used to represent the input state.+ If this is None it will attempt to derive from the signature.+ :param state_output_type: The pydantic model type that is used to represent the output state.+ If this is None it will attempt to derive from the signature.+ :return:+ """try:from burr.integrations.pydantic import pydantic_actionexcept ImportError:@@ -1238,11 +1251,21 @@ class streaming_action:state_output_type: Type["BaseModel"],stream_type: Union[Type["BaseModel"], Type[dict]],) -> Callable:+ """Creates a streaming action that uses pydantic models.++ :param reads: The fields this consumes from the state.+ :param writes: The fields this writes to the state.+ :param stream_type: The pydantic model or dictionary type that is used to represent the partial results.+ Use a dict if you want this untyped.+ :param state_input_type: The pydantic model type that is used to represent the input state.+ :param state_output_type: The pydantic model type that is used to represent the output state.+ :return: The same function, decorated function.+ """try:from burr.integrations.pydantic import pydantic_streaming_actionexcept ImportError:raise ImportError(- "Please install pydantic to use the pydantic decorator. pip install burr[pydantic]"+ "Please install pydantic to use the pydantic decorator. pip install 'burr[pydantic]'")return pydantic_streaming_action(diff --git a/burr/core/application.py b/burr/core/application.pyindex 2cdd2303..30c92b9a 100644--- a/burr/core/application.py+++ b/burr/core/application.py@@ -53,8 +53,8 @@ from burr.visibility import tracingfrom burr.visibility.tracing import tracer_factory_context_varif TYPE_CHECKING:- # TODO -- push type-checking check back from here- # OR just put everything under type-chekcing...+ # TODO -- figure out whether we want to just do if TYPE_CHECKING+ # for all first-class imports as Ruff suggests...from burr.tracking.base import TrackingClientlogger = logging.getLogger(__name__)@@ -67,10 +67,8 @@ StateTypeToSet = TypeVar("StateTypeToSet")def _validate_result(result: Any, name: str, schema: ActionSchema = DEFAULT_SCHEMA) -> None:- # TODO -- validate the output type is action schema's output type...# TODO -- split out the action schema into input/output schema types- # Then action schema will have both- # we'll just need to ensure we pass the right ones+ # Currently they're tied together, but this doesn't make as much sense for single-step actionsresult_type = schema.intermediate_result_type()if not isinstance(result, result_type):raise ValueError(@@ -2318,7 +2316,7 @@ class ApplicationBuilder(Generic[StateType]):return self.graph_builder.build()return self.prebuilt_graph- # @telemetry.capture_function_usage+ @telemetry.capture_function_usagedef build(self) -> Application[StateType]:"""Builds the application.@@ -2368,18 +2366,3 @@ class ApplicationBuilder(Generic[StateType]):else None),)---if __name__ == "__main__":- import pydantic-- class Foo(pydantic.BaseModel):- a: int- b: str-- from burr.integrations import pydantic-- app = ApplicationBuilder().with_typing(pydantic.PydanticTypingSystem(Foo)).build()-- _, _, foo = app.run(inputs={"a": 1, "b": "hello"})- mod = foo.datadiff --git a/burr/integrations/pydantic.py b/burr/integrations/pydantic.pyindex 4b458e7b..ebe8a63a 100644--- a/burr/integrations/pydantic.py+++ b/burr/integrations/pydantic.py@@ -170,15 +170,7 @@ def pydantic_action(state_input_type: Optional[Type[pydantic.BaseModel]] = None,state_output_type: Optional[Type[pydantic.BaseModel]] = None,) -> Callable[[PydanticActionFunction], PydanticActionFunction]:- """Action that specifies inputs/outputs using pydantic models.- This should make it easier to develop with guardrails.-- :param reads: keys that this model reads. Note that this will be a subset of the pydantic model with which this is decorated.- We will be validating that the keys are present in the model.- :param writes: keys that this model writes. Note that this will be a subset of the pydantic model with which this is decorated.- We will be validating that the keys are present in the model.- :return:- """+ """See docstring for @action.pydantic"""def decorator(fn: PydanticActionFunction) -> PydanticActionFunction:if state_input_type is None and state_output_type is None:@@ -296,16 +288,7 @@ def pydantic_streaming_action(state_output_type: Type[pydantic.BaseModel],stream_type: PartialType,) -> Callable[[PydanticStreamingActionFunction], PydanticStreamingActionFunction]:- """Creates a streaming action that uses pydantic models.-- :param reads: The fields this consumes from the state.- :param writes: The fields this writes to the state.- :param stream_type: The pydantic model or dictionary type that is used to represent the partial results. If this is None it will attempt to derive from the signature.- Use a dict if you want this untyped.- :param state_input_type: The pydantic model type that is used to represent the input state. If this is None it will attempt to derive from the signature.- :param state_output_type: The pydantic model type that is used to represent the output state. If this is None it will attempt to derive from the signature.- :return: The same function, decorated function.- """+ """See docstring for @streaming_action.pydantic"""def decorator(fn: PydanticStreamingActionFunctionVar) -> PydanticStreamingActionFunctionVar:itype, otype, stream_type_processed = _validate_and_extract_signature_types_streaming(@@ -353,8 +336,6 @@ def pydantic_streaming_action(is_async = inspect.isasyncgenfunction(fn)# This recreates the @streaming_action decorator# TODO -- use the @streaming_action decorator directly- # TODO -- ensure that the function is the right one -- specifically it probably won't show code in the UI- # nowsetattr(fn,FunctionBasedAction.ACTION_FUNCTION,diff --git a/docs/reference/actions.rst b/docs/reference/actions.rstindex ce473ac8..72d52e1d 100644--- a/docs/reference/actions.rst+++ b/docs/reference/actions.rst@@ -22,7 +22,12 @@ Actions.. automethod:: __init__-.. autodecorator:: burr.core.action.action+.. autoclass:: burr.core.action.action+ :members:++ .. automethod:: __init__++.. autofunction:: burr.core.action.binddiff --git a/docs/reference/index.rst b/docs/reference/index.rstindex 0613b28b..f6e96eec 100644--- a/docs/reference/index.rst+++ b/docs/reference/index.rst@@ -1,3 +1,4 @@+.. _reference:========================@@ -20,5 +21,6 @@ need functionality that is not publicly exposed, please open an issue and we cantrackingvisibilitylifecycle+ typingintegrations/indextelemetrydiff --git a/docs/reference/tracking.rst b/docs/reference/tracking.rstindex 73c9c4fa..ea317156 100644--- a/docs/reference/tracking.rst+++ b/docs/reference/tracking.rst@@ -3,7 +3,7 @@ Tracking========Reference on the Tracking/Telemetry API.-Rather, you should use this throug/in conjunction with :py:meth:`burr.core.application.ApplicationBuilder.with_tracker`.+Rather, you should use this through/in conjunction with :py:meth:`burr.core.application.ApplicationBuilder.with_tracker`... autoclass:: burr.tracking.LocalTrackingClientdiff --git a/examples/pydantic/centralized_state.py b/examples/pydantic/centralized_state.pydeleted file mode 100644index 5a57f891..00000000--- a/examples/pydantic/centralized_state.py+++ /dev/null@@ -1,217 +0,0 @@-import copy-import os-from typing import List, Optional--import openai-import pydantic--from burr.core import ApplicationBuilder, State, action, default, graph, when-from burr.integrations.pydantic import PydanticTypingSystem, pydantic_action-from burr.lifecycle import LifecycleAdapter--MODES = {- "answer_question": "text",- "generate_image": "image",- "generate_code": "code",- "unknown": "text",-}---class ApplicationState(pydantic.BaseModel):- chat_history: List[dict[str, str]] = pydantic.Field(default_factory=list)- prompt: Optional[str]- has_openai_key: Optional[bool]- safe: Optional[bool]- mode: Optional[str]- response: dict[str, str]---@pydantic_action(reads=[], writes=["chat_history", "prompt"])-def process_prompt(state: ApplicationState, prompt: str) -> ApplicationState:- state.chat_history.append({"role": "user", "content": prompt, "type": "text"})- state.prompt = prompt- return state---@pydantic_action(reads=["prompt"], writes=["safe"])-def check_safety(state: ApplicationState) -> ApplicationState:- state.safe = "unsafe" not in state.prompt- return state---def _get_openai_client():- return openai.Client()---@pydantic_action(reads=["prompt"], writes=["mode"])-def choose_mode(state: ApplicationState) -> ApplicationState:- prompt = (- f"You are a chatbot. You've been prompted this: {state.prompt}. "- f"You have the capability of responding in the following modes: {', '.join(MODES)}. "- "Please respond with *only* a single word representing the mode that most accurately "- "corresponds to the prompt. Fr instance, if the prompt is 'draw a picture of a cat', "- "the mode would be 'generate_image'. If the prompt is 'what is the capital of France', the mode would be 'answer_question'."- "If none of these modes apply, please respond with 'unknown'."- )-- result = _get_openai_client().chat.completions.create(- model="gpt-4",- messages=[- {"role": "system", "content": "You are a helpful assistant"},- {"role": "user", "content": prompt},- ],- )- content = result.choices[0].message.content- mode = content.lower()- if mode not in MODES:- mode = "unknown"- state.mode = mode- return state---@pydantic_action(reads=["prompt", "chat_history"], writes=["response"])-def prompt_for_more(state: ApplicationState) -> ApplicationState:- state.response = {- "content": "None of the response modes I support apply to your question. Please clarify?",- "type": "text",- "role": "assistant",- }- return state---@action(reads=[], writes=["has_openai_key"])-def check_openai_key(state: State) -> State:- result = {"has_openai_key": "OPENAI_API_KEY" in os.environ}- return state.update(**result)---@pydantic_action(reads=["prompt", "chat_history", "mode"], writes=["response"])-def chat_response(- state: ApplicationState,- prepend_prompt: str,- model: str = "gpt-3.5-turbo",-) -> ApplicationState:- chat_history = copy.deepcopy(state.chat_history)- chat_history[-1]["content"] = f"{prepend_prompt}: {chat_history[-1]['content']}"- chat_history_api_format = [- {- "role": chat["role"],- "content": chat["content"],- }- for chat in chat_history- ]- client = _get_openai_client()- result = client.chat.completions.create(- model=model,- messages=chat_history_api_format,- )- response = result.choices[0].message.content- state.response = {"content": response, "type": MODES[state.mode], "role": "assistant"}- return state---@pydantic_action(reads=["prompt", "chat_history", "mode"], writes=["response"])-def image_response(state: ApplicationState, model: str = "dall-e-2") -> ApplicationState:- client = _get_openai_client()- result = client.images.generate(- model=model, prompt=state.prompt, size="1024x1024", quality="standard", n=1- )- response = result.data[0].url- state.response = {"content": response, "type": MODES[state.mode], "role": "assistant"}- return state---@pydantic_action(reads=["response", "mode", "safe", "has_openai_key"], writes=["chat_history"])-def response(state: ApplicationState) -> ApplicationState:- if not state.has_openai_key:- chat_item = {- "role": "assistant",- "content": "You have not set an API key for [OpenAI](https://www.openai.com). Do this "- "by setting the environment variable `OPENAI_API_KEY` to your key. "- "You can get a key at [OpenAI](https://platform.openai.com). "- "You can still look at chat history/examples.",- "type": "error",- }- elif not state.safe:- chat_item = {- "role": "assistant",- "content": "I'm sorry, I can't respond to that.",- "type": "error",- }- else:- chat_item = state.response- state.chat_history.append(chat_item)- return state---graph_object = (- graph.GraphBuilder()- .with_actions(- prompt=process_prompt,- check_openai_key=check_openai_key,- check_safety=check_safety,- decide_mode=choose_mode,- generate_image=image_response,- generate_code=chat_response.bind(- prepend_prompt="Please respond with *only* code and no other text (at all) to the following:",- ),- answer_question=chat_response.bind(- prepend_prompt="Please answer the following question:",- ),- prompt_for_more=prompt_for_more,- response=response,- )- .with_transitions(- ("prompt", "check_openai_key", default),- ("check_openai_key", "check_safety", when(has_openai_key=True)),- ("check_openai_key", "response", default),- ("check_safety", "decide_mode", when(safe=True)),- ("check_safety", "response", default),- ("decide_mode", "generate_image", when(mode="generate_image")),- ("decide_mode", "generate_code", when(mode="generate_code")),- ("decide_mode", "answer_question", when(mode="answer_question")),- ("decide_mode", "prompt_for_more", default),- (- ["generate_image", "answer_question", "generate_code", "prompt_for_more"],- "response",- ),- ("response", "prompt", default),- )- .build()-)---def application(- hooks: Optional[List[LifecycleAdapter]] = None,- project_id: str = "test_centralized_state",-):- if hooks is None:- hooks = []- # we're initializing above so we can load from this as well- # we could also use `with_tracker("local", project=project_id, params={"storage_dir": storage_dir})`- return (- ApplicationBuilder()- .with_graph(graph_object)- # initializes from the tracking log if it does not already exist- .with_hooks(*hooks)- .with_tracker("local", project=project_id)- .with_entrypoint("prompt")- .with_state(- ApplicationState(- chat_history=[],- )- )- .with_typing(PydanticTypingSystem(model_type=ApplicationState))- .build()- )---if __name__ == "__main__":- app = application()- # app.visualize(- # output_file_path="statemachine", include_conditions=False, view=True, format="png"- # )- action, result, state = app.run(- halt_after=["response"], inputs={"prompt": "Who was Aaron Burr, sir?"}- )- state.datadiff --git a/examples/pydantic/decentralized_state.py b/examples/pydantic/decentralized_state.pydeleted file mode 100644index 5f40da57..00000000--- a/examples/pydantic/decentralized_state.py+++ /dev/null@@ -1,224 +0,0 @@-import copy-import os-from typing import List, Optional--import openai--from burr.core import Application, ApplicationBuilder, State, default, graph, when-from burr.core.action import action-from burr.lifecycle import LifecycleAdapter-from burr.tracking import LocalTrackingClient--MODES = {- "answer_question": "text",- "generate_image": "image",- "generate_code": "code",- "unknown": "text",-}---@action(reads=[], writes=["chat_history", "prompt"])-def process_prompt(state: State, prompt: str) -> State:- result = {"chat_item": {"role": "user", "content": prompt, "type": "text"}}- return (- state.wipe(keep=["prompt", "chat_history"])- .append(chat_history=result["chat_item"])- .update(prompt=prompt)- )---@action(reads=[], writes=["has_openai_key"])-def check_openai_key(state: State) -> State:- result = {"has_openai_key": "OPENAI_API_KEY" in os.environ}- return state.update(**result)---@action(reads=["prompt"], writes=["safe"])-def check_safety(state: State) -> State:- result = {"safe": "unsafe" not in state["prompt"]} # quick hack to demonstrate- return state.update(safe=result["safe"])---def _get_openai_client():- return openai.Client()---@action(reads=["prompt"], writes=["mode"])-def choose_mode(state: State) -> State:- prompt = (- f"You are a chatbot. You've been prompted this: {state['prompt']}. "- f"You have the capability of responding in the following modes: {', '.join(MODES)}. "- "Please respond with *only* a single word representing the mode that most accurately "- "corresponds to the prompt. Fr instance, if the prompt is 'draw a picture of a cat', "- "the mode would be 'generate_image'. If the prompt is 'what is the capital of France', the mode would be 'answer_question'."- "If none of these modes apply, please respond with 'unknown'."- )-- result = _get_openai_client().chat.completions.create(- model="gpt-4",- messages=[- {"role": "system", "content": "You are a helpful assistant"},- {"role": "user", "content": prompt},- ],- )- content = result.choices[0].message.content- mode = content.lower()- if mode not in MODES:- mode = "unknown"- result = {"mode": mode}- return state.update(**result)---@action(reads=["prompt", "chat_history"], writes=["response"])-def prompt_for_more(state: State) -> State:- result = {- "response": {- "content": "None of the response modes I support apply to your question. Please clarify?",- "type": "text",- "role": "assistant",- }- }- return state.update(**result)---@action(reads=["prompt", "chat_history", "mode"], writes=["response"])-def chat_response(- state: State, prepend_prompt: str, display_type: str = "text", model: str = "gpt-3.5-turbo"-) -> State:- chat_history = copy.deepcopy(state["chat_history"])- chat_history[-1]["content"] = f"{prepend_prompt}: {chat_history[-1]['content']}"- chat_history_api_format = [- {- "role": chat["role"],- "content": chat["content"],- }- for chat in chat_history- ]- client = _get_openai_client()- result = client.chat.completions.create(- model=model,- messages=chat_history_api_format,- )- response = result.choices[0].message.content- result = {"response": {"content": response, "type": MODES[state["mode"]], "role": "assistant"}}- return state.update(**result)---@action(reads=["prompt", "chat_history", "mode"], writes=["response"])-def image_response(state: State, model: str = "dall-e-2") -> State:- """Generates an image response to the prompt. Optional save function to save the image to a URL."""- client = _get_openai_client()- result = client.images.generate(- model=model, prompt=state["prompt"], size="1024x1024", quality="standard", n=1- )- response = result.data[0].url- result = {"response": {"content": response, "type": MODES[state["mode"]], "role": "assistant"}}- return state.update(**result)---@action(reads=["response", "mode", "safe", "has_openai_key"], writes=["chat_history"])-def response(state: State) -> State:- if not state["has_openai_key"]:- result = {- "chat_item": {- "role": "assistant",- "content": "You have not set an API key for [OpenAI](https://www.openai.com). Do this "- "by setting the environment variable `OPENAI_API_KEY` to your key. "- "You can get a key at [OpenAI](https://platform.openai.com). "- "You can still look at chat history/examples.",- "type": "error",- }- }- elif not state["safe"]:- result = {- "chat_item": {- "role": "assistant",- "content": "I'm sorry, I can't respond to that.",- "type": "error",- }- }- else:- result = {"chat_item": state["response"]}- return state.append(chat_history=result["chat_item"])---graph = (- graph.GraphBuilder()- .with_actions(- prompt=process_prompt,- check_openai_key=check_openai_key,- check_safety=check_safety,- decide_mode=choose_mode,- generate_image=image_response,- generate_code=chat_response.bind(- prepend_prompt="Please respond with *only* code and no other text (at all) to the following:",- ),- answer_question=chat_response.bind(- prepend_prompt="Please answer the following question:",- ),- prompt_for_more=prompt_for_more,- response=response,- )- .with_transitions(- ("prompt", "check_openai_key", default),- ("check_openai_key", "check_safety", when(has_openai_key=True)),- ("check_openai_key", "response", default),- ("check_safety", "decide_mode", when(safe=True)),- ("check_safety", "response", default),- ("decide_mode", "generate_image", when(mode="generate_image")),- ("decide_mode", "generate_code", when(mode="generate_code")),- ("decide_mode", "answer_question", when(mode="answer_question")),- ("decide_mode", "prompt_for_more", default),- (- ["generate_image", "answer_question", "generate_code", "prompt_for_more"],- "response",- ),- ("response", "prompt", default),- )- .build()-)---def base_application(- hooks: List[LifecycleAdapter],- app_id: str,- storage_dir: str,- project_id: str,-):- if hooks is None:- hooks = []- # we're initializing above so we can load from this as well- # we could also use `with_tracker("local", project=project_id, params={"storage_dir": storage_dir})`- tracker = LocalTrackingClient(project=project_id, storage_dir=storage_dir)- return (- ApplicationBuilder()- .with_graph(graph)- # initializes from the tracking log if it does not already exist- .initialize_from(- tracker,- resume_at_next_action=False, # always resume from entrypoint in the case of failure- default_state={"chat_history": []},- default_entrypoint="prompt",- )- .with_hooks(*hooks)- .with_tracker(tracker)- .with_identifiers(app_id=app_id)- .build()- )---def application(- app_id: Optional[str] = None,- project_id: str = "demo_chatbot",- storage_dir: Optional[str] = "~/.burr",- hooks: Optional[List[LifecycleAdapter]] = None,-) -> Application:- return base_application(hooks, app_id, storage_dir, project_id=project_id)---if __name__ == "__main__":- app = application()- app.visualize(- output_file_path="statemachine", include_conditions=False, view=True, format="png"- )- print(app.run(halt_after=["response"], inputs={"prompt": "Who was Aaron Burr, sir?"}))diff --git a/examples/typed-state/README.md b/examples/typed-state/README.mdnew file mode 100644index 00000000..361c9fed--- /dev/null+++ b/examples/typed-state/README.md@@ -0,0 +1,263 @@+# Typed State++This example goes over how to use the typed state features in Burr with pydantic.++It will cover the following concepts:++1. Why you might want to use typing for your state in the first place+1. Define typing at the application level+1. Defining/altering state at the action level+1. Doing so in a streaming manner+1. Wiring that through to a FastAPI app++This README will contain snippets + link out to the code.++This adapts the [instructor + youtube example](../youtube-to-social-media-post/). This+takes in a youtube video, creates a transcript, and uses OpenAI to generate a social media post based on that transcript.++## Why type state?++Burr originally came without typing -- typing is an additional (optional) plugin that requires some complexity. So, why use typing at all? And why use Pydantic? Lots of good reasons:++### Typing provides guard-rails++Typing state ensures you have guarentees about what the data in your state is, and what shape it takes. This makes it easier to work with/manipulate.++### Typing makes development easier++IDEs have integrations for handling type annotations, enabling you to+avoid the cognitive burden of tracking types in your head. You get auto-completion on typed classes, and errors if you attempt to access or assign to a field that does not exist.++### Typing makes downstream integration easier++Multiple tools use types (especially with pydantic) to make interacting with data easier. In this example we use [instructor](https://python.useinstructor.com/blog/), as well as [FastAPI](https://fastapi.tiangolo.com/) to leverage pydantic models that Burr also uses.++### Typing provides a form of documentation++Type-annotation in python allows you to read your code and get some sense of what it is actually doing. This can be a warm introduction to python for those who came from the world of java initially (the authors of this library included), and make reasoning about a complex codebase simpler.++## Setting up your IDE++VSCode (or an editor with a similar interface) is generally optimal for this. It has+pluggable typing (e.g. pylance), which handles generics cleanly. Unfortunately pycharm+is often behind on typing support. See issues like [this](https://youtrack.jetbrains.com/issue/PY-44364) and [this](https://youtrack.jetbrains.com/issue/PY-27627/Support-explicitly-parametrized-generic-class-instantiation-syntax).++While it will still work in pycharm, you will not get some of the beter auto-completion capabilities.++## Defining typed state at the application level++This code for this is in [application.py](application.py).++First, define a pydantic model -- make it as recursive as you want. This will represent+your entire state. In this case, we're going to have a transcript of a youtube video that+was given by the user, as well as the social media post. The high-level is here -- the rest is+in the code:++```python+class ApplicationState(BaseModel):+ # Make these have defaults as they are only set in actions+ transcript: Optional[str] = Field(+ description="The full transcript of the YouTube video.", default=None+ )+ post: Optional[SocialMediaPost] = Field(+ description="The generated social media post.", default=None+ )+```++Note that this should exactly model your state -- we need to make things optional,+as there are points in the state where the transcript/post will not have been assigned.++Next, we add it in to the application object, both the initial value and the typing system.+The typing system is what's responsible for managing the schema:++```python+app = (+ ApplicationBuilder()+ .with_actions(+ ...+ )+ .with_transitions(+ ...+ )+ .with_entrypoint(...)+ .with_typing(PydanticTypingSystem(ApplicationState))+ .with_state(ApplicationState())+ .build()+ )+```++That ensures that application and the application's state object are parameterized on the state type.++To get the state, you can use `.data` on any state object returned by the application++```python+# just from the application+print(app.state.data.transcript)++# after execution+_, _, state = app.run(halt_after=..., inputs=...)+print(state.data.transcript)+```++## Defining/altering typed state at the action level++This code for this is in [application.py](application.py).++In addition to defining state centrally, we can define it at an action level.++The code is simple, but the API is slightly different from standard Burr. Rather than+using the immutable state-based API, we in-place mutate pydantic models. Don't worry, it's still immutable, you're just modifying a copy and returning it.++In this case, we call to `@action.pydantic`, which tells which fields to read/write to from state. It derives the classes from the function annotations, although you can also pass it the+pydantic classes as arguments to the decorator if you prefer.++Note that the reads/writes have to be a subset of the state object. In this case we use the global `ApplicationState` object as described above, although it can use a subset/compatible set of fields (or, if you elect not to use centralized state, it just has to be compatible with upstream/downstream versions).++Under the hood, burr will subset the state class so it only has the relevant fields (the reads/write) fields.++```python[email protected](reads=["transcript"], writes=["post"])+def generate_post(state: ApplicationState, llm_client) -> ApplicationState:+ """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=[...]+ )+ # mutate in place+ state.post = response+ # return the state+ return state+```++## Typed state for streaming actions++This code for this is in [application.py](application.py).++For streaming actions, not only do we have to type the input/output state, but we can also type the intermediate result.++In this case, we just use the `SocialMediaPost` as we did in the application state. Instructor will be streaming that in as it gets created.++`@streaming_action.pydantic` currently requires you to pass in all the pydantic models as classes, although we will be adding the option to derive from the function signature.++We first call out to OpenAI, then we stream through++```python++@streaming_action.pydantic(+ reads=["transcript"],+ writes=["post"],+ state_input_type=ApplicationState,+ state_output_type=ApplicationState,+ stream_type=SocialMediaPost,+)+def generate_post_streaming(+ state: ApplicationState, llm_client+) -> Generator[Tuple[SocialMediaPost, Optional[ApplicationState]], None, None]:+ """Streams a post as it's getting created. This allows for interacting data on the UI side of partial+ results, using instructor's streaming capabilities for partial responses:+ https://python.useinstructor.com/concepts/partial/++ :param state: input state -- of the shape `ApplicationState`+ :param llm_client: the LLM client, we will bind this in the application+ :yield: a tuple of the post and the state -- state will be non-null when it's done+ """++ transcript = state.transcript+ response = llm_client.chat.completions.create_partial(+ model="gpt-4o-mini",+ response_model=SocialMediaPost,+ messages=[...],+ stream=True,+ )+ for post in response:+ yield post, None+ state.post = post+ yield post, state+```++When we call out to the application we built, we have to do a little magic to get typing to work+in the IDE, but we still have the same benefits as the non-streaming approach.++```python+app = build_streaming_application(...) # builder left out for now+_, streaming_container = app.stream_result(+ halt_after=["generate_post"],+ inputs={"youtube_url": "https://www.youtube.com/watch?v=hqutVJyd3TI"},+)+# annotate to make type-completion easier+streaming_container: StreamingResultContainer[ApplicationState, SocialMediaPost]+# post is of type SocialMediaPost+for post in streaming_container:+ obj = post.model_dump()+ console.clear()+ console.print(obj)+```++## FastAPI integration++This code for this is in [server.py](server.py).++To integrate this with FastAPI is easy, and gets easier with the types cascading through.++### Non-streaming++For the non-streaming case, we declare an endpoint that returns the entire state. Note you+may want a subset, but for now this is simple as it matches the pydantic models we defined above.++```python[email protected]("/social_media_post", response_model=SocialMediaPost)+def social_media_post(youtube_url: str = DEFAULT_YOUTUBE_URL) -> SocialMediaPost:+ _, _, state = burr_app.run(halt_after=["generate_post"], inputs={"youtube_url": youtube_url})+ return state.data.post+```++### Streaming++The streaming case involves using FastAPI's [StreamingResponse API](https://fastapi.tiangolo.com/advanced/custom-response/#streamingresponse). We define a generator, which simply yields all+intermediate results:++```python+[email protected]("/social_media_post_streaming", response_class=StreamingResponse)+def social_media_post_streaming(youtube_url: str = DEFAULT_YOUTUBE_URL) -> StreamingResponse:+ """Creates a completion for the chat message"""++ def gen():+ _, streaming_container = burr_app_streaming.stream_result(+ halt_after=["generate_post"],+ inputs={"youtube_url": youtube_url},+ ) # type: ignore+ for post in streaming_container:+ obj = post.model_dump()+ yield json.dumps(obj)++ return StreamingResponse(gen())+```++Note that `StreamingResponse` is not typed, but you have access to the types with the post+object, which corresponds to the stream from above!++Async streaming is similar.++You can run `server.py` with `python server.py`, which will open up on port 7443. You can use the `./curls.sh` command to query the server (it will use a default video, modify to pass your own):++```bash+./curls.sh # default, non-streaming+./curls.sh streaming # streaming endpoint+./sucls.sh streaming_async # streaming async endpoint+```++Note you'll have to have [jq](https://jqlang.github.io/jq/) installed for this to work.++## Caveats + next steps++Some things we'll be building out shortly:++1. The ability to derive application level schemas from individual actions+2. The ability to automatically generate a FastAPI application from state + Burr+3. Configurable validation for state -- guardrails to choose when/when not to validate in pydanticdiff --git a/examples/typed-state/application.py b/examples/typed-state/application.pynew file mode 100644index 00000000..d737de97--- /dev/null+++ b/examples/typed-state/application.py@@ -0,0 +1,292 @@+import textwrap+from typing import AsyncGenerator, Generator, Optional, Tuple, Union++import instructor+import openai+from pydantic import BaseModel, Field+from pydantic.json_schema import SkipJsonSchema+from rich.console import Console+from youtube_transcript_api import YouTubeTranscriptApi++from burr.core import Application, ApplicationBuilder, action+from burr.core.action import (+ AsyncStreamingResultContainer,+ StreamingResultContainer,+ streaming_action,+)+from burr.integrations.pydantic import PydanticTypingSystem+++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 -- please have at least 1",+ min_items=0,+ max_items=3,+ validate_default=False,+ )+ key_takeaways: list[str] = Field(+ description="A list of informative key takeways for the reader -- please have at least 1",+ min_items=0,+ max_items=4,+ validate_default=False,+ )+ 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+ )+++class ApplicationState(BaseModel):+ # Make these have defaults as they are only set in actions+ transcript: Optional[str] = Field(+ description="The full transcript of the YouTube video.", default=None+ )+ post: Optional[SocialMediaPost] = Field(+ description="The generated social media post.", default=None+ )++[email protected](reads=[], writes=["transcript"])+def get_youtube_transcript(state: ApplicationState, youtube_url: str) -> ApplicationState:+ """Get the official YouTube transcript for a video given its URL"""+ _, _, video_id = youtube_url.partition("?v=")++ transcript = YouTubeTranscriptApi.get_transcript(video_id, languages=["en"])+ state.transcript = " ".join([f"ts={entry['start']} - {entry['text']}" for entry in transcript])+ return state++ # store the transcript in state++[email protected](reads=["transcript"], writes=["post"])+def generate_post(state: ApplicationState, llm_client) -> ApplicationState:+ """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},+ ],+ )+ state.post = response++ # store the chapters in state+ return state+++@streaming_action.pydantic(+ reads=["transcript"],+ writes=["post"],+ state_input_type=ApplicationState,+ state_output_type=ApplicationState,+ stream_type=SocialMediaPost,+)+def generate_post_streaming(+ state: ApplicationState, llm_client+) -> Generator[Tuple[SocialMediaPost, Optional[ApplicationState]], None, None]:+ """Streams a post as it's getting created. This allows for interacting data on the UI side of partial+ results, using instructor's streaming capabilities for partial responses:+ https://python.useinstructor.com/concepts/partial/++ :param state: input state -- of the shape `ApplicationState`+ :param llm_client: the LLM client, we will bind this in the application+ :yield: a tuple of the post and the state -- state will be non-null when it's done+ """++ transcript = state.transcript+ response = llm_client.chat.completions.create_partial(+ 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},+ ],+ stream=True,+ )+ final_post: SocialMediaPost = None # type: ignore+ for post in response:+ final_post = post+ yield post, None++ yield final_post, state+++@streaming_action.pydantic(+ reads=["transcript"],+ writes=["post"],+ state_input_type=ApplicationState,+ state_output_type=ApplicationState,+ stream_type=SocialMediaPost,+)+async def generate_post_streaming_async(+ state: ApplicationState, llm_client+) -> AsyncGenerator[Tuple[SocialMediaPost, Optional[ApplicationState]], None]:+ """Async implementation of the streaming action above"""++ transcript = state.transcript+ response = llm_client.chat.completions.create_partial(+ 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},+ ],+ stream=True,+ )+ final_post = None+ async for post in response:+ final_post = post+ yield post, None++ yield final_post, state+++def build_application() -> Application[ApplicationState]:+ """Builds the standard application (non-streaming)"""+ llm_client = instructor.from_openai(openai.OpenAI())+ app = (+ ApplicationBuilder()+ .with_actions(+ get_youtube_transcript,+ generate_post.bind(llm_client=llm_client),+ )+ .with_transitions(+ ("get_youtube_transcript", "generate_post"),+ ("generate_post", "get_youtube_transcript"),+ )+ .with_entrypoint("get_youtube_transcript")+ .with_typing(PydanticTypingSystem(ApplicationState))+ .with_state(ApplicationState())+ .with_tracker(project="youtube-post")+ .build()+ )+ return app+++def build_streaming_application() -> Application[ApplicationState]:+ """Builds the streaming application -- this uses the generate_post_streaming action"""+ llm_client = instructor.from_openai(openai.OpenAI())+ app = (+ ApplicationBuilder()+ .with_actions(+ get_youtube_transcript,+ generate_post=generate_post_streaming.bind(llm_client=llm_client),+ )+ .with_transitions(+ ("get_youtube_transcript", "generate_post"),+ ("generate_post", "get_youtube_transcript"),+ )+ .with_entrypoint("get_youtube_transcript")+ .with_typing(PydanticTypingSystem(ApplicationState))+ .with_state(ApplicationState())+ .with_tracker(project="youtube-post")+ .build()+ )+ return app+++def build_streaming_application_async() -> Application[ApplicationState]:+ """Builds the async streaming application -- uses the generate_post_streaming_async action"""+ llm_client = instructor.from_openai(openai.AsyncOpenAI())+ app = (+ ApplicationBuilder()+ .with_actions(+ get_youtube_transcript,+ generate_post=generate_post_streaming_async.bind(llm_client=llm_client),+ )+ .with_transitions(+ ("get_youtube_transcript", "generate_post"),+ ("generate_post", "get_youtube_transcript"),+ )+ .with_entrypoint("get_youtube_transcript")+ .with_typing(PydanticTypingSystem(ApplicationState))+ .with_state(ApplicationState())+ .with_tracker(project="test-youtube-post")+ .build()+ )+ return app+++async def run_async():+ """quick function to run async -- this is not called in the mainline, see commented out code"""+ console = Console()+ app = build_streaming_application_async()++ _, streaming_container = await app.astream_result(+ halt_after=["generate_post"],+ inputs={"youtube_url": "https://www.youtube.com/watch?v=hqutVJyd3TI"},+ ) # type: ignore+ streaming_container: AsyncStreamingResultContainer[ApplicationState, SocialMediaPost]++ async for post in streaming_container:+ obj = post.model_dump()+ console.clear()+ console.print(obj)+++# mainline -- runs streaming and prints to console+if __name__ == "__main__":+ # asyncio.run(run_async())+ console = Console()+ app = build_streaming_application()+ _, streaming_container = app.stream_result(+ halt_after=["generate_post"],+ inputs={"youtube_url": "https://www.youtube.com/watch?v=hqutVJyd3TI"},+ ) # type: ignore+ streaming_container: StreamingResultContainer[ApplicationState, SocialMediaPost]+ for post in streaming_container:+ obj = post.model_dump()+ console.clear()+ console.print(obj)diff --git a/examples/youtube-to-social-media-post/curls.sh b/examples/typed-state/curls.shsimilarity index 100%rename from examples/youtube-to-social-media-post/curls.shrename to examples/typed-state/curls.shdiff --git a/examples/typed-state/notebook.ipynb b/examples/typed-state/notebook.ipynbnew file mode 100644index 00000000..cacaac34--- /dev/null+++ b/examples/typed-state/notebook.ipynb@@ -0,0 +1,836 @@+{+ "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": 5,+ "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": 6,+ "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": 7,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "<class '__main__.SocialMediaPost'>\n",+ "{'topic': 'Understanding B: A Powerful Tool for Agent Applications', 'hook': '🚀 Debug with ease using B!', 'body': 'Ever faced frustrating issues while building agent applications? Dive into our latest video where we unveil the capabilities of B, a framework designed to enhance observability and debugging. Learn how to fix bugs without restarting your entire agent and explore B’s unique graph-building capabilities for a seamless coding experience. Perfect for developers looking to streamline their coding processes!', 'concepts': [{'term': 'Agent Applications', 'definition': 'Applications that utilize AI agents to perform tasks or make decisions based on input and graphs of actions.', 'timestamp': 108.0}, {'term': 'Graph Building', 'definition': 'Creating a flowchart-like structure of actions and states for better process management in applications.', 'timestamp': 179.0}, {'term': 'Local Tracker', 'definition': 'A feature within B that allows interaction with the application state for tracking and debugging purposes.', 'timestamp': 260.0}], 'key_takeaways': ['B enables easy bug fixing without restarting your agent.', 'Graph-based modeling simplifies the coding process.', 'Integrate local tracking for comprehensive observability in applications.'], '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": 8,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "TOPIC: Understanding B: A Powerful Tool for Agent Applications\n",+ "\n",+ "🚀 Debug with ease using B!\n",+ "\n",+ "Ever faced frustrating issues while building agent applications? Dive into our latest video where we unveil the capabilities of B, a framework designed to enhance observability and debugging. Learn how to fix bugs without restarting your entire agent and explore B’s unique graph-building capabilities for a seamless coding experience. Perfect for developers looking to streamline their coding processes!\n",+ "\n",+ "B enables easy bug fixing without restarting your agent. Graph-based modeling simplifies the coding process. Integrate local tracking for comprehensive observability in applications.\n",+ "\n",+ "CONCEPTS\n",+ "1:48 - Agent Applications: Applications that utilize AI agents to perform tasks or make decisions based on input and graphs of actions.\n",+ "2:59 - Graph Building: Creating a flowchart-like structure of actions and states for better process management in applications.\n",+ "4:20 - Local Tracker: A feature within B that allows interaction with the application state for tracking and debugging purposes.\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": 9,+ "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": 10,+ "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->generate_post -->\n",+ "<g id=\"edge2\" class=\"edge\">\n",+ "<title>get_youtube_transcript->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->get_youtube_transcript -->\n",+ "<g id=\"edge1\" class=\"edge\">\n",+ "<title>input__youtube_url->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 0x7f94ead0d270>"+ ]+ },+ "execution_count": 10,+ "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": 11,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "TOPIC: Debugging with Burr and Graph States\n",+ "\n",+ "Ever struggled with debugging your AI agents?\n",+ "\n",+ "Dive into the world of Burr with our latest video! Learn how to leverage state tracking and condition-based flowcharts to handle failures and streamline debugging like never before. Discover how you can monitor your agents, and even resume operations from a specific point in their execution—without starting over! 🚀 Whether you’re a developer building complex applications or simply curious about AI functionality, this video will enhance your understanding of agent workflows. Don't miss out!\n",+ "\n",+ "Learn how to handle failures in AI agent applications effectively. Understand the relationship between actions and state in your applications. Discover how to resume operations from a specific state without restarting the entire application.\n",+ "\n",+ "link: https://www.youtube.com/watch?v=hqutVJyd3TI\n",+ "\n",+ "CONCEPTS\n",+ "10:57 - State Tracking: State tracking allows you to monitor the state of your application at different points in time, making debugging easier.\n",+ "1:50 - Flowchart: In this context, a flowchart represents the actions and their dependencies in your agent application as a directed graph.\n",+ "3:36 - Modality: The condition that determines which action to take next in the flow of your agent’s tasks.\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": 13,+ "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": 22,+ "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=\"381pt\" height=\"239pt\"\n",+ " viewBox=\"0.00 0.00 381.28 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 377.28,-235 377.28,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=\"M356.09,-166C356.09,-166 198.09,-166 198.09,-166 192.09,-166 186.09,-160 186.09,-154 186.09,-154 186.09,-142 186.09,-142 186.09,-136 192.09,-130 198.09,-130 198.09,-130 356.09,-130 356.09,-130 362.09,-130 368.09,-136 368.09,-142 368.09,-142 368.09,-154 368.09,-154 368.09,-160 362.09,-166 356.09,-166\"/>\n",+ "<text text-anchor=\"middle\" x=\"277.09\" 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=\"M324.09,-101C324.09,-101 230.09,-101 230.09,-101 224.09,-101 218.09,-95 218.09,-89 218.09,-89 218.09,-77 218.09,-77 218.09,-71 224.09,-65 230.09,-65 230.09,-65 324.09,-65 324.09,-65 330.09,-65 336.09,-71 336.09,-77 336.09,-77 336.09,-89 336.09,-89 336.09,-95 330.09,-101 324.09,-101\"/>\n",+ "<text text-anchor=\"middle\" x=\"277.09\" y=\"-79.3\" font-family=\"Times,serif\" font-size=\"14.00\">generate_post</text>\n",+ "</g>\n",+ "<!-- get_youtube_transcript->generate_post -->\n",+ "<g id=\"edge3\" class=\"edge\">\n",+ "<title>get_youtube_transcript->generate_post</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M277.09,-129.78C277.09,-124.09 277.09,-117.61 277.09,-111.34\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"280.59,-111.19 277.09,-101.19 273.59,-111.19 280.59,-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=\"277.09\" cy=\"-213\" rx=\"96.38\" ry=\"18\"/>\n",+ "<text text-anchor=\"middle\" x=\"277.09\" y=\"-209.3\" font-family=\"Times,serif\" font-size=\"14.00\">input: youtube_url</text>\n",+ "</g>\n",+ "<!-- input__youtube_url->get_youtube_transcript -->\n",+ "<g id=\"edge1\" class=\"edge\">\n",+ "<title>input__youtube_url->get_youtube_transcript</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M277.09,-194.78C277.09,-189.09 277.09,-182.61 277.09,-176.34\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"280.59,-176.19 277.09,-166.19 273.59,-176.19 280.59,-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=\"M229.59,-36C229.59,-36 146.59,-36 146.59,-36 140.59,-36 134.59,-30 134.59,-24 134.59,-24 134.59,-12 134.59,-12 134.59,-6 140.59,0 146.59,0 146.59,0 229.59,0 229.59,0 235.59,0 241.59,-6 241.59,-12 241.59,-12 241.59,-24 241.59,-24 241.59,-30 235.59,-36 229.59,-36\"/>\n",+ "<text text-anchor=\"middle\" x=\"188.09\" y=\"-14.3\" font-family=\"Times,serif\" font-size=\"14.00\">rewrite_post</text>\n",+ "</g>\n",+ "<!-- generate_post->rewrite_post -->\n",+ "<g id=\"edge4\" class=\"edge\">\n",+ "<title>generate_post->rewrite_post</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M252.77,-64.78C242.86,-57.77 231.26,-49.56 220.64,-42.04\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"222.57,-39.12 212.38,-36.19 218.52,-44.83 222.57,-39.12\"/>\n",+ "</g>\n",+ "<!-- rewrite_post->rewrite_post -->\n",+ "<g id=\"edge5\" class=\"edge\">\n",+ "<title>rewrite_post->rewrite_post</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M241.72,-29.47C252.17,-28.13 259.59,-24.31 259.59,-18 259.59,-13.96 256.55,-10.93 251.61,-8.93\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"252.27,-5.49 241.72,-6.53 250.62,-12.29 252.27,-5.49\"/>\n",+ "</g>\n",+ "<!-- input__user_prompt -->\n",+ "<g id=\"node5\" class=\"node\">\n",+ "<title>input__user_prompt</title>\n",+ "<ellipse fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" cx=\"100.09\" cy=\"-83\" rx=\"100.18\" ry=\"18\"/>\n",+ "<text text-anchor=\"middle\" x=\"100.09\" y=\"-79.3\" font-family=\"Times,serif\" font-size=\"14.00\">input: user_prompt</text>\n",+ "</g>\n",+ "<!-- input__user_prompt->rewrite_post -->\n",+ "<g id=\"edge2\" class=\"edge\">\n",+ "<title>input__user_prompt->rewrite_post</title>\n",+ "<path fill=\"none\" stroke=\"black\" d=\"M123.21,-65.45C133.18,-58.31 145,-49.85 155.81,-42.11\"/>\n",+ "<polygon fill=\"black\" stroke=\"black\" points=\"158.11,-44.77 164.2,-36.1 154.04,-39.08 158.11,-44.77\"/>\n",+ "</g>\n",+ "</g>\n",+ "</svg>\n"+ ],+ "text/plain": [+ "<graphviz.graphs.Digraph at 0x7f94c0175180>"+ ]+ },+ "execution_count": 22,+ "metadata": {},+ "output_type": "execute_result"+ }+ ],+ "source": [+ "from burr.core import ApplicationBuilder\n",+ "from burr.core.persistence import SQLLitePersister\n",+ "\n",+ "persister = SQLLitePersister(db_path=\".burr.db\", table_name=\"burr_state\")\n",+ "persister.initialize() # this will create the db and table\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(persister)\n",+ " .with_entrypoint(\"get_youtube_transcript\")\n",+ " .with_tracker(project=\"youtube-post\")\n",+ " .build()\n",+ ")\n",+ "application.visualize()"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 23,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "LAST ACTION : generate_post: transcript -> post \n",+ "\n",+ "TOPIC: Enhancing AI Agent Applications with B and Hamilton\n",+ "\n",+ "🚀 Dive into the world of AI agents and discover how to streamline your debugging process with B!\n",+ "\n",+ "Are you tired of constant debugging cycles in your AI projects? In our latest video, we explore B, a framework designed to help you monitor and debug agent applications efficiently. Learn how B allows you to visualize your application’s state, manage complex action flows, and even fork your state at any point to tackle bugs without restarting from scratch. Plus, discover its sister framework, Hamilton, perfect for managing data pipelines! Curious to learn how to simplify your debugging and enhance your application development? 🎥 Watch the full video now!\n",+ "\n",+ "Learn to visualize and debug agent applications effectively with B. Understand how to manage states and actions using a graphical approach. Explore the integration of Hamilton for complex data pipeline processes.\n",+ "\n",+ "link: https://www.youtube.com/watch?v=hqutVJyd3TI\n",+ "\n",+ "CONCEPTS\n",+ "0:1 - B Framework: A framework for building and debugging AI agent applications, allowing for state tracking and action visualization.\n",+ "2:25 - State Object: An object that retains the state of an application, enabling actions to read and write within that context.\n",+ "2:0 - Graph Visualization: A depiction of actions and states in a flowchart-like manner to streamline application behavior and debugging.\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: Enhancing AI Agent Applications with B and Hamilton\n",+ "\n",+ "🚀 Dive into the world of AI agents and discover how to streamline your debugging process with B!\n",+ "\n",+ "Are you encountering challenges with debugging cycles in your AI projects? In our latest video, we explore B, a framework designed for monitoring and debugging agent applications effectively. With B, you can visualize your application’s state, manage complex action flows, and fork your state to tackle bugs without having to restart from scratch. Additionally, we introduce Hamilton, a framework that complements B by simplifying the management of data pipelines. If you are interested in improving your debugging process and application development, we invite you to watch the full video!\n",+ "\n",+ "Learn to visualize and debug agent applications effectively with B. Understand how to manage states and actions using a graphical approach. Explore the integration of Hamilton for complex data pipeline processes.\n",+ "\n",+ "link: https://www.youtube.com/watch?v=hqutVJyd3TI\n",+ "\n",+ "CONCEPTS\n",+ "0:1 - B Framework: A framework for building and debugging AI agent applications, allowing for state tracking and action visualization.\n",+ "2:25 - State Object: An object that retains the state of an application, enabling actions to read and write within that context.\n",+ "2:0 - Graph Visualization: A depiction of actions and states in a flowchart-like manner to streamline application behavior and debugging.\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": [+ "Then, you can retrieve the store app ids and resume from there. This requires adding a `.initialize_from()` with the `persister`. Also, we're getting the `app_id` from storage via `persister.list_app_ids()`. By passing it to the `.with_identifiers(app_id=...)`, this \"reloaded application\" will logged and tracked in succession of the original app (as you can see in the Burr UI).\n",+ "\n",+ "Below, we're building a new `Application` from the persisted state. When we print the `State`, we're able to retrieve the previously generated (you can see the matching titles)!"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 36,+ "metadata": {},+ "outputs": [+ {+ "name": "stdout",+ "output_type": "stream",+ "text": [+ "Enhancing AI Agent Applications with B and Hamilton\n"+ ]+ }+ ],+ "source": [+ "app_id = persister.list_app_ids(\"\")[0]\n",+ "\n",+ "reloaded_app = (\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",+ " .initialize_from(\n",+ " persister,\n",+ " resume_at_next_action=True,\n",+ " default_state={},\n",+ " default_entrypoint=\"get_youtube_transcript\",\n",+ " )\n",+ " .with_state_persister(persister)\n",+ " .with_identifiers(app_id=app_id)\n",+ " .with_tracker(project=\"youtube-post\")\n",+ " .build()\n",+ ")\n",+ "\n",+ "print(reloaded_app.state[\"post\"].topic)"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "Persistence is great for iterative development such as tuning your [Instructor model with validators and constraints](https://python.useinstructor.com/concepts/reask_validation/), but it's also a powerful tool for building [test cases and guard rails](https://burr.dagworks.io/examples/guardrails/creating_tests/). The CLI command `burr-test-case` can generate a `pytest.fixture` to resume your app from a given state."+ ]+ },+ {+ "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/typed-state/server.py b/examples/typed-state/server.pynew file mode 100644index 00000000..b5592b55--- /dev/null+++ b/examples/typed-state/server.py@@ -0,0 +1,109 @@+import contextlib+import json+import logging++import fastapi+import uvicorn+from application import (+ ApplicationState,+ SocialMediaPost,+ build_application,+ build_streaming_application,+ build_streaming_application_async,+)+from fastapi.responses import StreamingResponse++from burr.core import Application+from burr.core.action import AsyncStreamingResultContainer, StreamingResultContainer++logger = logging.getLogger(__name__)++# define a global `burr_app` variable+burr_app: Application[ApplicationState] = None+# This does streaming, in sync mode+burr_app_streaming: Application[ApplicationState] = None+# And this does streaming, in async mode+burr_app_streaming_async: Application[ApplicationState] = None++DEFAULT_YOUTUBE_URL = "https://www.youtube.com/watch?v=hqutVJyd3TI"+++async def lifespan(app: fastapi.FastAPI):+ """Instantiate the Burr applications on FastAPI startup."""+ global burr_app, burr_app_streaming, burr_app_streaming_async+ burr_app = build_application()+ burr_app_streaming = build_streaming_application()+ burr_app_streaming_async = build_streaming_application_async()+ yield+++app = fastapi.FastAPI(lifespan=lifespan)++[email protected]("/social_media_post", response_model=SocialMediaPost)+def social_media_post(youtube_url: str = DEFAULT_YOUTUBE_URL) -> SocialMediaPost:+ """Basic, synchronous single-step API.+ This just returns the social media post, no streaming response.+++ :param youtube_url: youtube URL for the transcript, defaults to DEFAULT_YOUTUBE_URL+ :return: the social media post+ """+ # Note that state is of type State[ApplicationState]+ # This means that it has a data field of type ApplicationState+ # which means that our IDE will happily auto-complete for us+ # and that we can get the pydantic model+ _, _, state = burr_app.run(halt_after=["generate_post"], inputs={"youtube_url": youtube_url})+ return state.data.post++[email protected]("/social_media_post_streaming", response_class=StreamingResponse)+def social_media_post_streaming(youtube_url: str = DEFAULT_YOUTUBE_URL) -> StreamingResponse:+ """Creates a completion for the chat message"""++ def gen():+ _, streaming_container = burr_app_streaming.stream_result(+ halt_after=["generate_post"],+ inputs={"youtube_url": youtube_url},+ ) # type: ignore+ # We annotate this so we can get the right types cascaded through+ streaming_container: StreamingResultContainer[ApplicationState, SocialMediaPost]+ # Every post is of type SocialMediaPost, and the IDE (if you're using PyLance or an equivalent) should know+ for post in streaming_container:+ obj = post.model_dump()+ yield json.dumps(obj)+ # if we called streaming_container.get(), we would get two objects --+ # This state will have a field data of type ApplicationState, which we can use if we want++ # post, state = streaming_container.get()+ # state.data.transcript # valid + auto-completion in the IDE++ # return a final streaming result -- it'll just have strings+ # for certain SSE frameworks you may want to delimit with data:+ return StreamingResponse(gen())++[email protected]("/social_media_post_streaming_async", response_class=StreamingResponse)+async def social_media_post_streaming_async(+ youtube_url: str = DEFAULT_YOUTUBE_URL,+) -> StreamingResponse:+ """Creates a completion for the chat message"""++ async def gen():+ _, streaming_container = await burr_app_streaming_async.astream_result(+ halt_after=["generate_post"],+ inputs={"youtube_url": youtube_url},+ ) # type: ignore+ # We annotate this so we can get the right types cascaded through+ streaming_container: AsyncStreamingResultContainer[ApplicationState, SocialMediaPost]+ # Every post is of type SocialMediaPost, and the IDE (if you're using PyLance or an equivalent) should know+ async for post in streaming_container:+ obj = post.model_dump()+ yield json.dumps(obj)++ return StreamingResponse(gen())+++if __name__ == "__main__":+ uvicorn.run("server:app", host="127.0.0.1", port=7443, reload=True)diff --git a/examples/typed-state/statemachine.png b/examples/typed-state/statemachine.pngnew file mode 100644index 00000000..ec7a8b24Binary files /dev/null and b/examples/typed-state/statemachine.png differdiff --git a/examples/youtube-to-social-media-post/application.py b/examples/youtube-to-social-media-post/application.pyindex e0b6983e..683cec3e 100644--- a/examples/youtube-to-social-media-post/application.py+++ b/examples/youtube-to-social-media-post/application.py@@ -1,20 +1,14 @@import textwrap-from typing import Any, AsyncGenerator, Generator, Optional, Tuple, Union+from typing import Unionimport instructorimport openaifrom pydantic import BaseModel, Fieldfrom pydantic.json_schema import SkipJsonSchema-from rich.console import Consolefrom youtube_transcript_api import YouTubeTranscriptApi-from burr.core import Application, ApplicationBuilder, action-from burr.core.action import (- AsyncStreamingResultContainer,- StreamingResultContainer,- streaming_action,-)-from burr.integrations.pydantic import PydanticTypingSystem+from burr.core import Application, ApplicationBuilder, State, action+from burr.core.persistence import SQLLitePersisterclass Concept(BaseModel):@@ -38,16 +32,14 @@ class SocialMediaPost(BaseModel):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 -- please have at least 1",- min_items=0,+ description="Important concepts about Hamilton or Burr mentioned in this post.",+ min_items=1,max_items=3,- validate_default=False,)key_takeaways: list[str] = Field(- description="A list of informative key takeways for the reader -- please have at least 1",- min_items=0,+ description="A list of informative key takeways for the reader.",+ min_items=1,max_items=4,- validate_default=False,)youtube_url: SkipJsonSchema[Union[str, None]] = None@@ -74,72 +66,24 @@ class SocialMediaPost(BaseModel):)-class ApplicationState(BaseModel):- # Make these have defaults as they are only set in actions- transcript: Optional[str] = Field(- description="The full transcript of the YouTube video.", default=None- )- post: Optional[SocialMediaPost] = Field(- description="The generated social media post.", default=None- )---class ApplicationStateStream(ApplicationState):- # Make these have defaults as they are only set in actions- post_generator: Optional[Generator[SocialMediaPost, None, None]] = None-- class Config:- arbitrary_types_allowed = True-- def __copy__(self, memo: dict[int, Any] | None = None):- post_generator = self.post_generator- self.post_generator = None- out = self.model_copy(deep=True, update={"post_generator": post_generator})- self.post_generator = post_generator- return out- # # TODO -- ensure that post_generator is copied by reference, not value...- # # Ignore this for now -- this is specifically dealing with a copy() issue- # # then delegate to the superclass- # if memo is None:- # memo = {}- # if id(self) in memo:- # return memo[id(self)]-- # # Create a shallow copy to modify- # new_obj = copy.copy(self)-- # # Copy each attribute except the generator which should be shared- # for k, v in self.__dict__.items():- # if k != "post_generator":- # setattr(new_obj, k, copy.deepcopy(v, memo))-- # # Reference the same generator instance- # new_obj.post_generator = self.post_generator-- # # Store in memoization dictionary- # memo[id(self)] = new_obj-- # return new_obj--[email protected](reads=[], writes=["transcript"])-def get_youtube_transcript(state: ApplicationState, youtube_url: str) -> ApplicationState:+@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"])- state.transcript = " ".join([f"ts={entry['start']} - {entry['text']}" for entry in transcript])- return state+ full_transcript = " ".join([f"ts={entry['start']} - {entry['text']}" for entry in transcript])# store the transcript in state+ return state.update(transcript=full_transcript)[email protected](reads=["transcript"], writes=["post"])-def generate_post(state: ApplicationState, llm_client) -> ApplicationState:+@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+ transcript = state["transcript"]response = llm_client.chat.completions.create(model="gpt-4o-mini",@@ -152,169 +96,59 @@ def generate_post(state: ApplicationState, llm_client) -> ApplicationState:{"role": "user", "content": transcript},],)- state.post = response# store the chapters in state- return state---@streaming_action.pydantic(- reads=["transcript"],- writes=["post"],- state_input_type=ApplicationState,- state_output_type=ApplicationState,- stream_type=SocialMediaPost,-)-def generate_post_streaming(- state: ApplicationStateStream, llm_client-) -> Generator[Tuple[SocialMediaPost, Optional[ApplicationState]], None, None]:- """Use the Instructor LLM client to generate `SocialMediaPost` from the YouTube transcript."""+ return state.update(post=response)- transcript = state.transcript- response = llm_client.chat.completions.create_partial(- 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},- ],- stream=True,- )- final_post = None- for post in response:- final_post = post- yield post, None-- yield final_post, state---@streaming_action.pydantic(- reads=["transcript"],- writes=["post"],- state_input_type=ApplicationState,- state_output_type=ApplicationState,- stream_type=SocialMediaPost,-)-async def generate_post_streaming_async(- state: ApplicationStateStream, llm_client-) -> AsyncGenerator[Tuple[SocialMediaPost, Optional[ApplicationState]], None]:- """Use the Instructor LLM client to generate `SocialMediaPost` from the YouTube transcript."""- transcript = state.transcript- response = llm_client.chat.completions.create_partial(+@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": "Analyze the given YouTube transcript and generate a compelling social media post.",+ "content": f"Take the previously generated social media post and modify it according to the following instructions: {user_prompt}",},- {"role": "user", "content": transcript},+ {"role": "user", "content": post.model_dump_json()},],- stream=True,)- final_post = None- async for post in response:- final_post = post- yield post, None-- yield final_post, state+ # pass the youtube_url from the previous post version+ response.youtube_url = post.youtube_url-def build_application() -> Application[ApplicationState]:- llm_client = instructor.from_openai(openai.OpenAI())- app = (- ApplicationBuilder()- .with_actions(- get_youtube_transcript,- generate_post.bind(llm_client=llm_client),- )- .with_transitions(- ("get_youtube_transcript", "generate_post"),- ("generate_post", "get_youtube_transcript"),- )- # .with_state_persister(SQLLitePersister(db_path=".burr.db", table_name="state"))- .with_entrypoint("get_youtube_transcript")- .with_typing(PydanticTypingSystem(ApplicationState))- .with_state(ApplicationState())- .with_tracker(project="youtube-post")- .build()- )- return app+ return state.update(post=response)-def build_streaming_application() -> Application[ApplicationState]:+def build_application() -> Application:llm_client = instructor.from_openai(openai.OpenAI())- app = (+ return (ApplicationBuilder().with_actions(get_youtube_transcript,- generate_post=generate_post_streaming.bind(llm_client=llm_client),+ generate_post.bind(llm_client=llm_client),+ rewrite_post.bind(llm_client=llm_client),).with_transitions(("get_youtube_transcript", "generate_post"),- ("generate_post", "get_youtube_transcript"),+ ("generate_post", "rewrite_post"),+ ("rewrite_post", "rewrite_post"),)- # .with_state_persister(SQLLitePersister(db_path=".burr.db", table_name="state"))+ .with_state_persister(SQLLitePersister(db_path=".burr.db", table_name="state")).with_entrypoint("get_youtube_transcript")- .with_typing(PydanticTypingSystem(ApplicationState))- .with_state(ApplicationState()).with_tracker(project="youtube-post").build())- return app---def build_streaming_application_async() -> Application[ApplicationState]:- llm_client = instructor.from_openai(openai.AsyncOpenAI())- app = (- ApplicationBuilder()- .with_actions(- get_youtube_transcript,- generate_post=generate_post_streaming_async.bind(llm_client=llm_client),- )- .with_transitions(- ("get_youtube_transcript", "generate_post"),- ("generate_post", "get_youtube_transcript"),- )- # .with_state_persister(SQLLitePersister(db_path=".burr.db", table_name="state"))- .with_entrypoint("get_youtube_transcript")- .with_typing(PydanticTypingSystem(ApplicationState))- .with_state(ApplicationState())- .with_tracker(project="test-youtube-post")- .build()- )- return app---async def run_async():- console = Console()- app = build_streaming_application_async()-- a, streaming_container = await app.astream_result(- halt_after=["generate_post"],- inputs={"youtube_url": "https://www.youtube.com/watch?v=hqutVJyd3TI"},- ) # type: ignore- streaming_container: AsyncStreamingResultContainer[ApplicationState, SocialMediaPost]-- async for post in streaming_container:- obj = post.model_dump()- console.clear()- console.print(obj)if __name__ == "__main__":- console = Console()- app = build_streaming_application()- a, streaming_container = app.stream_result(+ 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"},- ) # type: ignore- streaming_container: StreamingResultContainer[ApplicationState, SocialMediaPost]- for post in streaming_container:- obj = post.model_dump()- console.clear()- console.print(obj)+ )diff --git a/examples/youtube-to-social-media-post/server.py b/examples/youtube-to-social-media-post/server.pyindex 906bb155..75b8a4d4 100644--- a/examples/youtube-to-social-media-post/server.py+++ b/examples/youtube-to-social-media-post/server.py@@ -1,90 +1,45 @@import contextlib-import jsonimport logging+from typing import Optional+import applicationimport fastapiimport uvicorn-from application import (- ApplicationState,- SocialMediaPost,- build_application,- build_streaming_application,- build_streaming_application_async,-)-from fastapi.responses import StreamingResponsefrom burr.core import Application-from burr.core.action import AsyncStreamingResultContainer, StreamingResultContainerlogger = logging.getLogger(__name__)# define a global `burr_app` variable-burr_app: Application[ApplicationState] = None-# This does streaming, in sync mode-burr_app_streaming: Application[ApplicationState] = None+burr_app: Optional[Application] = None-# And this does streaming, in async mode-burr_app_streaming_async: Application[ApplicationState] = None-DEFAULT_YOUTUBE_URL = "https://www.youtube.com/watch?v=hqutVJyd3TI"+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@contextlib.asynccontextmanagerasync 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_streaming, burr_app_streaming_async- burr_app = build_application()- burr_app_streaming = build_streaming_application()- burr_app_streaming_async = build_streaming_application_async()+ global burr_app+ burr_app = application.build_application()yieldapp = fastapi.FastAPI(lifespan=lifespan)[email protected]("/social_media_post", response_model=SocialMediaPost)-def social_media_post(youtube_url: str = DEFAULT_YOUTUBE_URL) -> SocialMediaPost:[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})- return state.data.post--[email protected]("/social_media_post_streaming_async", response_class=StreamingResponse)-async def social_media_post_streaming_async(- youtube_url: str = DEFAULT_YOUTUBE_URL,-) -> StreamingResponse:- """Creates a completion for the chat message"""-- async def gen():- _, streaming_container = await burr_app_streaming_async.astream_result(- halt_after=["generate_post"],- inputs={"youtube_url": youtube_url},- ) # type: ignore- streaming_container: AsyncStreamingResultContainer[ApplicationState, SocialMediaPost]- async for post in streaming_container:- obj = post.model_dump()- yield json.dumps(obj)-- return StreamingResponse(gen())--[email protected]("/social_media_post_streaming", response_class=StreamingResponse)-def social_media_post_streaming(youtube_url: str = DEFAULT_YOUTUBE_URL) -> StreamingResponse:- """Creates a completion for the chat message"""-- def gen():- _, streaming_container = burr_app_streaming.stream_result(- halt_after=["generate_post"],- inputs={"youtube_url": youtube_url},- ) # type: ignore- streaming_container: StreamingResultContainer[ApplicationState, SocialMediaPost]- for post in streaming_container:- obj = post.model_dump()- yield json.dumps(obj)-- return StreamingResponse(gen())+ post = state["post"]+ return {"formatted_post": post.display(), "post": post.model_dump()}if __name__ == "__main__":diff --git a/examples/youtube-to-social-media-post/statemachine.png b/examples/youtube-to-social-media-post/statemachine.pngindex e9ae4314..bdf72f90 100644Binary files a/examples/youtube-to-social-media-post/statemachine.png and b/examples/youtube-to-social-media-post/statemachine.png differdiff --git a/pyproject.toml b/pyproject.tomlindex 6834037c..2305a50b 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"[project]name = "burr"-version = "0.30.0rc5"+version = "0.30.0rc6"dependencies = [] # yes, there are nonerequires-python = ">=3.9"authors = [