docs: 📝 cover repo with wiki pages; expand LLM service docs and add Tokenization

Vincent Scharpen (Darkiron) · Vincent Scharpen (Darkiron) · commit 9fc3a27dc88c · 2025-10-23T15:57:59.000+02:00
diff --git a/docs/wiki/Backend-Symfony.md b/docs/wiki/Backend-Symfony.md
@@ -1,8 +1,30 @@
-# Backend (Symfony)
+# Backend — Symfony 🔙
 
-See detailed notes in repo: ../../docs/services/symfony-back.md
+Notes spécifiques au backend Symfony. Pour des détails d'implémentation, voir le code sous apps/symfony-back.
 
-Key points
-- API and domain logic are implemented in apps/symfony-back.
-- Important classes: Prompt, LLMGateway, GenerateStreamUseCase, LLMController.
-- Run locally with Symfony CLI or PHP built-in server.
+## LLMGateway — Client Python LLM
+- Implémentation: `apps/symfony-back/src/Infrastructure/LLM/PythonLLMClient.php`
+- Rôle: émettre une requête HTTP POST vers l'endpoint du service LLM et consommer une réponse en streaming.
+- URL par défaut: `llm_url` (paramètre Symfony) ou variable d'env `LLM_URL`; fallback: `http://llm:8008/generate/stream`.
+
+Extrait important:
+- Streaming via `HttpClientInterface` avec `buffer: false` puis itération avec `$this->httpClient->stream($response)`.
+- Les chunks sont relayés tels quels au consommateur (contrôleur/cas d'usage) pour un flux temps réel.
+
+## Configuration
+- Voir `compose.yaml` -> service `symfony-back`:
+  - `LLM_URL` et `LLM_METRICS_URL` injectés via env.
+- Paramétrage côté Symfony (parameters, services) pour `llm_url`.
+
+## Cas d'usage & contrôleurs
+- Domaine: `src/Domain/Model/Prompt.php`, `src/Domain/Port/LLMGateway.php`
+- Application: `src/Application/UseCase/GenerateStreamUseCase.php`
+- Interface: `src/Controller/LLMController.php`
+
+## Dépannage
+- 502/timeout en streaming: vérifier l'URL LLM, que le conteneur `llm` tourne, et aucun proxy n'interrompt la connexion.
+- CORS/front: s'assurer que le contrôleur renvoie les en-têtes nécessaires selon le front.
+
+Voir aussi:
+- [LLM-Service-Python](LLM-Service-Python) — endpoint attendu et métriques 🧠
+- [Architecture](Architecture) — flux entre services 🗺️
diff --git a/docs/wiki/Environment.md b/docs/wiki/Environment.md
@@ -1,9 +1,25 @@
-# Environment 🌱
+# Environment 🔑
 
-See repository details : ../env.md 🔗
+Variables d'environnement et configuration. Pour le détail complet, voir ../env.md.
 
-## Highlights ✨
-- 🚫 Never commit secrets (`.env.local`, `.env.dev` ignored where configured).
-- Symfony : `APP_SECRET`, `DATABASE_URL`
-- Laravel : `APP_KEY`, `APP_URL`
-- Python LLM : model/config paths, ports
+## Backend (Symfony)
+- LLM_URL: URL de génération/stream attendue (défaut: http://llm:8008/generate/stream)
+- LLM_METRICS_URL: URL des métriques du service LLM (ex.: http://llm:9108/metrics)
+
+Ces valeurs peuvent être définies via:
+- Paramètres Symfony (parameters.yaml) et/ou
+- Variables d'environnement (voir compose.yaml -> service symfony-back)
+
+## Service LLM (Python)
+- CKPT_PATH: chemin du checkpoint (ex.: /ckpts/rnn.pt)
+- METRICS_PORT: port d'exposition des métriques (défaut: 9108)
+- PYTHONPATH: inclut /app/apps/python-llm pour la CLI et les modules
+
+## Docker Compose (extraits utiles)
+Voir compose.yaml:
+- Volumes: ./ckpts:/ckpts, ./data:/data, ./apps/python-llm:/app/apps/python-llm
+- Ports: 80->java gateway, 8081->laravel-front, 8082->symfony-back, 9108->llm metrics
+
+Voir aussi:
+- [Setup](Setup) — démarrage rapide 🐳
+- [LLM-Service-Python](LLM-Service-Python) — détails service et API 🧠
diff --git a/docs/wiki/Frontend-Laravel.md b/docs/wiki/Frontend-Laravel.md
@@ -1,8 +1,21 @@
-# Frontend (Laravel)
+# Frontend — Laravel 🌐
 
-See detailed notes in repo: ../../docs/services/laravel-front.md
+Notes spécifiques au frontend Laravel (apps/laravel-front).
 
-Key points
-- UI built with Laravel in apps/laravel-front.
-- Ensure APP_KEY and .env are configured.
-- Run locally with php artisan serve.
+## Démarrage en dev
+- Servi par le conteneur `laravel-front` (voir compose.yaml):
+  - Commande: artisan serve sur 0.0.0.0:8080 (via script de démarrage).
+  - Port exposé par compose: 8081 -> 8080
+- Code monté en volume: `./apps/laravel-front:/var/www/html`
+
+## Communication avec le backend
+- Cible par défaut du backend selon compose: http://symfony-back:8080 (interne réseau Docker) — l'exposition hôte est http://localhost:8082
+- Configurer l'URL API côté front selon vos conventions (env/config).
+
+## Débogage rapide
+- Erreurs 404/500: vérifier les routes Laravel et la correspondance avec les endpoints du backend.
+- CORS: ajuster les en-têtes côté backend si nécessaire.
+
+Voir aussi:
+- [Backend-Symfony](Backend-Symfony) — endpoints et streaming 🔙
+- [Architecture](Architecture) — flux entre UI/API/LLM 🗺️
diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md
@@ -10,6 +10,7 @@ Bienvenue ! Cette documentation vous guide à travers l’architecture, l’ins
 - [Backend-Symfony](Backend-Symfony) — Notes backend Symfony
 - [Frontend-Laravel](Frontend-Laravel) — Notes frontend Laravel
 - [LLM-Service-Python](LLM-Service-Python) — Notes sur le service Python LLM
+- [Tokenization](Tokenization) — Modes byte/legacy/BPE et bonnes pratiques 🔤
 - [LLM RNN CLI](LLM-RNN-CLI) — Générer du texte via docker compose exec et llm_rnn.generate
 - [Ops-Deployment](Ops-Deployment) — Considérations de déploiement
 - [Troubleshooting](Troubleshooting) — Problèmes courants et correctifs
diff --git a/docs/wiki/LLM-Service-Python.md b/docs/wiki/LLM-Service-Python.md
@@ -1,7 +1,51 @@
-# LLM Service (Python)
+# LLM Service (Python) 🧠
 
-See detailed notes in repo: ../../docs/services/python-llm.md
+Notes sur le service LLM Python. Pour les détails approfondis, consulter aussi: ../../docs/services/python-llm.md
 
-Key points
-- Provides LLM capabilities consumed by the backend.
-- Prefer running via Docker Compose for consistency.
+## Rôle
+- Fournit des capacités de génération de texte (consommées par le backend Symfony).
+- Expose des métriques Prometheus pour l'observabilité.
+- S'exécute en local via Docker Compose pour une cohérence d'environnement.
+
+## API HTTP attendue par le backend
+- Endpoint: `POST /generate/stream`
+- URL par défaut côté backend: `http://llm:8008/generate/stream`
+  - Configurable via `LLM_URL` (compose/env) ou paramètre Symfony `llm_url`.
+- Client côté Symfony: `apps/symfony-back/src/Infrastructure/LLM/PythonLLMClient.php`
+  - Utilise le streaming (HttpClientInterface avec `buffer: false`).
+
+Remarque: l'implémentation HTTP de l'endpoint n'est pas incluse dans les extraits visibles ici; assurez-vous que le service LLM répond bien sur ce chemin si utilisé en production.
+
+## CLI — Génération rapide
+- Voir [LLM RNN CLI](LLM-RNN-CLI) pour générer du texte directement dans le conteneur `llm`.
+- Entrée: `python -m llm_rnn.generate` avec options `--ckpt`, `--seed`, `--chars`, `--temp`, `--top-k`, `--top-p`.
+
+## Tokenization
+- Modes pris en charge: byte-level (par défaut), legacy char-level, BPE.
+- Détails: [Tokenization](Tokenization) (modes, heuristiques, encode/decode).
+
+## Métriques Prometheus
+- Exposées par `services/llm/metrics_server.py` sur `/metrics`.
+- Port par défaut: `METRICS_PORT=9108` (voir compose.yaml -> service `llm`).
+- Exemple local: http://localhost:9108/metrics
+
+## Supervisor (processus)
+- Fichier: `services/llm/supervisor.py`
+  - Lance le serveur de métriques dans un thread.
+  - Maintient le conteneur vivant via une boucle idle.
+- Commande compose: `python services/llm/supervisor.py`
+
+## Répertoire modèle & checkpoints
+- Volume: `./ckpts` (hôte) monté en `/ckpts` (conteneur).
+- Chemin par défaut du checkpoint: `/ckpts/rnn.pt` (configurable via `CKPT_PATH`).
+
+## Fichiers clés (apps/python-llm)
+- `llm_rnn/generate.py` — CLI de génération (charge le ckpt, choisit le tokenizer, échantillonne via le modèle).
+- `llm_rnn/model.py` — définition du modèle `CharRNN` et logique de sampling.
+- `llm_rnn/tokenizer.py` — tokenizer byte/legacy.
+- `llm_rnn/tokenizer_bpe.py` — tokenizer BPE (si ckpt entraîné avec BPE).
+
+Voir aussi:
+- [LLM RNN CLI](LLM-RNN-CLI)
+- [Backend-Symfony](Backend-Symfony)
+- [Architecture](Architecture)
diff --git a/docs/wiki/Ops-Deployment.md b/docs/wiki/Ops-Deployment.md
@@ -1,8 +1,27 @@
-# Ops / Deployment
+# Ops & Deployment 🚀
 
-See repository details: ../../docs/ops/deployment.md
+Notes d'exploitation et de déploiement. Pour le guide complet, voir ../ops/deployment.md.
 
-Highlights
-- Containerized deployment recommended.
-- Use secret stores for sensitive configuration.
-- CI/CD to build, test, and deploy.
+## Services (compose.yaml)
+- java-gateway (port 80 -> 8080)
+- laravel-front (port 8081 -> 8080)
+- symfony-back (port 8082 -> 8080)
+- llm (metrics 9108 -> 9108)
+
+Volumes clés:
+- ./apps/laravel-front -> /var/www/html
+- ./apps/symfony-back -> /app
+- ./apps/python-llm -> /app/apps/python-llm
+- ./ckpts -> /ckpts
+- ./data -> /data
+
+Env importants:
+- LLM_URL, LLM_METRICS_URL côté backend
+- CKPT_PATH, METRICS_PORT, PYTHONPATH côté LLM
+
+Observabilité:
+- Prometheus peut scrapper le LLM sur http://llm:9108/metrics (ou via l’hôte: http://localhost:9108/metrics)
+
+Voir aussi:
+- [Architecture](Architecture) 🗺️
+- [LLM-Service-Python](LLM-Service-Python) 🧠
diff --git a/docs/wiki/Setup.md b/docs/wiki/Setup.md
@@ -1,9 +1,21 @@
-# Setup
+# Setup ⚙️🐳
 
-For full details see repository docs: ../setup.md
+Cette page résume l'installation locale et renvoie vers la source de vérité détaillée.
 
-Quickstart
-1. Ensure Docker Desktop is installed.
-2. Create env files as needed (see [[Environment]]).
-3. Run: docker compose up -d
-4. Visit the service URLs noted in README.md.
+- Guide complet: ../setup.md
+
+## Démarrage rapide
+- Prérequis: Docker Desktop 4.x+
+- Depuis la racine du dépôt:
+  - Copier/configurer les fichiers d'environnement selon ../env.md
+  - Lancer: `docker compose up -d`
+
+## Services exposés (par défaut)
+- Frontend (Laravel): http://localhost:8081 (la page d'accueil peut aussi être servie via le gateway: http://localhost:80)
+- Backend (Symfony): http://localhost:8082
+- LLM (metrics): http://localhost:9108/metrics
+
+Voir aussi:
+- [Architecture](Architecture) — panorama et flux 🗺️
+- [Environment](Environment) — variables d'environnement 🔑
+- [LLM RNN CLI](LLM-RNN-CLI) — génération locale via Docker 🧠
diff --git a/docs/wiki/Tokenization.md b/docs/wiki/Tokenization.md
@@ -0,0 +1,35 @@
+# Tokenization 🔤
+
+Aperçu des stratégies de tokenisation utilisées par le service LLM Python. Source code: apps/python-llm/llm_rnn.
+
+## Modes pris en charge
+- Byte-level (par défaut) — 0..255
+  - Préserve les accents/UTF‑8 via encodage/décodage bytes.
+  - Implémentation: `llm_rnn/tokenizer.py` (`CharTokenizer` avec `mode="byte"`).
+- Legacy char-level — liste de caractères
+  - Pour compat CKPT anciens; mappe chaque char à un indice.
+  - Hors vocabulaire: `?` si présent, sinon fallback 0.
+- BPE — (si le checkpoint est entraîné avec BPE)
+  - Implémentation: `llm_rnn/tokenizer_bpe.py` (requis par `tokenizer_kind="bpe"`).
+
+## Détection du mode
+- Dans `llm_rnn/generate.py`: le checkpoint charge `config["tokenizer_kind"]` ("bpe" | "byte" | "legacy").
+- Sinon, heuristique via `chars`:
+  - ints -> byte-level
+  - str -> legacy char-level
+
+## API encode/decode
+- encode(str) -> List[int]
+  - byte-level: UTF‑8 -> bytes -> liste 0..255 (errors='replace')
+  - legacy: conversion char->id avec fallback `?`/0
+- decode(List[int]) -> str
+  - byte-level: bytes(...).decode('utf-8', errors='replace')
+  - legacy: join via itos avec fallback `?`
+
+## Bonnes pratiques
+- Vérifier la compatibilité entre le checkpoint et la tokenizer (kind, vocab).
+- En cas d'artefacts de décodage, baisser la température (`--temp`) et confirmer le mode.
+
+Voir aussi:
+- [LLM RNN CLI](LLM-RNN-CLI)
+- [LLM-Service-Python](LLM-Service-Python)
diff --git a/docs/wiki/Troubleshooting.md b/docs/wiki/Troubleshooting.md
@@ -1,9 +1,32 @@
 # Troubleshooting 🛟
 
-See repository details : ../../docs/troubleshooting.md 🔗
+Problèmes courants et correctifs. Voir aussi ../troubleshooting.md pour plus de cas.
 
-## Common items ✅
-- 🐳 Docker ports conflict — adjust compose.yaml or stop conflicting services.
-- ⚠️ Symfony 500 — set APP_SECRET, clear cache, check var/log.
-- 🔑 Laravel APP_KEY — run `php artisan key:generate`.
-- 🔌 LLM not reachable — verify port mapping and URLs.
+## LLM — erreurs fréquentes
+- ModuleNotFoundError: No module named 'llm_rnn'
+  - Exécuter dans le conteneur `llm` (docker compose exec llm …) où PYTHONPATH est défini.
+  - En local, définir `PYTHONPATH=apps/python-llm`.
+- FileNotFoundError: /ckpts/rnn.pt
+  - Vérifier l'existence de `./ckpts/rnn.pt` (hôte) et le volume `./ckpts:/ckpts`.
+  - Ajuster `--ckpt` si nécessaire.
+- Flux interrompu côté backend
+  - Vérifier `LLM_URL` et l'accessibilité de `http://llm:8008/generate/stream` depuis le conteneur `symfony-back`.
+  - Désactiver proxies intermédiaires qui bufferisent le stream.
+
+## Backend (Symfony)
+- Timeout sur requêtes stream
+  - S'assurer que `timeout`=0 côté HttpClient et que l'upstream répond bien par fragments.
+- CORS
+  - Configurer les en-têtes selon le domaine du frontend.
+
+## Frontend (Laravel)
+- 404 sur endpoints API
+  - Vérifier le prefix/base URL et l'exposition du backend (8082).
+
+## Métriques et observabilité
+- LLM metrics: http://localhost:9108/metrics (ou http://llm:9108/metrics entre conteneurs)
+  - Si vide: attendre 1–2s; sinon vérifier `METRICS_PORT` et le supervisor.
+
+Voir aussi:
+- [LLM RNN CLI](LLM-RNN-CLI)
+- [Backend-Symfony](Backend-Symfony)
