feat(r5): dictée — audio local (faster-whisper) → note → corpus (ADR-004 §5)

Écran Voix R5 (maquetté, jamais construit) implémenté sur décision du référent : open-source et local, pas d'API externe. - apps/ai : faster-whisper (CTranslate2, CPU, MIT) opt-in (AI_TRANSCRIPTION=off|locale|deterministe, défaut off) ; endpoint /internal/transcrire — l'audio ne survit JAMAIS à l'appel (fichier temporaire supprimé quoi qu'il arrive) ; indexer_bilans inclut désormais InterventionReport.note anonymisée (champ existant depuis R2, jamais eu d'écran jusqu'ici) ; 29 pytest. - Contrat (77 opérations) : POST /assistant/transcribe (multipart). - API : proxy multipart vers siop2-ai (WORK_ORDERS.edit — même droit que la saisie du bilan) ; 2 tests e2e (80 tests API au total). - Mobile : expo-audio + expo-file-system, bouton dicter/terminer sur l'écran de clôture, purge locale après transcription, « Joindre la description à l'OT » (corrige un bug latent : enfilerBilan ignorait silencieusement les mises à jour de note). - Docker : siop2-ai embarque le modèle Whisper au build (1,54→2,19 Go), construit et vérifié (transcription réelle en conteneur, non-root). - Vérifié réellement : transcription fidèle (voix de synthèse française) en direct, bout en bout via l'API, dans le conteneur Docker construit, et chaîne corpus complète (note → clôture → réindexation → recherche sémantique). - Base de dev locale réinitialisée avec accord explicite du référent (prisma migrate reset, bloqué par défaut pour un agent IA) après pollution par les tests manuels de la recette terrain précédente. Reste : test tactile sur iPhone physique (bouton dicter) — bloqué par une connexion USB qui ne s'est pas rétablie malgré câble/port/ redémarrage essayés à plusieurs reprises, reporté comme la recette Android. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-08 12:41:54 +00:00 · 2026-07-22 11:55:47 +01:00
parent 0730bf9dad
commit 59ed6f3952
28 changed files with 782 additions and 20 deletions
--- a/docs/03-architecture/adr/ADR-004-modeles-ia.md
+++ b/docs/03-architecture/adr/ADR-004-modeles-ia.md
@@ -51,6 +51,23 @@
   réseau privé — la règle d'or ESLint d'ADR-001 concerne le code TypeScript de l'API,
   la topologie « MinIO jamais exposé » du runbook reste respectée.

+5. **Transcription (dictée, R5 D5) : locale, opt-in, jamais de persistance de l'audio.**
+   Amendement du 22/07/2026 — le référent choisit `faster-whisper` (CTranslate2, CPU,
+   licence MIT) plutôt qu'une API externe, même philosophie que les embeddings : « open
+   source et local ». `AI_TRANSCRIPTION=off` par défaut (endpoint refuse proprement,
+   503) ; `locale` charge le modèle (taille configurable par `AI_TRANSCRIPTION_MODEL`,
+   défaut `small`) ; `deterministe` en tests/CI (aucune dépendance audio). Le flux :
+   l'audio ne transite qu'une fois vers `siop2-ai` (multipart, jamais écrit sur disque
+   par `siop2-api`), un fichier temporaire le temps de l'inférence côté `siop2-ai`,
+   **supprimé aussitôt quoi qu'il arrive** — succès ou erreur (loi 09-08, D5). Seul le
+   texte transcrit revient, à relire par l'humain (D1) avant tout usage : suggestion de
+   bilan immédiate, et/ou sauvegarde dans `InterventionReport.note` — qui, à la clôture
+   de l'OT, rejoint le corpus comme les libellés codés (même pipeline d'anonymisation,
+   D4). **Point de vigilance non calibré** (décision explicite du référent : pas de
+   prototype de mesure préalable, contrairement au choix du modèle d'embeddings) :
+   Whisper transcrit mal le darija, probable en mélange avec le français sur le
+   terrain — à mesurer sur des enregistrements réels si la qualité déçoit en recette.
+
 ## Conséquences

 - L'anonymisation (D4) s'applique **à l'ingestion** — les index ne contiennent jamais
@@ -58,3 +75,11 @@
 - Le mode extractif est le contrat de base : toute recette R5 doit passer SANS clé API.
 - Si le partenaire veut un jour une génération 100 % locale (llama.cpp…), seul le point 3
  change — interface `Generateur` prévue pour ça.
+- La dictée (point 5) est opt-in et sans mesure de qualité préalable : à recetter avec
+  attention avant toute promesse de qualité au client, en particulier en darija.
+- Implémentée et vérifiée le 22/07/2026 : transcription réelle (français, voix de
+  synthèse) juste et rapide en local, bout en bout via l'API NestJS, et dans l'image
+  Docker de production construite pour l'occasion (modèle embarqué, aucun téléchargement
+  au démarrage). **Reste** : le test tactile sur iPhone physique (bouton dicter, permission
+  micro) n'a pas pu se jouer — blocage USB persistant malgré câble/port/redémarrage
+  multiples, reporté comme la recette Android (attend un accès matériel qui fonctionne).
--- a/docs/06-production/runbook-dokploy.md
+++ b/docs/06-production/runbook-dokploy.md
@@ -48,6 +48,8 @@ domaine (Traefik/Dokploy) ──▶ siop2-web :80 (nginx, statique)
 | `AI_API_KEY` | — | clé API Anthropic — **uniquement** si `AI_GENERATION=api` ; le service refuse de démarrer si elle manque en mode api |
 | `AI_MODEL` | — | défaut `claude-opus-4-8` |
 | `AI_SEUIL_PERTINENCE` / `AI_SEUIL_SUGGESTION` / `AI_SEUIL_CONFIANCE_FORTE` | — | défauts 0,45 / 0,40 / 0,55 — **à calibrer sur le corpus client** (voir §7) |
+| `AI_TRANSCRIPTION` | — | `off` (défaut) ou `locale` (dictée R5 D5, `faster-whisper` — le modèle est déjà dans l'image, l'activer ne demande pas de rebuild) |
+| `AI_TRANSCRIPTION_MODEL` | — | défaut `small` — `tiny`/`base`/`small`/`medium`/`large-v3`, compromis qualité/vitesse CPU non calibré sur le darija (voir ADR-004 §5) |

 Profils types :

@@ -125,6 +127,13 @@ version reste visible côté web).
 - Mode génératif : ajouter `AI_GENERATION=api` + `AI_API_KEY` dans l'environnement
  Dokploy puis redéployer le service `siop2-ai` seul. La clé ne transite jamais par
  le dépôt ni par les journaux (`/healthz` n'expose que le mode).
+- Dictée (D5) : ajouter `AI_TRANSCRIPTION=locale` dans l'environnement Dokploy puis
+  redéployer `siop2-ai` — le modèle Whisper est déjà dans l'image (§ci-dessus), pas
+  de rebuild ni de téléchargement au boot. L'audio n'est **jamais** stocké, ni par
+  `siop2-api` ni par `siop2-ai` : transcrit à la volée, effacé aussitôt (voir
+  ADR-004 §5). Point de vigilance non calibré : la qualité en darija (fréquent sur
+  le terrain, mélangé au français) — à mesurer sur de vrais enregistrements si la
+  dictée déçoit en recette.

 ## 6. Calibrage des seuils sur le corpus client

--- a/docs/journal/journal.md
+++ b/docs/journal/journal.md
@@ -4,6 +4,50 @@ Trace chronologique des sessions (la plus récente en premier). Le **playbook**

 ---

+## 2026-07-22 — Pr. Daaif (+ Claude) — Dictée implémentée : audio → transcription locale → corpus (ADR-004 §5)
+
+**Actions**
+
+- Suite du feu vert « on passe à l'audio » (maquette Voix amendée le 22/07) : implémentation complète de la
+  dictée (R5 D5) — écran maquetté jamais construit jusqu'ici, ni open source ni local en LLM externe, choix du
+  référent réaffirmé (« toujours pour l'open source et le local »).
+- **`apps/ai`** : `faster-whisper` (CTranslate2, CPU, MIT), `AI_TRANSCRIPTION=off|locale|deterministe` (défaut
+  off), `AI_TRANSCRIPTION_MODEL` (défaut `small`) ; endpoint `/internal/transcrire` — l'audio ne survit
+  JAMAIS à l'appel (fichier temporaire supprimé quoi qu'il arrive, succès ou erreur) ; `indexer_bilans` inclut
+  désormais `InterventionReport.note` (anonymisée par le même pipeline D4) — le champ existait en base et au
+  contrat depuis R2 mais **n'avait jamais eu d'écran** ; 29 pytest (dont le transcripteur déterministe pour CI).
+- **Contrat** (77 opérations) : `POST /assistant/transcribe` (multipart, `TranscriptionResult`).
+- **API NestJS** : proxy multipart vers `siop2-ai` (`AssistantService.transcribe`), `WORK_ORDERS.edit` — même
+  droit que la saisie du bilan qu'elle alimente ; 2 tests e2e ajoutés (80 tests API au total).
+- **Mobile** : `expo-audio` (enregistrement) + `expo-file-system` (purge locale) ; carte « Décrire pour
+  suggérer » de l'écran de clôture gagne un bouton dicter/terminer, une confirmation de purge, et
+  « Joindre la description à l'OT » (sauvegarde dans `note` via la file existante — corrige au passage un bug
+  latent : `enfilerBilan` ignorait silencieusement toute mise à jour de `note`).
+- **Docker** : `siop2-ai` embarque désormais aussi le modèle Whisper au build (image 1,54 Go → 2,19 Go) —
+  construit et vérifié réellement (transcription en conteneur, non-root, 0 téléchargement au démarrage).
+- **Vérification réelle** (voix de synthèse macOS `say`, français) : transcription fidèle en direct
+  (`TranscripteurLocal`), bout en bout via l'API NestJS, et dans le conteneur Docker construit — puis chaîne
+  complète corpus confirmée : note sauvegardée → OT clôturé → réindexation → contenu retrouvé par recherche
+  sémantique avec un bon score de pertinence.
+- **Nettoyage** : la base de dev locale, polluée par les tests manuels de la recette terrain (deux OT seedés
+  clôturés en dehors de leur état d'origine), a été réinitialisée avec l'accord explicite du référent
+  (`prisma migrate reset --force`, bloqué par défaut pour un agent IA — consentement demandé et obtenu avant
+  exécution).
+
+**Décisions**
+
+- Pas de prototype de mesure français/darija avant l'implémentation (confirmé une seconde fois) — seuls des
+  contrôles d'ingénierie de base (le code tourne, avec de la vraie parole) ont été faits, pas un calibrage.
+- **Reste** : le test tactile sur iPhone physique (bouton dicter, permission micro) n'a pas pu se jouer —
+  blocage USB persistant malgré câble/port/redémarrage/mode développeur essayés à plusieurs reprises. Reporté
+  comme la recette Android, sur décision du référent — ne bloque pas la suite.
+
+**Prochaine étape** : test tactile de la dictée sur iPhone dès que la connexion USB fonctionnera ; recette
+Android sur appareil physique ; redéploiement Dokploy (`AI_SERVICE_TOKEN`) ; calibrage `AI_SEUIL_*` et qualité
+darija sur corpus SPELEV réel.
+
+---
+
 ## 2026-07-22 — Pr. Daaif (+ Claude) — Idée backlog : transcription audio → corpus (maquette amendée, pas codée)

 **Actions**
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -1322,6 +1322,54 @@
        }
      }
    },
+    "/assistant/transcribe": {
+      "post": {
+        "operationId": "transcribeAudio",
+        "summary": "Dictée (R5 D5, opt-in) — l’audio est transcrit puis JAMAIS conservé, à relire avant tout usage",
+        "tags": [
+          "assistant"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "format": "binary"
+                  }
+                },
+                "required": [
+                  "file"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Texte transcrit — à relire (D1)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TranscriptionResult"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Dictée non activée ou service IA indisponible"
+          }
+        }
+      }
+    },
    "/search": {
      "get": {
        "operationId": "globalSearch",
@@ -5427,6 +5475,19 @@
        ],
        "additionalProperties": false
      },
+      "TranscriptionResult": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "text"
+        ],
+        "additionalProperties": false
+      },
      "SearchResponse": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",