Upload 9 files

README.md

@@ -1,59 +1,127 @@
----
-title: Text Adventure Agent Submission
-emoji: "\U0001F5FA"
-colorFrom: green
-colorTo: blue
-sdk: gradio
-sdk_version: "5.12.0"
-app_file: app.py
-pinned: false
-license: mit
----
+# Zork Submission : MCP Agent
 
-# Text Adventure Agent Submission
+Ce projet présente un Agent ReAct couplé à un serveur MCP personnalisé pour jouer à des jeux d'aventures textuels (Zork, Lostpig). L'objectif est de dépasser les limites d'un LLM classique en enrichissant ses capacités d'observation, sa mémoire spatiale et sa stratégie décisionnelle.
 
-## Overview
 
-This is my submission for the Text Adventure Agent assignment. My agent uses the ReAct pattern to play text adventure games via MCP.
+## Architecture 
 
-## Approach
+L'architecture repose sur une séparation stricte entre la logique de jeu, serveur MCP, et la stratégie cognitive, l'Agent.
 
-<!-- Describe your approach here -->
+### Serveur MCP 
 
-- What strategy does your agent use?
-- What tools did you implement in your MCP server?
-- Any interesting techniques or optimizations?
+Le serveur MCP a été conçu pour fournir à l'agent des outils de haute précision en s'appuyant sur l'API Jericho. Son rôle est d'exposer des « vérités absolues » sur l'état interne du jeu, permettant ainsi de fiabiliser les actions de l'agent.
 
-## 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 |
+Le serveur met à disposition plusieurs outils clés :
 
-## 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
+- **get_location_info** : Extrait des données structurées sur la position actuelle (ID et nom du lieu, inventaire des objets présents et leur hiérarchie). 
 
-## Local Testing
 
-```bash
-# Install dependencies
-pip install -r requirements.txt
+- **get_valid_actions** : Utilise la fonction éponyme native de Jericho pour générer une liste d'actions valides et prêtes à l'emploi. Cela aide l'agent à choisir ou à construire des commandes syntaxiquement correctes.
 
-# Test the MCP server interactively
-fastmcp dev mcp_server.py
+- **play_action** : L'interface directe permettant à l'agent d'exécuter une commande et d'interagir avec l'univers du jeu.
 
-# Run your agent on a game
-python run_agent.py --agent . --game lostpig -v -n 20
+D'autres outils ont été partiellement implémentés pour détecter les sorties, tester la grammaire des actions ou identifier les interactions possibles avec un objet spécifique. Bien que prometteurs pour affiner la précision de l'agent, ces modules n'ont pas été finalisés ou utilisé par manque de temps. 
 
-# Run evaluation
-python -m evaluation.evaluate -s . -g lostpig -t 3
-```
+### Agent 
+
+L'agent repose sur une architecture ReAct, augmentée par plusieurs modules spécialisés. L'objectif est de transformer un agent purement réactif en une entité dotée d'une conscience sémantique et d'une mémoire spatiale, capable d'interpréter son environnement au-delà du simple texte.
+
+#### Observation Extractor 
+
+Ce module est crucial pour la compréhension de l'environnement. Au lieu de se contenter de stocker le texte brut des réponses du jeu, l'extracteur fusionne les données brutes issues de l'API Jericho avec les descriptions textuelles pour produire une synthèse structurée.
+
+- Synthèse de données : Il extrait et catégorise les informations essentielles (sorties visibles, entités, objets interactifs ou ramassables).
+
+- Précision syntaxique : Il identifie les noms exacts des objets utilisables dans les commandes, réduisant ainsi les erreurs de syntaxe.
+
+- Filtrage intelligent : Le but est de synthétiser au maximum les informations pour ne transmettre à l'agent que les données actionnables, évitant ainsi la surcharge cognitive du modèle.
+
+
+#### Guidance Priority
+
+Ce module agit comme le centre décisionnel de l'agent en hiérarchisant les tâches à accomplir. Il fournit un contexte riche et orienté vers l'action, structuré autour de plusieurs piliers :
+
+- Contexte immédiat : L'agent reçoit systématiquement le feedback de sa dernière action, l'historique des interactions spécifiques à la pièce actuelle, ainsi qu'un état des lieux des objets environnants.
+
+- Gestion des objets : Le module distingue les objets avec lesquels l'agent a déjà interagi (en précisant la dernière interaction) de ceux encore inexplorés. Cette distinction guide l'agent vers de nouvelles découvertes.
+
+- Actions suggérées : En combinant les actions de base et les commandes validées par l'outil get_valid_actions, le module propose un catalogue d'options pertinentes pour faciliter la prise de décision.
+
+- Régulation Comportementale :
+
+    - Contrôle de l'Exploration : Un compteur de temps  passé dans une localisation est intégré. S'il devient trop élevé, l'agent est incité à se déplacer pour éviter de rester bloqué sur un objet ou une énigme.
+
+    - Dynamisme : Des priorités spécifiques sont injectées lors d'événements clés, comme l'entrée dans une nouvelle zone ou une modification majeure de l'état du monde, favorisant systématiquement l'exploration de nouveaux lieux.
+
+#### World Mapper
+
+Pour pallier l'absence de vision spatiale native des LLM, un module de cartographie a été intégré sous la forme d'un graphe dynamique. Ce module permet à l'agent de maintenir une représentation persistante et structurée de l'univers de jeu.
+
+- Structure du graphe : La carte répertorie les localisations, les connexions entre elles , ainsi que les objets, puzzles et interactions spécifiques à chaque lieu.
+
+- Mémoire des déplacements : À partir des observations textuelles et des actions effectuées, le module enregistre non seulement les chemins validés, mais aussi les sorties potentielles mentionnées dans les descriptions et celles bloqués
+
+- Analyse des connecteurs : Le système distingue les sorties confirmées des passages bloqués ou impossibles, permettant ainsi d'anticiper l'impact des futurs déplacements.
+
+- Mise à jour temps réel : Le graphe est actualisé après chaque mouvement, observation ou changement d'état de l'environnement, garantissant que l'agent dispose toujours d'une vue d'ensemble fiable pour planifier ses actions.
+
+
+#### Mémoire des Actions
+
+Pour renforcer la cohérence temporelle, l'agent dispose d'une mémoire historique indexée par localisation. Ce module enregistre chaque commande, son résultat brut ainsi qu'un résumé synthétique de l'effet produit.
+
+- Récupération Contextuelle : Lors de la génération des directives (guidances), le système interroge cette mémoire pour extraire soit les 10 dernières actions effectuées, soit les interactions spécifiques liées à un objet précis.
+
+- Utilité : Cela permet à l'agent de ne pas répéter indéfiniment des tentatives infructueuses et de s'appuyer sur ses succès passés pour progresser.
+
+
+#### Critique de l'agent 
+
+Un module de critique a été implémenté pour évaluer la pertinence des décisions en temps réel. Après chaque action, un LLM secondaire analyse le résultat pour déterminer si l'objectif a été atteint ou non.
+
+- Auto-correction : Ce module identifie explicitement les erreurs de syntaxe dans l'appel des outils ou les actions redondantes (ex: essayer d'ouvrir une porte déjà ouverte).
+
+- Orientation stratégique : En explicitant les raisons d'un échec, la critique guide l'agent vers des alternatives plus logiques, transformant chaque erreur en une donnée d'apprentissage pour le tour suivant.
+
+## Pistes d'Amélioration et Expérimentations
+
+Cette section explicite les fonctionnalités testées puis écartées, ainsi que les perspectives. 
+
+
+#### Fonctionnalités écartés
+Plusieurs approches basées sur l'autonomie totale du LLM ont été testées :
+
+- Base de connaissances dynamique : J'ai tenté de laisser le LLM mettre à jour sa propre base de connaissances tous les 10 tours. Cependant, le modèle générait trop de "bruit" : informations verbeuses, répétitions malgré les consignes, et hallucinations sur l'état du monde. Cette surcharge d'informations inutiles polluait le prompt et dégradait les performances.
+
+- Mémoire générative vs Mémoire factuelle : Une tentative de mémoire gérée par LLM a montré les mêmes limites (redondances et inventions). J'ai donc privilégié une mémoire basée strictement sur les actions et les sorties réelles, plus fiable pour la prise de décision.
+
+#### Perpectives 
+
+Par manque de temps, certaines fonctionnalités structurantes n'ont pu être finalisées :
+
+- Module Stratège : L'implémentation d'un module stratége capable d'analyser la carte et l'inventaire pour élaborer des plans à long terme (décomposition en sous-objectifs). Cela permettrait de passer d'un agent purement "réactif" à un agent véritablement "proactif".
+
+- RAG (Retrieval-Augmented Generation) : L'intégration d'un système RAG pour interroger intelligemment la mémoire et la carte aurait permis d'affiner le contexte envoyé au LLM sans le surcharger.
+
+- Critique Renforcée : Un module de critique plus directif pour recadrer l'agent de manière plus autoritaire en cas de boucle d'actions infructueuse.
+
+## Analyse de performance 
+
+Le dépassement de la baseline reste un défi complexe et sujet à une certaine variabilité (runs, modèles, ajustement des prompts).
+
+- Comportement exploratoire : L'agent actuel privilégie une stratégie d'exploration intensive. S'il parvient à résoudre des énigmes, c'est souvent par une interaction systématique avec les objets de son environnement plutôt que par un raisonnement logique déduit de l'énigme elle-même.
+
+- Synergie agent-Mcp : Bien que la théorie préconise une indépendance totale, l'agent est ici étroitement couplé au serveur MCP pour maximiser l'utilisation des "sources de vérité". Ce choix a été fait pour garantir une découverte optimale des lieux et des objets, le serveur MCP servant de socle de fiabilité pour toutes les interactions. De plus dans la example il y avait déjà un couplage avec la première action d'appeller l'outil play_action en dur dans le code
+
+- Limites de raisonnement : L'agent manque encore d'une vision holistique de sa mission. Sa force réside dans sa capacité à cartographier et interagir, mais il ne possède pas encore le recul nécessaire pour prioriser des objectifs de haut niveau.
+
+
+## Conclusion
+
+Ce projet a permis de mettre en lumière la complexité de l'orchestration entre un LLM et un environnement dynamique via le protocole MCP.
+
+La leçon principale de ce travail est que les capacités intrinsèques du LLM sont secondaires par rapport à la qualité de l'architecture logicielle qui l'entoure (contexte, mémoire, modules déterministes). Au cours du développement, j'ai compris que confier des tâches trop complexes ou trop libres à l'agent mène souvent à l'échec.
+
+La clé du succès réside dans la création d'un cadre déterministe rigoureux : il est préférable de restreindre l'agent à des tâches simples et bien encadrées, soutenues par un contexte précis, plutôt que de compter sur une autonomie totale. En résumé, l'intelligence du système ne provient pas uniquement du modèle de langage, mais de la structure qui guide et valide chacune de ses actions.

adaptive_knowledge.py

@@ -0,0 +1,486 @@
+"""
+adaptive_knowledge.py
+Système complet de gestion des connaissances adaptatives pour l'Agent ReAct.
+Gère l'extraction, l'analyse, la qualité et la génération de la base de connaissances.
+"""
+
+import os
+import re
+import json
+from typing import Dict, List, Optional, Tuple
+
+# =============================================================================
+# 1. UTILITAIRES DE SECTIONS
+# =============================================================================
+class SectionUtils:
+    """
+    Utilitaires de section afin d'extraire des sections de markdown
+    """
+    @staticmethod
+    def extract_section_content(content: str, section_name: str) -> str:
+        if not content: return ""
+        
+        # On normalise le nom recherché pour la comparaison
+        # "LOCATION: Cave With Stream" -> "LOCATION: CAVE WITH STREAM"
+        target = section_name.strip().upper()
+        
+        lines = content.split('\n')
+        section_data = []
+        found = False
+        
+        for line in lines:
+            clean_line = line.strip().upper()
+            
+            # Détection du header (on vérifie si la ligne contient le nom de la section)
+            # Cela règle le problème des "## LOCATION: O\nutside"
+            if clean_line.startswith("##") and target in clean_line:
+                found = True
+                continue
+            
+            if found:
+                # Si on croise un autre header, on s'arrête
+                if clean_line.startswith("##"):
+                    break
+                section_data.append(line)
+        
+        return "\n".join(section_data).strip() if found else ""
+
+    @staticmethod
+    def update_section_content(content: str, section_name: str, new_content: str) -> str:
+        """
+        Mettre à jour une section de connaissance
+        """
+        if not content: content = "# Zork Strategic Knowledge Base\n\n"
+        section_header = f"## {section_name}"
+        pattern = rf"## {re.escape(section_name)}(.*?)(?=\n## |$)"
+        match = re.search(pattern, content, re.DOTALL)
+        
+        # Ajout de la nouvelle section
+        full_new_section = f"{section_header}\n\n{new_content}\n"
+        
+        # Si on a déjà une section on remplace sinon ajoute
+        if match:
+            return content.replace(match.group(0), full_new_section, 1)
+        else:
+            return f"{content}\n\n{full_new_section}\n"
+
+    @staticmethod
+    def extract_cross_episode_section(content: str) -> str:
+        """Extrait la section 'Wisdom' qui doit persister entre les parties."""
+        return SectionUtils.extract_section_content(content, "CROSS-EPISODE INSIGHTS")
+
+# =============================================================================
+# 2. ANALYSEUR DE TOURS (Turn Extraction & Quality)
+# =============================================================================
+class TurnAnalyzer:
+    """
+    Analyseur de tours de notre agent
+    """
+    @staticmethod
+    def format_turn_window(history: list, start_index: int, end_index: int) -> Dict:
+        """Convertit l'historique brut de l'agent en format structuré pour l'analyse."""
+        window = history[start_index:end_index]
+        
+        turn_data = {
+            "start_turn": start_index + 1,
+            "end_turn": end_index,
+            "actions": [],
+            "death_events": [],
+            "score_changes": []
+        }
+
+        prev_score = 0
+        if start_index > 0:
+            prev_score = history[start_index-1].get("score", 0)
+
+        for i, step in enumerate(window):
+            # Pour chaque élément de la fenêtre
+            turn_num = start_index + 1 + i
+            
+            # Action data
+            turn_data["actions"].append({
+                "turn": turn_num,
+                "thought": step.get("thought", ""),
+                "action": step.get("tool", "") + str(step.get("args", "")),
+                "result": step.get("result", "")
+            })
+
+            # Score tracking, tracking du score
+            current_score = step.get("score", 0)
+            if current_score != prev_score:
+                turn_data["score_changes"].append({
+                    "location": current_location,
+                    "action": step.get("tool", "") + str(step.get("args", "")),
+                    "explanation": step.get("result", ""),
+                    "turn": turn_num,
+                    "from": prev_score,
+                    "to": current_score
+                })
+                prev_score = current_score
+
+            # Death detection
+            if "game over" in step.get("result", "").lower() or "died" in step.get("result", "").lower():
+                turn_data["death_events"].append({
+                    "turn": turn_num,
+                    "reason": step.get("result", "")[:100], # Short preview
+                    "context": step.get("thought", "")
+                })
+
+        return turn_data
+
+    @staticmethod
+    def check_quality(turn_data: Dict) -> Tuple[bool, str]:
+        """Détermine si ces tours valent la peine d'être analysés."""
+        actions = turn_data["actions"]
+        
+        # Toujours analyser les changements de scores ou les morts
+        if turn_data["death_events"]: return True, "Death event detected"
+        if turn_data["score_changes"]: return True, "Score progression detected"
+        
+        # Véritifer si on a assez d'actions
+        if len(actions) < 2: return False, "Too few actions"
+
+        # 3. Vérifier la variété (éviter d'analyser quand l'agent boucle)
+        action_strs = [a["action"] for a in actions]
+        unique_actions = set(action_strs)
+        variety_ratio = len(unique_actions) / len(actions)
+
+        if variety_ratio < 0.2: 
+            return False, f"Low variety ({variety_ratio:.1%}) - repetitive behavior"
+
+        return True, "Sufficient quality data"
+
+# =============================================================================
+# 3. GÉNÉRATEUR DE CONNAISSANCES (LLM Prompts)
+# =============================================================================
+class KnowledgeGenerator:
+
+    GLOBAL_RULES = """
+- Player is a pragmatic adventurer.
+- Movement: use cardinal directions (n, s, e, w, u, d).
+- Interaction: You must 'examine' objects to find details.
+- Combat: player prefers to 'hit' or 'smash' threats.
+"""
+
+
+    SYSTEM_PROMPT = """
+    
+You are the Strategic Analyst for a text game Agent.
+Your goal is to update the 'Strategic Knowledge Base' based on recent gameplay logs.
+
+ARCHITECTURAL RULES:
+1. **Universal Scope**: Focus on mechanics that apply ANYWHERE (e.g., "Darkness kills without light").
+2. **Avoid Specifics**: Do NOT write "Go North from House". Write "Explore cardinal directions systematically".
+3. **Analyze Failure**: If the agent died, identify the CAUSE and the PRINCIPLE to avoid it.
+
+OUTPUT SECTIONS REQUIRED:
+- **UNIVERSAL GAME MECHANICS**: Rules of physics/parser (e.g., "Containers must be opened").
+- **DANGER CATEGORIES**: Types of threats (e.g., "Trolls require weapons").
+- **STRATEGIC PRINCIPLES**: Heuristics for decision making.
+- **DEATH & DANGER ANALYSIS**: Specific analysis of recent deaths.
+
+Preserve existing 'CROSS-EPISODE INSIGHTS' if provided.
+"""
+
+    KNOWLEDGE_DELTA_PROMPT = """You are the Knowledge Analyst for a text game Agent.
+Your goal is to extract strictly **ABSOLUTE RULES** and **STRATEGIC LESSONS**.
+
+Do NOT:
+- Do not list exits or room descriptions (this is handled by Memory).
+- Do not list items in the room.
+
+DO IDENTIFY:
+- Universal Mechanics: "Light is required in dark places", "Glass breaks when hit".
+- Danger Patterns: "Falling from heights is fatal", "Water traps require swimming".
+- High-Level Strategies: "Examine objects twice", "Save heavy items for later".
+
+INPUTS:
+1. EXISTING KNOWLEDGE: What we already know (do NOT repeat this).
+2. NEW LOGS: Recent gameplay history and ON CURRENT LOCATION
+
+INSTRUCTIONS:
+1. Compare the Logs against Existing Knowledge.
+2. Identify **ONLY** new information:
+   - New mechanics discovered.
+   - New map connections or object interactions.
+4. **SILENCE**: If nothing new happened, output "NO_UPDATES".
+5. ONLY output insights that are NOT already in the EXISTING KNOWLEDGE.
+6. Be concise: One bullet point per new discovery.
+7. DO NOT repeat the headers if you have no data for them.
+
+CRITICAL CONSTRAINTS:
+1. NO SURVIVAL TALK: GAME is not about food, water, or fatigue. Ignore these.
+2. NO REPETITION: If an idea is already in 'EXISTING KNOWLEDGE', skip it.
+3. BE TECHNICAL: Focus on "Item X opens Door Y" or "Light is needed in Dark rooms".
+4. NO SPECULATION: Do not invent dangers (like hostile pigs) unless the logs explicitly show the agent taking damage or dying.
+
+
+OUTPUT FORMAT (Markdown):
+Only output the sections that have NEW content. Do not output empty sections.
+
+## UNIVERSAL MECHANICS (New technical rules only)
+- [New rule found]
+
+## STRATEGIC LESSONS and STRATEGIC TIPS (New navigation/interaction heuristics)
+- [Strategy]
+- [New strategy found]
+
+## DANGER ANALYSIS
+- [Analysis of what killed player or blocked him]
+
+## SCORE EVENTS
+- [Action] in [Location] increased score because [Reason].
+
+"""
+
+    @staticmethod
+    def build_prompt(turn_data: Dict, existing_knowledge: str) -> str:
+
+        logs_str = ""
+        for a in turn_data["actions"]:
+            logs_str += f"Turn {a['turn']}:\n"
+            logs_str += f"  Thought: {a['thought']}\n"
+            logs_str += f"  Action: {a['action']}\n"
+            logs_str += f"  Result: {a['result'][:400]}...\n\n" # Truncate
+
+        # Events summary
+        events_str = ""
+        if turn_data["death_events"]:
+            events_str += f"*** DEATHS: {len(turn_data['death_events'])} ***\n"
+        if turn_data["score_changes"]:
+            events_str += f"*** SCORE CHANGES: {len(turn_data['score_changes'])} ***\n"
+
+        return f"""
+ANALYZE THIS GAMEPLAY WINDOW (Turns {turn_data['start_turn']}-{turn_data['end_turn']}):
+
+EVENTS:
+{events_str}
+
+LOGS:
+{logs_str}
+
+EXISTING KNOWLEDGE BASE:
+------------------------
+{existing_knowledge}
+------------------------
+
+INSTRUCTIONS:
+Update the Knowledge Base. 
+1. Incorporate lessons from the logs above.
+3. Remove duplicates.
+4. Output ONLY the NEW additions in Markdown format.
+"""
+
+# =============================================================================
+# 4. LE MANAGER PRINCIPAL (L'Orchestrateur)
+# =============================================================================
+class AdaptiveKnowledgeManager:
+    def __init__(self, output_file: str = "knowledgebase.md"):
+        self.output_file = output_file
+    
+    def get_strategic_knowledge(self:str) -> str:
+        full_kb = self.load_knowledge()
+        if not full_kb: return ""
+
+        universal = SectionUtils.extract_section_content(full_kb, "UNIVERSAL MECHANICS")
+        lessons = SectionUtils.extract_section_content(full_kb, "STRATEGIC LESSONS")
+        dangers = SectionUtils.extract_section_content(full_kb, "DANGER ANALYSIS")
+        score_events = SectionUtils.extract_section_content(full_kb, "SCORE EVENTS")
+    
+    
+        return f"""
+                    ### 📜 WORLD RULES
+                    {KnowledgeGenerator.GLOBAL_RULES}
+
+                    ### 🧠 EVOLVED STRATEGIES
+                    {universal if universal else ""}
+                    {lessons if lessons else ""}
+
+                    ### ⚠️ LETHAL LESSONS
+                    {dangers if dangers else "No fatal errors recorded yet."}
+                """
+        
+    def load_knowledge(self) -> str:
+        if os.path.exists(self.output_file):
+            with open(self.output_file, "r", encoding="utf-8") as f:
+                return f.read()
+        return ""
+
+    def update_knowledge(self, history: list, start_idx: int, end_idx: int, llm_function) -> bool:
+        """
+        Orchestre la mise à jour des connaissances.
+        Args:
+            history: La liste self.history de l'agent
+            start_idx: Début de la fenêtre
+            end_idx: Fin de la fenêtre
+            llm_function: La fonction call_llm(prompt, system_prompt) de l'agent
+        """
+        
+        print(f"\n[KNOWLEDGE] Assessing turns {start_idx+1}-{end_idx}...")
+
+        # 1. Extraction et formatage
+        turn_data = TurnAnalyzer.format_turn_window(history, start_idx, end_idx)
+
+        # 2. Vérification qualité (Est-ce que ça vaut le coup ?)
+        should_update, reason = TurnAnalyzer.check_quality(turn_data)
+        if not should_update:
+            print(f"[KNOWLEDGE] Skipping update: {reason}")
+            return False
+
+        # 3. Chargement existant
+        current_knowledge = self.load_knowledge()
+
+        # 4. Construction du Prompt
+        prompt = KnowledgeGenerator.build_prompt(turn_data, current_knowledge)
+
+        # 5. Appel LLM (Génération)
+        print(f"[KNOWLEDGE] Generating insights (Reason: {reason})...")
+        try:
+            # On utilise une température un peu plus haute pour la créativité analytique
+            # CORRECTION 1: On nomme la variable delta_response pour la suite
+            delta_response = llm_function(
+                prompt=prompt, 
+                system_prompt=KnowledgeGenerator.KNOWLEDGE_DELTA_PROMPT,
+                seed=42 
+            )
+            
+            # CORRECTION 2: Indentation alignée avec delta_response
+            if "NO_UPDATES" not in delta_response and len(delta_response) > 10:
+                # C'est ici que la magie opère : Python colle les bouts
+                new_full_knowledge = SmartKnowledgeMerger.merge_delta(current_knowledge, delta_response)
+            
+                # Sauvegarde (Attention: indentation DANS le if précédent car new_full_knowledge n'existe que si on rentre ici)
+                if new_full_knowledge != current_knowledge:
+                    with open(self.output_file, "w", encoding="utf-8") as f:
+                        f.write(new_full_knowledge)
+                    print(f"[KNOWLEDGE] Added new insights to database. (+{len(delta_response)} chars)")
+                    return True
+            
+        # CORRECTION 3: Ajout du bloc except obligatoire
+        except Exception as e:
+            print(f"[KNOWLEDGE] Error during generation: {e}")
+            
+        print("[KNOWLEDGE] No new insights found.")
+        return False
+
+
+import re
+
+class SmartKnowledgeMerger:
+    @staticmethod
+    def merge_delta(existing_content: str, delta_content: str) -> str:
+        if "NO_UPDATES" in delta_content or not delta_content.strip():
+            return existing_content
+
+        if not existing_content:
+            return "# Zork Strategic Knowledge Base\n\n" + delta_content
+
+        updated_content = existing_content
+        
+        # On découpe par sections principales (## HEADER)
+        sections = re.split(r'(## [A-Z :-_]+)', delta_content)
+        
+        current_header = None
+        for part in sections:
+            part = part.strip()
+            if not part: continue
+            
+            if part.startswith("##"):
+                current_header = part.replace("## ", "")
+            elif current_header:
+                # Si c'est une fiche lieu, on utilise un traitement spécial
+                if "LOCATION" in current_header:
+                    updated_content = SmartKnowledgeMerger._merge_location_sheet(
+                        updated_content, current_header, part
+                    )
+                else:
+                    # Traitement standard pour UNIVERSAL MECHANICS, DANGERS, etc.
+                    updated_content = SmartKnowledgeMerger._append_to_section(
+                        updated_content, current_header, part
+                    )
+        
+        return updated_content
+
+    # @staticmethod
+    # def _merge_location_sheet(full_text: str, location_header: str, new_sheet_data: str) -> str:
+    #     """Fusionne une fiche lieu en mettant à jour les champs spécifiques."""
+    #     pattern = rf"(## {re.escape(location_header)})(.*?)(?=\n## |$)"
+    #     match = re.search(pattern, full_text, re.DOTALL)
+        
+    #     if not match:
+    #         # Nouveau lieu, on l'ajoute simplement
+    #         return f"{full_text.strip()}\n\n## {location_header}\n{new_sheet_data}\n"
+
+    #     existing_body = match.group(2)
+        
+    #     # On fusionne les lignes préfixées (ex: - **EXITS**:, - **KNOWLEDGE**:)
+    #     # Cette logique permet d'écraser les listes d'objets ou d'ajouter des faits
+    #     new_lines = new_sheet_data.strip().split('\n')
+    #     updated_body = existing_body
+
+    #     for line in new_lines:
+    #         line = line.strip()
+    #         if not line: continue
+            
+    #         # Si la ligne est une catégorie (ex: - **ENTITIES**:), on vérifie si elle existe
+    #         prefix_match = re.match(r"(- \*\*[A-Z ]+\*\*):", line)
+    #         if prefix_match:
+    #             prefix = prefix_match.group(1)
+    #             # Si le préfixe existe déjà, on remplace la ligne (car les listes d'objets changent)
+    #             if prefix in updated_body:
+    #                 updated_body = re.sub(rf"{re.escape(prefix)}:.*", line, updated_body)
+    #             else:
+    #                 updated_body += f"\n{line}"
+    #         else:
+    #             # C'est un point de connaissance (Knowledge), on l'ajoute via _append_to_section logic
+    #             if line.lower() not in updated_body.lower():
+    #                 updated_body += f"\n{line}"
+
+    #     return full_text.replace(match.group(0), f"## {location_header}\n{updated_body}\n", 1)
+
+    @staticmethod
+    def _append_to_section(full_text: str, section_name: str, text_to_add: str) -> str:
+        """Ajoute du texte à la fin d'une section existante."""
+        new_lines = [l.strip() for l in text_to_add.strip().split('\n') if l.strip().startswith(('-', '*'))]
+
+        # Chercher la section
+        pattern = rf"(## {re.escape(section_name)})(.*?)(?=\n## |$)"
+        match = re.search(pattern, full_text, re.DOTALL)
+        
+        if match:
+            # La section existe, on ajoute à la fin
+            header = match.group(1)
+            existing_body = match.group(2).rstrip()
+
+            existing_lines_set = set([l.strip() for l in existing_body.strip().split('\n') if l.strip()])
+
+            
+            
+            filtered_new_lines = []
+            for nl in new_lines:
+                clean_nl = nl.lower()
+                if clean_nl in existing_body:
+                    continue
+
+                important_words = set([w for w in clean_nl.split() if len(w) > 4])
+                is_redundant = False
+                for existing_line in existing_body.split('\n'):
+                    words_in_existing = set([w for w in existing_line.split() if len(w) > 4])
+                    # Si plus de 70% des mots importants sont déjà dans une ligne existante
+                    if important_words and len(important_words & words_in_existing) / len(important_words) > 0.7:
+                        is_redundant = True
+                        break
+                    
+                if nl not in existing_lines_set and nl.lower() not in [el.lower() for el in existing_lines_set] and not is_redundant:
+                    filtered_new_lines.append(nl)
+                    existing_lines_set.add(nl) # On l'ajoute au set pour éviter les doublons au sein du même delta
+
+            if not filtered_new_lines:
+                return full_text # Rien de nouveau, on ne touche à rien
+                
+            # 4. Reconstruction propre
+            updated_body = existing_body.rstrip() + "\n" + "\n".join(filtered_new_lines)
+            return full_text.replace(match.group(0), f"{header}\n{updated_body}\n", 1)
+        else:
+            # La section n'existe pas, on la crée à la fin
+            return f"{full_text.strip()}\n\n## {section_name}\n{text_to_add}\n"

agent.py

@@ -1,26 +1,8 @@
 """
-Student Agent for Text Adventure Games
+Example: MCP ReAct Agent
 
-This is your submission file. Implement the StudentAgent class to play
-text adventure games using the MCP server you also implement.
-
-Your agent should:
-1. Connect to the MCP server via the provided client
-2. Use the ReAct pattern (Thought -> Action -> Observation)
-3. Call MCP tools to interact with the game
-4. Maximize the game score within the step limit
-
-Required method:
-    async def run(self, client, game, max_steps, seed, verbose) -> RunResult
-
-The 'client' is a FastMCP Client already connected to your MCP server.
-Use it to call tools like: await client.call_tool("play_action", {"action": "look"})
-
-Tips:
-- Start by looking around and understanding your environment
-- Keep track of visited locations to avoid loops
-- Pick up useful items (lamp, sword, etc.)
-- The seed parameter should be used to set your LLM's seed for reproducibility
+A complete ReAct agent that uses MCP tools to play text adventure games.
+This is a working example students can learn from.
 """
 
 import json
@@ -32,44 +14,43 @@ from typing import Optional
 from dotenv import load_dotenv
 from huggingface_hub import InferenceClient
 
-# Load environment variables
+from typing import List, Optional, Dict
+from pydantic import BaseModel
+import json
+
+from adaptive_knowledge import AdaptiveKnowledgeManager
+from spatial_memory import SpatialMemorySystem
+from memory import HierarchicalMemoryManager
+from prompts import (
+    SYSTEM_PROMPT,
+    PLANNER_SYSTEM_PROMPT,
+    EXTRACTOR_SYSTEM_PROMPT,
+    CRITIC_SYSTEM_PROMPT,
+    MEMORY_SYNTHESIS_PROMPT
+)
+
 load_dotenv()
 
 # =============================================================================
 # LLM Configuration - DO NOT MODIFY
 # =============================================================================
 
-# Model to use (fixed for fair evaluation)
 LLM_MODEL = "Qwen/Qwen2.5-72B-Instruct"
+# LLM_MODEL = "Qwen/Qwen2.5-72B-Instruct:featherless-ai"
+# LLM_MODEL = "Qwen/Qwen2.5-72B-Instruct::fireworks-ai"
+# LLM_MODEL = "Qwen/Qwen2.5-1.5B-Instruct"
+# LLM_MODEL = "Qwen/Qwen2.5-7B-Instruct"
+# LLM_MODEL = "meta-llama/Llama-3.2-3B-Instruct"
+# LLM_MODEL = "mistralai/Mistral-7B-Instruct-v0.3"
 
-# 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,
-        )
-    """
+    """Call the LLM with the given prompt."""
     messages = [
         {"role": "system", "content": system_prompt},
         {"role": "user", "content": prompt},
@@ -78,7 +59,7 @@ def call_llm(prompt: str, system_prompt: str, seed: int, max_tokens: int = 300)
     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,
     )
@@ -99,179 +80,1923 @@ class RunResult:
 
 
 # =============================================================================
-# System Prompt - Customize this for your agent
+# Student Agent Implementation
 # =============================================================================
 
-SYSTEM_PROMPT = """You are playing a classic text adventure game.
+class StudentAgent:
+    """
+    MCP ReAct Agent - A complete working example.
+    
+    This agent demonstrates:
+    - ReAct loop (Thought -> Tool -> Observation)
+    - Loop detection
+    - Action validation
+    - Score tracking via memory tool
+    """
+    
+    def __init__(self):
+        """Initialize the agent state."""
+        self.history: list[dict] = []
+        self.recent_actions: list[str] = []
 
-GOAL: Explore the world, solve puzzles, and maximize your score.
+        self.score: int = 0
+        self.strategist = StrategyModule()
 
-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)
+        self.critic = CriticAgent(call_llm_func=call_llm, verbose=True)
+        self.knowledge_manager = AdaptiveKnowledgeManager("knowledgebase.md")
+        self.world_mapper = WorldMapper()
 
-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
+        self.extractor = ObservationExtractor(call_llm)
 
-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"}>
+        self.learning_interval = 10
+        self.last_learning_step = 0
+        self.seen_responses = {}
 
-Example:
-THOUGHT: I should look around to see where I am.
-TOOL: play_action
-ARGS: {"action": "look"}
-"""
+        self.last_room_id = None     # Utilise celui-ci pour la logique ID
+        self.last_world_hash = None
 
+        self.memory_manager = HierarchicalMemoryManager(call_llm)
+        self.current_location = "Start"
+        self.location_action_memory = {}
 
-# =============================================================================
-# Student Agent - IMPLEMENT THIS CLASS
-# =============================================================================
+        self.steps_in_current_room = 0
+
+        self.current_room_actions = set() 
+        
 
-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.
+            self,
+            client,
+            game: str,
+            max_steps: int,
+            seed: int,
+            verbose: bool = False,
+        ) -> RunResult:
+            """Run the agentknowledge_content = self.knowledge_manager.load_knowledge()
+                    if verbose and knowledge_content:
+                        print(f"\n[INIT] Loaded strategic knowledge ({len(knowledge_content)} chars)")
+             for a game session."""
+            locations_visited = set()
+            history = []
+            moves = 0
+
+            # Charger la connaissance au démarrage
+            knowledge_content = self.knowledge_manager.load_knowledge()
+            if verbose and knowledge_content:
+                print(f"\n[INIT] Loaded strategic knowledge ({len(knowledge_content)} chars)")
+
+            # Get list of available tools
+            tools = await client.list_tools()
+            tool_names = [t.name for t in tools]
+            
+            # Get initial observation
+            result = await client.call_tool("play_action", {"action": "look"})
+            observation = self._extract_result(result)
+
+            loc_result = await client.call_tool("get_location_info", {})
+            raw_res = self._extract_result(loc_result)
+
+            if isinstance(raw_res, str):
+                    import json
+                    loc_dict = json.loads(raw_res)
+            else:
+                loc_dict = raw_res
+            
+            structured_data = self.extractor.extract(
+                                        raw_text=observation, 
+                                        seed=seed + 0, 
+                                        ram_data=loc_dict, 
+                                        last_location=self.current_location
+                                        )
+
+            self.world_mapper.update_map(structured_data, "look", observation)
         
-        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
+          
+            # Track initial location
+            # location = observation.split("\n")[0] if observation else "Unknown"
+            # locations_visited.add(location)
+            
+            if verbose:
+                print(f"\n{observation}")
+            
+            # Main ReAct loop
+            for step in range(1, max_steps + 1):
+
+                raw_possible_actions = "No actions available"
+                structured_data = {"location_name": self.current_location, "is_new_location": False}
+                priority_guidance = ""
+
+                try:
+                    inv_result = await client.call_tool("inventory", {})
+                    current_inv = self._extract_result(inv_result)
+
+                    loc_result = await client.call_tool("get_location_info", {})
+                    raw_res = self._extract_result(loc_result)
+
+                    if isinstance(raw_res, str):
+                        import json
+                        loc_dict = json.loads(raw_res)
+                    else:
+                        loc_dict = raw_res
+
+                    if loc_dict.get("status") == "success":
+                        current_loc_id = loc_dict["location"].get("id")
+                        current_loc_name = loc_dict["location"].get("name")
+                        current_world_hash = loc_dict.get("world_hash")
+
+                        objects_in_room = [obj["name"] for obj in loc_dict.get("detected_objects", [])]
+                    else:
+                        print("⚠️ Erreur lors de la récupération des données RAM")
+
+                    is_new_room = False
+                    if current_loc_id != self.last_room_id:
+                        is_new_room = True
+                        self.steps_in_current_room = 0
+                        print(f"🚀 Mouvement détecté vers : {current_loc_name} (ID: {current_loc_id})")
+                        self.last_room_id = current_loc_id
+                        self.current_location = current_loc_name
+                    else : 
+                        self.steps_in_current_room += 1
+
+                    world_changed = False
+                    if current_world_hash != self.last_world_hash:
+                        world_changed = True
+                        print(f"🔍 Le monde a changé (objet déplacé/modifié)")
+                        self.last_world_hash = current_world_hash
+                        
+                    
+                    map_result = await client.call_tool("get_map", {})
+                    current_map = self._extract_result(map_result)
+
+                    # Extraction structurée
+                    structured_data = self.extractor.extract(
+                                        raw_text=observation, 
+                                        seed=seed + step, 
+                                        ram_data=loc_dict, 
+                                        last_location=self.current_location
+                                        )
+
+                    print("structured_data run loop ", structured_data)
+
+                    structured_data["location_id"] = current_loc_id
+                    structured_data["location_name"] = current_loc_name
+                    structured_data["is_new_location"] = is_new_room
+                    structured_data["world_changed"] = world_changed
+
+                    should_refresh_actions = is_new_room or world_changed
+
+                    if should_refresh_actions:
+                        cheat_result = await client.call_tool("get_valid_actions_cheat", {})
+                        new_actions = self._extract_result(cheat_result)
+                        
+                        if is_new_room:
+                            self.current_room_actions = set()
+                        
+                        if isinstance(new_actions, list):
+                            self.current_room_actions.update(new_actions)
+                        elif isinstance(new_actions, str):
+                            self.current_room_actions.update([a.strip() for a in new_actions.split(',')])
+
+                    structured_data["cheat_actions"] = list(self.current_room_actions)
+
+                    # valid_actions_result = await client.call_tool("get_valid_actions_cheat", {})
+                    # raw_possible_actions = self._extract_result(valid_actions_result)
+                    priority_guidance = self._build_priority_guidance(structured_data)
+                    print("priority guidance",priority_guidance)
+                    print("fin PRIORITY")
+
+                except Exception as e:
+                    print(f"⚠️ Sensory Error: {e}")
+                    structured_data = {}
+                    current_inv = "Unknown"
+                    current_map = "Unknown"
+                
+                is_urgent = False
+
+                enriched_actions = self._generate_enriched_actions(structured_data)
+
+                # strategic_knowledge = self.knowledge_manager.get_strategic_knowledge()
+
+                # memory_context = self.memory_manager.get_context(self.current_location)
+                
+                # visible_exits = structured_data.get("visible_exits", [])
+                # visible_objs = structured_data.get("visible_objects", [])
+                # visible_entities = structured_data.get("visible_entities", [])
+                # is_urgent = structured_data.get("in_combat_or_chase", False)
+                # summary = structured_data.get("description_summary", "")
+
+
+                # if hasattr(self, 'memory_manager'):
+                #     memory_context = self.memory_manager.get_context(current_loc)
+                # else:
+                #     memory_context = ""
+
+                # ============================================================
+                # 1. ADAPTIVE KNOWLEDGE CYCLE
+                # ============================================================
+                # On vérifie si on doit apprendre (intervalle ou mort détectée dans l'obs précédente)
+                is_dead = self._is_game_over(observation)
+                time_to_learn = (step - self.last_learning_step >= self.learning_interval)
+                
+                # if (time_to_learn or is_dead) and len(self.history) > 0:
+                #     if verbose: print(f"\n[KNOWLEDGE] analyzing recent turns to extract wisdom...")
+                #     updated = self.knowledge_manager.update_knowledge(
+                #         history=self.history, 
+                #         start_idx=self.last_learning_step,
+                #         end_idx=len(self.history),
+                #         llm_function=lambda prompt, system_prompt, seed: call_llm(
+                #             prompt,          # Premier arg
+                #             system_prompt,   # Deuxième arg
+                #             seed             # Troisième arg
+                #         )
+                #     )
+                    
+                #     if updated:
+                #         knowledge_content = self.knowledge_manager.load_knowledge()
+                #         if verbose: print("[KNOWLEDGE] Strategic Knowledge Base updated!")
+                    
+                #     self.last_learning_step = len(self.history)
+                
+                # id_result = await client.call_tool("get_location_id", {})
+                # try:
+                #     room_id = int(self._extract_result(id_result))
+                # except:
+                #     room_id = -1 # Fallback
+                
+                # room_name = structured_data.get("location_name", "Unknown Area")
+
+                # if step > 1:
+                #     self.map.update(room_id, room_name, self.last_move_action)
+                
+                # spatial_context = self.map.get_context_for_llm(room_id)
+
+                # Build context based on urgency
+                if is_urgent:
+                    if verbose:
+                        print("\n🔥 [MODE URGENCE ACTIVÉ] Le cochon court / Combat en cours !")
+                    
+                     #  STRATEGIC KNOWLEDGE: {strategic_knowledge if strategic_knowledge else "No knowledge yet."}
+                    rich_context = f"""
+                     !!! URGENT SITUATION - FOCUS ON IMMEDIATE ACTION !!!
+                     SITUATION : {observation}
+                     PRIORITY GUIDANCE : {priority_guidance if priority_guidance else "- [STATUS] Standard exploration."}
+                     POSSIBLE ACTIONS: {enriched_actions}
+                    """
+                    
+                    # rich_context = f"""
+                    #     !!! URGENT SITUATION - FOCUS ON IMMEDIATE ACTION !!!
+                    #     TARGETS/ENEMIES: {visible_entities}
+                    #     LAST EVENT: {summary}
+                    #     INVENTORY: {current_inv}
+                    #     KNOWLEDGE: {knowledge_content}
+                    #     SPATIAL : {spatial_context}
+                    #     RELEVANT MEMORIES: {memory_context}
+                    #     """
+                else:
+                    # STRATEGIC KNOWLEDGE: {strategic_knowledge if strategic_knowledge else "No knowledge yet."}
+                    # LOCAL MEMORY : {self.current_location} {memory_context}
+                    rich_context = f"""
+                    CURRENT SITUATION : {observation}
+                    INVENTORY : {current_inv}
+                    PRIORITY GUIDANCE : {priority_guidance if priority_guidance else "- [STATUS] Standard exploration."}
+                    POSSIBLE ACTIONS: {enriched_actions}
+                    """
+    #                 rich_context = f"""
+    # LOCATION: {current_loc}
+    # ENTITIES: {visible_entities}
+    # OBJECTS: {visible_objs}
+    # EXITS: {visible_exits}
+    # INVENTORY: {current_inv}
+    # KNOWN MAP: {current_map}
+    # SUMMARY: {summary}
+    # KNOWLEDGE: {knowledge_content}
+    # SPATIAL : {spatial_context}
+    # RELEVANT MEMORIES : {memory_context}
+    # """
+                if verbose : 
+                    print(f"Context {rich_context}")
+                
+                # # --- 2. STRATEGY (Planner) ---
+                # if step == 1 or step % 5 == 0:
+                #     if verbose:
+                #         print(f"\n[STRATEGY] Thinking about long-term plan...")
+                    
+                #     plan = self.strategist.generate_plan(rich_context, self.history, step,knowledge_content)
+                    
+                #     if verbose and plan:
+                #         print(f"[STRATEGY] Objective: {plan.get('current_objective')}")
+
+                # # --- 3. GENERATION & CRITIC LOOP (Actor) ---
+                prompt = self._build_prompt(rich_context,knowledge="")
+
+                max_retries = 3
+                # Default values in case something goes wrong
+                final_tool_name = "play_action"
+                final_tool_args = {"action": "look"}
+                final_thought = "No thought generated"
+
+                for attempt in range(max_retries): 
+                    # Call LLM
+                    response = call_llm(prompt, SYSTEM_PROMPT, seed + step + attempt)
+                    
+                    # Parse response
+                    thought, tool_name, tool_args = self._parse_response(response, tool_names)
+                    final_thought = thought # Keep track of the thought
+
+                    final_tool_name = tool_name
+                    final_tool_args = tool_args
+
+                    # Validate basics
+                    tool_name, tool_args = self._validate_tool_call(tool_name, tool_args, tool_names)
+                    
+                    # Logic Validation (Critic)
+                    # if tool_name == "play_action":
+                    #     proposed_action = tool_args.get("action", "look")
+                        
+                    #     is_allowed = self.critic.critique_action(
+                    #         proposed_action,
+                    #         rich_context,
+                    #         current_inv,
+                    #         current_loc,
+                    #         seed + step,
+                    #         valid_exits=visible_exits
+                    #     )
+                        
+                    #     if is_allowed:
+                    #         final_tool_name = tool_name
+                    #         final_tool_args = tool_args
+                    #         break # Success!
+                    #     else:
+                    #         if verbose:
+                    #             print(f"⚠️ Action '{proposed_action}' blocked by Critic. Retrying ({attempt+1}/{max_retries})...")
+                            
+                    #         # Add feedback to prompt for next attempt
+                    #         prompt += f"\n\nUSER: The action '{proposed_action}' is invalid, impossible (check exits), or repetitive. Please propose a DIFFERENT action."
+                            
+                    #         # If this was the last attempt, force fallback
+                    #         if attempt == max_retries - 1:
+                    #             if verbose:
+                    #                 print("❌ Too many rejections. Forcing 'look'.")
+                    #             final_tool_name = "play_action"
+                    #             final_tool_args = {"action": "look"}
+                    # else:
+                    #     # Non-game actions (map, memory) are always allowed
+                    #     final_tool_name = tool_name
+                    #     final_tool_args = tool_args
+                    #     break
+
+                # --- 4. EXECUTION PREPARATION ---
+                tool_name = final_tool_name
+                tool_args = final_tool_args
+                thought = final_thought # Ensure we have the thought for history
+
+                if verbose:
+                    print(f"\n--- Step {step} ---")
+                    print(f"[THOUGHT] {thought}")
+                    print(f"[TOOL] {tool_name}({tool_args})")
+
+                # Handle history and loop detection for ACTIONS only
+                proposed_action = "tool_use"
+                if tool_name == "play_action":
+                    proposed_action = tool_args.get("action", "look")
+                    
+                    self.recent_actions.append(proposed_action)
+                    if len(self.recent_actions) > 5:
+                        self.recent_actions = self.recent_actions[-5:]
+                    
+                    if len(self.recent_actions) >= 3 and len(set(self.recent_actions[-3:])) == 1:
+                        # On cherche les directions dans la liste possible_actions
+                        import random
+
+                        all_raw_actions = []
+                        if isinstance(enriched_actions, str):
+                            all_raw_actions = [line.strip("- ").strip() for line in enriched_actions.split('\n') if "-" in line]
+                        
+                        move_keywords = ["north", "south", "east", "west", "ne", "nw", "se", "sw", "up", "down", "in", "out", "go "]
+                        valid_moves = [
+                            a for a in all_raw_actions 
+                            if any(k == a or a.startswith("go ") for k in move_keywords) or a == "wait"
+                        ]
+                       
+                        if valid_moves:
+                            # On choisit un mouvement au hasard PARMI ceux qui ne sont pas l'action répétée
+                            last_action = self.recent_actions[-1]
+                            choices = [m for m in valid_moves if m != last_action]
+                            forced_move = random.choice(choices if choices else valid_moves)
+                            
+                            tool_args = {"action": forced_move}
+                            proposed_action = forced_move
+                            
+                            if verbose: 
+                                print(f"🔄 [LOOP BREAK] Agent stuck on '{last_action}'. Forcing move to: {forced_move}")
+                        else:
+                            # Fallback ultime si aucun mouvement n'est détecté dans les actions possibles
+                            tool_args = {"action": "wait"}
+                            proposed_action = "wait"
+                                
+                    moves += 1
+
+
+                # --- 5. EXECUTION ---
+                try:
+                    result = await client.call_tool(tool_name, tool_args)
+                    new_observation = self._extract_result(result)
+
+
+                    full_action_key = tool_args.get("action", tool_name)
+
+                    if self.current_location not in self.location_action_memory:
+                        self.location_action_memory[self.current_location] = []
+                    
+                    if tool_name :
+                        summary = self._clean_memory_result(new_observation)
+                        # On stocke un petit dictionnaire par action pour garder le contexte
+                        action_entry = {
+                            "action": full_action_key,
+                            "result": summary,
+                            "step": getattr(self, 'step_count', 0) # Optionnel: pour savoir quand c'est arrivé
+                        }
+                        self.location_action_memory[self.current_location].append(action_entry)
+
+                    if tool_name == "play_action":
+                        loc_res = await client.call_tool("get_location_info", {})
+                        new_loc_dict = self._extract_result(loc_res)
+
+                        print("new loc dict",new_loc_dict)
+
+                        if isinstance(new_loc_dict, str):
+                            import json
+                            try:
+                                new_loc_dict = json.loads(new_loc_dict)
+                            except:
+                                new_loc_dict = {}
+                        else:
+                            new_loc_dict = new_loc_dict
+
+                        print("new loc dict",new_loc_dict)
+                        new_id = str(new_loc_dict["location"].get("id"))
+                        
+                        action_text = tool_args.get("action", "")
+                        direction_attempted = self.world_mapper._extract_direction(action_text)
+
+                        if direction_attempted and new_id == str(self.last_room_id):
+                                reason = self._clean_memory_result(new_observation)
+                                self.world_mapper.mark_blocked_exit(new_id, direction_attempted, reason)
+                                print(f"🚫 BLOCAGE : {direction_attempted} n'a pas fonctionné.")
+                        else:
+                            print("direction attempted",direction_attempted,action_text)
+                            new_structured = self.extractor.extract(
+                                raw_text=new_observation,
+                                seed=seed,
+                                ram_data=new_loc_dict,
+                                last_location=self.current_location
+                            )
+                            self.world_mapper.update_map(new_structured, action_text, new_observation)
+                            
+                    
+                    # Update critic memory
+                    # if tool_name == "play_action":
+                    #     self.critic.record_result(proposed_action, current_loc, new_observation)
+
+                    #     if hasattr(self, 'memory_manager'):
+                    #         try:
+                    #             self.memory_manager.synthesize(current_loc, proposed_action, new_observation, step)
+                    #         except Exception as mem_e:
+                    #             print(f"⚠️ Memory Synthesis Failed: {mem_e}") # On log mais on continue
+                                
+                    observation = new_observation
+                    
+                    if verbose:
+                        print(f"[RESULT] {observation}...")
+
+                except Exception as e:
+                    observation = f"Error: {e}"
+                    if verbose:
+                        print(f"[ERROR] {e}")
+                
+                # --- 6. TRACKING ---
+                # location = observation.split("\n")[0] if observation else "Unknown"
+                # locations_visited.add(location)
+                
+                self.history.append({
+                    "step": step,
+                    "thought": thought,
+                    "tool": tool_name,
+                    "args": tool_args,
+                    "result": observation[:200]
+                })
+                if len(self.history) > 10:
+                    self.history = self.history[-10:]
+                
+                self._update_score(observation)
+                
+                # Add to full run history
+                history.append((thought, f"{tool_name}({tool_args})", observation[:100]))
+                
+                if self._is_game_over(observation):
+                    if verbose:
+                        print("\n*** GAME OVER ***")
+
+                    # self.knowledge_manager.update_knowledge(
+                    #     self.history, self.last_learning_step, len(self.history),
+                    #     lambda p, s, seed=seed: call_llm(p, s, seed, max_tokens=2000)
+                    # )
+                    break
             
-        Returns:
-            RunResult with final score and statistics
+            return RunResult(
+                final_score=self.score,
+                max_score=350,
+                moves=moves,
+                locations_visited=locations_visited,
+                game_completed=self._is_game_over(observation),
+                history=history,
+            )
+
+
+    def _clean_memory_result(self, text: str) -> str:
+        """Nettoie le résultat pour la mémoire : une seule ligne, max 80 chars."""
+        if not text: return ""
+        # 1. Remplace les sauts de ligne par des espaces
+        clean = text.replace('\n', ' ').strip()
+        # 2. Supprime les doubles espaces
+        clean = " ".join(clean.split())
+        return clean
+        
+    # def _generate_enriched_actions(self, raw_actions: str, structured_data: dict) -> str:
+    #     enriched = [raw_actions]
+        
+    #     # 1. Objets à prendre
+    #     objs = structured_data.get("takeable_objects", [])
+    #     if objs:
+    #         enriched.append("\nOBJECTS TO TAKE:")
+    #         for obj in objs:
+    #             enriched.append(f"  - take {obj}")
+    #             enriched.append(f"  - examine {obj}")
+
+    #     # 2. Éléments du décor (Vital pour éviter les "examine" dans le vide)
+    #     features = structured_data.get("interactable_features", [])
+    #     if features:
+    #         enriched.append("\nENVIRONMENTAL FEATURES (MUST EXAMINE):")
+    #         for feat in features:
+    #             enriched.append(f"  - examine {feat}")
+
+    #     # 3. Entités (Sans Grunk)
+    #     ents = [e for e in structured_data.get("entities", []) if e.lower() != "grunk"]
+    #     if ents:
+    #         enriched.append("\nENTITIES (INTERACT):")
+    #         for ent in ents:
+    #             enriched.append(f"  - talk to {ent}")
+                
+    #     return "\n".join(enriched)
+
+    def _generate_enriched_actions(self, structured_data: dict) -> str:
         """
-        # 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:
+        Génère un kit d'action utilisant les noms traduits (friendly) 
+        ou signalant les noms techniques si nécessaire.
         """
-        Build the prompt for the LLM.
+        ram_objects = structured_data.get("raw_ram_objects", [])
+        mapping = structured_data.get("name_translation", {})
+        inventory_raw = structured_data.get("inventory", [])
+        inventory = [obj["name"] for obj in inventory_raw]
+        
+        kit = ["### 🛠️ ACTION CONSTRUCTION KIT"]
+
+        cheat_actions = structured_data.get("cheat_actions", [])
+        if cheat_actions:
+            # On met ces actions en avant car elles sont GARANTIES valides par le moteur
+            kit.append(f"**DIRECT ACTIONS (Proven Valid)**: {', '.join(cheat_actions)}")
+            kit.append(f"ABOVE ACTIONS ARE VALID BUT CAN BE DUMB")
+
+        # 1. VERBES PERMANENTS
+        verbs = ["examine", "take", "drop", "look", "inventory", "wait", "listen", "search"]
+        
+        # 2. VERBES CONTEXTUELS
+        # On scanne le texte et la RAM pour adapter les verbes
+        all_context = (structured_data.get("description_summary", "") + " ".join(ram_objects)).lower()
         
-        TODO: Implement this to create effective prompts
+        if any(x in all_context for x in ["door", "gate", "mailbox", "chest", "box", "case", "window"]):
+            verbs += ["open", "close", "unlock", "lock"]
+        
+        if any(x in all_context or "torch" in str(inventory).lower() for x in ["lamp", "torch", "switch", "device"]):
+            verbs += ["turn on", "turn off", "light", "extinguish"]
+
+        kit.append(f"**CORE VERBS**: {', '.join(sorted(set(verbs)))}")
+
+        # 3. OBJETS (Traitement Friendly vs Technical)
+        visible_ram = [o for o in ram_objects if "(missing" not in o.lower()]
+        hidden_ram = [o for o in ram_objects if "(missing" in o.lower()]
+        
+        if visible_ram:
+            formatted_objects = []
+            for tech_name in visible_ram:
+                # Si on a une traduction dans le mapping, on l'utilise
+                if tech_name in mapping:
+                    friendly_name = mapping[tech_name]
+                    formatted_objects.append(f"{friendly_name.upper()}")
+                else:
+                    # Sinon, on affiche le nom technique avec un avertissement
+                    formatted_objects.append(f"{tech_name} [! technical name] map to possible real and simple words")
+            
+            kit.append(f"**OBJECTS AROUND YOU**: {', '.join(formatted_objects)}")
+            kit.append("_Note: Use names exactly as shown above._")
+
+
+        
+        # 4. ALERTE SECRET
+        # if hidden_ram:
+        #     kit.append(f"**⚠️ SENSORY ALERT**: Something is hidden. Use 'listen', 'search' or 'examine' on specific features.")
+
+        # 5. NAVIGATION
+        # exits = structured_data.get("visible_exits", [])
+        # kit.append(f"**NAVIGATION**: {', '.join([e.upper() for e in exits]) if exits else 'N, S, E, W, U, D, IN, OUT'}")
+
+        return "\n".join(kit)
+
+    def classify_interaction(self, action: str, result: str,observation: str,inventory : str, name_mapping : dict, possible_actions : str) -> dict:
         """
-        # TODO: Combine system prompt, history, and current observation
-        pass
-    
-    def _parse_response(self, response: str) -> tuple[str, str, dict]:
+        Demande au LLM si l'action a échoué et pourquoi.
+        """
+        valid_names = ", ".join([f"'{friendly}' (ID: {tech})" for tech, friendly in name_mapping.items()])
+
+        prompt = f"""
+        Analyze this text adventure interaction:
+        Current Observation : {observation}
+        Inventory :  {inventory}
+        valid objects to use: {valid_names}
+        ACTION: "{action}"
+        RESULT: "{result}"
+
+        Here is possible actions to take {possible_actions}
+
+        Is this interaction a FAILURE (e.g., object not found, too dark, locked, invalid name, generic response)?
+        If it's a failure, provide a short reason and a suggestion. 
+
+        Return ONLY JSON:
+        {{
+        "is_failure": true/false,
+        "reason": "short explanation",
+        "suggestion": "what to try instead"
+        }}
         """
-        Parse LLM response to extract thought, tool name, and arguments.
+        # On utilise un seed fixe pour la consistance
+        response = call_llm(prompt, "You are a Game Logic Analyzer.", seed=42)
+        try:
+            import json
+            return json.loads(response)
+        except:
+            return {"is_failure": False, "reason": "", "suggestion": ""}
+
+    # def _build_priority_guidance(self, structured_data: dict) -> str:
+    #     guidance = []
+    #     loc_name = self.current_location
+    #     loc_id = structured_data.get("location_id", self.last_room_id or -1)
+    #     tree_display = structured_data.get("tree", [])
+
         
-        TODO: Implement robust parsing
+    #     # On utilise objects_in_room pour avoir la hiérarchie (parents/enfants)
+    #     # Si absent, on replie sur raw_ram_objects pour la compatibilité
+    #     # objects_tree = structured_data.get("objects_in_room", [])
+    #     objects_tree = structured_data.get("objects_in_room", [])
+    #     raw_ram_objects = structured_data.get("raw_ram_objects",[])
+    #     mapping = structured_data.get("name_translation", {})
         
-        Returns:
-            Tuple of (thought, tool_name, args_dict)
-        """
-        # TODO: Parse the response format:
-        # THOUGHT: ...
-        # TOOL: ...
-        # ARGS: {...}
-        pass
+    #     past_actions = self.location_action_memory.get(loc_name, [])
+    #     interacted_res = None
+    #     world_changed = structured_data.get("world_changed", False)
+    #     is_new_loc = structured_data.get("is_new_location", False)
+
+
+    #     if self.recent_actions:
+    #         last_action_taken = self.recent_actions[-1]
+    #         # On récupère le dernier élément de notre liste de mémoire
+    #         last_entry = past_actions[-1] if past_actions else {}
+    #         last_res = last_entry.get("result", "No feedback available.")
+            
+    #         guidance.append("### ⚡ LAST ACTION FEEDBACK:")
+    #         guidance.append(f"- Command: '{last_action_taken}'")
+    #         guidance.append(f"- Full Result: '{last_res}'") # Ici on met tout le texte
+    #         guidance.append(f"USE ALL THE HINT FROM THIS ACTIONS. YOU CAN EXAMINE OBJECTS IN THE RESULT. EX : Examine bowl")
+    #         guidance.append("⚠️ TRUST THE CURRENT OBSERVATION TEXT OVER MEMORY FOR OBJECT NAMES. USE IT.")
+    #         guidance.append("")
+            
+    #         if world_changed:
+    #             guidance.append("- [!] SUCCESS: The world state changed. Analyze the new situation.")
+    #         elif not is_new_loc:
+    #             guidance.append("- [!] STASIS: No change detected. Do not repeat this exact command.")
+    #         guidance.append("")
+
+    #     visible_exits = structured_data.get("visible_exits", [])
+
+    #     guidance.append("### 🗺️ STRATEGIC NAVIGATION:")
+    #     visible_exits = structured_data.get("visible_exits", [])
+    #     room_data = self.world_mapper.graph.get(loc_id, {})
+    #     known_exits = room_data.get("exits", {})
+    #     blocked_exits = room_data.get("blocked_exits", {})
+
+    #     for direction in visible_exits:
+    #         d_l = direction.lower()
+    #         if d_l in blocked_exits:
+    #             guidance.append(f"- {direction.upper()} : 🚫 BLOCKED ({blocked_exits[d_l]})")
+    #         elif d_l in known_exits:
+    #             target_id = known_exits[d_l]
+    #             target_room = self.world_mapper.graph.get(str(target_id), {})
+    #             t_name = target_room.get("name", "Unknown Area")
+    #             status = "✅ Fully Visited" if target_room.get("items_scanned") else "🔎 Unexplored Items"
+    #             guidance.append(f"- {direction.upper()} : Leads to **{t_name}** ({status})")
+    #         else:
+    #             guidance.append(f"- {direction.upper()} : 🌟 [NEW PATHWAY - EXPLORE THIS]")
+    #     guidance.append("")
+        
+    #     guidance.append("\n### 🧠 GLOBAL STRATEGY & PUZZLE RADAR:")
     
-    def _call_llm(self, prompt: str, system_prompt: str, seed: int) -> str:
-        """
-        Call the LLM with the given prompt.
+    #     world_knowledge = []
+    #     active_puzzles = []
         
-        This is a convenience wrapper - you can also use call_llm() directly.
-        """
-        return call_llm(prompt, system_prompt, seed)
+    #     for r_id, r_data in self.world_mapper.graph.items():
+    #         # On ne liste pas la pièce actuelle pour éviter le bruit
+    #         if r_id != loc_id:
+    #             # Objets laissés ailleurs
+    #             if r_data.get("items"):
+    #                 world_knowledge.append(f"- In {r_data['name']}: {', '.join(r_data['items'])}")
+                
+    #             # Puzzles détectés ailleurs
+    #             for p in r_data.get("puzzles", []):
+    #                 active_puzzles.append(f"- [{r_data['name']}] Obstacle: {p}")
+
+    #     if world_knowledge:
+    #         guidance.append("**Dropped/Left Items:**")
+    #         guidance.extend(world_knowledge)
+
+    #     print("VISIBLE EXISTS",visible_exits)
+    #     if visible_exits:
+    #         guidance.append("### 🚪 AVAILABLE EXITS:")
+            
+    #         # On extrait les directions déjà tentées dans cette pièce
+    #         # On cherche des actions comme "go east", "east", "move north", etc.
+    #         attempted_exits = []
+    #         for entry in past_actions:
+    #             action_str = entry.get("action", "").lower()
+    #             for direction in visible_exits:
+    #                 if direction.lower() in action_str:
+    #                     attempted_exits.append(direction.lower())
+
+    #         exit_guidance = []
+    #         for direction in visible_exits:
+    #             if direction.lower() in attempted_exits:
+    #                 exit_guidance.append(f"- {direction.upper()} (Already explored/tried)")
+    #             else:
+    #                 exit_guidance.append(f"- {direction.upper()} 🌟 [NEW PATHWAY]")
+            
+    #         guidance.extend(exit_guidance)
+            
+    #         # Petit conseil stratégique si tout est exploré
+    #         if all(d.lower() in attempted_exits for d in visible_exits) and visible_exits:
+    #             guidance.append("- [TIP] All exits tried. If stuck, look for hidden objects or interact with items.")
+    #         guidance.append("")
+
+    #     # --- 2. HISTORIQUE CHRONOLOGIQUE (LES 10 DERNIÈRES) ---
+    #     if past_actions:
+    #         guidance.append(f"### 🛑 CHRONOLOGICAL HISTORY (Last 10 steps in this room):")
+    #         # On prend les 10 dernières entrées de la liste
+    #         for entry in past_actions[-10:-1]:
+    #             act = entry.get("action")
+    #             res = entry.get("result")
+    #             # On affiche tout le résultat, mais ligne par ligne pour la clarté
+    #             guidance.append(f"STEP {entry.get('step', '?')}: '{act}'")
+    #             guidance.append(f"  Result: {res}")
+    #         guidance.append("")
+
+
+    #     if world_changed or is_new_loc:
+    #         guidance.append("### 🔥 HOT FOCUS: NEW STATE DETECTED")
+    #         if is_new_loc:
+    #             guidance.append(f"- [LOCATION] You just entered '{loc_name}'. All previous room logic is VOID.")
+    #         if world_changed:
+    #             guidance.append("- [WORLD CHANGE] The game state has mutated! Something opened, moved, or appeared.")
+    #         guidance.append("- [URGENT] Acts based on the change (e.g., if something opened, look inside).")
+
+    #     # --- SCAN HIERARCHIQUE (OBJETS PARENTS) ---
+    #     # print("TREE DISPLAY",tree_display)
+    #     # if tree_display:
+    #     #     guidance.append("### 🌳 ENVIRONMENT HIERARCHY (SENSORS):")
+    #     #     guidance.append("This is the exact structure of the room:")
+    #     #     for line in tree_display:
+    #     #         guidance.append(line)
+    #     #     guidance.append("")
+
+    #     guidance.append(f"### 🔍 RAM SENSORS (INTELLIGENT SCAN):")
+        
+    #     objects_in_room = structured_data.get("objects_in_room", [])
+    #     unexplored = [] # Jamais touchés
+    #     failed_attempts = [] # Tentés mais avec erreur
+    #     known_success = [] # Déjà examinés avec succès
+
+    #     for obj_data in objects_in_room:
+    #         if not isinstance(obj_data, dict):
+    #             continue
+
+    #         raw_name = obj_data.get("name", "Unknown")
+    #         friendly_name = mapping.get(raw_name, raw_name).upper()
+            
+    #         # 1. Recherche de la dernière interaction
+    #         last_entry = None
+    #         for entry in reversed(past_actions):
+    #             act = entry.get("action", "").lower()
+    #             if raw_name.lower() in act or friendly_name.lower() in act:
+    #                 last_entry = entry
+    #                 break
+            
+    #         # 2. Construction de l'info de contenu (Hiérarchie)
+    #         content_list = obj_data.get("contents", [])
+    #         content_str = f" [Contains: {', '.join([mapping.get(c['name'], c['name']).upper() for c in content_list])}]" if content_list else ""
+    #         display_line = f"- {friendly_name}{content_str}"
+
+    #         # 3. Classification par LLM si une interaction existe
+    #         if last_entry:
+    #             action_tried = last_entry.get("action")
+    #             result_received = last_entry.get("result")
+                
+    #             # On demande au LLM si c'est un échec
+    #             analysis = self.classify_interaction(action_tried, result_received)
+                
+    #             if analysis.get("is_failure"):
+    #                 # C'est un échec : on le met en priorité pour correction
+    #                 fail_msg = f"{display_line}\n  ⚠️ FAILED: '{action_tried}' -> {analysis['reason']}\n  💡 SUGGESTION: {analysis['suggestion']}"
+    #                 failed_attempts.append(fail_msg)
+    #             else:
+    #                 # C'est un succès : on le met dans les acquis
+    #                 known_success.append(f"{display_line} | ✅ Known: {result_received[:60]}...")
+    #         else:
+    #             # Jamais tenté
+    #             unexplored.append(display_line)
+
+    #     # --- AFFICHAGE HIÉRARCHISÉ ---
+        
+    #     if failed_attempts:
+    #         guidance.append("### ⚠️ ACTIONS TO CORRECT (FAILED ATTEMPTS):")
+    #         guidance.extend(failed_attempts)
+    #         guidance.append("")
+
+    #     if unexplored:
+    #         guidance.append("### ✨ NEW / UNEXPLORED IN ROOM:")
+    #         guidance.extend(unexplored)
+    #         guidance.append("")
+
+    #     if known_success:
+    #         guidance.append("### ✅ ALREADY INTERACTED (SUCCESS):")
+    #         guidance.extend(known_success)
+    #         guidance.append("")
+
+    #     # --- GUIDANCE STRATÉGIQUE MISE À JOUR ---
+    #     guidance.append("\n**STRATEGY GUIDANCE**:")
+    #     if failed_attempts:
+    #         guidance.append("- [RECOVERY] Prioritize correcting FAILED actions. Do not repeat the same command; follow the suggestion.")
+    #     guidance.append("- [PHYSICS] If an item is inside a container, you MUST 'OPEN' or 'EXAMINE' the parent first.")
+    #     guidance.append("- [EXPLORATION] Do not leave this room until all 'NEW' and 'FAILED' items are resolved.")
+
+    #     # --- DÉTECTION DES SECRETS ---
+    #     # On utilise raw_ram_objects ici car c'est une liste de strings simple
+    #     raw_names_list = structured_data.get("raw_ram_objects", [])
+    #     has_secrets = any("(missing" in o.lower() for o in raw_names_list)
+    #     if has_secrets:
+    #         guidance.append("### ⚠️ SENSORY ANOMALY:")
+    #         guidance.append("- [GOD-MODE] Hidden structures detected. Use 'SEARCH' or 'EXAMINE' on the scenery.")
+
+
+    #     clues = " ".join(structured_data.get("puzzle_clues", [])).lower()
+    #     if any(k in clues for k in ["noise", "hear", "sound"]):
+    #         guidance.append("- [AUDIO] Noise detected! Use 'listen'.")
+
+    #     if is_new_loc:
+    #         guidance.append("### 🚀 NEW AREA PROTOCOL: 1. 'look', 2. 'examine' new objects, 3. 'listen', 4. explore exits.")
+
+    #     return "\n".join(guidance)
+
+    def _build_priority_guidance(self, structured_data: dict) -> str:
+        guidance = []
+        loc_name = self.current_location
+        loc_id = str(structured_data.get("location_id", self.last_room_id or -1))
+        mapping = structured_data.get("name_translation", {})
+        past_actions = self.location_action_memory.get(loc_name, [])
+        
+        
+        current_inventory = str(structured_data.get("inventory", "Unknown"))
+        current_obs = structured_data.get("description_summary", "No description")
+        enriched_actions = self._generate_enriched_actions(structured_data)
+
+
+        if self.steps_in_current_room >= MAX_STEPS_ALLOWED:
+            guidance.append("\n### 🚀 URGENT STRATEGIC DIRECTIVE:")
+            guidance.append(f"- [STAGNATION ALERT] {self.steps_in_current_room} turns in this room.")
+            
+            known_room = self.world_mapper.graph.get(loc_id, {})
+            potential = known_room.get("potential_exits", [])
+            already_linked = known_room.get("exits", {}) # Dict: {direction: target_id}
+            
+            new_paths = [p for p in potential if p not in already_linked]
+            
+            # --- CAS 1 : Il y a des nouvelles sorties à tester ---
+            if new_paths:
+                guidance.append(f"- [ACTION] Move to a NEW area. Priority: {', '.join(new_paths).upper()}")
+            
+            # --- CAS 2 : On connaît déjà des sorties ---
+            elif already_linked:
+                # On suggère de faire marche arrière ou de changer de zone
+                guidance.append("- [ACTION] Room exhausted. Backtrack or move to a known adjacent room.")
+                directions_list = [d.upper() for d in already_linked.keys()]
+                guidance.append(f"- [HINT] Known exits: {', '.join(directions_list)}")
+            
+            # --- CAS 3 : AUCUNE SORTIE TROUVÉE (Le vrai problème) ---
+            else:
+                guidance.append("- [CRITICAL] No exits found in memory or observation.")
+                guidance.append("- [ACTION] Use 'SEARCH', 'LISTEN', or 'EXAMINE' on the scenery to find hidden passages.")
+                guidance.append("- [HINT] Try common directions anyway: NORTH, SOUTH, EAST, WEST,NORTHEAST,NORTHWEST,SOUTHEAST,SOUTHWEST, UP, DOWN.")
+
+
+        
+        # ============================================================
+        # 1. FEEDBACK IMMÉDIAT (Ce qui vient de se passer)
+        # ============================================================
+        if self.recent_actions and past_actions:
+            last_action_taken = self.recent_actions[-1]
+            last_entry = past_actions[-1]
+        
+            guidance.append("### ⚡ LAST ACTION FEEDBACK:")
+            guidance.append(f"- Command: '{last_action_taken}'")
+            
+            # On analyse l'action qui vient d'être faite
+            immediate_analysis = self.classify_interaction(
+                action=last_entry['action'], 
+                result=last_entry['result'],
+                observation=current_obs, 
+                inventory=current_inventory,
+                name_mapping=mapping,
+                possible_actions=enriched_actions
+            )
+
+            if immediate_analysis.get("is_failure"):
+                guidance.append(f"- [!] STATUS: FAILURE")
+                guidance.append(f"- [!] REASON: {immediate_analysis['reason']}")
+                guidance.append(f"- [!] SUGGESTION: {immediate_analysis['suggestion']}")
+            elif structured_data.get("world_changed"):
+                guidance.append("- [!] STATUS: SUCCESS (World state updated)")
+            else:
+                guidance.append(f"- [!] STATUS: NEUTRAL / INFO: {last_entry.get('result', '')}")
+            
+        guidance.append("IF ANOTHER ENTITIES IS INTERESTED BY AN ITEM IT'S A HINT. EX : pig climb fountain -> fountain must be an important object to examine or search")
+
+        # ============================================================
+        # 2. VISION STRATÉGIQUE (Utilisation de TA fonction !)
+        # ============================================================
+        # On appelle la fonction de ton WorldMapper
+        strategic_summary = self.world_mapper.generate_summary(loc_id)
+        guidance.append(strategic_summary)
+        guidance.append("")
+
+        # ============================================================
+        # 3. SCAN RAM LOCAL (Détails des objets de la pièce)
+        # ============================================================
+        guidance.append("### 🔍 LOCAL OBJECT SCAN (RAM):")
+        objects_in_room = structured_data.get("objects_in_room", [])
+        unexplored = []
+        failed_attempts = []
+        known_success = []
+
+        for obj_data in objects_in_room:
+            if not isinstance(obj_data, dict): continue
+            raw_name = obj_data.get("name", "Unknown")
+            has_hidden = obj_data.get("contains_count", 0) > 0
+            
+            friendly_name = mapping.get(raw_name, "").upper()
+            present = True
+            if friendly_name == "": 
+                present = False
+            
+            # Trouver la dernière interaction spécifique à cet objet
+            last_obj_entry = None
+            for entry in reversed(past_actions):
+                act = entry.get("action", "").lower()
+                found_raw = raw_name and raw_name.lower() in act
+                found_friendly = friendly_name and friendly_name.lower() in act
+
+                if found_raw or found_friendly:
+                    last_obj_entry = entry
+                    break
+
+            # Texte de hiérarchie (Contenu)
+            contents = obj_data.get("contents", [])
+            content_str = f" [Contains: {', '.join([mapping.get(c['name'], c['name']).upper() for c in contents])}]" if contents else ""
+            if contents:
+                child_names = [c.get("name", "Unknown").upper() for c in contents]
+                content_str = f" [Contains: {', '.join(child_names)}]"
+
+            if present:
+                display_line = f"- {friendly_name}{content_str}"
+            
+            if not present :
+                display_line = f"- {raw_name}{content_str} [!] Technical Name use the real name or a full word. Ex : fountabowl -> bowl, brokstair -> stairs ... CHECK YOUR HISTORY AND OBSERVATION"
+
+            if last_obj_entry:
+                last_act_text = last_obj_entry['action']
+                last_res_text = last_obj_entry['result']
+                
+                # Si cette action était un échec (on réutilise ta fonction de classification)
+                analysis = self.classify_interaction(
+                    action=last_obj_entry['action'], 
+                    result=last_obj_entry['result'],
+                    observation=current_obs, 
+                    inventory=current_inventory,
+                    name_mapping=mapping,
+                    possible_actions=self._generate_enriched_actions(structured_data)
+                )
+                
+                if analysis.get("is_failure"):
+                    guidance.append(f"{display_line}\n  ❌ Last tried: '{last_act_text}' -> {analysis['reason']}")
+                    guidance.append(f"  💡 Suggestion: {analysis['suggestion']}")
+                else:
+                    guidance.append(f"{display_line} | ✅ Last: '{last_act_text}' (Success) {last_act_text}")
+            else:
+                # Jamais touché
+                if present or contents :
+                    guidance.append(f"{display_line} | ✨ UNEXPLORED")
+
+        # # Affichage des listes
+        # if failed_attempts:
+        #     guidance.append("\n**⚠️ TO CORRECT:**")
+        #     guidance.extend(failed_attempts)
+        
+        # if unexplored:
+        #     guidance.append("\n**✨ UNEXPLORED:**")
+        #     guidance.extend(unexplored)
+        
+        # ============================================================
+        # 4. CHRONOLOGIE (Historique des commandes)
+        # ============================================================
+        if past_actions:
+            guidance.append(f"\n### 🛑 ROOM HISTORY (Last steps):")
+            for entry in past_actions[-10:]:
+                guidance.append(f"- '{entry.get('action')}' -> {entry.get('result')}...")
+
+        MAX_STEPS_ALLOWED = 8
+       
+
+        return "\n".join(guidance)
+
+    def _build_prompt(self, observation: str,knowledge:str) -> str:
+        """Build the prompt for the LLM with context."""
+        parts = []
+
+        # strategy_text = self.strategist.get_strategy_context()
+        # parts.append(strategy_text)
+        # parts.append("-" * 40)
+
+        parts.append(f"Current Score: {self.score}")
+        
+        # Recent history
+        if self.history:
+            parts.append("\nRecent actions:")
+            for entry in self.history[-3:]:
+                action = entry.get("args", {}).get("action", entry["tool"])
+                result_short = entry["result"][:80] + "..." if len(entry["result"]) > 80 else entry["result"]
+                parts.append(f"  > {action} -> {result_short}")
+            
+            # Warn about repeated actions
+            if self.recent_actions and len(set(self.recent_actions[-3:])) == 1:
+                parts.append(f"\n[WARNING: You've been doing '{self.recent_actions[-1]}' repeatedly. TRY SOMETHING DIFFERENT!]")
+        
+        # if knowledge:
+        #     parts.append("\n=== ACQUIRED STRATEGIC KNOWLEDGE ===")
+        #     parts.append(knowledge)
+        #     parts.append("====================================\n")
+
+        parts.append(f"\nCURRENT SITUATION:\n{observation}")
+        parts.append("\nWhat is your next specific command?")
+        
+        return "\n".join(parts)
+    
+    def _parse_response(self, response: str, valid_tools: list[str]) -> tuple[str, str, dict]:
+        """Parse the LLM response to extract thought, tool, and arguments."""
+        thought = "No reasoning provided"
+        tool_name = "play_action"
+        tool_args = {"action": "look"}
+        
+        lines = response.strip().split("\n")
+        
+        for line in lines:
+            line_clean = line.strip()
+            line_upper = line_clean.upper()
+            
+            if line_upper.startswith("THOUGHT:"):
+                thought = line_clean.split(":", 1)[1].strip()
+            
+            elif line_upper.startswith("TOOL:"):
+                raw_tool = line_clean.split(":", 1)[1].strip().lower()
+                raw_tool = raw_tool.replace("**", "").replace("*", "").replace("`", "")
+                raw_tool = raw_tool.split()[0] if raw_tool else "play_action"
+                tool_name = raw_tool
+            
+            elif line_upper.startswith("ARGS:"):
+                args_part = line_clean.split(":", 1)[1].strip()
+                try:
+                    args_part = args_part.replace("'", '"')
+                    tool_args = json.loads(args_part)
+                except json.JSONDecodeError:
+                    match = re.search(r'"action"\s*:\s*"([^"]+)"', args_part)
+                    if match:
+                        tool_args = {"action": match.group(1)}
+                    else:
+                        tool_args = {"action": "look"}
+        
+        return thought, tool_name, tool_args
+    
+    def _validate_tool_call(self, tool_name: str, tool_args: dict, valid_tools: list[str]) -> tuple[str, dict]:
+        """Validate and fix common tool call issues."""
+        # Fix tool name
+        if tool_name not in valid_tools:
+            if tool_name in ["action", "do", "command"]:
+                tool_name = "play_action"
+            elif tool_name in ["map", "location"]:
+                tool_name = "get_map"
+            elif tool_name in ["mem", "state", "status"]:
+                tool_name = "memory"
+            elif tool_name in ["inv", "items"]:
+                tool_name = "inventory"
+            else:
+                tool_name = "play_action"
+        
+        # Fix action verbs
+        if tool_name == "play_action":
+            action = str(tool_args.get("action", "look")).lower().strip()
+            direction = tool_args.get("direction")
+
+            # Fusion de la direction si le LLM l'a mise à part
+            if direction and str(direction).lower() not in action:
+                action = f"{action} {direction}"
+
+            nav_map = {
+            "north": "n", "south": "s", "east": "e", "west": "w",
+            "northeast": "ne", "northwest": "nw", 
+            "southeast": "se", "southwest": "sw",
+            "up": "u", "down": "d"
+            }
+
+            invalid_verb_map = {
+                "check": "examine",
+                "inspect": "examine",
+                "search": "look",
+                "grab": "take",
+                "pick": "take",
+                "use": "examine",
+                "investigate": "examine",
+            }
+            
+            if action.startswith("go "):
+                action = action.replace("go ", "").strip()
+
+            words = action.split()
+            if words:
+                if words[0] in invalid_verb_map:
+                    words[0] = invalid_verb_map[words[0]]
+                    action = " ".join(words)
+
+                if words[0] == "examine":
+                    words = words[:2] 
+                    action = " ".join(words)
+                else:
+                    action = " ".join(words)
+                
+                if action in nav_map:
+                    action = nav_map[action]
+            
+            action = action.replace("**", "").replace("*", "").replace("`", "")
+            action = " ".join(action.split())
+            
+            return tool_name, {"action": action}
+        
+        return tool_name, tool_args
+    
+    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 _update_score(self, text: str) -> None:
+        """Update score from game text."""
+        patterns = [
+            r'Score:\s*(\d+)',
+            r'score[:\s]+(\d+)',
+            r'\[Score:\s*(\d+)',
+        ]
+        
+        for pattern in patterns:
+            match = re.search(pattern, text, re.IGNORECASE)
+            if match:
+                self.score = max(self.score, int(match.group(1)))
+    
+    def _is_game_over(self, text: str) -> bool:
+        """Check if the game is over."""
+        game_over_phrases = [
+            "game over",
+            "you have died",
+            "you are dead",
+            "*** you have died ***",
+        ]
+        text_lower = text.lower()
+        return any(phrase in text_lower for phrase in game_over_phrases)
 
 
 # =============================================================================
-# For local testing
+# Local Testing
 # =============================================================================
 
 async def test_agent():
     """Test the agent locally."""
     from fastmcp import Client
     
-    # Path to your MCP server
-    server_path = "mcp_server.py"
-    
     agent = StudentAgent()
     
-    async with Client(server_path) as client:
+    async with Client("mcp_server.py") as client:
         result = await agent.run(
             client=client,
             game="zork1",
-            max_steps=10,
+            max_steps=20,
             seed=42,
             verbose=True,
         )
         
-        print(f"\nFinal Score: {result.final_score}")
+        print(f"\n{'=' * 50}")
+        print(f"Final Score: {result.final_score}")
         print(f"Moves: {result.moves}")
-        print(f"Locations: {result.locations_visited}")
+        print(f"Locations: {len(result.locations_visited)}")
+
+
+class StrategyModule:
+    """
+    Gère la planification haut niveau (The 'Brain').
+    """
+    def __init__(self):
+        self.current_plan = None
+        self.last_update_step = 0
+    
+    def generate_plan(self, observation: str, history: list, step: int,knowledge:str) -> dict:
+        """Génère ou met à jour le plan stratégique."""
+        
+        # Préparer le contexte pour le stratège
+        history_summary = "\n".join(
+            [f"- {h['thought']} -> {h['result'][:50]}..." for h in history[-5:]]
+        )
+        
+        prompt = f"""
+        CURRENT SITUATION:
+        {observation}
+
+        RECENT HISTORY:
+        {history_summary}
+
+        ACQUIRED KNOWLEDGE (Tips & Rules from previous games):
+        {knowledge if knowledge else "No prior knowledge available."}
+
+        TASK:
+        Based on the Situation and Knowledge, create a strategic plan.
+        If the Knowledge says "Trolls fear swords", and you see a Troll, your plan must be "Find sword".
+        """
+        
+        # Appel LLM dédié à la stratégie (on peut utiliser un seed différent)
+        response = call_llm(prompt, PLANNER_SYSTEM_PROMPT, seed=step, max_tokens=400)
+        
+        try:
+            # Nettoyage basique pour extraire le JSON si le modèle bavarde
+            json_str = response.strip()
+            if "```json" in json_str:
+                json_str = json_str.split("```json")[1].split("```")[0]
+            elif "```" in json_str:
+                json_str = json_str.split("```")[1].split("```")[0]
+                
+            self.current_plan = json.loads(json_str)
+            self.last_update_step = step
+            return self.current_plan
+        except Exception as e:
+            print(f"[Strategy Error] Failed to parse plan: {e}")
+            return None
+
+    def get_strategy_context(self) -> str:
+        """Renvoie une chaîne de texte à injecter dans le prompt de l'Acteur."""
+        if not self.current_plan:
+            return "NO ACTIVE PLAN. Explore cautiously."
+            
+        return f"""
+        *** STRATEGIC GUIDANCE ***
+        CURRENT OBJECTIVE: {self.current_plan.get('current_objective', 'Unknown')}
+        STRATEGIC REASONING: {self.current_plan.get('reasoning', 'None')}
+        STEPS TO TAKE:
+        {chr(10).join(['- ' + s for s in self.current_plan.get('suggested_steps', [])])}
+        """
+
+##### CRITIC Agent
+
+@dataclass
+class CriticResponse:
+    score: float
+    justification: str
+    is_fatal: bool = False
+
+class ActionHistoryTracker:
+    """
+    Detect loop and critics
+    """
+    def __init__(self):
+        self.recent_actions: List[str] = []
+        self.location_history: List[str] = []
+        self.failed_actions_per_location: Dict[str, Set[str]] = {}
+        
+    def update(self, action: str, location: str, result: str):
+        self.recent_actions.append(action)
+        self.location_history.append(location)
+        
+        # Détection basique d'échec basée sur le texte du jeu
+        failure_keywords = ["can't", "don't", "nothing happens", "impossible", "failed", "no such"]
+        if any(k in result.lower() for k in failure_keywords):
+            if location not in self.failed_actions_per_location:
+                self.failed_actions_per_location[location] = set()
+            self.failed_actions_per_location[location].add(action)
+            
+        # 
+        if len(self.recent_actions) > 20:
+            self.recent_actions.pop(0)
+            self.location_history.pop(0)
+
+    def is_looping(self, proposed_action: str) -> bool:
+        """Détecte les répétitions immédiates."""
+        if len(self.recent_actions) >= 3:
+            # Si les 3 dernières actions sont identiques à la proposée
+            if all(a == proposed_action for a in self.recent_actions[-3:]):
+                return True
+        return False
+
+    def is_known_failure(self, proposed_action: str, current_location: str) -> bool:
+        """Vérifie si cette action a déjà échoué ici."""
+        if current_location in self.failed_actions_per_location:
+            if proposed_action in self.failed_actions_per_location[current_location]:
+                return True
+        return False
+
+class CriticAgent:
+    """
+    Le module critique qui valide les actions avant exécution.
+    """
+    def __init__(self,call_llm_func, verbose: bool = False):
+        self.history_tracker = ActionHistoryTracker()
+        self.verbose = verbose
+        self.call_llm = call_llm_func
+
+    def check_heuristics(self, action: str, current_location: str,valid_exits:list[str]) -> tuple[bool, str]:
+        """
+        Vérification rapide basée sur des règles (Pas de LLM).
+        Retourne (Est_Valid, Raison).
+        """
+        # 1. Vérifier si c'est une action vide
+        if not action or len(action.strip()) < 2:
+            return False, "Action too short or empty"
+
+        # 2. Vérifier les boucles immédiates
+        if self.history_tracker.is_looping(action):
+            return False, "Detected infinite loop (action repeated too many times)"
+        
+        # 3. Vérifier les échecs connus (Memory-based rejection)
+        if self.history_tracker.is_known_failure(action, current_location):
+            return False, f"Action '{action}' previously failed in this location"
+        
+        directions = ["north", "south", "east", "west", "up", "down", 
+                    "n", "s", "e", "w", "u", "d", "ne", "nw", "se", "sw"]
+        
+        action_word = action.lower().strip()
+
+        if action_word in directions and valid_exits:
+            
+            is_possible = False
+            for exit_name in valid_exits:
+                if action_word in exit_name.lower() or exit_name.lower().startswith(action_word):
+                    is_possible = True
+                    break
+            
+            if not is_possible:
+                return False, f"You can't go '{action_word}'. Visible exits are: {valid_exits}"
+
+        return True, "Heuristics passed"
+
+        return True, "Heuristics passed"
+
+    def evaluate_with_llm(self, action: str, observation: str, inventory: str, seed: int) -> CriticResponse:
+        """
+        Évaluation sémantique lente via LLM.
+        """
+        # Construction du prompt
+        prompt = f"""
+        OBSERVATION:
+        {observation[:1000]}...
+        
+        INVENTORY:
+        {inventory}
+        
+        PROPOSED ACTION:
+        {action}
+        
+        Evaluate this action.
+        """
+        
+        try:
+            response_text = self.call_llm(prompt, CRITIC_SYSTEM_PROMPT, seed=seed, max_tokens=150)
+            
+            # Parsing JSON résilient
+            json_str = response_text.strip()
+            if "```json" in json_str:
+                json_str = json_str.split("```json")[1].split("```")[0]
+            elif "```" in json_str:
+                json_str = json_str.split("```")[1].split("```")[0]
+            
+            data = json.loads(json_str)
+            return CriticResponse(
+                score=float(data.get("score", 0.5)),
+                justification=data.get("justification", "No reason provided"),
+                is_fatal=data.get("is_fatal", False)
+            )
+            
+        except Exception as e:
+            if self.verbose:
+                print(f"[Critic Error] LLM validation failed: {e}")
+            # En cas d'erreur, on laisse passer (fail open)
+            return CriticResponse(score=1.0, justification="Validation failed, allowing action")
+
+    def critique_action(self, action: str, observation: str, inventory: str, current_location: str, seed: int,valid_exits: list[str] = None) -> bool:
+        """
+        Méthode principale à appeler depuis l'agent.
+        Retourne True si l'action est acceptée, False sinon.
+        """
+        # 1. Filtre Heuristique (Rapide & Gratuit)
+        is_valid, reason = self.check_heuristics(action, current_location,valid_exits)
+        if not is_valid:
+            if self.verbose:
+                print(f"🛑 [CRITIC REJECT - RULE] {reason}")
+            return False
+
+        # 2. Filtre LLM (Lent & Coûteux - on peut l'activer seulement pour les actions complexes)
+        # Pour optimiser, on ne vérifie pas les mouvements simples (north, south, etc.)
+        simple_moves = ["north", "south", "east", "west", "up", "down", "look", "inventory"]
+        if action.lower() in simple_moves:
+            return True
+
+        # Appel LLM pour les actions complexes (take, attack, open...)
+        evaluation = self.evaluate_with_llm(action, observation, inventory, seed)
+        
+        if evaluation.score < 0.4 or evaluation.is_fatal:
+            if self.verbose:
+                print(f"🛑 [CRITIC REJECT - LLM] Score: {evaluation.score} | Reason: {evaluation.justification}")
+            return False
+            
+        return True
+
+    def record_result(self, action: str, current_location: str, result_text: str):
+        """Met à jour la mémoire du critique après l'exécution."""
+        self.history_tracker.update(action, current_location, result_text)
+
+
+#### Extractor of data
+
+class StructuredObservation(BaseModel):
+    location_id: int # L'ID RAM de la pièce
+    location_name: str
+    is_new_location: bool 
+    world_changed: bool # Basé sur le Hash
+    description_summary: str
+    takeable_objects: List[str] 
+    visible_exits: List[str]
+    interactable_features: List[str]
+    puzzle_clues: List[str]    
+    entities: List[str]        
+    in_combat: bool
+    raw_ram_objects : List[str]
+    name_translation: Dict[str, str]
+
+
+class ObservationExtractor:
+    def __init__(self, call_llm_func):
+        self.call_llm = call_llm_func
+
+    def extract(self, raw_text: str, seed: int, ram_data: dict, last_location: str = "Unknown") -> dict:
+        """
+        Convertit le texte brut et les données RAM structurées en dictionnaire.
+        """
+        inventory_raw = ram_data.get("inventory", [])
+        inventory_names = [item["name"] for item in inventory_raw]
+
+        # 1. Extraction sécurisée des données imbriquées de ram_data
+        location_info = ram_data.get("location", {})
+        curr_id = location_info.get("id", -1)
+        curr_name = location_info.get("name", last_location)
+        
+        
+        # Extraction des noms d'objets depuis la liste de dictionnaires [{'name':...}, ...]
+        detected_objs_raw_all = ram_data.get("detected_objects", [])
+        inventory_names_l = [item["name"].lower() for item in ram_data.get("inventory", [])]
+
+        detected_objs_raw = []
+        for obj in detected_objs_raw_all:
+            name_l = obj["name"].lower()
+            content_names_l = [c["name"].lower() for c in obj.get("contents", [])]
+            
+            # Si c'est le joueur (par son nom ou parce qu'il contient nos items d'inventaire), on l'ignore
+            is_player = (
+                name_l in ["inconnu", "self", "player", "me", "grunk"] or
+                (content_names_l and any(inv_item in content_names_l for inv_item in inventory_names_l))
+            )
+            
+            if not is_player:
+                detected_objs_raw.append(obj)
+
+        
+        inventory_data = ram_data.get("inventory", [])
+        inv_names_lower = [str(item.get("name", "")).lower() for item in inventory_data]
+
+        objects_in_ram = []
+        tree_view = []
+
+        for parent in detected_objs_raw:
+            p_name = parent["name"]
+            p_contents = parent.get("contents", [])
+            p_content_names = [c["name"] for c in p_contents]
+
+            # On normalise tout en minuscule pour la comparaison
+            p_name_l = p_name.lower()
+            p_content_names_l = [n.lower() for n in p_content_names]
+
+            # Logique de détection du joueur améliorée
+            is_player_container = (
+                p_name_l in ["inconnu", "self", "player", "me", "inventory", "grunk"] or
+                # On vérifie si UN des objets de l'inventaire est présent dans ce container
+                any(inv_item in p_content_names_l for inv_item in inv_names_lower) or
+                # Ou si le nom du parent est lui même dans l'inventaire
+                p_name_l in inv_names_lower
+            )
+
+            if is_player_container:
+                # Optionnel: print(f"DEBUG: On ignore l'objet joueur : {p_name}")
+                continue
+                
+            # --- Si c'est un vrai objet du décor ---
+            objects_in_ram.append(p_name)
+            
+            if p_contents:
+                c_names = [c["name"] for c in p_contents]
+                objects_in_ram.extend(c_names)
+                tree_view.append(f"- {p_name} (contains: {', '.join(c_names)})")
+            else:
+                tree_view.append(f"- {p_name}")
+    
+
+        # 3. Construction du prompt
+        # Note : on signale au LLM que les objets (missing...) sont des indices de puzzles
+        prompt = f"""
+                RAW GAME TEXT:
+                {raw_text}
+
+                --- RAM DATA (TECHNICAL TRUTH) ---
+                CURRENT LOCATION ID: {curr_id}
+                OBJECTS DETECTED IN RAM: {", ".join(objects_in_ram)}
+                OBJECTS DETECTED (HIERARCHY): 
+                {chr(10).join(tree_view)}
+
+
+                JSON SCHEMA:
+                Follow the StructuredObservation model.
+                """
+
+        try:
+            # Appel LLM (Assure-toi que call_llm supporte ton nouveau token/modèle)
+            response = self.call_llm(
+                prompt, 
+                EXTRACTOR_SYSTEM_PROMPT, 
+                seed=seed
+            )
+            
+            json_match = re.search(r'\{.*\}', response, re.DOTALL)
+            data = json.loads(json_match.group(0)) if json_match else json.loads(response)
+
+            data["location_id"] = curr_id
+            data["location_name"] =  curr_name
+            data["raw_ram_objects"] = objects_in_ram 
+            
+            if not data.get("location_name") or data.get("location_name") == "Unknown":
+                data["location_name"] = curr_name
+            
+            raw_data_mapping = data.get("name_translation", {})
+            valid_mapping = {}
+            lower_text = raw_text.lower()
+            for tech_name, friendly_name in raw_data_mapping.items():
+                if tech_name in objects_in_ram:
+                    if friendly_name.lower() in lower_text:
+                        valid_mapping[tech_name] = friendly_name
+                    else:
+                        pass
+
+            parent_names = [item["name"] for item in detected_objs_raw]
+            # Filtrage pour éviter les hallucinations
+            data["takeable_objects"] = [o for o in data.get("takeable_objects", []) if o in parent_names]
+            data["interactable_features"] = [o for o in data.get("interactable_features", []) if o in parent_names]
+            data["objects_in_room"] = detected_objs_raw
+            data["name_translation"] = valid_mapping
+
+            # Ajout automatique des secrets détectés dans la RAM (comme ton ID 101)
+            secrets = [o for o in objects_in_ram if "(missing" in o.lower()]
+            if secrets:
+                if "puzzle_clues" not in data: data["puzzle_clues"] = []
+                data["puzzle_clues"].append(f"RAM Alert: {len(secrets)} hidden object(s) detected. Search the area.")
+
+            return data
+
+        except Exception as e:
+            print(f"[Extractor Error] {e}")
+
+            manual_exits = []
+            lower_text = raw_text.lower()
+            for d in VALID_DIRECTIONS:
+                # On cherche la direction entourée d'espaces ou de ponctuation
+                if re.search(rf"\b{d}\b", lower_text):
+                    manual_exits.append(d)
+            
+            return {
+                "location_id": curr_id,
+                "location_name": curr_name,
+                "description_summary": raw_text,
+                "raw_ram_objects": objects_in_ram,
+                "objects_in_room" : detected_objs_raw,
+                "visible_exits": manual_exits, # On injecte le scan manuel
+                "name_translation": {},
+                "takeable_objects": [],
+                "puzzle_clues": ["Erreur d'extraction LLM."]
+            }
+
+#### Utilitaires de sections
+
+class SectionUtils:
+    """
+    Utilitaires de nos fonctions
+    """
+    @staticmethod
+    def extract_section_content(content: str, section_name: str) -> str:
+        if not content: return ""
+        pattern = rf"## {re.escape(section_name)}(.*?)(?=\n## |$)"
+        match = re.search(pattern, content, re.DOTALL)
+        return match.group(1).strip() if match else ""
+
+    @staticmethod
+    def update_section_content(content: str, section_name: str, new_content: str) -> str:
+        if not content: content = "# Zork Strategic Knowledge Base\n\n"
+        section_header = f"## {section_name}"
+        pattern = rf"## {re.escape(section_name)}(.*?)(?=\n## |$)"
+        match = re.search(pattern, content, re.DOTALL)
+        
+        full_new_section = f"{section_header}\n\n{new_content}\n"
+        
+        if match:
+            return content.replace(match.group(0), full_new_section, 1)
+        else:
+            return f"{content}\n\n{full_new_section}\n"
+
+    @staticmethod
+    def extract_cross_episode_section(content: str) -> str:
+        """Extrait la section 'Wisdom' qui doit persister entre les parties."""
+        return SectionUtils.extract_section_content(content, "CROSS-EPISODE INSIGHTS")
+
+VALID_DIRECTIONS = {
+    "n", "s", "e", "w", "ne", "nw", "se", "sw", "u", "d", "in", "out",
+    "north", "south", "east", "west", "northeast", "northwest", 
+    "southeast", "southwest", "up", "down"
+}
+
+class WorldMapper:
+    def __init__(self):
+        self.graph = {}
+        self.last_room_id = None
+        self.last_direction = None
+
+    def update_map(self, structured_data: dict, last_action: str, observation: str):
+        curr_id = str(structured_data.get("location_id"))
+        curr_name = structured_data.get("location_name")
+        new_exits = structured_data.get("visible_exits", [])
+        clean_directions = [d.lower() for d in new_exits if d.lower() in VALID_DIRECTIONS]
+        print("cleand directions", clean_directions)
+        
+        if curr_id not in self.graph:
+            self.graph[curr_id] = {
+                "name": curr_name,
+                "exits": {}, 
+                "blocked_exits" : {},
+                "potential_exits": clean_directions,
+                "puzzles": structured_data.get("puzzle_clues", []),
+                "items": structured_data.get("takeable_objects", []),   
+                "scenery": structured_data.get("interactable_features", []),
+                "visited_count": 1,
+                "items_scanned": False ,
+                "description": observation
+            }
+        else:
+            self.graph[curr_id]["visited_count"] += 1
+            self.graph[curr_id]["items"] = structured_data.get("takeable_objects", [])
+            self.graph[curr_id]["puzzles"] = list(set(self.graph[curr_id]["puzzles"] + structured_data.get("puzzle_clues", [])))
+
+            existing_potentials = set(self.graph[curr_id].get("potential_exits", []))
+            existing_potentials.update(clean_directions)
+            self.graph[curr_id]["potential_exits"] = list(existing_potentials)
+
+        direction_taken = self._extract_direction(last_action)
+
+        if self.last_room_id and self.last_room_id != curr_id and direction_taken:
+            # On vérifie si la direction prise était bien dans les "potentielles" de la pièce d'avant
+            self.graph[self.last_room_id]["exits"][direction_taken.lower()] = curr_id
+                
+            opp = self._get_opposite(direction_taken.lower())
+            if opp:
+                # On crée le lien inverse immédiatement
+                self.graph[curr_id]["exits"][opp] = self.last_room_id
+                print(f"🗺️ Map Link: {self.graph[self.last_room_id]['name']} <({direction_taken})--({opp})> {curr_name}")
+
+        self.last_room_id = curr_id
+
+    def mark_as_scanned(self, room_id: str):
+        """Appelé quand l'agent a fini d'examiner tous les objets d'une pièce."""
+        if room_id in self.graph:
+            self.graph[room_id]["items_scanned"] = True
+
+    def mark_blocked_exit(self, room_id: str, direction: str, reason: str):
+        """Stocke une direction qui a échoué pour ne plus la tenter inutilement."""
+        room_id = str(room_id)
+        if room_id in self.graph:
+            if "blocked_exits" not in self.graph[room_id]:
+                self.graph[room_id]["blocked_exits"] = {}
+            
+            # On stocke la direction et la raison (ex: "locked", "too dark")
+            self.graph[room_id]["blocked_exits"][direction.lower()] = reason
+
+    def _extract_direction(self, action: str) -> str:
+        action = action.lower().strip()
+        
+        # Mapping complet pour transformer chaque raccourci en toutes lettres
+        mapping = {
+            "n": "north",
+            "s": "south",
+            "e": "east",
+            "w": "west",
+            "u": "up",
+            "d": "down",
+            "ne": "northeast",
+            "nw": "northwest",
+            "se": "southeast",
+            "sw": "southwest",
+            "in": "inside",
+            "out": "outside",
+            "enter": "inside",
+            "exit": "outside"
+        }
+
+        # 1. On vérifie d'abord si l'action est un raccourci exact (ex: "ne")
+        if action in mapping:
+            return mapping[action]
+
+        # 2. Sinon, on cherche si un mot complet est présent dans la phrase (ex: "go northeast")
+        # On trie par longueur décroissante pour ne pas matcher "north" si c'est "northeast"
+        full_directions = sorted(mapping.values(), key=len, reverse=True)
+        for d in full_directions:
+            if d in action:
+                return d
+                
+        return None
+
+    def get_navigation_guidance(self, current_id: str, visible_exits: list) -> list:
+        current_id = str(current_id)
+        room_data = self.graph.get(current_id, {})
+        known_exits = room_data.get("exits", {}) # Ce qu'on a déjà traversé
+        
+        nav_lines = []
+        for direction in visible_exits:
+            dir_lower = direction.lower()
+            if dir_lower in known_exits:
+                target_id = known_exits[dir_lower]
+                target_name = self.graph.get(target_id, {}).get("name", "Unknown")
+                nav_lines.append(f"- {direction.upper()} : Already taken (leads to {target_name})")
+            else:
+                # C'est ici qu'on pousse l'agent à explorer !
+                nav_lines.append(f"- {direction.upper()} : 🌟 [NEW PATHWAY - TRY THIS]")
+        
+        return nav_lines
+
+    def _get_opposite(self, direction: str) -> str:
+        opposites = {
+            "north": "south", "south": "north",
+            "east": "west", "west": "east",
+            "up": "down", "down": "up",
+            "northeast": "southwest", "southwest": "northeast",
+            "northwest": "southeast", "southeast": "northwest",
+            "inside": "outside", "outside": "inside",
+            "n": "s", "s": "n", "e": "w", "w": "e",
+            "u": "d", "d": "u", "ne": "sw", "sw": "ne",
+            "nw": "se", "se": "nw", "in": "out", "out": "in"
+        }
+        return opposites.get(direction)
+
+    def generate_summary(self, current_id: str) -> str:
+        """Génère une vision stratégique complète pour le prompt de l'IA."""
+        current_id = str(current_id)
+        if current_id not in self.graph:
+            return "### 🗺️ MAP: Position current unknown in strategic memory."
+
+        summary = ["### ����️ STRATEGIC MAP & SPATIAL MEMORY:"]
+        
+        # 1. SORTIES ET NAVIGATION IMMÉDIATE
+        summary.append(f"**Current Location:** {self.graph[current_id]['name']}")
+        exits = self.graph[current_id].get("exits", {})
+        if exits:
+            for direction, target_id in exits.items():
+                room = self.graph.get(target_id, {})
+                name = room.get("name", "Unknown Area")
+                # Indicateur visuel pour savoir si on a fini le boulot là-bas
+                status = "✅ Scanned" if room.get("items_scanned") else "🔎 Items left"
+                summary.append(f"- {direction.upper()} -> {name} ({status})")
+        else:
+            summary.append("- No known exits explored yet from here.")
+
+        # 2. OBJETS DISPONIBLES DANS LE MONDE (AILLEURS)
+        # On ne liste pas la salle actuelle car elle est déjà dans l'observation RAM
+        other_rooms_with_stuff = []
+        for r_id, r_data in self.graph.items():
+            if r_id != current_id:
+                items = r_data.get("items", [])
+                features = r_data.get("scenery", [])
+                
+                if items or features:
+                    room_info = f"- In {r_data['name']}:"
+                    if items: room_info += f" Items: [{', '.join(items)}]"
+                    if features: room_info += f" Scenery: {', '.join(features)}"
+                    other_rooms_with_stuff.append(room_info)
+
+        if other_rooms_with_stuff:
+            summary.append("\n**🌍 WORLD OBJECTS (Memory):**")
+            summary.extend(other_rooms_with_stuff)
+
+        # 3. PUZZLES ET OBSTACLES (VISION GLOBALE)
+        unsolved_puzzles = []
+        for r_id, r_data in self.graph.items():
+            for p in r_data.get("puzzles", []):
+                unsolved_puzzles.append(f"[{r_data['name']}] {p}")
+        
+        # if unsolved_puzzles:
+        #     summary.append("\n**⚠️ ACTIVE PUZZLES / OBSTACLES:**")
+        #     summary.extend([f"- {p}" for p in unsolved_puzzles])
+
+        # 4. ÉTAT D'EXPLORATION DE LA SALLE ACTUELLE
+        # is_scanned = self.graph[current_id].get("items_scanned", False)
+        # summary.append(f"\n**STATUS:** {'Room fully examined. You can move.' if is_scanned else 'New items detected here. Examine them before leaving.'}")
+        summary.append(f"**Current Location:** {self.graph[current_id]['name']}")
+
+        potential = self.graph[current_id].get("potential_exits", [])
+        known = self.graph[current_id].get("exits", {})
+        blocked = self.graph[current_id].get("blocked_exits", {})
+
+        summary.append("**Immediate Navigation:**")
+        # On fusionne tout pour ne rien rater
+        all_possible = set(potential) | set(known.keys()) | set(blocked.keys())
+
+        if not all_possible : 
+            summary.append("- ⚠️ NO EXITS DETECTED IN SCAN.")
+            summary.append("- **HYPOTHETICAL DIRECTIONS:** [NORTH, SOUTH, EAST, WEST,NORTHEAST,NORTHWEST, SOUTHEAST, SOUTHWEST , UP, DOWN]")
+            summary.append("- **ADVICE:** Use 'LOOK' or 'SEARCH' to confirm exits before moving, otherwise you might hit a wall.")
+
+        for d in all_possible:
+            d_l = d.lower()
+            if d_l in blocked:
+                summary.append(f"- {d.upper()} : 🚫 BLOCKED ({blocked[d_l]})")
+            elif d_l in known:
+                target_name = self.graph.get(known[d_l], {}).get("name", "Unknown")
+                summary.append(f"- {d.upper()} : Leads to {target_name} ✅")
+            else:
+                summary.append(f"- {d.upper()} : 🌟 [NEW - NEVER TESTED]")
+
+        room_data = self.graph.get(current_id, {})
+        
+        # Affichage des sorties bloquées
+        blocked = room_data.get("blocked_exits", {})
+        if blocked:
+            summary.append("\n**🚫 BLOCKED / FAILED DIRECTIONS:**")
+            for d, reason in blocked.items():
+                summary.append(f"- {d.upper()} : {reason}")
+
+        # Affichage des notes (ex: One-way)
+        for note in room_data.get("notes", []):
+            summary.append(f"- ⚠️ {note}")
+
+        return "\n".join(summary)
 
 
 if __name__ == "__main__":

map_graph.py

@@ -0,0 +1,119 @@
+"""
+map_graph.py
+Gère la structure du graphe, la persistance JSON et les algorithmes spatiaux (BFS).
+"""
+import json
+import os
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional, Set, Tuple
+from collections import deque
+
+@dataclass
+class Connection:
+    to_id: int
+    direction: str
+    is_verified: bool = True  # True si on l'a vraiment traversé
+
+@dataclass
+class RoomNode:
+    id: int
+    name: str
+    # Connexions: direction -> Connection object
+    exits: Dict[str, Connection] = field(default_factory=dict)
+    # Murs/Bloquages: direction -> nombre d'échecs
+    failed_exits: Dict[str, int] = field(default_factory=dict)
+    visited_count: int = 1
+
+class MapGraph:
+    def __init__(self):
+        self.rooms: Dict[int, RoomNode] = {}
+        
+        # Mapping des directions inverses pour l'inférence
+        self.inverse_dirs = {
+            "n": "s", "s": "n", "e": "w", "w": "e", 
+            "north": "south", "south": "north", 
+            "east": "west", "west": "east",
+            "up": "down", "down": "up",
+            "ne": "sw", "sw": "ne", "nw": "se", "se": "nw",
+            "enter": "exit", "exit": "enter", "in": "out", "out": "in"
+        }
+
+    def add_or_update_room(self, room_id: int, name: str):
+        """Crée ou met à jour un noeud."""
+        if room_id not in self.rooms:
+            self.rooms[room_id] = RoomNode(id=room_id, name=name)
+        else:
+            self.rooms[room_id].visited_count += 1
+            # On garde le nom le plus long (souvent le plus descriptif)
+            if len(name) > len(self.rooms[room_id].name):
+                self.rooms[room_id].name = name
+
+    def add_connection(self, from_id: int, to_id: int, direction: str):
+        """Ajoute une arête dirigée."""
+        if from_id not in self.rooms or to_id not in self.rooms:
+            return
+
+        # 1. Connexion directe (Vérifiée)
+        self.rooms[from_id].exits[direction] = Connection(to_id=to_id, direction=direction, is_verified=True)
+        
+        # 2. Si une connexion précédente échouée existait, on la nettoie (Pruning)
+        if direction in self.rooms[from_id].failed_exits:
+            del self.rooms[from_id].failed_exits[direction]
+
+        # 3. Connexion inverse (Inférée/Non vérifiée)
+        # On suppose que si on va au Nord, le Sud ramène au départ.
+        rev_dir = self.inverse_dirs.get(direction)
+        if rev_dir:
+            target_room = self.rooms[to_id]
+            # On ajoute seulement si l'exit n'existe pas déjà
+            if rev_dir not in target_room.exits:
+                target_room.exits[rev_dir] = Connection(to_id=from_id, direction=rev_dir, is_verified=False)
+
+    def record_failure(self, room_id: int, direction: str):
+        """Enregistre un mur/bloquage."""
+        if room_id in self.rooms:
+            self.rooms[room_id].failed_exits[direction] = self.rooms[room_id].failed_exits.get(direction, 0) + 1
+
+    def get_shortest_path(self, start_id: int, target_id: int) -> Optional[List[str]]:
+        """BFS pour trouver le chemin le plus court."""
+        queue = deque([(start_id, [])])
+        visited = {start_id}
+        
+        while queue:
+            curr, path = queue.popleft()
+            if curr == target_id:
+                return path
+            
+            if curr in self.rooms:
+                for d, conn in self.rooms[curr].exits.items():
+                    if conn.to_id not in visited:
+                        visited.add(conn.to_id)
+                        queue.append((conn.to_id, path + [d]))
+        return None
+
+    def get_hubs(self) -> List[str]:
+        """Retourne les noms des salles importantes (Hubs) avec >3 sorties."""
+        return [r.name for r in self.rooms.values() if len(r.exits) > 3]
+
+    # --- Persistance JSON ---
+    def save(self, filepath: str):
+        data = {
+            str(rid): asdict(node) for rid, node in self.rooms.items()
+        }
+        with open(filepath, 'w') as f:
+            json.dump(data, f, indent=2)
+
+    def load(self, filepath: str):
+        if not os.path.exists(filepath): return
+        try:
+            with open(filepath, 'r') as f:
+                data = json.load(f)
+            self.rooms = {}
+            for rid, rdata in data.items():
+                node = RoomNode(id=int(rid), name=rdata['name'], visited_count=rdata['visited_count'])
+                node.failed_exits = rdata['failed_exits']
+                # Reconstruire les objets Connection
+                node.exits = {d: Connection(**c) for d, c in rdata['exits'].items()}
+                self.rooms[int(rid)] = node
+        except Exception as e:
+            print(f"Error loading map: {e}")

mcp_server.py

@@ -1,27 +1,8 @@
 """
-Student MCP Server for Text Adventure Games
+Example: MCP Server for Text Adventures
 
-This is your MCP server submission. Implement the tools that your agent
-will use to play text adventure games.
-
-Required tool:
-    play_action(action: str) -> str
-        Execute a game command and return the result.
-
-Recommended tools:
-    memory() -> str
-        Return current game state, score, and recent history.
-    
-    inventory() -> str  
-        Return the player's current inventory.
-    
-    get_map() -> str
-        Return a map of explored locations.
-
-Test your server with:
-    fastmcp dev submission_template/mcp_server.py
-
-Then open the MCP Inspector in your browser to test the tools interactively.
+A complete MCP server that exposes text adventure games via tools.
+This demonstrates a full-featured server with memory, mapping, and inventory.
 """
 
 import sys
@@ -31,179 +12,669 @@ import os
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 from fastmcp import FastMCP
-from games.zork_env import TextAdventureEnv
-
+from games.zork_env import TextAdventureEnv, list_available_games
 
-# =============================================================================
-# Create the MCP Server
-# =============================================================================
+import asyncio
 
-mcp = FastMCP("Student Text Adventure Server")
+# Get game from environment variable (default: zork1)
+INITIAL_GAME = os.environ.get("GAME", "zork1")
 
+# Create the MCP server
+mcp = FastMCP("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
-    """
+class GameState:
+    """Manages the text adventure game state and exploration data."""
     
-    def __init__(self):
-        self.env: TextAdventureEnv = None
-        self.state = None
-        self.game_name: str = ""
-        # TODO: Add more state tracking
-        # self.history: list[tuple[str, str]] = []
-        # self.explored_locations: dict[str, set[str]] = {}
-        # self.current_location: str = ""
-    
-    def initialize(self, game: str = "zork1"):
-        """Initialize or reset the game."""
+    def __init__(self, game: str = "zork1"):
         self.game_name = game
         self.env = TextAdventureEnv(game)
         self.state = self.env.reset()
-        # TODO: Reset your state tracking here
-        return self.state.observation
+        self.history: list[tuple[str, str]] = []
+        self.explored_locations: dict[str, set[str]] = {}
+        self.current_location: str = self._extract_location(self.state.observation)
     
-    def step(self, action: str) -> str:
-        """Execute an action and return the result."""
-        if self.env is None:
-            self.initialize()
-        
+    def _extract_location(self, observation: str) -> str:
+        """Extract location name from observation (usually first line)."""
+        lines = observation.strip().split('\n')
+        return lines[0] if lines else "Unknown"
+
+    def clean_text(self, text: str) -> str:
+        """Transforme 'obj91: pants parent87...' en 'pants'."""
+        text = str(text).lower()
+        if ":" in text:
+            # On prend la partie après le matricule obj
+            name_part = text.split(":", 1)[1].strip()
+            # On coupe avant les métadonnées techniques
+            for stop_word in [" parent", " sibling", " child", " attributes"]:
+                if stop_word in name_part:
+                    name_part = name_part.split(stop_word)[0].strip()
+            return name_part
+        return text
+    
+    def take_action(self, action: str) -> str:
+        """Execute a game action and return the result."""
         self.state = self.env.step(action)
+        result = self.state.observation
+        
+        # Track history
+        self.history.append((action, result))
+        if len(self.history) > 50:
+            self.history = self.history[-50:]
+        
+        # Update map
+        new_location = self._extract_location(result)
+        if action in ["north", "south", "east", "west", "up", "down", 
+                      "enter", "exit", "n", "s", "e", "w", "u", "d"]:
+            if self.current_location not in self.explored_locations:
+                self.explored_locations[self.current_location] = set()
+            if new_location != self.current_location:
+                self.explored_locations[self.current_location].add(f"{action} -> {new_location}")
+        self.current_location = new_location
+        
+        return result
+    
+    # def get_heuristic_actions(self) -> str:
+    #         """
+    #         Génère des actions ultra-précises en fusionnant l'observation textuelle 
+    #         et le scan de la mémoire vive du jeu (God Mode).
+    #         """
+
+    #         self._debug_log("HEURISTIC - STRUCTURED")
+
+    #         # visible_objs = structured_data.get("takeable_objects", [])
+    #         # puzzles = structured_data.get("puzzle_clues", [])
+    #         # exits = structured_data.get("visible_exits", [])
+
+    #         categorized_actions: Dict[str, Set[str]] = {
+    #         "navigation": {"north", "south", "east", "west","northeast", "northwest", "southeast", "southwest","up", "down", "in", "out"},
+    #         "system": {"look", "inventory", "wait"},
+    #         "inventory_interactions": set(),
+    #         "environment_interactions": set(),
+    #         "contextual": set()
+    #         }
+
+    #         BASE_ACTIONS = {
+    #         "look",
+    #         "inventory",
+    #         "wait"
+    #         }
+
+    #         DIRECTIONS = {
+    #         "north", "south", "east", "west","northwest","northeast","southeast","southwest"
+    #         "up", "down", "in", "out",
+    #         "n", "s", "e", "w", "u", "d","nw","ne","se","sw"
+    #         }
+
+    #         INVENTORY_VERBS = {
+    #             "examine",
+    #             "use",
+    #             "drop",
+    #         }
+
+    #         ROOM_VERBS = {
+    #         "examine",
+    #         "open",
+    #         "close",
+    #         "push",
+    #         "pull",
+    #         "take",
+    #         }
+
+    #         inventory_items = [i['name'] for i in self.state.inventory_raw] # Liste de dicts {'name':...}
+    #         room_items = structured_data.get("raw_ram_objects", [])
+
+    #         available_verbs = ["examine", "take", "drop", "look", "inventory", "wait"]
+
+    #         actions: Set[str] = set()
+
+    #         obs = self.state.observation.lower()
+
+    #         clean_inventory = [self.clean_text(i) for i in self.state.inventory]
+
+    #         for item in clean_inventory:
+    #             for verb in INVENTORY_VERBS:
+    #                 categorized_actions["inventory_interactions"].add(f"{verb} {item}")
+
+    #         if "door" in obs:
+    #             categorized_actions["environment_interactions"] |= {"open door", "close door", "examine door"}
+            
+    #         if "window" in obs:
+    #             categorized_actions["environment_interactions"] |= {"open window", "examine window"}
+            
+    #         if "stairs" in obs or "staircase" in obs:
+    #             actions |= {"up", "down"}
+    #             categorized_actions["contextual"] |= {"up stairs", "down stairs"}
+
+    #         if "dark" in obs or "can't see" in obs:
+    #             for item in clean_inventory:
+    #                 if any(k in item for k in ["lamp", "torch", "light"]):
+    #                     categorized_actions["inventory_interactions"].add(f"use {item}")
+    #                     categorized_actions["inventory_interactions"].add(f"turn on {item}")
+
+    #         if any(k in obs for k in ["man", "woman", "person", "creature"]):
+    #             categorized_actions["contextual"] |= {"talk", "listen", "attack"}
+
+    #         if any(k in obs for k in ["noise", "sound", "voice", "squeal"]):
+    #             categorized_actions["contextual"].add("listen")
+    #             categorized_actions["contextual"].add("examine noise")
+            
+    #         # --- 7. Anti-boucle simple ---
+    #         if self.history:
+    #             last_action = self.history[-1]
+    #             if last_action in actions:
+    #                 actions.remove(last_action)
+
+
+    #         final_output = []
+    #         for category, acts in categorized_actions.items():
+    #             if acts:
+    #                 # On trie et on formate chaque catégorie
+    #                 sorted_acts = sorted(list(acts))
+    #                 category_text = f"\n{category.replace('_', ' ').upper()}:\n"
+    #                 category_text += "\n".join([f"  - {a}" for a in sorted_acts])
+    #                 final_output.append(category_text)
+
+    #         return "\n".join(final_output)
+
+    def get_heuristic_actions(self, structured_data: dict) -> str:
+        """
+        Fournit au LLM les briques nécessaires pour construire ses propres actions
+        en se basant sur la vérité de la RAM.
+        """
+        self._debug_log("HEURISTIC - COMPONENT BASED")
+
+        # 1. Récupération des objets réels (RAM + Inventaire)
+        # On utilise les noms exacts venant de la RAM pour éviter les erreurs
+        inventory_items = [i['name'] for i in self.state.inventory_raw] # Liste de dicts {'name':...}
+        room_items = structured_data.get("raw_ram_objects", [])
         
-        # TODO: Update your state tracking here
-        # self.history.append((action, self.state.observation))
-        # Update location tracking, etc.
+        # 2. Définition des Verbes (Le "Lexique")
+        # On ne donne que les verbes pertinents à la situation
+        available_verbs = ["examine", "take", "drop", "look", "inventory", "wait"]
         
-        return self.state.observation
+        obs = self.state.observation.lower()
+        
+        if any(k in obs for k in ["door", "window", "container", "box"]):
+            available_verbs += ["open", "close", "unlock"]
+        
+        if any(k in obs for k in ["noise", "sound", "squeal", "quiet"]):
+            available_verbs.append("listen")
+            
+        if "dark" in obs or "torch" in str(inventory_items):
+            available_verbs += ["turn on", "light"]
+
+        # 3. Construction du message d'aide
+        final_output = [
+            "### ACTION CONSTRUCTION KIT",
+            f"VERBS: {', '.join(sorted(set(available_verbs)))}",
+            f"INVENTORY: {', '.join(inventory_items) if inventory_items else 'Empty'}",
+            f"ROOM OBJECTS: {', '.join(room_items) if room_items else 'None visible'}",
+            "\nNAVIGATION: n, s, e, w, ne, nw, se, sw, u, d, in, out",
+            "\nEXAMPLES: 'examine tracks', 'turn on torch', 'open mailbox', 'listen'"
+        ]
+
+        return "\n".join(final_output)
+
+
+    def _debug_log(self, message: str):
+        """Envoie un log de debug vers stderr pour ne pas polluer le flux MCP."""
+        print(f"DEBUG_HEURISTIC: {message}", file=sys.stderr, flush=True)
+
+    def get_memory(self) -> str:
+        """Get a summary of current game state."""
+        recent = self.history[-5:] if self.history else []
+        recent_str = "\n".join([f"  > {a} -> {r[:60]}..." for a, r in recent]) if recent else "  (none yet)"
+        
+        return f"""Current State:
+- Location: {self.current_location}
+- Score: {self.state.score} points
+- Moves: {self.state.moves}
+- Game: {self.game_name}
+
+Recent Actions:
+{recent_str}
+
+Current Observation:
+{self.state.observation}"""
     
-    def get_score(self) -> int:
-        """Get current score."""
-        return self.state.score if self.state else 0
+    def get_map(self) -> str:
+        """Get a map of explored locations."""
+        if not self.explored_locations:
+            return "Map: No locations explored yet. Try moving around!"
+        
+        lines = ["Explored Locations and Exits:"]
+        for loc, exits in sorted(self.explored_locations.items()):
+            lines.append(f"\n* {loc}")
+            for exit_info in sorted(exits):
+                lines.append(f"    -> {exit_info}")
+        
+        lines.append(f"\n[Current] {self.current_location}")
+        return "\n".join(lines)
     
-    def get_moves(self) -> int:
-        """Get number of moves taken."""
-        return self.state.moves if self.state else 0
+    def get_inventory(self) -> str:
+        """Get current inventory."""
+        items = self.state.inventory if hasattr(self.state, 'inventory') and self.state.inventory else []
+        
+        if not items:
+            return "Inventory: You are empty-handed."
+        
+        item_names = []
+        for item in items:
+            item_str = str(item)
+            item_lower = item_str.lower()
+            if "parent" in item_lower:
+                idx = item_lower.index("parent")
+                name = item_str[:idx].strip()
+                if ":" in name:
+                    name = name.split(":", 1)[1].strip()
+                item_names.append(name)
+            elif ":" in item_str:
+                name = item_str.split(":")[1].strip()
+                item_names.append(name)
+            else:
+                item_names.append(item_str)
+        
+        return f"Inventory: {', '.join(item_names)}"
 
 
-# Global game manager
-_game = GameManager()
+# Global game state
+_game_state: GameState | None = None
 
 
-def get_game() -> GameManager:
-    """Get or initialize the game manager."""
-    global _game
-    if _game.env is None:
-        # Get game from environment variable (set by evaluator)
-        game = os.environ.get("GAME", "zork1")
-        _game.initialize(game)
-    return _game
+def get_game() -> GameState:
+    """Get or initialize the game state."""
+    global _game_state
+    if _game_state is None:
+        _game_state = GameState(INITIAL_GAME)
+    return _game_state
 
 
 # =============================================================================
-# MCP Tools - IMPLEMENT THESE
+# MCP Tools
 # =============================================================================
 
 @mcp.tool()
 def play_action(action: str) -> str:
     """
-    Execute a game command and return the result.
-    
-    This is the main tool for interacting with the game.
+    Execute a game action in the text adventure.
     
     Args:
-        action: The command to execute (e.g., "north", "take lamp", "open mailbox")
-        
+        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
+        The game's response to your 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
+    # Add score info
+    score_info = f"\n\n[Score: {game.state.score} | Moves: {game.state.moves}]"
     
-    result = game.step(action)
+    if game.state.reward > 0:
+        score_info = f"\n\n+{game.state.reward} points! (Total: {game.state.score})"
     
-    # Optional: Append score info
-    # result += f"\n[Score: {game.get_score()} | Moves: {game.get_moves()}]"
+    done_info = ""
+    if game.state.done:
+        done_info = "\n\nGAME OVER"
     
-    return result
+    return result + score_info + done_info
 
 
-# TODO: Implement additional tools to help your agent
+@mcp.tool()
+def memory() -> str:
+    """
+    Get a summary of the current game state.
+    
+    Returns location, score, moves, recent actions, and current observation.
+    """
+    return get_game().get_memory()
 
-# @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 get_map() -> str:
+    """
+    Get a map showing explored locations and connections.
+    
+    Useful for navigation and avoiding getting lost.
+    """
+    return get_game().get_map()
 
 
+@mcp.tool()
+def inventory() -> str:
+    """
+    Check what items you are currently carrying.
+    """
+    return get_game().get_inventory()
+
+# Dans mcp_server.py
+
 # @mcp.tool()
-# def inventory() -> str:
-#     """
-#     Check what the player is carrying.
-#     
-#     Returns:
-#         List of items in the player's inventory
-#     """
+# def get_valid_actions_cheat() -> str:
+#     """[GOD MODE] Liste des actions syntaxiques via Spacy/Jericho."""
 #     game = get_game()
-#     result = game.step("inventory")
-#     return result
+#     # On appelle la méthode de TON wrapper TextAdventureEnv
+#     actions = game.env.get_valid_actions()
+#     return "ACTIONS VALIDES :\n" + ", ".join(actions)
+ 
+
+@mcp.tool()
+async def get_valid_actions_cheat() -> str:
+    """
+    [GOD MODE] Returns the list of ALL valid actions currently possible.
+    """
+    # On utilise le verrou pour empêcher le calcul parallèle
+    try:
+        game = get_game()
+        jericho_env = game.env.env 
+        
+        # Jericho est synchrone, on l'exécute normalement
+        valid_actions = jericho_env.get_valid_actions(use_parallel=False)
+
+        if not valid_actions:
+            return "Jericho returned an empty list of actions."
+            
+        return "VALID ACTIONS:\n" + ", ".join(valid_actions)
+
+    except Exception as e:
+        return f"Error retrieving valid actions: {str(e)}"
+
 
 
 # @mcp.tool()
-# def get_map() -> str:
+# def get_valid_actions_cheat() -> str:
 #     """
-#     Get a map of explored locations.
-#     
-#     Returns:
-#         A text representation of explored locations and connections
+#     [GOD MODE] Returns the absolute list of logical actions 
+#     by scanning the game's internal memory tree.
 #     """
-#     game = get_game()
-#     # TODO: Return map of explored locations
-#     pass
+#     return get_game().get_heuristic_actions()
+        
+@mcp.tool()
+def detect_objects_cheat() -> str:
+    """
+    [GOD MODE] Scans the game memory to find interactive objects in the current location.
+    Returns their internal game names.
+    """
+    try:
+        # identify_interactive_objects renvoie les objets avec lesquels on peut interagir
+        # Note: Cette fonction Jericho n'est pas dispo pour TOUS les jeux, mais souvent pour Zork/LostPig
+        objs = env.identify_interactive_objects() 
+        return f"OBJECTS IN MEMORY: {objs}"
+    except Exception as e:
+        return f"Feature not available: {e}"
+
+
+@mcp.tool()
+def cheat_sense_surroundings() -> str:
+    try:
+        game = get_game()
+        j_env = game.env.env
+        # player_loc = j_env.get_player_location() # Ex: 93
+        player_loc = 164
+        
+        # On récupère tous les objets du jeu (souvent plusieurs centaines)
+        world_objs = j_env.get_world_objects()
+        contents = []
+        
+        for obj in world_objs:
+            # On vérifie si le parent est la pièce actuelle
+            if obj.parent == player_loc:
+                name = str(obj.name).replace('\x00', '').strip()
+                # On ignore le joueur lui-même et les noms vides
+                if name and "player" not in name.lower():
+                    contents.append(f"{name} (ID:{obj.num})")
+
+        return "VISIBLE IN MEMORY: " + (", ".join(contents) if contents else "Empty Room")
+    except Exception as e:
+        return f"Error: {e}"
+
+@mcp.tool()
+def get_game_dictionary() -> list[str]:
+    """Récupère tous les mots compris par le jeu."""
+    game = get_game()
+    # Récupère les objets DictionaryWord
+    words = game.env.env.get_dictionary()
+    return [w.word for w in words]
+
+@mcp.tool()
+def get_action_grammar() -> str:
+    """Récupère les modèles de phrases autorisées (ex: 'put X on Y')."""
+    game = get_game()
+    return game.env.env.bindings.get('grammar', 'Non disponible') 
+
+
+@mcp.tool()
+def cheat_get_valid_exits() -> str:
+    """[GOD MODE] Analyse les propriétés de la pièce actuelle pour trouver les sorties."""
+    try:
+        game = get_game()
+        j_env = game.env.env
+        # room_id = j_env.get_player_location()
+        room_id = 166
+        
+        # On définit les directions cardinales
+        directions = ['north', 'south', 'east', 'west', 'up', 'down', 'ne', 'nw', 'se', 'sw', 'in', 'out']
+        valid_exits = []
+
+        # On utilise une méthode de lecture de propriété si elle existe, 
+        # sinon on se rabat sur une analyse de l'observation textuelle 'propre'
+        for d in directions:
+            try:
+                # Tentative de lecture directe de la destination pour la direction d
+                dest_id = j_env.get_next_location(room_id, d)
+                if dest_id > 0:
+                    valid_exits.append(d)
+            except:
+                continue
+
+        # FALLBACK : Si le moteur Jericho est vraiment trop bridé pour les sorties
+        if not valid_exits:
+            obs = game.state.observation.lower()
+            # On cherche des patterns classiques comme "Exit: North" ou "to the south"
+            for d in directions:
+                if f" {d}" in obs and ("exit" in obs or "lead" in obs or "way" in obs):
+                    valid_exits.append(d)
+        
+        return f"STRICT VALID EXITS: {', '.join(valid_exits) if valid_exits else 'None (Try exploring manually)'}"
+    except Exception as e:
+        return f"Error: {e}"
+
+@mcp.tool()
+def cheat_get_status() -> str:
+    """
+    [GOD MODE] Returns the internal state: Score, Moves, and Inventory.
+    """
+    try:
+        score = env.get_score()
+        # Note: inventory est une liste d'objets Jericho
+        inv_objs = env.get_inventory()
+        inv_names = [obj.name for obj in inv_objs]
+        
+        return f"""
+SCORE: {score}
+INVENTORY (INTERNAL): {inv_names}
+"""
+    except Exception as e:
+        return str(e)
 
 
+@mcp.tool()
+def get_location_info() -> dict:
+    """
+    Scan la pièce actuelle et le contenu immédiat des objets (Niveau +1).
+    Permet au LLM de déduire les types via les noms et la structure.
+    """
+    try:
+        game = get_game()
+        env = game.env.env
+        
+        def clean_name(name):
+            return str(name).replace('\x00', '').strip() if name else "Inconnu"
+
+        # 1. Localisation racine
+        loc = env.get_player_location()
+        room_id = loc.num if hasattr(loc, 'num') else int(loc)
+        room_obj = env.get_object(room_id)
+        
+        world_objs = env.get_world_objects()
+
+        # 2. Collecte des objets de la pièce
+        detected_elements = []
+        for obj in world_objs:
+            # On ne prend que les objets dont le parent est la pièce actuelle
+            if obj.parent == room_id:
+                name = clean_name(obj.name)
+                if "player" in name.lower(): continue
+
+                # Scan de niveau +1 : on regarde juste si cet objet contient des trucs
+                sub_contents = []
+                for sub_obj in world_objs:
+                    if sub_obj.parent == obj.num:
+                        sub_contents.append({
+                            "id": sub_obj.num,
+                            "name": clean_name(sub_obj.name)
+                        })
+
+                # On construit une fiche simple
+                element = {
+                    "id": obj.num,
+                    "name": name,
+                    "contains_count": len(sub_contents),
+                    "contents": sub_contents # Liste des noms/id immédiats
+                }
+                detected_elements.append(element)
+
+        return {
+            "status": "success",
+            "location": {
+                "id": room_id,
+                "name": clean_name(room_obj.name)
+            },
+            "detected_objects": detected_elements,
+            "inventory": [
+                {"id": i.num, "name": clean_name(i.name)} 
+                for i in env.get_inventory()
+            ],
+            "world_hash": env.get_world_state_hash()
+        }
+
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
 # @mcp.tool()
-# def get_valid_actions() -> str:
+# def get_location_info() -> dict:
 #     """
-#     Get a list of likely valid actions from the current location.
-#     
-#     Returns:
-#         List of actions that might work here
+#     Retourne la vérité absolue de la RAM : Localisation, Objets présents, 
+#     Inventaire et Hash d'état.
 #     """
-#     # 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"
+#     try:
+#         game = get_game()
+#         env = game.env.env
+        
+#         # 1. Récupération de la localisation précise
+#         loc = env.get_player_location()
+#         room_id = loc.num if hasattr(loc, 'num') else int(loc)
+#         room_obj = env.get_object(room_id)
+#         room_name = str(room_obj.name).replace('\x00', '').strip() if room_obj else "Unknown Room"
+        
+#         # 2. Scan des objets présents dans la pièce (Vérité RAM)
+#         world_objs = env.get_world_objects()
+#         detected_objects = []
+#         for obj in world_objs:
+#             # On vérifie si l'objet est physiquement dans la pièce
+#             if obj.parent == room_id:
+#                 name = str(obj.name).replace('\x00', '').strip()
+#                 # On ignore le joueur et les objets sans nom
+#                 if name and "player" not in name.lower():
+#                     # On stocke le nom et l'ID pour le "Radar" de l'agent
+#                     detected_objects.append({"name": name, "id": obj.num})
+                
+#         # 3. Inventaire technique (Objets portés)
+#         inventory = []
+#         for obj in env.get_inventory():
+#             inv_name = str(obj.name).replace('\x00', '').strip()
+#             inventory.append({"name": inv_name, "id": obj.num})
+                
+#         # 4. Hash d'état pour détecter tout changement atomique
+#         world_hash = env.get_world_state_hash()
+                
+#         return {
+#             "status": "success",
+#             "location": {
+#                 "id": room_id,
+#                 "name": room_name
+#             },
+#             "detected_objects": detected_objects,
+#             "inventory": inventory,
+#             "world_hash": world_hash
+#         }
+        
+#     except Exception as e:
+#         return {
+#             "status": "error",
+#             "message": str(e),
+#             "location": {"id": -1, "name": "Error"}
+#         }
 
+@mcp.tool()
+def get_current_room_name() -> str:
+    """Récupère le nom officiel de la pièce dans la mémoire du jeu."""
+    try:
+        game = get_game()
+        env = game.env.env # Accès Jericho
+        
+        # 1. On récupère l'ID de la pièce actuelle
+        room_id = env.get_player_location()
+        
+        # 2. On récupère l'objet correspondant
+        room_obj = env.get_object(room_id)
+        
+        # 3. On renvoie son nom (en forçant le string pour éviter les bytes)
+        return str(room_obj.name).strip()
+    except Exception as e:
+        return f"Error: {e}"
+
+@mcp.tool()
+def test_dictionary_access() -> str:
+    """[TEST] Récupère un échantillon du dictionnaire interne du jeu."""
+    try:
+        game = get_game()
+        # Récupère tous les mots connus du parseur
+        words = game.env.env.get_dictionary()
+        # On en prend 20 pour ne pas surcharger le log
+        sample = [w.word for w in words[:20]]
+        return f"DICTIONARY SAMPLE ({len(words)} words total): " + ", ".join(sample)
+    except Exception as e:
+        return f"Dictionary Test Failed: {e}"
 
+@mcp.tool()
+def test_grammar_access() -> str:
+    """[TEST] Récupère les modèles d'actions (Grammaire)."""
+    try:
+        game = get_game()
+        # Les bindings contiennent la grammaire des verbes
+        bindings = game.env.env.bindings
+        grammar = bindings.get('grammar', 'No grammar found')
+        # On coupe si c'est trop long pour l'affichage
+        return f"GRAMMAR SNIPPET: {grammar[:300]}..."
+    except Exception as e:
+        return f"Grammar Test Failed: {e}"
+
+@mcp.tool()
+def get_object_tree_simple() -> str:
+    """[TEST] Liste brute des 5 premiers objets pour voir leur structure."""
+    try:
+        game = get_game()
+        objs = game.env.env.get_world_objects()
+        res = []
+        for o in objs[:5]:
+            res.append(f"Obj{o.num}: {o.name} (Parent:{o.parent})")
+        return "OBJECT TREE SAMPLE: " + " | ".join(res)
+    except Exception as e:
+        return f"Object Tree Failed: {e}"
 # =============================================================================
-# Run the server
+# Main
 # =============================================================================
 
 if __name__ == "__main__":
-    # This runs the server with stdio transport (for MCP clients)
     mcp.run()

memory.py

@@ -0,0 +1,257 @@
+import os
+import re
+from dataclasses import dataclass, asdict
+from typing import List, Dict, Optional
+
+
+@dataclass
+class MemoryEntry:
+    category: str     
+    type: str         
+    title: str
+    text: str
+    turn_created: int
+    data_list: Optional[List[str]] = None
+
+MEMORY_SYNTHESIS_PROMPT = MEMORY_SYNTHESIS_PROMPT = """
+[ROLE]
+You are the Memory Architect. Your goal is to extract ONLY NEW and RELEVANT facts.
+
+[INPUT]
+- Location: {location}
+- Action: {action}
+- Result: {result}
+- Known Memories: {existing}
+
+[TASK]
+Compare the 'Result' with 'Known Memories'. 
+- If the result contains NO NEW information or state changes, return {{"should_remember": false}}.
+- If something changed or a new fact appeared, create a memory.
+- Use the "supersedes" list to name the titles of old memories that are now obsolete.
+
+[CRITICAL: NO DUPLICATES]
+Do NOT extract information already present in 'Known Memories'. 
+Focus on state changes (e.g., door opened, item taken).
+
+[OUTPUT FORMAT]
+Return ONLY a JSON object. No markdown blocks, no explanations.
+{{
+    "should_remember": bool,
+    "memories": [
+        {{
+            "title": "Unique Title", 
+            "text": "The new fact",
+            "category": "DANGER"|"MECHANIC"|"STATE"|"INFO",
+            "type": "PERMANENT"|"EPHEMERAL"|"CORE"
+        }}
+    ],
+    "supersedes": ["Old Title"]
+}}
+"""
+
+class HierarchicalMemoryManager:
+    def __init__(self, call_llm_func, filepath="Memories.md"):
+        self.call_llm = call_llm_func
+        self.filepath = filepath
+        self.memories: Dict[str, List[MemoryEntry]] = {} # Key: Location Name
+        self.load_from_md() # Chargement au démarrage
+
+    def load_from_md(self):
+        """Charge les mémoires depuis le fichier Markdown."""
+        if not os.path.exists(self.filepath):
+            return
+
+        current_loc = None
+        pattern = re.compile(r'- \[(.*?)\] \[(.*?)\] \*\*(.*?)\*\*: (.*)')
+        
+        with open(self.filepath, 'r', encoding='utf-8') as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith("## Location:"):
+                    current_loc = line.split(":", 1)[1].strip()
+                    self.memories[current_loc] = []
+                elif line.startswith("- [") and current_loc:
+                    match = pattern.match(line)
+                    if match:
+                        mem_type, cat, title, text = match.groups()
+                        self.memories[current_loc].append(MemoryEntry(
+                            category=cat, type=mem_type, title=title, text=text, turn_created=0
+                        ))
+
+    def _is_redundant(self, location: str, new_text: str) -> bool:
+        """Vérifie si le texte existe déjà (partiellement ou totalement) dans ce lieu."""
+        if location not in self.memories:
+            return False
+        
+        new_text_clean = new_text.lower().strip()
+        for m in self.memories[location]:
+            existing_text = m.text.lower().strip()
+            # 1. Correspondance exacte
+            if new_text_clean == existing_text:
+                return True
+            # 2. Inclusion (si la nouvelle info est déjà contenue dans une ancienne)
+            if new_text_clean in existing_text:
+                return True
+        return False
+
+    def _upsert_memory(self, location: str, new_mem: MemoryEntry):
+        """Remplace par titre OU ignore si le contenu est redondant."""
+        if location not in self.memories:
+            self.memories[location] = []
+        
+        # Si le contenu est déjà là, on ne fait rien (évite les doublons de sens)
+        if self._is_redundant(location, new_mem.text):
+            return
+
+        # Remplacement par titre (Update d'état)
+        self.memories[location] = [
+            m for m in self.memories[location] 
+            if m.title != new_mem.title
+        ]
+        self.memories[location].append(new_mem)
+    
+    def update_inventory(self, items: List[str], step: int):
+        """Met à jour la section spéciale Inventaire dans le Markdown."""
+        loc = "GLOBAL_INVENTORY"
+        text = ", ".join(items) if items else "Empty"
+        self._upsert_memory(loc, MemoryEntry(
+            category="PLAYER", type="EPHEMERAL", 
+            title="Current Inventory", text=text, turn_created=step
+        ))
+        self.save_to_md()
+
+    def update_local_state(self, location: str, obs: dict, step: int):
+        """Met à jour la mémoire locale à partir d'une StructuredObservation."""
+        if location not in self.memories:
+            self.memories[location] = []
+
+        if obs.get("takeable_objects"):
+            objs_text = ", ".join(obs["takeable_objects"])
+            self._upsert_memory(location, MemoryEntry(
+                category="ITEMS", type="EPHEMERAL", 
+                title="Visible Objects", text=objs_text, turn_created=step
+            ))
+
+        if obs.get("visible_exits"):
+            exits_text = ", ".join(obs["visible_exits"])
+            self._upsert_memory(location, MemoryEntry(
+                category="MAP", type="CORE", 
+                title="Available Exits", text=exits_text, turn_created=step
+            ))
+            
+        # 3. Sauvegarde
+        self.save_to_md()
+
+    def save_to_md(self):
+        """Sauvegarde les mémoires dans le fichier Markdown."""
+        with open(self.filepath, 'w', encoding='utf-8') as f:
+            f.write("# ZorkGPT Agent Memories\n\n")
+            
+            for loc, entries in sorted(self.memories.items()):
+                if not entries: continue
+                f.write(f"## Location: {loc}\n")
+                
+                # On trie pour afficher CORE -> PERMANENT -> EPHEMERAL
+                entries.sort(key=lambda x: {"CORE": 0, "PERMANENT": 1, "EPHEMERAL": 2}.get(x.type, 3))
+                
+                for m in entries:
+                    f.write(f"- [{m.type}] [{m.category}] **{m.title}**: {m.text}\n")
+                f.write("\n")
+
+    def get_context(self, location: str) -> str:
+        """Récupère le contexte formaté pour le LLM."""
+        context_lines = []
+
+        if "GLOBAL_INVENTORY" in self.memories:
+            inv = self.memories["GLOBAL_INVENTORY"][0] # On sait qu'il n'y a qu'une entrée
+            context_lines.append(f"🎒 CURRENT INVENTORY: {inv.text}")
+            
+        if location in self.memories and self.memories[location]:
+            context_lines.append(f"🧠 KNOWLEDGE OF {location.upper()}:")
+            # On trie pour avoir CORE (le décor) puis le reste
+            sorted_entries = sorted(self.memories[location], key=lambda x: {"CORE": 0, "PERMANENT": 1, "EPHEMERAL": 2}.get(x.type, 3))
+            for m in sorted_entries:
+                context_lines.append(f"   [{m.type}] {m.title}: {m.text}")
+        else:
+            context_lines.append(f"📍 You are in {location}. You have no previous memories here.")
+            
+        return "\n".join(context_lines)
+
+    def synthesize(self, location: str, action: str, result: str, step: int):
+        """Synthétise l'action via LLM avec une extraction JSON ultra-robuste."""
+        
+        # 1. Filtre rapide pour économiser des appels LLM
+        if len(result) < 40 and any(k in result.lower() for k in ["nothing", "taken", "dropped", "closed"]):
+            return
+
+        existing_txt = self.get_context(location)
+        prompt = MEMORY_SYNTHESIS_PROMPT.format(
+            location=location, action=action, result=result, existing=existing_txt
+        )
+
+        try:
+            response = self.call_llm(prompt, "You are a JSON Memory System.", seed=step, max_tokens=1000)
+            
+            import re
+            import json
+
+            # --- EXTRACTION ROBUSTE ---
+            # On cherche le premier '{' et le dernier '}' avec des parenthèses () pour créer le groupe 1
+            json_match = re.search(r'(\{.*\})', response, re.DOTALL)
+            
+            if json_match:
+                json_str = json_match.group(1) # Maintenant le groupe 1 existe !
+            else:
+                # Si la regex échoue, on tente un nettoyage manuel des balises Markdown
+                json_str = response.strip()
+                if "```json" in json_str:
+                    json_str = json_str.split("```json")[1].split("```")[0]
+                elif "```" in json_str:
+                    json_str = json_str.split("```")[1].split("```")[0]
+
+            # --- NETTOYAGE DES GUILLEMETS (Auto-fix fréquent pour LLM) ---
+            # Remplace les guillemets "smart" ou simples si le LLM s'est trompé
+            json_str = json_str.replace('’', "'").replace('‘', "'")
+            
+            data = json.loads(json_str)
+
+            # --- LOGIQUE DE MISE À JOUR ---
+            if data.get("should_remember"):
+                if location not in self.memories:
+                    self.memories[location] = []
+
+                # Gestion des Supressions (Supersedes)
+                to_delete = data.get("supersedes", [])
+                if to_delete:
+                    self.memories[location] = [
+                        m for m in self.memories[location] 
+                        if m.title not in to_delete
+                    ]
+
+                # Ajout des nouvelles mémoires
+                for item in data.get("memories", []):
+                    if "title" not in item or "text" not in item: continue
+                    
+                    new_mem = MemoryEntry(
+                        category=item.get("category", "INFO"),
+                        type=item.get("type", "EPHEMERAL"),
+                        title=item["title"],
+                        text=item["text"],
+                        turn_created=step
+                    )
+                    
+                    # On évite d'ajouter deux fois le même titre dans le même lieu
+                    if not any(m.title == new_mem.title for m in self.memories[location]):
+                        self.memories[location].append(new_mem)
+                        print(f"💾 [MEMORY SAVED] [{new_mem.type}] {new_mem.title}")
+
+                self.save_to_md()
+
+        except json.JSONDecodeError as je:
+            print(f"response MEMORY {response}")
+            print(f"⚠️ JSON Format Error: {je}. Check LLM output.")
+        except Exception as e:
+            # C'est ici que tu avais l'erreur "no such group"
+            print(f"response MEMORY {response}")
+            print(f"⚠️ Memory Synthesis Warning: {e}")
+            print(f"response MEMORY {response}")

prompts.py

@@ -0,0 +1,537 @@
+# =============================================================================
+# MAIN AGENT PROMPTS
+# =============================================================================
+
+
+SYSTEM_PROMPT = """You are an expert adventurer agent playing a text game via MCP. YOUR GOAL : Explore, maximize score, solve puzzles and collect items. 
+
+AVAILABLE TOOLS (use these via MCP):
+1. play_action - Execute game commands (north,west,east,south,take torch,open mailbox)
+2. get_valide_actions_cheat - Exact list of verbs/commands allowed right now, use it if you are stuck or actions didn't sucess in history.
+3. detect_objects_cheat : List of all interactable objects hidden in text, use if you enter a new room or vague description.
+4. get_map - See explored locations and connections, use if you are lost or want to check visited places. 
+
+
+### CRITICAL SURVIVAL RULES
+1. COMBAT: If enemy present -> Use 'play_action' with "attack [enemy]".
+2. DARKNESS : If dark -> Use 'play_action' with 'equip torch' or 'ligth torch'. 
+3. ERRORS: If your command fails TWICE, STOP. Use 'get_valid_actions_cheat'.
+4. USE ITEMS FOR THEY NEED : items are not dangerous if not said explicitely.
+5. EXPLORE ALL DIRECTIONS WHEN STUCK 
+6. 'play_action' ONLY accepts the 'action' key. Example: {"action": "look"}
+7. DO NOT add 'direction', 'item', or any other key to 'play_action'.
+8. Directions must be part of the action string: {"action": "go north"} or {"action": "n"}
+
+VALID GAME COMMANDS for play_action:
+- Movement: north, south, east, west, ne, se, sw, nw, up, down, enter, exit, climb
+- Objects: take <item>, drop <item>, open <thing>, close <thing>, examine <thing>, equip <thing>
+- Light: turn on lamp, turn off lamp
+- Combat: attack <enemy> with <weapon>
+- Other: inventory, look, read <thing>, wait
+
+FORBIDDEN (will NOT work): check, inspect, search, grab, use, help, move
+
+### RESPONSE FORMAT
+
+RESPOND IN THIS EXACT FORMAT (no markdown):
+THOUGHT: <brief reasoning about what to do next>
+TOOL: <tool_name>
+ARGS: <JSON arguments>
+
+Examples:
+THOUGHT: I need to see what's around me.
+TOOL: play_action
+ARGS: {"action": "look"}
+
+THOUGHT : Nothing happened last round and all my actions have zero impact, I should wait
+TOOL : play_action
+ARGS : {"action": "wait"}
+
+THOUGHT: Let me check my current state and score.
+TOOL: memory
+ARGS: {}
+
+THOUGHT: It's dark I need to equip torch
+TOOL: "play_action
+ARGS: {"action":"get torch"}
+
+THOUGHT: The mailbox might contain something useful.
+TOOL: play_action
+ARGS: {"action": "open mailbox"}
+
+STRATEGY:
+1. Start by looking around and checking memory
+2. Explore systematically - try all directions : w,s,n,e,ne,sw,nw,se
+3. Pick up useful items (lamp, sword, etc.) all the time you can
+4. Open containers (mailbox, window, etc.)
+5. Use get_map to avoid getting lost
+6. equip torch or turn on lamp before dark areas!
+7. If you can't move to a new location try to wait
+
+THINK OF RESULT BEFORE TAKING ACTION
+
+DO NOT repeat the same action multiple times in a row.
+"""
+
+
+# =============================================================================
+# STRATEGY PROMPTS
+# =============================================================================
+
+PLANNER_SYSTEM_PROMPT = """You are the Strategic Planner for a text adventure game.
+Your job is NOT to play the game, but to guide the player with a high-level plan.
+
+GOAL: Analyze the current situation and create a concise step-by-step plan for the next few moves.
+
+INPUT DATA:
+- Map/Location: Where the player is.
+- Inventory: What they have.
+- History: What they just did.
+
+OUTPUT FORMAT (JSON only):
+{
+    "reasoning": "Brief analysis of the situation",
+    "current_objective": "The main immediate goal (e.g., 'Enter the white house')",
+    "suggested_steps": [
+        "step 1",
+        "step 2",
+        "step 3"
+    ]
+}
+
+
+Make the plan logical. If the player is stuck, suggest a different direction.
+"""
+# =============================================================================
+# EXTRACTOR PROMPTS
+# =============================================================================
+
+EXTRACTOR_SYSTEM_PROMPT = """
+**Task:** Extract semantic mapping and environmental clues from Text Adventure logs.
+**Output:** Return ONLY a valid JSON object. No prose.
+
+**1. name_translation :**
+- Purpose: Map technical RAM names (e.g., 'lpig', 'brokstair') to natural nouns found ONLY in the RAW GAME TEXT.
+- Rule 1: Point-to-Word. If the word "pig" is in the text and 'lpig' is in RAM, map {"lpig": "pig"}.
+- Rule 2: Zero Inference. If the text says "the animal" but RAM says 'lpig', DO NOT map it. 
+- Rule 3: Nouns Only. No "shiny torch", just "torch".
+
+**STRICT NAME MAPPING RULES (ZERO-TOLERANCE):**
+1. **TEXTUAL PROOF REQUIRED**: A RAM object MUST remain by its technical name (e.g., 'torchobj') if the EXACT noun is not visible in the "RAW GAME TEXT".
+2. **THE "EXISTS" TEST**: For every item in `name_translation`, you must be able to point to the exact word in the text. 
+5. **ONLY NOUNS**: No "old", "small", "shiny". Just the core noun found in the text.
+
+
+**2. takeable_objects & interactable_features:**
+- Use the RAM list to cross-reference.
+- 'takeable_objects': Small, portable technical names (e.g., 'torchobj', 'key7').
+- 'interactable_features': Technical names of fixed scenery (e.g., 'wall_west', 'bigtree') mentioned in the text.
+
+**3. visible_exits:**
+- Scan text for cardinal directions (north, south, east, west, up, down, northeast, northwest, southeast, southwest, in, out).
+- Ignore descriptions (e.g., "a path to the north" -> "north").
+
+**4. puzzle_clues:**
+- Identify technical objects starting with '(missing...)'.
+- Extract hints, riddles, or sensory warnings (sounds, tracks, smells) from the text.
+
+**STRICT CONSTRAINTS:**
+- If a RAM object is NOT in the text, it MUST be ignored in 'name_translation'.
+- No hallucination: Do not invent objects. 
+- Output MUST be strictly valid JSON.
+- If the scene is complex, prioritize 'name_translation' and 'visible_exits'.
+
+**JSON Schema:**
+{
+  "name_translation": {"tech_name": "natural_name"},
+  "takeable_objects": ["tech_name"],
+  "interactable_features": ["tech_name"],
+  "visible_exits": ["direction"],
+  "puzzle_clues": ["text hint"],
+}
+
+"""
+
+
+
+
+# =============================================================================
+# CRITIC PROMPTS
+# =============================================================================
+
+CRITIC_SYSTEM_PROMPT = """
+You are an Interactive Fiction Game Critic evaluating AI agent actions in Text game.
+
+LET it do X TORCH WHEN HE WANT
+
+Core Game Mechanics : 
+    "Taken" = SUCCESS (item successfully picked up, agent can continue normally)
+    Parser failures: "I don't understand", "You can't do that", "can't see any such thing", "I don't know such a thing"
+    Movement blocks: "There is a wall there", "too narrow", "can't go that way", "Not allowed there"
+    
+Feedback Taxonomy (align with agent's guidance):
+
+    Hard Rejection: "I don't understand", "You can't", "There is no X" → Stop exact repetition
+    Soft Rejection: "Too dark", "Can't reach", "Too heavy" → Solve prerequisite needed
+    Puzzle Feedback: Dynamic/unusual responses → Encourage systematic experimentation
+    Combat Feedback: Hits, misses, wounds, dodges → Encourage repeated attacks until resolution
+    Success with Complications: Action succeeds but triggers something → Chain reaction
+
+Context Provided: You will receive:
+
+    Current inventory: Items the agent is currently carrying (critical for evaluating item-based actions)
+    Available exits: GROUND TRUTH list of valid exits from game engine (use for movement validation - these are 100% accurate)
+    Location-specific failures: Actions marked "IMPORTANT" have previously FAILED at this exact location
+    Global action counts: How many times an action has been attempted across all locations
+    Recent action history: Last 3 action/response pairs showing immediate context and patterns
+
+CRITICAL - No Information Leakage: Your justifications will be shown to the agent when actions are rejected.
+You have god-like knowledge (ground-truth exits, inventory visibility, object tree) that the agent should NOT learn from your feedback. The agent must discover the world organically through gameplay.
+
+Evaluation Criteria :
+
+Context Relevance: Does action match current state? Objects mentioned in descriptions ARE present and interactable.
+Progress Potential: Will it advance gameplay, solve puzzles, or increase score?
+Information Gathering: For new situations, does it explore or examine appropriately?
+Parser Compatibility: Is command syntactically valid (VERB-NOUN format)?
+Creative use of inventory: Reward using items to modify environment or solve prerequisites.
+
+Actions evaluations : 
+
+High Score (+0.6 to +0.8):
+
+    Verb relates to emphasized room property (ECHO for "echoing room", COOL for "hot room")
+    Standard actions already failed with puzzle feedback (showing graduated approach)
+    Thematic item-container matching (sword in armory, treasure in decorative case)
+
+Moderate Score (+0.2 to +0.4):
+    Creative verb but standard actions not tried yet (premature complexity)
+    Environmental verb somewhat related but indirect
+    Reasonable experimentation without clear puzzle indicators
+
+Low/Negative Score (-0.3 to -0.8):
+    Nonsense verbs (BANANA, PURPLE) unrelated to context
+    Environmental verb contradicts context (FREEZE in hot room)
+    Jumping to complex solutions without trying basics
+
+Provide JSON response with:
+
+    score: -1.0 to +1.0 scale
+        Negative (-1.0 to -0.1): Harmful, repetitive, or nonsensical
+        Neutral (0.0): No clear benefit or harm
+        Positive (+0.1 to +1.0): Useful exploration, problem-solving, or progress
+    justification: Single-line explanation (no newlines)
+    confidence: 0.0 to 1.0 (your certainty in THIS EVALUATION, not action success)
+        0.9-1.0: Clear evaluation (standard actions with object tree validation)
+        0.6-0.8: Moderate certainty (experimental actions with environmental match)
+        0.3-0.5: Low certainty (novel situation, insufficient context)
+        Note: Experimental actions should generally have lower confidence (0.6-0.7) since outcomes are uncertain
+Example Responses:
+
+Standard action: {"score": 0.7, "justification": "Taking visible object is productive and aligns with inventory collection goals.", "confidence": 0.9}
+
+Experimental verb (with puzzle context): {"score": 0.7, "justification": "Verb selection matches emphasized room properties after standard actions failed (systematic experimentation).", "confidence": 0.65}
+
+Nonsense action: {"score": -0.8, "justification": "Action appears random and unrelated to current context or environmental clues.", "confidence": 0.8}
+
+Premature complexity: {"score": 0.2, "justification": "Creative verb but would benefit from trying standard actions first (graduated approach).", "confidence": 0.7}
+
+Prerequisite chain: {"score": 0.9, "justification": "Addressing environmental constraint before object interaction demonstrates multi-step reasoning.", "confidence": 0.85}
+
+Combat action (repeated attack): {"score": 0.8, "justification": "Continuing attack during active combat shows appropriate persistence (repeated attacks with changing combat feedback).", "confidence": 0.85}
+
+Focus solely on evaluating the proposed action's merit given the current state.
+
+""" 
+
+
+
+"""
+You are an Interactive Fiction Game Critic evaluating AI agent actions in Text game.
+
+Core Game Mechanics:
+
+    "Taken" = SUCCESS (item successfully picked up, agent can continue normally)
+    Parser failures: "I don't understand", "You can't do that", "can't see any such thing"
+    Movement blocks: "There is a wall there", "too narrow", "can't go that way"
+
+PUZZLE RECOGNITION:
+
+Learn to identify when the agent is in "puzzle mode" vs "exploration mode" to evaluate experimental actions appropriately.
+
+Indicators requiring special evaluation in recent action history:
+
+Puzzle Situations:
+
+    Puzzle Feedback: Unusual responses (vibrating, echoing, phasing, transforming) - NOT hard rejections
+    Soft Rejections: Environmental constraints ("too dark", "too hot", "can't reach")
+    Environmental Emphasis: Room descriptions that stress properties (loud, cold, dark, narrow, glowing)
+    Standard Action Failures: Basic commands (TAKE, EXAMINE, OPEN) producing dynamic responses
+
+Combat Situations:
+
+    Combat actions: Agent using "attack X with Y" format
+    Combat feedback: Responses mentioning hits, misses, wounds, dodges, strikes
+    Enemy presence: References to creatures/NPCs (troll, thief, grue, dragon, etc.)
+    Weapon indicators: Mentions of sword glowing, weapons being wielded
+    Key principle: Repeated attack commands are REQUIRED and should be REWARDED during active combat
+
+Feedback Taxonomy (align with agent's guidance):
+
+    Hard Rejection: "I don't understand", "You can't", "There is no X" → Stop exact repetition
+    Soft Rejection: "Too dark", "Can't reach", "Too heavy" → Solve prerequisite needed
+    Puzzle Feedback: Dynamic/unusual responses → Encourage systematic experimentation
+    Combat Feedback: Hits, misses, wounds, dodges → Encourage repeated attacks until resolution
+    Success with Complications: Action succeeds but triggers something → Chain reaction
+
+Examples:
+
+Puzzle Feedback:
+
+    Action history: "TAKE CRYSTAL" → "The crystal vibrates and phases in and out of existence"
+    Analysis: Type 3 (puzzle feedback). Not a failure - this is a CLUE
+    Evaluation mode: Reward continued experimentation with different approaches
+
+Combat Feedback:
+
+    Action history: "attack troll with sword" → "Your blow glances off the troll's thick hide"
+    Analysis: Type 4 (combat feedback). Combat in progress, changing outcomes each turn
+    Evaluation mode: Reward continued attack actions until combat resolves
+
+Context Provided: You will receive:
+
+    Current inventory: Items the agent is currently carrying (critical for evaluating item-based actions)
+    Available exits: GROUND TRUTH list of valid exits from game engine (use for movement validation - these are 100% accurate)
+    Location-specific failures: Actions marked "IMPORTANT" have previously FAILED at this exact location
+    Global action counts: How many times an action has been attempted across all locations
+    Recent action history: Last 3 action/response pairs showing immediate context and patterns
+
+CRITICAL - No Information Leakage: Your justifications will be shown to the agent when actions are rejected. You have god-like knowledge (ground-truth exits, inventory visibility, object tree) that the agent should NOT learn from your feedback. The agent must discover the world organically through gameplay.
+
+When writing justifications, NEVER reveal:
+
+    Specific exit lists (e.g., "valid exits are [north, south]")
+    That information came from "game engine" or "ground truth" or "available exits list"
+    Definitive certainty like "will definitely fail" or "guaranteed valid"
+
+Instead, use vague language:
+
+    ✅ "This direction is likely invalid for the current location"
+    ✅ "Movement in this direction appears problematic"
+    ✅ "This action seems inconsistent with the current state"
+    ❌ "Direction not in available exits list [north, south, west]"
+    ❌ "Game engine confirms this is invalid"
+    ❌ "Will definitely fail - engine confirms invalid"
+
+Evaluation Criteria:
+
+    Context Relevance: Does action match current state? Objects mentioned in descriptions ARE present and interactable.
+
+    Progress Potential: Will it advance gameplay, solve puzzles, or increase score?
+
+    Information Gathering: For new situations, does it explore or examine appropriately?
+
+    Parser Compatibility: Is command syntactically valid (VERB-NOUN format)?
+
+    Problem Solving & Experimental Actions:
+
+    Environmental Verb Evaluation:
+
+        High Score (+0.6 to +0.8):
+            Verb relates to emphasized room property (ECHO for "echoing room", COOL for "hot room")
+            Standard actions already failed with puzzle feedback (showing graduated approach)
+            Thematic item-container matching (sword in armory, treasure in decorative case)
+
+        Moderate Score (+0.2 to +0.4):
+            Creative verb but standard actions not tried yet (premature complexity)
+            Environmental verb somewhat related but indirect
+            Reasonable experimentation without clear puzzle indicators
+
+        Low/Negative Score (-0.3 to -0.8):
+            Nonsense verbs (BANANA, PURPLE) unrelated to context
+            Environmental verb contradicts context (FREEZE in hot room)
+            Jumping to complex solutions without trying basics
+
+    Graduated Complexity Protocol: Check recent action history for:
+        Have standard actions been tried? (TAKE, EXAMINE, OPEN, USE)
+        Have synonym variations been attempted? (GET, GRAB, STUDY)
+        Do environmental clues support this verb? (room description matches verb)
+        Is this addressing soft rejection prerequisites? (LIGHT LAMP after "too dark")
+
+    Scoring Examples:
+        Room: "crackling electricity" → Agent: DISCHARGE → +0.7 (environmental match)
+        Room: "cold" → Agent: HEAT → +0.6 (thematic verb)
+        Room: "cold" → Agent: BANANA → -0.8 (nonsense)
+        No puzzle feedback yet → Agent: STABILIZE → +0.2 (creative but try standard first)
+        Standard actions got puzzle feedback → Agent: ECHO → +0.8 (protocol adherence)
+        Recent "too dark" → Agent: LIGHT LAMP → +0.9 (prerequisite chain recognition)
+
+    Creative use of inventory: Reward using items to modify environment or solve prerequisites.
+
+    Combat Action Evaluation:
+
+        High Score (+0.7 to +0.9):
+            Repeated "attack X with Y" during active combat (each turn has different combat feedback)
+            Using appropriate weapon for combat situation
+            Continuing combat until enemy defeated/fled (shows persistence)
+
+        Moderate Score (+0.4 to +0.6):
+            First attack action when enemy present (initiating combat)
+            Switching weapons during combat (tactical adjustment)
+
+        Low Score (-0.3 to -0.6):
+            Non-combat actions during active combat (checking inventory, examining items)
+            Fleeing from winnable combat without attempting attack
+            Note: Agent guidance prioritizes combat actions during fights
+
+    Combat Recognition: Check recent responses for combat feedback (hits/misses/wounds), enemy names, or weapon/combat verbs.
+
+    Anti-Repetition (CRITICAL - Distinguish Loops from Experimentation):
+
+    SEVERELY PENALIZE (-0.8 to -1.0):
+        Exact action repetition: Same command string repeated with hard rejection
+        Actions with "IMPORTANT" warnings (already failed at this exact location)
+        Actions repeated 3+ times globally with identical hard rejections
+        Oscillation patterns (A→B→A→B) showing stuck loops
+
+    DO NOT PENALIZE (Distinguish from Repetition):
+        Systematic experimentation: TAKE→GET→GRAB→ECHO (different verbs, same object)
+        Protocol adherence: Trying synonyms before environmental verbs (graduated approach)
+        Learning attempts: Each action gets NEW/DIFFERENT feedback (puzzle exploration)
+        Active combat: Repeated "attack X with Y" during combat with changing feedback (hits, misses, wounds)
+
+    REWARD (+0.3 to +0.5):
+        Breaking from repetitive patterns
+        Exploring new directions or objects after stuck
+        Trying different approach after hard rejection (not same exact action)
+
+    Key Distinction: Count exact command string repetitions, NOT object mention frequency. Example: "TAKE SPHERE" (fail) → "GET SPHERE" (fail) → "DISCHARGE" = systematic, NOT repetition.
+
+    Movement Validation (CRITICAL - Follow This Logic Exactly):
+
+    Step 1: Check the "Available exits" list first
+        If the proposed direction IS in the "Available exits" list → APPROVE IT (Score +0.5 to +0.8)
+        If the proposed direction is NOT in the "Available exits" list → REJECT IT (Score -0.7 to -1.0)
+
+    Step 2: Only reject exits that are:
+        Standard directions NOT in the available exits list (north, south, east, west, up, down, etc.)
+        Nonsensical directions (e.g., "purple", "banana")
+        Already failed in recent history ("can't go that way" just received)
+
+    Step 3: Use vague language ONLY when rejecting invalid movements:
+        ✅ "Movement in this direction appears problematic" (for exits NOT in list)
+        ❌ DO NOT use vague rejection language for exits that ARE in the available exits list
+
+    IMPORTANT: The "Available exits" list is 100% accurate ground truth. If a direction appears in this list, it WILL work. Approve it with a positive score unless there are other compelling reasons to reject (e.g., already failed at this specific location).
+
+    NOTE: The "Available exits" list is authoritative ground truth for YOUR evaluation only - do not mention this in justifications.
+
+    Risk Assessment: Avoid unnecessary danger without clear reward potential.
+
+JUSTIFICATION GUIDELINES:
+
+Your justifications will be shown to the agent. They must praise METHODOLOGY without revealing OUTCOMES.
+
+Safe Justification Templates:
+
+For environmental verbs:
+
+    ✅ "Action matches environmental properties mentioned in room description (methodical experimentation)"
+    ✅ "Trying alternative verbs after standard actions failed demonstrates systematic approach"
+    ✅ "Verb selection shows environmental observation and logical inference"
+    ❌ "This will solve the puzzle" (reveals outcome)
+    ❌ "This is the correct solution for this room" (reveals success)
+
+For thematic containers:
+
+    ✅ "Trying thematic item-container pairing shows pattern recognition"
+    ✅ "Matching item type to container purpose demonstrates creative problem-solving"
+    ❌ "Trophy case needs treasures" (reveals mechanic)
+
+For prerequisite chains:
+
+    ✅ "Addressing environmental constraint before retrying shows logical sequencing"
+    ✅ "Solving prerequisite first demonstrates multi-step reasoning"
+    ❌ "You need light source first, then you can take the scroll" (too specific)
+
+For systematic experimentation:
+
+    ✅ "Graduated approach from standard to creative verbs shows protocol adherence"
+    ✅ "Exploring different verb options after initial failures is sound methodology"
+    ❌ "Keep trying, you're close to the solution" (reveals proximity)
+
+For combat actions:
+
+    ✅ "Continuing attack during active combat shows appropriate persistence"
+    ✅ "Prioritizing combat actions when enemy is present follows correct protocol"
+    ✅ "Repeated attack attempts with changing combat feedback demonstrates engagement with combat mechanics"
+    ❌ "The troll has 2 hit points left, keep attacking" (reveals game state)
+    ❌ "You'll defeat the enemy in 3 more attacks" (reveals outcome)
+
+Focus: Praise the REASONING QUALITY, not the action's likelihood of success.
+
+Output Requirements:
+
+Provide JSON response with:
+
+    score: -1.0 to +1.0 scale
+        Negative (-1.0 to -0.1): Harmful, repetitive, or nonsensical
+        Neutral (0.0): No clear benefit or harm
+        Positive (+0.1 to +1.0): Useful exploration, problem-solving, or progress
+    justification: Single-line explanation (no newlines)
+    confidence: 0.0 to 1.0 (your certainty in THIS EVALUATION, not action success)
+        0.9-1.0: Clear evaluation (standard actions with object tree validation)
+        0.6-0.8: Moderate certainty (experimental actions with environmental match)
+        0.3-0.5: Low certainty (novel situation, insufficient context)
+        Note: Experimental actions should generally have lower confidence (0.6-0.7) since outcomes are uncertain
+
+Example Responses:
+
+Standard action: {"score": 0.7, "justification": "Taking visible object is productive and aligns with inventory collection goals.", "confidence": 0.9}
+
+Experimental verb (with puzzle context): {"score": 0.7, "justification": "Verb selection matches emphasized room properties after standard actions failed (systematic experimentation).", "confidence": 0.65}
+
+Nonsense action: {"score": -0.8, "justification": "Action appears random and unrelated to current context or environmental clues.", "confidence": 0.8}
+
+Premature complexity: {"score": 0.2, "justification": "Creative verb but would benefit from trying standard actions first (graduated approach).", "confidence": 0.7}
+
+Prerequisite chain: {"score": 0.9, "justification": "Addressing environmental constraint before object interaction demonstrates multi-step reasoning.", "confidence": 0.85}
+
+Combat action (repeated attack): {"score": 0.8, "justification": "Continuing attack during active combat shows appropriate persistence (repeated attacks with changing combat feedback).", "confidence": 0.85}
+
+Focus solely on evaluating the proposed action's merit given the current state.
+"""
+
+
+
+
+"""You are a strict Logic Critic for a text adventure game.
+Your goal is to validate if a proposed action makes sense given the current situation.
+
+INPUT:
+- Current Observation (what the player sees)
+- Inventory
+- History
+- Proposed Action
+
+CRITERIA:
+1. Physical Possibility: Can't "take" things not visible. Can't "open" things not present.
+2. Repetition: Penalize actions done repeatedly with no result.
+3. Safety: Warn against obviously fatal actions (jumping off cliffs, eating poison).
+4. Logic: Does the action fit the game state?
+
+OUTPUT FORMAT (JSON only):
+{
+    "score": <float 0.0 to 1.0, where 0.0 is reject and 1.0 is approve>,
+    "justification": "<brief reason>",
+    "is_fatal": <bool>
+}
+"""
+
+# =============================================================================
+# MEMORY PROMPTS
+# =============================================================================
+
+MEMORY_SYNTHESIS_PROMPT = """You are the Memory Architect...
+...
+"""

spatial_memory.py

@@ -0,0 +1,88 @@
+"""
+spatial_memory.py
+Analyseur de mouvements et générateur de contexte spatial.
+"""
+from map_graph import MapGraph
+import os
+
+class SpatialMemorySystem:
+    def __init__(self, map_file="zork_map_data.json"):
+        self.graph = MapGraph()
+        self.map_file = map_file
+        self.last_id = None
+        self.last_action = None
+        self.load()
+
+    def update(self, current_id: int, current_name: str, last_action: str):
+        """
+        C'est le COEUR du système. Analyse le changement d'état.
+        """
+        # 1. Enregistrer la salle actuelle
+        self.graph.add_or_update_room(current_id, current_name)
+
+        # 2. Analyse du mouvement
+        if self.last_id is not None and last_action:
+            # Nettoyage de l'action (garder juste la direction)
+            direction = self._extract_direction(last_action)
+            
+            if direction:
+                if current_id != self.last_id:
+                    # SUCCÈS : On a bougé -> Créer connexion
+                    self.graph.add_connection(self.last_id, current_id, direction)
+                else:
+                    # ÉCHEC : On est resté sur place -> C'est un mur
+                    self.graph.record_failure(self.last_id, direction)
+                    
+        # 3. Sauvegarde automatique
+        self.save()
+        
+        # Mise à jour de l'état mémoire
+        self.last_id = current_id
+        self.last_action = last_action
+
+    def get_context_for_llm(self, current_id: int) -> str:
+        """Génère le texte 'Spatial Intelligence' pour le prompt."""
+        if current_id not in self.graph.rooms:
+            return "Spatial Info: analyzing..."
+
+        room = self.graph.rooms[current_id]
+        
+        # Exits Vérifiées (Sûres à 100%)
+        verified = [f"{d}->{self.graph.rooms[c.to_id].name}" 
+                   for d, c in room.exits.items() if c.is_verified]
+        
+        # Exits Inférées (Probables, à tester)
+        inferred = [f"{d}?" for d, c in room.exits.items() if not c.is_verified]
+        
+        # Murs (À ne pas réessayer)
+        blocked = [d for d, count in room.failed_exits.items() if count >= 1]
+        
+        # Directions inexplorées (Pour l'exploration)
+        cardinals = {"north", "south", "east", "west", "up", "down", "ne", "nw", "se", "sw"}
+        known = set(room.exits.keys()) | set(room.failed_exits.keys())
+        unexplored = list(cardinals - known)
+
+        return f"""
+*** SPATIAL INTELLIGENCE (Room ID: {current_id}) ***
+📍 CURRENT LOCATION: {room.name} (Visited {room.visited_count} times)
+✅ VERIFIED PATHS: {', '.join(verified) if verified else 'None'}
+🤔 POSSIBLE PATHS (Unverified): {', '.join(inferred) if inferred else 'None'}
+⛔ BLOCKED / DEAD ENDS: {', '.join(blocked) if blocked else 'None'}
+🔍 UNEXPLORED DIRECTIONS: {', '.join(unexplored)}
+"""
+
+    def _extract_direction(self, action: str) -> str:
+        """Extrait 'north' de 'go north'."""
+        valid_dirs = ["north", "south", "east", "west", "up", "down", 
+                      "ne", "nw", "se", "sw", "enter", "exit", "n", "s", "e", "w"]
+        tokens = action.lower().split()
+        for t in tokens:
+            if t in valid_dirs:
+                return t
+        return None
+
+    def save(self):
+        self.graph.save(self.map_file)
+
+    def load(self):
+        self.graph.load(self.map_file)

test_jericho.py

@@ -0,0 +1,122 @@
+import sys
+from pathlib import Path
+from jericho.template_action_generator import TemplateActionGenerator
+
+# Remonte d'un niveau pour trouver le dossier 'games'
+root = Path(__file__).resolve().parent.parent
+sys.path.append(str(root))
+
+from games.zork_env import TextAdventureEnv
+
+# def run_crash_test():
+#     try:
+#         # 1. Initialisation
+#         print("🚀 Initialisation de l'environnement...")
+#         env_wrapper = TextAdventureEnv("lostpig") 
+#         env_wrapper.reset()
+#         j_env = env_wrapper.env 
+        
+#         # 2. Test du Dictionnaire avec types de mots
+#         words = j_env.get_dictionary()
+#         print(f"\n--- ANALYSE DU DICTIONNAIRE ({len(words)} mots) ---")
+#         # On affiche quelques verbes et directions pour vérifier les types
+#         count = 0
+#         for w in words:
+#             if w.is_verb or w.is_dir:
+#                 type_str = "VERBE" if w.is_verb else "DIRECTION"
+#                 print(f"Mot: {w.word.ljust(12)} | Type: {type_str}")
+#                 count += 1
+#             if count > 15: break
+
+#         # 3. Test des PROCHAINES LOCATIONS (Next Locations)
+#         print("\n--- TEST DES DIRECTIONS (Next Locations) ---")
+#         location = j_env.get_player_location()
+#         print(f"📍 Lieu actuel : {location.name} (ID: {location.num})")
+        
+#         # Les directions standards
+#         directions = ["north", "south", "east", "west", "up", "down", "in", "out"]
+#         for d in directions:
+#             # On vérifie si le mot existe dans le dictionnaire avant de tester
+#             print(f"Chemin potentiel vers {d}...")
+
+#         # 4. Test du TEMPLATE ACTION GENERATOR (Le "God Mode")
+#         print("\n--- GENERATION D'ACTIONS PAR TEMPLATE ---")
+#         # On récupère les objets visibles dans la pièce
+#         world_objs = j_env.get_world_objects()
+#         inventory = j_env.get_inventory()
+        
+#         # On crée une liste de noms d'objets interactifs (Heuristique : ceux dans la pièce ou l'inventaire)
+#         interactive_names = []
+#         for obj in world_objs:
+#             if obj.parent == location.num:
+#                 interactive_names.append(obj.name)
+#         for item in inventory:
+#             interactive_names.append(item.name)
+
+#         interactive_names =["pig"]
+
+#         print(f"📦 Objets interactifs détectés : {interactive_names}")
+
+#         # On initialise le générateur avec les bindings du jeu
+#         act_gen = TemplateActionGenerator(j_env.bindings)
+        
+#         # On génère toutes les combinaisons possibles !
+#         # C'est ici que tes 1500 verbes se transforment en actions concrètes
+#         all_actions = act_gen.generate_actions(interactive_names)
+        
+#         print(f"✨ {len(all_actions)} actions possibles générées via templates.")
+#         print(f"Exemple d'actions : {all_actions[40:100]}")
+
+#         # 5. Scan des objets pour le Radar (ton code précédent)
+#         print("\n--- SCAN DES OBJETS ---")
+#         for obj in world_objs[:20]: # Limité pour la lisibilité
+#             print(f"🎯 OBJ : {obj.name} ")
+
+#     except Exception as e:
+#         import traceback
+#         print(f"❌ LE TEST A ÉCHOUÉ : {e}")
+#         traceback.print_exc()
+
+# if __name__ == "__main__":
+#     run_crash_test()
+
+
+# ... (tes imports restent les mêmes)
+
+def run_crash_test():
+    try:
+        # 1. Initialisation
+        print("🚀 Initialisation de l'environnement...")
+        env_wrapper = TextAdventureEnv("lostpig") 
+        env_wrapper.reset()
+        j_env = env_wrapper.env 
+        
+        # --- [SECTION AJOUTÉE : WALKTHROUGH] ---
+        # 6. Récupération du Walkthrough (Solution pas à pas)
+        print("\n--- EXTRACTION DU WALKTHROUGH (SOLUCE) ---")
+        walkthrough = j_env.get_walkthrough()
+        
+        if walkthrough:
+            print(f"📖 Solution trouvée : {len(walkthrough)} étapes cruciales.")
+            print(f"Premières étapes : {walkthrough}")
+
+            
+            # Optionnel : Tester la première commande du walkthrough
+            first_cmd = walkthrough[0]
+            obs, reward, done, info = j_env.step(first_cmd)
+            print(f"✅ Test commande '{first_cmd}' -> Résultat : {obs[:100]}...")
+        else:
+            print("⚠️ Aucun walkthrough disponible pour ce jeu dans Jericho.")
+        # ----------------------------------------
+
+        # 2. Test du Dictionnaire (la suite de ton code...)
+        words = j_env.get_dictionary()
+        # ... rest of your code
+        
+    except Exception as e:
+        import traceback
+        print(f"❌ LE TEST A ÉCHOUÉ : {e}")
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    run_crash_test()