From 0aa197e4a412c2aea84abe7e8211e77fae521ec7 Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Wed, 25 Jun 2025 23:36:04 -0400
Subject: [PATCH] Add docstrings to DeepgramSTTService

---
 src/pipecat/services/deepgram/stt.py | 68 ++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/src/pipecat/services/deepgram/stt.py b/src/pipecat/services/deepgram/stt.py
index 308ad1d1d..da7ec535f 100644
--- a/src/pipecat/services/deepgram/stt.py
+++ b/src/pipecat/services/deepgram/stt.py
@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Deepgram speech-to-text service implementation."""
+
 from typing import AsyncGenerator, Dict, Optional
 
 from loguru import logger
@@ -41,6 +43,22 @@ except ModuleNotFoundError as e:
 
 
 class DeepgramSTTService(STTService):
+    """Deepgram speech-to-text service.
+
+    Provides real-time speech recognition using Deepgram's WebSocket API.
+    Supports configurable models, languages, VAD events, and various audio
+    processing options.
+
+    Args:
+        api_key: Deepgram API key for authentication.
+        url: Deprecated. Use base_url instead.
+        base_url: Custom Deepgram API base URL.
+        sample_rate: Audio sample rate. If None, uses default or live_options value.
+        live_options: Deepgram LiveOptions for detailed configuration.
+        addons: Additional Deepgram features to enable.
+        **kwargs: Additional arguments passed to the parent STTService.
+    """
+
     def __init__(
         self,
         *,
@@ -108,12 +126,27 @@ class DeepgramSTTService(STTService):
 
     @property
     def vad_enabled(self):
+        """Check if Deepgram VAD events are enabled.
+
+        Returns:
+            True if VAD events are enabled in the current settings.
+        """
         return self._settings["vad_events"]
 
     def can_generate_metrics(self) -> bool:
+        """Check if this service can generate processing metrics.
+
+        Returns:
+            True, as Deepgram service supports metrics generation.
+        """
         return True
 
     async def set_model(self, model: str):
+        """Set the Deepgram model and reconnect.
+
+        Args:
+            model: The Deepgram model name to use.
+        """
         await super().set_model(model)
         logger.info(f"Switching STT model to: [{model}]")
         self._settings["model"] = model
@@ -121,25 +154,53 @@ class DeepgramSTTService(STTService):
         await self._connect()
 
     async def set_language(self, language: Language):
+        """Set the recognition language and reconnect.
+
+        Args:
+            language: The language to use for speech recognition.
+        """
         logger.info(f"Switching STT language to: [{language}]")
         self._settings["language"] = language
         await self._disconnect()
         await self._connect()
 
     async def start(self, frame: StartFrame):
+        """Start the Deepgram STT service.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
         self._settings["sample_rate"] = self.sample_rate
         await self._connect()
 
     async def stop(self, frame: EndFrame):
+        """Stop the Deepgram STT service.
+
+        Args:
+            frame: The end frame.
+        """
         await super().stop(frame)
         await self._disconnect()
 
     async def cancel(self, frame: CancelFrame):
+        """Cancel the Deepgram STT service.
+
+        Args:
+            frame: The cancel frame.
+        """
         await super().cancel(frame)
         await self._disconnect()
 
     async def run_stt(self, audio: bytes) -> AsyncGenerator[Frame, None]:
+        """Send audio data to Deepgram for transcription.
+
+        Args:
+            audio: Raw audio bytes to transcribe.
+
+        Yields:
+            Frame: None (transcription results come via WebSocket callbacks).
+        """
         await self._connection.send(audio)
         yield None
 
@@ -172,6 +233,7 @@ class DeepgramSTTService(STTService):
             await self._connection.finish()
 
     async def start_metrics(self):
+        """Start TTFB and processing metrics collection."""
         await self.start_ttfb_metrics()
         await self.start_processing_metrics()
 
@@ -235,6 +297,12 @@ class DeepgramSTTService(STTService):
                 )
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames with Deepgram-specific handling.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame processing.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, UserStartedSpeakingFrame) and not self.vad_enabled: