📝 Add docstrings to patch-1 (#26)

* 📝 Add docstrings to `patch-1`

Docstrings generation was requested by @JarbasAl.

* #19 (comment)

The following files were modified:

* `ovos_solver_openai_persona/__init__.py`
* `ovos_solver_openai_persona/dialog_transformers.py`
* `ovos_solver_openai_persona/engines.py`

* Update engines.py

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: JarbasAI <33701864+JarbasAl@users.noreply.github.com>

Author: coderabbitai[bot]

ovos_solver_openai_persona/__init__.py

@@ -3,6 +3,11 @@
 
 class OpenAIPersonaSolver(OpenAIChatCompletionsSolver):
     def __init__(self, *args, **kwargs):
+           """
+           Initializes the solver and issues a deprecation warning.
+           
+           A DeprecationWarning is raised advising to use OpenAIChatCompletionsSolver instead.
+           """
            warnings.warn(
               "use OpenAIChatCompletionsSolver instead",
               DeprecationWarning,

ovos_solver_openai_persona/dialog_transformers.py

@@ -7,6 +7,11 @@
 
 class OpenAIDialogTransformer(DialogTransformer):
     def __init__(self, name="ovos-dialog-transformer-openai-plugin", priority=10, config=None):
+        """
+        Initializes the OpenAIDialogTransformer with a name, priority, and configuration.
+        
+        Creates an OpenAIChatCompletionsSolver using the provided API key, API URL, and a system prompt from the configuration or a default prompt if not specified.
+        """
         super().__init__(name, priority, config)
         self.solver = OpenAIChatCompletionsSolver({
             "key": self.config.get("key"),
@@ -17,9 +22,16 @@ def __init__(self, name="ovos-dialog-transformer-openai-plugin", priority=10, co
 
     def transform(self, dialog: str, context: dict = None) -> Tuple[str, dict]:
         """
-        Optionally transform passed dialog and/or return additional context
-        :param dialog: str utterance to mutate before TTS
-        :returns: str mutated dialog
+        Transforms the dialog string using a character-specific prompt if available.
+        
+        If a prompt is provided in the context or configuration, rewrites the dialog as if spoken by a different character using the solver; otherwise, returns the original dialog unchanged.
+        
+        Args:
+            dialog: The dialog string to be transformed.
+            context: Optional dictionary containing transformation context, such as a prompt or language.
+        
+        Returns:
+            A tuple containing the transformed (or original) dialog and the unchanged context.
         """
         prompt = context.get("prompt") or self.config.get("rewrite_prompt")
         if not prompt:

ovos_solver_openai_persona/engines.py

@@ -19,10 +19,16 @@ def __init__(self, config=None,
                  enable_tx: bool = False,
                  enable_cache: bool = False,
                  internal_lang: Optional[str] = None):
+        """
+        Initializes the OpenAICompletionsSolver with API configuration and credentials.
+         
+        Raises:
+            ValueError: If the API key is not provided in the configuration.
+        """
         super().__init__(config=config, translator=translator,
-                         detector=detector, priority=priority,
-                         enable_tx=enable_tx, enable_cache=enable_cache,
-                         internal_lang=internal_lang)
+                 detector=detector, priority=priority,
+                 enable_tx=enable_tx, enable_cache=enable_cache,
+                 internal_lang=internal_lang)
         self.api_url = f"{self.config.get('api_url', 'https://api.openai.com/v1')}/completions"
         self.engine = self.config.get("model", "gpt-4o-mini")
         self.key = self.config.get("key")
@@ -94,10 +100,16 @@ def __init__(self, config=None,
                  enable_tx: bool = False,
                  enable_cache: bool = False,
                  internal_lang: Optional[str] = None):
+        """
+        Initializes the OpenAIChatCompletionsSolver with API configuration, memory settings, and system prompt.
+         
+        Raises:
+            ValueError: If the API key is not provided in the configuration.
+        """
         super().__init__(config=config, translator=translator,
-                         detector=detector, priority=priority,
-                         enable_tx=enable_tx, enable_cache=enable_cache,
-                         internal_lang=internal_lang)
+                 detector=detector, priority=priority,
+                 enable_tx=enable_tx, enable_cache=enable_cache,
+                 internal_lang=internal_lang)
         self.api_url = f"{self.config.get('api_url', 'https://api.openai.com/v1')}/chat/completions"
         self.engine = self.config.get("model", "gpt-4o-mini")
         self.key = self.config.get("key")
@@ -118,6 +130,18 @@ def __init__(self, config=None,
 
     # OpenAI API integration
     def _do_api_request(self, messages):
+        """
+        Sends a chat completion request to the OpenAI API and returns the assistant's reply.
+        
+        Args:
+            messages: A list of message dictionaries representing the conversation history.
+        
+        Returns:
+            The content of the assistant's reply as a string.
+        
+        Raises:
+            RequestException: If the OpenAI API returns an error in the response.
+        """
         s = requests.Session()
         headers = {
             "Content-Type": "application/json",
@@ -148,6 +172,17 @@ def _do_api_request(self, messages):
 
     def _do_streaming_api_request(self, messages):
 
+        """
+        Streams response content from the OpenAI chat completions API.
+        
+        Sends a POST request with the provided chat messages and yields content chunks as they are received from the streaming API. Stops iteration if an error is encountered or the response is finished.
+        
+        Args:
+            messages: A list of chat message dictionaries to send as context.
+        
+        Yields:
+            str: Segments of the assistant's reply as they arrive from the API.
+        """
         s = requests.Session()
         headers = {
             "Content-Type": "application/json",
@@ -187,6 +222,15 @@ def _do_streaming_api_request(self, messages):
                 yield chunk["choices"][0]["delta"]["content"]
 
     def get_chat_history(self, system_prompt=None):
+        """
+        Builds the chat history as a list of messages, starting with a system prompt.
+        
+        Args:
+            system_prompt: Optional override for the system prompt message.
+        
+        Returns:
+            A list of message dictionaries representing the system prompt and the most recent user-assistant exchanges.
+        """
         qa = self.qa_pairs[-1 * self.max_utts:]
         system_prompt = system_prompt or self.system_prompt or "You are a helpful assistant."
         messages = [
@@ -198,6 +242,16 @@ def get_chat_history(self, system_prompt=None):
         return messages
 
     def get_messages(self, utt, system_prompt=None) -> MessageList:
+        """
+        Builds a list of chat messages including the system prompt, recent conversation history, and the current user utterance.
+        
+        Args:
+        	utt: The current user input to be appended as the latest message.
+        	system_prompt: Optional system prompt to use as the initial message.
+        
+        Returns:
+        	A list of message dictionaries representing the chat context for the API.
+        """
         messages = self.get_chat_history(system_prompt)
         messages.append({"role": "user", "content": utt})
         return messages
@@ -206,15 +260,18 @@ def get_messages(self, utt, system_prompt=None) -> MessageList:
     def continue_chat(self, messages: MessageList,
                       lang: Optional[str],
                       units: Optional[str] = None) -> Optional[str]:
-        """Generate a response based on the chat history.
+        """
+        Generates a chat response using the provided message history and updates memory if enabled.
+
+        If the first message is not a system prompt, prepends the system prompt. Processes the API response and returns a cleaned answer, or None if the answer is empty or only punctuation/underscores. Updates internal memory with the latest question and answer if memory is enabled.
 
         Args:
-            messages (List[Dict[str, str]]): List of chat messages, each containing 'role' and 'content'.
-            lang (Optional[str]): The language code for the response. If None, will be auto-detected.
-            units (Optional[str]): Optional unit system for numerical values.
+            messages: List of chat messages with 'role' and 'content' keys.
+            lang: Optional language code for the response.
+            units: Optional unit system for numerical values.
 
         Returns:
-            Optional[str]: The generated response or None if no response could be generated.
+            The generated response as a string, or None if no valid response is produced.
         """
         if messages[0]["role"] != "system":
             messages = [{"role": "system", "content": self.system_prompt }] + messages