Add README

Signed-off-by: Yohann D'ANELLO <ynerant@crans.org>

.gitignore

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

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