docstrs

Author: JarbasAl

ovos_solver_openai_persona/engines.py

@@ -101,10 +101,10 @@ def __init__(self, config=None,
                  enable_cache: bool = False,
                  internal_lang: Optional[str] = None):
         """
-        Initializes the OpenAIChatCompletionsSolver with API configuration, memory settings, and system prompt.
-         
+        Initialize an OpenAIChatCompletionsSolver instance with API configuration, conversation memory settings, and system prompt.
+
         Raises:
-            ValueError: If the API key is not provided in the configuration.
+            ValueError: If the API key is missing from the configuration.
         """
         super().__init__(config=config, translator=translator,
                  detector=detector, priority=priority,
@@ -131,16 +131,16 @@ 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.
+        Send a chat completion request to the OpenAI API using the provided conversation history and return the assistant's reply.
         
-        Args:
-            messages: A list of message dictionaries representing the conversation history.
+        Parameters:
+            messages (list): Conversation history as a list of message dictionaries.
         
         Returns:
-            The content of the assistant's reply as a string.
+            str: The assistant's reply content.
         
         Raises:
-            RequestException: If the OpenAI API returns an error in the response.
+            RequestException: If the OpenAI API response contains an error.
         """
         s = requests.Session()
         headers = {
@@ -243,14 +243,14 @@ def get_chat_history(self, system_prompt=None):
 
     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.
+        Constructs a list of chat messages for the API, 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.
+        Parameters:
+        	utt: The current user input to be added 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.
+        	A list of message dictionaries representing the chat context.
         """
         messages = self.get_chat_history(system_prompt)
         messages.append({"role": "user", "content": utt})
@@ -261,17 +261,17 @@ def continue_chat(self, messages: MessageList,
                       lang: Optional[str],
                       units: Optional[str] = None) -> Optional[str]:
         """
-        Generates a chat response using the provided message history and updates memory if enabled.
+        Generate a chat response based on the provided message history and update conversation 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.
+        If the first message is not a system prompt, prepends the system prompt. Returns a cleaned response string, or None if the response is empty or contains only punctuation or underscores. Updates internal memory with the latest user message and answer when memory is enabled.
 
-        Args:
-            messages: List of chat messages with 'role' and 'content' keys.
-            lang: Optional language code for the response.
-            units: Optional unit system for numerical values.
+        Parameters:
+            messages (MessageList): List of chat messages, each with 'role' and 'content' keys.
+            lang (Optional[str]): Language code for the response.
+            units (Optional[str]): Unit system for numerical values.
 
         Returns:
-            The generated response as a string, or None if no valid response is produced.
+            Optional[str]: The generated response string, or None if no valid response is produced.
         """
         if messages[0]["role"] != "system":
             messages = [{"role": "system", "content": self.system_prompt }] + messages
@@ -322,15 +322,15 @@ def stream_utterances(self, query: str,
                           lang: Optional[str] = None,
                           units: Optional[str] = None) -> Iterable[str]:
         """
-        Stream utterances for the given query as they become available.
+        Yields partial responses for a query as they are generated by the chat completions API.
 
-        Args:
-            query (str): The query text.
-            lang (Optional[str]): Optional language code. Defaults to None.
-            units (Optional[str]): Optional units for the query. Defaults to None.
+        Parameters:
+            query (str): The user query to send to the chat model.
+            lang (Optional[str]): Language code for the response, if applicable.
+            units (Optional[str]): Units relevant to the query, if applicable.
 
         Returns:
-            Iterable[str]: An iterable of utterances.
+            Iterable[str]: An iterator yielding segments of the model's response as they become available.
         """
         messages = self.get_messages(query)
         yield from self.stream_chat_utterances(messages, lang, units)

ovos_solver_openai_persona/rag.py

@@ -100,16 +100,16 @@ def __init__(self, config: Optional[Dict[str, Any]] = None,
 
     def _search_vector_store(self, query: str) -> List[str]:
         """
-        Performs a search against the ovos-persona-server's vector store.
+        Searches the configured vector store for relevant text chunks matching the user query.
 
-        Args:
-            query (str): The user's query string.
+        Parameters:
+            query (str): The user's query string to search for relevant context.
 
         Returns:
-            List[str]: A list of relevant text chunks (content) retrieved from the vector store.
+            List[str]: A list of text chunks retrieved from the vector store that are relevant to the query.
 
         Raises:
-            RequestException: If the search API call fails or returns an error.
+            RequestException: If the search request fails or the response format is invalid.
         """
         search_url = f"{self.api_url}/vector_stores/{self.vector_store_id}/search"
         headers = {"Content-Type": "application/json"}
@@ -140,15 +140,17 @@ def _search_vector_store(self, query: str) -> List[str]:
 
     def _build_llm_messages(self, user_query: str, retrieved_context_chunks: List[str], chat_history: List[Dict[str, str]]) -> List[Dict[str, str]]:
         """
-        Constructs the complete message list for the LLM, including RAG context and chat history.
+        Constructs the message list for the LLM by combining retrieved context, recent chat history, and the current user query.
 
-        Args:
-            user_query (str): The current user's utterance.
-            retrieved_context_chunks (List[str]): List of text chunks retrieved from the vector store.
-            chat_history (List[Dict[str, str]]): The conversation history from `self.qa_pairs`.
+        The method concatenates relevant context chunks (up to a token limit), formats the system prompt with this context and the user's question, appends recent Q&A pairs from memory, and adds the current user query as the final message.
+
+        Parameters:
+            user_query (str): The user's current question or utterance.
+            retrieved_context_chunks (List[str]): Relevant text segments retrieved from the vector store.
+            chat_history (List[Dict[str, str]]): Previous conversation history.
 
         Returns:
-            List[Dict[str, str]]: A new list of messages, augmented with the RAG context and history.
+            List[Dict[str, str]]: The complete list of messages to send to the LLM, including system prompt, chat history, and user query.
         """
         context_str = ""
         current_context_tokens = 0
@@ -186,8 +188,10 @@ def _build_llm_messages(self, user_query: str, retrieved_context_chunks: List[st
 
     def get_chat_history(self) -> List[Dict[str, str]]:
         """
-        Returns the chat history managed by this RAG solver.
-        This method is called by the base ChatMessageSolver.
+        Return the recent chat history as a list of user and assistant messages.
+
+        Returns:
+            List of message dictionaries representing the most recent question-answer pairs, formatted with roles 'user' and 'assistant'.
         """
         # The base class expects a list of messages (role, content).
         # We store (query, answer) tuples.
@@ -202,17 +206,18 @@ def continue_chat(self, messages: List[Dict[str, str]],
                       lang: Optional[str],
                       units: Optional[str] = None) -> Optional[str]:
         """
-        Generates a chat response using RAG by directly calling the Persona Server's
-        chat completions endpoint.
+        Generate a chat response by augmenting the user query with retrieved context from a vector store and sending the constructed prompt to the Persona Server's chat completions endpoint.
 
-        Args:
-            messages: List of chat messages with 'role' and 'content' keys.
-                      The last user message is used for RAG retrieval and as the current query.
-            lang: Optional language code for the response.
-            units: Optional unit system for numerical values.
+        Parameters:
+            messages (List[Dict[str, str]]): List of chat messages, where the last message is treated as the current user query.
+            lang (Optional[str]): Optional language code for the response.
+            units (Optional[str]): Optional unit system for numerical values.
 
         Returns:
-            The generated response as a string, or None if no valid response is produced.
+            Optional[str]: The generated response as a string, or None if no valid response is produced.
+
+        Raises:
+            RequestException: If the Persona Server's chat completions endpoint returns an error or an invalid response.
         """
         user_query = messages[-1]["content"] # Get the current user query
 
@@ -265,16 +270,17 @@ def stream_chat_utterances(self, messages: List[Dict[str, str]],
                                lang: Optional[str] = None,
                                units: Optional[str] = None) -> Iterable[str]: # Yields raw data: lines
         """
-        Stream utterances for the given chat history using RAG by directly calling the Persona Server's
-        chat completions endpoint in streaming mode.
+        Streams chat completion responses from the Persona Server using Retrieval Augmented Generation (RAG), yielding each line of streamed data as it arrives.
 
-        Args:
-            messages: The chat messages. The last user message is used for RAG retrieval and as the current query.
-            lang (Optional[str]): Optional language code. Defaults to None.
-            units (Optional[str]): Optional units for the query. Defaults to None.
+        The method retrieves relevant context from the vector store based on the latest user query, augments the chat history, and streams the LLM's response line by line. If enabled, it stores the full answer in memory for multi-turn conversations.
+
+        Parameters:
+            messages (List[Dict[str, str]]): The chat history, with the last message as the current user query.
+            lang (Optional[str]): Optional language code for the query.
+            units (Optional[str]): Optional units for the query.
 
         Returns:
-            Iterable[str]: An iterable of raw data: [JSON] strings from the streaming API.
+            Iterable[str]: Yields each raw data line (as a string) from the streaming API response.
         """
         user_query = messages[-1]["content"] # Get the current user query
 
@@ -339,15 +345,15 @@ def stream_utterances(self, query: str,
                           lang: Optional[str] = None,
                           units: Optional[str] = None) -> Iterable[str]:
         """
-        Stream utterances for the given query using RAG.
+        Streams the assistant's response for a given user query, incorporating current chat history and Retrieval Augmented Generation context.
 
-        Args:
-            query (str): The query text.
-            lang (Optional[str]): Optional language code. Defaults to None.
-            units (Optional[str]): Optional units for the query. Defaults to None.
+        Parameters:
+            query (str): The user's input query.
+            lang (Optional[str]): Language code for the response, if applicable.
+            units (Optional[str]): Units relevant to the query, if applicable.
 
         Returns:
-            Iterable[str]: An iterable of raw data: [JSON] strings from the streaming API.
+            Iterable[str]: Yields raw data chunks from the streaming chat completions API.
         """
         # For stream_utterances, we directly build a single-turn message list
         # We need to include existing chat history here as well for proper context
@@ -359,15 +365,15 @@ def get_spoken_answer(self, query: str,
                           lang: Optional[str] = None,
                           units: Optional[str] = None) -> Optional[str]:
         """
-        Obtain the spoken answer for a given query using RAG.
+        Return the assistant's spoken answer to a user query, incorporating recent chat history for context.
 
-        Args:
-            query (str): The query text.
-            lang (Optional[str]): Optional language code. Defaults to None.
-            units (Optional[str]): Optional units for the query. Defaults to None.
+        Parameters:
+            query (str): The user's input question.
+            lang (Optional[str]): Language code for the response, if specified.
+            units (Optional[str]): Units relevant to the query, if specified.
 
         Returns:
-            str: The spoken answer as a text response.
+            Optional[str]: The assistant's text response, or None if no answer is generated.
         """
         # For get_spoken_answer, we need to include existing chat history
         messages: List[Dict[str, str]] = self.get_chat_history()
@@ -376,8 +382,13 @@ def get_spoken_answer(self, query: str,
 
     def get_messages(self, utt: str, system_prompt: Optional[str] = None) -> List[Dict[str, str]]:
         """
-        Builds a message list including the RAG solver's chat history and the current user utterance.
-        The system prompt for the LLM is constructed dynamically in _build_llm_messages.
+        Return the current chat history messages with the latest user utterance appended.
+
+        Parameters:
+        	utt (str): The current user utterance to add to the message list.
+
+        Returns:
+        	List of message dictionaries representing the conversation history plus the new user message.
         """
         messages = self.get_chat_history()
         messages.append({"role": "user", "content": utt})