Implemented memory-driven agent with two-phase LLM approach (Priorization/Summarization)

.gitignore

@@ -20,3 +20,18 @@ venv/
 # OS
 .DS_Store
 Thumbs.db
+
+# game binaries / collections (do not commit)
+z-machine-games-master/
+**/*.z1
+**/*.z2
+**/*.z3
+**/*.z4
+**/*.z5
+**/*.z6
+**/*.z7
+**/*.z8
+**/*.zblorb
+**/*.blb
+**/*.zip
+

README.md

@@ -14,21 +14,42 @@ license: mit
 
 ## Overview
 
-This is my submission for the Text Adventure Agent assignment. My agent uses the ReAct pattern to play text adventure games via MCP.
+This agent uses a memory-driven architecture with a two-phase LLM approach to systematically explore text adventure games. At each step, the agent leverages Jericho's API to access valid actions and current location data, maintaining a structured memory dictionary that records location-specific information including tried actions, available actions, promising action subsets, and summarized outcomes.
+
+The core innovation is the dual LLM call strategy: first for strategic action selection with reasoning over promising action subsets (up to 10), and second for outcome summarization that ensures the agent actively "listens" to and learns from each action result. This approach balances comprehensive exploration with concise memory management, preventing context overflow while maintaining rich historical knowledge.
 
 ## Approach
 
-<!-- Describe your approach here -->
+### Memory Architecture
+
+The agent maintains a location-indexed memory dictionary with the following structure:
+- **valid_actions**: Location-specific actions from Jericho's API (verified to work)
+- **tried_actions**: Set of actions already attempted at this location
+- **promising_actions**: LLM-selected subset (max 10) of strategic actions to consider
+- **results**: For each tried action, stores {observation, summary, success, key_info}
+
+This structure allows the agent to return to previously visited locations with full context, enabling informed decision-making even with new inventory or changed game state.
+
+### Two-Phase LLM Strategy
+
+**Phase 1 - Action Selection**: The LLM receives current observation, game state (score, moves, inventory), and formatted location memory showing valid actions, previous promising actions, and tried actions with concise summaries (not overwhelming full text). The LLM then identifies up to 10 promising actions from available options and selects the single best action to execute, with explicit reasoning.
+
+**Phase 2 - Outcome Summarization**: After action execution, a second LLM call analyzes the full observation and generates a concise 1-2 sentence summary, success classification (yes/no/partial), and key information to remember. This summary is stored in memory, forcing the agent to actively process outcomes rather than passively accumulating raw text.
+
+### Key Strategic Features
+
+- **Object-focused exploration**: System prompt emphasizes that examining and interacting with props/objects is often critical for progress, with explicit guidance to try multiple interaction types (examine, take, open, read, push, pull, turn)
+- **Movement tracking**: Detects object movements in observations and provides hints to follow them
+- **Stagnation detection**: Monitors score progress and warns when exploration becomes circular
+- **Context preservation**: Full observations archived for debugging while summaries keep prompts manageable
+- **Dynamic re-evaluation**: Always recalculates promising actions on location revisits, accounting for changed context (new items, completed objectives)
 
-- What strategy does your agent use?
-- What tools did you implement in your MCP server?
-- Any interesting techniques or optimizations?
 
 ## Files
 
 | File | Description |
 |------|-------------|
-| `agent.py` | ReAct agent with `StudentAgent` class |
+| `agent.py` | Memory-driven agent with two-phase LLM approach |
 | `mcp_server.py` | MCP server with game interaction tools |
 | `app.py` | Gradio interface for HF Space |
 | `requirements.txt` | Additional dependencies |

agent.py

@@ -1,48 +1,32 @@
 """
-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
+Memory-driven agent with two-phase LLM approach:
+1. Action Selection: Choose promising actions (max 10) and pick best one
+2. Outcome Summarization: Summarize action result for memory storage
+
+Strategy:
+- Location memory tracks: valid_actions, tried_actions, promising_actions, results
+- Results store: {observation, summary, success, key_info} for each action
+- Agent sees concise summaries in context, not overwhelming full observations
+- Forces agent to "listen" by summarizing outcomes
 """
 
 import json
 import os
 import re
 from dataclasses import dataclass, field
-from typing import Optional
+from typing import Optional, Dict, Set, Any
 
 from dotenv import load_dotenv
 from huggingface_hub import InferenceClient
 
-# Load environment variables
 load_dotenv()
 
 # =============================================================================
 # LLM Configuration - DO NOT MODIFY
 # =============================================================================
 
-# Model to use (fixed for fair evaluation)
 LLM_MODEL = "Qwen/Qwen2.5-72B-Instruct"
 
-# Initialize the LLM client (uses HF_TOKEN from environment)
 _hf_token = os.getenv("HF_TOKEN")
 if not _hf_token:
     raise ValueError("HF_TOKEN not found. Set it in your .env file.")
@@ -50,45 +34,25 @@ if not _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,
-        )
-    """
+def call_llm(prompt: str, system_prompt: str, seed: int, max_tokens: int = 512) -> str:
     messages = [
         {"role": "system", "content": system_prompt},
         {"role": "user", "content": prompt},
     ]
-    
+
     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
 
 
 @dataclass
 class RunResult:
-    """Result of running the agent. Do not modify this class."""
     final_score: int
     max_score: int
     moves: int
@@ -99,152 +63,482 @@ class RunResult:
 
 
 # =============================================================================
-# System Prompt - Customize this for your agent
+# System Prompts - Two Phase Approach
 # =============================================================================
 
-SYSTEM_PROMPT = """You are playing a classic text adventure game.
+ACTION_SELECTION_SYSTEM_PROMPT = """You are playing a text adventure game to maximize score.
+
+GOAL: Explore systematically, solve puzzles, collect items, and maximize score.
+
+YOU WILL RECEIVE:
+- Current observation
+- Location memory with:
+  * VALID ACTIONS (from game engine - verified to work at this location)
+  * TRIED ACTIONS with summaries of outcomes (concise, LLM-generated)
+  * Previous promising actions (if you've been here before)
+
+YOUR TASK - ACTION SELECTION:
+1. Analyze the valid actions available
+2. Consider which actions you've already tried and their outcomes
+3. Identify up to 10 PROMISING ACTIONS from available options
+4. Choose the BEST action to try next
+
+STRATEGY GUIDELINES:
+- Prioritize untried actions from the valid list
+- **Objects are key**: When uncertain about next steps, examining or interacting with props/objects in the scene is often critical for progress
+- Pick up valuable items: lamp, lantern, torch, sword, keys, treasures, tools
+- Make sure you have a light sources before entering dark areas
+- Examine objects, open containers, read signs, search rooms thoroughly
+- Try multiple interactions with same object (examine, take, open, read, push, pull, turn)
+- If stagnating (no progress), try different location or different action type
+- Learn from previous outcomes: avoid repeating failures unless context changed
+- If "not see that there": object moved - explore elsewhere
+- Follow object movements mentioned in observations
 
-GOAL: Explore the world, solve puzzles, and maximize your score.
+RESPOND IN THIS EXACT FORMAT (no markdown):
+THOUGHT: <your strategic reasoning>
+PROMISING_ACTIONS: <JSON array of up to 10 promising actions to consider>
+CHOSEN_ACTION: <the single best action to execute>
+REASONING: <why this specific action is best>
 
-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)
+Example:
+THOUGHT: I'm in a dark area and need light. Valid actions show "turn on lamp". I haven't tried this yet.
+PROMISING_ACTIONS: ["turn on lamp", "examine lamp", "go back", "look", "inventory"]
+CHOSEN_ACTION: turn on lamp
+REASONING: Lamp is critical for exploring dark areas. Should activate it before moving forward.
+"""
 
-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
+OUTCOME_SUMMARY_SYSTEM_PROMPT = """You are analyzing the outcome of an action in a text adventure game.
+
+YOUR TASK - OUTCOME SUMMARIZATION:
+Given an action and its observation result, create a concise summary that captures:
+1. What happened (1-2 sentences max)
+2. Whether it succeeded, partially succeeded, or failed
+3. Key information to remember for future decisions
+
+Be CONCISE but capture critical details like:
+- Items acquired/lost
+- New areas discovered
+- Obstacles encountered
+- Score changes
+- Object movements
+- State changes (doors opened, lights turned on, etc.)
 
 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"}>
+OUTCOME_SUMMARY: <1-2 sentence summary>
+SUCCESS: <yes/no/partial>
+KEY_INFO: <key detail to remember>
 
-Example:
-THOUGHT: I should look around to see where I am.
-TOOL: play_action
-ARGS: {"action": "look"}
+Example action: "take lamp"
+Example observation: "Taken. The brass lamp is now in your inventory. [Score: 5 | Moves: 3]"
+
+Example response:
+OUTCOME_SUMMARY: Successfully picked up the brass lamp and added it to inventory.
+SUCCESS: yes
+KEY_INFO: Lamp acquired - can use for dark areas
 """
 
 
 # =============================================================================
-# Student Agent - IMPLEMENT THIS CLASS
+# Student Agent with Two-Phase LLM Approach
 # =============================================================================
 
 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.
-        
-        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
-        
-        # Example of calling a tool:
-        # result = await client.call_tool("play_action", {"action": "look"})
-        # observation = result[0].text if result else "No response"
-        
-        # Example of calling the LLM:
-        # response = call_llm(
-        #     prompt="Current observation: " + observation,
-        #     system_prompt=SYSTEM_PROMPT,
-        #     seed=seed,
-        # )
-        
-        # Placeholder implementation - replace with your code
-        locations_visited = set()
-        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]:
+        self.score = 0
+        self.moves = 0
+
+        # Enhanced location memory
+        self.location_memory: Dict[str, Dict[str, Any]] = {}
+        # Structure: {
+        #   "Location Name": {
+        #       "valid_actions": [...],
+        #       "tried_actions": set(),
+        #       "promising_actions": [...],
+        #       "visited": count,
+        #       "results": {
+        #           "action": {
+        #               "observation": "full text",
+        #               "summary": "concise summary",
+        #               "success": "yes/no/partial",
+        #               "key_info": "important detail"
+        #           }
+        #       }
+        #   }
+        # }
+
+        # Global tracking
+        self.locations_visited: set[str] = set()
+        self.inventory_items: set[str] = set()
+
+        # Stagnation detection
+        self.last_score_change_move: int = 0
+
+        # MCP client handle
+        self.env_handle = None
+
+    def _extract_result(self, result) -> str:
+        """Extract text from MCP tool result."""
+        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 _parse_action_selection(self, response: str) -> tuple[str, list[str], str]:
         """
-        Parse LLM response to extract thought, tool name, and arguments.
-        
-        TODO: Implement robust parsing
-        
-        Returns:
-            Tuple of (thought, tool_name, args_dict)
+        Parse action selection response.
+        Returns: (thought, promising_actions, chosen_action)
         """
-        # TODO: Parse the response format:
-        # THOUGHT: ...
-        # TOOL: ...
-        # ARGS: {...}
-        pass
-    
-    def _call_llm(self, prompt: str, system_prompt: str, seed: int) -> str:
+        thought = "Proceed with exploration"
+        promising_actions = []
+        chosen_action = "look"
+        reasoning = ""
+
+        for line in (response or "").splitlines():
+            line_stripped = line.strip()
+            line_upper = line_stripped.upper()
+
+            if line_upper.startswith("THOUGHT:"):
+                thought = line_stripped.split(":", 1)[1].strip()
+            elif line_upper.startswith("PROMISING_ACTIONS:"):
+                actions_str = line_stripped.split(":", 1)[1].strip()
+                try:
+                    # Try to parse as JSON array
+                    promising_actions = json.loads(actions_str)
+                    if not isinstance(promising_actions, list):
+                        promising_actions = []
+                except:
+                    # Fallback: comma-separated
+                    promising_actions = [a.strip().strip('"\'') for a in actions_str.split(",")]
+                    promising_actions = [a for a in promising_actions if a][:10]
+                
+            elif line_upper.startswith("CHOSEN_ACTION:"):
+                chosen_action = line_stripped.split(":", 1)[1].strip()
+                chosen_action = chosen_action.strip('"\'').strip()
+            elif line_upper.startswith("REASONING:"):
+                reasoning = line_stripped.split(":", 1)[1].strip()
+
+        # Ensure we have at least something
+        if not chosen_action or chosen_action == "":
+            chosen_action = "look"
+
+        return thought, promising_actions, chosen_action
+
+    def _parse_outcome_summary(self, response: str) -> tuple[str, str, str]:
         """
-        Call the LLM with the given prompt.
-        
-        This is a convenience wrapper - you can also use call_llm() directly.
+        Parse outcome summary response.
+        Returns: (summary, success, key_info)
         """
-        return call_llm(prompt, system_prompt, seed)
+        summary = "Action executed"
+        success = "unknown"
+        key_info = ""
+
+        for line in (response or "").splitlines():
+            line_stripped = line.strip()
+            line_upper = line_stripped.upper()
+
+            if line_upper.startswith("OUTCOME_SUMMARY:"):
+                summary = line_stripped.split(":", 1)[1].strip()
+            elif line_upper.startswith("SUCCESS:"):
+                success = line_stripped.split(":", 1)[1].strip().lower()
+            elif line_upper.startswith("KEY_INFO:"):
+                key_info = line_stripped.split(":", 1)[1].strip()
+
+        return summary, success, key_info
+
+    def _update_score_moves(self, obs: str) -> None:
+        """Extract score and moves from observation."""
+        m = re.search(r"\[Score:\s*(\d+)\s*\|\s*Moves:\s*(\d+)\]", obs)
+        if m:
+            new_score = int(m.group(1))
+            if new_score > self.score:
+                self.last_score_change_move = int(m.group(2))
+            self.score = max(self.score, new_score)
+            self.moves = max(self.moves, int(m.group(2)))
+
+    def _is_game_over(self, obs: str) -> bool:
+        t = (obs or "").lower()
+        return any(p in t for p in ["game over", "you have died", "you are dead", "*** you have died ***"])
+
+    async def _get_current_location_name(self, client) -> str:
+        """Get current location name from Jericho's get_player_location()."""
+        try:
+            res = await client.call_tool("get_player_location", {})
+            loc_info = self._extract_result(res)
+            return loc_info.strip()
+        except Exception as e:
+            return "Unknown"
+
+    async def _get_valid_actions_for_location(self, client) -> list[str]:
+        """Get valid actions from Jericho API."""
+        try:
+            res = await client.call_tool("get_valid_actions", {})
+            actions_str = self._extract_result(res)
+
+            if actions_str.startswith("{"):
+                data = json.loads(actions_str)
+                return data.get("actions", [])
+
+            return [a.strip() for a in actions_str.split(",") if a.strip()]
+        except Exception:
+            return []
+
+    def _format_location_memory_for_action_selection(self, loc_name: str) -> str:
+        """Format location memory for action selection prompt."""
+        if loc_name not in self.location_memory:
+            return "=== LOCATION MEMORY: First visit - no memory yet ===\n"
+
+        mem = self.location_memory[loc_name]
+        visit_count = mem["visited"]
+        valid_actions = mem["valid_actions"]
+        tried_actions = mem["tried_actions"]
+        results = mem["results"]
+        promising_actions = mem.get("promising_actions", [])
+
+        parts = [f"=== LOCATION MEMORY: {loc_name} (visited {visit_count} times) ==="]
+
+        # Valid actions from game engine
+        parts.append(f"\nVALID ACTIONS ({len(valid_actions)} available):")
+        parts.append(f"{', '.join(sorted(valid_actions))}")
+        parts.append("NOTE: These are location-specific actions verified by game engine.")
+        parts.append("Universal commands (look, inventory, wait) also work but aren't listed here.")
+
+        # Previous promising actions (if any)
+        if promising_actions:
+            parts.append(f"\nPREVIOUS PROMISING ACTIONS:")
+            parts.append(f"{', '.join(promising_actions)}")
+
+        # Tried actions with SUMMARIES (not full observations)
+        if results:
+            parts.append(f"\nTRIED ACTIONS ({len(tried_actions)} total):")
+            # Show most recent 8 with summaries
+            for action, action_result in list(results.items())[-8:]:
+                summary = action_result.get("summary", "No summary")
+                success = action_result.get("success", "unknown")
+                key_info = action_result.get("key_info", "")
+                
+                status_icon = "+" if success == "yes" else "-" if success == "no" else "~"
+                parts.append(f"  [{status_icon}] {action}")
+                parts.append(f"      → {summary}")
+                if key_info:
+                    parts.append(f"      [*] {key_info}")
+        else:
+            parts.append("\nTRIED ACTIONS: (none yet at this location)")
+
+        return "\n".join(parts)
+
+    def _build_action_selection_prompt(self, observation: str, current_location: str) -> str:
+        """Build prompt for Phase 1: Action Selection."""
+        parts = []
+
+        # Game state
+        parts.append(f"=== GAME STATE ===")
+        parts.append(f"Score: {self.score} | Moves: {self.moves}")
+        parts.append(f"Locations visited: {len(self.locations_visited)}")
+
+        if self.inventory_items:
+            parts.append(f"Inventory: {', '.join(sorted(self.inventory_items))}")
+
+        # Location memory (key context)
+        parts.append("\n" + self._format_location_memory_for_action_selection(current_location))
+
+        # Current observation
+        parts.append(f"\n=== CURRENT OBSERVATION ===")
+        parts.append(observation)
+
+        # Add strategic hints based on game state
+        hints = []
+
+        # Stagnation warning
+        moves_since_progress = self.moves - self.last_score_change_move
+        if moves_since_progress > 10:
+            hints.append(f"[!] No score progress in {moves_since_progress} moves!")
+            hints.append("    Consider: exploring new locations or trying different action types")
+
+        # Check for "not see that there" patterns
+        if current_location in self.location_memory:
+            mem = self.location_memory[current_location]
+            recent_failures = sum(1 for action, result in list(mem["results"].items())[-3:]
+                                if "not see that there" in result.get("observation", "").lower())
+            if recent_failures >= 2:
+                hints.append("[!] Multiple 'not see that there' errors - object likely moved elsewhere!")
+
+        # Check for object movement in observation
+        obs_lower = observation.lower()
+        if any(phrase in obs_lower for phrase in ["ran to", "run to", "went to", "moved to"]):
+            hints.append("[+] Object movement detected in observation - consider following it!")
+
+        if hints:
+            parts.append("\n=== STRATEGIC HINTS ===")
+            parts.extend(hints)
+
+        parts.append("\n=== YOUR TASK ===")
+        parts.append("Select up to 10 promising actions and choose the best one to execute.")
+
+        return "\n".join(parts)
+
+    def _build_outcome_summary_prompt(self, action: str, observation: str) -> str:
+        """Build prompt for Phase 2: Outcome Summarization."""
+        return f"""Action executed: "{action}"
+
+Observation received:
+{observation}
+
+Analyze this outcome and provide a concise summary."""
+
+    async def run(self, client, game: str, max_steps: int, seed: int, verbose: bool = False) -> RunResult:
+        result_history: list[tuple[str, str, str]] = []
+        moves_used = 0
+
+        # Discover available tools
+        tools = await client.list_tools()
+        tool_names = {t.name for t in tools}
+
+        # Initial look
+        try:
+            res = await client.call_tool("play_action", {"action": "look"})
+            obs = self._extract_result(res)
+            moves_used += 1
+            self._update_score_moves(obs)
+        except Exception as e:
+            return RunResult(self.score, 350, moves_used, self.locations_visited, False, error=str(e), history=result_history)
+
+        if verbose:
+            print(f"\n{obs}")
+
+        # Initial inventory check
+        if "inventory" in tool_names:
+            try:
+                inv_res = await client.call_tool("inventory", {})
+                inv_text = self._extract_result(inv_res).lower()
+                moves_used += 1
+
+                for item in ["torch", "lamp", "lantern", "sword", "key"]:
+                    if item in inv_text:
+                        self.inventory_items.add(item)
+
+                if verbose and self.inventory_items:
+                    print(f"[Starting inventory: {', '.join(self.inventory_items)}]")
+            except:
+                pass
+
+        # Main game loop
+        for step in range(1, max_steps - moves_used + 1):
+            # Get current location
+            current_location = await self._get_current_location_name(client)
+            self.locations_visited.add(current_location)
+
+            # Initialize or update location memory
+            if current_location not in self.location_memory:
+                valid_actions = await self._get_valid_actions_for_location(client)
+
+                self.location_memory[current_location] = {
+                    "tried_actions": set(),
+                    "valid_actions": valid_actions,
+                    "promising_actions": [],
+                    "visited": 1,
+                    "results": {}
+                }
+
+                if verbose:
+                    print(f"\n[New location: {current_location}]")
+                    print(f"[Valid actions: {len(valid_actions)}]")
+            else:
+                self.location_memory[current_location]["visited"] += 1
+
+            # ========================================================
+            # PHASE 1: ACTION SELECTION (LLM Call #1)
+            # ========================================================
+
+            prompt1 = self._build_action_selection_prompt(obs, current_location)
+            llm_response1 = call_llm(prompt1, ACTION_SELECTION_SYSTEM_PROMPT, seed + step, max_tokens=512)
+            
+            thought, promising_actions, chosen_action = self._parse_action_selection(llm_response1)
+
+            # Store promising actions in memory
+            self.location_memory[current_location]["promising_actions"] = promising_actions
+
+            if verbose:
+                print(f"\n--- Step {step} ---")
+                print(f"THOUGHT: {thought}")
+                print(f"PROMISING: {promising_actions}")
+                print(f"CHOSEN: {chosen_action}")
+
+            # ========================================================
+            # EXECUTE ACTION
+            # ========================================================
+
+            try:
+                res = await client.call_tool("play_action", {"action": chosen_action})
+                obs = self._extract_result(res)
+                moves_used += 1
+
+                # Track score changes
+                old_score = self.score
+                self._update_score_moves(obs)
+                if self.score > old_score:
+                    self.last_score_change_move = moves_used
+
+                if verbose:
+                    print(f"Observation: {obs}...")
+
+                # ========================================================
+                # PHASE 2: OUTCOME SUMMARIZATION (LLM Call #2)
+                # ========================================================
+
+                prompt2 = self._build_outcome_summary_prompt(chosen_action, obs)
+                llm_response2 = call_llm(prompt2, OUTCOME_SUMMARY_SYSTEM_PROMPT, seed + step + 10000, max_tokens=256)
+                
+                summary, success, key_info = self._parse_outcome_summary(llm_response2)
+
+                if verbose:
+                    print(f"SUMMARY: {summary}")
+                    print(f"SUCCESS: {success}")
+                    if key_info:
+                        print(f"KEY_INFO: {key_info}")
+
+                # ========================================================
+                # UPDATE MEMORY with summarized outcome
+                # ========================================================
+
+                mem = self.location_memory[current_location]
+                mem["tried_actions"].add(chosen_action)
+                mem["results"][chosen_action] = {
+                    "observation": obs,          # Full text preserved
+                    "summary": summary,          # LLM-generated summary
+                    "success": success,          # yes/no/partial
+                    "key_info": key_info        # Important detail
+                }
+
+                # Update inventory tracking
+                if "take" in chosen_action.lower() and success == "yes":
+                    words = chosen_action.split()
+                    if len(words) >= 2:
+                        item = words[-1]
+                        self.inventory_items.add(item)
+
+                # Record in history
+                result_history.append((thought, f"play_action({chosen_action})", obs))
+
+                if self._is_game_over(obs):
+                    break
+
+            except Exception as e:
+                result_history.append((thought, f"play_action({chosen_action})", f"Error: {e}"))
+                return RunResult(self.score, 350, moves_used, self.locations_visited, False, error=str(e), history=result_history)
+
+            if moves_used >= max_steps:
+                break
+
+        return RunResult(
+            final_score=self.score,
+            max_score=350,
+            moves=moves_used,
+            locations_visited=self.locations_visited,
+            game_completed=self._is_game_over(obs),
+            history=result_history,
+        )
 
 
 # =============================================================================
@@ -254,24 +548,21 @@ class StudentAgent:
 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,
+            game="lostpig",
+            max_steps=50,
             seed=42,
             verbose=True,
         )
-        
+
         print(f"\nFinal 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

@@ -49,41 +49,67 @@ class GameManager:
     """
     Manages the text adventure game state.
     
-    TODO: Extend this class to track:
-    - Action history (for memory tool)
-    - Explored locations (for mapping)
+    Tracks:
+    - Action history (for memory tool, though agent manages its own memory)
+    - Current location (using Jericho API)
     - Current score and moves
+    
+    Note: The agent handles its own location_memory system and doesn't rely
+    on server-side tracking beyond the core MCP tools.
     """
     
     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 = ""
+        # State tracking (for optional tools - agent manages its own memory)
+        self.history: list[tuple[str, str]] = []              # (action, observation)
+        self.current_location: str = "Unknown"
     
     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
+
+        # Reset tracking data
+        self.history = []
+        self.current_location = self._get_player_location_internal()
         return self.state.observation
     
+    def _get_player_location_internal(self) -> str:
+        """
+        Get current player location using Jericho API.
+        """
+        if self.env and hasattr(self.env, 'env') and self.env.env:
+            try:
+                # Access Jericho's get_player_location() which returns a ZObject
+                loc_obj = self.env.env.get_player_location()
+                # ZObject has a .name attribute
+                if hasattr(loc_obj, 'name'):
+                    return loc_obj.name
+            except Exception:
+                pass
+        return "Unknown"
+
     def step(self, action: str) -> str:
         """Execute an action and return the result."""
         if self.env is None:
             self.initialize()
-        
+
         self.state = self.env.step(action)
+        obs = self.state.observation
+
+        # Record history
+        self.history.append((action, obs))
+        if len(self.history) > 50:
+            self.history = self.history[-50:]
+
+        # Update current location using Jericho API
+        self.current_location = self._get_player_location_internal()
         
-        # TODO: Update your state tracking here
-        # self.history.append((action, self.state.observation))
-        # Update location tracking, etc.
-        
-        return self.state.observation
+        return obs
+
     
     def get_score(self) -> int:
         """Get current score."""
@@ -97,17 +123,6 @@ class GameManager:
 # Global game manager
 _game = GameManager()
 
-
-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
-
-
 # =============================================================================
 # MCP Tools - IMPLEMENT THESE
 # =============================================================================
@@ -132,72 +147,186 @@ def play_action(action: str) -> str:
     """
     game = get_game()
     
-    # 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()}]"
+    obs = game.step(action)
+
+    # Append score/moves info for the agent
+    score_info = f"\n\n[Score: {game.get_score()} | Moves: {game.get_moves()}]"
+
+    # If the environment exposes reward/done, include them (optional but helpful)
+    try:
+        if getattr(game.state, "reward", 0) and game.state.reward > 0:
+            score_info = f"\n\n+{game.state.reward} points! (Total: {game.get_score()})"
+    except Exception:
+        pass
+
+    done_info = ""
+    try:
+        if getattr(game.state, "done", False):
+            done_info = "\n\nGAME OVER"
+    except Exception:
+        pass
+
+    return obs + score_info + done_info
+
+
+@mcp.tool()
+def memory() -> str:
+    """
+    Get a summary of the current game state.
+
+    Returns:
+        A summary including current location, score, moves, and recent history
+    """
+    game = get_game()
+
+    recent = game.history[-5:] if game.history else []
+    if recent:
+        recent_str = "\n".join([f"  > {a} -> {obs[:80]}..." for a, obs in recent])
+    else:
+        recent_str = "  (none yet)"
+
+    return (
+        "Current State:\n"
+        f"- Location: {game.current_location}\n"
+        f"- Score: {game.get_score()} points\n"
+        f"- Moves: {game.get_moves()}\n"
+        f"- Game: {game.game_name}\n\n"
+        "Recent Actions:\n"
+        f"{recent_str}\n\n"
+        "Current Observation:\n"
+        f"{game.state.observation if game.state else ''}"
+    )
+
+@mcp.tool()
+def get_map() -> str:
+    """
+    Get a map of explored locations.
     
-    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"
+    Note: This tool is not used by the current agent implementation.
+    The agent manages its own location memory internally.
+
+    Returns:
+        A message indicating the agent doesn't use this tool
+    """
+    game = get_game()
+    return f"Current location: {game.current_location}\\n\\nNote: The agent manages location tracking internally via its location_memory system."
+
+@mcp.tool()
+def inventory() -> str:
+    """
+    Check what items you are currently carrying.
+    """
+    game = get_game()
+
+    items = []
+    try:
+        if getattr(game.state, "inventory", None):
+            items = game.state.inventory
+    except Exception:
+        items = []
+
+    if not items:
+        return "Inventory: You are empty-handed."
+
+    # Convert items to readable names
+    item_names = []
+    for item in items:
+        s = str(item)
+        s_lower = s.lower()
+        if "parent" in s_lower:
+            idx = s_lower.index("parent")
+            name = s[:idx].strip()
+            if ":" in name:
+                name = name.split(":", 1)[1].strip()
+            item_names.append(name)
+        elif ":" in s:
+            item_names.append(s.split(":", 1)[1].strip())
+        else:
+            item_names.append(s)
+
+    return "Inventory: " + ", ".join(item_names)
+
+def get_game() -> GameManager:
+    """Get or initialize the game manager."""
+    global _game
+
+    game_name = os.environ.get("GAME", "zork1")
+
+    if _game.env is None:
+        _game.initialize(game_name)
+    elif _game.game_name != game_name:
+        _game.initialize(game_name)
+
+    return _game
+
+
+@mcp.tool()
+def get_player_location() -> str:
+    """
+    Get the current player location name from Jericho's location tracking.
+
+    Returns:
+        The name of the current location (e.g., "West of House", "Forest")
+    """
+    game = get_game()
+
+    if game.env and hasattr(game.env, 'env') and game.env.env:
+        try:
+            # Access Jericho's get_player_location() which returns a ZObject
+            loc_obj = game.env.env.get_player_location()
+
+            # ZObject has a .name attribute
+            if hasattr(loc_obj, 'name'):
+                return loc_obj.name
+        except Exception as e:
+            pass
+
+    # Fallback: use heuristic location extraction
+    return game.current_location
+
+
+@mcp.tool()
+def get_valid_actions() -> str:
+    """
+    Get valid actions from Jericho's action space at the current location.
+
+    Returns:
+        JSON string with valid actions: {"available": true, "actions": [...], "count": N}
+    """
+    game = get_game()
+
+    if game.env and hasattr(game.env, 'env') and game.env.env:
+        try:
+            # CRITICAL: use_parallel=False to prevent deadlock on Lost Pig
+            valid_actions = game.env.env.get_valid_actions(
+                use_object_tree=True,
+                use_ctypes=True,
+                use_parallel=False  # Prevent multiprocessing deadlock
+            )
+
+            import json
+            return json.dumps({
+                "available": True,
+                "actions": valid_actions,
+                "count": len(valid_actions),
+                "source": "jericho"
+            })
+        except Exception as e:
+            import json
+            return json.dumps({
+                "available": False,
+                "error": str(e),
+                "actions": [],
+                "count": 0
+            })
+
+    import json
+    return json.dumps({
+        "available": False,
+        "error": "Game environment not initialized",
+        "actions": [],
+        "count": 0
+    })
 
 
 # =============================================================================

z-machine-games-master

@@ -0,0 +1 @@
+../z-machine-games-master