Skip to content

docs: refresh roadmap to reflect shipped, in-review, and planned work #976

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
elijahbenizzy wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: refresh roadmap to reflect shipped, in-review, and planned work #976

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 8 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,18 +214,14 @@ but realized that it has a wide array of applications and decided to release it

## 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
2. Various efficiency/usability improvements for the core library (see [planned capabilities](https://burr.apache.org/concepts/planned-capabilities/) for more details). This includes:
1. First-class support for retries + exception management
2. More integration with popular frameworks (LCEL, LLamaIndex, Apache Hamilton, etc...)
3. Capturing & surfacing extra metadata, e.g. annotations for particular point in time, that you can then pull out for fine-tuning, etc.
4. Improvements to the pydantic-based typing system
3. Tooling for hosted execution of state machines, integrating with your infrastructure (Ray, modal, FastAPI + EC2, etc...)
4. Additional storage integrations. More integrations with technologies like MySQL, S3, etc. so you can run Apache Burr on top of what you have available.

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.
Apache Burr is stable and actively developed. The full status roadmap, with links to docs, pull requests, and design threads, lives at [Roadmap and Status](https://burr.apache.org/concepts/planned-capabilities/). In brief:

- **Shipped**: state persistence (`initialize_from` + SQLite/PostgreSQL/MongoDB/Redis persisters), annotations in the tracking UI, `Condition.safe_expr`, integrations (Hamilton, Haystack, LangChain, Langfuse, OpenTelemetry, Pydantic, Ray, Bedrock, Streamlit), UI dark mode, and a published [security policy](https://github.com/apache/burr/blob/main/SECURITY.md).
- **In review**: exception transitions, durable execution (suspend/resume), a visual builder in the UI, an artifact store for large state values, parallel streaming, Mermaid graph export, Aerospike and Google Sheets persisters, a TypeScript port, and a LiteLLM integration.
- **Under discussion**: durable execution design and the direction of the visual builder, on `dev@burr.apache.org`.
- **Planned**: build-time graph validation, evaluation and LLM-as-judge over annotations, a FastAPI serving integration, and more storage backends.

Need something sooner? Open an issue or start a thread on the mailing list.

## Contributing

Expand Down
199 changes: 103 additions & 96 deletions docs/concepts/planned-capabilities.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,99 +17,106 @@
under the License.


====================
Planned Capabilities
====================

These are on the roadmap (and will be part of Burr in the imminent future), but have not been built yet.

We build fast though, so let us know which ones you need and they'll be in there before you know it!


------------------------------------
Evaluation & Annotation integrations
------------------------------------

You can already annotate with the Burr UI. We have plans to:

1. plug in metrics and custom callbacks/LLM as judge capabilities to enable you to evaluate what captured and annotated.
2. SDK functionality to allow programmatic annotation and evaluation, as well as export and search of annotations.

-----------------------------
State Management/Immutability
-----------------------------

We plan the ability to manage state in a few ways:

1. ``commit`` -- an internal tool to commit/compile a series of changes so that we have the latest state evaluated
2. ``persist`` -- a user-facing API to persist state to a database. This will be pluggable by the user, and we will have a few built-in options (e.g. a simple in-memory store, a file store, a database store, etc...)
3. ``hydrate`` -- a static method to hydrate state from a database. This will be pluggable by the user, and we will have a few built-in options that mirror those in ``persist`` options.

Currently state is immutable, but it utilizes an inefficient copy mechanism. This is out of expedience -- we don't anticipate this will
be painful for the time being, but plan to build a more efficient functional paradigm. We will likely have:

1. Each state object be a node in a linked list, with a pointer to the previous state. It carries a diff of the changes from the previous state.
2. An ability to ``checkpoint`` (allowing for state garbage collection), and store state in memory/kill out the pointers.

We will also consider having the ability to have a state solely backed by redis (and not memory), but we are still thinking through the API.

----------------------
Compilation/Validation
----------------------

We currently do not validate that the chain of actions provide a valid state, although we plan to walk the graph to ensure that no "impossible"
situation is reached. E.G. if an action reads from a state that is not written to (or not initialized), we will raise an error, likely upon calling `validate`.
We may be changing the behavior with defaults over time.

--------------------
Exception Management
--------------------

Currently, exceptions will break the control flow of an action, stopping the program early. Thus,
if an exception is expected, the program will stop early. We will be adding the ability to conditionally transition based
on exceptions, which will allow you to transition to an error-handling (or retry) action that does not
need the full outputs of the prior action.

Here is what it would look like in the current API:

.. code-block:: python

@action(reads=["attempts"], writes=["output", "attempts"])
def some_flaky_action(state: State, max_retries: int=3) -> State:
result = {"output": None, "attempts": state["attempts"] + 1}
try:
result["output"] = call_some_api(...)
except APIException as e:
if state["attempts"] >= max_retries:
raise e
return state.update(**result)

One could imagine adding it as a condition (a few possibilities)

.. code-block:: python

@action(reads=[], writes=["output"])
def some_flaky_action(state: State) -> State
result = {"output": call_some_api(...)}
return state.update(**result)

builder.with_actions(
some_flaky_action=some_flaky_action
).with_transitions(
(
"some_flaky_action",
"some_flaky_action",
error(APIException) # infinite retries
error(APIException, max=3) # 3 visits to this edge then it gets reset if this is not chosen
# That's stored in state
)
)

Will have to come up with ergonomic APIs -- the above are just some ideas.

------------
Integrations
------------

We already have support for Haystack, Hamilton, and LangChain.
Please request any other integrations you'd like to see.
==================
Roadmap and Status
==================

This page is a status report on notable Apache Burr capabilities, accurate as of October 2026.
It records where each item stands -- shipped, in review, under discussion, or planned -- rather than
making commitments or ranking priorities. Work happens in the open: proposals and design discussions
go to the ``dev@burr.apache.org`` mailing list, and code goes through pull requests on
`GitHub <https://github.com/apache/burr>`_. If something you need is missing, open an issue or start
a thread.

-------
Shipped
-------

Available in the current release.

* **State persistence and rehydration.** Save and reload application state with
``ApplicationBuilder.initialize_from`` and the persister API. Built-in persisters cover in-memory,
SQLite, PostgreSQL, MongoDB, and Redis, with async variants. See
`State Persistence <https://burr.apache.org/concepts/state-persistence/>`_.
* **Annotations in the tracking UI.** Annotate steps and spans of a run from the Burr UI; data lives
alongside the tracked application. See `Tracking <https://burr.apache.org/concepts/tracking/>`_
(introduced in `#383 <https://github.com/apache/burr/pull/383>`_).
* **Restricted condition expressions.** ``Condition.safe_expr`` evaluates transition expressions under
an allowlisted AST grammar, for conditions that come from untrusted sources. See
`Conditions/Transitions <https://burr.apache.org/reference/conditions/>`_
(`#820 <https://github.com/apache/burr/pull/820>`_).
* **Integrations.** Hamilton, Haystack, LangChain, Langfuse, OpenTelemetry (including Traceloop),
Pydantic, Ray, Amazon Bedrock, and Streamlit. See
`Integrations <https://burr.apache.org/reference/integrations/>`_.
* **Dark mode in the UI.** Follows the system preference with a manual toggle
(`#830 <https://github.com/apache/burr/pull/830>`_).
* **Security policy.** A published reporting process and security model in
`SECURITY.md <https://github.com/apache/burr/blob/main/SECURITY.md>`_
(`#944 <https://github.com/apache/burr/pull/944>`_).

---------
In review
---------

Open pull requests. Listing here means the code exists and is being reviewed, not that it will merge
as-is.

* **Exception transitions** via ``on_error`` capture and wildcard routing --
`#796 <https://github.com/apache/burr/pull/796>`_ (tracks
`issue #30 <https://github.com/apache/burr/issues/30>`_; this supersedes the earlier
``error(APIException)`` sketch that used to live on this page).
* **Durable execution** (suspend/resume with a durable journal on the context) --
`#786 <https://github.com/apache/burr/pull/786>`_; see the design discussion below.
* **Visual builder and workspace mode** in the Burr UI --
`#687 <https://github.com/apache/burr/pull/687>`_.
* **Claude Code skill** for working on Burr applications --
`#644 <https://github.com/apache/burr/pull/644>`_.
* **Artifact/blob store** for large state values --
`#931 <https://github.com/apache/burr/pull/931>`_.
* **Lower-level parallel streaming** -- `#836 <https://github.com/apache/burr/pull/836>`_.
* **Mermaid graph visualization** -- `#861 <https://github.com/apache/burr/pull/861>`_.
* **Aerospike persister** -- `#936 <https://github.com/apache/burr/pull/936>`_.
* **Google Sheets persister** -- `#932 <https://github.com/apache/burr/pull/932>`_.
* ``Application.get_prior_action`` -- `#943 <https://github.com/apache/burr/pull/943>`_.
* **OrcaRouter agent example** -- `#896 <https://github.com/apache/burr/pull/896>`_.
* **TypeScript implementation** of the core state machine --
`#728 <https://github.com/apache/burr/pull/728>`_.
* **LiteLLM AI gateway integration** -- `#803 <https://github.com/apache/burr/pull/803>`_
(closed by inactivity on 2026-10-05 after the author added the requested end-to-end example;
revivable).

----------------
Under discussion
----------------

Design threads on ``dev@burr.apache.org`` and open issues without an implementation yet.

* **Durable execution design** --
`[DISCUSS] Durable execution in Burr <https://lists.apache.org/thread/v9nrtms7nq5noqj2ottw0r0tntohl8s5>`_
(May--October 2026); the implementation proposal is `#786`_ above.
* **Builder direction** (code-picture-code round-tripping, Pyodide, roadmap) --
`[DISCUSS] Builder direction <https://lists.apache.org/thread/l9y4nk98wtn2rhpj9xgxszpbvq4psh7c>`_
and the earlier
`[discuss] Graph builder UI <https://lists.apache.org/thread/hst35owhcl8swv967rxlh9tpx75gwlrq>`_
(March 2026); related to `#687`_ above.
* **Google Sheets persister design** --
`[DISCUSS] Google Sheets Persister design <https://lists.apache.org/thread/z6rmcsqb5b8t1o80z64cmnok6r6r23yy>`_
and `issue #213 <https://github.com/apache/burr/issues/213>`_; related to `#932`_ above.
* **Interceptor lifecycle hook** --
`[discuss] adding interceptor lifecycle hook <https://lists.apache.org/thread/k4sq37opkmx0pywp40kqwqkc7x3yyvgn>`_
(November 2025, no implementation yet).
* **Exception transitions** -- `issue #30`_ remains open while `#796`_ is reviewed.
Comment on lines +57 to +108

@jernejfrank jernejfrank Oct 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can see how collecting In review and Under Discussion could be useful, but, IMO, this will drift and become stale very fast. Maybe it is enough to just point to open PRs and to search the email threads with the discussion subject?

An alternative is to automate these two blocks via CI, but then we need a discussion which PRs are notable enough to get them on this list (if we just collect all the PRs I do not see much value since they are already on github).


-------
Planned
-------

@jernejfrank jernejfrank Oct 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of these look exciting to work on, but would be good to have some priorities attached to them or a community mechanism to vote on?


Intentions carried over from the previous version of this page that have not shipped and have no open
pull request. No dates are attached.

* **Build-time graph validation.** Walk the graph at build time and flag impossible situations, such as
an action that reads a state field no action writes and no initial state provides.
* **Evaluation on annotations.** Metrics, custom callbacks, and LLM-as-judge over annotated runs, plus
SDK support for programmatic annotation, export, and search.
* **FastAPI integration** for serving Burr applications without hand-writing the REST layer.
* **More storage backends** beyond the persisters listed above.
Loading