copied good agent code

agent.py

@@ -1,305 +1,439 @@
 """
-Student Agent for Text Adventure Games
+ReAct Agent Template 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.
+This is a starter template for building a ReAct agent that plays text adventures using MCP.
 
-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
+ReAct (Reasoning + Acting) is a simple but effective agent pattern:
+1. THINK: Reason about the current situation
+2. ACT: Choose and execute a tool
+3. OBSERVE: See the result
+4. Repeat until goal is achieved
 
-Required method:
-    async def run(self, client, game, max_steps, seed, verbose) -> RunResult
+Your task is to implement:
+1. Connect to the MCP server
+2. Implement the ReAct loop
+3. Use the LLM to generate thoughts and choose actions
 
-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
+TODO:
+1. Set up the MCP client connection
+2. Implement the agent loop
+3. Parse LLM responses to extract tool calls
 """
 
-import json
+import asyncio
 import os
-import re
-from dataclasses import dataclass, field
-from typing import Optional
-
-from dotenv import load_dotenv
 from huggingface_hub import InferenceClient
+from dotenv import load_dotenv
 
-# Load environment variables
-load_dotenv()
+# FastMCP client for connecting to MCP servers
+from fastmcp import Client
 
-# 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
+# Configuration
 # =============================================================================
 
-# 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
-
-    _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)
-
-
-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
-        max_tokens=max_tokens,
-        seed=seed,
-    )
-
-    return response.choices[0].message.content
+# Load environment variables
+load_dotenv()
 
+# LLM Configuration
+MODEL = os.getenv("HF_MODEL", "meta-llama/Llama-3.2-3B-Instruct")
+HF_TOKEN = os.getenv("HF_TOKEN")
 
-@dataclass
-class RunResult:
-    """Result of running the agent. Do not modify this class."""
-    final_score: int
-    max_score: int
-    moves: int
-    locations_visited: set[str]
-    game_completed: bool
-    error: Optional[str] = None
-    history: list[tuple[str, str, str]] = field(default_factory=list)
+if not HF_TOKEN:
+    raise ValueError("HF_TOKEN not found. Set it in your .env file.")
 
 
 # =============================================================================
-# System Prompt - Customize this for your agent
+# System Prompt - Instructions for the LLM
 # =============================================================================
 
-SYSTEM_PROMPT = """You are playing a classic text adventure game.
+SYSTEM_PROMPT = """You are playing a classic text adventure game. You are extremely intelligent and effective.
+You are both a good strategist and skilled at devising tactics. 
+You are very good at thinking outside the box when necessary, 
+but you are pragmatic and do not seek to be conspicuously clever,
+only when necessary and with the ultimate goal of maximising the score.
 
-GOAL: Explore the world, solve puzzles, and maximize your score.
+GOAL: Explore the world, solve puzzles, collect treasures, 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)
+AVAILABLE TOOLS will be indicated and described in the prompt.
+The main tools you can use to interact with the game is
+ play_action
+    
+    Execute a game action in the text adventure.
+    
+    This is the main tool for interacting with the game.
+    
+    Common commands:
+    - Movement: north, south, east, west, up, down
+    - Objects: take <item>, drop <item>, open <thing>
+    - Look: look, examine <thing>
+    
+    Args:
+        action: The command to execute (e.g., 'north', 'take lamp', 'open door')
+    
+ 
 
-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
+VALID GAME COMMANDS:
+- Movement: north, south, east, west, up, down
+- Objects: take <item>, drop <item>, open <thing>, examine <thing>
+- Light: turn on lamp
 
-RESPOND IN THIS EXACT FORMAT (no markdown):
-THOUGHT: <your reasoning about what to do next>
+RESPOND IN THIS EXACT FORMAT:
+THOUGHT: <your reasoning>
 TOOL: <tool_name>
-ARGS: <JSON arguments, e.g., {"action": "look"}>
+ARGS: <arguments as JSON, or empty {} if no args>
 
 Example:
-THOUGHT: I should look around to see where I am.
+THOUGHT: I see a container. I should open it to see what's inside.
 TOOL: play_action
-ARGS: {"action": "look"}
+ARGS: {"action": "open container"}
 """
 
 
 # =============================================================================
-# Student Agent - IMPLEMENT THIS CLASS
+# ReAct Agent Class
 # =============================================================================
 
-class StudentAgent:
+class ReActAgent:
     """
-    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
+    A ReAct agent that uses MCP tools to play text adventures.
     
-    Use the provided call_llm() function to interact with the LLM.
+    TODO: Complete this implementation!
     """
     
-    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:
+    def __init__(self, mcp_server_path: str):
         """
-        Run the agent for a game session.
+        Initialize the agent.
         
         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
+            mcp_server_path: Path to the MCP server script
         """
-        # 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,
-        )
+        self.mcp_server_path = mcp_server_path
+        self.llm = InferenceClient(token=HF_TOKEN)
+        self.history: list[dict] = []
+        self.available_tools = []
+        
+        # Summarization state
+        self.summary_interval = 4
+        self.game_summary = "Game started. No major events yet."
+    
+    async def run(self, max_steps: int = 50, verbose: bool = False):
+        """
+        Run the ReAct agent loop.
+        
+        TODO: Implement the main agent loop!
+        
+        Steps:
+        1. Connect to MCP server using FastMCP Client
+        2. Get initial observation (call play_action with "look")
+        3. Loop:
+           a. Build prompt with current observation
+           b. Call LLM to get thought and tool choice
+           c. Parse the response
+           d. Execute the chosen tool via MCP
+           e. Update history with observation
+           f. Check if done
+        """
+        # TODO: Implement the agent loop
+        # Hint: Use `async with Client(self.mcp_server_path) as client:`
+        
+        print("=" * 60)
+        print("Starting Text Adventure ReAct Agent")
+        print("=" * 60)
+        
+        # Connect to the MCP server
+        async with Client(self.mcp_server_path) as client:
+            # List available tools
+            tools = await client.list_tools()
+            print(f"\nAvailable tools: {[t.name for t in tools]}")
+            self.available_tools = await client.list_tools() # store available tools to pass later in the prompt
+            
+            # Get initial observation
+            result = await client.call_tool("play_action", {"action": "look"})
+            observation = result.content[0].text
+            print(f"\nInitial observation:\n{observation}\n")
+            
+            # Main loop
+            for step in range(1, max_steps + 1):
+                print(f"\n{'─' * 40}")
+                print(f"Step {step}")
+                print("─" * 40)
+                
+                # TODO: Build prompt for LLM
+                prompt = self._build_prompt(observation, verbose=verbose)
+                
+                # TODO: Call a LLM
+                response = self._call_llm(prompt)
+                
+                # TODO: Parse response to get tool and arguments
+                thought, tool_name, tool_args = self._parse_response(response)
+                
+                print(f"\nTHOUGHT: {thought}")
+                print(f"TOOL: {tool_name}")
+                print(f"ARGS: {tool_args}")
+                
+                # TODO: Execute the tool via MCP
+                try:
+                    result = await client.call_tool(tool_name, tool_args)
+                    observation = result.content[0].text
+                    print(f"\nRESULT:\n{observation}")
+                except Exception as e:
+                    observation = f"Error: {e}"
+                    print(f"\nERROR: {e}")
+                
+                # TODO: Update history
+                self.history.append({
+                    "thought": thought,
+                    "tool": tool_name,
+                    "args": tool_args,
+                    "result": observation
+                })
+                
+                # Check for game over
+                if "GAME OVER" in observation.upper():
+                    print("\n\nGame Over!")
+                    break
+                
+                # Periodic Summarization
+                if len(self.history) >= self.summary_interval:
+                    if verbose:
+                        print("\n" + "*" * 40)
+                        print("SUMMARIZING HISTORY...")
+                        print("*" * 40)
+                    
+                    new_summary = await self._update_summary(verbose=verbose)
+                    self.game_summary = new_summary
+                    self.history = [] # Clear history as it's now in the summary
+                    
+                    if verbose:
+                        print(f"NEW SUMMARY:\n{self.game_summary}\n")
+                        print("*" * 40 + "\n")
+        
+        print("\n" + "=" * 60)
+        print("Agent finished")
+        print("=" * 60)
     
-    def _build_prompt(self, observation: str, history: list) -> str:
+    def _build_prompt(self, observation: str, verbose: bool = False) -> str:
         """
         Build the prompt for the LLM.
         
-        TODO: Implement this to create effective prompts
+        TODO: Customize this to include relevant context!
+        
+        Consider including:
+        - Current observation
+        - Recent history (last few actions and results)
+        - Warnings about repeated actions
         """
-        # TODO: Combine system prompt, history, and current observation
-        pass
+
+        # AVAILABLE TOOLS (Dynamic with Schema)
+        import json
+        tool_infos = []
+        for t in self.available_tools:
+            # We include name, description AND the input schema so the LLM knows the arguments
+            schema = json.dumps(t.inputSchema, indent=2) if hasattr(t, 'inputSchema') else "{}"
+            info = f"- TOOL: {t.name}\n  DESCRIPTION: {t.description}\n  ARGUMENTS SCHEMA: {schema}"
+            tool_infos.append(info)
+        
+        tool_list = "\n\n".join(tool_infos)
+        TOOLS_PROMPT = f"\nAVAILABLE TOOLS:\n{tool_list}\n"
+        
+
+
+        parts = []
+        parts.append(TOOLS_PROMPT)
+        
+        
+        # Add Game Summary
+        parts.append(f"GAME SUMMARY (Context):\n{self.game_summary}\n")
+        
+        # Add recent history
+        if self.history:
+            parts.append("Recent actions:")
+            for entry in self.history[-10:]:
+                parts.append(f"  > {entry['tool']}({entry['args']}) -> {entry['result'][:150]}...")
+            parts.append("")
+        
+        # Current observation
+        parts.append(f"Current observation:\n{observation}")
+        parts.append("\nWhat do you do next?")
+        
+        if verbose:
+            print("\n" + "="*20 + " FULL PROMPT CONTENT " + "="*20)
+            for i, part in enumerate(parts):
+                print(f"--- PART {i+1} ---")
+                print(part.strip())
+            print("="*61 + "\n")
+            
+        return "\n".join(parts)
+
+    def _detect_loop(self) -> str:
+        """Analyze history for repetitive patterns and return a warning if found."""
+        if len(self.history) < 2:
+            return ""
+        
+        last = self.history[-1]
+        prev = self.history[-2]
+        
+        # Simple loop: same tool and same args
+        if last['tool'] == prev['tool'] and last['args'] == prev['args']:
+            return f"You are stuck! You just tried '{last['tool']}({last['args']})' and got the same result. DO NOT DO IT AGAIN. Use 'play_action' with a different command like 'go north', 'go south', or 'inventory'."
+        
+        # Pattern loop: check for A-B-A-B (last 4 actions)
+        if len(self.history) >= 4:
+            h = self.history
+            if h[-1]['args'] == h[-3]['args'] and h[-2]['args'] == h[-4]['args']:
+                return "You are oscillating in a circle. BLOCK this pattern. Go to a new room or try a completely new interaction like 'open mailbox' (if you haven't) or 'examine house'."
+                
+        return ""
     
+    def _call_llm(self, prompt: str) -> str:
+        """
+        Call the LLM to get the next action.
+        
+        TODO: Customize LLM parameters if needed.
+        """
+        try:
+            messages = [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": prompt}
+            ]
+            
+            response = self.llm.chat.completions.create(
+                model=MODEL,
+                messages=messages,
+                temperature=0.7,
+                max_tokens=200,
+            )
+
+            if False:
+                # printing messages (deving)
+                import json
+                print("\n" + "="*20 + " LLM MESSAGES " + "="*20)
+                print(json.dumps(messages, indent=2, ensure_ascii=False))
+                print("="*54 + "\n")
+
+
+            return response.choices[0].message.content
+        except Exception as e:
+            print(f"LLM Error: {e}")
+            return "THOUGHT: Error occurred.\nTOOL: play_action\nARGS: {\"action\": \"look\"}"
+        
     def _parse_response(self, response: str) -> tuple[str, str, dict]:
         """
-        Parse LLM response to extract thought, tool name, and arguments.
+        Parse the LLM response to extract thought, tool, and arguments.
         
-        TODO: Implement robust parsing
+        TODO: Make this more robust!
         
-        Returns:
-            Tuple of (thought, tool_name, args_dict)
+        Expected format:
+        THOUGHT: <reasoning>
+        TOOL: <tool_name>
+        ARGS: <json args>
         """
-        # TODO: Parse the response format:
-        # THOUGHT: ...
-        # TOOL: ...
-        # ARGS: {...}
-        pass
-    
-    def _call_llm(self, prompt: str, system_prompt: str, seed: int) -> str:
+        import json
+        
+        thought = ""
+        tool_name = "play_action"
+        tool_args = {"action": "look"}
+        
+        lines = response.strip().split("\n")
+        
+        for line in lines:
+            line_upper = line.upper().strip()
+            
+            if line_upper.startswith("THOUGHT:"):
+                thought = line.split(":", 1)[1].strip()
+            elif line_upper.startswith("TOOL:"):
+                tool_name = line.split(":", 1)[1].strip().lower()
+            elif line_upper.startswith("ARGS:"):
+                try:
+                    args_str = line.split(":", 1)[1].strip()
+                    tool_args = json.loads(args_str)
+                except (json.JSONDecodeError, IndexError):
+                    # Try to extract action from malformed args
+                    if "action" in args_str.lower():
+                        # Simple extraction for common case
+                        tool_args = {"action": "look"}
+        
+        return thought, tool_name, tool_args
+
+    async def _update_summary(self, verbose: bool = False) -> str:
+        """
+        Ask the LLM to update the game summary based on recent history.
         """
-        Call the LLM with the given prompt.
+        # Format the recent history for the summarizer
+        recent_text = ""
+        for entry in self.history:
+            recent_text += f"- Action: {entry['tool']} {entry['args']}\n  Result: {entry['result']}\n"
+            
+        summary_prompt = f"""
+        You are an intelligent summarizer for a text adventure agent.
+        
+        CURRENT SUMMARY:
+        {self.game_summary}
+        
+        NEW EVENTS (to be added):
+        {recent_text}
         
-        This is a convenience wrapper - you can also use call_llm() directly.
+        TASK:
+        Create a new, updated summary of the game so far.
+        - Combine the Current Summary and New Events.
+        - Keep it under 4 paragraphs.
+        - Focus on important clues, discovered locations, obtained items, and completed objectives.
+        - Discard repetitive navigation details (e.g. "went north, then south").
+        
+        RESPONSE:
+        Just the new summary text, nothing else.
         """
-        return call_llm(prompt, system_prompt, seed)
+        
+        try:
+            # We use a separate direct call logic or reuse _call_llm but we need to bypass the JSON format check
+            # Simpler to just call the client directly here for the specific task
+            messages = [{"role": "user", "content": summary_prompt}]
+            response = self.llm.chat.completions.create(
+                model=MODEL,
+                messages=messages,
+                temperature=0.5,
+                max_tokens=500,
+            )
+            return response.choices[0].message.content.strip()
+        except Exception as e:
+            print(f"Summarization failed: {e}")
+            return self.game_summary # Fallback to old summary
 
 
 # =============================================================================
-# For local testing
+# Main - Run the agent
 # =============================================================================
 
-async def test_agent():
-    """Test the agent locally."""
-    from fastmcp import Client
+async def main():
+    """Run the ReAct agent."""
+    import argparse
     
-    # Path to your MCP server
-    server_path = "mcp_server.py"
+    parser = argparse.ArgumentParser(description="Run the ReAct Text Adventure Agent")
+    parser.add_argument(
+        "--server", "-s",
+        default="templates/mcp_server_template.py",
+        help="Path to the MCP server script"
+    )
+    parser.add_argument(
+        "--max-steps", "-n",
+        type=int,
+        default=50,
+        help="Maximum steps to run"
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        default=False,
+        help="Show detailed output"
+    )
     
-    agent = StudentAgent()
+    args = parser.parse_args()
     
-    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}")
+    agent = ReActAgent(args.server)
+    await agent.run(max_steps=args.max_steps, verbose=args.verbose)
 
 
 if __name__ == "__main__":
-    import asyncio
-    asyncio.run(test_agent())
+    asyncio.run(main())

mcp_server.py

@@ -1,27 +1,15 @@
 """
-Student MCP Server for Text Adventure Games
+MCP Server Template for Text Adventure Games
 
-This is your MCP server submission. Implement the tools that your agent
-will use to play text adventure games.
+This is a starter template for building your text adventure MCP server.
+Your task is to implement the tools that allow an AI agent to play text adventures.
 
-Required tool:
-    play_action(action: str) -> str
-        Execute a game command and return the result.
+FastMCP makes it easy to create MCP servers - just decorate functions!
 
-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.
+TODO:
+1. Implement the play_action tool (required)
+2. Add helper tools like memory, get_map, inventory (recommended)
+3. Test your server with: fastmcp dev templates/mcp_server_template.py
 """
 
 import sys
@@ -38,172 +26,187 @@ from games.zork_env import TextAdventureEnv
 # Create the MCP Server
 # =============================================================================
 
-mcp = FastMCP("Student Text Adventure Server")
+# TODO: Create a FastMCP server instance
+# Hint: mcp = FastMCP("Your Server Name")
+mcp = FastMCP("Text Adventure Server")
 
 
 # =============================================================================
 # Game State Management
 # =============================================================================
 
-class GameManager:
+class GameState:
     """
     Manages the text adventure game state.
     
-    TODO: Extend this class to track:
-    - Action history (for memory tool)
+    TODO: You may want to extend this class to track:
+    - Action history (for context)
     - Explored locations (for mapping)
-    - Current score and moves
+    - Current location name
     """
+
+    def _clean_jericho_name(self, s: str) -> str:
+        """Clean raw Jericho string representations (e.g. 'Obj180: West House Parent...')."""
+        if not s: return s
+        if "Obj" in s and ":" in s:
+            # Extract name part: "Obj180: West House Parent..." -> "West House"
+            parts = s.split(":", 1)[1].strip()
+            if "Parent" in parts:
+                parts = parts.split("Parent")[0].strip()
+            return parts
+        return s
     
-    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
-    
-    def step(self, action: str) -> str:
-        """Execute an action and return the result."""
-        if self.env is None:
-            self.initialize()
+        # Track additional state
+        self.history = []
+        self.explored_locations = {}
+        self.summary = "No detailed memory yet. I have just started the game."
         
+        # Initial State Clean
+        if self.state.location:
+            self.state.location = self._clean_jericho_name(self.state.location)
+            # Add initial location to map
+            self.explored_locations[self.state.location] = 1
+    
+    def take_action(self, action: str) -> str:
+        """Execute a game action and return the result."""
+        action = action.strip()
         self.state = self.env.step(action)
+        self.history.append(action)
         
-        # TODO: Update your state tracking here
-        # self.history.append((action, self.state.observation))
-        # Update location tracking, etc.
+        # Clean location
+        if self.state.location:
+             self.state.location = self._clean_jericho_name(self.state.location)
         
+        # Track explored locations
+        if self.state.location and self.state.location != "Unknown":
+            count = self.explored_locations.get(self.state.location, 0)
+            self.explored_locations[self.state.location] = count + 1
+            
         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
 
 
-# Global game manager
-_game = GameManager()
+# Global game instance (created on first use)
+_game: GameState | None = None
 
 
-def get_game() -> GameManager:
-    """Get or initialize the game manager."""
+def get_game() -> GameState:
+    """Get or create the game instance."""
     global _game
-    if _game.env is None:
-        # Get game from environment variable (set by evaluator)
-        game = os.environ.get("GAME", "zork1")
-        _game.initialize(game)
+    if _game is None:
+        _game = GameState()
     return _game
 
 
 # =============================================================================
-# MCP Tools - IMPLEMENT THESE
+# MCP Tools - IMPLEMENT THESE!
 # =============================================================================
 
 @mcp.tool()
 def play_action(action: str) -> str:
     """
-    Execute a game command and return the result.
+    Execute a game action in the text adventure.
     
     This is the main tool for interacting with the game.
     
+    Common commands:
+    - Movement: north, south, east, west, up, down
+    - Objects: take <item>, drop <item>, open <thing>
+    - Look: look, examine <thing>
+    
     Args:
-        action: The command to execute (e.g., "north", "take lamp", "open mailbox")
-        
+        action: The command to execute (e.g., 'north', 'take lamp')
+    
     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
+        The game's response to your action
     """
+    # TODO: Implement this tool
+    # Hint: Use get_game().take_action(action)
     game = get_game()
+    result = game.take_action(action)
     
-    # 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()}]"
-    
+    # TODO: Optionally add score info or game over detection
     return result
 
 
-# TODO: Implement additional tools to help your agent
+# TODO: Implement additional helper tools
+# These are optional but will help your agent play better!
 
 # @mcp.tool()
 # def memory() -> str:
 #     """
-#     Get the current game state summary.
+#     Get a summary of the current game state.
 #     
-#     Returns:
-#         A summary including current location, score, moves, and recent history
+#     Returns location, score, recent actions, and current observation.
+#     Use this to understand where you are and what happened recently.
 #     """
-#     game = get_game()
-#     # TODO: Return useful state information
+#     # TODO: Implement this
 #     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 inventory() -> str:
+    """List the items currently carried."""
+    game = get_game()
+    items = game.state.inventory
+    if not items:
+        return "You are not carrying anything."
+    
+    # Clean item names
+    cleaned_items = [game._clean_jericho_name(i) for i in items]
+    return "Carrying:\n" + "\n".join(f"- {item}" for item in cleaned_items)
 
 
-# @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_map() -> str:
+    """List all locations visited so far."""
+    game = get_game()
+    if not game.explored_locations:
+        return "You haven't explored any locations yet."
+    
+    lines = ["Explored Locations:"]
+    for loc, count in game.explored_locations.items():
+        mark = " (Current)" if loc == game.state.location else ""
+        lines.append(f"- {loc} [Visited {count} times]{mark}")
+        
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_current_state() -> str:
+    """
+    Get a snapshot of the current game situation.
+    
+    Returns:
+    - Current Observation (what you see)
+    - Score and Moves
+    - Current Memory Notebook content
+    """
+    game = get_game()
+    info = [
+        "=== CURRENT GAME STATE ===",
+        f"Score: {game.state.score}/{game.state.max_score}",
+        f"Moves: {game.state.moves}",
+        f"Inventory (Last Known): {[game._clean_jericho_name(i) for i in game.state.inventory]}",
+        "",
+        "--- OBSERVATION ---",
+        game.state.observation,
+        "",
+        "--- NOTEBOOK ---",
+        game.summary
+    ]
+    return "\n".join(info)
 
 
-# @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"
 
 
 # =============================================================================
-# Run the server
+# Main - Run the server
 # =============================================================================
 
 if __name__ == "__main__":
-    # This runs the server with stdio transport (for MCP clients)
+    # This runs the server using stdio transport (for local testing)
     mcp.run()