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
Fixes up state typing docs
elijahbenizzy9587699a46f4
diff --git a/docs/concepts/state-typing.rst b/docs/concepts/state-typing.rstnew file mode 100644index 00000000..82235a38--- /dev/null+++ b/docs/concepts/state-typing.rst@@ -0,0 +1,120 @@+.. _statetyping:++============+Typing State+============++.. note::++ Burr allows you to specify types for your state. This enables more self-documenting, easy-to-write actions,+ allows you to type your entire application object for downstream consumption, and provides a way to inspect+ the state of your application prior to execution (for use by a web-server/other typing system). This is done+ through the use of pydantic schemas.++For a quick-start guide, see the `example <https://github.com/DAGWorks-Inc/burr/tree/main/examples/typed-state>`_+++Burr has two approaches to specifying a schema for a state. These can work together as long as they specify clashing state:++1. Application-level typing+2. Action-level typing++These enable a host of other extensions/capabilities.++While these are built for pydantic, the typing system is intended to be pluggable, and we plan to add further integrations+(dataclasses, typed dicts, etc...).+++Application-level Typing+------------------------++To type at the application level, you can use the :py:meth:`ApplicationBuilder.with_typing burr.core.application.ApplicationBuilder.with_typing` method.+This takes in a :py:class:`TypingSystem burr.core.typing.TypingSystem` object, which specifies how to gather types from/assign types to the state.++This looks as follows:++First, define a pydantic model for your application:++.. code-block:: python++ from pydantic import BaseModel+ class ApplicationState(pydantic.BaseModel):+ chat_history: List[dict[str, str]] = pydantic.Field(default_factory=list)+ prompt: Optional[str] = None+ mode: Optional[Literal["text", "image"]] = None+ response: Optional[dict[str, str]] = None++Then, we can use this model to type our application:++.. code-block:: python++ from burr import ApplicationBuilder+ from burr.core.typing import PydanticTypingSystem++ app = (+ ApplicationBuilder()+ .with_actions(...)+ .with_entrypoint(...)+ .with_transitions(...)+ .with_typing(PydanticTypingSystem(ApplicationState))+ .with_state(ApplicationState())+ .build()+ )++Your application is now typed with that pydantic model. If you're using an appropriate typing+integration in your IDE (E.G. pylance), it will know that the state of your application is of type+``MyApplicationState``.++When you have this you'll be able to run:++.. code-block:: python++ action_ran, result, state = app.run(inputs=...)+ state.data # of type ApplicationState -- do what you want with this!+++Action-level typing+-------------------++You can also define type computations on on the action-level:++.. code-block:: python++ @pydantic_action(reads=["prompt", "chat_history"], 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++Note three interesting choices here:++1. The state is typed as a pydantic model+2. The return type is the same pydantic model+3. We mutate the state in place, rather than returning a new state++This is a different action API -- it effectively subsets the state on input,+gives you that object, then subsets the state on output, and merges it back.++Thus if you try to refer to a state variable that you didn't specify in the reads/writes,+it will give an error.++Mutating in place is OK as this produces a new object for each execution run. For now, you will+want to be careful about lists/list pointers -- we are working on that.+++Application + Action-level typing+---------------------------------++Application-level typing has the benefit of giving you application-level IDE autocompletion and allowing you to specify+the schema. Action level typing makes it easier to write actions, and allows for more flexible/modular actions without specifying+the whole state in advance.++You can use them both as long as the types match up. If not, this will error out.++.. note::++ We have not yet implemented validation on more than just the action level -- this is coming soon!diff --git a/docs/reference/integrations/index.rst b/docs/reference/integrations/index.rstindex ec1f941a..0d15cda1 100644--- a/docs/reference/integrations/index.rst+++ b/docs/reference/integrations/index.rst@@ -1,6 +1,6 @@-================+============Integrations-================+============Integrations -- we will be adding more@@ -12,3 +12,4 @@ Integrations -- we will be adding moreopentelemetrytracelooplangchain+ pydanticdiff --git a/docs/reference/integrations/langchain.rst b/docs/reference/integrations/langchain.rstindex 90c6a33b..4b6436d0 100644--- a/docs/reference/integrations/langchain.rst+++ b/docs/reference/integrations/langchain.rst@@ -1,6 +1,6 @@------------------Burr + Langchain-----------------+---------+Langchain+---------Burr works out of the box with langchain, as Burr delegates to any python code.diff --git a/docs/reference/serde.rst b/docs/reference/serde.rstindex a12e0453..c331c975 100644--- a/docs/reference/serde.rst+++ b/docs/reference/serde.rst@@ -1,3 +1,5 @@+.. _serderef:+==================================Serialization & Deserialization==================================@@ -21,8 +23,6 @@ This is used to identify the deserialization function to use.Out of the box Implementations==============================-.. _serderef:-The following implementations are available assuming you have the right dependencies in your environment:LangChain Objectsdiff --git a/docs/reference/typing.rst b/docs/reference/typing.rstnew file mode 100644index 00000000..c8e9017f--- /dev/null+++ b/docs/reference/typing.rst@@ -0,0 +1,19 @@+.. _statetypingref:++======+Typing+======++Reference on the State typing API. Note that docs here are for both core burr and the pydantic plugin+(which does the interesting typing). For an overview, read :ref:`statetyping`.+++.. autoclass:: burr.core.typing.TypingSystem+ :members:++ .. automethod:: __init__++.. autoclass:: burr.integrations.pydantic.PydanticTypingSystem+ :members:++ .. automethod:: __init__