submission

README.md

@@ -18,11 +18,21 @@ This is my submission for the Text Adventure Agent assignment. My agent uses the
 
 ## Approach
 
-<!-- Describe your approach here -->
+When comparing to the reference agent, this agent has two types of improvements: a **large mapping system** that is very different from the reference agent and **smaller changes** that directly build upon the ideas of the baseline.
 
-- What strategy does your agent use?
-- What tools did you implement in your MCP server?
-- Any interesting techniques or optimizations?
+**Context size management:** Each call to the model **automatically includes a short summary of past actions**, without any need for the agent to explicitely call the memory tool. If done properly, the **context size stays small** while helping the model not to get stuck. The whole summary process has been rewritten and always includes explicit function calls from past iterations of the LLM, which **greatly reduces the number of poorly formatted MCP requests**.
+
+**Better location counting:** The reference agent was using broken filtering rules for detecting the current location. This has been changed to something more robust that seem to work on all games tested so far.
+
+**Graph of locations:** The agent tends to struggle with spatial awareness in this type of game, especially when the number of location grows. At the same time, directions can be weird. For instance, at the beginning of Zork, going north then south does not lead to the initial position. Backtracking using opposite direction will thus not always work. This agent tries to allievate this problem by creating a directed graph of transition between locations, with transitions that are confirmed and other that are unconfirmed.
+
+*Example:* For instance, if going north from location A leads to location B, then the edges (A, B, north, confirmed) and (B, A, south, unconfirmed) will be added to the graph, because we cannot be sure that going south from B will lead to A, but this is still a good guess.
+
+*Unexplored locations:* The graph also takes into account location adjacent to previously visited location, whose existence can be infered through the use of `get_valid_actions`.
+
+**Listing locations and travelling:** From the above graph, the closest explored and unexplored locations can be infered. In practice, this is done by prioritizing routing through "confirmed" edges, but allowing to go through "unconfirmed" edges if needed. Accordingly, the agent is given tools to list those locations, to see how far they are, and to travel through them. When travelling, the actions corresponding to the best guess for a route to this location will be executed in order. When destination is reached or something unexpected happen, the control is given back to the agent. This allows to shorten even more the context size and keep the agent focused on longer term objectives.
+
+*Note:* The agent is extremely slow on lostpig because calls to `get_valid_actions` take ages for some reason.
 
 ## Files
 

agent.py

@@ -1,26 +1,8 @@
 """
-Student Agent for Text Adventure Games
+Example: MCP ReAct Agent
 
-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
+A complete ReAct agent that uses MCP tools to play text adventure games.
+This is a working example students can learn from.
 """
 
 import json
@@ -32,83 +14,41 @@ 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
 # =============================================================================
 
-# Model to use (fixed for fair evaluation)
 LLM_MODEL = "Qwen/Qwen2.5-72B-Instruct"
 
-# Initialize the LLM client based on mode
-_local_pipeline = None
-
-if USE_LOCAL_MODEL:
-    import torch
-    from transformers import pipeline as _hf_pipeline
+_hf_token = os.getenv("HF_TOKEN")
+if not _hf_token:
+    raise ValueError("HF_TOKEN not found. Set it in your .env file.")
 
-    _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,
-        )
-    """
+    """Call the LLM with the given prompt."""
     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"]
+    # print("\n\n------------")
+    # for m in messages[1:]:
+    #     print(f"{m['role']}: {m['content']}")
+    # print("------------\n\n")
 
     response = LLM_CLIENT.chat.completions.create(
         model=LLM_MODEL,
         messages=messages,
-        temperature=0.0,  # Deterministic for reproducibility
+        temperature=0.0,
         max_tokens=max_tokens,
         seed=seed,
     )
-
+    
     return response.choices[0].message.content
 
 
@@ -125,179 +65,328 @@ class RunResult:
 
 
 # =============================================================================
-# System Prompt - Customize this for your agent
+# System Prompt
 # =============================================================================
 
-SYSTEM_PROMPT = """You are playing a classic text adventure game.
-
-GOAL: Explore the world, solve puzzles, and maximize your score.
+SYSTEM_PROMPT = """You are an expert text adventure game player. Your goal is to explore, collect treasures, and maximize your score as fast as possible.
 
-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)
+AVAILABLE TOOLS (use these via MCP):
+1. play_action - Execute game commands and physically interact with your environment (north, take lamp, open mailbox, etc).
+2. get_locations - List nearby locations that you visited or that are adjacent to locations you visited.
+3. get_unexplored_locations - List nearby unexplored adjacent to locations you visited.
+4. travel - Fast travel to a given location you previously visited through backtracking.
+5. memory - Get a summary of the current game state, in case you feel lost.
+6. inventory - Check your inventory. You have no inventory size limit.
 
 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
+- Light: turn on lamp, turn off lamp
+- Combat: attack <enemy> with <weapon>
+- Other: inventory, look, read <thing>, wait
+
+FORBIDDEN (will NOT work): check, inspect, search, grab, use, help
 
 RESPOND IN THIS EXACT FORMAT (no markdown):
-THOUGHT: <your reasoning about what to do next>
+THOUGHT: <brief reasoning about what to do next>
 TOOL: <tool_name>
-ARGS: <JSON arguments, e.g., {"action": "look"}>
+ARGS: <JSON arguments>
 
-Example:
-THOUGHT: I should look around to see where I am.
+Examples:
+THOUGHT: I need to see what's around me.
 TOOL: play_action
 ARGS: {"action": "look"}
-"""
+
+THOUGHT: I'm completely loss and don't know where to go next. I will check for nearby unexplored locations.
+TOOL: get_unexplored_locations
+ARGS: {}
+
+THOUGHT: I need to explore new locations. I travel north of the burn forest directly.
+TOOL: travel
+ARGS: {"destination": "Unexplored (North Of Burnt Forest"}
+
+STRATEGY:
+1. Explore systematically and travel to unexplored places. When relevant, explore up and down before exploring other directions.
+2. Pick up useful items. They will not be collected automatically; you have to manually collect them (e.g. "take sword").
+3. Open containers (mailbox, window, etc.)
+4. Use get_locations and get_unexplored_locations to avoid getting lost. Use 'travel' for faster travel.
+5. Turn on lamp before dark areas!
+
+DO NOT repeat the same action multiple times in a row."""
 
 
 # =============================================================================
-# Student Agent - IMPLEMENT THIS CLASS
+# Student Agent Implementation
 # =============================================================================
 
 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
+        """Initialize the agent state."""
+        self.history: list[dict] = []
+        self.score: int = 0
     
     async def run(
         self,
-        client,  # FastMCP Client connected to your MCP server
+        client,
         game: str,
         max_steps: int,
         seed: int,
         verbose: bool = False,
     ) -> RunResult:
-        """
-        Run the agent for a game session.
+        """Run the agent for a game session."""
+        locations_visited = set()
+        history = []
+        moves = 0
         
-        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
+        # Get list of available tools
+        tools = await client.list_tools()
+        tool_names = [t.name for t in tools]
         
-        # Example of calling a tool:
-        # result = await client.call_tool("play_action", {"action": "look"})
-        # observation = result[0].text if result else "No response"
+        # Get initial observation
+        observation, self.score, is_game_over = (await client.call_tool("play_action", {"action": "look"})).data
+        # result = self._extract_result(await client.call_tool("play_action", {"action": "look"}))
+        # observation = '\n'.join(result.split('\n')[:-2])
+        # self.score = max(self.score, int(result.split('\n')[-2]))
+        # is_game_over = bool(result.split('\n')[-1])
+
+        self.history.append({
+            "step": 0,
+            "thought": "This is the start of the game. I need to see what is around me.",
+            "tool": 'play_action',
+            "args": {'action': 'look'},
+            "result": observation,
+        })
         
-        # Example of calling the LLM:
-        # response = call_llm(
-        #     prompt="Current observation: " + observation,
-        #     system_prompt=SYSTEM_PROMPT,
-        #     seed=seed,
-        # )
+        # Track initial location
+        location = observation.split("\n")[0] if observation else "Unknown"
+        locations_visited.add(location)
         
-        # Placeholder implementation - replace with your code
-        locations_visited = set()
-        history = []
-        final_score = 0
-        moves = 0
+        if verbose:
+            print(self._entry_to_str(self.history[-1]))
         
-        # TODO: Your implementation here
-        # ...
+        # Main ReAct loop
+        for step in range(1, max_steps + 1):
+
+            # Make prompt from game history and call LLM
+            prompt = self._make_prompt()
+            response = call_llm(prompt, SYSTEM_PROMPT, seed + step)
+            
+            # Parse the response
+            thought, tool_name, tool_args = self._parse_response(response, tool_names)
+            
+            if verbose:
+                print(f"\n--- Step {step} ---")
+                print(f"THOUGHT: {thought}")
+                print(f"TOOL: {tool_name}")
+                print(f"ARGS: {tool_args}")
+            
+            # Validate and fix common issues
+            tool_name, tool_args = self._validate_tool_call(tool_name, tool_args, tool_names)
+            
+            # Execute the tool
+            try:
+                if tool_name == "play_action" or tool_name == "travel":
+                    moves += 1
+                    # result = self._extract_result(await client.call_tool(tool_name, tool_args))
+                    # observation = '\n'.join(result.split('\n')[:-2])
+                    # self.score = max(self.score, int(result.split('\n')[-2]))
+                    # is_game_over = bool(int(result.split('\n')[-1]))
+                observation, self.score, is_game_over = (await client.call_tool(tool_name, tool_args)).data
+                # else:
+                #     # observation = self._extract_result(await client.call_tool(tool_name, tool_args))
+                #     observation, = (await client.call_tool(tool_name, tool_args)).data
+
+
+            except Exception as e:
+                observation = f"Error: {e}"
+            
+            # Track location
+            location = observation.split("\n")[0] if observation else "Unknown"
+            locations_visited.add(location)
+            
+            # Update history
+            self.history.append({
+                'step': step,
+                'thought': thought,
+                'tool': tool_name,
+                'args': tool_args,
+                'result': observation,
+                'score': self.score,
+                'game_over': is_game_over,
+            })
+
+            if verbose:
+                print(f"GAME: {observation}")
+            
+            if is_game_over:
+                if verbose:
+                    print("\n*** GAME OVER ***")
+                break
         
         return RunResult(
-            final_score=final_score,
-            max_score=350,  # Zork1 max score, adjust if needed
+            final_score=self.score,
+            max_score=350,
             moves=moves,
             locations_visited=locations_visited,
-            game_completed=False,
+            game_completed=is_game_over,
             history=history,
         )
+
+    def _entry_to_str(self, entry: dict) -> str:
+        parts = []
+        parts.append(f"THOUGHT: {entry['thought']}")
+        parts.append(f"TOOL: {entry['tool']}")
+        parts.append(f"ARGS: {entry['args']}")
+        parts.append(f"GAME: {entry['result']}")
+        return '\n'.join(parts)
     
-    def _build_prompt(self, observation: str, history: list) -> str:
-        """
-        Build the prompt for the LLM.
+    def _make_prompt(self, n_past_steps: int = 4) -> str:
+        """Build the prompt for the LLM with context."""
+        parts = []
         
-        TODO: Implement this to create effective prompts
-        """
-        # TODO: Combine system prompt, history, and current observation
-        pass
+        # Recent history
+        parts.append("\nHere are the last things that happened:")
+        for entry in self.history[-n_past_steps:]:
+            parts.append(self._entry_to_str(entry))
+
+        parts.append(f"\nYou current score is {self.score}. Now it's your turn! What do you do next?")
+        return '\n'.join(parts)
     
-    def _parse_response(self, response: str) -> tuple[str, str, dict]:
-        """
-        Parse LLM response to extract thought, tool name, and arguments.
+    def _parse_response(self, response: str, valid_tools: list[str]) -> tuple[str, str, dict]:
+        """Parse the LLM response to extract thought, tool, and arguments."""
+        thought = "No reasoning provided"
+        tool_name = "play_action"
+        tool_args = {"action": "look"}
         
-        TODO: Implement robust parsing
+        lines = response.strip().split("\n")
         
-        Returns:
-            Tuple of (thought, tool_name, args_dict)
-        """
-        # TODO: Parse the response format:
-        # THOUGHT: ...
-        # TOOL: ...
-        # ARGS: {...}
-        pass
+        for line in lines:
+            line_clean = line.strip()
+            line_upper = line_clean.upper()
+            
+            if line_upper.startswith("THOUGHT:"):
+                thought = line_clean.split(":", 1)[1].strip()
+            
+            elif line_upper.startswith("TOOL:"):
+                raw_tool = line_clean.split(":", 1)[1].strip().lower()
+                raw_tool = raw_tool.replace("**", "").replace("*", "").replace("`", "")
+                raw_tool = raw_tool.split()[0] if raw_tool else "play_action"
+                tool_name = raw_tool
+            
+            elif line_upper.startswith("ARGS:"):
+                args_part = line_clean.split(":", 1)[1].strip()
+                try:
+                    args_part = args_part.replace("'", '"')
+                    tool_args = json.loads(args_part)
+                except json.JSONDecodeError:
+                    match = re.search(r'"action"\s*:\s*"([^"]+)"', args_part)
+                    if match:
+                        tool_args = {"action": match.group(1)}
+                    else:
+                        tool_args = {"action": "look"}
+        
+        return thought, tool_name, tool_args
     
-    def _call_llm(self, prompt: str, system_prompt: str, seed: int) -> str:
-        """
-        Call the LLM with the given prompt.
+    def _validate_tool_call(self, tool_name: str, tool_args: dict, valid_tools: list[str]) -> tuple[str, dict]:
+        """Validate and fix common tool call issues."""
+        # Fix tool name
+        if tool_name not in valid_tools:
+            if tool_name in ["action", "do", "command"]:
+                tool_name = "play_action"
+            elif tool_name in ["map", "location"]:
+                tool_name = "get_map"
+            elif tool_name in ["mem", "state", "status"]:
+                tool_name = "memory"
+            elif tool_name in ["inv", "items"]:
+                tool_name = "inventory"
+            else:
+                tool_name = "play_action"
         
-        This is a convenience wrapper - you can also use call_llm() directly.
-        """
-        return call_llm(prompt, system_prompt, seed)
+        # Fix action verbs
+        if tool_name == "play_action":
+            action = tool_args.get("action", "look")
+            
+            invalid_verb_map = {
+                "check": "examine",
+                "inspect": "examine",
+                "search": "look",
+                "grab": "take",
+                "pick": "take",
+                "use": "examine",
+                "investigate": "examine",
+            }
+            
+            words = action.lower().split()
+            if words and words[0] in invalid_verb_map:
+                words[0] = invalid_verb_map[words[0]]
+                action = " ".join(words)
+            
+            action = action.lower().strip()
+            action = action.replace("**", "").replace("*", "").replace("`", "")
+            action = " ".join(action.split())
+            
+            tool_args["action"] = action
+        
+        return tool_name, tool_args
+    
+    def _extract_result(self, result) -> str:
+        """Extract text from MCP tool result."""
+        # return result.data
+        if hasattr(result, 'content') and result.content:
+            return result.content[0].text
+        if isinstance(result, list) and result:
+            return result[0].text if hasattr(result[0], 'text') else str(result[0])
+        return str(result)
+    
+    def _update_score(self, text: str) -> None:
+        """Update score from game text."""
+        patterns = [
+            r'Score:\s*(\d+)',
+            r'score[:\s]+(\d+)',
+            r'\[Score:\s*(\d+)',
+        ]
+        
+        for pattern in patterns:
+            match = re.search(pattern, text, re.IGNORECASE)
+            if match:
+                self.score = max(self.score, int(match.group(1)))
+    
+    def _is_game_over(self, text: str) -> bool:
+        """Check if the game is over."""
+        game_over_phrases = [
+            "game over",
+            "you have died",
+            "you are dead",
+            "*** you have died ***",
+        ]
+        text_lower = text.lower()
+        return any(phrase in text_lower for phrase in game_over_phrases)
 
 
 # =============================================================================
-# For local testing
+# 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:
+    async with Client("mcp_server.py") as client:
         result = await agent.run(
             client=client,
             game="zork1",
-            max_steps=10,
+            max_steps=20,
             seed=42,
             verbose=True,
         )
         
-        print(f"\nFinal Score: {result.final_score}")
+        print(f"\n{'=' * 50}")
+        print(f"Final Score: {result.final_score}")
         print(f"Moves: {result.moves}")
-        print(f"Locations: {result.locations_visited}")
+        print(f"Locations: {len(result.locations_visited)}")
 
 
 if __name__ == "__main__":

mcp_server.py

@@ -1,209 +1,355 @@
 """
-Student MCP Server for Text Adventure Games
+Example: MCP Server for Text Adventures
 
-This is your MCP server submission. Implement the tools that your agent
-will use to play text adventure games.
-
-Required tool:
-    play_action(action: str) -> str
-        Execute a game command and return the result.
-
-Recommended tools:
-    memory() -> str
-        Return current game state, score, and recent history.
-    
-    inventory() -> str  
-        Return the player's current inventory.
-    
-    get_map() -> str
-        Return a map of explored locations.
-
-Test your server with:
-    fastmcp dev submission_template/mcp_server.py
-
-Then open the MCP Inspector in your browser to test the tools interactively.
+A complete MCP server that exposes text adventure games via tools.
+This demonstrates a full-featured server with memory, mapping, and inventory.
 """
 
 import sys
 import os
+from typing import Optional
+import networkx as nx
 
 # Add parent directory to path to import games module
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 from fastmcp import FastMCP
-from games.zork_env import TextAdventureEnv
+from games.zork_env import TextAdventureEnv, list_available_games
 
 
-# =============================================================================
-# Create the MCP Server
-# =============================================================================
+# Get game from environment variable (default: zork1)
+INITIAL_GAME = os.environ.get("GAME", "zork1")
 
-mcp = FastMCP("Student Text Adventure Server")
+# Create the MCP server
+mcp = FastMCP("Text Adventure Server")
 
+OPPOSITE_DIRECTION = {
+    'north': 'south',
+    'south': 'north',
+    'east': 'west',
+    'west': 'east',
+    'up': 'down',
+    'down': 'up',
+}
 
-# =============================================================================
-# Game State Management
-# =============================================================================
 
-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
-    """
+class GameState:
+    """Manages the text adventure game state and exploration data."""
     
-    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 = ""
-    
-    def initialize(self, game: str = "zork1"):
-        """Initialize or reset the game."""
+    def __init__(self, game: str = "zork1"):
         self.game_name = game
         self.env = TextAdventureEnv(game)
         self.state = self.env.reset()
-        # TODO: Reset your state tracking here
-        return self.state.observation
+        self.history: list[tuple[str, str]] = []
+        self.loc_history: list[Optional[str]] = [None]
+        self.graph: nx.DiGraph = nx.DiGraph() # graph of locations
+        self.current_location: str = self._extract_location(self.state.observation)
     
-    def step(self, action: str) -> str:
-        """Execute an action and return the result."""
-        if self.env is None:
-            self.initialize()
-        
+    def _extract_location(self, observation: str) -> Optional[str]:
+        """Extract location name from observation (usually first line)."""
+        lines = observation.strip().split('\n')
+        return lines[0] if lines[0].istitle() and lines[0][-1] not in ['.', '!', ',', ';', '?'] else None
+
+    def valid_actions(self) -> list[str]:
+        "Returns valid actions as computed by Jericho"
+        print("start get_valid_actions", file=sys.stderr)
+        va = self.env.env.get_valid_actions(use_object_tree=True, use_ctypes=True, use_parallel=False)
+        print("end get_valid_actions", file=sys.stderr)
+        return va
+
+    def _follow_direction(self, location: Optional[str], direction: str):
+        "Returns what happens in the graph if a direction is followed from a location."
+        if not self.graph.has_node(location):
+            return None
+        candidates = [v for _, v, data in self.graph.out_edges(location, data=True) if data['direction'] == direction]
+        return candidates[0] if len(candidates) > 0 else None
+    
+    def take_action(self, action: str) -> str:
+        """Execute a game action and return the result."""
         self.state = self.env.step(action)
+        result = self.state.observation
         
-        # TODO: Update your state tracking here
-        # self.history.append((action, self.state.observation))
-        # Update location tracking, etc.
+        # Track history
+        self.history.append((action, result))
         
-        return self.state.observation
+        #########################
+        # Update location graph #
+        #########################
+        new_loc = self._extract_location(result)
+        if new_loc is None:
+            return result
+
+        new_loc = new_loc.lower()
+        self.loc_history.append(new_loc)
+
+        # when location hasn't changed, nothing to do
+        if self.loc_history[-2] == new_loc:
+            return result
+
+        last_loc = self.loc_history[-2]
+
+        first_time_here = self.graph.has_node(new_loc)
+
+        # if we are not where we were supposed to go, update the graph accordingly
+        # this is done by deleting unsure edges between explored location and renaming unexplored locations
+        old_node = self._follow_direction(last_loc, action)
+        if old_node is not None and old_node != new_loc:
+            if self.graph.nodes(data=True)[old_node]['explored']:
+                self.graph.remove_edge(last_loc, old_node)
+            else:
+                nx.relabel_nodes(self.graph, {old_node: new_loc})
+
+        self.graph.add_node(new_loc, explored=True)
+
+
+        # add sure forward direction
+        if last_loc is not None:
+            self.graph.add_edge(last_loc, new_loc, direction=action, sure=True)
+
+        # add unsure backward direction if possible and useful
+        if action in OPPOSITE_DIRECTION.keys() and not self.graph.has_edge(new_loc, last_loc) and last_loc is not None:
+            self.graph.add_edge(new_loc, last_loc, direction=OPPOSITE_DIRECTION[action], sure=False)
+
+
+        # if first time in this location, add all valid directions that seem to be unexplored as unexplored locations
+        if not first_time_here:
+            return result
+
+        # for direction in ['north', 'south', 'east', 'west']:
+        for direction in set(self.valid_actions()) & set(OPPOSITE_DIRECTION.keys()):
+            if self._follow_direction(new_loc, direction) is not None:
+                continue
+            unexplored = f"unexplored ({direction} of {new_loc})".lower()
+            self.graph.add_node(unexplored, explored=False)
+            self.graph.add_edge(new_loc, unexplored, direction=direction, sure=True)
+            result += f"\nThere is a potentially unnexplored location {direction} of here."
+
+        return result
+
+    def travel(self, dest_loc: str) -> str:
+        cur_loc = self.loc_history[-1]
+        dest_loc = dest_loc.lower()
+
+        if dest_loc not in self.graph.nodes():
+            return f"\"{dest_loc.title()}\" is not the exact name of any location you have seen. You can get a list of locations you can travel to by using get_locations or get_unexplored_locations. Make sure you type the exact name of the (unexplored) location."
+        
+        # travel only through edges that are sure to exist if possible
+        sure_graph = nx.subgraph_view(self.graph, filter_edge = lambda u,v: self.graph[u][v]['sure'])
+
+        try:
+            path = nx.shortest_path(sure_graph, source=cur_loc, target=dest_loc)
+        except nx.NetworkXNoPath:
+            try:
+                path = nx.shortest_path(self.graph, source=cur_loc, target=dest_loc)
+            except nx.NetworkXNoPath:
+                return f"Cannot travel from {cur_loc.title()} to {dest_loc.title()} given current knowledge of the map. Did you type the location name properly?"
+
+        parts = []
+        for i in range(len(path)-1):
+            direction = self.graph[path[i]][path[i+1]]['direction']
+            parts.append(f"> {direction}\n")
+            parts.append(self.take_action(direction))
+
+            # if travel is not finished but location is unexpected, stop here
+            if i < len(path)-2 and self.loc_history[-1] != path[i+1]:
+                parts.append("This location is unexpected given your initial route. You stop travelling here.")
+                break
+        return '\n'.join(parts)
+
+    def get_locations(self, n_max=None, unexplored=False) -> str:
+        if unexplored:
+            graph = nx.subgraph_view(self.graph, filter_node = lambda u: not self.graph.nodes(data=True)[u]['explored'])
+        else:
+            graph = self.graph
+
+        all_paths = nx.single_source_shortest_path(self.graph, self.loc_history[-1])
+        all_paths = sorted(all_paths.values(), key=len)[1:]
+
+        if len(all_paths) == 0:
+            return f"No {'unexplored' if unexplored else ''} location automatically detected. Try something else and figure it out by yourself."
+
+        parts = []
+        parts.append(f"Current location: {self.loc_history[-1].title()}")
+        if n_max is None or len(all_paths) <= n_max:
+            parts.append(f"All {"unexplored" if unexplored else "known"} locations you can potentially travel to given your current knowledge:")
+        else:
+            parts.append(f"{n_max} closest {"unexplored" if unexplored else "known"} locations you can potentially travel to given your current knowledge:")
+
+        for path in all_paths:
+            parts.append(f"- {path[-1].title()}: {len(path)-1} step{'s' if len(path) > 2 else ''} away")
+            # parts.append(f"- {path[-1].title()} (current location -> {(' -> '.join(path[1:])).title()})")
+
+        return '\n'.join(parts)
+
+    def get_memory(self) -> str:
+        """Get a summary of current game state."""
+        recent = self.history[-5:] if self.history else []
+        recent_str = "\n".join([f"  > {a} -> {r[:60]}..." for a, r in recent]) if recent else "  (none yet)"
+        
+        return f"""Current State:
+- Location: {self.current_location}
+- Score: {self.state.score} points
+- Moves: {self.state.moves}
+- Game: {self.game_name}
+
+Recent Actions:
+{recent_str}
+
+Current Observation:
+{self.state.observation}"""
     
-    def get_score(self) -> int:
-        """Get current score."""
-        return self.state.score if self.state else 0
+    def get_map(self) -> str:
+        """Get a map of explored locations."""
+        if not self.explored_locations:
+            return "Map: No locations explored yet. Try moving around!"
+        
+        lines = ["Explored Locations and Exits:"]
+        for loc, exits in sorted(self.explored_locations.items()):
+            lines.append(f"\n* {loc}")
+            for exit_info in sorted(exits):
+                lines.append(f"    -> {exit_info}")
+        
+        lines.append(f"\n[Current] {self.current_location}")
+        return "\n".join(lines)
     
-    def get_moves(self) -> int:
-        """Get number of moves taken."""
-        return self.state.moves if self.state else 0
+    def get_inventory(self) -> str:
+        """Get current inventory."""
+        items = self.state.inventory if hasattr(self.state, 'inventory') and self.state.inventory else []
+        
+        if not items:
+            return "Inventory: You are empty-handed."
+        
+        item_names = []
+        for item in items:
+            item_str = str(item)
+            item_lower = item_str.lower()
+            if "parent" in item_lower:
+                idx = item_lower.index("parent")
+                name = item_str[:idx].strip()
+                if ":" in name:
+                    name = name.split(":", 1)[1].strip()
+                item_names.append(name)
+            elif ":" in item_str:
+                name = item_str.split(":")[1].strip()
+                item_names.append(name)
+            else:
+                item_names.append(item_str)
+        
+        return f"Inventory: {', '.join(item_names)}"
 
 
-# Global game manager
-_game = GameManager()
+# Global game state
+_game_state: GameState | None = None
 
 
-def get_game() -> GameManager:
-    """Get or initialize the game manager."""
-    global _game
-    if _game.env is None:
-        # Get game from environment variable (set by evaluator)
-        game = os.environ.get("GAME", "zork1")
-        _game.initialize(game)
-    return _game
+def get_game() -> GameState:
+    """Get or initialize the game state."""
+    global _game_state
+    if _game_state is None:
+        _game_state = GameState(INITIAL_GAME)
+    return _game_state
 
 
 # =============================================================================
-# MCP Tools - IMPLEMENT THESE
+# MCP Tools
 # =============================================================================
 
 @mcp.tool()
-def play_action(action: str) -> str:
+def play_action(action: str) -> tuple[str, int, bool]:
     """
-    Execute a game command and return the result.
+    Execute a game action in the text adventure.
+    
+    Args:
+        action: The command to execute (e.g., 'north', 'take lamp', 'open mailbox')
+    
+    Returns: tuple (result, score, game_over), where:
+    - result (str): The game's response to your action
+    - score (int): The current score
+    - game_over (bool): Whether or not the game is over
+    """
+    game = get_game()
+    result = game.take_action(action)
+    
+    # Add score info
+    score_info = f"\n\n[Score: {game.state.score} | Moves: {game.state.moves}]"
+    
+    if game.state.reward > 0:
+        result += f"\n\n+{game.state.reward} points! (Total: {game.state.score})"
     
-    This is the main tool for interacting with the game.
+    if game.state.done:
+        result += "\n\nGAME OVER"
+    else:
+        valid = [action for action in game.valid_actions() if action != 'jump'] # jump often means death
+        result += f"\n\nCurrent valid actions: {', '.join(valid)}"
+    
+    # return f"{result}\n{game.state.score}\n{int(game.state.done)}"
+    return result, game.state.score, game.state.done
+
+@mcp.tool()
+def travel(destination: str) -> tuple[str, int, bool]:
+    """
+    Travel to a location the user is aware of.
     
     Args:
-        action: The command to execute (e.g., "north", "take lamp", "open mailbox")
-        
-    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
+        destination: The name of the location to travel to
+    
+    Returns: tuple (result, score, game_over), where:
+    - result (str): The game's response to your action
+    - score (int): The current score
+    - game_over (bool): Whether or not the game is over
     """
     game = get_game()
+    result = game.travel(destination)
+    
+    # Add score info
+    score_info = f"\n\n[Score: {game.state.score} | Moves: {game.state.moves}]"
+    
+    if game.state.reward > 0:
+        result += f"\n\n+{game.state.reward} points! (Total: {game.state.score})"
+    
+    if game.state.done:
+        result += "\n\nGAME OVER"
+    else:
+        result += f"\n\nCurrent valid actions: {', '.join(game.valid_actions())}"
+    # return f"{result}\n{game.state.score}\n{int(game.state.done)}"
+    return result, game.state.score, game.state.done
+
+@mcp.tool()
+def get_locations() -> tuple[str, int, bool]:
+    "Get a list of all locations the player can go to."
+    game = get_game()
+    return game.get_locations(n_max=10), game.state.score, game.state.done
+
+@mcp.tool()
+def get_unexplored_locations() -> tuple[str, int, bool]:
+    "Get a list of all unexplored locations the player can go to."
+    game = get_game()
+    return game.get_locations(n_max=10, unexplored=True), game.state.score, game.state.done
+    # return get_game().get_locations(n_max=10, unexplored=True)
+
+@mcp.tool()
+def memory() -> tuple[str, int, bool]:
+    """
+    Get a summary of the current game state.
     
-    # TODO: You might want to add action validation here
-    # TODO: You might want to include score changes in the response
-    
-    result = game.step(action)
-    
-    # Optional: Append score info
-    # result += f"\n[Score: {game.get_score()} | Moves: {game.get_moves()}]"
-    
-    return result
-
-
-# TODO: Implement additional tools to help your agent
-
-# @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"
+    Returns location, score, moves, recent actions, and current observation.
+    """
+    game = get_game()
+    return game.get_memory(), game.state.score, game.state.done
+
+
+@mcp.tool()
+def inventory() -> tuple[str, int, bool]:
+    """
+    Check what items you are currently carrying.
+    """
+    game = get_game()
+    return game.get_inventory(), game.state.score, game.state.done
 
 
 # =============================================================================
-# Run the server
+# Main
 # =============================================================================
 
 if __name__ == "__main__":
-    # This runs the server with stdio transport (for MCP clients)
     mcp.run()

requirements.txt

@@ -7,3 +7,4 @@
 # Add any additional packages your agent needs below:
 # numpy
 # requests
+networkx