Merge pull request #5 from mathiscapart/mathiscapart/check-notion-portfolio

Correctifs mobile Safari, script d'arrêt et documentation

Author: mathiscapart

.env.example

@@ -10,3 +10,11 @@ OLLAMA_PORT=11434
 OLLAMA_CHAT_MODEL=qwen3:8b
 OLLAMA_TIMEOUT=60
 CORS_ORIGINS=http://localhost:3000
+
+# Exposition publique (deploy/docker-compose.expose.yml)
+TRAEFIK_DOMAIN=mathiscapart.xyz
+CLOUDFLARE_TUNNEL_TOKEN=a-renseigner-ne-jamais-committer
+
+# Services natifs (valeurs par defaut de deploy/start-natif.ps1)
+TTS_URL=http://127.0.0.1:8001
+TTS_VOIX=estelle

README.md

@@ -1,60 +1,51 @@
 # PortFolio-AI
 
-## Prérequis
-
-- Docker et Docker Compose.
-- [Ollama](https://ollama.com) installé et lancé **nativement sur l'hôte** (pas en conteneur :
-  les wheels ROCm utilisés ne sont disponibles que pour Windows, le GPU AMD ne passe pas
-  vers un conteneur Linux).
-
-Par défaut, Ollama n'écoute que sur `127.0.0.1` et n'est donc pas joignable depuis le
-conteneur `rag`. Pour l'exposer :
-
-1. Définir la variable d'environnement Windows `OLLAMA_HOST=0.0.0.0`, puis redémarrer Ollama.
-2. Autoriser le port `11434` dans le pare-feu Windows.
-
-Sans cette étape, le conteneur `rag` échoue avec des erreurs `connection refused` en
-essayant de joindre Ollama.
-
-## Configuration
-
-Copier `.env.example` en `.env` et ajuster les valeurs si besoin.
-
-## Lancement
-
-```bash
-docker compose up --build
-```
-
-## API
-
-Elle tourne en natif, pas en conteneur :
+Portfolio vocal de Mathis Capart, en ligne sur https://mathiscapart.xyz. Le
+visiteur pose sa question à voix haute ; l'assistant répond avec une copie de la
+voix de Mathis, uniquement à partir de son parcours.
+
+Chaîne : reconnaissance vocale Kyutai (GPU AMD, ROCm) → recherche Qdrant →
+`qwen3:8b` via Ollama → synthèse Pocket TTS. Tout tourne en local sur un homelab
+Windows, exposé par Traefik et un tunnel Cloudflare, sans API d'inférence externe.
+
+## Structure
+
+| Dossier | Contenu |
+|---|---|
+| `backend/api/` | API FastAPI : `/health`, `/chat` (SSE), `/voice` (WebSocket) |
+| `backend/stt/` | reconnaissance vocale Kyutai en streaming |
+| `backend/tts/` | service de synthèse vocale (voix clonée dans `voix/`, non versionné) |
+| `backend/rag/` | découpage, ingestion et recherche ; `corpus/` = le parcours |
+| `frontend/` | Next.js en export statique : interface vocale et page parcours |
+| `deploy/` | Traefik, nginx, cloudflared, script de démarrage des services natifs |
+| `.github/` | CI et Dependabot |
+
+## Démarrage rapide
+
+```powershell
+docker compose up -d qdrant
+powershell -ExecutionPolicy Bypass -File deploy\start-natif.ps1
+docker compose --env-file .env -f deploy/docker-compose.expose.yml up -d
 
-```
-python -m uvicorn backend.api.main:app --port 8000
+# Arrêter l'API et le TTS
+powershell -ExecutionPolicy Bypass -File deploy\stop-natif.ps1
 ```
 
-`GET /health` renvoie l'etat de Qdrant et d'Ollama.
-`POST /chat` streame la reponse en SSE, puis un evenement `sources` terminal.
+## Documentation
 
-## Exposition publique
+Toute la documentation est dans [`docs/`](docs/) :
 
-Configuration dans `deploy/` : Traefik en frontal, nginx pour l'export statique
-du front, cloudflared pour le tunnel. L'API et Ollama restent natifs sur l'hote,
-joints via `host.docker.internal`.
+| Document | Contenu |
+|---|---|
+| [exploitation.md](docs/exploitation.md) | architecture, démarrage, déploiement, arrêt, vérifications, dépannage, sécurité |
+| [frontend.md](docs/frontend.md) | front Next.js : variables de build, commandes, spécificités mobiles, tests |
+| [corpus-demo.md](docs/corpus-demo.md) | corpus fictif de démonstration |
 
-Prerequis, dans l'ordre :
+Conventions et décisions techniques mesurées : [CLAUDE.md](CLAUDE.md).
 
-1. `npm run build` dans `frontend/` avec `NEXT_PUBLIC_API_URL=https://<domaine>/api`
-2. l'API lancee : `python -m uvicorn backend.api.main:app --port 8000`
-3. `TRAEFIK_DOMAIN` et `CLOUDFLARE_TUNNEL_TOKEN` renseignes
-4. la route DNS creee cote Cloudflare vers ce tunnel
+## Tests
 
-Lancement (le `--env-file` est obligatoire : compose cherche sinon `deploy/.env`) :
-
-```
-docker compose --env-file .env -f deploy/docker-compose.expose.yml up -d
+```powershell
+python -m pytest backend/tests          # backend, sans GPU
+cd frontend; npx vitest run; npx tsc --noEmit
 ```
-
-Un rate-limit est pose sur `/api` : l'endpoint de chat n'est pas authentifie et
-s'adosse a une seule carte graphique.

backend/api/main.py

@@ -22,6 +22,7 @@
 from pydantic import BaseModel, Field, field_validator
 from qdrant_client.http.exceptions import ResponseHandlingException, UnexpectedResponse
 from starlette.concurrency import run_in_threadpool
+from starlette.websockets import WebSocketState
 
 # Triton est absent des wheels ROCm Windows : le STT (Moshi) passe par
 # torch.compile et leve TritonMissing sans repli en mode eager. Doit etre
@@ -424,6 +425,10 @@ async def voice(websocket: WebSocket):
     await websocket.accept()
     try:
         await _gerer_session_vocale(websocket)
+        # Fermeture explicite (1000) : sans trame de fermeture, Safari iOS voit
+        # une coupure anormale et émet un "error" tardif côté navigateur.
+        if websocket.client_state == WebSocketState.CONNECTED:
+            await websocket.close()
     except WebSocketDisconnect:
         pass
     finally:

backend/rag/corpus_demo/README.md

@@ -20,3 +20,18 @@ def test_voice_refuse_une_origine_etrangere():
         with client.websocket_connect("/voice", headers={"origin": "https://site-malveillant.example"}) as ws:
             ws.receive_json()
     assert erreur.value.code == 1008
+
+
+def test_voice_ferme_proprement_la_connexion_en_fin_de_session(monkeypatch):
+    """Sans trame de fermeture, Safari iOS voit une coupure anormale et émet
+    un événement "error" tardif qui cassait la question suivante."""
+    async def session_vide(websocket):
+        await websocket.send_json({"type": "error", "message": "Aucune parole detectee."})
+
+    monkeypatch.setattr(api_main, "_gerer_session_vocale", session_vide)
+    monkeypatch.setattr(api_main.app.state, "session_vocale_active", False, raising=False)
+    with client.websocket_connect("/voice", headers={"origin": "http://localhost:3000"}) as ws:
+        ws.receive_json()
+        message = ws.receive()
+    assert message["type"] == "websocket.close"
+    assert message["code"] == 1000

backend/tests/test_securite_api.py

@@ -0,0 +1,35 @@
+# Arrete les deux process natifs lances par start-natif.ps1 :
+#   - API (127.0.0.1:8000) : le vocal et /api tombent, le site statique reste en ligne
+#   - TTS (127.0.0.1:8001)
+# Les conteneurs (Qdrant, nginx, Traefik, cloudflared) ne sont pas touches :
+# voir docs/exploitation.md, section 4, pour couper aussi le site.
+# Usage : powershell -ExecutionPolicy Bypass -File deploy\stop-natif.ps1 [-WhatIf]
+[CmdletBinding(SupportsShouldProcess)]
+param()
+
+# Chargement reel du module meme sous -WhatIf (sinon il simule la creation de ses alias).
+$simulation = $WhatIfPreference
+$WhatIfPreference = $false
+Import-Module NetTCPIP
+$WhatIfPreference = $simulation
+
+$services = @(
+    @{ Port = 8000; Nom = "API" },
+    @{ Port = 8001; Nom = "TTS" }
+)
+
+foreach ($service in $services) {
+    $port = $service.Port
+    $nom = $service.Nom
+    $ecoutes = @(Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue)
+    if ($ecoutes.Count -eq 0) {
+        Write-Output "$nom (port $port) : deja arrete"
+        continue
+    }
+    foreach ($id in ($ecoutes.OwningProcess | Sort-Object -Unique)) {
+        if ($PSCmdlet.ShouldProcess("$nom (port $port, PID $id)", "Arreter")) {
+            Stop-Process -Id $id -Force
+            Write-Output "$nom (port $port) : arrete (PID $id)"
+        }
+    }
+}

deploy/stop-natif.ps1

@@ -0,0 +1,11 @@
+# Corpus de démonstration
+
+Concerne le dossier `backend/rag/corpus_demo/`.
+
+Données de démonstration entièrement fictives (persona « Camille Verne »),
+générées pour exercer la chaîne d'ingestion et de recherche avant que le vrai
+corpus de `backend/rag/corpus/` soit rédigé. Il sert encore à tester le site sans
+données personnelles (`CORPUS_DIR=../backend/rag/corpus_demo`, voir
+[frontend.md](frontend.md)).
+
+Ne jamais servir ce répertoire en production : il ne décrit personne de réel.