README.md

---
title: Semantrix
emoji: 🔠
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 5.1.0
app_file: app.py
pinned: false
license: other
---

# 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.