feat: implement Redis-backed user state management and update state handling

app.py

@@ -0,0 +1,19 @@
+import subprocess
+import time
+import atexit
+
+# Launch local Redis server
+redis_process = subprocess.Popen([
+    "redis-server",
+    "--save", "",
+    "--appendonly", "no",
+])
+
+# Ensure Redis shuts down on exit
+atexit.register(redis_process.terminate)
+
+# Give the server a moment to start
+time.sleep(0.5)
+
+# Import and run the Gradio app
+import src.main  # noqa: F401

packages.txt

@@ -0,0 +1 @@
+redis-server

requirements.txt

@@ -14,4 +14,7 @@ langchain-community==0.3.16
 langchain-google-genai==2.1.4
 pydantic-core==2.23.4
 pydantic-settings==2.7.1
-pydantic==2.9.2
+pydantic==2.9.2
+redis[hiredis]>=5
+aioredis>=2
+msgpack

src/agent/llm_graph.py

@@ -14,7 +14,7 @@ from agent.tools import (
     generate_story_frame,
     update_state_with_choice,
 )
-from agent.state import get_user_state
+from agent.redis_state import get_user_state
 from audio.audio_generator import change_music_tone
 logger = logging.getLogger(__name__)
 
@@ -75,7 +75,7 @@ async def node_init_game(state: GraphState) -> GraphState:
 
 async def node_player_step(state: GraphState) -> GraphState:
     logger.debug("[Graph] node_player_step state: %s", state)
-    user_state = get_user_state(state.user_hash)
+    user_state = await get_user_state(state.user_hash)
     scene_id = user_state.current_scene_id
     if state.choice_text:
         await update_state_with_choice.ainvoke(

src/agent/redis_state.py

@@ -0,0 +1,51 @@
+"""Async Redis-backed user state storage."""
+
+from __future__ import annotations
+
+import json
+import msgpack
+import redis.asyncio as redis
+
+from agent.models import UserState
+
+
+class UserRepository:
+    """Repository for storing UserState objects in Redis."""
+
+    def __init__(self, redis_url: str = "redis://localhost") -> None:
+        self.redis = redis.from_url(redis_url)
+
+    async def get(self, user_id: str) -> UserState:
+        """Return user state for the given id, creating it if absent."""
+        key = f"llmgamehub:{user_id}"
+        data = await self.redis.hget(key, "data")
+        if data is None:
+            return UserState()
+        state_dict = msgpack.unpackb(data, raw=False)
+        return UserState.parse_obj(state_dict)
+
+    async def set(self, user_id: str, state: UserState) -> None:
+        """Persist updated user state."""
+        key = f"llmgamehub:{user_id}"
+        packed = msgpack.packb(json.loads(state.json()))
+        await self.redis.hset(key, mapping={"data": packed})
+
+    async def reset(self, user_id: str) -> None:
+        """Remove stored state for a user."""
+        key = f"llmgamehub:{user_id}"
+        await self.redis.delete(key)
+
+
+_repo = UserRepository()
+
+
+async def get_user_state(user_hash: str) -> UserState:
+    return await _repo.get(user_hash)
+
+
+async def set_user_state(user_hash: str, state: UserState) -> None:
+    await _repo.set(user_hash, state)
+
+
+async def reset_user_state(user_hash: str) -> None:
+    await _repo.reset(user_hash)

src/agent/runner.py

@@ -10,7 +10,7 @@ from agent.tools import generate_scene_image
 
 from agent.llm_graph import GraphState, llm_game_graph
 from agent.models import UserState
-from agent.state import get_user_state
+from agent.redis_state import get_user_state
 
 logger = logging.getLogger(__name__)
 
@@ -38,7 +38,7 @@ async def process_step(
 
     final_state = await llm_game_graph.ainvoke(asdict(graph_state))
 
-    user_state: UserState = get_user_state(user_hash)
+    user_state: UserState = await get_user_state(user_hash)
     response: Dict = {}
 
     ending = final_state.get("ending")

src/agent/tools.py

@@ -17,7 +17,7 @@ from agent.models import (
     UserChoice,
 )
 from agent.prompts import ENDING_CHECK_PROMPT, SCENE_PROMPT, STORY_FRAME_PROMPT
-from agent.state import get_user_state, set_user_state
+from agent.redis_state import get_user_state, set_user_state
 from images.image_generator import modify_image, generate_image
 from agent.image_agent import ChangeScene
 
@@ -53,9 +53,9 @@ async def generate_story_frame(
         character=character,
         genre=genre,
     )
-    state = get_user_state(user_hash)
+    state = await get_user_state(user_hash)
     state.story_frame = story_frame
-    set_user_state(user_hash, state)
+    await set_user_state(user_hash, state)
     return story_frame.dict()
 
 
@@ -65,7 +65,7 @@ async def generate_scene(
     last_choice: Annotated[str, "Last user choice"],
 ) -> Annotated[Dict, "Generated scene"]:
     """Generate a new scene based on the current user state."""
-    state = get_user_state(user_hash)
+    state = await get_user_state(user_hash)
     if not state.story_frame:
         return _err("Story frame not initialized")
     llm = create_llm().with_structured_output(SceneLLM)
@@ -98,7 +98,7 @@ async def generate_scene(
     )
     state.current_scene_id = scene_id
     state.scenes[scene_id] = scene
-    set_user_state(user_hash, state)
+    await set_user_state(user_hash, state)
     return scene.dict()
 
 
@@ -119,10 +119,10 @@ async def generate_scene_image(
                 # for now always modify the image to avoid the generating an update in a completely wrong style
                 else modify_image(current_image, change_scene.scene_description)
             )
-        state = get_user_state(user_hash)
+        state = await get_user_state(user_hash)
         if scene_id in state.scenes:
             state.scenes[scene_id].image = image_path
-        set_user_state(user_hash, state)
+        await set_user_state(user_hash, state)
         return image_path
     except Exception as exc:  # noqa: BLE001
         return _err(str(exc))
@@ -137,7 +137,7 @@ async def update_state_with_choice(
     """Record the player's choice in the state."""
     import datetime
 
-    state = get_user_state(user_hash)
+    state = await get_user_state(user_hash)
     state.user_choices.append(
         UserChoice(
             scene_id=scene_id,
@@ -145,7 +145,7 @@ async def update_state_with_choice(
             timestamp=datetime.datetime.utcnow().isoformat(),
         )
     )
-    set_user_state(user_hash, state)
+    await set_user_state(user_hash, state)
     return state.dict()
 
 
@@ -154,7 +154,7 @@ async def check_ending(
     user_hash: Annotated[str, "User session ID"],
 ) -> Annotated[Dict, "Ending check result"]:
     """Check whether an ending has been reached."""
-    state = get_user_state(user_hash)
+    state = await get_user_state(user_hash)
     if not state.story_frame:
         return _err("No story frame")
     llm = create_llm().with_structured_output(EndingCheckResult)
@@ -166,6 +166,6 @@ async def check_ending(
     resp: EndingCheckResult = await llm.ainvoke(prompt)
     if resp.ending_reached and resp.ending:
         state.ending = resp.ending
-        set_user_state(user_hash, state)
+        await set_user_state(user_hash, state)
         return {"ending_reached": True, "ending": resp.ending.dict()}
     return {"ending_reached": False}

src/main.py

@@ -26,9 +26,9 @@ logger = logging.getLogger(__name__)
 
 async def return_to_constructor(user_hash: str):
     """Return to the constructor and reset user state and audio."""
-    from agent.state import reset_user_state
+    from agent.redis_state import reset_user_state
 
-    reset_user_state(user_hash)
+    await reset_user_state(user_hash)
     await cleanup_music_session(user_hash)
     # Generate a new hash to avoid stale state
     new_hash = str(uuid.uuid4())