@ephia/dova-sdk 1.0.0

package/src/core/text-processing/voice-formatting.normalizer.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+import {
+  normalizePreviewText,
+  normalizeCommittedText,
+  resolveVoiceFormattingConfig,
+} from "./voice-formatting.normalizer";
+
+const dictation = { mode: "dictation" as const };
+const none = { mode: "none" as const };
+
+describe("resolveVoiceFormattingConfig", () => {
+  it("défaut mode none", () => {
+    expect(resolveVoiceFormattingConfig()).toEqual({ mode: "none" });
+  });
+
+  it("map legacy enabled=true vers dictation", () => {
+    expect(resolveVoiceFormattingConfig({ enabled: true } as never)).toEqual({
+      mode: "dictation",
+    });
+  });
+
+  it("map legacy enabled=false vers none", () => {
+    expect(resolveVoiceFormattingConfig({ enabled: false } as never)).toEqual({
+      mode: "none",
+    });
+  });
+});
+
+describe("normalizePreviewText — feature désactivée", () => {
+  it("retourne le texte intact si mode=none", () => {
+    expect(
+      normalizePreviewText("foie droit point à la ligne taille normale", none)
+    ).toBe("foie droit point à la ligne taille normale");
+  });
+
+  it("retourne le texte intact si config undefined", () => {
+    expect(normalizePreviewText("virgule rien", undefined)).toBe("virgule rien");
+  });
+});
+
+describe("normalizePreviewText — sauts de ligne", () => {
+  it("à la ligne → \\n + capitalisation", () =>
+    expect(normalizePreviewText("foie normal à la ligne vésicule", dictation)).toBe(
+      "foie normal \nVésicule"
+    ));
+
+  it("nouveau paragraphe → \\n\\n + capitalisation", () =>
+    expect(
+      normalizePreviewText("conclusion nouveau paragraphe rien à signaler", dictation)
+    ).toBe("conclusion \n\nRien à signaler"));
+
+  it("point à la ligne → .\\n + capitalisation", () =>
+    expect(
+      normalizePreviewText("taille normale point à la ligne échogénicité", dictation)
+    ).toBe("taille normale .\nÉchogénicité"));
+});
+
+describe("normalizePreviewText — ponctuation", () => {
+  it("virgule → ,", () =>
+    expect(normalizePreviewText("rein droit virgule taille normale", dictation)).toBe(
+      "rein droit , taille normale"
+    ));
+
+  it("point d'interrogation → ? + capitalisation si suite", () =>
+    expect(normalizePreviewText("hématome point d'interrogation suite", dictation)).toBe(
+      "hématome ? Suite"
+    ));
+
+  it("point seul → . + capitalisation", () =>
+    expect(normalizePreviewText("taille normale point foie", dictation)).toBe(
+      "taille normale . Foie"
+    ));
+});
+
+describe("normalizePreviewText — locale en-US", () => {
+  it("period → . + capitalisation", () =>
+    expect(normalizePreviewText("liver period normal", { mode: "dictation", locale: "en-US" })).toBe(
+      "liver . Normal"
+    ));
+
+  it("comma → ,", () =>
+    expect(
+      normalizePreviewText("right kidney comma size normal", { mode: "dictation", locale: "en-US" })
+    ).toBe("right kidney , size normal"));
+});
+
+describe("normalizePreviewText — ambiguïté médicale 'point'", () => {
+  it("documente le comportement actuel de 'point de rehaussement'", () => {
+    expect(normalizePreviewText("point de rehaussement", dictation)).toBe(
+      ". De rehaussement"
+    );
+  });
+});
+
+describe("normalizeCommittedText", () => {
+  it("retourne le texte intact si mode=none", () => {
+    expect(normalizeCommittedText("bonjour virgule monde", none)).toBe(
+      "bonjour virgule monde"
+    );
+  });
+
+  it("ne convertit pas 'virgule' en mode dictation (ponctuation exclue du committed)", () => {
+    expect(normalizeCommittedText("bonjour virgule monde", dictation)).toBe(
+      "bonjour virgule monde"
+    );
+  });
+
+  it("ne crée pas de double point sur 'Point' commité (ponctuation exclue du committed)", () => {
+    expect(normalizeCommittedText("aiguë. Point reste.", dictation)).toBe(
+      "aiguë. Point reste."
+    );
+  });
+
+  it("à la ligne + virgule Voxtral → \\n + majuscule sans virgule", () => {
+    // Voxtral sort "À la ligne, petite dilatation..." → doit devenir "\nPetite dilatation..."
+    expect(
+      normalizeCommittedText("À la ligne, petite dilatation modérée.", dictation)
+    ).toBe("\nPetite dilatation modérée.");
+  });
+
+  it("à la ligne + point-virgule Voxtral → \\n + majuscule sans point-virgule", () => {
+    expect(
+      normalizeCommittedText("À la ligne; bonne aération sinusienne.", dictation)
+    ).toBe("\nBonne aération sinusienne.");
+  });
+
+  it("à la ligne sans ponctuation parasite → \\n + majuscule", () => {
+    expect(
+      normalizeCommittedText("À la ligne bonne aération sinusienne.", dictation)
+    ).toBe("\nBonne aération sinusienne.");
+  });
+});

package/src/core/text-processing/voice-formatting.normalizer.ts

@@ -0,0 +1,284 @@
+/**
+ * Voice Formatting Normalizer
+ *
+ * Intercepte les commandes vocales dictées et les substitue par leur
+ * équivalent typographique (preview realtime et texte committé).
+ * Désactivé par défaut (mode: "none").
+ */
+
+import type { EphiaAudioEvent } from "ephia-protocol";
+
+export type VoiceFormattingMode = "none" | "dictation";
+
+export interface VoiceFormattingConfig {
+  /**
+   * Mode de traitement de la ponctuation vocale.
+   * - "none"      : aucun traitement (défaut)
+   * - "dictation" : substitution des commandes vocales sur preview ET commit
+   */
+  mode: VoiceFormattingMode;
+  /** Locale pour le dictionnaire de commandes. Défaut: 'fr-FR'. */
+  locale?: "fr-FR" | "en-US";
+}
+
+/** Legacy shape still accepted by resolveVoiceFormattingConfig. */
+type LegacyVoiceFormattingConfig = VoiceFormattingConfig & {
+  enabled?: boolean;
+};
+
+interface VoiceCommandEntry {
+  /** Texte de remplacement */
+  replace: string;
+  /** Si true, le prochain caractère alphabétique sera capitalisé */
+  capitalize: boolean;
+}
+
+type VoiceCommandMap = Record<string, VoiceCommandEntry>;
+
+// ─── Dictionnaires ────────────────────────────────────────────────────────────
+
+const PREVIEW_COMMANDS_FR: VoiceCommandMap = {
+  // Sauts de ligne / structure
+  "point à la ligne": { replace: ".\n", capitalize: true },
+  "à la ligne": { replace: "\n", capitalize: true },
+  "retour à la ligne": { replace: "\n", capitalize: true },
+  "saut de ligne": { replace: "\n", capitalize: true },
+  "nouveau paragraphe": { replace: "\n\n", capitalize: true },
+  "nouvelle ligne": { replace: "\n", capitalize: true },
+
+  // Ponctuation de fin
+  point: { replace: ". ", capitalize: true },
+  "point final": { replace: ". ", capitalize: true },
+  virgule: { replace: ", ", capitalize: false },
+  "point-virgule": { replace: "; ", capitalize: false },
+  "point virgule": { replace: "; ", capitalize: false },
+  "deux points": { replace: " : ", capitalize: false },
+  "point d'interrogation": { replace: " ? ", capitalize: true },
+  "point d'exclamation": { replace: " ! ", capitalize: true },
+  tiret: { replace: " — ", capitalize: false },
+  "tiret long": { replace: " — ", capitalize: false },
+
+  // Parenthèses / guillemets
+  "ouvrir parenthèse": { replace: " (", capitalize: false },
+  "fermer parenthèse": { replace: ") ", capitalize: false },
+  "ouvrir guillemets": { replace: " « ", capitalize: false },
+  "fermer guillemets": { replace: " » ", capitalize: false },
+  "guillemet ouvrant": { replace: " « ", capitalize: false },
+  "guillemet fermant": { replace: " » ", capitalize: false },
+};
+
+// Texte commité uniquement : structure/sauts de ligne.
+// Ponctuation exclue — déjà résolue côté backend (Voxtral prompt, apply_dictation_commands).
+const COMMITTED_COMMANDS_FR: VoiceCommandMap = {
+  "point à la ligne":  { replace: ".\n",  capitalize: true },
+  "à la ligne":        { replace: "\n",   capitalize: true },
+  "retour à la ligne": { replace: "\n",   capitalize: true },
+  "saut de ligne":     { replace: "\n",   capitalize: true },
+  "nouveau paragraphe":{ replace: "\n\n", capitalize: true },
+  "nouvelle ligne":    { replace: "\n",   capitalize: true },
+};
+
+const COMMANDS_EN: VoiceCommandMap = {
+  "new line": { replace: "\n", capitalize: true },
+  "new paragraph": { replace: "\n\n", capitalize: true },
+  period: { replace: ". ", capitalize: true },
+  "full stop": { replace: ". ", capitalize: true },
+  comma: { replace: ", ", capitalize: false },
+  semicolon: { replace: "; ", capitalize: false },
+  colon: { replace: ": ", capitalize: false },
+  "question mark": { replace: "? ", capitalize: true },
+  "exclamation mark": { replace: "! ", capitalize: true },
+  "open parenthesis": { replace: " (", capitalize: false },
+  "close parenthesis": { replace: ") ", capitalize: false },
+  "open quote": { replace: ' "', capitalize: false },
+  "close quote": { replace: '" ', capitalize: false },
+  dash: { replace: " — ", capitalize: false },
+};
+
+const DEFAULT_VOICE_FORMATTING: VoiceFormattingConfig = { mode: "none" };
+
+export function resolveVoiceFormattingConfig(
+  input?: LegacyVoiceFormattingConfig | null
+): VoiceFormattingConfig {
+  if (!input) return DEFAULT_VOICE_FORMATTING;
+
+  if ("mode" in input && input.mode) {
+    return {
+      mode: input.mode,
+      locale: input.locale,
+    };
+  }
+
+  if ("enabled" in input && typeof input.enabled === "boolean") {
+    return {
+      mode: input.enabled ? "dictation" : "none",
+      locale: input.locale,
+    };
+  }
+
+  return DEFAULT_VOICE_FORMATTING;
+}
+
+// ─── Builder ──────────────────────────────────────────────────────────────────
+
+function buildCommandMap(
+  locale: VoiceFormattingConfig["locale"] = "fr-FR",
+  baseOverride?: VoiceCommandMap,
+): VoiceCommandMap {
+  return baseOverride ?? (locale === "en-US" ? COMMANDS_EN : PREVIEW_COMMANDS_FR);
+}
+
+/**
+ * Trie les commandes par longueur décroissante pour garantir que
+ * "point d'interrogation" est testé avant "point".
+ */
+function sortedCommands(map: VoiceCommandMap): Array<[string, VoiceCommandEntry]> {
+  return Object.entries(map).sort((a, b) => b[0].length - a[0].length);
+}
+
+// ─── Moteur de substitution ───────────────────────────────────────────────────
+
+const _regexpCache = new Map<string, RegExp>();
+
+function getCommandPattern(cmd: string): RegExp {
+  if (!_regexpCache.has(cmd)) {
+    const escaped = cmd.replace(/[-]/g, "\\-");
+    _regexpCache.set(cmd, new RegExp(`(?<![\\wÀ-ÿ])(${escaped})(?![\\wÀ-ÿ])`, "gi"));
+  }
+  return _regexpCache.get(cmd)!;
+}
+
+function applyCommands(text: string, commands: Array<[string, VoiceCommandEntry]>): string {
+  let result = text;
+  for (const [cmd, entry] of commands) {
+    const pattern = getCommandPattern(cmd);
+    result = result.replace(pattern, () => {
+      if (entry.capitalize) {
+        return entry.replace + "\u0001";
+      }
+      return entry.replace;
+    });
+  }
+  return result;
+}
+
+function applyCapitalization(text: string): string {
+  // After a newline command (\n\u0001), strip orphaned comma/semicolon that Voxtral
+  // appends naturally to "à la ligne" — e.g. "à la ligne, petite" → "\nPetite" not "\n, petite"
+  let result = text.replace(/\n\u0001[ \t]*[,;][ \t]*/g, "\n\u0001");
+  result = result.replace(/\u0001\s*([a-zA-ZÀ-ÿ])/g, (_, letter) => letter.toUpperCase());
+  result = result.replace(/\u0001/g, "");
+  return result;
+}
+
+function normalizeVoiceText(text: string, config?: VoiceFormattingConfig, baseOverride?: VoiceCommandMap): string {
+  if (!text) return text;
+  if (!config || config.mode === "none") return text;
+
+  const commandMap = buildCommandMap(config.locale, baseOverride);
+  const commands = sortedCommands(commandMap);
+
+  const lower = text.toLowerCase();
+  const hasCandidate = commands.some(([cmd]) => lower.includes(cmd.split(" ")[0]));
+  if (!hasCandidate) return text;
+
+  let result = applyCommands(text, commands);
+  result = applyCapitalization(result);
+  result = result.replace(/ {2,}/g, " ");
+
+  return result;
+}
+
+// ─── Export principal ─────────────────────────────────────────────────────────
+
+/**
+ * Normalise un texte de preview realtime en appliquant les substitutions
+ * de commandes vocales si voiceFormatting.mode === "dictation".
+ */
+export function normalizePreviewText(
+  text: string,
+  config?: VoiceFormattingConfig
+): string {
+  return normalizeVoiceText(text, config);
+}
+
+/**
+ * Normalise le texte d'un segment committé (transcript.segment.committed).
+ * En mode dictation : applique uniquement les commandes structurelles (sauts de ligne).
+ * La ponctuation n'est pas retraduite — elle a déjà été résolue côté backend.
+ */
+export function normalizeCommittedText(
+  text: string,
+  config?: VoiceFormattingConfig
+): string {
+  return normalizeVoiceText(text, config, COMMITTED_COMMANDS_FR);
+}
+
+function formatEventPayloadText(
+  eventType: string,
+  payload: Record<string, unknown>,
+  config: VoiceFormattingConfig
+): Record<string, unknown> {
+  const next = { ...payload };
+
+  if (
+    eventType === "transcript.preview" ||
+    eventType === "transcript.preview.stable"
+  ) {
+    if (typeof payload.text === "string") {
+      next.text = normalizePreviewText(payload.text, config);
+    }
+    return next;
+  }
+
+  if (eventType === "transcript.final") {
+    if (typeof payload.text === "string") {
+      next.text = normalizeCommittedText(payload.text, config);
+    }
+    return next;
+  }
+
+  if (eventType === "transcript.segment.ready") {
+    const text = typeof payload.text === "string" ? payload.text : undefined;
+    const delta = typeof payload.delta === "string" ? payload.delta : undefined;
+    const effective = delta ?? text;
+    if (effective) {
+      const normalized = normalizeCommittedText(effective, config);
+      if (delta) next.delta = normalized;
+      else next.text = normalized;
+    }
+    return next;
+  }
+
+  if (eventType === "transcript.segment.committed") {
+    const text = typeof payload.text === "string" ? payload.text : "";
+    const delta = typeof payload.delta === "string" ? payload.delta : undefined;
+    const effective = delta ?? text;
+    const normalized = normalizeCommittedText(effective, config);
+    if (delta) next.delta = normalized;
+    next.text = normalized;
+    return next;
+  }
+
+  return next;
+}
+
+/**
+ * Retourne une copie de l'event avec le texte normalisé (mode dictation).
+ * L'event d'origine n'est pas muté.
+ */
+export function applyVoiceFormattingToEvent(
+  event: EphiaAudioEvent,
+  config?: VoiceFormattingConfig
+): EphiaAudioEvent {
+  const resolved = resolveVoiceFormattingConfig(config);
+  if (resolved.mode === "none") return event;
+
+  const payload = event.payload as Record<string, unknown> | undefined;
+  if (!payload) return event;
+
+  const nextPayload = formatEventPayloadText(event.type, payload, resolved);
+  if (nextPayload === payload) return event;
+
+  return { ...event, payload: nextPayload } as EphiaAudioEvent;
+}