Skip to content

armgit / burr

Public Imported from GitHub
0

Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.

Fixes up state typing docs

elijahbenizzy9587699a46f4
diff --git a/docs/concepts/state-typing.rst b/docs/concepts/state-typing.rst
new file mode 100644
index 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.rst
index 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 more
opentelemetry
traceloop
langchain
+ pydantic
diff --git a/docs/reference/integrations/langchain.rst b/docs/reference/integrations/langchain.rst
index 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.rst
index 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 Objects
diff --git a/docs/reference/typing.rst b/docs/reference/typing.rst
new file mode 100644
index 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__