Release 2.0.2a3 (#30)

JarbasAl · github-actions[bot] · Delfshkrimm · web-flow · commit 831e69fd70bb · 2025-05-02T16:11:30.000+01:00
* Update downstream dependencies for ovos-openai-plugin * Update downstream dependencies for ovos-openai-plugin * Update downstream dependencies for ovos-openai-plugin * Update downstream dependencies for ovos-openai-plugin * Update downstream dependencies for ovos-openai-plugin * Merge pull request #19 from Delfshkrimm/patch-1 Use system_prompt in solver configuration (breaking change) * 📝 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> * Increment Version to 2.0.2a1 * Update Changelog * Update README.md * Update downstream dependencies for ovos-openai-plugin * Update README.md * Update README.md * Update README.md * Update release_workflow.yml * Increment Version to 2.0.2a2 * fix: setup.py (#29) * Increment Version to 2.0.2a3 * Update Changelog * Update __init__.py --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Delfshkrimm <mehdi.domec@live.fr> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: JarbasAI <33701864+JarbasAl@users.noreply.github.com> Co-authored-by: JarbasAl <JarbasAl@users.noreply.github.com>
diff --git a/.github/workflows/release_workflow.yml b/.github/workflows/release_workflow.yml
@@ -4,10 +4,10 @@ on:
   pull_request:
     types: [closed]
     branches: [dev]
+  workflow_dispatch:
 
 jobs:
   publish_alpha:
-    if: github.event.pull_request.merged == true
     uses: TigreGotico/gh-automations/.github/workflows/publish-alpha.yml@master
     secrets: inherit
     with:
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,16 +1,32 @@
 # Changelog
 
-## [2.0.1a1](https://github.com/OpenVoiceOS/ovos-openai-plugin/tree/2.0.1a1) (2025-04-10)
+## [2.0.2a3](https://github.com/OpenVoiceOS/ovos-openai-plugin/tree/2.0.2a3) (2025-05-02)
 
-[Full Changelog](https://github.com/OpenVoiceOS/ovos-openai-plugin/compare/V2.0.0...2.0.1a1)
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-openai-plugin/compare/2.0.2a2...2.0.2a3)
 
 **Merged pull requests:**
 
-- fix: params from config [\#24](https://github.com/OpenVoiceOS/ovos-openai-plugin/pull/24) ([JarbasAl](https://github.com/JarbasAl))
+- fix: setup.py [\#29](https://github.com/OpenVoiceOS/ovos-openai-plugin/pull/29) ([JarbasAl](https://github.com/JarbasAl))
 
-## [V2.0.0](https://github.com/OpenVoiceOS/ovos-openai-plugin/tree/V2.0.0) (2025-02-26)
+## [2.0.2a2](https://github.com/OpenVoiceOS/ovos-openai-plugin/tree/2.0.2a2) (2025-05-02)
 
-[Full Changelog](https://github.com/OpenVoiceOS/ovos-openai-plugin/compare/2.0.0...V2.0.0)
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-openai-plugin/compare/2.0.2a1...2.0.2a2)
+
+## [2.0.2a1](https://github.com/OpenVoiceOS/ovos-openai-plugin/tree/2.0.2a1) (2025-05-02)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-openai-plugin/compare/V2.0.1...2.0.2a1)
+
+**Breaking changes:**
+
+- Use system\_prompt in solver configuration \(breaking change\) [\#19](https://github.com/OpenVoiceOS/ovos-openai-plugin/pull/19) ([Delfshkrimm](https://github.com/Delfshkrimm))
+
+**Merged pull requests:**
+
+- 📝 Add docstrings to `patch-1` [\#26](https://github.com/OpenVoiceOS/ovos-openai-plugin/pull/26) ([coderabbitai[bot]](https://github.com/apps/coderabbitai))
+
+## [V2.0.1](https://github.com/OpenVoiceOS/ovos-openai-plugin/tree/V2.0.1) (2025-04-10)
+
+[Full Changelog](https://github.com/OpenVoiceOS/ovos-openai-plugin/compare/2.0.1...V2.0.1)
 
 
 
diff --git a/README.md b/README.md
@@ -18,10 +18,10 @@ To create your own persona using a OpenAI compatible server create a .json in `~
   "solvers": [
     "ovos-solver-openai-plugin"
   ],
-  "ovos-openai-plugin": {
+  "ovos-solver-openai-plugin": {
     "api_url": "https://llama.smartgic.io/v1",
     "key": "sk-xxxx",
-    "persona": "helpful, creative, clever, and very friendly."
+    "system_prompt": "You are helping assistant who gives very short and factual answers in maximum twenty words and you don't use emojis"
   }
 }
 ```
@@ -35,11 +35,11 @@ This plugins also provides a default "Remote LLama" demo persona, it points to a
 you can rewrite text dynamically based on specific personas, such as simplifying explanations or mimicking a specific tone.  
 
 #### Example Usage:
-- **Persona:** `"rewrite the text as if you were explaining it to a 5-year-old"`  
+- **`rewrite_prompt`:** `"rewrite the text as if you were explaining it to a 5-year-old"`  
 - **Input:** `"Quantum mechanics is a branch of physics that describes the behavior of particles at the smallest scales."`  
 - **Output:** `"Quantum mechanics is like a special kind of science that helps us understand really tiny things."`  
 
-Examples of `persona` Values:
+Examples of `rewrite_prompt` Values:
 - `"rewrite the text as if it was an angry old man speaking"`  
 - `"Add more 'dude'ness to it"`  
 - `"Explain it like you're teaching a child"`  
@@ -49,11 +49,14 @@ To enable this plugin, add the following to your `mycroft.conf`:
 ```json
 "dialog_transformers": {
     "ovos-dialog-transformer-openai-plugin": {
+        "system_prompt": "Your task is to rewrite text as if it was spoken by a different character",
         "rewrite_prompt": "rewrite the text as if you were explaining it to a 5-year-old"
     }
 }
 ```
 
+> 💡 the user utterance will be appended after `rewrite_prompt` for the actual query
+
 ## Direct Usage
 
 ```python
diff --git a/downstream_report.txt b/downstream_report.txt
@@ -1,3 +1,3 @@
-ovos-openai-plugin==2.0.0
-└── ovos-persona==0.6.16 [requires: ovos-openai-plugin>=2.0.0,<3.0.0]
-    └── ovos-core==1.2.3 [requires: ovos-persona>=0.4.4,<1.0.0]
+ovos-openai-plugin==2.0.2a1
+└── ovos-persona==0.6.20a4 [requires: ovos-openai-plugin>=2.0.0,<3.0.0]
+    └── ovos-core==1.2.6a1 [requires: ovos-persona>=0.4.4,<1.0.0]
diff --git a/ovos_solver_openai_persona/__init__.py b/ovos_solver_openai_persona/__init__.py
@@ -1,43 +1,19 @@
-from typing import Optional
-
+import warnings
 from ovos_solver_openai_persona.engines import OpenAIChatCompletionsSolver
 
-
 class OpenAIPersonaSolver(OpenAIChatCompletionsSolver):
-    """default "Persona" engine"""
-
-    def __init__(self, config=None):
-        # defaults to gpt-3.5-turbo
-        super().__init__(config=config)
-        self.default_persona = config.get("persona") or "helpful, creative, clever, and very friendly."
-
-    def get_chat_history(self, persona=None):
-        persona = persona or self.default_persona
-        initial_prompt = f"You are a helpful assistant. " \
-                         f"You give short and factual answers. " \
-                         f"You are {persona}"
-        return super().get_chat_history(initial_prompt)
-
-    # officially exported Solver methods
-    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.
-
-        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.
-
-        Returns:
-            str: The spoken answer as a text response.
-        """
-        answer = super().get_spoken_answer(query, lang, units)
-        if not answer or not answer.strip("?") or not answer.strip("_"):
-            return None
-        return answer
-
+    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,
+              stacklevel=2,
+           )
+           super().__init__(*args, **kwargs)
 
 # for ovos-persona
 LLAMA_DEMO = {
@@ -51,9 +27,8 @@ def get_spoken_answer(self, query: str,
   }
 }
 
-
 if __name__ == "__main__":
-    bot = OpenAIPersonaSolver(LLAMA_DEMO["ovos-solver-openai-plugin"])
+    bot = OpenAIChatCompletionsSolver(LLAMA_DEMO["ovos-solver-openai-plugin"])
     #for utt in bot.stream_utterances("describe quantum mechanics in simple terms"):
     #    print(utt)
         #  Quantum mechanics is a branch of physics that studies the behavior of atoms and particles at the smallest scales.
diff --git a/ovos_solver_openai_persona/dialog_transformers.py b/ovos_solver_openai_persona/dialog_transformers.py
@@ -7,19 +7,31 @@
 
 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"),
             'api_url': self.config.get('api_url', 'https://api.openai.com/v1'),
             "enable_memory": False,
-            "initial_prompt": "your task is to rewrite text as if it was spoken by a different character"
+            "system_prompt": self.config.get("system_prompt") or "Your task is to rewrite text as if it was spoken by a different character"
         })
 
     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:
diff --git a/ovos_solver_openai_persona/engines.py b/ovos_solver_openai_persona/engines.py
@@ -19,12 +19,18 @@ 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", "text-davinci-002")  # "ada" cheaper and faster, "davinci" better
+        self.engine = self.config.get("model", "gpt-4o-mini")
         self.key = self.config.get("key")
         if not self.key:
             LOG.error("key not set in config")
@@ -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")
@@ -107,10 +119,29 @@ def __init__(self, config=None,
         self.memory = config.get("enable_memory", True)
         self.max_utts = config.get("memory_size", 3)
         self.qa_pairs = []  # tuple of q+a
-        self.initial_prompt = config.get("initial_prompt", "You are a helpful assistant.")
+        if "persona" in config:
+            LOG.warning("'persona' config option is deprecated, use 'system_prompt' instead")
+        if "initial_prompt" in config:
+            LOG.warning("'initial_prompt' config option is deprecated, use 'system_prompt' instead")
+        self.system_prompt = config.get("system_prompt") or config.get("initial_prompt")
+        if not self.system_prompt:
+            self.system_prompt =  "You are a helpful assistant."
+            LOG.error(f"system prompt not set in config! defaulting to '{self.system_prompt}'")
 
     # 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",
@@ -141,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",
@@ -179,36 +221,60 @@ def _do_streaming_api_request(self, messages):
                     continue
                 yield chunk["choices"][0]["delta"]["content"]
 
-    def get_chat_history(self, initial_prompt=None):
+    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:]
-        initial_prompt = initial_prompt or self.initial_prompt or "You are a helpful assistant."
+        system_prompt = system_prompt or self.system_prompt or "You are a helpful assistant."
         messages = [
-            {"role": "system", "content": initial_prompt},
+            {"role": "system", "content": system_prompt},
         ]
         for q, a in qa:
             messages.append({"role": "user", "content": q})
             messages.append({"role": "assistant", "content": a})
         return messages
 
-    def get_messages(self, utt, initial_prompt=None) -> MessageList:
-        messages = self.get_chat_history(initial_prompt)
+    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
 
     # abstract Solver methods
     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
         response = self._do_api_request(messages)
         answer = post_process_sentence(response)
         if not answer or not answer.strip("?") or not answer.strip("_"):
@@ -218,7 +284,7 @@ def continue_chat(self, messages: MessageList,
             self.qa_pairs.append((query, answer))
         return answer
 
-    def stream_chat_utterances(self, messages: List[Dict[str, str]],
+    def stream_chat_utterances(self, messages: MessageList,
                                lang: Optional[str] = None,
                                units: Optional[str] = None) -> Iterable[str]:
         """
@@ -232,6 +298,8 @@ def stream_chat_utterances(self, messages: List[Dict[str, str]],
         Returns:
             Iterable[str]: An iterable of utterances.
         """
+        if messages[0]["role"] != "system":
+            messages = [{"role": "system", "content": self.system_prompt }] + messages
         answer = ""
         query = messages[-1]["content"]
         if self.memory:
diff --git a/ovos_solver_openai_persona/version.py b/ovos_solver_openai_persona/version.py
@@ -1,6 +1,6 @@
 # START_VERSION_BLOCK
 VERSION_MAJOR = 2
 VERSION_MINOR = 0
-VERSION_BUILD = 1
-VERSION_ALPHA = 0
+VERSION_BUILD = 2
+VERSION_ALPHA = 3
 # END_VERSION_BLOCK
diff --git a/setup.py b/setup.py
