Initial template

.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Environment
+.env
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -0,0 +1,59 @@
+---
+title: Text Adventure Agent Submission
+emoji: "\U0001F5FA"
+colorFrom: green
+colorTo: blue
+sdk: gradio
+sdk_version: "5.0.0"
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Text Adventure Agent Submission
+
+## Overview
+
+This is my submission for the Text Adventure Agent assignment. My agent uses the ReAct pattern to play text adventure games via MCP.
+
+## Approach
+
+<!-- Describe your approach here -->
+
+- 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 |
+| `mcp_server.py` | MCP server with game interaction tools |
+| `app.py` | Gradio interface for HF Space |
+| `requirements.txt` | Additional dependencies |
+
+## How to Submit
+
+1. Fork the template Space: `https://huggingface.co/spaces/LLM-course/text-adventure-template`
+2. Clone your fork locally
+3. Implement your agent in `agent.py` and `mcp_server.py`
+4. Test locally (see below)
+5. Push your changes to your Space
+6. Submit your Space URL on the course platform
+
+## Local Testing
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Test the MCP server interactively
+fastmcp dev mcp_server.py
+
+# Run your agent on a game
+python run_agent.py --agent . --game lostpig -v -n 20
+
+# Run evaluation
+python -m evaluation.evaluate -s . -g lostpig -t 3
+```

agent.py

@@ -0,0 +1,279 @@
+"""
+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
+"""
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+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.")
+
+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},
+    ]
+    
+    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
+
+
+@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)
+
+
+# =============================================================================
+# System Prompt - Customize this for your agent
+# =============================================================================
+
+SYSTEM_PROMPT = """You are playing a classic text adventure game.
+
+GOAL: Explore the world, solve puzzles, and maximize your score.
+
+AVAILABLE TOOLS (use via MCP):
+- play_action: Execute a game command (north, take lamp, open mailbox, etc.)
+- memory: Get current game state and history (if implemented)
+- inventory: Check what you're carrying (if implemented)
+
+VALID GAME COMMANDS for play_action:
+- Movement: north, south, east, west, up, down, enter, exit
+- Objects: take <item>, drop <item>, open <thing>, close <thing>, examine <thing>
+- Other: look, inventory, read <thing>, turn on lamp
+
+RESPOND IN THIS EXACT FORMAT (no markdown):
+THOUGHT: <your reasoning about what to do next>
+TOOL: <tool_name>
+ARGS: <JSON arguments, e.g., {"action": "look"}>
+
+Example:
+THOUGHT: I should look around to see where I am.
+TOOL: play_action
+ARGS: {"action": "look"}
+"""
+
+
+# =============================================================================
+# Student Agent - IMPLEMENT THIS CLASS
+# =============================================================================
+
+class StudentAgent:
+    """
+    Your ReAct agent implementation.
+    
+    TODO:
+    1. Implement the run() method with the ReAct loop
+    2. Parse LLM responses to extract tool calls
+    3. Track state and avoid loops
+    
+    Use the provided call_llm() function to interact with the LLM.
+    """
+    
+    def __init__(self):
+        """Initialize your agent here."""
+        # TODO: Initialize any state tracking you need
+        # self.history = []
+        # self.visited_locations = set()
+        pass
+    
+    async def run(
+        self,
+        client,  # FastMCP Client connected to your MCP server
+        game: str,
+        max_steps: int,
+        seed: int,
+        verbose: bool = False,
+    ) -> RunResult:
+        """
+        Run the agent for a game session.
+        
+        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]:
+        """
+        Parse LLM response to extract thought, tool name, and arguments.
+        
+        TODO: Implement robust parsing
+        
+        Returns:
+            Tuple of (thought, tool_name, args_dict)
+        """
+        # TODO: Parse the response format:
+        # THOUGHT: ...
+        # TOOL: ...
+        # ARGS: {...}
+        pass
+    
+    def _call_llm(self, prompt: str, system_prompt: str, seed: int) -> str:
+        """
+        Call the LLM with the given prompt.
+        
+        This is a convenience wrapper - you can also use call_llm() directly.
+        """
+        return call_llm(prompt, system_prompt, seed)
+
+
+# =============================================================================
+# For local testing
+# =============================================================================
+
+async def test_agent():
+    """Test the agent locally."""
+    from fastmcp import Client
+    
+    # Path to your MCP server
+    server_path = "mcp_server.py"
+    
+    agent = StudentAgent()
+    
+    async with Client(server_path) as client:
+        result = await agent.run(
+            client=client,
+            game="zork1",
+            max_steps=10,
+            seed=42,
+            verbose=True,
+        )
+        
+        print(f"\nFinal Score: {result.final_score}")
+        print(f"Moves: {result.moves}")
+        print(f"Locations: {result.locations_visited}")
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(test_agent())

app.py

@@ -0,0 +1,71 @@
+"""
+Hugging Face Space - Text Adventure Agent Submission
+
+This is a code-only Space for submitting your agent implementation.
+The evaluation is run separately.
+
+Files in this submission:
+- agent.py: Your ReAct agent implementation
+- mcp_server.py: Your MCP server implementation
+- requirements.txt: Additional dependencies
+
+To test locally:
+    fastmcp dev mcp_server.py
+    python agent.py
+"""
+
+import gradio as gr
+from pathlib import Path
+
+
+def read_readme():
+    """Read the README content."""
+    readme_path = Path(__file__).parent / "README.md"
+    if readme_path.exists():
+        return readme_path.read_text()
+    return "# Submission\n\nNo README.md found."
+
+
+def read_file_content(filename: str) -> str:
+    """Read a source file's content."""
+    file_path = Path(__file__).parent / filename
+    if file_path.exists():
+        return file_path.read_text()
+    return f"# File not found: {filename}"
+
+
+# Create the Gradio interface
+with gr.Blocks(title="Text Adventure Agent Submission") as demo:
+    gr.Markdown("# Text Adventure Agent Submission")
+    gr.Markdown(
+        "This Space contains a student submission for the Text Adventure Agent assignment. "
+        "Use the tabs below to view the submitted code."
+    )
+    
+    with gr.Tabs():
+        with gr.Tab("README"):
+            gr.Markdown(read_readme())
+        
+        with gr.Tab("Agent Code"):
+            gr.Code(
+                value=read_file_content("agent.py"),
+                language="python",
+                label="agent.py",
+            )
+        
+        with gr.Tab("MCP Server Code"):
+            gr.Code(
+                value=read_file_content("mcp_server.py"),
+                language="python",
+                label="mcp_server.py",
+            )
+    
+    gr.Markdown(
+        "---\n"
+        "**Note:** This is a code submission Space. "
+        "Evaluation is performed using the evaluation script."
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

mcp_server.py

@@ -0,0 +1,209 @@
+"""
+Student MCP Server for Text Adventure Games
+
+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.
+"""
+
+import sys
+import os
+
+# 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
+
+
+# =============================================================================
+# Create the MCP Server
+# =============================================================================
+
+mcp = FastMCP("Student Text Adventure Server")
+
+
+# =============================================================================
+# 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
+    """
+    
+    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."""
+        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()
+        
+        self.state = self.env.step(action)
+        
+        # TODO: Update your state tracking here
+        # self.history.append((action, self.state.observation))
+        # Update location tracking, etc.
+        
+        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()
+
+
+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
+# =============================================================================
+
+@mcp.tool()
+def play_action(action: str) -> str:
+    """
+    Execute a game command and return the result.
+    
+    This is the main tool for interacting with the game.
+    
+    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
+    """
+    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()}]"
+    
+    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"
+
+
+# =============================================================================
+# Run the server
+# =============================================================================
+
+if __name__ == "__main__":
+    # This runs the server with stdio transport (for MCP clients)
+    mcp.run()

requirements.txt

@@ -0,0 +1,9 @@
+# Required for HF Space display
+gradio>=4.0.0
+
+# Agent dependencies (these are provided by the evaluation infrastructure)
+# Do not add jericho, fastmcp, or huggingface_hub here - they are already installed
+
+# Add any additional packages your agent needs below:
+# numpy
+# requests