feat: Implement interactive narrative game framework

.env.example

@@ -0,0 +1 @@
+GEMINI_API_KEY=KEY

.gitignore

@@ -0,0 +1,178 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+versions/
+
+.gradio
+generated/

requirements.txt

@@ -0,0 +1,16 @@
+gradio==5.32.0
+google-genai==1.18.0
+Pillow==10.1.0
+requests==2.31.0
+python-dotenv==1.0.0
+asyncio
+aiohttp==3.9.1 
+pygame==2.5.2 
+numpy
+langchain==0.3.17
+langchain-core==0.3.58
+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

src/agent/image_agent.py

@@ -0,0 +1,82 @@
+from pydantic import BaseModel, Field
+from typing import Literal, Optional
+from agent.llm import create_light_llm
+from langchain_core.messages import SystemMessage, HumanMessage
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+IMAGE_GENERATION_SYSTEM_PROMPT = """You are an AI agent for a visual novel game. Your role is to process an incoming scene description and determine if the visual scene needs to change. If it does, you will generate a new `scene_description`. This `scene_description` MUST BE a highly detailed image prompt, specifically engineered for an AI image generation model, and it MUST adhere to the strict first-person perspective detailed below.
+
+**Your Core Tasks & Output Structure:**
+Your output MUST be a `ChangeScene` object. You need to:
+1.  **Determine Change Type:** Decide if the scene requires a "change_completely", "modify", or "no_change" and set this in the `change_scene` field of the output object.
+2.  **Generate FPS Image Prompt:** If your decision is "change_completely" or "modify", you MUST then generate the image prompt and place it in the `scene_description` field of the output object. If "no_change", this field can be null or empty.
+
+**Mandatory: First-Person Perspective (FPS) for Image Prompts**
+The image prompt you generate for the `scene_description` field MUST strictly describe the scene from a first-person perspective (FPS), as if the player is looking directly through the character's eyes.
+    *   **Viewpoint:** All descriptions must be from the character's eye level, looking forward or as indicated by the scene.
+    *   **Character Visibility:** The scene must be depicted strictly as if looking through the character's eyes. NO part of the character's own body (e.g., hands, arms, feet, clothing on them) should be visible or described in the prompt. The view is purely what is external to the character.
+    *   **Immersion:** Focus on what the character directly sees and perceives in their immediate environment. Use phrasing that reflects this, for example: "I see...", "Before me lies...", "Looking through the grimy window...", "The corridor stretches out in front of me."
+
+**Guidelines for Crafting the FPS Image Prompt (for `scene_description` field):**
+When generating the image prompt, ensure it's detailed and considers the following aspects, all from the character's first-person viewpoint:
+
+1.  **Subject & Focus (as seen by the character):**
+    *   What is the primary subject or point of interest directly in the character's view?
+    *   Describe any other characters visible to the POV character: their appearance (from the character's perspective), clothing, expressions, posture, and actions.
+    *   Detail key objects, items, or environmental elements the character is interacting with or observing.
+
+2.  **Setting & Environment (from the character's perspective):**
+    *   Describe the immediate surroundings as the character would see them.
+    *   Time of day and weather conditions as perceived by the character.
+    *   Specific architectural or natural features visible in the character's field of view.
+
+3.  **Art Style & Medium:**
+    *   Specify the desired visual style (e.g., photorealistic, anime, manga, watercolor, oil painting, pixel art, 3D render, concept art, comic book).
+    *   Mention any specific artist influences if relevant (e.g., "in the style of Studio Ghibli").
+
+4.  **Composition & Framing (from the character's viewpoint):**
+    *   How is the scene framed from the character's eyes? (e.g., "looking straight ahead at a door," "view through a sniper scope," "gazing up at a tall tower").
+    *   Describe the arrangement of elements as perceived by the character. Avoid terms like "medium shot" or "wide shot" unless they can be rephrased from an FPS view (e.g., "a wide vista opens up before me").
+
+5.  **Lighting & Atmosphere (as perceived by the character):**
+    *   Describe lighting conditions (e.g., "bright sunlight streams through the window in front of me," "only the dim glow of my flashlight illuminates the passage ahead," "neon signs reflect off the wet street I'm looking at").
+    *   What is the overall mood or atmosphere from the character's perspective? (e.g., "a tense silence hangs in the air as I look down the dark hallway," "a sense of peace as I gaze at the sunset over the mountains").
+
+6.  **Color Palette:**
+    *   Specify dominant colors or a color scheme relevant to what the character sees.
+
+7.  **Details & Keywords:**
+    *   Include crucial details from the input scene description that the character would notice.
+    *   Use descriptive adjectives and strong keywords.
+
+**Example for the `scene_description` field (the FPS image prompt):**
+"FPS view. Through the cockpit window of a futuristic hovercar, a sprawling neon-lit cyberpunk city stretches out under a stormy, rain-lashed sky. Rain streaks across the glass. The hum of the engine is palpable. Photorealistic, Blade Runner style. Cool blue and vibrant pink neon palette."
+"""
+
+
+class ChangeScene(BaseModel):
+    change_scene: Literal["change_completely", "modify", "no_change"] = Field(
+        description="Whether the scene should be completely changed, just modified or not changed at all"
+    )
+    scene_description: Optional[str] = None
+
+
+image_prompt_generator_llm = create_light_llm(0.1).with_structured_output(ChangeScene)
+
+async def generate_image_prompt(scene_description: str, request_id: str) -> ChangeScene:
+    """
+    Generates a detailed image prompt string based on a scene description.
+    This prompt is intended for use with an AI image generation model.
+    """
+    logger.info(f"Generating image prompt for the current scene: {request_id}")
+    response = await image_prompt_generator_llm.ainvoke(
+        [
+            SystemMessage(content=IMAGE_GENERATION_SYSTEM_PROMPT),
+            HumanMessage(content=scene_description),
+        ]
+    )
+    logger.info(f"Image prompt generated: {request_id}")
+    return response

src/agent/llm.py

@@ -0,0 +1,59 @@
+"""Utility functions for working with the language model."""
+
+import logging
+from langchain_google_genai import ChatGoogleGenerativeAI
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+_API_KEYS: list[str] = []
+_current_key_idx = 0
+MODEL_NAME = "gemini-2.5-flash-preview-05-20"
+
+
+def _get_api_key() -> str:
+    """Return an API key using round-robin selection."""
+    global _API_KEYS, _current_key_idx
+
+    if not _API_KEYS:
+        keys_str = settings.gemini_api_key.get_secret_value()
+        if keys_str:
+            _API_KEYS = [k.strip() for k in keys_str.split(",") if k.strip()]
+        if not _API_KEYS:
+            msg = "Google API keys are not configured or invalid"
+            logger.error(msg)
+            raise ValueError(msg)
+
+    key = _API_KEYS[_current_key_idx]
+    _current_key_idx = (_current_key_idx + 1) % len(_API_KEYS)
+    logger.debug("Using Google API key index %s", _current_key_idx)
+    return key
+
+
+def create_llm(
+    temperature: float = settings.temperature,
+    top_p: float = settings.top_p,
+) -> ChatGoogleGenerativeAI:
+    """Create a standard LLM instance."""
+    return ChatGoogleGenerativeAI(
+        model=MODEL_NAME,
+        google_api_key=_get_api_key(),
+        temperature=temperature,
+        top_p=top_p,
+        thinking_budget=1024,
+    )
+    
+    
+def create_light_llm(temperature: float = settings.temperature, top_p: float = settings.top_p):
+    return ChatGoogleGenerativeAI(
+        model="gemini-2.0-flash",
+        google_api_key=_get_api_key(),
+        temperature=temperature,
+        top_p=top_p
+    )
+
+
+def create_precise_llm() -> ChatGoogleGenerativeAI:
+    """Return an LLM tuned for deterministic output."""
+    return create_llm(temperature=0, top_p=1)

src/agent/llm_agent.py

@@ -0,0 +1,73 @@
+from agent.llm import create_llm
+from pydantic import BaseModel, Field
+from typing import List
+import logging
+from agent.image_agent import ChangeScene
+import asyncio
+from agent.music_agent import generate_music_prompt
+from agent.image_agent import generate_image_prompt
+import uuid
+
+logger = logging.getLogger(__name__)
+
+
+class PlayerOption(BaseModel):
+    option_description: str = Field(
+        description="The description of the option, Examples: [Change location] Go to the forest; [Say] Hello!"
+    )
+
+
+class LLMOutput(BaseModel):
+    game_message: str = Field(
+        description="The message to the player, Example: You entered the forest, and you see unknown scary creatures. What do you do?"
+    )
+    player_options: List[PlayerOption] = Field(
+        description="The list of up to 3 options for the player to choose from."
+    )
+
+
+class MultiAgentResponse(BaseModel):
+    game_message: str = Field(
+        description="The message to the player, Example: You entered the forest, and you see unknown scary creatures. What do you do?"
+    )
+    player_options: List[PlayerOption] = Field(
+        description="The list of up to 3 options for the player to choose from."
+    )
+    music_prompt: str = Field(description="The prompt for the music generation model.")
+    change_scene: ChangeScene = Field(description="The change to the scene.")
+
+llm = create_llm().with_structured_output(MultiAgentResponse)
+
+
+async def process_user_input(input: str) -> MultiAgentResponse:
+    """
+    Process user input and update the state.
+    """
+    request_id = str(uuid.uuid4())
+    logger.info(f"LLM input received: {request_id}")
+
+    response: LLMOutput = await llm.ainvoke(input)
+
+    # return response
+    current_state = f"""{input}
+    
+    Game reaction: {response.game_message}
+    Player options: {response.player_options}
+    """
+
+    music_prompt_task = generate_music_prompt(current_state, request_id)
+    
+    change_scene_task = generate_image_prompt(current_state, request_id)
+    
+    music_prompt, change_scene = await asyncio.gather(music_prompt_task, change_scene_task)
+
+    multi_agent_response = MultiAgentResponse(
+        game_message=response.game_message,
+        player_options=response.player_options,
+        music_prompt=music_prompt,
+        change_scene=change_scene,
+    )
+    
+    logger.info(f"LLM responded: {request_id}")
+
+    return multi_agent_response

src/agent/llm_graph.py

@@ -0,0 +1,144 @@
+"""LangGraph setup for the interactive fiction agent."""
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+import asyncio
+from langgraph.graph import END, StateGraph
+from agent.image_agent import generate_image_prompt
+
+from agent.tools import (
+    check_ending,
+    generate_scene,
+    generate_scene_image,
+    generate_story_frame,
+    update_state_with_choice,
+)
+from agent.state import get_user_state
+from audio.audio_generator import change_music_tone
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class GraphState:
+    """Mutable state passed between graph nodes."""
+
+    user_hash: Optional[str] = None
+    step: Optional[str] = None
+    setting: Optional[str] = None
+    character: Optional[Dict[str, Any]] = None
+    genre: Optional[str] = None
+    choice_text: Optional[str] = None
+    scene: Optional[Dict[str, Any]] = None
+    ending: Optional[Dict[str, Any]] = None
+
+
+async def node_entry(state: GraphState) -> GraphState:
+    logger.debug("[Graph] entry state: %s", state)
+    return state
+
+
+def route_step(state: GraphState) -> str:
+    if state.step == "start":
+        return "init_game"
+    if state.step == "choose":
+        return "player_step"
+    logger.warning("route_step received unknown step '%s'", state.step)
+    return "init_game"
+
+
+async def node_init_game(state: GraphState) -> GraphState:
+    logger.debug("[Graph] node_init_game state: %s", state)
+    await generate_story_frame.ainvoke(
+        {
+            "user_hash": state.user_hash,
+            "setting": state.setting,
+            "character": state.character,
+            "genre": state.genre,
+        }
+    )
+    first_scene = await generate_scene.ainvoke(
+        {"user_hash": state.user_hash, "last_choice": "start"}
+    )
+    change_scene = await generate_image_prompt(first_scene["description"], state.user_hash)
+    logger.info(f"Change scene: {change_scene}")
+    await generate_scene_image.ainvoke(
+        {
+            "user_hash": state.user_hash,
+            "scene_id": first_scene["scene_id"],
+            "change_scene": change_scene,
+        }
+    )
+    state.scene = first_scene
+    return state
+
+
+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)
+    scene_id = user_state.current_scene_id
+    if state.choice_text:
+        await update_state_with_choice.ainvoke(
+            {
+                "user_hash": state.user_hash,
+                "scene_id": scene_id,
+                "choice_text": state.choice_text,
+            }
+        )
+    ending = await check_ending.ainvoke({"user_hash": state.user_hash})
+    state.ending = ending
+    if not ending.get("ending_reached", False):
+        next_scene = await generate_scene.ainvoke(
+            {
+                "user_hash": state.user_hash,
+                "last_choice": state.choice_text,
+            }
+        )
+        change_scene = await generate_image_prompt(next_scene["description"], state.user_hash)
+        image_task = generate_scene_image.ainvoke(
+            {
+                "user_hash": state.user_hash,
+                "scene_id": next_scene["scene_id"],
+                "current_image": user_state.assets[scene_id],
+                "change_scene": change_scene,
+            }
+        )
+        music_task = change_music_tone(state.user_hash, next_scene["music"])
+        await asyncio.gather(image_task, music_task)
+        state.scene = next_scene
+    return state
+
+
+def route_ending(state: GraphState) -> str:
+    return "game_over" if state.ending.get("ending_reached") else "continue"
+
+
+async def node_game_over(state: GraphState) -> GraphState:
+    logger.info("[Graph] Game over for user %s", state.user_hash)
+    return state
+
+
+def build_llm_game_graph() -> StateGraph:
+    graph = StateGraph(GraphState)
+    graph.add_node("entry", node_entry)
+    graph.add_node("init_game", node_init_game)
+    graph.add_node("player_step", node_player_step)
+    graph.add_node("game_over", node_game_over)
+
+    graph.set_entry_point("entry")
+    graph.add_conditional_edges(
+        "entry",
+        route_step,
+        {"init_game": "init_game", "player_step": "player_step"},
+    )
+    graph.add_edge("init_game", END)
+    graph.add_conditional_edges(
+        "player_step",
+        route_ending,
+        {"game_over": "game_over", "continue": END},
+    )
+    graph.add_edge("game_over", END)
+    return graph.compile()
+
+
+llm_game_graph = build_llm_game_graph()

src/agent/models.py

@@ -0,0 +1,104 @@
+"""Pydantic models representing game state and LLM outputs."""
+
+from typing import Dict, List, Optional, Set
+
+from pydantic import BaseModel, Field
+
+
+class Milestone(BaseModel):
+    """Milestone that can be achieved during the story."""
+
+    id: str
+    description: str
+
+
+class Ending(BaseModel):
+    """Possible game ending."""
+
+    id: str
+    type: str  # "good" or "bad"
+    condition: str
+    description: Optional[str] = None
+
+
+class StoryFrame(BaseModel):
+    """Overall plot information generated by the LLM."""
+
+    lore: str
+    goal: str
+    milestones: List[Milestone]
+    endings: List[Ending]
+    setting: str
+    character: Dict[str, str]
+    genre: str
+
+
+class StoryFrameLLM(BaseModel):
+    """Structure returned by the LLM for story frame generation."""
+
+    lore: str
+    goal: str
+    milestones: List[Milestone]
+    endings: List[Ending]
+
+
+class SceneChoice(BaseModel):
+    """User choice leading to another scene."""
+
+    text: str
+    next_scene_short_desc: str
+
+
+class PlayerOption(BaseModel):
+    """Option presented to the player in a scene."""
+
+    option_description: str = Field(
+        description=(
+            "Description of the option, e.g. '[Say] Hello!' or "
+            "'Go to the forest'"
+        )
+    )
+
+
+class Scene(BaseModel):
+    """Game scene with choices and optional assets."""
+
+    scene_id: str
+    description: str
+    choices: List[SceneChoice]
+    image: Optional[str] = None
+    music: Optional[str] = None
+
+
+class SceneLLM(BaseModel):
+    """Structure expected from the LLM when generating a scene."""
+
+    description: str
+    choices: List[SceneChoice]
+
+
+class EndingCheckResult(BaseModel):
+    """Result returned from the LLM when checking for an ending."""
+
+    ending_reached: bool = Field(default=False)
+    ending: Optional[Ending] = None
+
+
+class UserChoice(BaseModel):
+    """Single player choice recorded in the history."""
+
+    scene_id: str
+    choice_text: str
+    timestamp: Optional[str] = None
+
+
+class UserState(BaseModel):
+    """State stored for each user."""
+
+    story_frame: Optional[StoryFrame] = None
+    current_scene_id: Optional[str] = None
+    scenes: Dict[str, Scene] = Field(default_factory=dict)
+    milestones_achieved: Set[str] = Field(default_factory=set)
+    user_choices: List[UserChoice] = Field(default_factory=list)
+    ending: Optional[Ending] = None
+    assets: Dict[str, str] = Field(default_factory=dict)

src/agent/music_agent.py

@@ -0,0 +1,47 @@
+from pydantic import BaseModel
+from agent.llm import create_light_llm
+from langchain_core.messages import SystemMessage, HumanMessage
+import logging
+
+logger = logging.getLogger(__name__)
+
+music_options = """Instruments: 303 Acid Bass, 808 Hip Hop Beat, Accordion, Alto Saxophone, Bagpipes, Balalaika Ensemble, Banjo, Bass Clarinet, Bongos, Boomy Bass, Bouzouki, Buchla Synths, Cello, Charango, Clavichord, Conga Drums, Didgeridoo, Dirty Synths, Djembe, Drumline, Dulcimer, Fiddle, Flamenco Guitar, Funk Drums, Glockenspiel, Guitar, Hang Drum, Harmonica, Harp, Harpsichord, Hurdy-gurdy, Kalimba, Koto, Lyre, Mandolin, Maracas, Marimba, Mbira, Mellotron, Metallic Twang, Moog Oscillations, Ocarina, Persian Tar, Pipa, Precision Bass, Ragtime Piano, Rhodes Piano, Shamisen, Shredding Guitar, Sitar, Slide Guitar, Smooth Pianos, Spacey Synths, Steel Drum, Synth Pads, Tabla, TR-909 Drum Machine, Trumpet, Tuba, Vibraphone, Viola Ensemble, Warm Acoustic Guitar, Woodwinds, ...
+Music Genre: Acid Jazz, Afrobeat, Alternative Country, Baroque, Bengal Baul, Bhangra, Bluegrass, Blues Rock, Bossa Nova, Breakbeat, Celtic Folk, Chillout, Chiptune, Classic Rock, Contemporary R&B, Cumbia, Deep House, Disco Funk, Drum & Bass, Dubstep, EDM, Electro Swing, Funk Metal, G-funk, Garage Rock, Glitch Hop, Grime, Hyperpop, Indian Classical, Indie Electronic, Indie Folk, Indie Pop, Irish Folk, Jam Band, Jamaican Dub, Jazz Fusion, Latin Jazz, Lo-Fi Hip Hop, Marching Band, Merengue, New Jack Swing, Minimal Techno, Moombahton, Neo-Soul, Orchestral Score, Piano Ballad, Polka, Post-Punk, 60s Psychedelic Rock, Psytrance, R&B, Reggae, Reggaeton, Renaissance Music, Salsa, Shoegaze, Ska, Surf Rock, Synthpop, Techno, Trance, Trap Beat, Trip Hop, Vaporwave, Witch house, ...
+Mood/Description: Acoustic Instruments, Ambient, Bright Tones, Chill, Crunchy Distortion, Danceable, Dreamy, Echo, Emotional, Ethereal Ambience, Experimental, Fat Beats, Funky, Glitchy Effects, Huge Drop, Live Performance, Lo-fi, Ominous Drone, Psychedelic, Rich Orchestration, Saturated Tones, Subdued Melody, Sustained Chords, Swirling Phasers, Tight Groove, Unsettling, Upbeat, Virtuoso, Weird Noises, ...
+"""
+system_prompt = f"""
+You are a music agent responsible for generating appropriate music tones for scenes in a visual novel game.
+
+Your task is to analyze the current scene description and generate a detailed music prompt that captures:
+1. The emotional atmosphere
+2. The intensity level
+3. The genre/style that best fits the scene
+4. Specific instruments that would enhance the mood
+
+You have access to a wide range of musical elements including:
+{music_options}
+
+When generating a music prompt:
+- Consider the scene's context, mood, and any suspense elements
+- Choose instruments that complement the scene's atmosphere
+- Select a genre that matches the story's setting and tone
+- Include specific mood descriptors to guide the music generation
+
+Your output should be a concise but detailed prompt that the music generation model can use to create an appropriate soundtrack for the scene.
+"""
+
+
+class MusicPrompt(BaseModel):
+    prompt: str
+
+
+llm = create_light_llm(0.1).with_structured_output(MusicPrompt)
+
+
+async def generate_music_prompt(scene_description: str, request_id: str) -> str:
+    logger.info(f"Generating music prompt for the current scene: {request_id}")
+    response = await llm.ainvoke(
+        [SystemMessage(content=system_prompt), HumanMessage(content=scene_description)]
+    )
+    logger.info(f"Music prompt generated: {request_id}")
+    return response.prompt

src/agent/prompts.py

@@ -0,0 +1,40 @@
+STORY_FRAME_PROMPT = """
+You are a narrative game designer. Use the player data below to
+create a story frame for an interactive adventure.
+Setting: {setting}
+Character: {character}
+Genre: {genre}
+Return ONLY a JSON object with:
+- lore: brief world description
+- goal: main player objective
+- milestones: 2-4 key events (id, description)
+- endings: good/bad endings (id, type, condition, description)
+Translate the lore, goal, milestones and endings into
+a language of setting language.
+"""
+
+SCENE_PROMPT = """
+Using the provided lore and history, generate the next scene.
+Lore: {lore}
+Goal: {goal}
+Milestones: {milestones}
+Endings: {endings}
+History: {history}
+Last choice: {last_choice}
+The scene description must be 2-3 sentences and no more than 50 words.
+Each choice text must be concise, up to 7 words.
+Respond ONLY with JSON containing:
+- description: short summary of the scene
+- choices: exactly two dicts {{"text": ..., "next_scene_short_desc": ...}}
+Translate the scene description and choices into a language of lore language.
+"""
+
+ENDING_CHECK_PROMPT = """
+History: {history}
+Endings: {endings}
+Check if any ending conditions are met.
+If none are met return ending_reached: false.
+If an ending is reached return ending_reached: true and provide the
+ending object (id, type, description).
+Respond ONLY with JSON.
+"""

src/agent/runner.py

@@ -0,0 +1,67 @@
+"""Entry point for executing a graph step."""
+
+import logging
+from dataclasses import asdict
+from typing import Dict, Optional
+
+from agent.llm_graph import GraphState, llm_game_graph
+from agent.models import UserState
+from agent.state import get_user_state
+
+logger = logging.getLogger(__name__)
+
+
+async def process_step(
+    user_hash: str,
+    step: str,
+    setting: Optional[str] = None,
+    character: Optional[dict] = None,
+    genre: Optional[str] = None,
+    choice_text: Optional[str] = None,
+) -> Dict:
+    """Run one interaction step through the graph."""
+    logger.info("[Runner] Step %s for user %s", step, user_hash)
+
+    graph_state = GraphState(user_hash=user_hash, step=step)
+    if step == "start":
+        assert setting and character and genre, "Missing start parameters"
+        graph_state.setting = setting
+        graph_state.character = character
+        graph_state.genre = genre
+    elif step == "choose":
+        assert choice_text, "choice_text is required"
+        graph_state.choice_text = choice_text
+
+    final_state = await llm_game_graph.ainvoke(asdict(graph_state))
+
+    user_state: UserState = get_user_state(user_hash)
+    response: Dict = {}
+
+    ending = final_state.get("ending")
+    if ending and ending.get("ending_reached"):
+        ending_info = ending["ending"]
+        if (
+            ("description" not in ending_info
+                or not ending_info["description"])
+            and user_state.story_frame
+        ):
+            for e in user_state.story_frame.endings:
+                if e.id == ending_info.get("id"):
+                    ending_info["description"] = e.description
+                    break
+        response["ending"] = ending_info
+        response["game_over"] = True
+    else:
+        if (
+            user_state.current_scene_id
+            and user_state.current_scene_id in user_state.scenes
+        ):
+            current_scene = user_state.scenes[
+                user_state.current_scene_id
+            ].dict()
+        else:
+            current_scene = final_state.get("scene")
+        response["scene"] = current_scene
+        response["game_over"] = False
+
+    return response

src/agent/state.py

@@ -0,0 +1,24 @@
+"""Simple in-memory user state storage."""
+
+from typing import Dict
+
+from agent.models import UserState
+
+_USER_STATE: Dict[str, UserState] = {}
+
+
+def get_user_state(user_hash: str) -> UserState:
+    """Return user state for the given id, creating it if necessary."""
+    if user_hash not in _USER_STATE:
+        _USER_STATE[user_hash] = UserState()
+    return _USER_STATE[user_hash]
+
+
+def set_user_state(user_hash: str, state: UserState) -> None:
+    """Persist updated user state."""
+    _USER_STATE[user_hash] = state
+
+
+def reset_user_state(user_hash: str) -> None:
+    """Reset stored state for a user."""
+    _USER_STATE[user_hash] = UserState()

src/agent/tools.py

@@ -0,0 +1,171 @@
+"""LLM tools used by the game graph."""
+
+import logging
+import uuid
+from typing import Annotated, Dict
+
+from langchain_core.tools import tool
+
+from agent.llm import create_llm
+from agent.models import (
+    EndingCheckResult,
+    Scene,
+    SceneChoice,
+    SceneLLM,
+    StoryFrame,
+    StoryFrameLLM,
+    UserChoice,
+)
+from agent.prompts import ENDING_CHECK_PROMPT, SCENE_PROMPT, STORY_FRAME_PROMPT
+from agent.state import get_user_state, set_user_state
+from images.image_generator import modify_image, generate_image
+from agent.image_agent import ChangeScene
+
+logger = logging.getLogger(__name__)
+
+
+def _err(msg: str) -> str:
+    logger.error(msg)
+    return f"{{'error': '{msg}'}}"
+
+
+@tool
+async def generate_story_frame(
+    user_hash: Annotated[str, "User session ID"],
+    setting: Annotated[str, "Game world setting"],
+    character: Annotated[Dict[str, str], "Character info"],
+    genre: Annotated[str, "Genre"],
+) -> Annotated[Dict, "Generated story frame"]:
+    """Create the initial story frame and store it in user state."""
+    llm = create_llm().with_structured_output(StoryFrameLLM)
+    prompt = STORY_FRAME_PROMPT.format(
+        setting=setting,
+        character=character,
+        genre=genre,
+    )
+    resp: StoryFrameLLM = await llm.ainvoke(prompt)
+    story_frame = StoryFrame(
+        lore=resp.lore,
+        goal=resp.goal,
+        milestones=resp.milestones,
+        endings=resp.endings,
+        setting=setting,
+        character=character,
+        genre=genre,
+    )
+    state = get_user_state(user_hash)
+    state.story_frame = story_frame
+    set_user_state(user_hash, state)
+    return story_frame.dict()
+
+
+@tool
+async def generate_scene(
+    user_hash: Annotated[str, "User session ID"],
+    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)
+    if not state.story_frame:
+        return _err("Story frame not initialized")
+    llm = create_llm().with_structured_output(SceneLLM)
+    prompt = SCENE_PROMPT.format(
+        lore=state.story_frame.lore,
+        goal=state.story_frame.goal,
+        milestones=",".join(m.id for m in state.story_frame.milestones),
+        endings=",".join(e.id for e in state.story_frame.endings),
+        history="; ".join(f"{c.scene_id}:{c.choice_text}" for c in state.user_choices),
+        last_choice=last_choice,
+    )
+    resp: SceneLLM = await llm.ainvoke(prompt)
+    if len(resp.choices) < 2:
+        resp = await llm.ainvoke(
+            prompt + "\nThe scene must contain exactly two choices."
+        )
+    scene_id = str(uuid.uuid4())
+    choices = [
+        SceneChoice(**ch.model_dump())
+        if hasattr(ch, "model_dump")
+        else SceneChoice(**ch)
+        for ch in resp.choices[:2]
+    ]
+    scene = Scene(
+        scene_id=scene_id,
+        description=resp.description,
+        choices=choices,
+        image=None,
+        music=None,
+    )
+    state.current_scene_id = scene_id
+    state.scenes[scene_id] = scene
+    set_user_state(user_hash, state)
+    return scene.dict()
+
+
+@tool
+async def generate_scene_image(
+    user_hash: Annotated[str, "User session ID"],
+    scene_id: Annotated[str, "Scene ID"],
+    change_scene: Annotated[ChangeScene, "Prompt for image generation"],
+    current_image: Annotated[str, "Current image"] | None = None,
+) -> Annotated[str, "Path to generated image"]:
+    """Generate an image for a scene and save the path in the state."""
+    try:
+        image_path = current_image
+        if change_scene.change_scene == "change_completely" or change_scene.change_scene == "modify":
+            image_path, _ = await (
+                generate_image(change_scene.scene_description)
+                if current_image is None
+                # 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)
+        if scene_id in state.scenes:
+            state.scenes[scene_id].image = image_path
+        set_user_state(user_hash, state)
+        return image_path
+    except Exception as exc:  # noqa: BLE001
+        return _err(str(exc))
+
+
+@tool
+async def update_state_with_choice(
+    user_hash: Annotated[str, "User session ID"],
+    scene_id: Annotated[str, "Scene ID"],
+    choice_text: Annotated[str, "Chosen option"],
+) -> Annotated[Dict, "Updated state"]:
+    """Record the player's choice in the state."""
+    import datetime
+
+    state = get_user_state(user_hash)
+    state.user_choices.append(
+        UserChoice(
+            scene_id=scene_id,
+            choice_text=choice_text,
+            timestamp=datetime.datetime.utcnow().isoformat(),
+        )
+    )
+    set_user_state(user_hash, state)
+    return state.dict()
+
+
+@tool
+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)
+    if not state.story_frame:
+        return _err("No story frame")
+    llm = create_llm().with_structured_output(EndingCheckResult)
+    history = "; ".join(f"{c.scene_id}:{c.choice_text}" for c in state.user_choices)
+    prompt = ENDING_CHECK_PROMPT.format(
+        history=history,
+        endings=",".join(f"{e.id}:{e.condition}" for e in state.story_frame.endings),
+    )
+    resp: EndingCheckResult = await llm.ainvoke(prompt)
+    if resp.ending_reached and resp.ending:
+        state.ending = resp.ending
+        set_user_state(user_hash, state)
+        return {"ending_reached": True, "ending": resp.ending.dict()}
+    return {"ending_reached": False}

src/audio/audio_generator.py

@@ -0,0 +1,120 @@
+import asyncio
+from google import genai
+from google.genai import types
+from config import settings
+import wave
+import queue
+import logging
+import io
+import time
+
+logger = logging.getLogger(__name__)
+
+client = genai.Client(api_key=settings.gemini_api_key.get_secret_value(), http_options={'api_version': 'v1alpha'})
+
+async def generate_music(user_hash: str, music_tone: str, receive_audio):
+    if user_hash in sessions:
+        return
+    async with (
+        client.aio.live.music.connect(model='models/lyria-realtime-exp') as session,
+        asyncio.TaskGroup() as tg,
+    ):
+        # Set up task to receive server messages.
+        tg.create_task(receive_audio(session, user_hash))
+
+        # Send initial prompts and config
+        await session.set_weighted_prompts(
+          prompts=[
+            types.WeightedPrompt(text=music_tone, weight=1.0),
+          ]
+        )
+        await session.set_music_generation_config(
+          config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
+        )
+        await session.play()
+        logger.info(f"Started music generation for user hash {user_hash}, music tone: {music_tone}")
+        sessions[user_hash] = {
+            'session': session,
+            'queue': queue.Queue()
+        }
+        
+async def change_music_tone(user_hash: str, new_tone):
+    logger.info(f"Changing music tone to {new_tone}")
+    session = sessions.get(user_hash, {}).get('session')
+    if not session:
+        logger.error(f"No session found for user hash {user_hash}")
+        return
+    await session.set_weighted_prompts(
+        prompts=[types.WeightedPrompt(text=new_tone, weight=1.0)]
+    )
+        
+
+SAMPLE_RATE = 48000
+NUM_CHANNELS = 2  # Stereo
+SAMPLE_WIDTH = 2  # 16-bit audio -> 2 bytes per sample
+
+async def receive_audio(session, user_hash):
+    """Process incoming audio from the music generation."""
+    while True:
+        try:
+            async for message in session.receive():
+                if message.server_content and message.server_content.audio_chunks:
+                    audio_data = message.server_content.audio_chunks[0].data
+                    queue = sessions[user_hash]['queue']
+                    # audio_data is already bytes (raw PCM)
+                    await asyncio.to_thread(queue.put, audio_data)
+                await asyncio.sleep(10**-12)
+        except Exception as e:
+            logger.error(f"Error in receive_audio: {e}")
+            break
+
+sessions = {}
+
+async def start_music_generation(user_hash: str, music_tone: str):
+    """Start the music generation in a separate thread."""
+    await generate_music(user_hash, music_tone, receive_audio)
+    
+async def cleanup_music_session(user_hash: str):
+    if user_hash in sessions:
+        logger.info(f"Cleaning up music session for user hash {user_hash}")
+        session = sessions[user_hash]['session']
+        await session.stop()
+        await session.close()
+        del sessions[user_hash]
+    
+
+def update_audio(user_hash):
+    """Continuously stream audio from the queue as WAV bytes."""
+    while True:
+        if user_hash not in sessions:
+            time.sleep(0.5)
+            continue
+        queue = sessions[user_hash]['queue']
+        pcm_data = queue.get() # This is raw PCM audio bytes
+        
+        if not isinstance(pcm_data, bytes):
+            logger.warning(f"Expected bytes from audio_queue, got {type(pcm_data)}. Skipping.")
+            continue
+
+        # Lyria provides stereo, 16-bit PCM at 48kHz.
+        # Ensure the number of bytes is consistent with stereo 16-bit audio.
+        # Each frame = NUM_CHANNELS * SAMPLE_WIDTH bytes.
+        # If len(pcm_data) is not a multiple of (NUM_CHANNELS * SAMPLE_WIDTH), 
+        # it might indicate an incomplete chunk or an issue.
+        bytes_per_frame = NUM_CHANNELS * SAMPLE_WIDTH
+        if len(pcm_data) % bytes_per_frame != 0:
+            logger.warning(
+                f"Received PCM data with length {len(pcm_data)}, which is not a multiple of "
+                f"bytes_per_frame ({bytes_per_frame}). This might cause issues with WAV formatting."
+            )
+            # Depending on strictness, you might want to skip this chunk:
+            # continue 
+
+        wav_buffer = io.BytesIO()
+        with wave.open(wav_buffer, 'wb') as wf:
+            wf.setnchannels(NUM_CHANNELS)
+            wf.setsampwidth(SAMPLE_WIDTH) # Corresponds to 16-bit audio
+            wf.setframerate(SAMPLE_RATE)
+            wf.writeframes(pcm_data)
+        wav_bytes = wav_buffer.getvalue()
+        yield wav_bytes

src/config.py

@@ -0,0 +1,34 @@
+from dotenv import load_dotenv
+from pydantic_settings import BaseSettings
+import logging
+from pydantic import SecretStr
+
+load_dotenv()
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(levelname)s:\t%(asctime)s [%(name)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S %z",
+)
+
+
+class BaseAppSettings(BaseSettings):
+    """Base settings class with common configuration."""
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        extra = "ignore"
+
+
+class AppSettings(BaseAppSettings):
+    gemini_api_key: SecretStr
+    gemini_api_keys: SecretStr
+    # assistant_api_key: SecretStr
+    top_p: float = 0.95
+    temperature: float = 0.5
+    pregenerate_next_scene: bool = True
+    
+
+settings = AppSettings()

src/css.py

@@ -0,0 +1,155 @@
+# Custom CSS for fullscreen image with overlay
+custom_css = """
+/* Make the image container fullscreen */
+.image-container {
+    position: fixed !important;
+    top: 0 !important;
+    left: 0 !important;
+    width: 100vw !important;
+    height: 100vh !important;
+    z-index: 1 !important;
+}
+
+.image-container img {
+    width: 100vw !important;
+    height: 100vh !important;
+    object-fit: cover !important;
+}
+
+/* Style the overlay content */
+.overlay-content {
+    position: fixed !important;
+    bottom: 0 !important;
+    left: 0 !important;
+    right: 0 !important;
+    background: linear-gradient(transparent, rgba(0,0,0,0.8)) !important;
+    padding: 40px 20px 20px !important;
+    z-index: 10 !important;
+    color: white !important;
+}
+
+/* Style the narrative text */
+.narrative-text {
+    background: rgba(0,0,0,0.7) !important;
+    border: none !important;
+    color: white !important;
+    font-size: 15px !important;
+    line-height: 1.5 !important;
+    padding: 10px !important;
+    border-radius: 10px !important;
+    margin-bottom: 10px !important;
+}
+
+img {
+    pointer-events: none;
+}
+
+.narrative-text textarea {
+    background: transparent !important;
+    border: none !important;
+    color: white !important;
+    -webkit-text-fill-color: white !important;
+    font-size: 15px !important;
+    resize: none !important;
+}
+
+/* Style the choice buttons */
+.choice-buttons {
+    background: rgba(0,0,0,0.7) !important;
+    border-radius: 10px !important;
+    padding: 10px !important;
+}
+
+.choice-buttons label {
+    color: white !important;
+    font-size: 14px !important;
+}
+
+/* Fix radio button backgrounds */
+.choice-buttons input[type="radio"] {
+    background: transparent !important;
+    border: 2px solid white !important;
+}
+
+.choice-buttons input[type="radio"]:checked {
+    background: white !important;
+}
+
+.choice-buttons .form-radio {
+    background: transparent !important;
+}
+
+/* Style radio button containers */
+.choice-buttons > div {
+    background: transparent !important;
+}
+
+.choice-buttons fieldset {
+    background: transparent !important;
+    border: none !important;
+}
+
+/* Remove any remaining white backgrounds */
+.choice-buttons * {
+    background-color: transparent !important;
+}
+
+.choice-buttons input {
+    background-color: transparent !important;
+    border: 1px solid rgba(255,255,255,0.5) !important;
+    color: white !important;
+}
+
+.choice-buttons label span {
+    color: white !important;
+}
+
+/* Hide gradio header and footer */
+.gradio-header, .gradio-footer {
+    display: none !important;
+}
+
+/* Hide image control buttons using correct DOM selector */
+.image-container .icon-button-wrapper {
+    display: none !important;
+}
+
+.image-container .icon-buttons {
+    display: none !important;
+}
+
+/* Position the back button in the top-right corner */
+#back-btn {
+    position: fixed !important;
+    top: 10px !important;
+    right: 10px !important;
+    z-index: 20 !important;
+}
+
+/* Make form element transparent */
+.overlay-content .form {
+    background: transparent !important;
+}
+"""
+
+# CSS for the loading indicator
+loading_css_styles = """
+#loading-indicator {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background-color: rgba(0, 0, 0, 0.8); /* Semi-transparent black */
+    /* When Gradio makes this gr.Column visible, it will set display:flex !important; (or similar). */
+    /* These properties will then apply to center the content of the Column: */
+    justify-content: center;
+    align-items: center;
+    z-index: 9999; /* Ensure it's on top */
+}
+#loading-indicator .loading-text { /* Style for the text inside */
+    color: white;
+    font-size: 2em;
+    text-align: center;
+}
+"""

src/game_constructor.py

@@ -0,0 +1,174 @@
+import gradio as gr
+import json
+import uuid
+from game_setting import Character, GameSetting, get_user_story
+from game_state import story, state, get_current_scene
+from agent.llm_agent import process_user_input
+from images.image_generator import generate_image
+from game_setting import Character, GameSetting
+from agent.runner import process_step
+from audio.audio_generator import start_music_generation
+import asyncio
+from config import settings
+
+
+# Predefined suggestions for demo
+SETTING_SUGGESTIONS = [
+    "A mystical forest shrouded in eternal twilight, where ancient trees whisper secrets and magical creatures roam freely",
+    "A sprawling cyberpunk metropolis in 2099, where neon lights illuminate towering skyscrapers and technology controls every aspect of life",
+    "A Victorian-era mansion on a remote cliff, filled with hidden passages, antique furniture, and an atmosphere of dark mysteries",
+    "A post-apocalyptic wasteland where survivors struggle to rebuild civilization among the ruins of the old world",
+    "A magical academy floating in the clouds, where young wizards learn to master their powers and uncover ancient spells",
+]
+
+CHARACTER_SUGGESTIONS = [
+    {
+        "name": "Elena Nightwhisper",
+        "age": "25",
+        "background": "A skilled detective with supernatural intuition, haunted by visions of crimes before they happen",
+        "personality": "Determined, intuitive, struggles with self-doubt but fiercely protective of the innocent",
+    },
+    {
+        "name": "Marcus Steelborn",
+        "age": "32",
+        "background": "A former soldier turned cybernetic engineer in a dystopian future, seeking to expose corporate corruption",
+        "personality": "Brave, tech-savvy, has trust issues but deeply loyal to those who earn his respect",
+    },
+    {
+        "name": "Aria Moonstone",
+        "age": "19",
+        "background": "A young witch discovering her powers while attending a prestigious magical academy",
+        "personality": "Curious, ambitious, sometimes reckless but has a good heart and strong sense of justice",
+    },
+    {
+        "name": "Dr. Victoria Blackthorne",
+        "age": "45",
+        "background": "A renowned archaeologist who specializes in occult artifacts and ancient mysteries",
+        "personality": "Intelligent, sophisticated, perfectionist with a hidden romantic side",
+    },
+]
+
+GENRE_OPTIONS = [
+    "Horror - Supernatural terror and psychological thrills",
+    "Detective/Mystery - Crime solving and investigation",
+    "Romance - Love stories and relationship drama",
+    "Fantasy - Magic and mythical creatures",
+    "Sci-Fi - Futuristic technology and space exploration",
+    "Adventure - Action-packed journeys and quests",
+    "Psychological Thriller - Mind games and suspense",
+    "Historical Fiction - Stories set in past eras",
+]
+
+
+def load_setting_suggestion(suggestion: str):
+    """Load a predefined setting suggestion"""
+    return suggestion
+
+
+def load_character_suggestion(character_name: str):
+    """Load a predefined character suggestion"""
+    if character_name == "None":
+        return "", "", "", ""
+
+    for char in CHARACTER_SUGGESTIONS:
+        if char["name"] in character_name:
+            return char["name"], char["age"], char["background"], char["personality"]
+    return "", "", "", ""
+
+
+def save_game_config(
+    setting_desc: str,
+    char_name: str,
+    char_age: str,
+    char_background: str,
+    char_personality: str,
+    genre: str,
+):
+    """Save the game configuration to a JSON file"""
+    if not all(
+        [setting_desc, char_name, char_age, char_background, char_personality, genre]
+    ):
+        return "❌ Please fill in all fields before saving."
+
+    config = {
+        "id": str(uuid.uuid4()),
+        "setting": {"description": setting_desc},
+        "character": {
+            "name": char_name,
+            "age": char_age,
+            "background": char_background,
+            "personality": char_personality,
+        },
+        "genre": genre,
+        "created_at": str(uuid.uuid4()),  # In real app, would use actual timestamp
+    }
+
+    try:
+        filename = f"game_config_{config['id'][:8]}.json"
+        with open(f"generated/{filename}", "w") as f:
+            json.dump(config, f, indent=2)
+        return f"✅ Game configuration saved as {filename}"
+    except Exception as e:
+        return f"❌ Error saving configuration: {str(e)}"
+
+
+async def start_game_with_settings(
+    user_hash: str,
+    setting_desc: str,
+    char_name: str,
+    char_age: str,
+    char_background: str,
+    char_personality: str,
+    genre: str,
+):
+    """Initialize the game with custom settings and switch to game interface"""
+    if not all(
+        [setting_desc, char_name, char_age, char_background, char_personality, genre]
+    ):
+        return (
+            gr.update(visible=True),  # constructor_interface
+            gr.update(visible=False),  # loading indicator
+            gr.update(visible=False),  # game_interface
+            gr.update(
+                value="❌ Please fill in all fields before starting the game.",
+                visible=True,
+            ),  # error_message
+            gr.update(),
+            gr.update(),
+            gr.update(),  # game components unchanged
+        )
+
+    character = Character(
+        name=char_name,
+        age=char_age,
+        background=char_background,
+        personality=char_personality,
+    )
+
+    game_setting = GameSetting(character=character, setting=setting_desc, genre=genre)
+    
+    asyncio.create_task(start_music_generation(user_hash, "neutral"))
+
+    # Запускаем LLM-граф для инициализации истории
+    result = await process_step(
+        user_hash=user_hash,
+        step="start",
+        setting=game_setting.setting,
+        character=game_setting.character.model_dump(),
+        genre=game_setting.genre,
+    )
+
+    scene = result["scene"]
+    scene_text = scene["description"]
+    scene_image = scene.get("image", "")
+    scene_choices = [ch["text"] for ch in scene.get("choices", [])]
+
+    return (
+        gr.update(visible=False),  # loading indicator
+        gr.update(visible=False),  # constructor_interface
+        gr.update(visible=True),  # game_interface
+        gr.update(visible=False),  # error_message
+        gr.update(value=scene_text),  # game_text
+        gr.update(value=scene_image),  # game_image
+        gr.update(choices=scene_choices, value=None),  # game_choices
+    )

src/game_setting.py

@@ -0,0 +1,25 @@
+from pydantic import BaseModel
+
+
+class Character(BaseModel):
+    name: str
+    age: str
+    background: str
+    personality: str
+
+
+class GameSetting(BaseModel):
+    character: Character
+    setting: str
+    genre: str
+
+
+def get_user_story(
+    scene_description: str, scene_image_description: str, user_choice: str
+) -> str:
+    return f"""Current scene description:
+            {scene_description}
+            Current scene image description: {scene_image_description}
+            
+            User's choice: {user_choice}
+        """

src/game_state.py

@@ -0,0 +1,15 @@
+story = {
+    "start": {
+        "text": "You wake up in a mysterious forest. What do you do?",
+        "image": "forest.jpg",
+        "choices": {"Explore": None, "Wait": None},
+        "music_tone": "neutral",
+        "img_description": "forest in the fog",
+    },
+}
+
+state = {"scene": "start"}
+
+def get_current_scene():
+    scene = story[state["scene"]]
+    return scene["text"], scene["image"], scene["choices"].keys()

src/images/image_generator.py

@@ -0,0 +1,166 @@
+from google import genai
+from google.genai import types
+import os
+from PIL import Image
+from io import BytesIO
+from datetime import datetime
+from config import settings
+import logging
+import asyncio
+import gradio as gr
+
+logger = logging.getLogger(__name__)
+
+client = genai.Client(api_key=settings.gemini_api_key.get_secret_value()).aio
+
+safety_settings = [
+    types.SafetySetting(
+        category="HARM_CATEGORY_HARASSMENT",
+        threshold="BLOCK_NONE",  # Block none
+    ),
+    types.SafetySetting(
+        category="HARM_CATEGORY_HATE_SPEECH",
+        threshold="BLOCK_NONE",  # Block none
+    ),
+    types.SafetySetting(
+        category="HARM_CATEGORY_SEXUALLY_EXPLICIT",
+        threshold="BLOCK_NONE",  # Block none
+    ),
+    types.SafetySetting(
+        category="HARM_CATEGORY_DANGEROUS_CONTENT",
+        threshold="BLOCK_NONE",  # Block none
+    ),
+]
+
+
+async def generate_image(prompt: str) -> tuple[str, str] | None:
+    """
+    Generate an image using Google's Gemini model and save it to generated/images directory.
+
+    Args:
+        prompt (str): The text prompt to generate the image from
+
+    Returns:
+        str: Path to the generated image file, or None if generation failed
+    """
+    # Ensure the generated/images directory exists
+    output_dir = "generated/images"
+    os.makedirs(output_dir, exist_ok=True)
+
+    logger.info(f"Generating image with prompt: {prompt}")
+
+    try:
+        response = await client.models.generate_content(
+            model="gemini-2.0-flash-preview-image-generation",
+            contents=prompt,
+            config=types.GenerateContentConfig(
+                response_modalities=["TEXT", "IMAGE"],
+                safety_settings=safety_settings,
+            ),
+        )
+
+        # Process the response parts
+        image_saved = False
+        for part in response.candidates[0].content.parts:
+            if part.inline_data is not None:
+                # Create a filename with timestamp
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                filename = f"gemini_{timestamp}.png"
+                filepath = os.path.join(output_dir, filename)
+
+                # Save the image
+                image = Image.open(BytesIO(part.inline_data.data))
+                await asyncio.to_thread(image.save, filepath, "PNG")
+                logger.info(f"Image saved to: {filepath}")
+                image_saved = True
+
+                return filepath, prompt
+
+        if not image_saved:
+            gr.Warning("Image was censored by Google!")
+            logger.error("No image was generated in the response.")
+            return None, None
+
+    except Exception as e:
+        logger.error(f"Error generating image: {e}")
+        return None, None
+
+
+async def modify_image(image_path: str, modification_prompt: str) -> str | None:
+    """
+    Modify an existing image using Google's Gemini model based on a text prompt.
+
+    Args:
+        image_path (str): Path to the existing image file
+        modification_prompt (str): The text prompt describing how to modify the image
+
+    Returns:
+        str: Path to the modified image file, or None if modification failed
+    """
+    # Ensure the generated/images directory exists
+    output_dir = "generated/images"
+    os.makedirs(output_dir, exist_ok=True)
+
+    logger.info(f"Modifying current scene image with prompt: {modification_prompt}")
+
+    # Check if the input image exists
+    if not os.path.exists(image_path):
+        logger.error(f"Error: Image file not found at {image_path}")
+        return None
+
+    key = settings.gemini_api_key.get_secret_value()
+
+    client = genai.Client(api_key=key).aio
+
+    try:
+        # Load the input image
+        input_image = Image.open(image_path)
+
+        # Make the API call with both text and image
+        response = await client.models.generate_content(
+            model="gemini-2.0-flash-preview-image-generation",
+            contents=[modification_prompt, input_image],
+            config=types.GenerateContentConfig(
+                response_modalities=["TEXT", "IMAGE"],
+                safety_settings=safety_settings,
+            ),
+        )
+
+        # Process the response parts
+        image_saved = False
+        for part in response.candidates[0].content.parts:
+            if part.inline_data is not None:
+                # Create a filename with timestamp
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                filename = f"gemini_modified_{timestamp}.png"
+                filepath = os.path.join(output_dir, filename)
+
+                # Save the modified image
+                modified_image = Image.open(BytesIO(part.inline_data.data))
+                await asyncio.to_thread(modified_image.save, filepath, "PNG")
+                logger.info(f"Modified image saved to: {filepath}")
+                image_saved = True
+
+                return filepath, modification_prompt
+
+        if not image_saved:
+            gr.Warning("Updated image was censored by Google!")
+            logger.error("No modified image was generated in the response.")
+            return None, None
+
+    except Exception as e:
+        logger.error(f"Error modifying image: {e}")
+        return None, None
+
+
+if __name__ == "__main__":
+    # Example usage
+    sample_prompt = "A Luke Skywalker half height sprite with white background for visual novel game"
+    generated_image_path = generate_image(sample_prompt)
+
+    # if generated_image_path:
+    #     # Example modification
+    #     modification_prompt = "Now the house is destroyed, and the jawas are running away"
+    #     modified_image_path = modify_image(generated_image_path, modification_prompt)
+    #     if modified_image_path:
+    #         print(f"Successfully modified image: {modified_image_path}")

src/main.py

@@ -0,0 +1,347 @@
+import gradio as gr
+from css import custom_css, loading_css_styles
+from audio.audio_generator import (
+    update_audio,
+    cleanup_music_session,
+)
+import logging
+from agent.llm_agent import process_user_input
+from images.image_generator import modify_image
+from agent.runner import process_step
+import uuid
+from game_constructor import (
+    SETTING_SUGGESTIONS,
+    CHARACTER_SUGGESTIONS,
+    GENRE_OPTIONS,
+    load_setting_suggestion,
+    load_character_suggestion,
+    start_game_with_settings,
+)
+import asyncio
+from game_setting import get_user_story
+from config import settings
+
+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
+
+    reset_user_state(user_hash)
+    await cleanup_music_session(user_hash)
+    # Generate a new hash to avoid stale state
+    new_hash = str(uuid.uuid4())
+    return (
+        gr.update(visible=False),  # loading_indicator
+        gr.update(visible=True),  # constructor_interface
+        gr.update(visible=False),  # game_interface
+        gr.update(visible=False),  # error_message
+        gr.update(value=new_hash),  # local_storage
+    )
+
+
+async def update_scene(user_hash: str, choice):
+    logger.info(f"Updating scene with choice: {choice}")
+    if not isinstance(choice, str):
+        return gr.update(), gr.update(), gr.update()
+
+    result = await process_step(
+        user_hash=user_hash,
+        step="choose",
+        choice_text=choice,
+    )
+
+    if result.get("game_over"):
+        ending = result["ending"]
+        ending_text = ending.get("description") or ending.get("condition", "")
+        return (
+            gr.update(value=ending_text),
+            gr.update(value=None),
+            gr.Radio(choices=[], label="", value=None),
+        )
+
+    scene = result["scene"]
+    return (
+        scene["description"],
+        scene.get("image", ""),
+        gr.Radio(
+            choices=[ch["text"] for ch in scene.get("choices", [])],
+            label="What do you choose?",
+            value=None,
+            elem_classes=["choice-buttons"],
+        ),
+    )
+
+
+def update_preview(setting, name, age, background, personality, genre):
+    """Update the configuration preview"""
+    if not any([setting, name, age, background, personality]):
+        return "Fill in the fields to see a preview..."
+
+    preview = f"""🌍 SETTING: {setting[:100]}{"..." if len(setting) > 100 else ""}
+
+👤 CHARACTER: {name} (Age: {age})
+📖 Background: {background}
+💭 Personality: {personality}
+
+🎭 GENRE: {genre}"""
+    return preview
+
+
+async def start_game_with_music(
+    user_hash: str,
+    setting_desc: str,
+    char_name: str,
+    char_age: str,
+    char_background: str,
+    char_personality: str,
+    genre: str,
+):
+    """Start the game with custom settings and initialize music"""
+    yield (
+        gr.update(visible=True),  # loading indicator
+        gr.update(),  # constructor_interface
+        gr.update(),  # game_interface
+        gr.update(),  # error_message
+        gr.update(),
+        gr.update(),
+        gr.update(),  # game components unchanged
+    )
+
+    # First, get the game interface updates
+    result = await start_game_with_settings(
+        user_hash,
+        setting_desc,
+        char_name,
+        char_age,
+        char_background,
+        char_personality,
+        genre,
+    )
+    yield result
+
+
+with gr.Blocks(
+    theme="soft",
+    title="Game Constructor & Visual Novel",
+    css=custom_css + loading_css_styles,
+) as demo:
+    # Fullscreen Loading Indicator (hidden by default)
+    with gr.Column(visible=False, elem_id="loading-indicator") as loading_indicator:
+        gr.HTML("<div class='loading-text'>🚀 Starting your adventure...</div>")
+
+    local_storage = gr.BrowserState(str(uuid.uuid4()), "user_hash")
+
+    # Constructor Interface (visible by default)
+    with gr.Column(
+        visible=True, elem_id="constructor-interface"
+    ) as constructor_interface:
+        gr.Markdown("# 🎮 Interactive Game Constructor")
+        gr.Markdown(
+            "Create your own interactive story game by defining the setting, character, and genre!"
+        )
+
+        # Error message area
+        error_message = gr.Textbox(
+            label="⚠️ Error",
+            visible=False,
+            interactive=False,
+            elem_classes=["error-message"],
+        )
+
+        with gr.Row():
+            with gr.Column(scale=2):
+                # Setting Description Section
+                with gr.Group():
+                    gr.Markdown("## 🌍 Setting Description")
+                    setting_suggestions = gr.Dropdown(
+                        choices=["Select a suggestion..."] + SETTING_SUGGESTIONS,
+                        label="Quick Suggestions",
+                        value="Select a suggestion...",
+                        interactive=True,
+                    )
+                    setting_description = gr.Textbox(
+                        label="Describe your game setting",
+                        placeholder="Enter a detailed description of where your story takes place...",
+                        lines=4,
+                        max_lines=6,
+                    )
+
+                # Character Description Section
+                with gr.Group():
+                    gr.Markdown("## 👤 Character Description")
+                    character_suggestions = gr.Dropdown(
+                        choices=["None"]
+                        + [
+                            f"{char['name']} - {char['background'][:50]}..."
+                            for char in CHARACTER_SUGGESTIONS
+                        ],
+                        label="Character Templates",
+                        value="None",
+                        interactive=True,
+                    )
+
+                    with gr.Row():
+                        char_name = gr.Textbox(
+                            label="Character Name",
+                            placeholder="Enter character name...",
+                        )
+                        char_age = gr.Textbox(label="Age", placeholder="25")
+
+                    char_background = gr.Textbox(
+                        label="Background/Profession",
+                        placeholder="Describe your character's background, profession, or role...",
+                        lines=2,
+                    )
+                    char_personality = gr.Textbox(
+                        label="Personality & Traits",
+                        placeholder="Describe personality, quirks, motivations, fears...",
+                        lines=2,
+                    )
+
+                # Genre Selection Section
+                with gr.Group():
+                    gr.Markdown("## 🎭 Genre & Style")
+                    genre_selection = gr.Dropdown(
+                        choices=GENRE_OPTIONS,
+                        label="Choose your story genre",
+                        value=GENRE_OPTIONS[0],
+                        interactive=True,
+                    )
+
+            with gr.Column(scale=1):
+                # Preview Section
+                with gr.Group():
+                    gr.Markdown("## 📋 Configuration Preview")
+                    preview_box = gr.Textbox(
+                        label="Game Summary",
+                        lines=8,
+                        interactive=False,
+                        placeholder="Fill in the fields to see a preview...",
+                    )
+
+                with gr.Group():
+                    gr.Markdown("## 🎮 Ready to Play?")
+                    start_btn = gr.Button("▶️ Start Game", variant="primary", size="lg")
+
+    with gr.Column(visible=False, elem_id="game-interface") as game_interface:
+        gr.Markdown("# 🎮 Your Interactive Story")
+
+        with gr.Row():
+            gr.Markdown("### Playing your custom game!")
+        back_btn = gr.Button(
+            "⬅️ Back to Constructor",
+            variant="secondary",
+            elem_id="back-btn",
+        )
+
+        # Audio component for background music
+        audio_out = gr.Audio(
+            autoplay=True, streaming=True, interactive=False, visible=False
+        )
+
+        # Background image (fullscreen)
+        with gr.Column(elem_classes=["image-container"]):
+            game_image = gr.Image(type="filepath", interactive=False, show_label=False)
+
+        # Overlay content (text and buttons)
+        with gr.Column(elem_classes=["overlay-content"]):
+            game_text = gr.Textbox(
+                label="",
+                interactive=False,
+                show_label=False,
+                elem_classes=["narrative-text"],
+                lines=3,
+            )
+            game_choices = gr.Radio(
+                choices=[],
+                label="What do you choose?",
+                value=None,
+                elem_classes=["choice-buttons"],
+            )
+
+    # Event handlers for constructor interface
+    setting_suggestions.change(
+        fn=load_setting_suggestion,
+        inputs=[setting_suggestions],
+        outputs=[setting_description],
+    )
+
+    character_suggestions.change(
+        fn=load_character_suggestion,
+        inputs=[character_suggestions],
+        outputs=[char_name, char_age, char_background, char_personality],
+    )
+
+    # Update preview when any field changes
+    for component in [
+        setting_description,
+        char_name,
+        char_age,
+        char_background,
+        char_personality,
+        genre_selection,
+    ]:
+        component.change(
+            fn=update_preview,
+            inputs=[
+                setting_description,
+                char_name,
+                char_age,
+                char_background,
+                char_personality,
+                genre_selection,
+            ],
+            outputs=[preview_box],
+        )
+
+    # Interface switching handlers
+    start_btn.click(
+        fn=start_game_with_music,
+        inputs=[
+            local_storage,
+            setting_description,
+            char_name,
+            char_age,
+            char_background,
+            char_personality,
+            genre_selection,
+        ],
+        outputs=[
+            loading_indicator,
+            constructor_interface,
+            game_interface,
+            error_message,
+            game_text,
+            game_image,
+            game_choices,
+        ],
+    )
+
+    back_btn.click(
+        fn=return_to_constructor,
+        inputs=[local_storage],
+        outputs=[
+            loading_indicator,
+            constructor_interface,
+            game_interface,
+            error_message,
+            local_storage,
+        ],
+    )
+
+    game_choices.change(
+        fn=update_scene,
+        inputs=[local_storage, game_choices],
+        outputs=[game_text, game_image, game_choices],
+    )
+
+    demo.unload(cleanup_music_session)
+    demo.load(
+        fn=update_audio,
+        inputs=[local_storage],
+        outputs=[audio_out],
+    )
+
+demo.launch(ssr_mode=False)