From 98559b66aa80c13e9e0f591ada6b131f5f27b370 Mon Sep 17 00:00:00 2001 From: Yohann D'ANELLO Date: Wed, 4 May 2022 21:10:32 +0200 Subject: [PATCH] Add README Signed-off-by: Yohann D'ANELLO --- .gitignore | 1 + README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 README.md diff --git a/.gitignore b/.gitignore index 5494455..5a681d0 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ cemantix-charm .ssh cemantix.txt history/ +*.bin diff --git a/README.md b/README.md new file mode 100644 index 0000000..32e3f40 --- /dev/null +++ b/README.md @@ -0,0 +1,107 @@ +# Cemantix -- Terminal edition + +## Introduction + +Ce jeu est largement inspiré de Cemantix : https://cemantix.herokuapp.com/, +publié par [@enigmathix](https://twitter.com/enigmathix). + +Dans ce jeu, vous devez trouver un mot en faisant des propositions successives, +et une distance vous est donnée, calculée en utilisant +[Word2Vec](https://fr.wikipedia.org/wiki/Word2vec|Word2Vec). Cette distance est une +distance sémantique : deux mots vont être proches s'ils sont relativement +similaires. Par exemple, les mots « identique » et « similaire » ont un taux de +similarité d'environ 54.87 %, selon notre modèle, ce qui est relativement +élevé. + +Pour jouer, il suffit d'ouvrir un terminal et de lancer, pour l'instance +principale : + +```bash +$ ssh -p 2200 cemantix.ynerant.fr +``` + +Un nouveau mot est généré chaque jour à minuit heure de Paris. + + +## Jeu de données + +Le jeu de données provient d'une extraction des pages de Wikipédia France, +que l'on peut trouver ici : https://dumps.wikimedia.org/frwiki/latest/ +Les textes ont été entraînés en utilisant cet utilitaire autour de word2vec : +https://github.com/jind11/word2vec-on-wikipedia + +Un jeu entraîné par mes propres soins (29 avril 2022) peut être trouvé ici : +https://perso.crans.org/ynerant/frwiki.skip.size500.win10.neg15.sample1e-5.min15.bin + +En plus de cet entraînement de données, un dictionnaire de mots admissibles est +utilisé. Il s'agit de la liste des mots qui peuvent servir à fournir un mot +aléatoire, et dans laquelle l'utilisateur⋅rice a le droit de proposer un mot. +Cette liste est restreinte aux lemmes, c'est-à-dire aux racines des mots, en +excluant donc les éventuels verbes conjugués ou mots déclinés au féminin ou au +pluriel. Cette liste est ensuite intersectée avec les mots connus du jeu de +données. Le fichier ``lemmes.txt`` est issu de ce travail de filtrage à +partir des données du site https://grammalecte.net/download.php?prj=fr . + + +## Installation + +Si vous voulez déployer ce serveur chez vous, vous avez besoin des prérequis +suivants : + +* Golang +* Python 3 + * numpy + * scipy + * gensim + +Pour les installer, avec une distribution basée sur Debian ou Ubuntu : + +```bash +$ sudo apt install golang python3-pip python3-numpy python3-scipy +$ sudo pip3 install gensim # Ou installation locale +``` + +Sous Arch Linux : + +```bash +sudo pacman -Sy go python-pip python-numpy python-scipy +sudo pip install gensim # Ou installation locale +yay -Sy python-gensim # Alternative utilisant yay +``` + +Une fois ces quelques dépendances installées, il vous suffit de lancer +``go build`` pour générer le bon binaire. Récupérez le jeu de données +entraînées cité plus haut et placez-le dans le dossier du projet, sans renommer +le fichier. + +Lancez enfin le script ``new_word.py``, qui prend quelques secondes. Cela va +générer un fichier ``cemantix.txt`` en conservant un historique daté dans le +dossier ``history``, qui permettra au serveur de connaître les différents +scores de chaque mot, sans avoir à les recalculer à la volée. + +Enfin, il suffit de lancer le serveur ``./cemantix-charm`` pour lancer le +serveur SSH du jeu. Cela ouvre un serveur SSH sur le port 2200 écoutant sur +toutes les adresses, avec des clés stockées dans un dossier ``.ssh`` créé si ce +n'était pas déjà fait. On peut enfin jouer en lançant +``ssh -p 2200 localhost``. N'hésitez pas à actualiser votre configuration +pare-feu pour permettre d'éventuelles connexions depuis l'extérieur. + +À l'heure actuelle, il n'est pas possible de configurer le serveur, notamment +les adresses et les ports d'écoute. + +Vous pouvez ensuite définir par exemple un cron qui vient appeler le script +``new_word.py`` toutes les nuits, pour redéfinir le nouveau mot à trouver. Il +n'est pas nécessaire de redémarrer le serveur. + + +## Développement + +Le projet est réalisé en Go (sauf la partie traitement des mots qui est faite +en Python), en utilisant beaucoup le framework *BubbleTea* ainsi que +l'intégration SSH *Wish*, de la suite libre [charm.sh](https://charm.sh). + + +## J'ai un problème / une suggestion + +N'hésitez pas à ouvrir un ticket si vous le pouvez, ou à envoyer un mail à +l'adresse ynerant+cemantix@crans.org :)