Add README

Signed-off-by: Yohann D'ANELLO <ynerant@crans.org>
This commit is contained in:
Yohann D'ANELLO 2022-05-04 21:10:32 +02:00
parent c409de8154
commit 98559b66aa
Signed by: ynerant
GPG Key ID: 3A75C55819C8CF85
2 changed files with 108 additions and 0 deletions

1
.gitignore vendored
View File

@ -4,3 +4,4 @@ cemantix-charm
.ssh .ssh
cemantix.txt cemantix.txt
history/ history/
*.bin

107
README.md Normal file
View File

@ -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 :)