Implement my agent

agent.py

@@ -1,28 +1,9 @@
 """
 Student Agent for Text Adventure Games
-
-This is your submission file. Implement the StudentAgent class to play
-text adventure games using the MCP server you also implement.
-
-Your agent should:
-1. Connect to the MCP server via the provided client
-2. Use the ReAct pattern (Thought -> Action -> Observation)
-3. Call MCP tools to interact with the game
-4. Maximize the game score within the step limit
-
-Required method:
-    async def run(self, client, game, max_steps, seed, verbose) -> RunResult
-
-The 'client' is a FastMCP Client already connected to your MCP server.
-Use it to call tools like: await client.call_tool("play_action", {"action": "look"})
-
-Tips:
-- Start by looking around and understanding your environment
-- Keep track of visited locations to avoid loops
-- Pick up useful items (lamp, sword, etc.)
-- The seed parameter should be used to set your LLM's seed for reproducibility
+Features: Continuous Intelligence, Global Mapping, and Robust Parsing.
 """
 
+import ast
 import json
 import os
 import re
@@ -32,89 +13,34 @@ from typing import Optional
 from dotenv import load_dotenv
 from huggingface_hub import InferenceClient
 
-# Load environment variables
 load_dotenv()
 
-# Set USE_LOCAL_MODEL=1 in your .env to use a locally downloaded model
-USE_LOCAL_MODEL = os.getenv("USE_LOCAL_MODEL", "0").strip() in ("1", "true", "yes")
-LOCAL_MODEL_ID = os.getenv("LOCAL_MODEL_ID", "Qwen/Qwen2.5-3B-Instruct")
-
 # =============================================================================
-# LLM Configuration - DO NOT MODIFY
+# LLM Setup
 # =============================================================================
 
-# Model to use (fixed for fair evaluation)
 LLM_MODEL = "Qwen/Qwen2.5-72B-Instruct"
+_hf_token = os.getenv("HF_TOKEN")
+if not _hf_token:
+    raise ValueError("HF_TOKEN not found. Set it in your .env file.")
 
-# Initialize the LLM client based on mode
-_local_pipeline = None
-
-if USE_LOCAL_MODEL:
-    import torch
-    from transformers import pipeline as _hf_pipeline
-
-    _local_pipeline = _hf_pipeline(
-        "text-generation",
-        model=LOCAL_MODEL_ID,
-        torch_dtype=torch.bfloat16,
-        device_map="auto",
-    )
-    LLM_CLIENT = None
-else:
-    _hf_token = os.getenv("HF_TOKEN")
-    if not _hf_token:
-        raise ValueError("HF_TOKEN not found. Set it in your .env file.")
-    LLM_CLIENT = InferenceClient(token=_hf_token)
-
+LLM_CLIENT = InferenceClient(token=_hf_token)
 
 def call_llm(prompt: str, system_prompt: str, seed: int, max_tokens: int = 300) -> str:
-    """
-    Call the LLM with the given prompt. Use this function in your agent.
-    
-    Args:
-        prompt: The user prompt (current game state, history, etc.)
-        system_prompt: The system prompt (instructions for the agent)
-        seed: Random seed for reproducibility
-        max_tokens: Maximum tokens in response (default: 300)
-        
-    Returns:
-        The LLM's response text
-        
-    Example:
-        response = call_llm(
-            prompt="You are in a forest. What do you do?",
-            system_prompt=SYSTEM_PROMPT,
-            seed=42,
-        )
-    """
-    messages = [
-        {"role": "system", "content": system_prompt},
-        {"role": "user", "content": prompt},
-    ]
-
-    if USE_LOCAL_MODEL and _local_pipeline is not None:
-        outputs = _local_pipeline(
-            messages,
-            max_new_tokens=max_tokens,
-            temperature=0.0001,  # Near-deterministic (0.0 unsupported by some backends)
-            do_sample=True,
-        )
-        return outputs[0]["generated_text"][-1]["content"]
-
     response = LLM_CLIENT.chat.completions.create(
         model=LLM_MODEL,
-        messages=messages,
-        temperature=0.0,  # Deterministic for reproducibility
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user",   "content": prompt},
+        ],
+        temperature=0.0,
         max_tokens=max_tokens,
         seed=seed,
     )
-
     return response.choices[0].message.content
 
-
 @dataclass
 class RunResult:
-    """Result of running the agent. Do not modify this class."""
     final_score: int
     max_score: int
     moves: int
@@ -123,183 +49,242 @@ class RunResult:
     error: Optional[str] = None
     history: list[tuple[str, str, str]] = field(default_factory=list)
 
-
 # =============================================================================
-# System Prompt - Customize this for your agent
+# Direction Normalization (Fuzzy Support)
 # =============================================================================
 
-SYSTEM_PROMPT = """You are playing a classic text adventure game.
-
-GOAL: Explore the world, solve puzzles, and maximize your score.
-
-AVAILABLE TOOLS (use via MCP):
-- play_action: Execute a game command (north, take lamp, open mailbox, etc.)
-- memory: Get current game state and history (if implemented)
-- inventory: Check what you're carrying (if implemented)
-
-VALID GAME COMMANDS for play_action:
-- Movement: north, south, east, west, up, down, enter, exit
-- Objects: take <item>, drop <item>, open <thing>, close <thing>, examine <thing>
-- Other: look, inventory, read <thing>, turn on lamp
-
-RESPOND IN THIS EXACT FORMAT (no markdown):
-THOUGHT: <your reasoning about what to do next>
-TOOL: <tool_name>
-ARGS: <JSON arguments, e.g., {"action": "look"}>
-
-Example:
-THOUGHT: I should look around to see where I am.
-TOOL: play_action
-ARGS: {"action": "look"}
-"""
-
+_DIR_MAP = {
+    'n': 'n', 'north': 'n',
+    's': 's', 'south': 's',
+    'e': 'e', 'east': 'e',
+    'w': 'w', 'west': 'w',
+    'u': 'u', 'up': 'u',
+    'd': 'd', 'down': 'd',
+    'ne': 'ne', 'northeast': 'ne', 'north-east': 'ne',
+    'nw': 'nw', 'northwest': 'nw', 'north-west': 'nw',
+    'se': 'se', 'southeast': 'se', 'south-east': 'se',
+    'sw': 'sw', 'southwest': 'sw', 'south-west': 'sw',
+    'in': 'in', 'out': 'out', 'enter': 'enter', 'exit': 'exit'
+}
+
+def _normalize_direction(action_str: str) -> str:
+    parts = action_str.lower().replace('-', ' ').strip().split()
+    if not parts: return ""
+    # Handle "go north", "walk ne", etc.
+    candidate = parts[1] if len(parts) >= 2 and parts[0] in ("go", "walk", "move") else parts[0]
+    return _DIR_MAP.get(candidate, "")
 
 # =============================================================================
-# Student Agent - IMPLEMENT THIS CLASS
+# StudentAgent Class
 # =============================================================================
 
 class StudentAgent:
-    """
-    Your ReAct agent implementation.
-    
-    TODO:
-    1. Implement the run() method with the ReAct loop
-    2. Parse LLM responses to extract tool calls
-    3. Track state and avoid loops
-    
-    Use the provided call_llm() function to interact with the LLM.
-    """
-    
     def __init__(self):
-        """Initialize your agent here."""
-        # TODO: Initialize any state tracking you need
-        # self.history = []
-        # self.visited_locations = set()
-        pass
-    
-    async def run(
-        self,
-        client,  # FastMCP Client connected to your MCP server
-        game: str,
-        max_steps: int,
-        seed: int,
-        verbose: bool = False,
-    ) -> RunResult:
-        """
-        Run the agent for a game session.
+        # Global map: { "Room": { "exits": { "ne": {"dest": "A Hole", "status": "Visited/Hypothesized"} } } }
+        self.global_map = {}
+        # Local memory: { "Room": { "desc": "", "leads": [], "log": [], "steps": 0 } }
+        self.rooms = {}
         
-        Args:
-            client: FastMCP Client connected to your MCP server
-            game: Name of the game being played (e.g., "zork1")
-            max_steps: Maximum number of steps to take
-            seed: Random seed for reproducibility (use for LLM calls)
-            verbose: Whether to print detailed output
-            
-        Returns:
-            RunResult with final score and statistics
-        """
-        # TODO: Implement your ReAct loop here
-        #
-        # Basic structure:
-        # 1. Get initial observation (call play_action with "look")
-        # 2. Loop for max_steps:
-        #    a. Build prompt with current observation and history
-        #    b. Call LLM to get thought and action
-        #    c. Parse the response to extract tool and args
-        #    d. Call the tool via client.call_tool(tool_name, args)
-        #    e. Update history and state
-        #    f. Check for game over
-        # 3. Return RunResult with final statistics
+        self.current_room = None
+        self.inventory = []
+        self.score = 0
+        self.moves = 0
+
+    # -------------------------------------------------------------------------
+    # 1. Continuous Intelligence (LLM Helpers)
+    # -------------------------------------------------------------------------
+
+    def _summarise(self, action: str, obs: str, seed: int) -> str:
+        prompt = f"Action: {action}\nResult: {obs}\nSummarize outcome in 8 words."
+        return call_llm(prompt, "Summarizer.", seed).strip()
+
+    def _extract_best_leads(self, desc: str, actions: list, seed: int) -> list[str]:
+        # Filter movement and meta out of leads to keep LLM focused on objects
+        filtered = [a for a in actions if _normalize_direction(a) == "" and len(a.split()) < 4]
+        prompt = f"DESC: {desc[:400]}\nVALID: {filtered[:30]}\nPick 5 best non-movement leads. Return Python list of strings."
+        res = call_llm(prompt, "Strategist.", seed)
+        try:
+            return ast.literal_eval(res[res.find('['):res.rfind(']')+1])
+        except: return filtered[:5]
+
+    def _hypothesize_exits(self, desc: str, seed: int) -> list[dict]:
+        """LLM cartographer: called EVERY turn to ensure no exits are missed."""
+        prompt = f"OBSERVATION: {desc[:600]}\nList all exits mentioned in text (n, s, e, w, ne, nw, se, sw, up, down, in, out). Format: [{{'dir': 'ne', 'leads_to': 'a hole'}}, ...] Do not hallucinate exits, only extract from text."
+        res = call_llm(prompt, "Cartographer.", seed)
+        try:
+            return ast.literal_eval(res[res.find('['):res.rfind(']')+1])
+        except: return []
+
+    # -------------------------------------------------------------------------
+    # 2. State & Dynamic Map Reconciliation
+    # -------------------------------------------------------------------------
+
+    async def _update_intelligence(self, client, last_obs=None, last_act=None, seed=42):
+        """Refreshes game state and map hypotheses based on the LATEST observation."""
+        state_res = await client.call_tool("game_state", {})
+        data = json.loads(self._text(state_res))
         
-        # Example of calling a tool:
-        # result = await client.call_tool("play_action", {"action": "look"})
-        # observation = result[0].text if result else "No response"
+        new_room = data.get("location", "Unknown")
+        self.inventory, self.score, self.moves = data.get("inventory", []), data.get("score", 0), data.get("moves", 0)
+
+        # 1. If we moved, confirm the path in the global map
+        if last_act and self.current_room and self.current_room != new_room:
+            norm_dir = _normalize_direction(last_act)
+            if norm_dir:
+                if self.current_room not in self.global_map: self.global_map[self.current_room] = {"exits": {}}
+                self.global_map[self.current_room]["exits"][norm_dir] = {"dest": new_room, "status": "Visited"}
+                print(f"[Map] Confirmed: {self.current_room} -> {new_room}")
+
+        self.current_room = new_room
+
+        # 2. Discovery: Initialize new room memory if needed
+        if new_room not in self.rooms:
+            print(f"[Discovery] Arriving at: {new_room}")
+            # If we don't have a fresh observation from a play_action, get one via 'look'
+            obs = last_obs if last_obs else self._text(await client.call_tool("play_action", {"action": "look"}))
+            valid = json.loads(self._text(await client.call_tool("get_valid_actions", {}))).get("valid_actions", [])
+            
+            self.rooms[new_room] = {
+                "desc": obs, 
+                "leads": self._extract_best_leads(obs, valid, seed), 
+                "log": [], 
+                "steps": 0
+            }
         
-        # Example of calling the LLM:
-        # response = call_llm(
-        #     prompt="Current observation: " + observation,
-        #     system_prompt=SYSTEM_PROMPT,
-        #     seed=seed,
-        # )
+        # 3. CONTINUOUS MAPPING: Scan the latest observation for exits (every turn!)
+        current_obs = last_obs if last_obs else self.rooms[new_room]["desc"]
+        if new_room not in self.global_map: self.global_map[new_room] = {"exits": {}}
         
-        # Placeholder implementation - replace with your code
-        locations_visited = set()
+        for h in self._hypothesize_exits(current_obs, seed):
+            d = _normalize_direction(h['dir'])
+            # Only add if it's new OR if the current status is just a guess
+            if d and (d not in self.global_map[new_room]["exits"] or self.global_map[new_room]["exits"][d]["status"] == "Hypothesized"):
+                self.global_map[new_room]["exits"][d] = {"dest": h['leads_to'], "status": "Hypothesized"}
+
+    def _get_map_str(self) -> str:
+        if not self.global_map: return "Empty"
+        lines = []
+        for room, info in self.global_map.items():
+            ex = info.get("exits", {})
+            vis = [f"{d}->{v['dest']}" for d, v in ex.items() if v["status"] == "Visited"]
+            hyp = [f"{d}({v['dest']}?)" for d, v in ex.items() if v["status"] == "Hypothesized"]
+            if vis or hyp:
+                lines.append(f"  {room}: {' '.join(vis + hyp)}")
+        return "\n".join(lines)
+
+    # -------------------------------------------------------------------------
+    # 3. Main Loop
+    # -------------------------------------------------------------------------
+
+    async def run(self, client, game, max_steps, seed, verbose=False) -> RunResult:
         history = []
-        final_score = 0
-        moves = 0
-        
-        # TODO: Your implementation here
-        # ...
-        
-        return RunResult(
-            final_score=final_score,
-            max_score=350,  # Zork1 max score, adjust if needed
-            moves=moves,
-            locations_visited=locations_visited,
-            game_completed=False,
-            history=history,
-        )
-    
-    def _build_prompt(self, observation: str, history: list) -> str:
-        """
-        Build the prompt for the LLM.
-        
-        TODO: Implement this to create effective prompts
-        """
-        # TODO: Combine system prompt, history, and current observation
-        pass
-    
-    def _parse_response(self, response: str) -> tuple[str, str, dict]:
-        """
-        Parse LLM response to extract thought, tool name, and arguments.
-        
-        TODO: Implement robust parsing
-        
-        Returns:
-            Tuple of (thought, tool_name, args_dict)
-        """
-        # TODO: Parse the response format:
-        # THOUGHT: ...
-        # TOOL: ...
-        # ARGS: {...}
-        pass
-    
-    def _call_llm(self, prompt: str, system_prompt: str, seed: int) -> str:
-        """
-        Call the LLM with the given prompt.
-        
-        This is a convenience wrapper - you can also use call_llm() directly.
-        """
-        return call_llm(prompt, system_prompt, seed)
+        await self._update_intelligence(client, seed=seed)
+
+        system_prompt = """You are an expert Text Adventure player. Maximize score by exploring, solving puzzles, and collecting treasures/items.
+AVAILABLE TOOLS:
+- play_action: {"action": "command"} (Use this for ALL game commands like 'ne', 'take pants', 'light torch')
+- get_valid_actions: {} (Use this if you are stuck)
+
+RULES:
+1. Prioritize 'Hypothesized' exits marked with (?) on the map to find new rooms.
+2. If the map shows a path leads to a room you want to go to, use that direction.
+3. Finish 'Promising Leads' (taking items, etc) before leaving.
+4. Use THOUGHT, TOOL, ARGS format exactly."""
+
+        for step in range(max_steps):
+            room_data = self.rooms[self.current_room]
+            room_data["steps"] += 1
+            
+            print(f"\n[DEBUG] STEP {step+1} | MOVES:{self.moves} | LOC:{self.current_room}")
+            
+            bias = ""
+            if room_data["steps"] > 6:
+                bias = "\n[SYSTEM ADVICE]: You have lingered here. Pick an unexplored (?) path and move!"
 
+            prompt = f"""
+=== STATUS ===
+Moves: {self.moves} | Score: {self.score} | Inventory: {self.inventory}
 
-# =============================================================================
-# For local testing
-# =============================================================================
 
-async def test_agent():
-    """Test the agent locally."""
-    from fastmcp import Client
-    
-    # Path to your MCP server
-    server_path = "mcp_server.py"
-    
-    agent = StudentAgent()
-    
-    async with Client(server_path) as client:
-        result = await agent.run(
-            client=client,
-            game="zork1",
-            max_steps=10,
-            seed=42,
-            verbose=True,
-        )
-        
-        print(f"\nFinal Score: {result.final_score}")
-        print(f"Moves: {result.moves}")
-        print(f"Locations: {result.locations_visited}")
 
+=== CURRENT LOCATION: {self.current_room} ===
+{room_data['desc']}
+
+=== GLOBAL MAP ===
+{self._get_map_str()}
+
+=== ACTION LOG (In this room) ===
+{chr(10).join(f"- {l}" for l in room_data['log'][-5:])}
+
+=== STRATEGY Leads ===
+{room_data['leads']}
+{bias}
+
+What is your next move?"""
+
+            llm_res = call_llm(prompt, system_prompt, seed)
+            if verbose: print(f"--- Thought ---\n{llm_res}")
+            
+            thought, tool, args = self._parse(llm_res)
+
+            try:
+                res_obj = await client.call_tool(tool, args)
+                obs = self._text(res_obj)
+                act_str = args.get('action', "look")
+
+                if tool == "play_action":
+                    summary = self._summarise(act_str, obs, seed)
+                    room_data["log"].append(f"{act_str} -> {summary}")
+                    # If action was successful, update the room's stored description
+                    if "not" not in summary.lower() and "fail" not in summary.lower():
+                        room_data["desc"] = obs 
+                
+                # Update intelligence with the NEW observation
+                await self._update_intelligence(client, last_obs=obs, last_act=act_str, seed=seed)
+                history.append((act_str, obs))
+
+            except Exception as e:
+                print(f"Loop Error: {e}")
+
+        return RunResult(self.score, 350, self.moves, set(self.rooms.keys()), False, history=history)
+
+    # -------------------------------------------------------------------------
+    # 4. Utilities & Robust Parser
+    # -------------------------------------------------------------------------
+
+    def _text(self, res) -> str:
+        if hasattr(res, 'content') and isinstance(res.content, list) and res.content:
+            return res.content[0].text
+        return str(res.data) if hasattr(res, 'data') else str(res)
+
+    def _parse(self, res: str) -> tuple[str, str, dict]:
+        thought = tool = ""
+        args = {}
+        t_m = re.search(r"THOUGHT:\s*(.*?)(?=TOOL:|$)", res, re.DOTALL)
+        if t_m: thought = t_m.group(1).strip()
+        m_m = re.search(r"TOOL:\s*(.*?)(?=ARGS:|$)", res, re.DOTALL)
+        if m_m: tool = m_m.group(1).strip()
+        a_m = re.search(r"ARGS:\s*(\{.*?\})", res, re.DOTALL)
+        if a_m:
+            try: args = json.loads(a_m.group(1).strip())
+            except: pass
+        
+        # Correction logic
+        if tool.lower() in ["go", "move", "take", "walk"]:
+            action_val = str(args) if not isinstance(args, dict) else args.get('action', "look")
+            tool, args = "play_action", {"action": action_val}
+            
+        if not tool or tool not in ["play_action", "get_valid_actions", "inspect_surroundings"]:
+            tool, args = "play_action", {"action": "look"}
+            
+        return thought, tool, args
 
+# (Optional Local Test Block)
 if __name__ == "__main__":
     import asyncio
-    asyncio.run(test_agent())
+    async def test_agent():
+        from fastmcp import Client
+        agent = StudentAgent()
+        async with Client("mcp_server.py") as client:
+            await agent.run(client, "zork1", 20, 42, verbose=True)
+    asyncio.run(test_agent())

mcp_server.py

@@ -32,7 +32,7 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 from fastmcp import FastMCP
 from games.zork_env import TextAdventureEnv
-
+import json
 
 # =============================================================================
 # Create the MCP Server
@@ -46,52 +46,99 @@ mcp = FastMCP("Student Text Adventure Server")
 # =============================================================================
 
 class GameManager:
-    """
-    Manages the text adventure game state.
-    
-    TODO: Extend this class to track:
-    - Action history (for memory tool)
-    - Explored locations (for mapping)
-    - Current score and moves
-    """
+    """Manages the text adventure game state and builds a dynamic map."""
     
     def __init__(self):
         self.env: TextAdventureEnv = None
         self.state = None
         self.game_name: str = ""
-        # TODO: Add more state tracking
-        # self.history: list[tuple[str, str]] = []
-        # self.explored_locations: dict[str, set[str]] = {}
-        # self.current_location: str = ""
-    
+        
+        # --- Map Tracking Variables ---
+        self.visited = set()
+        self.connections = {}  # Format: { "Room A": { "north": "Room B" } }
+        self.unexplored = {}   # Format: { "Room A": set(["east", "west"]) }
+        
+        # Standard Z-machine directions
+        self.directions = {
+            'north', 'south', 'east', 'west', 
+            'ne', 'nw', 'se', 'sw', 
+            'up', 'down', 'in', 'out', 'enter', 'exit',
+            'n', 's', 'e', 'w', 'u', 'd'
+        }
+        
+        # Dictionary to normalize shortcuts (n -> north)
+        self.dir_map = {
+            'n': 'north', 's': 'south', 'e': 'east', 'w': 'west',
+            'u': 'up', 'd': 'down'
+        }
+
+
+    def _normalize_dir(self, direction: str) -> str:
+        d = direction.lower().strip()
+        return self.dir_map.get(d, d)
+
+    def _update_map(self, previous_loc: str, action: str, current_loc: str):
+        """Builds the graph as the player moves around."""
+        if not current_loc:
+            # Still record the edge from previous room as a dead-end/blocked path
+            if previous_loc and action:
+                norm_action = self._normalize_dir(action)
+                if norm_action in self.directions and previous_loc in self.unexplored:
+                    self.unexplored[previous_loc].discard(norm_action)
+            return
+
+        # 1. Initialize the new room if we haven't seen it
+        if current_loc not in self.connections:
+            self.connections[current_loc] = {}
+            self.visited.add(current_loc)
+            
+            # Find which directions are possible from this new room
+            if self.env and self.env.env:
+                valid_actions = self.env.env.get_valid_actions(use_parallel=False)
+                # Filter out standard directions
+                valid_dirs = set(self._normalize_dir(a) for a in valid_actions if a.lower() in self.directions)
+                self.unexplored[current_loc] = valid_dirs
+
+        # 2. Record the traversal edge if we just moved
+        norm_action = self._normalize_dir(action)
+        if previous_loc and previous_loc != current_loc and norm_action in self.directions:
+            self.connections[previous_loc][norm_action] = current_loc
+            
+            # Remove this direction from unexplored for the previous room
+            if previous_loc in self.unexplored:
+                self.unexplored[previous_loc].discard(norm_action)
+
     def initialize(self, game: str = "zork1"):
-        """Initialize or reset the game."""
         self.game_name = game
         self.env = TextAdventureEnv(game)
         self.state = self.env.reset()
-        # TODO: Reset your state tracking here
+        
+        # Map the starting room
+        start_loc = self.env.env.get_player_location()
+        if start_loc:
+            self._update_map(None, "", start_loc.name)
+            
         return self.state.observation
     
     def step(self, action: str) -> str:
-        """Execute an action and return the result."""
         if self.env is None:
             self.initialize()
+            
+        loc_before_obj = self.env.env.get_player_location()
+        loc_before = loc_before_obj.name if loc_before_obj else None
         
         self.state = self.env.step(action)
         
-        # TODO: Update your state tracking here
-        # self.history.append((action, self.state.observation))
-        # Update location tracking, etc.
+        loc_after_obj = self.env.env.get_player_location()
+        loc_after = loc_after_obj.name if loc_after_obj else None
+        
+        # Update our Map Graph!
+        self._update_map(loc_before, action, loc_after)
         
         return self.state.observation
     
-    def get_score(self) -> int:
-        """Get current score."""
-        return self.state.score if self.state else 0
-    
-    def get_moves(self) -> int:
-        """Get number of moves taken."""
-        return self.state.moves if self.state else 0
+    def get_score(self) -> int: return self.state.score if self.state else 0
+    def get_moves(self) -> int: return self.state.moves if self.state else 0
 
 
 # Global game manager
@@ -114,90 +161,188 @@ def get_game() -> GameManager:
 
 @mcp.tool()
 def play_action(action: str) -> str:
-    """
-    Execute a game command and return the result.
+    """Execute a game command and return the result."""
+    game = get_game()
     
-    This is the main tool for interacting with the game.
+    # Get location BEFORE action
+    loc_before = game.env.env.get_player_location().name if game.env.env.get_player_location() else ""
     
-    Args:
-        action: The command to execute (e.g., "north", "take lamp", "open mailbox")
+    # Execute action
+    result = game.step(action)
+    
+    # Get location AFTER action
+    loc_after = game.env.env.get_player_location().name if game.env.env.get_player_location() else ""
+    
+    # If the player moved, append a fresh "look" observation automatically
+    # if loc_before != loc_after and action.lower() not in ['look', 'l']:
+    #     look_result = game.step("look")
+    #     result += f"\n\n[You moved to a new area]\n{look_result}"
         
+    return result
+
+# TODO: Implement additional tools to help your agent
+@mcp.tool()
+def game_state() -> str:
+    """
+    Returns the current state of the game: Score, Moves, Location, and Inventory.
+    """
+    game = get_game()
+    if not game.env.env:
+        return "Game not initialized."
+    
+    inventory = game.env.env.get_inventory()
+    inv_names = [obj.name for obj in inventory] if inventory else ["Empty"]
+    
+    location = game.env.env.get_player_location()
+    loc_name = location.name if location else "Unknown"
+
+    state = {
+        "location": loc_name,
+        "score": game.get_score(),
+        "moves": game.get_moves(),
+        "inventory": inv_names
+    }
+    return json.dumps(state)
+
+
+@mcp.tool()
+def inventory() -> str:
+    """
+    Check what the player is carrying.
+    
     Returns:
-        The game's response to the action
-        
-    Valid commands include:
-        - Movement: north, south, east, west, up, down, enter, exit
-        - Objects: take <item>, drop <item>, open <thing>, examine <thing>
-        - Other: look, inventory, read <thing>, turn on lamp
+        List of items in the player's inventory
     """
     game = get_game()
+    if not game.env.env: return "Game not initialized."
     
-    # TODO: You might want to add action validation here
-    # TODO: You might want to include score changes in the response
+    inventory_objects = game.env.env.get_inventory()
+    if not inventory_objects:
+        return "Your inventory is empty."
     
-    result = game.step(action)
+    items = [obj.name for obj in inventory_objects]
+    return f"Inventory: {', '.join(items)}"
+
+@mcp.tool()
+def memory() -> str:
+    """
+    Get the current game state summary: Location, Score, and Moves.
+    Use this to orient yourself.
+    """
+    game = get_game()
+    if not game.env.env: return "Game not initialized."
     
-    # Optional: Append score info
-    # result += f"\n[Score: {game.get_score()} | Moves: {game.get_moves()}]"
+    location = game.env.env.get_player_location()
+    loc_name = location.name if location else "Unknown Location"
     
-    return result
+    return json.dumps({
+        "location": loc_name,
+        "score": game.get_score(),
+        "moves": game.get_moves(),
+        "max_score": game.env.env.get_max_score()
+    })
 
+@mcp.tool()
+def get_map() -> str:
+    """
+    Get a map of explored locations AND the paths to reach unexplored exits.
+    Use this to figure out where to go next to discover new areas.
+    """
+    game = get_game()
+    if not game.env or not game.env.env:
+        return "Game not initialized."
+        
+    current_loc_obj = game.env.env.get_player_location()
+    if not current_loc_obj:
+        return "Cannot determine your current location."
+        
+    current_loc = current_loc_obj.name
+    
+    # 1. List Visited Locations
+    visited_str = ", ".join(sorted(list(game.visited)))
+    
+    # 2. Find paths to Unexplored Exits using BFS (Breadth-First Search)
+    queue = [(current_loc, [])]  # Queue of (Room Name, [Path of Actions])
+    visited_bfs = set([current_loc])
+    
+    paths_to_unexplored = []
+    
+    # Rooms that have at least one unexplored exit
+    rooms_with_unexplored = {r: exits for r, exits in game.unexplored.items() if len(exits) > 0}
+    
+    while queue:
+        curr, path = queue.pop(0)
+        
+        # If this room has unexplored exits, log the path to get here!
+        if curr in rooms_with_unexplored:
+            unexp_str = ", ".join(rooms_with_unexplored[curr])
+            if not path:
+                paths_to_unexplored.append(f"Right here in '{curr}', you haven't tried: {unexp_str}")
+            else:
+                path_str = " -> ".join(path)
+                paths_to_unexplored.append(f"To explore '{curr}' ({unexp_str}), walk: {path_str}")
+                
+        # Traverse known connections
+        for direction, neighbor in game.connections.get(curr, {}).items():
+            if neighbor not in visited_bfs:
+                visited_bfs.add(neighbor)
+                queue.append((neighbor, path + [direction]))
+                
+    # 3. Format the final beautiful output
+    output = f"CURRENT LOCATION: {current_loc}\n\n"
+    output += f"VISITED LOCATIONS ({len(game.visited)} total):\n{visited_str}\n\n"
+    output += f"UNEXPLORED PATHS & HOW TO GET THERE:\n"
+
+    if paths_to_unexplored:
+        output += "\n".join(f"- {p}" for p in paths_to_unexplored)
+    else:
+        output += "- No known unexplored paths! You have fully explored everything."
+        
+    return output
 
-# TODO: Implement additional tools to help your agent
+@mcp.tool()
+def get_valid_actions() -> str:
+    """
+    Get a list of guaranteed valid actions for the current game state.
+    Use this when you are stuck or don't know what verbs the game understands.
+    """
+    game = get_game()
+    if not game.env.env:
+        return "Game not initialized."
+    
+    # Jericho extracts valid actions based on the object tree
+    valid_actions = game.env.env.get_valid_actions(use_object_tree=True, use_parallel=False)
+    
+    # Filter out boring/meta actions if necessary, or just return them
+    return json.dumps({
+        "valid_actions": valid_actions[:30] # Limit to top 30 to save context window
+    })
 
-# @mcp.tool()
-# def memory() -> str:
-#     """
-#     Get the current game state summary.
-#     
-#     Returns:
-#         A summary including current location, score, moves, and recent history
-#     """
-#     game = get_game()
-#     # TODO: Return useful state information
-#     pass
-
-
-# @mcp.tool()
-# def inventory() -> str:
-#     """
-#     Check what the player is carrying.
-#     
-#     Returns:
-#         List of items in the player's inventory
-#     """
-#     game = get_game()
-#     result = game.step("inventory")
-#     return result
-
-
-# @mcp.tool()
-# def get_map() -> str:
-#     """
-#     Get a map of explored locations.
-#     
-#     Returns:
-#         A text representation of explored locations and connections
-#     """
-#     game = get_game()
-#     # TODO: Return map of explored locations
-#     pass
-
-
-# @mcp.tool()
-# def get_valid_actions() -> str:
-#     """
-#     Get a list of likely valid actions from the current location.
-#     
-#     Returns:
-#         List of actions that might work here
-#     """
-#     # This is a hint: Jericho provides get_valid_actions()
-#     game = get_game()
-#     if game.env and game.env.env:
-#         valid = game.env.env.get_valid_actions()
-#         return "Valid actions: " + ", ".join(valid[:20])
-#     return "Could not determine valid actions"
+@mcp.tool()
+def inspect_surroundings() -> str:
+    """
+    Scans the room and returns a list of interactive objects physically present.
+    """
+    game = get_game()
+    if not game.env.env: return "Game not initialized."
+    
+    player_loc = game.env.env.get_player_location()
+    if not player_loc: return "Cannot determine location."
+    
+    # Traverse the object tree: get the first child of the room, then iterate siblings
+    objects_in_room = []
+    child_num = player_loc.child
+    
+    while child_num != 0:
+        obj = game.env.env.get_object(child_num)
+        if obj and obj.num != game.env.env.get_player_object().num: # Don't list the player
+            objects_in_room.append(obj.name)
+        child_num = obj.sibling if obj else 0
+        
+    if not objects_in_room:
+        return "No notable interactive objects found here."
+        
+    return f"Interactive objects in this room: {', '.join(objects_in_room)}"
 
 
 # =============================================================================
@@ -206,4 +351,4 @@ def play_action(action: str) -> str:
 
 if __name__ == "__main__":
     # This runs the server with stdio transport (for MCP clients)
-    mcp.run()
+    mcp.run()