feat voice: implement real-time response segmentation for agent replies, enhancing transcript delivery via WebRTC data channels. Update LangGraphProcessor to split responses into segments and modify frontend to display these segments in real-time. Update documentation to reflect new segment handling features.

docs/VOICE_CLIENT_INTEGRATION.md

@@ -519,6 +519,65 @@ Le polling HTTP sur `GET /voice/transcript/{conversation_id}` reste recommandé
 - recharger une conversation plus tard,
 - exporter les transcriptions.
 
+### 3.5. Segments de réponse agent en temps réel
+
+Les réponses de l'agent sont également découpées en plusieurs segments texte côté serveur (dans `LangGraphProcessor`) et envoyées au client au fur et à mesure de leur synthèse vocale.
+
+Le format des messages est :
+
+```json
+{
+  "type": "assistant_segment",
+  "text": "phrase de la reponse agent",
+  "segment_index": 2,
+  "total_segments": 5,
+  "conversation_id": "uuid-de-la-conversation"
+}
+```
+
+#### SmallWebRTC – écouter les segments de réponse
+
+```javascript
+const dc = pc.createDataChannel("pipecat-app");
+
+dc.onmessage = (event) => {
+  try {
+    const msg = JSON.parse(event.data);
+    if (!msg || typeof msg !== "object") return;
+
+    if (msg.type === "buffered_transcript") {
+      displayUserSegment(msg.text, msg.segment_index);
+    } else if (msg.type === "assistant_segment") {
+      displayAssistantSegment(msg.text, msg.segment_index, msg.total_segments);
+    }
+  } catch (e) {
+    console.warn("Message datachannel non JSON:", event.data);
+  }
+};
+```
+
+#### Daily – écouter les segments de réponse
+
+```javascript
+const callObject = window.Daily.createCallObject();
+
+callObject.on("app-message", (ev) => {
+  const msg = ev.data;
+  if (!msg || typeof msg !== "object") return;
+
+  if (msg.type === "buffered_transcript") {
+    displayUserSegment(msg.text, msg.segment_index);
+  } else if (msg.type === "assistant_segment") {
+    displayAssistantSegment(msg.text, msg.segment_index, msg.total_segments);
+  }
+});
+```
+
+Comme pour les segments STT, ces messages sont complémentaires au polling HTTP :
+
+- les segments `assistant_segment` offrent une vue temps réel, synchronisée grossièrement avec la voix,
+- l'endpoint `GET /voice/transcript/{conversation_id}` fournit l'historique complet structuré `user` / `assistant`.
+
 ---
 
 ## 4. Paramètres VAD (Voice Activity Detection)

services/voice/README.md

@@ -329,6 +329,43 @@ dc.onmessage = (event) => {
 
 Le polling HTTP sur `/voice/transcript/{conversation_id}` reste utile pour reconstruire l'historique complet (user/assistant) ou pour des usages offline/export.
 
+### 3.5. Segments de réponse agent en temps réel
+
+En plus des segments STT utilisateur, les réponses de l'agent sont découpées en plusieurs segments texte dans `LangGraphProcessor` et renvoyées au client au fil de l'eau.
+
+- Chaque segment de réponse agent génère un message JSON de la forme :
+
+```json
+{
+  "type": "assistant_segment",
+  "text": "phrase de la reponse agent",
+  "segment_index": 2,
+  "total_segments": 5,
+  "conversation_id": "uuid-de-la-conversation"
+}
+```
+
+- Côté SmallWebRTC, ces messages sont reçus sur le même data channel `pipecat-app` :
+
+```javascript
+dc.onmessage = (event) => {
+  try {
+    const msg = JSON.parse(event.data);
+    if (msg.type === "buffered_transcript") {
+      // segments STT utilisateur
+      displayUserSegment(msg.text, msg.segment_index);
+    } else if (msg.type === "assistant_segment") {
+      // segments de reponse agent
+      displayAssistantSegment(msg.text, msg.segment_index, msg.total_segments);
+    }
+  } catch (e) {
+    console.warn("Message datachannel non JSON:", event.data);
+  }
+};
+```
+
+Sur la page de test `voice.html`, ces segments sont déjà affichés dans la colonne de droite (fil de discussion en temps réel).
+
 ---
 
 ## 4. Intégration dans d’autres types de clients

services/voice/langgraph_processor.py

@@ -1,7 +1,7 @@
 """Pipecat FrameProcessor that routes transcribed text through the LangGraph agent."""
 import re
 import logging
-from typing import Optional
+from typing import Optional, List
 
 from pipecat.processors.frame_processor import FrameProcessor
 from pipecat.frames.frames import (
@@ -9,6 +9,7 @@ from pipecat.frames.frames import (
     TextFrame,
     LLMFullResponseStartFrame,
     LLMFullResponseEndFrame,
+    OutputTransportMessageFrame,
 )
 
 from services.voice.transcript_store import TranscriptStore
@@ -53,10 +54,25 @@ class LangGraphProcessor(FrameProcessor):
                         TranscriptStore.append(self.conversation_id, "assistant", response)
 
                     clean = self._clean_response_for_tts(response)
-                    logger.info("Sending to TTS: %s", clean)
+                    logger.info("Sending to TTS (cleaned): %s", clean)
+
+                    segments = self._split_into_segments(clean)
+                    logger.info("Split response into %d segment(s)", len(segments))
 
                     await self.push_frame(LLMFullResponseStartFrame())
-                    await self.push_frame(TextFrame(clean))
+                    for idx, segment in enumerate(segments, start=1):
+                        await self.push_frame(TextFrame(segment))
+                        await self.push_frame(
+                            OutputTransportMessageFrame(
+                                {
+                                    "type": "assistant_segment",
+                                    "text": segment,
+                                    "segment_index": idx,
+                                    "total_segments": len(segments),
+                                    "conversation_id": self.conversation_id,
+                                }
+                            )
+                        )
                     await self.push_frame(LLMFullResponseEndFrame())
                 except Exception:
                     logger.exception("Error in LangGraphProcessor")
@@ -104,3 +120,57 @@ class LangGraphProcessor(FrameProcessor):
         clean = re.sub(r"\s+", " ", clean)
 
         return clean.strip()
+
+    # ------------------------------------------------------------------
+    # Segmentation helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _split_into_segments(text: str) -> List[str]:
+        """Split cleaned assistant text into sentence-like segments.
+
+        Uses simple punctuation-based splitting on `.`, `?`, `!` and
+        falls back to a single-segment list if no punctuation is found.
+        Very short segments are merged back into neighbours.
+        """
+        if not text:
+            return []
+
+        # Split on end-of-sentence punctuation followed by whitespace.
+        parts = re.split(r"(?<=[.?!])\s+", text)
+        parts = [p.strip() for p in parts if p and p.strip()]
+
+        if not parts:
+            return []
+        if len(parts) == 1:
+            return parts
+
+        # Merge very short trailing segments into the previous one to avoid noise.
+        merged: List[str] = []
+        buffer = ""
+        for idx, part in enumerate(parts):
+            if buffer:
+                candidate = buffer + " " + part
+            else:
+                candidate = part
+
+            # Heuristic: keep segments with at least ~10 characters,
+            # otherwise merge with the next piece.
+            if len(candidate) < 10 and idx < len(parts) - 1:
+                buffer = candidate
+                continue
+
+            if buffer and candidate is not buffer:
+                merged.append(candidate)
+                buffer = ""
+            else:
+                merged.append(part)
+                buffer = ""
+
+        if buffer:
+            if merged:
+                merged[-1] = merged[-1] + " " + buffer
+            else:
+                merged.append(buffer)
+
+        return merged

static/voice.html

@@ -414,6 +414,29 @@
             bufferThreadEl.scrollTop = bufferThreadEl.scrollHeight;
         }
 
+        function appendAssistantSegment(msg) {
+            if (!bufferThreadEl || !msg || !msg.text) return;
+
+            const wrapper = document.createElement("div");
+
+            const meta = document.createElement("div");
+            meta.className = "buffer-segment-meta";
+            const idx = typeof msg.segment_index === "number" ? msg.segment_index : null;
+            meta.textContent = idx !== null
+                ? `Agent · segment #${idx}${msg.total_segments ? " / " + msg.total_segments : ""}`
+                : "Agent";
+
+            const bubble = document.createElement("div");
+            bubble.className = "buffer-segment-bubble";
+            bubble.style.background = "#e0f2fe"; // legerement different des segments user
+            bubble.textContent = msg.text;
+
+            wrapper.appendChild(meta);
+            wrapper.appendChild(bubble);
+            bufferThreadEl.appendChild(wrapper);
+            bufferThreadEl.scrollTop = bufferThreadEl.scrollHeight;
+        }
+
         async function fetchTranscript() {
             if (!conversationId) return;
             try {
@@ -484,8 +507,11 @@
                     if (!event || typeof event.data !== "string") return;
                     try {
                         const msg = JSON.parse(event.data);
-                        if (msg && msg.type === "buffered_transcript") {
+                        if (!msg || typeof msg !== "object") return;
+                        if (msg.type === "buffered_transcript") {
                             appendBufferedSegment(msg);
+                        } else if (msg.type === "assistant_segment") {
+                            appendAssistantSegment(msg);
                         }
                     } catch (e) {
                         // Ignore non-JSON messages (ou logs si besoin)