State Management¶

State is the data container that flows through your graph. Every node receives the current state and returns an updated state.

SharedState¶

SharedState is the default, thread-safe state type. It behaves like a Python dict:

from flowgentra_ai import SharedState

# Create with initial data
state = SharedState({"name": "FlowgentraAI", "version": 1})

# Dict-like access
state["count"] = 42
print(state["name"])          # "FlowgentraAI"
print("name" in state)        # True
print(len(state))             # 3
del state["version"]

# Methods
state.set("key", "value")
val = state.get("key")        # "value" (returns None if missing)
val = state.get_string("key") # "value" (returns None if not a string)
keys = state.keys()           # ["name", "count", "key"]
state.remove("key")

Serialization¶

# To/from dict
d = state.to_dict()           # {"name": "FlowgentraAI", "count": 42}
state = SharedState.from_dict({"a": 1, "b": 2})

# To/from JSON
json_str = state.to_json()
state = SharedState.from_json('{"a": 1, "b": 2}')

Deep Clone¶

SharedState is reference-counted internally. Assigning it to another variable shares the same data. To get an independent copy:

original = SharedState({"x": 1})
clone = original.deep_clone()
clone["x"] = 99
print(original["x"])  # 1 (unchanged)

PlainState¶

PlainState is a non-thread-safe state for advanced use cases where you need direct ownership:

from flowgentra_ai import PlainState

state = PlainState({"x": 1})
state["y"] = 2

# Additional typed getters
state.get_string("x")   # None (x is int)
state.get_int("x")      # 1
state.get_float("x")    # None
state.get_bool("x")     # None

Tip

Use SharedState for all graph workflows. Only use PlainState if you have a specific reason to avoid the thread-safety overhead.