Add comments to code,Update README.md, Sintezise game.py modules

README.md

@@ -10,4 +10,105 @@ pinned: false
 license: other
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Semantrix Game
+
+This repository contains the implementation of the Semantrix game, a word guessing game using word embeddings. The game supports multiple languages (Spanish and English) and can be configured to use either a Word2Vec model or a SentenceTransformer model for word embeddings.
+
+## Modules
+
+
+
+### app.py
+
+This module defines a Gradio-based web application for the Semantrix game. The application allows users to play the game in either Spanish or English, using different embedding models for word similarity.
+
+#### Functions
+
+- `convert_to_markdown_centered(text)`: Converts text to a centered markdown format for displaying game history and last attempt.
+    - **Parameters**:
+        - `text (str)`: The text to be converted.
+    - **Returns**: `str`: The centered markdown formatted text.
+
+- `reset(difficulty, lang, model)`: Resets the game state based on the selected difficulty, language, and model.
+    - **Parameters**:
+        - `difficulty`: The selected difficulty level.
+        - `lang`: The selected language.
+        - `model`: The selected embedding model.
+    - **Returns**: `list`: A list of initial output components for the UI.
+
+- `change(state, inp)`: Changes the game state by incrementing the state variable.
+    - **Parameters**:
+        - `state`: The current game state.
+        - `inp`: The user input.
+    - **Returns**: `list`: A list containing the updated state and input component.
+
+- `update(state, radio, inp, hint)`: Updates the game state and UI components based on the current state and user inputs.
+    - **Parameters**:
+        - `state`: The current game state.
+        - `radio`: The radio input component.
+        - `inp`: The user input.
+        - `hint`: The hint state.
+    - **Returns**: `list`: A list of updated output components for the UI.
+
+### game.py
+
+This module defines the Semantrix class, which implements a word guessing game using word embeddings. The game can be configured to use either a Word2Vec model or a SentenceTransformer model for word embeddings. The game supports multiple languages and difficulty levels.
+
+#### Classes
+
+- `Semantrix`: A class that implements the Semantrix word guessing game.
+    - **Methods**:
+        - `__init__(self, lang=0, model_type="SentenceTransformer")`: Initializes the Semantrix game with the specified language and model type.
+        - `prepare_game(self, difficulty)`: Prepares the game with the selected difficulty level.
+        - `gen_rank(self, repeated)`: Generates the ranking file based on the scores.
+        - `play_game(self, word)`: Plays the game with the selected word and returns feedback.
+        - `curiosity(self)`: Generates a curiosity hint about the secret word once the game is over.
+
+### hints.py
+
+This module provides functions to generate dynamic hints and curiosities about a secret word using language models (LLMs).
+
+#### Functions
+
+- `hint(secret, n, model, last_hint, lang, Config)`: Generates a dynamic hint based on the secret word and the number of hints given.
+    - **Parameters**:
+        - `secret (str)`: The secret word.
+        - `n (int)`: The number of hints already given.
+        - `model`: The sentence transformer model used for encoding.
+        - `last_hint (int)`: The index of the last hint given.
+        - `lang (int)`: The language code (0 for Spanish, 1 for English).
+        - `Config`: Configuration object containing hint templates.
+    - **Returns**: `tuple`: A tuple containing the generated hint (str), the updated number of hints (int), and the index of the last hint given (int).
+
+- `curiosity(secret, Config)`: Generates a curiosity about the secret word.
+    - **Parameters**:
+        - `secret (str)`: The secret word.
+        - `Config`: Configuration object containing the curiosity template.
+    - **Returns**: `str`: The generated curiosity.
+
+- `ireplace(old, new, text)`: Replaces all occurrences of a substring in a string, case-insensitively.
+    - **Parameters**:
+        - `old (str)`: The substring to be replaced.
+        - `new (str)`: The substring to replace with.
+        - `text (str)`: The original string.
+    - **Returns**: `str`: The modified string with all occurrences of the old substring replaced by the new substring.
+
+    
+## How to Run
+
+1. Clone the repository.
+2. Install the required dependencies.
+3. Run the `app.py` script to launch the Gradio web application.
+
+## Dependencies
+
+- Gradio
+- OpenAI
+- SentenceTransformers
+- Gensim
+- NumPy
+
+## License
+
+This project is licensed under the MIT License.

app.py

@@ -1,19 +1,78 @@
+"""
+This module defines a Gradio-based web application for the Semantrix game. The application allows users to play the game in either Spanish or English, using different embedding models for word similarity.
+
+Modules:
+    gradio: Used for creating the web interface.
+    json: Used for loading configuration files.
+    game: Contains the Semantrix class for game logic.
+
+File Paths:
+    config_file_path: Path to the configuration file.
+    logo_path: Path to the logo image.
+    logo_win_path: Path to the winning logo image.
+
+Functions:
+    convert_to_markdown_centered(text):
+        Converts text to a centered markdown format for displaying game history and last attempt.
+
+    reset(difficulty, lang, model):
+        Resets the game state based on the selected difficulty, language, and model.
+
+    change(state, inp):
+        Changes the game state by incrementing the state variable.
+
+    update(state, radio, inp, hint):
+        Updates the game state and UI components based on the current state and user inputs.
+
+Gradio Components:
+    demo: The main Gradio Blocks component that contains the entire UI layout.
+    header: A Markdown component for displaying the game header.
+    state: A State component for tracking the current game state.
+    difficulty: A State component for tracking the difficulty level.
+    hint: A State component for tracking if a hint is provided.
+    img: An Image component for displaying the game logo.
+    ranking: A Markdown component for displaying the ranking.
+    out: A Textbox component for displaying game messages.
+    hint_out: A Textbox component for displaying hints.
+    radio: A Radio component for user selections.
+    inp: A Textbox component for user input.
+    but: A Button component for several actions.
+    give_up: A Button component for giving up.
+    reload: A Button component for reloading the game.
+    model: A Dropdown component for selecting the embedding model.
+    lang: A Dropdown component for selecting the language.
+
+Events:
+    inp.submit: Triggers the change function on input submission.
+    but.click: Triggers the change function on button click.
+    give_up.click: Triggers the change function on give up button click.
+    radio.input: Triggers the change function on radio input.
+    reload.click: Triggers the reset function on reload button click.
+    demo.load: Triggers the reset function on demo load.
+    lang[0].select: Triggers the reset function on language selection.
+    model[0].select: Triggers the reset function on model selection.
+    state.change: Triggers the update function on state change.
+
+Main:
+    Launches the Gradio application if the script is run as the main module.
+"""
+
 import gradio as gr
 import json
-from game_word2vec import Semantrix as semantrix_word2vec
-from game_transformer import Semantrix as semantrix_sentence_transformers
-
+from game import Semantrix
 
+# File paths for configuration and images
 config_file_path = "config/lang.json"
 logo_path = "config/images/logo.png"
 logo_win_path = "config/images/logo_win.gif"
 
+# Loading the configuration file
 with open(config_file_path, "r") as file:
     Config_full = json.load(file)
 
-lang_conf = 0
-
+lang_conf = 0  # Language configuration flag (0 for Spanish, 1 for English)
 
+# Setting the configuration based on the language flag
 if lang_conf == 1:
     Config = Config_full["ENG"]["Game"]
     Menu = Config_full["ENG"]["Menu"]
@@ -22,6 +81,7 @@ else:
     Menu = Config_full["SPA"]["Menu"]
 
 
+# Function to convert text to centered markdown format
 def convert_to_markdown_centered(text):
     lines = text.strip().split("\n")
 
@@ -64,13 +124,17 @@ def convert_to_markdown_centered(text):
     return markdown
 
 
+#
 with gr.Blocks() as demo:
-    state = gr.State(-1)
-    difficulty = gr.State(-1)
-    hint = gr.State(False)
+    # Initializing state variables to manage the internal state of the application
+    state = gr.State(-1)  # State variable to track the current game state
+    difficulty = gr.State(-1)  # State variable to track the difficulty level
+    hint = gr.State(False)  # State variable to track if the hint is provided
 
-    game = semantrix_sentence_transformers()
+    # Initializing the game using the Semantrix class with default parameters
+    game = Semantrix(lang=0, model_type="SentenceTransformer")
 
+    # Creating a Markdown component to display the header
     header = gr.Markdown(
         """
     <p style="text-align:center"> """
@@ -79,15 +143,22 @@ with gr.Blocks() as demo:
     """
     )
 
+    # Function to reset the game
     def reset(difficulty, lang, model):
-        global Config, game, Menu
+        global Config, game, Menu  # Declare global variables to modify them within the function
+
+        # Determine the language based on the input parameter
         language = 1 if lang == "English" else 0
 
+        # Initialize the game object based on the selected model
         if model == "Word2Vec":
-            game = semantrix_word2vec(language)
+            game = Semantrix(language, "word2vec")  # Use Word2Vec model
         else:
-            game = semantrix_sentence_transformers(language)
+            game = Semantrix(
+                language, "SentenceTransformer"
+            )  # Use Sentence Transformers model
 
+        # Set the configuration and menu based on the selected language
         if language == 1:
             Config = Config_full["ENG"]["Game"]
             Menu = Config_full["ENG"]["Menu"]
@@ -95,7 +166,10 @@ with gr.Blocks() as demo:
             Config = Config_full["SPA"]["Game"]
             Menu = Config_full["SPA"]["Menu"]
 
+        # Prepare the game with the selected difficulty level
         game.prepare_game(difficulty)
+
+        # Define the initial output components for the UI
         output = [
             -1,
             gr.Textbox(visible=False),
@@ -114,20 +188,30 @@ with gr.Blocks() as demo:
             ),
         ]
 
+        # Return the initial output components
         return output
 
+    # Function to change the state of the game
     def change(state, inp):
-
+        # Increment the state by 1
         state = state + 1
+
+        # Return the updated state and input component
         return [state, inp]
 
+    # Function to update the game state based on the current state of the game
     def update(state, radio, inp, hint):
         global difficulty
+
+        # Define the difficulty state
         dif_state = 4
+
+        # Initialize the output component list with the current state
         output = [state]
 
         state_int = state
 
+        # Define UI components for the initial state
         if state_int == -1:
             output.extend(
                 [
@@ -145,6 +229,7 @@ with gr.Blocks() as demo:
                 ]
             )
 
+        # Define UI components for the first state, ask the user if they want to know the rules
         elif state_int == 1:
             output.extend(
                 [
@@ -161,6 +246,8 @@ with gr.Blocks() as demo:
                     gr.Markdown(visible=False),
                 ]
             )
+
+        # Define UI components for the second state, Depending on the answer, show the rules or keep going
         elif state_int == 2:
             if radio == Menu["No"]:
                 output = [
@@ -196,6 +283,8 @@ with gr.Blocks() as demo:
                         gr.Markdown(visible=False),
                     ]
                 )
+
+        # Define UI components for the difficulty state, ask the user to select the difficulty level
         elif state_int == dif_state:
             output.extend(
                 [
@@ -215,6 +304,8 @@ with gr.Blocks() as demo:
                     gr.Markdown(visible=False),
                 ]
             )
+
+        # Define UI components for the difficulty state + 1, prepare the game based on the selected difficulty level, and start the game
         elif state_int == dif_state + 1:
             if radio == Menu["Easy"]:
                 difficulty = 1
@@ -241,6 +332,7 @@ with gr.Blocks() as demo:
                 ]
             )
 
+        # Define UI components for the difficulty state + 2, play the game based on the selected difficulty level and prepare the game for the word guessing
         elif state_int == dif_state + 2:
 
             game.prepare_game(difficulty)
@@ -263,8 +355,14 @@ with gr.Blocks() as demo:
                     gr.Markdown(visible=False),
                 ]
             )
+
+        # Define UI components for the state greater than the difficulty state + 2, play the game and provide feedback based on the user input
         elif state_int > dif_state + 2:
+
+            # Send the user input to the game and get the feedback from the game
             feed = game.play_game(inp)
+
+            # Check if the feedback contains the ranking information and process it
             feedback_trim = feed.split("[rank]")
             if len(feedback_trim) > 1:
                 ranking_vis = True
@@ -274,17 +372,30 @@ with gr.Blocks() as demo:
                 ranking_vis = False
                 ranking_md = ""
 
+            # Check if the feedback contains a hint, win, or lose message
             feedback = feedback_trim[0].split("[hint]")
             win = feedback_trim[0].split("[win]")
             lose = feedback_trim[0].split("[lose]")
+
+            # Check if the feedback contains a hint message
             if len(feedback) > 1:
                 hint = True
+                hint_out = feedback[1]
+                feedback = feedback[0]
             else:
                 hint = False
+                feedback = feedback[0]
 
+            # Check if the feedback contains a win or lose message and process it
             if len(win) > 1 or len(lose) > 1:
+
+                # Check if the user won the game
                 won = True if len(win) > 1 else False
+
+                # Get the curiosity message from the game
                 curiosity = game.curiosity()
+
+                # Define the output components for the win or lose state
                 output.extend(
                     [
                         gr.Button(Menu["Send"], visible=False, variant="primary"),
@@ -304,24 +415,25 @@ with gr.Blocks() as demo:
                         gr.Markdown(visible=False),
                     ]
                 )
+
                 return output
 
+            # Define the output components for the feedback and keep playing
             output.extend(
                 [
                     gr.Button(Menu["Send"], visible=True, variant="primary"),
                     gr.Radio(label="", visible=False),
-                    gr.Textbox(feedback[0], visible=True, label=""),
+                    gr.Textbox(feedback, visible=True, label=""),
                     gr.Button(visible=True, variant="stop"),
                     gr.Textbox(value="", visible=True, placeholder=Menu["New_word"]),
                     gr.Image(logo_path, interactive=False, visible=False),
-                    gr.Textbox(
-                        feedback[1] if hint else "", visible=hint, label="Pista"
-                    ),
+                    gr.Textbox(hint_out if hint else "", visible=hint, label="Pista"),
                     gr.Button(visible=False),
                     gr.Markdown(ranking_md, visible=ranking_vis),
                 ]
             )
 
+        # Define UI components for the rest of the states, state for showing basic text to the user
         else:
             output.extend(
                 [
@@ -338,23 +450,31 @@ with gr.Blocks() as demo:
                     gr.Markdown(visible=False),
                 ]
             )
+
+        # Return the output components
         return output
 
+    # Define the UI layout for the gam
     img = gr.Image(logo_path, height=430, interactive=False, visible=True)
     ranking = gr.Markdown(visible=False)
 
     with gr.Row():
         out = gr.Textbox(visible=False, placeholder=Config[list(Config.keys())[0]])
         hint_out = gr.Textbox(visible=False)
+
     radio = gr.Radio(visible=False)
+
     with gr.Row():
         inp = gr.Textbox(visible=False, interactive=True, label="")
         but = gr.Button(Menu["Start"])
         give_up = gr.Button("Pista", visible=False)
         reload = gr.Button(Menu["Play_again"], visible=False)
 
+    # Define the settings components for the game
     with gr.Accordion("Configuración/Settings", open=False):
         with gr.Row():
+
+            # Dropdown to select the model engine for the game
             model = (
                 gr.Dropdown(
                     ["Sentence Transformers", "Word2Vec"],
@@ -362,12 +482,17 @@ with gr.Blocks() as demo:
                     label="Embedding Model",
                 ),
             )
+
+            # Dropdown to select the language for the game
             lang = (
                 gr.Dropdown(
                     ["Español", "English"], value="Español", label="Idioma/Language"
                 ),
             )
 
+    # Define the UI events for the game
+
+    # Define events that trigger the game state change
     inp.submit(change, inputs=[state, inp], outputs=[state, inp])
     but.click(change, inputs=[state, inp], outputs=[state, inp])
     give_up.click(
@@ -380,6 +505,7 @@ with gr.Blocks() as demo:
     )
     radio.input(change, inputs=[state, inp], outputs=[state, inp])
 
+    # Define events that trigger the game reset
     reload.click(
         reset,
         inputs=[difficulty, lang[0], model[0]],
@@ -401,6 +527,7 @@ with gr.Blocks() as demo:
         outputs=[state, out, inp, img, but, radio, hint_out, reload, header],
     )
 
+    # Define events that trigger the game state update
     state.change(
         update,
         inputs=[state, radio, inp, hint],

data/ranking.txt

@@ -1,5 +1,10 @@
-['#3', 'dfsdffdf', 3.96]
+['#8', 'medium', 6.94]
 ---------------------------
-['#1', 'amigo', 6.48]
-['#2', 'loco', 5.79]
-['#3', 'dfsdffdf', 3.96]
+['#1', 'amigo', 8.3]
+['#2', 'loco', 7.64]
+['#7', 'fantasma', 7.41]
+['#8', 'medium', 6.94]
+['#4', 'hermano', 6.81]
+['#5', 'duelo', 5.76]
+['#3', 'familia', 4.88]
+['#6', 'divorcio', 1.67]

game_word2vec.py → game.py

@@ -1,4 +1,41 @@
-# %%
+"""
+Semantrix Game Module
+
+This module defines the Semantrix class, which implements a word guessing game using word embeddings. The game can be configured to use either a Word2Vec model or a SentenceTransformer model for word embeddings. The game supports multiple languages and difficulty levels.
+
+Classes:
+    Semantrix: A class that implements the Semantrix word guessing game.
+    Semantrix.DictWrapper: A helper class to wrap configuration dictionaries.
+
+Functions:
+    __init__(self, lang=0, model_type="SentenceTransformer"): Initializes the Semantrix game with the specified language and model type.
+    prepare_game(self, difficulty): Prepares the game with the selected difficulty level.
+    gen_rank(self, repeated): Generates the ranking file based on the scores.
+    play_game(self, word): Plays the game with the selected word and returns feedback.
+    curiosity(self): Generates a curiosity hint about the secret word once the game is over.
+
+Attributes:
+    model (KeyedVectors): The word embeddings model.
+    config_file_path (str): Path to the configuration file.
+    secret_file_path (str): Path to the secret words file.
+    data_path (str): Path to the data directory.
+    Config_full (dict): Full configuration data.
+    secret (dict): Secret words data.
+    lang (int): Language of the game (0 for Spanish, 1 for English).
+    model_type (str): Type of the model ("word2vec" or "SentenceTransformer").
+    Config (DictWrapper): Configuration data for the selected language.
+    secret_dict (dict): Secret words for the selected language.
+    secret_list (list): List of secret words for the selected difficulty.
+    words (list): List of words guessed by the player.
+    scores (list): List of scores for the guessed words.
+    win (bool): Indicates if the player has won the game.
+    n (int): Number of hints given.
+    recent_hint (int): Counter for recent hints.
+    f_dev_avg (float): Moving average of the tendency slope.
+    last_hint (int): Index of the last hint given.
+    difficulty (int): Difficulty level of the game.
+"""
+
 import json
 import random
 from datetime import datetime
@@ -15,65 +52,102 @@ import warnings
 warnings.filterwarnings(action="ignore", category=UserWarning, module="gensim")
 
 
+# Define the class Semantrix
 class Semantrix:
 
-    model_st = SentenceTransformer(
-        "sentence-transformers/paraphrase-multilingual-mpnet-base-v2"
-    )
+    # Create empty KeyedVectors model with predefined size where the embeddings will be stored
+    model = KeyedVectors(768)
 
+    # Define the paths for the configuration files and the data
     config_file_path = "config/lang.json"
-
     secret_file_path = "config/secret.json"
-
     data_path = "data/"
 
+    # Define the class DictWrapper to store the configuration data
     class DictWrapper:
         def __init__(self, data_dict):
             self.__dict__.update(data_dict)
 
-    def __init__(self, lang=0):
-
-        self.lang = lang
-
-        self.embeddings_dict = {}
+    # Define the constructor of the class which loads the configuration files and initializes the class variables depending on the language parameter and the model type
+    def __init__(self, lang=0, model_type="SentenceTransformer"):
 
+        # Load the configuration files
         with open(self.config_file_path, "r") as file:
             self.Config_full = json.load(file)
 
+        # Load the secret file where the secret words are stored
         with open(self.secret_file_path, "r") as file:
             self.secret = json.load(file)
 
+        # Set the language of the game
+        self.lang = lang
+
+        # Set the model type
+        self.model_type = model_type
+
+        # Load word2vec model if needed
+        if self.model_type == "word2vec":
+            if self.lang == 1:
+                self.model = KeyedVectors.load(
+                    "config/w2v_models/eng_w2v_model", mmap="r"
+                )
+                self.Config = self.DictWrapper(self.Config_full["ENG"]["Game"])
+                self.secret_dict = self.secret["ENG"]
+            else:
+                self.model = KeyedVectors.load(
+                    "config/w2v_models/esp_w2v_model", mmap="r"
+                )
+                self.Config = self.DictWrapper(self.Config_full["SPA"]["Game"])
+                self.secret_dict = self.secret["SPA"]
+        else:
+            self.model_st = SentenceTransformer(
+                "sentence-transformers/paraphrase-multilingual-mpnet-base-v2"
+            )
+
+        # Set the configuration variables depending on the language
         if self.lang == 1:
-            self.model = KeyedVectors.load("config/w2v_models/eng_w2v_model", mmap="r")
             self.Config = self.DictWrapper(self.Config_full["ENG"]["Game"])
             self.secret_dict = self.secret["ENG"]
         else:
-            self.model = KeyedVectors.load("config/w2v_models/esp_w2v_model", mmap="r")
             self.Config = self.DictWrapper(self.Config_full["SPA"]["Game"])
             self.secret_dict = self.secret["SPA"]
 
+        # Create the ranking file
         with open(self.data_path + "ranking.txt", "w+") as file:
             file.write("---------------------------")
 
+    # Define the function to prepare the game with the selected difficulty
     def prepare_game(self, difficulty):
 
+        # Set the secret list depending on the difficulty
         self.secret_list = (
             self.secret_dict["basic"]
             if difficulty <= 2
             else self.secret_dict["advanced"]
         )
 
+        # Select a random secret word from the secret list
         self.secret = self.secret_list.pop(random.randint(0, len(self.secret_list) - 1))
         self.secret = self.secret.lower()
 
+        # Store the secret word in the words list
         self.words = [self.Config.secret_word]
+
+        # Store the score in the scores list
         self.scores = [10]
 
-        if self.secret not in self.embeddings_dict.keys():
-            self.embeddings_dict[self.secret] = self.model[self.secret]
+        # Store the embedding of the secret word in the embeddings dictionary
+        if self.secret not in self.model.key_to_index.keys():
 
-        self.word_vect = [self.embeddings_dict[self.secret].tolist()]
+            # Add the secret word to the KeyedVectors model if the model type is SentenceTransformer
+            # If the model type is word2vec, the secret word is already in the model
+            if self.model_type == "SentenceTransformer":
+                self.model.add_vector(
+                    self.secret,
+                    self.model_st.encode(self.secret, convert_to_tensor=True).tolist(),
+                )
 
+        # Initialize the game variables
         self.win = False
         self.n = 0
         self.recent_hint = 0
@@ -81,10 +155,12 @@ class Semantrix:
         self.last_hint = -1
         self.difficulty = difficulty
 
+        # Set the number of hints depending on the difficulty
         if self.difficulty == 1:
             self.n = 3
 
-    def preproc_vectors(self, repeated):
+    # Define the function to generate the ranking file
+    def gen_rank(self, repeated):
         ascending_indices = np.argsort(self.scores)
         descending_indices = list(ascending_indices[::-1])
         ranking_data = []
@@ -104,9 +180,13 @@ class Semantrix:
             for item in ranking_data:
                 file.write("%s\n" % item)
 
+    # Define the function to play the game with the selected word
     def play_game(self, word):
 
+        # Convert the word to lowercase
         word = word.lower()
+
+        # Check if the user wants to give up
         if word == "give_up":
             text = (
                 "[lose]"
@@ -117,14 +197,22 @@ class Semantrix:
             )
             return text
 
+        # Check if the word is repeated
         if word in self.words:
             repeated = self.words.index(word)
         else:
             repeated = -1
             self.words.append(word)
 
-        if word not in self.embeddings_dict.keys():
-            if word not in self.model.key_to_index.keys():
+        # Check if the word is in the model already
+        if word not in self.model.key_to_index.keys():
+            # Add the word to the KeyedVectors model if the model type is SentenceTransformer
+            if self.model_type == "SentenceTransformer":
+                self.model.add_vector(
+                    word, self.model_st.encode(word, convert_to_tensor=True).tolist()
+                )
+            else:
+                # If the word is not in the model when using word2vec, remove it from the words list and provide feedback
                 self.words.pop(len(self.words) - 1)
                 feedback = (
                     "I don't know that word. Try again."
@@ -136,18 +224,23 @@ class Semantrix:
                     if len(self.words) > 1
                     else "\n\n"
                 )
-
                 return feedback
 
-            embedding = self.model[word]
-            self.embeddings_dict[word] = embedding
-
-        score = round(self.model.similarity(self.secret, word) * 10, 2)
+        # Calculate the score of the word, apply logarithmic scaling, interpolate the score to a range from 0 to 10, and round it to two decimal places
+        score = round(
+            np.interp(
+                np.log(self.model.similarity(self.secret, word) * 10),
+                [0, np.log(10)],
+                [0, 10],
+            ),
+            2,
+        )
 
+        # Remove the word from the score list if it is repeated
         if repeated == -1:
-            self.word_vect.append(self.embeddings_dict[word].tolist())
             self.scores.append(score)
 
+        # Generate the feedback message depending on the score
         if score <= 2.5:
             feedback = self.Config.Feedback_0 + str(score)
         elif score > 2.5 and score <= 4.0:
@@ -160,28 +253,38 @@ class Semantrix:
             feedback = self.Config.Feedback_4 + str(score)
         elif score > 8.0 and score < 10.0:
             feedback = self.Config.Feedback_5 + str(score)
+        # If the score is 10, the user wins the game
         else:
             self.win = True
             feedback = "[win]" + self.Config.Feedback_8
             self.words[0] = self.secret
             self.words.pop(len(self.words) - 1)
-            self.word_vect.pop(len(self.word_vect) - 1)
             self.scores.pop(len(self.scores) - 1)
 
+        # Generate the feedback message depending on the score and the previous score
         if score > self.scores[len(self.scores) - 2] and self.win == False:
             feedback += "\n" + self.Config.Feedback_6
         elif score < self.scores[len(self.scores) - 2] and self.win == False:
             feedback += "\n" + self.Config.Feedback_7
 
+        ## Hint generation
+        # If the difficulty is not 4, calculate the moving average of the scores and the tendency slope
         if self.difficulty != 4:
             mov_avg = calculate_moving_average(self.scores[1:], 5)
 
+            # If the moving average has more than one element and the user has not won yet, calculate the tendency slope and the moving average of the tendency slope
             if len(mov_avg) > 1 and self.win == False:
                 f_dev = calculate_tendency_slope(mov_avg)
                 f_dev_avg = calculate_moving_average(f_dev, 3)
+
+                # If the tendency slope is negative and the hint has not been given recently (at least three rounds earlier), generate a hint
                 if f_dev_avg[len(f_dev_avg) - 1] < 0 and self.recent_hint == 0:
+
+                    # Generate a random hint intro from the hint list
                     i = random.randint(0, len(self.Config.hint_intro) - 1)
                     feedback += "\n\n[hint]" + self.Config.hint_intro[i]
+
+                    # Generate a dynamic hint
                     hint_text, self.n, self.last_hint = hint(
                         self.secret,
                         self.n,
@@ -200,26 +303,30 @@ class Semantrix:
             if self.recent_hint != 0:
                 self.recent_hint -= 1
 
-        self.preproc_vectors(repeated)
+        # Generate the ranking file
+        self.gen_rank(repeated)
 
+        # Add the ranking file to the feedback message
         feedback += "[rank]" + open(self.data_path + "ranking.txt", "r").read()
 
-        if self.win:
-            bold_display = 0
-
+        # Save the ranking file with the plays of the user if the user wins
         if self.win:
 
             with open(self.data_path + "ranking.txt", "r") as original_file:
                 file_content = original_file.readlines()
 
             new_file_name = self.secret + "_" + str(datetime.now()) + ".txt"
+
             with open(self.data_path + "plays/" + new_file_name, "w+") as new_file:
                 new_file.writelines(file_content[2:])
 
+        # Return the feedback message
         return feedback
 
+    # Define the function to generate a curiosity hint once the game is over
     def curiosity(self):
 
+        # Generate a curiosity aboyt the secret word
         feedback = curiosity(
             self.secret,
             (
@@ -229,4 +336,5 @@ class Semantrix:
             ),
         )
 
+        # Return the feedback message
         return feedback

game_transformer.py

@@ -1,228 +0,0 @@
-# %%
-import json
-import re
-import random
-from datetime import datetime
-import numpy as np
-from gensim.models import KeyedVectors
-from hints import curiosity, hint
-from tracking import (
-    calculate_moving_average,
-    calculate_tendency_slope,
-)
-from sentence_transformers import SentenceTransformer
-import warnings
-
-warnings.filterwarnings(action="ignore", category=UserWarning, module="gensim")
-
-
-class Semantrix:
-    model = KeyedVectors(768)
-    model_st = SentenceTransformer(
-        "sentence-transformers/paraphrase-multilingual-mpnet-base-v2"
-    )
-
-    config_file_path = "config/lang.json"
-    secret_file_path = "config/secret.json"
-    data_path = "data/"
-
-    class DictWrapper:
-        def __init__(self, data_dict):
-            self.__dict__.update(data_dict)
-
-    def __init__(self, lang=0):
-
-        self.embeddings_dict = {}
-
-        with open(self.config_file_path, "r") as file:
-            self.Config_full = json.load(file)
-
-        with open(self.secret_file_path, "r") as file:
-            self.secret = json.load(file)
-
-        self.lang = lang
-
-        if self.lang == 1:
-            self.Config = self.DictWrapper(self.Config_full["ENG"]["Game"])
-            self.secret_dict = self.secret["ENG"]
-        else:
-            self.Config = self.DictWrapper(self.Config_full["SPA"]["Game"])
-            self.secret_dict = self.secret["SPA"]
-
-        with open(self.data_path + "ranking.txt", "w+") as file:
-            file.write("---------------------------")
-
-    def prepare_game(self, difficulty):
-
-        self.secret_list = (
-            self.secret_dict["basic"]
-            if difficulty <= 2
-            else self.secret_dict["advanced"]
-        )
-
-        self.secret = self.secret_list.pop(random.randint(0, len(self.secret_list) - 1))
-        self.secret = self.secret.lower()
-
-        self.words = [self.Config.secret_word]
-        self.scores = [10]
-
-        if self.secret not in self.embeddings_dict.keys():
-            self.embeddings_dict[self.secret] = self.model_st.encode(
-                self.secret, convert_to_tensor=True
-            )
-            self.model.add_vector(
-                self.secret, self.embeddings_dict[self.secret].tolist()
-            )
-
-        self.word_vect = [self.embeddings_dict[self.secret].tolist()]
-
-        self.win = False
-        self.n = 0
-        self.recent_hint = 0
-        self.f_dev_avg = 0
-        self.last_hint = -1
-        self.difficulty = difficulty
-
-        if self.difficulty == 1:
-            self.n = 3
-
-    def preproc_vectors(self, repeated):
-        ascending_indices = np.argsort(self.scores)
-        descending_indices = list(ascending_indices[::-1])
-        ranking_data = []
-        k = len(self.words) - 1
-        if repeated != -1:
-            k = repeated
-
-        ranking_data.append(["#" + str(k), self.words[k], self.scores[k]])
-
-        ranking_data.append("---------------------------")
-        for i in descending_indices:
-            if i == 0:
-                continue
-            ranking_data.append(["#" + str(i), self.words[i], self.scores[i]])
-
-        with open(self.data_path + "ranking.txt", "w+") as file:
-            for item in ranking_data:
-                file.write("%s\n" % item)
-
-    def play_game(self, word):
-
-        word = word.lower()
-        if word == "give_up":
-            text = (
-                "[lose]"
-                + self.Config.Feedback_9
-                + self.secret
-                + "\n\n"
-                + self.Config.Feedback_10
-            )
-            return text
-
-        if word in self.words:
-            repeated = self.words.index(word)
-        else:
-            repeated = -1
-            self.words.append(word)
-
-        if word not in self.embeddings_dict.keys():
-            embedding = self.model_st.encode(word, convert_to_tensor=True)
-            self.embeddings_dict[word] = embedding
-            self.model.add_vector(word, embedding.tolist())
-
-        score = round(
-            np.interp(
-                np.log(self.model.similarity(self.secret, word) * 10),
-                [0, np.log(10)],
-                [0, 10],
-            ),
-            2,
-        )
-
-        if repeated == -1:
-            self.word_vect.append(self.embeddings_dict[word].tolist())
-            self.scores.append(score)
-
-        if score <= 2.5:
-            feedback = self.Config.Feedback_0 + str(score)
-        elif score > 2.5 and score <= 4.0:
-            feedback = self.Config.Feedback_1 + str(score)
-        elif score > 4.0 and score <= 6.0:
-            feedback = self.Config.Feedback_2 + str(score)
-        elif score > 6.0 and score <= 7.5:
-            feedback = self.Config.Feedback_3 + str(score)
-        elif score > 7.5 and score <= 8.0:
-            feedback = self.Config.Feedback_4 + str(score)
-        elif score > 8.0 and score < 10.0:
-            feedback = self.Config.Feedback_5 + str(score)
-        else:
-            self.win = True
-            feedback = "[win]" + self.Config.Feedback_8
-            self.words[0] = self.secret
-            self.words.pop(len(self.words) - 1)
-            self.word_vect.pop(len(self.word_vect) - 1)
-            self.scores.pop(len(self.scores) - 1)
-
-        if score > self.scores[len(self.scores) - 2] and self.win == False:
-            feedback += "\n" + self.Config.Feedback_6
-        elif score < self.scores[len(self.scores) - 2] and self.win == False:
-            feedback += "\n" + self.Config.Feedback_7
-
-        if self.difficulty != 4:
-            mov_avg = calculate_moving_average(self.scores[1:], 5)
-
-            if len(mov_avg) > 1 and self.win == False:
-                f_dev = calculate_tendency_slope(mov_avg)
-                f_dev_avg = calculate_moving_average(f_dev, 3)
-                if f_dev_avg[len(f_dev_avg) - 1] < 0 and self.recent_hint == 0:
-                    i = random.randint(0, len(self.Config.hint_intro) - 1)
-                    feedback += "\n\n[hint]" + self.Config.hint_intro[i]
-                    hint_text, self.n, self.last_hint = hint(
-                        self.secret,
-                        self.n,
-                        self.model_st,
-                        self.last_hint,
-                        self.lang,
-                        (
-                            self.DictWrapper(self.Config_full["ENG"]["Hint"])
-                            if self.lang == 1
-                            else self.DictWrapper(self.Config_full["SPA"]["Hint"])
-                        ),
-                    )
-                    feedback += "\n" + hint_text
-                    self.recent_hint = 3
-
-            if self.recent_hint != 0:
-                self.recent_hint -= 1
-
-        self.preproc_vectors(repeated)
-
-        feedback += "[rank]" + open(self.data_path + "ranking.txt", "r").read()
-
-        if self.win:
-            bold_display = 0
-
-        if self.win:
-
-            with open(self.data_path + "ranking.txt", "r") as original_file:
-                file_content = original_file.readlines()
-
-            new_file_name = self.secret + "_" + str(datetime.now()) + ".txt"
-
-            with open(self.data_path + "plays/" + new_file_name, "w+") as new_file:
-                new_file.writelines(file_content[2:])
-
-        return feedback
-
-    def curiosity(self):
-
-        feedback = curiosity(
-            self.secret,
-            (
-                self.DictWrapper(self.Config_full["ENG"]["Hint"])
-                if self.lang == 1
-                else self.DictWrapper(self.Config_full["SPA"]["Hint"])
-            ),
-        )
-
-        return feedback

hints.py

@@ -1,24 +1,60 @@
-import json
-import os
-import random
+"""
+This module provides functions to generate dynamic hints and curiosities about a secret word using llms.
+
+Functions:
+    hint(secret, n, model, last_hint, lang, Config):
+        Generates a dynamic hint based on the secret word and the number of hints given.
+        Parameters:
+            secret (str): The secret word.
+            n (int): The number of hints already given.
+            model: The sentence transformer model used for encoding.
+            last_hint (int): The index of the last hint given.
+            lang (int): The language code (0 for Spanish, 1 for English).
+            Config: Configuration object containing hint templates.
+        Returns:
+            tuple: A tuple containing the generated hint (str), the updated number of hints (int), and the index of the last hint given (int).
+
+    curiosity(secret, Config):
+        Generates a curiosity about the secret word.
+        Parameters:
+            secret (str): The secret word.
+            Config: Configuration object containing the curiosity template.
+        Returns:
+            str: The generated curiosity.
 
+    ireplace(old, new, text):
+        Replaces all occurrences of a substring in a string, case-insensitively.
+        Parameters:
+            old (str): The substring to be replaced.
+            new (str): The substring to replace with.
+            text (str): The original string.
+        Returns:
+            str: The modified string with all occurrences of the old substring replaced by the new substring.
+"""
+
+import random
 import openai
 from sentence_transformers import util
 
-openai.api_key = os.getenv("OPENAI_API_KEY")
+gpt_model = "gpt-3.5-turbo"
+
 
+# Dynamic hint function that returns a hint based on the secret word and the number of hints given
+def hint(secret, n, model, last_hint, lang, Config):
 
-def hint(secret, n, model, last_pista, lang, Config):
-    pista = ""
+    # Initialize hint variable
+    hint = ""
 
-    # Pistas avanzadas
+    # Advanced hints
     if n >= 3:
         j = random.randint(0, 2)
-        while j == last_pista:
+        while j == last_hint:
             j = random.randint(0, 2)
+
+        # Advanced hint 1: Definition of the secret word
         if j == 0:
             response = openai.chat.completions.create(
-                model="gpt-3.5-turbo",
+                model=gpt_model,
                 messages=[
                     {
                         "role": "user",
@@ -38,6 +74,7 @@ def hint(secret, n, model, last_pista, lang, Config):
             output = str(response.choices[0].message.content)
             output = output.replace('"', "").replace("'", "")
 
+            # Replace the secret word with "La palabra secreta" or "The secret word" just in case the model uses the secret word in the definition
             if lang == 0:
                 output = ireplace("la " + secret, "La palabra secreta", output)
                 output = ireplace("las " + secret, "La palabra secreta", output)
@@ -51,11 +88,13 @@ def hint(secret, n, model, last_pista, lang, Config):
                 output = ireplace("the " + secret, "The secret word", output)
                 output = ireplace("a " + secret, "The secret word", output)
 
-            pista += Config.hint_0_3 + output  # type: ignore
-            last_pista = 0
+            hint += Config.hint_0_3 + output  # type: ignore
+            last_hint = 0
+
+        # Advanced hint 2: Representation of the secret word with emojis
         elif j == 1:
             response = openai.chat.completions.create(
-                model="gpt-3.5-turbo",
+                model=gpt_model,
                 messages=[
                     {
                         "role": "user",
@@ -69,11 +108,13 @@ def hint(secret, n, model, last_pista, lang, Config):
                 presence_penalty=0,
             )
             output = str(response.choices[0].message.content)
-            pista += Config.hint_1_2 + output  # type: ignore
-            last_pista = 1
+            hint += Config.hint_1_2 + output  # type: ignore
+            last_hint = 1
+
+        # Advanced hint 3: Poem about the secret word
         elif j == 2:
             response = openai.chat.completions.create(
-                model="gpt-3.5-turbo",
+                model=gpt_model,
                 messages=[
                     {
                         "role": "user",
@@ -88,18 +129,20 @@ def hint(secret, n, model, last_pista, lang, Config):
             )
             output = str(response.choices[0].message.content)
 
-            pista += Config.hint_2_2 + output  # type: ignore
+            hint += Config.hint_2_2 + output  # type: ignore
 
-            last_pista = 2
-    # Pistas iniciales
+            last_hint = 2
+    # Initial hints
     else:
         j = random.randint(3, 4)
-        while j == last_pista:
+        while j == last_hint:
             j = random.randint(3, 4)
+
+        # Initial hint 1: Rank of four words related to the secret word
         if j == 3:
             words = []
             response = openai.chat.completions.create(
-                model="gpt-3.5-turbo",
+                model=gpt_model,
                 messages=[
                     {
                         "role": "user",
@@ -116,7 +159,7 @@ def hint(secret, n, model, last_pista, lang, Config):
             output = (output.replace(" ", "").replace(".", "")).lower()
             words.extend(output.strip().split(","))
             response = openai.chat.completions.create(
-                model="gpt-3.5-turbo",
+                model=gpt_model,
                 messages=[
                     {
                         "role": "user",
@@ -145,7 +188,7 @@ def hint(secret, n, model, last_pista, lang, Config):
             sum_scores = sum(scores)
             normalized_scores = [round(score * 100 / sum_scores, 1) for score in scores]
 
-            pista += Config.hint_3_3  # type: ignore
+            hint += Config.hint_3_3  # type: ignore
 
             max_len = -1
             for ele in words:
@@ -156,19 +199,21 @@ def hint(secret, n, model, last_pista, lang, Config):
             for i in range(len(words)):
 
                 word_hint = words[i].ljust(len(longest_word) + 1)
-                pista += (
+                hint += (
                     # word_hint[: len(longest_word)]
                     word_hint
                     + "|"
-                    + ("🟩") * round(normalized_scores[i] * 0.1)
+                    + ("🟩") * round(normalized_scores[i] * 0.2)
                     + " "
                     + str(normalized_scores[i])
                     + "%\n"
                 )
-            last_pista = 3
+            last_hint = 3
+
+        # Initial hint 2: Film representation with emojis with the secret word
         elif j == 4:
             response = openai.chat.completions.create(
-                model="gpt-3.5-turbo",
+                model=gpt_model,
                 messages=[
                     {
                         "role": "user",
@@ -185,7 +230,7 @@ def hint(secret, n, model, last_pista, lang, Config):
             )
             film_title = str(response.choices[0].message.content).replace('"', "")
             response = openai.chat.completions.create(
-                model="gpt-3.5-turbo",
+                model=gpt_model,
                 messages=[
                     {
                         "role": "user",
@@ -201,16 +246,17 @@ def hint(secret, n, model, last_pista, lang, Config):
                 presence_penalty=0,
             )
             output = str(response.choices[0].message.content)
-            pista += Config.hint_4_4 + "\n" + output  # type: ignore
-            last_pista = 4
+            hint += Config.hint_4_4 + "\n" + output  # type: ignore
+            last_hint = 4
 
-    return pista, n + 1, last_pista
+    return hint, n + 1, last_hint
 
 
+# Tell a curiosity about the secret word
 def curiosity(secret, Config):
 
     response = openai.chat.completions.create(
-        model="gpt-3.5-turbo",
+        model=gpt_model,
         messages=[
             {
                 "role": "user",
@@ -228,6 +274,7 @@ def curiosity(secret, Config):
     return output
 
 
+# Replace all occurrences of a substring in a string
 def ireplace(old, new, text):
     idx = 0
     while idx < len(text):

ranking.txt

@@ -1 +0,0 @@
----------------------------

requirements.txt

@@ -3,5 +3,5 @@ sentence_transformers==2.2.2
 openai==1.2.3
 gradio==5.1.0
 transformers==4.33.2
-huggingface-hub==0.25.2
-python-multipart==0.0.12
+# huggingface-hub==0.25.2
+# python-multipart==0.0.12