Refactorings, add missing comments

gradle/dependencies.gradle

@@ -268,10 +268,10 @@ task installBinaries(type: Task) {
     readDependencies()
     apps.each { app ->
       if ('latest' == app.version) {
-        println(os + ": TODO Installing latest version of '" + app.binary + "'")
+        println(os + ": FIXME Installing latest version of '" + app.binary + "'")
       }
       else {
-        println(os + ": TODO Installing '" + app.binary + "' v" + app.version)
+        println(os + ": FIXME Installing '" + app.binary + "' v" + app.version)
       }
     }
   }

pyproject.toml

@@ -74,3 +74,9 @@ opentelemetry-api = ">=1.27.0"
 opentelemetry-sdk = ">=1.27.0"
 opentelemetry-proto = ">=1.27.0"
 pytz = ">=2024.1"
+
+[tool.black]
+fast = true
+config = true
+target-version = ["py310"]
+line-length = 120

src/demo/others/spinner_demo.py

@@ -1,10 +1,11 @@
-from askai.core.support.spinner import Spinner
 from hspylib.core.tools.commons import sysout
 from hspylib.modules.cli.vt100.vt_color import VtColor
 
 import os
 import pause
 
+from src.demo.devel.spinner import Spinner
+
 
 def echo(message: str, prefix: str | None = None, end=os.linesep) -> None:
     """Prints a message with a prefix followed by the specified end character.

src/main/askai/core/component/cache_service.py

@@ -270,7 +270,9 @@ def _get_role_(msg: BaseMessage) -> str:
                 )
 
     def read_memory(self) -> list[str]:
-        """TODO"""
+        """Reads and parses the memory from the context file.
+        :return: A list of non-empty, stripped strings split by roles (human, assistant, system).
+        """
         flags: int = re.MULTILINE | re.DOTALL | re.IGNORECASE
         memory: str = ASKAI_MEMORY_FILE.read_text()
         return list(

src/main/askai/core/component/internet_service.py

@@ -88,9 +88,14 @@ class InternetService(metaclass=Singleton):
 
     @classmethod
     def _url_to_icon(cls, url: str) -> str:
-        """TODO"""
+        """Replaces a URL with its corresponding icon URL from SITE_ICONS if available.
+        :param url: The URL to be replaced with its corresponding icon.
+        :return: The icon URL if found in SITE_ICONS, otherwise the original URL.
+        :raises KeyError: If the URL is not found in SITE_ICONS.
+        """
         return url.replace(url, cls.SITE_ICONS[url]) if cls.SITE_ICONS[url] else url
 
+
     @classmethod
     def wrap_response(cls, terms: str, output: str, search: SearchResult) -> str:
         """Format and wrap the search response based on the search terms, output, and method used.

src/main/askai/core/component/scheduler.py

@@ -296,15 +296,23 @@ def _call_it_back() -> None:
         self._add(f"Every-{callback.__name__}", _call_it_back)
 
     def _add(self, thread_name: str, callback: Callable, *args, **kwargs) -> None:
-        """TODO"""
+        """Adds a new thread to the '_not_started' internal list for management.
+        :param thread_name: The name of the thread to be added.
+        :param callback: The function to be executed by the thread.
+        :param args: Positional arguments to be passed to the callback.
+        :param kwargs: Keyword arguments to be passed to the callback.
+        :return: None
+        """
         th_new: Thread = Thread(
             name=thread_name, target=callback, args=args, kwargs=kwargs
         )
         self._not_started.append(th_new)
         self._threads[thread_name] = th_new
 
     def _remove(self, not_started: Thread) -> None:
-        """TODO"""
+        """Removes a thread from the '_not_started' internal list for management.
+        :param not_started: The thread to remove from the '_not_started' list
+        """
         self._not_started.remove(not_started)
 
 

src/main/askai/core/component/text_streamer.py

@@ -114,7 +114,13 @@ def _process(text: AnyStr, prefix: AnyStr = "", tempo: int = 1, language: Langua
     def stream_text(
         self, text: AnyStr, prefix: AnyStr = "", tempo: int = 1, language: Language = Language.EN_US
     ) -> None:
-        """TODO"""
+        """Streams the given text with a specified prefix, tempo, and language settings.
+        :param text: The text to be streamed.
+        :param prefix: A prefix to be added to the streamed text. Defaults to an empty string.
+        :param tempo: The tempo for streaming the text. Defaults to 1.
+        :param language: The language for the text being streamed. Defaults to Language.EN_US.
+        :raises ValueError: If the provided tempo is invalid.
+        """
         TextStreamer.STREAMER_THREAD = Thread(daemon=True, target=self._process, args=(text, prefix, tempo, language))
         TextStreamer.STREAMER_THREAD.start()
         TextStreamer.STREAMER_THREAD.join()

src/main/askai/core/engine/openai/openai_vision.py

@@ -2,15 +2,15 @@
 # -*- coding: utf-8 -*-
 
 """
-   @project: HsPyLib-AskAI
-   @package: askai.core.engine.openai
-      @file: openai_vision.py
-   @created: Tue, 5 Sep 2024
-    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
-      @site: https://github.com/yorevs/askai
-   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+@project: HsPyLib-AskAI
+@package: askai.core.engine.openai
+   @file: openai_vision.py
+@created: Tue, 5 Sep 2024
+ @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
+   @site: https://github.com/yorevs/askai
+@license: MIT - Please refer to <https://opensource.org/licenses/MIT>
 
-   Copyright (c) 2024, AskAI
+Copyright (c) 2024, AskAI
 """
 from typing import TypeAlias, Literal
 import os
@@ -72,11 +72,19 @@ def create_image_caption_chain(inputs: dict) -> MessageContent:
         return msg.content
 
     def image_template(self, question: str = "") -> str:
+        """Generates a formatted prompt for an image based on the given question.
+        :param question: Optional question to include in the image prompt.
+        :return: A string containing the formatted prompt for an image description.
+        """
         return PromptTemplate(input_variables=["question"], template=prompt.read_prompt("img-caption")).format(
             question=question
         )
 
     def screenshot_template(self, question: str = "") -> str:
+        """Generates a formatted prompt for a screenshot based on the given question.
+        :param question: Optional question to include in the screenshot prompt.
+        :return: A string containing the formatted prompt for a screenshot description.
+        """
         return PromptTemplate(input_variables=["question"], template=prompt.read_prompt("ss-caption")).format(
             question=question
         )
@@ -99,9 +107,7 @@ def caption(
         check_argument(len((final_path := str(find_file(final_path) or ""))) > 0, f"Invalid image path: {final_path}")
         vision_prompt: str = self._get_vision_prompt(query, image_type)
         load_image_chain = TransformChain(
-            input_variables=["image_path", "parser_guides"],
-            output_variables=["image"],
-            transform=self._encode_image
+            input_variables=["image_path", "parser_guides"], output_variables=["image"], transform=self._encode_image
         )
         out_parser: JsonOutputParser = self._get_out_parser(image_type)
         vision_chain = load_image_chain | self.create_image_caption_chain | out_parser
@@ -113,7 +119,11 @@ def caption(
         return str(vision_chain.invoke(args))
 
     def _get_out_parser(self, image_type: Literal["photo", "screenshot"]) -> JsonOutputParser:
-        """TODO"""
+        """Returns the appropriate JSON output parser based on the image type.
+        :param image_type: The type of image, either "photo" or "screenshot".
+        :return: An instance of JsonOutputParser configured for the specified image type.
+        :raises ValueError: If no parser is found for the given image type.
+        """
         match image_type:
             case "photo":
                 return JsonOutputParser(pydantic_object=ImageResult)
@@ -123,7 +133,12 @@ def _get_out_parser(self, image_type: Literal["photo", "screenshot"]) -> JsonOut
                 raise ValueError(f"Parser not found for: {image_type}")
 
     def _get_vision_prompt(self, query: str, image_type: Literal["photo", "screenshot"]) -> str:
-        """TODO"""
+        """Returns the appropriate vision prompt based on the image type and query.
+        :param query: The query string used to generate the vision prompt.
+        :param image_type: The type of image, either "photo" or "screenshot".
+        :return: A string containing the vision prompt tailored for the specified image type.
+        :raises ValueError: If no prompt is found for the given image type.
+        """
         match image_type:
             case "photo":
                 return self.image_template(query)

src/main/askai/core/enums/acc_color.py

@@ -2,15 +2,15 @@
 # -*- coding: utf-8 -*-
 
 """
-   @project: HsPyLib-AskAI
-   @package: askai.core.enums.acc_response
-      @file: acc_color.py
-   @created: Thu, 26 Sep 2024
-    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
-      @site: https://github.com/yorevs/askai
-   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
-
-   Copyright (c) 2024, AskAI
+@project: HsPyLib-AskAI
+@package: askai.core.enums.acc_response
+   @file: acc_color.py
+@created: Thu, 26 Sep 2024
+ @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
+   @site: https://github.com/yorevs/askai
+@license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+
+Copyright (c) 2024, AskAI
 """
 from typing import Literal, TypeAlias
 import logging as log
@@ -21,21 +21,29 @@
 
 
 class AccColor(Enumeration):
-    """TODO"""
+    """Represents various color-coded accuracy levels with associated values.
+    Each color corresponds to a specific status and numeric value.
+    """
 
     # fmt: off
 
-    INTERRUPT   = 'Black', -1
+    INTERRUPT = 'Black', -1
+    """Black color, indicating an interrupt status."""
 
-    TERMINATE   = 'White',  0
+    TERMINATE = 'White', 0
+    """White color, indicating a terminate status."""
 
-    EXCELLENT   = 'Blue',   1
+    EXCELLENT = 'Blue', 1
+    """Blue color, indicating an excellent status."""
 
-    GOOD        = 'Green',  2
+    GOOD = 'Green', 2
+    """Green color, indicating a good status."""
 
-    MODERATE    = 'Yellow', 3
+    MODERATE = 'Yellow', 3
+    """Yellow color, indicating a moderate status."""
 
-    BAD         = 'Red',    4
+    BAD = 'Red', 4
+    """Red color, indicating a bad status."""
 
     def __init__(self, color: AccuracyColors, weight: int):
         self._color: AccuracyColors = color

src/main/askai/core/enums/router_mode.py

@@ -2,15 +2,15 @@
 # -*- coding: utf-8 -*-
 
 """
-   @project: HsPyLib-AskAI
-   @package: askai.core.enums.router_mode
-      @file: router_mode.py
-   @created: Tue, 24 Jun 2024
-    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
-      @site: https://github.com/yorevs/askai
-   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
-
-   Copyright (c) 2024, AskAI
+@project: HsPyLib-AskAI
+@package: askai.core.enums.router_mode
+   @file: router_mode.py
+@created: Tue, 24 Jun 2024
+ @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
+   @site: https://github.com/yorevs/askai
+@license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+
+Copyright (c) 2024, AskAI
 """
 from askai.core.askai_configs import configs
 from askai.core.askai_messages import msg
@@ -94,7 +94,12 @@ def is_default(self) -> bool:
         return self == RouterMode.default()
 
     def welcome(self, **kwargs) -> Optional[str]:
-        """TODO"""
+        """Generates a welcome message based on the current router mode and optional context.
+        :param kwargs: Optional keyword arguments to customize the welcome message.
+            - sum_path: The path to the summary context (optional).
+            - sum_glob: The glob pattern for the summary files (optional).
+        :return: A string containing the welcome message, or None if no message is generated.
+        """
         match self:
             case RouterMode.QNA:
                 sum_path: str = get_or_default_by_key(kwargs, "sum_path", None)

src/main/askai/core/model/acc_response.py

@@ -2,15 +2,15 @@
 # -*- coding: utf-8 -*-
 
 """
-   @project: HsPyLib-AskAI
-   @package: askai.core.enums.acc_response
-      @file: acc_response.py
-   @created: Tue, 23 Apr 2024
-    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
-      @site: https://github.com/yorevs/askai
-   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
-
-   Copyright (c) 2024, AskAI
+@project: HsPyLib-AskAI
+@package: askai.core.enums.acc_response
+   @file: acc_response.py
+@created: Tue, 23 Apr 2024
+ @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
+   @site: https://github.com/yorevs/askai
+@license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+
+Copyright (c) 2024, AskAI
 """
 from askai.core.enums.acc_color import AccColor, AccuracyColors
 from askai.core.support.llm_parser import parse_field
@@ -49,7 +49,6 @@ def __str__(self):
         return f"{self.status} -> {self.details}"
 
     def __eq__(self, other: "AccResponse") -> bool:
-        """TODO"""
         return (
             self.acc_color == other.acc_color
             and self.accuracy == other.accuracy

src/main/askai/core/model/screenshot_result.py

@@ -11,15 +11,27 @@ class ScreenshotResult(BaseModel):
     """
 
     class DocumentModel(BaseModel):
-        """TODO"""
+        """Represents a model for storing document metadata and content overview.
+
+        Attributes:
+            page_number: The number of the page in the document.
+            header: The content of the document's header.
+            footer: The content of the document's footer.
+            content_overview: A brief overview of the document's content.
+        """
 
         page_number: int = Field(description="Document page number")
         header: str = Field(description="Document header content")
         footer: str = Field(description="Document footer content")
         content_overview: str = Field(description="Document content overview")
 
     class WebsiteModel(BaseModel):
-        """TODO"""
+        """Represents a model for storing website metadata.
+
+        Attributes:
+            website_description: A description of the website.
+            website_url: The URL of the website.
+        """
 
         website_description: str = Field(description="Website description")
         website_url: str = Field(description="Website URL")

src/main/askai/core/model/search_result.py

@@ -2,15 +2,15 @@
 # -*- coding: utf-8 -*-
 
 """
-   @project: HsPyLib-AskAI
-   @package: askai.core.model
-      @file: search_result.py
-   @created: Sun, 12 Mar 2024
-    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
-      @site: https://github.com/yorevs/askai
-   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+@project: HsPyLib-AskAI
+@package: askai.core.model
+   @file: search_result.py
+@created: Sun, 12 Mar 2024
+ @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior
+   @site: https://github.com/yorevs/askai
+@license: MIT - Please refer to <https://opensource.org/licenses/MIT>
 
-   Copyright (c) 2024, AskAI
+Copyright (c) 2024, AskAI
 """
 from askai.core.component.geo_location import geo_location
 from askai.core.support.llm_parser import parse_field, parse_list
@@ -56,7 +56,6 @@ def __str__(self):
         return f"Search Results: {json.dumps(self.__dict__, default=lambda obj: obj.__dict__)}"
 
     def __eq__(self, other: "SearchResult") -> bool:
-        """TODO"""
         return (
             self.category == other.category
             and self.keywords == other.keywords
@@ -65,5 +64,7 @@ def __eq__(self, other: "SearchResult") -> bool:
         )
 
     def build(self) -> str:
-        """TODO"""
+        """Builds the search result reference, by combining keywords, sites, and filters.
+        :return: A string containing the concatenated keywords, sites, and filters.
+        """
         return f"{self.keywords} {self.sites} {self.filters}"