init

app.py

@@ -0,0 +1,150 @@
+import gradio as gr
+from gradio import ChatMessage
+import re
+import sys
+import time
+import json
+import os
+import jsonpickle
+import configparser
+
+import example_worlds
+from models import GeminiModel
+from prompts import prompt_narrate_current_scene, prompt_world_update, prompt_describe_objective
+
+PATH_GAMELOGS = 'logs'
+
+# config
+config = configparser.ConfigParser()
+config.read('config.ini')
+
+# language of the game
+language = config['Options']['Language']
+
+# Initialize the model and disable the safety settings
+reasoning_model_name = config['Models']['ReasoningModel']
+narrative_model_name = config['Models']['NarrativeModel']
+reasoning_model = GeminiModel("API_key", reasoning_model_name)
+narrative_model = GeminiModel("API_key", narrative_model_name)
+
+# Create a name for the log file
+timestamp = time.time()
+today =  time.gmtime(timestamp)
+log_filename =  f"{today[0]}_{today[1]}_{today[2]}_{str(int(time.time()))[-5:]}.json"
+
+# The game loop
+def game_loop(message, history):
+    global last_player_position
+    global number_of_turns
+    global game_log_dictionary
+
+    number_of_turns+=1
+    game_log_dictionary[number_of_turns] = {}
+    game_log_dictionary[number_of_turns]["date"] = time.ctime(time.time())
+    game_log_dictionary[number_of_turns]["previous_symbolic_world_state"] = jsonpickle.encode(world, unpicklable=False)
+    game_log_dictionary[number_of_turns]["previous_rendered_world_state"] = world.render_world()
+    game_log_dictionary[number_of_turns]["user_input"] = message
+
+
+    answer = ""
+
+    # Get the changes in the world
+    prompt_update = prompt_world_update(world.render_world(), message, language=language)
+    response_update = reasoning_model.prompt_model(prompt_update)
+
+    # Show the detected changes in the fictional world
+    print("🛠️ Predicted outcomes of the player input 🛠️")
+    print(f"> Player input: {message}")
+    try:
+        predicted_outcomes = re.sub(r'#([^#]*?)#','',response_update) 
+        print(f"{predicted_outcomes}\n")
+        game_log_dictionary[number_of_turns]["predicted_outcomes"] = predicted_outcomes
+
+    except Exception as e:
+        print (f"Error: {e}")
+    
+    # World update
+    world.update(response_update)
+    game_log_dictionary[number_of_turns]["updated_symbolic_world_state"] = jsonpickle.encode(world, unpicklable=True)
+    game_log_dictionary[number_of_turns]["updated_rendered_world_state"] = world.render_world()
+    
+    if last_player_position is not world.player.location:
+    #Narrate new scene
+        last_player_position = world.player.location
+        new_scene_narration = narrative_model.prompt_model(
+            prompt_narrate_current_scene(world.render_world(), 
+                                         previous_narrations = world.player.visited_locations[world.player.location.name],
+                                         language=language)
+
+        )
+        world.player.visited_locations[world.player.location.name]+=[new_scene_narration] 
+        answer += f"\n{new_scene_narration}\n\n"
+    else:
+    #Narrate actions in the current scene
+        try:
+            answer+= f"{re.findall(r'#([^#]*?)#',response_update)[0]}\n"
+        except Exception as e:
+            print (f"Error: {e}")
+
+
+    print(f"\n🌎 World state 🌍\n>Player input: {message}\n{world.render_world()}\n")
+
+    if world.check_objective():
+        if language=='es':
+            answer += "\n\n🎯¡Completaste el objetivo!"
+        else:
+            answer += "\n\n🎯You have completed your quest!"
+
+    game_log_dictionary[number_of_turns]["narration"] = answer
+
+    # Dump the whole gamelog to a json file after this turn
+    with open(os.path.join(PATH_GAMELOGS,log_filename), 'w', encoding='utf-8') as f:
+        json.dump(game_log_dictionary, f, ensure_ascii=False, indent=4)
+    
+    return answer.replace("<",r"\<").replace(">", r"\>")
+
+# Instantiate the world
+world_id = config["Options"]["WorldID"]
+world = example_worlds.get_world(world_id, language=language)
+
+# Initialize variables
+last_player_position = world.player.location
+number_of_turns = 0
+game_log_dictionary = {}
+game_log_dictionary["narrative_model_name"] = narrative_model_name
+game_log_dictionary["reasoning_model_name"] = reasoning_model_name
+
+print(f"\n🌎 World state 🌍\n{world.render_world()}\n")
+game_log_dictionary[0] = {}
+game_log_dictionary[0]["date"] = time.ctime(time.time())
+game_log_dictionary[0]["initial_symbolic_world_state"] = jsonpickle.encode(world, unpicklable=True)
+game_log_dictionary[0]["initial_rendered_world_state"] = world.render_world()
+
+#Generate a description of the starting scene
+starting_narration = narrative_model.prompt_model(
+    prompt_narrate_current_scene(world.render_world(), 
+                                 previous_narrations = world.player.visited_locations[world.player.location.name],
+                                 language=language, 
+                                 starting_scene=True))
+world.player.visited_locations[world.player.location.name]+=[starting_narration]
+
+#Generate a description of the main objective
+narrated_objective = narrative_model.prompt_model(prompt_describe_objective(world.objective, language=language))
+starting_narration += f"\n\n🎯 {re.findall(r'#([^#]*?)#',narrated_objective)[0]}"
+game_log_dictionary[0]["starting_narration"] = starting_narration
+
+with open(os.path.join(PATH_GAMELOGS,log_filename), 'w', encoding='utf-8') as f:
+    json.dump(game_log_dictionary, f, ensure_ascii=False, indent=4)
+
+#Instantiate the Gradio app
+gradio_interface = gr.ChatInterface(
+    fn=game_loop,
+    chatbot = gr.Chatbot(height=500, value=[{"role": "assistant", "content": starting_narration.replace("<",r"\<").replace(">", r"\>")}], 
+                         bubble_full_width = False, show_copy_button = False, type='messages'),
+    textbox=gr.Textbox(placeholder="What do you want to do?", container=False, scale=5),
+    title="PAYADOR",
+    theme="Soft",
+    type='messages',
+)
+
+gradio_interface.launch(inbrowser=False)

config.ini

@@ -0,0 +1,7 @@
+[Options]
+Language = es
+WorldID = 1
+
+[Models]
+NarrativeModel = gemini-1.0-pro
+ReasoningModel = gemini-1.5-flash

environment.yml

@@ -0,0 +1,11 @@
+name: payador
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.12
+  - pip
+  - pip:
+      - google-generativeai==0.8
+      - jsonpickle==4.0
+      - gradio==5.*

example_worlds.py

@@ -0,0 +1,162 @@
+"""Includes two example worlds to experiment with different scenarios."""
+
+import random
+from world import Character, Item, Location, Puzzle, World
+
+
+def get_world(arg: str, language='en') -> World:
+    if arg=='2':
+        if language == 'es':
+            return get_world_2_spanish()
+        else:
+            return get_world_2_english()
+    else:
+        if language == 'es':
+            return get_world_1_spanish()
+        else:
+            return get_world_1_english()
+
+def get_world_1_english() -> World:
+    """A simple fictional world, used as an example in Figure 3 of the paper."""
+    item_1 = Item("Apple",
+                  ["A fruit that can be eaten", "It is round-shaped and green"])
+    item_2 = Item("Toy car",
+                  ["A tiny toy purple car", "It looks brand new"])
+    item_3 = Item("Mate",
+                  ["A classical mate, ready to drink!", "It contains some yerba", "You can drink this to boost your energy!"])
+
+    place_1 = Location("Garden",
+                       ["A beautiful garden", "There is a statue in the center"],
+                       items = [item_2])
+    place_2 = Location("Cabin",
+                       ["A small cabin", "It looks like no one has lived here for a while"])
+    place_3 = Location("Mansion hall",
+                       ["A big hall", "There is a big staircase"])
+    
+    two_random_numbers =  [random.randrange(0, 10) for i in range(2)]
+    puzzle1 = Puzzle("puzzle",["There's a symbol of a microphone and below a letter that says how to open the door"],
+                      f"To unlock this door, you have to say out loud the sum of {str(two_random_numbers[0])} and {str(two_random_numbers[1])}.",
+                      f"The answer is {str(two_random_numbers[0] + two_random_numbers[1])} ")
+
+    place_1.connecting_locations+=[place_2,place_3]
+    place_2.connecting_locations+=[place_1]
+    place_3.connecting_locations+=[place_1]
+    place_1.block_passage(place_3,puzzle1)
+
+    player = Character("Alicia",
+                       ["She is wearing a long skirt","She likes to sing"],
+                       inventory=[item_1],
+                       location=place_1)
+    npc = Character("Javier",
+                    ["He has a long beard", "He loves to restore furtniture"],
+                    inventory=[item_3],
+                    location=place_3)
+
+    the_world = World(player)
+    the_world.add_locations([place_1, place_2, place_3])
+    the_world.add_items([item_1, item_2, item_3])
+    the_world.add_character(npc)
+    the_world.set_objective(item_2,place_3)
+
+    return the_world
+
+def get_world_1_spanish() -> World:
+    item_1 = Item("Manzana",
+                  ["Una fruta que puede ser comida", "Es redonda y verde"])
+    item_2 = Item("Auto de juguete",
+                  ["Un pequeño auto de juguete de color púrpura", "Luce como recién comprado"])
+    item_3 = Item("Mate",
+                  ["Un mate clásico ¡listo para tomar!", "Contiene algo de yerba", "¡Puedes tomar esto para mejorar tu energía!"])
+
+    place_1 = Location("Jardín",
+                       ["Un jardín hermoso", "Hay una estatua en el centro"],
+                       items = [item_2])
+    place_2 = Location("Cabaña",
+                       ["Una pequeña cabaña", "Parece que nadie ha vivido acá por un tiempo"])
+    place_3 = Location("Hall de la Mansión",
+                       ["Un hall grande", "Hay una enorme escalera principal"])
+
+    two_random_numbers =  [random.randrange(0, 10) for i in range(2)]
+    puzzle1 = Puzzle("puzzle",["Hay un dibujo de un micrófono y debajo un letrero, con la premisa para abrir la puerta"],
+                      f"Para desbloquear esta puerta, hay que decir en voz alta la suma de {str(two_random_numbers[0])} y {str(two_random_numbers[1])}.",
+                      f"La respuesta es {str(two_random_numbers[0] + two_random_numbers[1])} ")
+
+    place_1.connecting_locations+=[place_2,place_3]
+    place_2.connecting_locations+=[place_1]
+    place_3.connecting_locations+=[place_1]
+    place_1.block_passage(place_3,puzzle1)
+
+
+    player = Character("Alicia",
+                       ["Está usando una falda larga","Le gusta cantar"],
+                       inventory=[item_1],
+                       location=place_1)
+    npc = Character("Javier",
+                    ["Tiene una barba larga", "Le encanta restaurar muebles"],
+                    inventory=[item_3],
+                    location=place_3)
+    
+    
+
+    the_world = World(player)
+    the_world.add_locations([place_1, place_2, place_3])
+    the_world.add_items([item_1, item_2, item_3])
+    the_world.add_character(npc)
+    the_world.set_objective(item_2,place_3)
+
+
+    return the_world
+
+def get_world_2_english() -> World:
+    """Use this world to test more complex cases, like blocked passages between locations."""
+    item_1 = Item("Apple",
+                  ["A fruit that can be eaten", "It is round-shaped and red"])
+    item_2 = Item("Key",
+                  ["A key to open a lock", "It is golden", "It is engraved with a strange coat of arms"])
+    item_3 = Item("A grey Hammer",
+                  ["A great grey hammer that can be used to break things", "It is so heavy..."])
+    item_4 = Item("Lock",
+                  ["A strong lock engraved with a coat of arms", "It seems that you cannot open it with your hands"])
+    item_5 = Item("Note",
+                  ["A paper with a note", "You can read 'Go to the kitchen to know the truth'"])
+    item_6 = Item("Flashlight",
+                  ["A flashlight without batteries"])
+    item_7 = Item("A green Hammer",
+                  ["A small green hammer", "It is just a toy and you cannot break anything with it."])
+    item_8 = Item("A wall of flames",
+                  ["The heat is really intense but it is a small fire anyway"])
+    item_9 = Item("A metal flower",
+                  ["A strange flower"])
+    item_10 = Item("A fire extinguisher",
+                   ["You can control small fires with this."])
+
+    place_3 = Location ("Garden",
+                        ["A small garden below the kitchen"],
+                        items = [item_9])
+    place_2 = Location("Kitchen",
+                       ["A beautiful well-lit kitchen"],
+                       items = [item_6,item_10])
+    place_2.connecting_locations = [place_3]
+    place_2.block_passage(place_3, item_8, symmetric=False)
+
+    place_1 = Location("Cellar",
+                       ["There is a metal door locked by a lock", "You can see damp patches on the walls"],
+                       items = [item_2, item_3, item_5, item_7])
+    place_1.connecting_locations = [place_2]
+    place_1.block_passage(place_2, item_4)
+
+    player = Character("Cid",
+                       ["A tall soldier"],
+                       inventory = [item_1],
+                       location = place_1)
+    npc = Character("Elvira",
+                            ["A little girl", "Her favorite food is apple pie, but she enjoys eating any fruit", "She can't read yet"],
+                            location= place_1)
+
+    the_world = World(player)
+    the_world.add_locations([place_1,place_2,place_3])
+    the_world.add_items([item_1,item_2,item_3,item_4,item_5,
+                         item_6, item_7,item_8, item_9, item_10])
+    the_world.add_character(npc)
+
+    return the_world

models.py

@@ -0,0 +1,54 @@
+"""Load models to use them as a narrator and a common-sense oracle in the PAYADOR pipeline."""
+import google.generativeai as genai
+import requests
+
+
+class GeminiModel():
+    def __init__ (self, api_key_file:str, model_name:str = "gemini-pro") -> None:
+        """"Initialize the Gemini model using an API key."""
+        self.safety_settings = [
+            {
+                "category": "HARM_CATEGORY_DANGEROUS",
+                "threshold": "BLOCK_NONE",
+            },
+            {
+                "category": "HARM_CATEGORY_HARASSMENT",
+                "threshold": "BLOCK_NONE",
+            },
+            {
+                "category": "HARM_CATEGORY_HATE_SPEECH",
+                "threshold": "BLOCK_NONE",
+            },
+            {
+                "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+                "threshold": "BLOCK_NONE",
+            },
+            {
+                "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+                "threshold": "BLOCK_NONE",
+            },
+        ]
+        genai.configure(api_key=get_api_key(api_key_file))
+        self.model = genai.GenerativeModel(model_name)
+
+    def prompt_model(self,prompt: str) -> str:
+        """Prompt the Gemini model."""
+        return self.model.generate_content(prompt, safety_settings=self.safety_settings).text
+
+
+def prompt_HF_API (prompt: str, model: str = "microsoft/Phi-3-mini-4k-instruct", api_key_file: str = "HF_API_key"):
+    API_URL = f"https://api-inference.huggingface.co/models/{model}"
+
+    headers = {"Authorization": f"Bearer {get_api_key(api_key_file)}"}
+    payload = {"inputs": prompt}
+
+    output = requests.post(API_URL, headers=headers, json=payload).json()
+    
+    return output[0]["generated_text"]
+
+def get_api_key(path: str) -> str:
+    """Load an API key from path."""
+    key = ""
+    with open(path) as f:
+        key = f.readline()
+    return key

prompts.py

@@ -0,0 +1,218 @@
+def prompt_describe_objective (objective, language:str = 'en') -> str:
+    prompt = ""
+
+    if language == 'es':
+        prompt = prompt_describe_objective_spanish(objective)
+    else:
+        prompt = prompt_describe_objective_english(objective)
+    
+    return prompt
+
+def prompt_describe_objective_english (objective) -> str:
+
+    prompt = "Please, provide an alternative way to narrate the following objective, using simple language: "
+    first_component_class = objective[0].__class__.__name__
+    second_component_class = objective[1].__class__.__name__
+
+    if first_component_class == "Character" and second_component_class == "Location":
+        prompt+= f'"You have to go to <{objective[1].name}>."'
+    elif first_component_class == "Character" and second_component_class == "Item":
+        prompt+= f'"<{objective[0].name}> has to get the item <{objective[1].name}>."'
+    elif first_component_class == "Item" and second_component_class == "Location":
+        prompt+= f'"You have to leave item <{objective[0].name}> in place <{objective[1].name}>."'
+
+    prompt+="\nPut your generated narration between # characters. For example: # You have to get the <key> # or # You have to reach the <castle> #"
+
+    return prompt
+
+def prompt_describe_objective_spanish (objective) -> str:
+
+    prompt = "Por favor, dame una forma alternativa de narrar el siguiente objetivo, usando lenguaje simple: "
+    first_component_class = objective[0].__class__.__name__
+    second_component_class = objective[1].__class__.__name__
+
+    if first_component_class == "Character" and second_component_class == "Location":
+        prompt+= f'"Tienes que ir a <{objective[1].name}>."'
+    elif first_component_class == "Character" and second_component_class == "Item":
+        prompt+= f'"<{objective[0].name}> tiene que conseguir el objeto <{objective[1].name}>."'
+    elif first_component_class == "Item" and second_component_class == "Location":
+        prompt+= f'"Tienes que dejar el objeto <{objective[0].name}> en el lugar <{objective[1].name}>."'
+
+    prompt+="\nPon tu narración generada entre caracteres #. Por ejemplo: # Tienes que conseguir la <llave> # o # Tienes que llegaral <Castillo> #"
+
+    return prompt
+
+def prompt_narrate_current_scene (world_state: str, previous_narrations: 'list[str]', language: str = 'en', starting_scene: bool = False) -> str:
+    prompt = ""
+
+    if language == 'es':
+        prompt = prompt_narrate_current_scene_spanish(world_state, previous_narrations, starting_scene)
+    else:
+        prompt = prompt_narrate_current_scene_english(world_state, previous_narrations, starting_scene)
+
+
+    return prompt
+
+def prompt_narrate_current_scene_english (world_state: str, previous_narrations: 'list[str]', starting_scene: bool = False) -> str:
+
+    prompt = "You are a storyteller. Take the following state of the world and narrate it in a few sentences. Be careful not to include details that contradict the current state of the world or that move the story forward. Also, try to use simple sentences and do not overuse poetic language.\n"
+    
+    if starting_scene:
+        prompt += "\nTake into account that this is the first scene in the story: introduce the main character, creating a small background story and why that character is in that specific location.\n"
+    elif len(previous_narrations)==0:
+        prompt += "Take into account that the player already knows what the main character looks like, so do not mention anything about that. However, it is the first time the player visits this place, so make sure to describe it exhaustively."
+    else:
+        prompt += "Take into account that the player already knows what the main character looks like, so do not mention anything about that. Additionally, it is not the first time the player visits this place. Next I’ll give you some previous narrations of this same location (from oldest to newest) so you can be sure to not repeat the same details again:\n"
+        for narration in previous_narrations:
+            prompt+=f'- {narration}\n'
+
+    prompt+= "\nRemember: you are talking to the player, describing what his or her character has and what he or she can see or feel."
+
+    prompt +=f"""This is the state of the world at the moment:
+    {world_state}
+    """
+
+    return prompt
+
+def prompt_narrate_current_scene_spanish (world_state: str, previous_narrations: 'list[str]', starting_scene: bool = False) -> str:
+    
+    prompt = f"""Eres un narrador. Toma el siguiente estado del mundo y nárralo en unas pocas oraciones. Ten cuidado de no incluir detalles que contradigan el estado del mundo actual, o que hagan avanzar la historia. Además, intenta usar oraciones simples, sin abusar del lenguaje poético."""
+    
+    if starting_scene:
+        prompt += "\nTen en cuenta que esta es la primera escena en la historia narradad: presenta al personaje del jugador, creando un pequeño trasfondo y por qué este personaje está en ese lugar específicamente.\n"
+    elif len(previous_narrations)==0:
+        prompt += "Ten en cuenta que el jugador ya conoce a su personaje, y cómo se ve, así que no menciones nada sobre esto. Sin embargo, es la primera vez que el jugador visita este lugar, así que describelo exaustivamente."
+    else:
+        prompt += "Ten en cuenta que el jugador ya conoce a s upersonaje, y cómo se ve, así que no menciones nada sobre esto. Además, no es la primera vez que el jugador visita este lugar. A continuación te daré algunas narraciones previas de este mismo lugar (de la más antigua a la más nueva), así te puedes asegurar de no repetir los mismos detalles de nuevo:\n"
+        for narration in previous_narrations:
+            prompt+=f'- {narration}\n'
+
+    prompt+= "\nRecuerda: le estás hablando al jugador, describiendo lo que su personaje tiene y lo que puede sentir o ver."
+
+    prompt +=f"""Este es el estado del mundo en este momnto:
+    {world_state}
+    """
+
+    return prompt
+
+def prompt_world_update (world_state: str, input: str, language: str = 'en') -> str:
+    prompt = ""
+
+    if language == 'es':
+        prompt = prompt_world_update_spanish(world_state, input)
+    else:
+        prompt = prompt_world_update_english(world_state, input)
+
+
+    return prompt
+
+def prompt_world_update_spanish (world_state: str, input: str) -> str:
+    prompt = f"""Eres un narrador. Estás manejando un mundo ficticio, y el jugador puede interactuar con él. Este es el estado del mundo en este momento:
+    {world_state}\n\n
+    Explica los cambios en el mundo a partir de las acciones del jugador en esta entrada "{input}". 
+    
+    Aquí hay algunas aclaraciones:
+    (A) Si un pasaje está bloqueado, significa que el jugador debe desbloquearlo antes de poder acceder al lugar. Aunque el jugador te diga que va a acceder al lugar bloqueado, tienes que estar seguro de que está cumpliendo con lo pedido para permitirle desbloquear el acceso, por ejemplo usando una llave o resolviendo un puzzle.
+    (B) Presta atención a a la descripción de los componentes y sus capacidades.
+	(C) No asumas que lo que dice el jugador siempre tiene sentido; quizás esas acciones intentan hacer algo que el mundo no lo permite.
+    (D) Sigue siempre el siguiente formato con las tres categorías, usando "None" en cada caso si no hay cambios y repite la categoría por cada caso:
+    - Moved object: <object> now is in <new_location>
+    - Blocked passages now available: <now_reachable_location>
+    - Your location changed: <new_location>
+    
+    Aquí hay algunos ejemplos sobre el formato, descrito en el anterior punto (D).
+    Ejemplo 1
+    - Moved object: <hacha> now is in <Inventory>
+    - Blocked passages now available: None
+    - Your location changed: None
+
+    Ejemplo 2
+    - Moved object: None
+    - Blocked passages now available: None
+    - Your location changed: <Jardín>
+
+    Ejemplo 3
+    - Moved object: <banana> now is in <Inventory>,  <botella> now is in <Inventory>,  <hacha> now is in <Hall principal>
+    - Blocked passages now available: None
+    - Your location changed: None
+
+    Ejemplo 4
+    - Moved object: <banana> now is in <Inventory>,  <botella> now is in <Inventory>,  <hacha> now is in <Hall principal>
+    - Blocked passages now available: <Pequeña habitación>
+    - Your location changed: None
+
+    Ejemplo 5
+    - Moved object: <banana> now is in <Inventory>,  <botella> now is in <Inventory>,  <hacha> now is in <Hall principal>
+    - Blocked passages now available: <Pequeña habitación>
+    - Your location changed:  <Pequeña habitación>
+
+    Ejemplo 6
+    - Moved object: <libro> now is in <John>,  <lápiz> now is in <Inventory>
+    - Blocked passages now available: None
+    - Your location changed:  None
+
+    Ejemplo 7
+    - Moved object: <computadora> now is in <Susan>
+    - Blocked passages now available: None
+    - Your location changed:  None
+    
+	Por último, puedes agregar una pequeña oración final narrando los cambios detecados en el estado del mundo (¡sin hacer avanzar la historia y sin crear detalles no incluidos en el estado del mundo!) o respondiendo una pregunta del jugador sobre el estado del mundo, usando el formato: #<tu oración final>#
+    """
+
+    return prompt
+
+def prompt_world_update_english (world_state: str, input: str) -> str:
+    prompt = f"""You are a storyteller. You are managing a fictional world, and the player can interact with it. This is the state of the world at the moment:
+    {world_state}\n\n
+    Explain the changes in the world after the player actions in this input "{input}". 
+    
+    Here are some clarifications:
+    (A) If a passage is blocked, then the player must unblock it before being able to reach the place. Even if the player tells you that he is going to access the locked location, you have to be sure that he is complying with what you asked to allow him to unlock the access, for example by using a key or solving a puzzle.
+    (B) Pay atenttion to the description of the components and their capabilities.
+    (C) Do not assume that the player input always make sense; maybe those actions try to do something that the world does not allow.
+    (D) Follow always the following format with the three categories, using "None" in each case if there are no changes and repeat the category for each case:
+    - Moved object: <object> now is in <new_location>
+    - Blocked passages now available: <now_reachable_location>
+    - Your location changed: <new_location>
+    
+    Here you have some examples. 
+    Example 1
+    - Moved object: <axe> now is in <Inventory>
+    - Blocked passages now available: None
+    - Your location changed: None
+
+    Example 2
+    - Moved object: None
+    - Blocked passages now available: None
+    - Your location changed: <Garden>
+
+    Example 3
+    - Moved object: <banana> now is in <Inventory>,  <bottle> now is in <Inventory>,  <axe> now is in <Main Hall>
+    - Blocked passages now available: None
+    - Your location changed: None
+
+    Example 4
+    - Moved object: <banana> now is in <Inventory>,  <bottle> now is in <Inventory>,  <axe> now is in <Main Hall>
+    - Blocked passages now available: <Small room>
+    - Your location changed: None
+
+    Example 5
+    - Moved object: <banana> now is in <Inventory>,  <bottle> now is in <Inventory>,  <axe> now is in <Main Hall>
+    - Blocked passages now available: <Small room>
+    - Your location changed:  <Small room>
+
+    Example 6
+    - Moved object: <book> now is in <John>,  <pencil> now is in <Inventory>
+    - Blocked passages now available: None
+    - Your location changed:  None
+
+    Example 7
+    - Moved object: <computer> now is in <Susan>
+    - Blocked passages now available: None
+    - Your location changed:  None
+    
+
+    Finally, you can add a final short sentence narrating the detected changes in the state of the world (without moving the story forward and creating details not included in the state of the world!) or answering a question of the player about the state of the world, using the format: #<your final sentence>#
+    """
+
+    return prompt

world.py

@@ -0,0 +1,357 @@
+"""This module implements the classes needed to represent the fictional world of the game.
+
+The world class includes references to the several components (Items, Locations, Character),
+and methods to update according to the detected changes by a language model.
+"""
+
+import re
+from typing import Type
+
+
+class Component:
+  """A class to represent a component of the world.
+
+  The components considered in the PAYADOR approach are Items, Locations and Characters.
+  """
+  def __init__ (self, name:str, descriptions: 'list[str]'):
+
+    self.name = name
+    """the name of the component"""
+
+    self.descriptions = descriptions
+    """a set of natural language descriptions for the component"""
+  
+class Puzzle (Component):
+  """A class to represent a Puzzle"""
+
+  def __init__(self, name:str, descriptions: 'list[str]', problem: str, answer: str):
+    
+    super().__init__(name, descriptions)
+    """inherited from Component"""
+
+    self.problem = problem
+    """the main problem to be solved"""
+
+    self.answer = answer
+    """a possible answer to the riddle or puzzle"""
+
+class Item (Component):
+  """A class to represent an Item."""
+  def __init__ (self, name:str, descriptions: 'list[str]', gettable: bool = True):
+
+    super().__init__(name, descriptions)
+    """inherited from Component"""
+
+    self.gettable = gettable
+    """indicates if the Item can be taken by the player"""
+
+class Location (Component):
+  """A class to represent a Location in the world."""
+  def __init__ (self, name:str, descriptions: 'list[str]', items: 'list[Item]' = None, connecting_locations: 'list[Location]' = None):
+
+    super().__init__(name, descriptions)
+    """inherited from Component"""
+
+    self.items = items or []
+    """a list of the items available in that location"""
+
+    self.connecting_locations = connecting_locations or []
+    """a list of the reachable locations from itself."""
+
+    self.blocked_locations = {}
+    """a dictionary with the name of a location as key and <location,obstacle,symmetric> as value.
+    A blocked passage between self and a location means that it
+    will be reachable from [self] after overcoming the [obstacle].
+    The symmetric variable is a boolean that indicates if, when unblocked,
+    [self] will also be reachable from [location].
+    """
+
+  def block_passage(self, location: 'Location', obstacle, symmetric: bool = True):
+    """Block a passage between self and location using an obstacle."""
+    if location in self.connecting_locations:
+      if location.name not in self.blocked_locations:
+        self.blocked_locations[location.name] = (location, obstacle, symmetric)
+        self.connecting_locations = [x for x in self.connecting_locations if x is not location]
+      else:
+        raise Exception(f"Error: A blocked passage to {location.name} already exists")
+    else:
+        raise Exception(f"Error: Two non-conected locations cannot be blocked")
+
+  def unblock_passage(self, location: 'Location'):
+    """Unblock a passage between self and location by adding it to the connecting locations of self.
+
+    In case that the block was symmetric, self will be added to the connecting locations of location.
+    """
+    if self.blocked_locations[location.name]:
+      self.connecting_locations += [location]
+      if self.blocked_locations[location.name][2] and self not in location.connecting_locations:
+        location.connecting_locations += [self]
+      del self.blocked_locations[location.name]
+    else:
+      raise Exception("Error: That is not a blocked passage")
+
+class Character (Component):
+  """A class to represent a character."""
+  def __init__ (self, name:str, descriptions: 'list[str]', location:Location, inventory: 'list[Item]' = None):
+
+    super().__init__(name, descriptions)
+    """inherited from Component"""
+
+    self.inventory = inventory or []
+    """a set of Items the carachter has"""
+
+    self.location = location
+    """the location of the character"""
+
+    self.visited_locations = {self.location.name: []}
+    """a dictionary that contains the successive descriptions of the visited places"""
+
+  def move(self, new_location: Location):
+    """Move the character to a new location."""
+    if new_location in self.location.connecting_locations:
+      self.location = new_location
+      if self.location.name not in self.visited_locations:
+        self.visited_locations[self.location.name] = []
+    else:
+      raise Exception(f"Error: {new_location.name} is not reachable")
+
+  def save_item(self,item: Item, item_location_or_owner):
+    """Add an item to the character inventory."""
+    if item.gettable:
+      if item not in self.inventory:
+        self.inventory += [item]
+        if item_location_or_owner.__class__.__name__ == 'Character':
+          item_location_or_owner.inventory = [i for i in item_location_or_owner.inventory if i is not item]
+        elif item_location_or_owner.__class__.__name__ == 'Location':
+          item_location_or_owner.items = [i for i in item_location_or_owner.items if i is not item]
+      else:
+        raise Exception(f"Error: {item.name} is already in your inventory")
+    else:
+      raise Exception(f"Error: {item.name} cannot be taken")
+
+  def drop_item (self, item: Item):
+    """Leave an item in the current location."""
+    self.inventory = [i for i in self.inventory if i is not item]
+    self.location.items += [item]
+
+  def give_item (self, character: 'Character', item: Item):
+    """Give an item to another character."""
+    try:
+      character.save_item(item, self)
+    except Exception as e:
+      print(e)
+
+
+class World:
+  """A class to represent the fictional world, with references to every component."""
+  def __init__ (self, player: Character) -> None:
+
+    self.items = {}
+    """a dictionary of all the Items in the world, with their names as values"""
+
+    self.characters = {}
+    """a dictionary of all the Characters in the world, with their names as values"""
+
+    self.locations =  {}
+    """a dictionary of all the Locations in the world, with their names as values"""
+
+    self.player = player
+    """a character for the player"""
+
+    self.objective = None
+    """the current objective for the player in this world"""
+
+  def set_objective (self, first_component: Type[Component], second_component: Type[Component]):
+    
+    first_component_class = first_component.__class__.__name__
+    second_component_class = second_component.__class__.__name__
+    
+    if  first_component_class == second_component_class:
+      raise Exception(f"Error: Objectives with same two classes {first_component_class} are not allowed")
+    elif (first_component_class == "Character" and second_component_class in ["Location", "Item"]) or (second_component_class == "Character" and first_component_class in ["Location", "Item"]):
+      self.objective = (first_component, second_component)
+    elif (first_component_class  == "Item" and second_component_class == "Location") or (second_component_class  == "Item" and first_component_class == "Location"):
+      self.objective = (first_component, second_component)
+    else:
+      raise Exception(f"Error: Cannot set objective with classes {first_component_class} and {second_component_class}")
+
+  def check_objective(self) -> bool:
+
+    done = False
+    first_component_class = self.objective[0].__class__.__name__
+    second_component_class = self.objective[1].__class__.__name__
+
+    if first_component_class == "Character" and second_component_class == "Location":
+      if self.objective[0].location == self.objective[1]: done = True
+    elif first_component_class == "Character" and second_component_class == "Item":
+      if self.objective[1] in self.objective[0].inventory: done = True
+    elif first_component_class == "Item" and second_component_class == "Location":
+      if self.objective[0] in self.objective[1].items: done = True
+
+    return done
+
+  def add_location (self,location: Location) -> None:
+    """Add a location to the world."""
+    if location.name in self.locations:
+      raise Exception(f"Error: Already exists a location called '{location.name}'")
+    else:
+       self.locations[location.name] = location
+
+  def add_item (self, item: Item) -> None:
+    """Add an item to the world."""  
+    if item.name in self.items:
+      raise Exception(f"Error: Already exists an item called '{item.name}'")
+    else:
+      self.items[item.name] = item
+
+  def add_character (self, character: Character) -> None:
+    """Add a character to the world."""
+    if character.name in self.characters:
+      raise Exception(f"Error: Already exists a character called '{character.name}'")
+    else:
+      self.characters[character.name] = character
+
+  def add_locations (self,locations: 'list[Location]') -> None:
+    """"Add a set of locations to the world."""
+    for location in locations:
+      self.add_location(location)
+
+  def add_items (self, items: 'list[Item]') -> None:
+    """Add a set of items to the world."""
+    for item in items:
+      self.add_item(item)
+
+  def add_characters (self, characters: 'list[Character]') -> None:
+    """Add a set of characters to the world."""
+    for character in characters:
+      self.add_character(character)
+
+  def render_world(self, *,  detail_components:bool = True) -> str:
+    """Return the fictional world as a natural language description, using simple sentences.
+
+    The components described are only those the player can see in the current location.
+    If detail_components is False, then the descriptions for each component are not included.
+    """
+    player_location = self.player.location
+    reachable_locations = [f"<{p.name}>" for p in player_location.connecting_locations]
+    blocked_passages = [f"<{p}> blocked by <{player_location.blocked_locations[p][1].name}>" for p in player_location.blocked_locations.keys()]
+    characters_in_the_scene = [character for character in self.characters.values() if character.location is player_location]
+
+    
+    world_description = f'You are in <{player_location.name}>\n'
+    
+    if reachable_locations:
+      world_description += f'From <{player_location.name}> you can access: {(", ").join(reachable_locations)}\n'
+    else:
+      world_description += f'From <{player_location.name}> you can access: None\n'
+
+    if blocked_passages:
+      world_description += f'From <{player_location.name}> there are blocked passages to: {(", ").join(blocked_passages)}\n'
+    else:
+      world_description += f'From <{player_location.name}> there are blocked passages to: None\n'
+
+    if self.player.inventory:
+      world_description += f'You have the following items in your inventory: {(", ").join([f"<{i.name}>" for i in self.player.inventory])}\n'
+    else:
+      world_description += f'You have the following items in your inventory: None\n'
+
+    if player_location.items:
+      world_description += f'If you look around, you can see the following items: {(", ").join([f"<{i.name}>" for i in player_location.items])}\n'
+    else:
+      world_description += f'If you look around, you can see the following items: None\n'
+      
+    if characters_in_the_scene:
+      world_description += f'You can see some people: {(", ").join([f"<{c.name}>" for c in characters_in_the_scene])}'
+    else:
+      world_description += f'You can see some people: None'
+
+    details = ""
+    if detail_components:
+      items_in_the_scene = player_location.items + self.player.inventory + [blocked_values[1] for blocked_values in player_location.blocked_locations.values() if isinstance(blocked_values[1], Item)]
+      puzzles_in_the_scene = [blocked_values[1] for blocked_values in player_location.blocked_locations.values() if isinstance(blocked_values[1], Puzzle)]
+
+      details += "\nHere is a description of each component.\n"
+      details += f"<{player_location.name}>: This is the player's location. {('. ').join(player_location.descriptions)}.\n"
+      details += "Characters:\n"
+      details += f"- <Player>: The player is acting as {self.player.name}. {('. ').join(self.player.descriptions)}.\n"
+      if len(characters_in_the_scene)>0:
+        for character in characters_in_the_scene:
+          details += f"- <{character.name}>: {('. ').join(character.descriptions)}."
+          if len(character.inventory)>0:
+            details += f" This character has the following items: {(', ').join([f'<{i.name}>' for i in character.inventory])}\n"
+            items_in_the_scene+= character.inventory
+          else:
+            details += "\n"
+      if len(items_in_the_scene)>0:
+        details+="Objects:\n"
+        for item in items_in_the_scene:
+          details += f"- <{item.name}>: {('. ').join(item.descriptions)}\n"
+      if len(puzzles_in_the_scene)>0:
+        details+="Puzzles:\n"
+        for puzzle in puzzles_in_the_scene:
+          details+= f'- <{puzzle.name}>: {('. ').join(puzzle.descriptions)}. The riddle to solve is: "{puzzle.problem}". The expected answer, that you CANNOT tell the player (EVER) is: "{puzzle.answer}".\n'
+
+    return world_description + '\n' + details
+
+  def update (self, updates: str) -> None:
+    """Does the changes in the world according to the output of the language model.
+
+    The possible changes considered are:
+      - an object was moved
+      - a location is now reachable
+      - the position of the player changed.
+    """
+    self.parse_moved_objects(updates)
+    self.parse_blocked_passages(updates)
+    self.parse_location_change(updates)
+
+  def parse_moved_objects (self, updates: str) -> None:
+    """Parse the output of the language model to update the position of objects.
+
+    There are three cases:
+      - the player has a new item
+      - the player gave an item to other character
+      - the player dropped an item.
+    """
+    parsed_objects = re.findall(r".*Moved object:\s*(.+)",updates)
+    if 'None' not in parsed_objects:
+      parsed_objects_split = re.findall(r"<[^<>]*?>.*?<[^<>]*?>",parsed_objects[0])
+      for parsed_object in parsed_objects_split:
+        pair = re.findall(r"<([^<>]*?)>.*?<([^<>]*?)>",parsed_object)
+        try:
+          world_item = self.items[pair[0][0]]
+          
+          if pair[0][1] in ['Inventory', 'Inventario', 'Player',  'Jugador', self.player.name]: #(save_item case)
+            item_location = [character for character in list(self.characters.values()) if world_item in character.inventory]
+            item_location += [location for location in list(self.locations.values()) if world_item in location.items]
+            self.player.save_item(world_item, item_location[0])
+
+          elif pair[0][1] in self.characters: #(give_item case)
+            self.player.give_item(self.characters[pair[0][1]], world_item)
+          
+          else: #(drop_item case)
+            self.player.drop_item(world_item)
+        except Exception as e:
+          print(e)
+
+  def parse_blocked_passages (self, updates: str) -> None:
+    """Parse the output of the language model to update the reachable locations."""
+    parsed_blocked_passages = re.findall(r".*Blocked passages now available:\s*(.+)",updates)
+    if 'None' not in parsed_blocked_passages:
+      parsed_blocked_passages_split = re.findall(r"<([^<>]*?)>",parsed_blocked_passages[0])
+      for parsed_passage in parsed_blocked_passages_split:
+        try:
+          self.locations[self.player.location.name].unblock_passage(self.locations[parsed_passage])
+        except Exception as e:
+          print (e)
+
+  def parse_location_change (self, updates: str) -> None:
+    """Parse the output of the language model to update the position of the player."""
+    parsed_location_change = re.findall(r".*Your location changed: (.+)",updates)
+    if "None" not in parsed_location_change:
+      parsed_location_change_split = re.findall(r"<([^<>]*?)>",parsed_location_change[0])
+      try:
+        self.player.move(self.locations[parsed_location_change_split[0]])
+      except Exception as e:
+        print(e)
+