📝 Add docstrings to modernize

Docstrings generation was requested by @JarbasAl.

* #45 (comment)

The following files were modified:

* `ovos_stt_http_server/__init__.py`
* `ovos_stt_http_server/gradio_app.py`

Author: coderabbitai[bot]

ovos_stt_http_server/__init__.py

@@ -92,11 +92,38 @@ def unload_engine(self, lang: str):
             self.engines.pop(lang)
 
     def process_audio(self, audio: AudioData, lang: str):
+        """
+        Transcribes the provided audio using the engine for the specified language.
+        
+        Parameters:
+            audio (AudioData): Audio content to transcribe.
+            lang (str): Language code identifying which engine to use.
+        
+        Returns:
+            str: Transcribed text for the audio, or an empty string if no transcription is produced.
+        """
         engine = self.get_engine(lang)
         return engine.execute(audio, language=lang) or ""
 
 
 def create_app(stt_plugin, lang_plugin=None, multi=False, has_gradio=False):
+    """
+    Create and configure a FastAPI app that exposes STT and language-detection endpoints and returns the app with its model container.
+    
+    Configures CORS origins from the CORS_ORIGINS environment variable, initializes either a single-model or multi-model container using the provided plugins, and registers three endpoints:
+    - GET /status: returns service and plugin metadata.
+    - POST /stt: accepts raw audio bytes in the request body (query params: `lang`, `sample_rate`, `sample_width`), optionally performs language detection when `lang=auto`, and returns transcribed text.
+    - POST /lang_detect: accepts raw audio bytes and returns detected language and confidence (supports `valid_langs` query param).
+    
+    Parameters:
+        stt_plugin (str): Name or identifier of the STT plugin to load.
+        lang_plugin (str, optional): Name or identifier of an optional language-detection plugin. Defaults to None.
+        multi (bool, optional): If True, use a MultiModelContainer (one engine per language); otherwise use a single ModelContainer. Defaults to False.
+        has_gradio (bool, optional): Flag included in the /status response indicating whether a Gradio UI is available. Defaults to False.
+    
+    Returns:
+        tuple: (app, model) where `app` is the configured FastAPI application and `model` is the initialized ModelContainer or MultiModelContainer instance.
+    """
     app = FastAPI()
     cors_origins = os.environ.get("CORS_ORIGINS", "*")
     origins = [origin.strip() for origin in cors_origins.split(",")] if cors_origins != "*" else ["*"]
@@ -121,6 +148,18 @@ def stats(request: Request):
 
     @app.post("/stt", response_class=PlainTextResponse)
     async def get_stt(request: Request):
+        """
+        Handle an STT request: read audio from the request body, determine language if requested, and return the transcription.
+        
+        Parameters:
+            request (Request): HTTP request whose body contains raw audio bytes. Query parameters:
+                - lang: language code or "auto" (default from Configuration().get("lang", "auto")).
+                - sample_rate: sample rate in Hz for the audio (default 16000).
+                - sample_width: sample width in bytes (default 2).
+        
+        Returns:
+            str: Transcribed text from the provided audio, or an empty string if no transcription is produced.
+        """
         lang = str(request.query_params.get("lang", Configuration().get("lang", "auto"))).lower()
         sr = int(request.query_params.get("sample_rate", 16000))
         sw = int(request.query_params.get("sample_width", 2))
@@ -147,4 +186,4 @@ def start_stt_server(engine: str,
                      multi: bool = False,
                      has_gradio: bool = False) -> (FastAPI, ModelContainer):
     app, engine = create_app(engine, lang_engine, multi, has_gradio)
-    return app, engine
+    return app, engine

ovos_stt_http_server/gradio_app.py

@@ -1,4 +1,3 @@
-
 import gradio as gr
 
 from os.path import join, dirname, basename, splitext, isfile
@@ -10,6 +9,18 @@
 
 
 def transcribe(audio_file, language: str, sample_rate: int = 16000, sample_width: int = 2):
+    """
+    Transcribe an audio file into text using the configured STT engine.
+    
+    Parameters:
+        audio_file (str): Path to the audio file to transcribe.
+        language (str): Language code to use for transcription.
+        sample_rate (int): Sample rate in Hz for the provided audio (default 16000).
+        sample_width (int): Sample width in bytes for the provided audio (default 2).
+    
+    Returns:
+        transcription (str): The transcribed text, or `None` if the file is missing or invalid.
+    """
     try:
         with open(audio_file, 'rb') as f:
             audio = f.read()
@@ -22,7 +33,22 @@ def transcribe(audio_file, language: str, sample_rate: int = 16000, sample_width
 def bind_gradio_service(app, stt_engine: ModelContainer,
                         title, description, info, badge,
                         default_lang="en", cache=True):
-    global STT
+    """
+                        Create and mount a Gradio-based transcription UI at /gradio using the provided STT engine.
+                        
+                        Initializes the module STT with the given ModelContainer, prepares available language choices and example audio files, constructs a Gradio Interface configured to call the transcribe function, and mounts that interface to the supplied app at path "/gradio". This function logs a deprecation warning for the Gradio interface.
+                        
+                        Parameters:
+                            app: The web application or framework instance to which the Gradio interface will be mounted.
+                            stt_engine (ModelContainer): Speech-to-text engine container used to perform transcriptions and to obtain available languages.
+                            title (str): Title to display in the Gradio UI.
+                            description (str): Short description shown in the Gradio UI.
+                            info (str): Additional informational HTML or text displayed in the Gradio UI article section.
+                            badge: UI badge metadata (present for API compatibility; not used by this function).
+                            default_lang (str): Preferred default language code; if not available it will be adjusted or replaced with the first available language.
+                            cache (bool): Whether to cache example executions to speed up runtime after initial initialization.
+                        """
+                        global STT
     LOG.warning("gradio interface is deprecated and will be removed in a follow up release")
     STT = stt_engine
     languages = list(stt_engine.engine.available_languages or [default_lang])
@@ -61,4 +87,4 @@ def bind_gradio_service(app, stt_engine: ModelContainer,
         analytics_enabled=False)
 
     LOG.info(f"Mounting app to /gradio")
-    gr.mount_gradio_app(app, iface, path="/gradio")
+    gr.mount_gradio_app(app, iface, path="/gradio")