refactor(config): centralize scenario configuration defaults

README.md

@@ -165,19 +165,6 @@ Prompts for every stage live in `prompts.yaml`, making it easy to retune instruc
 - [uv](https://github.com/astral-sh/uv) (optional but fastest)
 - HuggingFace API token with access to the OpenAI-compatible inference endpoint (set as `HF_TOKEN`)
 
-### Installation
-
-```bash
-# Clone
-git clone https://github.com/ArkaiAriza/fire-rescue-mcp.git
-cd fire-rescue-mcp
-
-# Install deps (recommended)
-uv sync
-# or fall back to pip
-pip install -e .
-```
-
 ### Environment Variables
 
 ```bash

app.py

@@ -11,6 +11,7 @@ import uuid
 import gradio as gr
 from typing import Optional
 
+from config import SCENARIO_DEFAULTS
 from service import (
     ADVISOR_MODEL_CHOICES,
     DEFAULT_ADVISOR_MODEL_CHOICE,
@@ -800,7 +801,7 @@ def deploy_at_cell(
             _get_combined_advisor_messages(service),
             service.get_event_log_text(),
             render_status_html(state, is_thinking, thinking_stage),
-        ] + updates
+        ] + updates + [service, display_cache]
     
     # Handle fire placement
     if selection == "🔥 Fire":
@@ -890,14 +891,19 @@ def refresh_display(
     thinking_stage = service.get_thinking_stage()
     
     # Freeze background UI once a win/lose overlay has already been shown
+    # but still allow the final tick (when the overlay first appears) to push
+    # its grid updates so the user sees the true end state.
     overlay_state = changes.get("result_state", "")
-    freeze_background = bool(overlay_state)
-    if freeze_background:
-        if display_cache["result_freeze_state"] != overlay_state:
-            display_cache["result_freeze_state"] = overlay_state
-    elif display_cache["result_freeze_state"]:
+    cached_overlay_state = display_cache["result_freeze_state"]
+    overlay_first_tick = bool(overlay_state) and not cached_overlay_state
+    
+    if overlay_state:
+        display_cache["result_freeze_state"] = overlay_state
+    elif cached_overlay_state:
         display_cache["result_freeze_state"] = ""
     
+    freeze_background = bool(display_cache["result_freeze_state"]) and not overlay_first_tick
+    
     # Timer control - stop when game ends
     timer_update = gr.update()
     if status in ["success", "fail"]:
@@ -1847,29 +1853,45 @@ def create_app() -> gr.Blocks:
         with gr.Accordion("⚙️ Settings & Controls", open=False):
             with gr.Row():
                 with gr.Column(scale=1):
+                    fire_count_defaults = SCENARIO_DEFAULTS["fire_count"]
                     fire_count = gr.Slider(
-                        minimum=1, maximum=40, value=20, step=1,
+                        minimum=fire_count_defaults.minimum,
+                        maximum=fire_count_defaults.maximum,
+                        value=fire_count_defaults.value,
+                        step=fire_count_defaults.step,
                         label="🔥 Initial Fire Count",
-                        info="Number of fire starting points (1-25)"
+                        info="Number of fire starting points"
                     )
                 with gr.Column(scale=1):
+                    fire_intensity_defaults = SCENARIO_DEFAULTS["fire_intensity"]
                     fire_intensity = gr.Slider(
-                        minimum=0.2, maximum=0.9, value=0.6, step=0.05,
+                        minimum=fire_intensity_defaults.minimum,
+                        maximum=fire_intensity_defaults.maximum,
+                        value=fire_intensity_defaults.value,
+                        step=fire_intensity_defaults.step,
                         label="🌡️ Fire Intensity",
-                        info="Initial fire strength (0.2-0.9)"
+                        info="Initial fire strength"
                     )
             with gr.Row():
                 with gr.Column(scale=1):
+                    building_count_defaults = SCENARIO_DEFAULTS["building_count"]
                     building_count = gr.Slider(
-                        minimum=1, maximum=35, value=20, step=1,
+                        minimum=building_count_defaults.minimum,
+                        maximum=building_count_defaults.maximum,
+                        value=building_count_defaults.value,
+                        step=building_count_defaults.step,
                         label="🏢 Building Count",
                         info="Number of buildings (connected cluster)"
                     )
                 with gr.Column(scale=1):
+                    max_units_defaults = SCENARIO_DEFAULTS["max_units"]
                     max_units = gr.Slider(
-                        minimum=1, maximum=20, value=10, step=1,
+                        minimum=max_units_defaults.minimum,
+                        maximum=max_units_defaults.maximum,
+                        value=max_units_defaults.value,
+                        step=max_units_defaults.step,
                         label="🚒 Max Units",
-                        info="Maximum deployable units (1-20)"
+                        info="Maximum deployable units"
                     )
             with gr.Row():
                 with gr.Column(scale=1):
@@ -2044,7 +2066,7 @@ def create_app() -> gr.Blocks:
         # Event handlers for grid buttons (click to place)
         for x, y, btn in grid_buttons:
             btn.click(
-                fn=lambda sel, _x=x, _y=y, svc=None, cache=None: deploy_at_cell(_x, _y, sel, svc, cache),
+                fn=lambda sel, svc, cache, _x=x, _y=y: deploy_at_cell(_x, _y, sel, svc, cache),
                 inputs=[place_selector, service_state, display_cache_state],
                 outputs=[result_popup, advisor_display, event_log_display, status_display] + all_buttons + [service_state, display_cache_state],
             )

config.py

@@ -0,0 +1,45 @@
+"""Centralized configuration defaults for scenario controls."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+
+@dataclass(frozen=True)
+class SliderDefaults:
+    """Slider configuration along with a helper to clamp values."""
+
+    minimum: float
+    maximum: float
+    value: float
+    step: float
+
+    def clamp(self, candidate: float) -> float:
+        """Clamp ``candidate`` to this slider's min/max bounds."""
+        return max(self.minimum, min(self.maximum, candidate))
+
+
+SCENARIO_DEFAULTS: Final[dict[str, SliderDefaults]] = {
+    "fire_count": SliderDefaults(minimum=1, maximum=40, value=20, step=1),
+    "fire_intensity": SliderDefaults(minimum=0.2, maximum=0.9, value=0.6, step=0.05),
+    "building_count": SliderDefaults(minimum=1, maximum=35, value=20, step=1),
+    "max_units": SliderDefaults(minimum=1, maximum=20, value=10, step=1),
+}
+
+
+def range_text(key: str) -> str:
+    """
+    Return a human-readable ``min-max`` string for any configured scenario slider.
+    Primarily used in docstrings / README notes to avoid diverging documentation.
+    """
+    defaults = SCENARIO_DEFAULTS[key]
+    step_value = float(defaults.step)
+    if step_value.is_integer():
+        min_val = int(defaults.minimum)
+        max_val = int(defaults.maximum)
+    else:
+        min_val = defaults.minimum
+        max_val = defaults.maximum
+    return f"{min_val}-{max_val}"
+

fire_rescue_mcp/mcp_server.py

@@ -28,6 +28,7 @@ from mcp.server.fastmcp import FastMCP
 # Add parent directory to path for imports
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
+from config import range_text
 from models import CellType, UnitType
 from simulation import SimulationEngine, SimulationConfig
 
@@ -49,6 +50,10 @@ def attach_engine(engine: SimulationEngine, session_id: str) -> None:
 # Unit effective ranges (matching SimulationConfig, Chebyshev/square distance)
 FIRE_TRUCK_RANGE = 1  # Square coverage radius (includes 8 neighbors)
 HELICOPTER_RANGE = 2  # Square coverage radius (extends two cells in all directions)
+FIRE_COUNT_RANGE_TEXT = range_text("fire_count")
+FIRE_INTENSITY_RANGE_TEXT = range_text("fire_intensity")
+BUILDING_COUNT_RANGE_TEXT = range_text("building_count")
+MAX_UNITS_RANGE_TEXT = range_text("max_units")
 
 
 def detach_engine(session_id: str) -> None:
@@ -175,15 +180,15 @@ def reset_scenario(
     max_units: int = 10,
     session_id: Optional[str] = None,
 ) -> dict:
-    """
+    f"""
     Reset and initialize a new fire rescue simulation scenario.
     
     Args:
         seed: Random seed for reproducibility (optional)
-        fire_count: Number of initial fire points (1-25, default: 10)
-        fire_intensity: Initial fire intensity (0.2-0.9, default: 0.5)
-        building_count: Number of buildings to place (1-35, default: 20)
-        max_units: Maximum deployable units (1-20, default: 10)
+        fire_count: Number of initial fire points ({FIRE_COUNT_RANGE_TEXT}, default: 10)
+        fire_intensity: Initial fire intensity ({FIRE_INTENSITY_RANGE_TEXT}, default: 0.5)
+        building_count: Number of buildings to place ({BUILDING_COUNT_RANGE_TEXT}, default: 20)
+        max_units: Maximum deployable units ({MAX_UNITS_RANGE_TEXT}, default: 10)
     
     Returns:
         Status, summary, and emoji map of the initial state

models.py

@@ -9,6 +9,11 @@ from enum import Enum
 from typing import Optional
 import random
 
+from config import SCENARIO_DEFAULTS
+
+FIRE_COUNT_DEFAULTS = SCENARIO_DEFAULTS["fire_count"]
+BUILDING_COUNT_DEFAULTS = SCENARIO_DEFAULTS["building_count"]
+
 
 class UnitType(str, Enum):
     """Types of firefighting units available."""
@@ -146,23 +151,23 @@ class WorldState:
         fire_intensity: float = 0.6,
         building_count: int = 16
     ):
-        """
+        f"""
         Initialize the grid with terrain and initial fires.
         
         Args:
             seed: Random seed for reproducibility
-            fire_count: Number of initial fire points (1-25)
+            fire_count: Number of initial fire points ({int(FIRE_COUNT_DEFAULTS.minimum)}-{int(FIRE_COUNT_DEFAULTS.maximum)})
             fire_intensity: Initial fire intensity (0.0-1.0)
-            building_count: Number of buildings to place (1-25)
+            building_count: Number of buildings to place ({int(BUILDING_COUNT_DEFAULTS.minimum)}-{int(BUILDING_COUNT_DEFAULTS.maximum)})
         """
         if seed is not None:
             random.seed(seed)
             self.seed = seed
         
-        # Clamp values to valid ranges
-        fire_count = max(1, min(25, fire_count))
+        # Clamp values using shared configuration
+        fire_count = int(FIRE_COUNT_DEFAULTS.clamp(fire_count))
         fire_intensity = max(0.0, min(1.0, fire_intensity))
-        building_count = max(1, min(25, building_count))
+        building_count = int(BUILDING_COUNT_DEFAULTS.clamp(building_count))
         
         # Generate random building positions (connected cluster)
         self.building_positions = self._generate_building_positions(building_count)

service.py

@@ -24,11 +24,15 @@ from agent import (
     PlanResult,
     CycleSummary,
 )
+from config import range_text
 from fire_rescue_mcp.mcp_client import LocalFastMCPClient
 from fire_rescue_mcp.mcp_server import attach_engine, detach_engine, mcp as fastmcp_server
 from models import SimulationStatus, CellType
 from simulation import SimulationEngine
 
+FIRE_COUNT_RANGE_TEXT = range_text("fire_count")
+BUILDING_COUNT_RANGE_TEXT = range_text("building_count")
+
 
 ADVISOR_MODEL_CHOICES = {
     "GPT-OSS · HuggingFace (openai/gpt-oss-120b)": {
@@ -256,14 +260,14 @@ class SimulationService:
         session_id: Optional[str] = None,
         on_update: Optional[Callable] = None
     ) -> dict:
-        """
+        f"""
         Start a new simulation.
         
         Args:
             seed: Random seed for reproducibility
-            fire_count: Number of initial fire points (1-25)
+            fire_count: Number of initial fire points ({FIRE_COUNT_RANGE_TEXT})
             fire_intensity: Initial fire intensity (0.0-1.0)
-            building_count: Number of buildings to place (1-25)
+            building_count: Number of buildings to place ({BUILDING_COUNT_RANGE_TEXT})
             on_update: Callback function called on state changes
             
         Returns:

simulation.py

@@ -7,16 +7,21 @@ Handles fire spread, unit behavior, and win/lose conditions.
 import random
 from typing import Optional
 
+from config import range_text
 from models import (
-    WorldState, 
-    Cell, 
-    CellType, 
-    Unit, 
-    UnitType, 
+    WorldState,
+    Cell,
+    CellType,
+    Unit,
+    UnitType,
     SimulationStatus,
-    Event
+    Event,
 )
 
+FIRE_COUNT_RANGE_TEXT = range_text("fire_count")
+BUILDING_COUNT_RANGE_TEXT = range_text("building_count")
+MAX_UNITS_RANGE_TEXT = range_text("max_units")
+
 
 class SimulationConfig:
     """Configuration parameters for the simulation."""
@@ -64,15 +69,15 @@ class SimulationEngine:
         building_count: int = 16,
         max_units: int = 10
     ) -> WorldState:
-        """
+        f"""
         Reset and initialize a new simulation.
         
         Args:
             seed: Random seed for reproducibility
-            fire_count: Number of initial fire points (1-25)
+            fire_count: Number of initial fire points ({FIRE_COUNT_RANGE_TEXT})
             fire_intensity: Initial fire intensity (0.0-1.0)
-            building_count: Number of buildings to place (1-25)
-            max_units: Maximum number of deployable units (1-20)
+            building_count: Number of buildings to place ({BUILDING_COUNT_RANGE_TEXT})
+            max_units: Maximum number of deployable units ({MAX_UNITS_RANGE_TEXT})
         """
         self.world = WorldState(
             width=self.config.GRID_WIDTH,