# Autonomous Agent for Text Adventure Games

## Overview
This repository contains an autonomous AI agent designed to navigate, solve puzzles, and maximize scores in classic text adventure games (like Zork) using Large Language Models (LLMs). The core challenge in solving these games is maintaining spatial awareness, managing inventory, and avoiding infinite loops caused by rigid game parsers.

## Experimental Approach: The Tri-Agent System (Discarded)
Initially, I experimented with a complex, multi-agent architecture designed to divide cognitive responsibilities. The system consisted of:
* **The Navigator:** Dedicated solely to spatial mapping and proposing movement actions (e.g., `north`, `enter`, `climb`). His main goal was to provide spatial awareness and to avoid looping.
* **The Detective:** Focused strictly on environmental observation and inventory management, proposing interaction commands (e.g., `take sword`, `examine leaves`, `open lantern`).
* **The Chief:** The ultimate decision-maker that evaluated the proposals from both the Navigator and the Detective to select the most optimal move.

**Conclusion:** While conceptually elegant, this method proved to be too "heavy" and inefficient compared to the next method. This complex delegation did not yield higher scores or better progression than simpler methods; the Chief agent often struggled to correctly weigh exploration against interaction, occasionally leading to decision paralysis.

## Current Architecture: State-Aware ReAct Agent (Active)
To optimize performance and context management, the architecture was streamlined into a single, highly state-aware agent using the **ReAct (Reasoning + Acting)** pattern. This approach blends programmatic state-tracking with LLM reasoning, essentially merging the "Detective" and "Navigator" roles into a highly structured context prompt.

### Key Features
* **Single-Agent ReAct Loop:** As suggested by the template, the agent uses a strict `THOUGHT -> TOOL -> ARGS` structure to reason about its immediate environment before committing to an action.
* **Lightweight Auto-Extraction (The "Mini-Detective"):** Whenever the agent enters a *new* room, a secondary, fast LLM call parses the room's description to extract a list of promising interactive objects (e.g., `["open mailbox", "move leaves"]`). These are injected into the main agent's prompt as targeted suggestions.
* **Robust Memory Tracking:**
    * **Spatial Graph:** Programmatically builds a directional map of visited locations and their connections.
    * **Room-Specific Logs:** Records exactly which actions have already been tried in the *current* room. This prevents the agent from repeating failed commands (e.g., trying to `take leaves` multiple times when the parser rejects it).
* **Anti-Looping "System Overrides":** If the agent remains in the same location for too many consecutive turns (e.g., $\ge 4$ turns) without progress, raise a warning into the prompt if this is the case. This forces the LLM to abandon its current task and use a movement command to explore elsewhere.