From d57713648a4fafe88b04f4cca7f3409a5952f457 Mon Sep 17 00:00:00 2001 From: vaquarkhan Date: Fri, 8 May 2026 02:25:46 -0500 Subject: [PATCH] docs: fix docs typos and example issues for issue 725 Correct broken snippets and grammar, fix RST formatting issues, and remove decorative emoji from documentation headers for consistency with project standards. --- README.md | 30 ++++++++++++------------- docs/concepts/actions.rst | 4 ++-- docs/concepts/state-persistence.rst | 2 +- docs/concepts/tracking.rst | 2 +- docs/examples/deployment/index.rst | 6 ++--- docs/getting_started/install.rst | 3 ++- docs/getting_started/simple-example.rst | 4 ++-- docs/getting_started/up-next.rst | 2 +- examples/simple-chatbot-intro/README.md | 2 +- 9 files changed, 28 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ac155fc98..3fb414f7c 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ pluggable persisters (e.g. for memory) to save & load application state. Link to [documentation](https://burr.apache.org/). Quick (<3min) video intro [here](https://www.loom.com/share/a10f163428b942fea55db1a84b1140d8?sid=1512863b-f533-4a42-a2f3-95b13deb07c9). Longer [video intro & walkthrough](https://www.youtube.com/watch?v=rEZ4oDN0GdU). Blog post [here](https://blog.dagworks.io/p/burr-develop-stateful-ai-applications). Join discord for help/questions [here](https://discord.gg/6Zy2DwP4f3). -## πŸƒQuick start +## Quick start Install from `pypi`: @@ -57,7 +57,7 @@ burr ``` This will open up Burr's telemetry UI. It comes loaded with some default data so you can click around. -It also has a demo chat application to help demonstrate what the UI captures enabling you too see things changing in +It also has a demo chat application to help demonstrate what the UI captures, enabling you to see things changing in real-time. Hit the "Demos" side bar on the left and select `chatbot`. To chat it requires the `OPENAI_API_KEY` environment variable to be set, but you can still see how it works if you don't have an API key set. @@ -73,7 +73,7 @@ See if you can find it. For more details see the [getting started guide](https://burr.apache.org/getting_started/simple-example/). -## πŸ”© How does Apache Burr work? +## How does Apache Burr work? With Apache Burr you express your application as a state machine (i.e. a graph/flowchart). You can (and should!) use it for anything in which you have to manage state, track complex decisions, add human feedback, or dictate an idempotent, self-persisting workflow. @@ -94,7 +94,7 @@ def ai_response(state: State) -> State: # query the LLM however you want (or don't use an LLM, up to you...) response = _query_llm(state["chat_history"]) # Burr doesn't care how you use LLMs! chat_item = {"role" : "system", "content" : response} - return state.update(response=content).append(chat_history=chat_item) + return state.update(response=response).append(chat_history=chat_item) app = ( ApplicationBuilder() @@ -113,12 +113,12 @@ print("answer:", app.state["response"]) Apache Burr includes: 1. A (dependency-free) low-abstraction python library that enables you to build and manage state machines with simple python functions -2. A UI you can use view execution telemetry for introspection and debugging +2. A UI you can use to view execution telemetry for introspection and debugging 3. A set of integrations to make it easier to persist state, connect to telemetry, and integrate with other systems ![Burr at work](https://github.com/apache/burr/blob/main/chatbot.gif) -## πŸ’»οΈ What can you do with Apache Burr? +## What can you do with Apache Burr? Apache Burr can be used to power a variety of applications, including: @@ -139,12 +139,12 @@ Apache Burr will _not_ tell you how to build your models, how to query APIs, or in a way that scales with your needs and makes following the logic of your system easy. Burr comes out of the box with a host of integrations including tooling to build a UI in streamlit and watch your state machine execute. -## πŸ— Start building +## Start building See the documentation for [getting started](https://burr.apache.org/getting_started/simple-example), and follow the example. Then read through some of the concepts and write your own application! -## πŸ“ƒ Comparison against common frameworks +## Comparison against common frameworks While Apache Burr is attempting something (somewhat) unique, there are a variety of tools that occupy similar spaces: @@ -157,7 +157,7 @@ While Apache Burr is attempting something (somewhat) unique, there are a variety | Open-source user-interface for monitoring/tracing | βœ… | ❌ | ❌ | ❌ | ❌ | βœ… | | Works with non-LLM use-cases | βœ… | ❌ | ❌ | ❌ | ❌ | βœ… | -## 🌯 Why the name Burr? +## Why the name Burr? Apache Burr is named after [Aaron Burr](https://en.wikipedia.org/wiki/Aaron_Burr), founding father, third VP of the United States, and murderer/arch-nemesis of [Alexander Hamilton](https://en.wikipedia.org/wiki/Alexander_Hamilton). What's the connection with (Apache) Hamilton? We imagine a world in which Burr and Hamilton lived in harmony and saw through their differences to better the union. Originally Apache Burr was built as a _harness_ to handle state between executions of Apache Hamilton DAGs (because DAGs don't have cycles), @@ -207,7 +207,7 @@ but realized that it has a wide array of applications and decided to release it **Aditya K.** *DS Architect, TaskHuman* -## πŸ›£ Roadmap +## Roadmap While Apache Burr is stable and well-tested, we have quite a few tools/features on our roadmap! 1. FastAPI integration + hosted deployment -- make it really easy to get Apache Burr in an app in production without thinking about REST APIs @@ -222,11 +222,11 @@ While Apache Burr is stable and well-tested, we have quite a few tools/features If you want to avoid self-hosting the above solutions we're building Burr Cloud. To let us know you're interested sign up [here](https://forms.gle/w9u2QKcPrztApRedA) for the waitlist to get access. -## 🀲 Contributing +## Contributing We welcome contributors! To get started on developing, see the [developer-facing docs](https://burr.apache.org/contributing). -## πŸ‘ͺ Contributors +## Contributors ### Code contributions @@ -249,12 +249,12 @@ Users who have contributed small docs fixes, design suggestions, and found bugs - [Evans](https://github.com/sudoevans) - [Sasmitha Manathunga](https://github.com/mmz-001) -# πŸ“‘ License +# License Apache Burr is released under the Apache 2.0 License. See [LICENSE](https://github.com/apache/burr/blob/main/LICENSE) for details. -# 🌎 Community -## πŸ‘¨β€πŸ’» Contributing +# Community +## Contributing We're very supportive of changes by new contributors, big or small! Make sure to discuss potential changes by creating an issue or commenting on an existing one before opening a pull request. Good first contributions include creating an example or an integration with your favorite Python library! To contribute, checkout our [contributing guidelines](https://github.com/apache/burr/blob/main/CONTRIBUTING.rst), our [developer setup guide](https://github.com/apache/burr/blob/main/developer_setup.md), and our [Code of Conduct](https://github.com/apache/burr/blob/main/CODE_OF_CONDUCT.md). diff --git a/docs/concepts/actions.rst b/docs/concepts/actions.rst index 30bf70957..c8809411d 100644 --- a/docs/concepts/actions.rst +++ b/docs/concepts/actions.rst @@ -26,7 +26,7 @@ Actions .. note:: Actions are the core building block of Burr. They read from state and write to state. - They can be synchronous and asynchonous, and have both a ``sync`` and ``async`` API. + They can be synchronous and asynchronous, and have both a ``sync`` and ``async`` API. There are both function and class-based APIs. @@ -96,7 +96,7 @@ above is equivalent to returning an empty dictionary instead of the results. from burr.core import action, State @action(reads=["var_from_state"], writes=["var_to_update"]) - def custom_action(state: State) -> State + def custom_action(state: State) -> State: return results, state.update(var_to_update=var_from_state + 1) app = ApplicationBuilder().with_actions( diff --git a/docs/concepts/state-persistence.rst b/docs/concepts/state-persistence.rst index cff0e6284..e6b38ffb8 100644 --- a/docs/concepts/state-persistence.rst +++ b/docs/concepts/state-persistence.rst @@ -271,7 +271,7 @@ tracked runs. This is useful for debugging, or building an application that enab tracker, resume_at_next_action=True, default_state={"chat_history" : []}, - default_entrypoint="human_converse + default_entrypoint="human_converse" ) .with_tracker(tracker) .with_identifiers(app_id=app_id) diff --git a/docs/concepts/tracking.rst b/docs/concepts/tracking.rst index 1e69b4525..ed035a63f 100644 --- a/docs/concepts/tracking.rst +++ b/docs/concepts/tracking.rst @@ -93,7 +93,7 @@ For example, to debug your Burr Application, you'd have some control flow like t fork_from_sequence_id=sequence_id, fork_from_partition_key=partition_key ) - .with_tracker(tracker) # tracking + checkpointing; one line πŸͺ„. + .with_tracker(tracker) # tracking + checkpointing in one line. .build() ) diff --git a/docs/examples/deployment/index.rst b/docs/examples/deployment/index.rst index e1afd91c3..60168777c 100644 --- a/docs/examples/deployment/index.rst +++ b/docs/examples/deployment/index.rst @@ -17,9 +17,9 @@ under the License. -============= -✈ Deployment -============= +========== +Deployment +========== Burr is specifically meant to make getting your product in production easier and faster. This section covers examples of getting Burr to production, as well as a brief overview of approaches/requirements. diff --git a/docs/getting_started/install.rst b/docs/getting_started/install.rst index 335401758..38ec9874e 100644 --- a/docs/getting_started/install.rst +++ b/docs/getting_started/install.rst @@ -33,7 +33,8 @@ along with a fully built server. This will give you tools to visualize, track, and interact with the UI. You can explore the UI (including some sample projects) simply by running the command ``burr``. Up next we'll write our own application and follow it in the UI. -If you're using poetry, you can't install the ``start`` target directly, due to [this issue](https://github.com/python-poetry/poetry/issues/3369). +If you're using poetry, you can't install the ``start`` target directly, due to +`this issue `_. Instead, please install manually using the following command: .. code-block:: bash diff --git a/docs/getting_started/simple-example.rst b/docs/getting_started/simple-example.rst index 774275639..de467c68d 100644 --- a/docs/getting_started/simple-example.rst +++ b/docs/getting_started/simple-example.rst @@ -48,7 +48,7 @@ So hold tight! This gets you started with the basics but there's a lot more you If you want to skip ahead to the cool stuff (chatbots, ML training, simulations, etc...) feel free to jump into the deep end and start with the :ref:`examples `. -πŸ€” If you prefer to learn by video, check out +If you prefer to learn by video, check out `this video walkthrough `_ using `this notebook `_. @@ -222,4 +222,4 @@ Now that we've built a basic application, we can do the following with only a fe 2. :ref:`Persist state to a database + reload ` -- add a ``initialize_from`` line to the builder and select a pre-existing/implement a custom persistence method. 3. :ref:`Add monitoring to track application data ` -- leverage ``with_tracker`` to track to the Burr UI and visualize your application live. 4. :ref:`Stream results back ` -- minimize time to first token by streaming results back to the user. -5. `Generate test cases from prior runs `_ -- use the ``burr-testburr-test-case create`` command to automatically generate test cases for your LLM app. +5. `Generate test cases from prior runs `_ -- use the ``burr-test-case create`` command to automatically generate test cases for your LLM app. diff --git a/docs/getting_started/up-next.rst b/docs/getting_started/up-next.rst index 7acb2d28c..576071b8c 100644 --- a/docs/getting_started/up-next.rst +++ b/docs/getting_started/up-next.rst @@ -88,7 +88,7 @@ Once you're comfortable with the UI, you may want to get a sense of a few of the of the Burr library and where you can go to learn more about them: - :ref:`Creating custom actions ` and calling out to integrated frameworks -- :ref:`Running applications `, managing their lifeycyle, and inspecting the results +- :ref:`Running applications `, managing their lifecycle, and inspecting the results - :ref:`Managing state ` -- persisting, inspecting, and updating - :ref:`Handling transition between nodes ` and managing the flow of your application - :ref:`Adding hooks to customize execution ` and integrate with other systems diff --git a/examples/simple-chatbot-intro/README.md b/examples/simple-chatbot-intro/README.md index 059dc1346..23d05f76d 100644 --- a/examples/simple-chatbot-intro/README.md +++ b/examples/simple-chatbot-intro/README.md @@ -19,7 +19,7 @@ Example that goes with [introductory blog post](https://blog.dagworks.io/p/burr-develop-stateful-ai-applications). -## πŸƒQuick start +## Quick start ```bash pip install "burr[start]" jupyter