Apache Burr: a state machine library for LLM applications

The problem Apache Burr addresses: decisions and state, not prompts

Most LLM code starts as a straight line: take input, call a model, return text. It stops being a straight line the moment a step depends on the previous result, a human has to approve something, or a run has to survive a process restart. At that point the control flow is usually buried in nested conditionals, and the state is scattered across local variables that vanish with the process.

Apache Burr asks you to write that control flow down explicitly. The README states that you express your application as a state machine, in its words a graph or flowchart, and that you 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." The audience is Python engineers building chatbots, agents, simulations and similar applications who want the orchestration layer to be inspectable rather than implied by the framework.

The README is equally clear about the boundary: Apache Burr "will not tell you how to build your models, how to query APIs, or how to manage your data." It is a coordination layer. If you want a framework that hands you a retriever, a prompt template registry and an agent loop, this is the wrong shape of tool.

How the action graph, State and ApplicationBuilder fit together

The unit of work is an action: a plain Python function that reads named keys from State and writes named keys back. The decorator records those read and write sets, and the builder uses them to assemble the graph. Nothing in the action signature is LLM-specific, which is why the README can point at a time-series simulation and hyperparameter tuning as examples alongside chatbots.

The README's hello-world shows the whole shape. Two actions, human_input and ai_response, are registered with with_actions. with_transitions declares the edges, here a two-node loop. with_state seeds chat_history as an empty list, and with_entrypoint names where execution begins. app.run is then called with halt_after=["ai_response"] and an inputs dictionary carrying the prompt. The run returns the action results and the final state, and the README's example prints app.state["response"].

Two consequences follow from this design. First, the graph is data you can inspect before running anything, so a cycle that never terminates is visible in the transition list rather than discovered at runtime. Second, because actions declare what they read and write, the framework can persist and reload state at action boundaries. The README describes pluggable persisters, with memory given as the example, for saving and loading application state. Persistence is a property of the graph execution, not something you bolt on inside each function.

The repository layout backs this up. The package sits in burr/, the UI in telemetry/, and the runnable applications in examples/, with directories for multi-agent collaboration, conversational RAG, an LLM adventure game, OpenTelemetry wiring, parallelism and pytest usage. The README also notes that hooks and other integrations let you connect vendors for observability and storage, and delegate to libraries such as Apache Hamilton.

Installing Apache Burr and running the hello-world counter

The README's quick start installs from PyPI with the start extra, which pulls in the optional pieces including the CLI. The pyproject.toml lists no required dependencies for the core package, so the base library is dependency-free; the extras are where the weight lives.

pip install "apache-burr[start]"

One version note matters before you plan a rollout. The README states that in version 0.43.0 the optional CLI included with the start, learn and cli extras requires Python 3.10+, while core library usage remains compatible with Python 3.9. If you are pinned to 3.9, you can use the library but not the bundled CLI.

Running the bare command burr starts the telemetry UI. According to the README it ships with default data so you can click around, and includes a demo chat application under the Demos sidebar. Selecting chatbot requires the OPENAI_API_KEY environment variable, though the README notes you can still see how it works without an API key set.

export OPENAI_API_KEY=your-key-here
burr

The first real application is the counter example, which the README clones from the repository and runs directly. Expect counter output in the terminal and a corresponding trace in the UI.

git clone https://github.com/apache/burr && cd burr/examples/hello-world-counter
python application.py

For a chatbot of your own, the README's simple example defines the two actions with the @action decorator, wiring reads and writes for prompt, chat_history and response, then builds the application with ApplicationBuilder and runs it with halt_after and an inputs dictionary. The LLM call itself is left to you.

Where Apache Burr gets in the way

The explicit graph is the cost as well as the benefit. Every branch has to be declared as a transition, so a workflow that changes shape often means editing the builder each time. A single script that calls a model once and prints the answer gains nothing from a state machine except indirection.

The README is silent on several operational questions that decide whether a state machine library is usable in production. It does not document rollback semantics for a persister, nor how concurrent runs sharing one persister are isolated. Persistence is described as pluggable, with memory as the example, but the README does not enumerate which external stores ship as integrations. If your requirement is durable state in a specific database, check the integrations before you design around the persister API.

The telemetry UI deserves the same scrutiny. The README says it can track, monitor and trace your system in real time, and the quick start loads it with default data. What the UI stores, where it stores it, and how to turn capture off for sensitive inputs are not covered in the README. For applications handling personal data, that is a question to answer from the documentation before running the UI against real traffic.

Finally, the project is incubating at the Apache Software Foundation, and pyproject.toml classifies it as Development Status 4 - Beta. Version numbers carry the -incubating suffix. Treat API stability as provisional. The last push to the default branch was on 2026-09-10, and the most recent release listed is v0.43.0-incubating from 2026-08-29.

Apache Burr compared with LangGraph and Apache Hamilton

The search data shows people comparing Apache Burr with LangGraph, and the honest difference is where the graph comes from. LangGraph is part of an LLM application stack: its nodes are typically model calls and tool calls, and the surrounding library supplies message handling and agent patterns. Apache Burr's actions are ordinary Python functions with declared reads and writes, and the README repeatedly stresses that it does not care how you use LLMs. If your team already has opinions about prompting, retrieval and model clients, Burr leaves those decisions alone. If you want the framework to make them, LangGraph's integrated approach will involve less assembly.

The comparison with Apache Hamilton is a different axis, and the README points at it directly: hooks and integrations let you build custom actions that delegate to libraries like Hamilton. Hamilton expresses computation as a dataflow of functions over a dataframe-like structure; Burr expresses control flow as transitions between actions with persisted state. They are complementary, which is why the repository carries a hamilton-integration example rather than treating the two as rivals. Airflow, which also appears in the search data, schedules batch workflows on a timetable; Burr runs an application's decision loop inside your process, or in a server you operate, which is a different job.

Licence and the cost of tracking an incubating project

Apache Burr is licensed under Apache-2.0, and pyproject.toml lists LICENSE-wheel, NOTICE and DISCLAIMER among the licence files shipped with the distribution. The DISCLAIMER file at the repository root is the standard Apache incubator notice. For most commercial use the Apache licence is permissive and imposes notice obligations rather than source disclosure; that is a general description of the licence, not legal advice, and your counsel should review the NOTICE and DISCLAIMER as distributed.

Upgrade cost is the more practical concern. The release history shows v0.42.0-incubating in May 2026, then v0.43.0-incubating in August 2026, with burr-0.40.2 back in May 2025. That cadence is steady but the version numbers are still below 1.0 and carry the incubating suffix, so minor releases can move APIs. The 0.43.0 note about the CLI requiring Python 3.10+ while the core stays on 3.9 is exactly the kind of change that reaches users through release notes rather than a major version bump. Pin the version, read the release notes before moving, and keep your actions thin so that a change in the builder API touches few files.

Editorial conclusion

Adopt Apache Burr if your application has branching decisions, human feedback steps, or state you need to resume and inspect, and you are willing to write the LLM calls yourself. Skip it if you want a framework that supplies prompts, retrieval or agent loops, or if you cannot run Python 3.10+ and need the bundled CLI. Before committing, verify three things: that a persister you can operate exists for your storage, that the telemetry UI's data handling matches your requirements, and that the incubating status and release cadence fit your dependency policy. Start from examples/hello-world-counter, which the README names as the first runnable example.

Frequently asked questions

Official sources

1. apache/burr on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases