Enhance documentation and improve code readability across multiple mo…

…dules

.github/workflows/python-lint.yml

@@ -22,8 +22,12 @@ jobs:
     - name: Install linting tools
       run: |
         python -m pip install --upgrade pip
-        pip install flake8
+        pip install flake8 pylint
 
     - name: Lint with flake8
       run: |
-        flake8 .
+        flake8 .
+
+    - name: Lint with pylint
+      run: |
+        pylint $(git ls-files '*.py')

classes/json_wrapper.py

@@ -1,7 +1,17 @@
+"""
+This module provides a JsonWrapper class for handling JSON file operations.
+It includes functionality for reading, writing, and managing JSON files.
+"""
+
 import json
 
 
 class JsonWrapper:
+    """
+    A utility class for reading, writing, and managing JSON files.
+    Provides methods for reading JSON and text files, writing JSON data,
+    and clearing JSON file contents.
+    """
     @staticmethod
     def read_json(file_path):
         """
@@ -13,11 +23,11 @@ def read_json(file_path):
             str: The contents of the JSON file as a pretty-printed JSON string.
         """
 
-        with open(file_path, 'r') as file:
+        with open(file_path, 'r', encoding='utf-8') as file:
             data = json.load(file)
             return json.dumps(data, indent=4)
 
-    def read_txt(file_path):
+    def read_txt(self, file_path):
         """
         Reads a text file and returns its contents as a string.
         Args:
@@ -26,7 +36,7 @@ def read_txt(file_path):
             str: The contents of the text file as a string.
         """
 
-        with open(file_path, 'r') as file:
+        with open(file_path, 'r', encoding='utf-8') as file:
             return file.read()
 
     @staticmethod
@@ -41,7 +51,7 @@ def write(file_path, data):
             IOError: If the file cannot be opened or written to.
         """
 
-        with open(file_path, 'a') as file:
+        with open(file_path, 'a', encoding='utf-8') as file:
             json.dump(data, file, indent=4)
 
     @staticmethod
@@ -54,7 +64,7 @@ def delete(file_path):
             IOError: If the file cannot be deleted.
         """
 
-        with open(file_path, 'r') as file:
+        with open(file_path, 'r', encoding='utf-8') as file:
             data = json.load(file)
 
         if isinstance(data, list):
@@ -65,5 +75,5 @@ def delete(file_path):
             raise ValueError(
                 "The file does not contain a JSON object or array.")
 
-        with open(file_path, 'w') as file:
+        with open(file_path, 'w', encoding='utf-8') as file:
             json.dump(empty_data, file, indent=4)

classes/osc.py

@@ -1,7 +1,21 @@
+"""
+Module for handling OSC (Open Sound Control) communications with VRChat.
+This module provides a class for sending messages and managing typing
+indicators in the VRChat chatbox through OSC protocol. It utilizes the
+python-osc library for UDP client functionality.
+Classes:
+    VRChatOSC: A class for managing OSC communications with VRChat chatbox.
+"""
+
 from pythonosc import udp_client
 
 
 class VRChatOSC:
+    """
+    A class for managing OSC communications with VRChat chatbox.
+    Provides methods for sending messages and controlling typing indicators
+    through OSC protocol.
+    """
     def __init__(self, ip: str, port: int):
         """
         Initializes the OSC client with the specified IP address and port.

classes/system_prompt.py

@@ -1,7 +1,36 @@
+"""
+A class that handles system prompts for an AI assistant.
+This class provides static methods to manage and retrieve prompts from
+a 'prompts' directory. It can combine mood-specific prompts with additional
+prompt content to create comprehensive system instructions.
+The class assumes a specific directory structure where prompt files are
+stored in a 'prompts' directory, with filenames that begin with a mood
+identifier followed by underscores.
+Example:
+    full_prompt = SystemPrompt.get_full_prompt('happy')
+Attributes:
+    None
+Methods:
+    get_prompt_directory(): Returns a dictionary of prompt files.
+    get_full_prompt(mood): Returns combined prompt content for a specific mood.
+"""
 import os
 
 
 class SystemPrompt:
+    """
+    A class that handles system prompts for an AI assistant.
+
+    This class provides static methods to manage and retrieve prompts from
+    a 'prompts' directory. It combines mood-specific prompts with additional
+    prompt content to create comprehensive system instructions.
+
+    Methods:
+        get_prompt_directory(): Returns a dictionary of prompt files.
+        get_full_prompt(mood): Returns combined prompt content for a specific
+        mood.
+    """
+
     @staticmethod
     def get_prompt_directory():
         """
@@ -51,10 +80,11 @@ def get_full_prompt(mood):
         mood_prompt_path = prompt_dict[mood]
         additional_prompt_path = prompt_dict['additional']
 
-        with open(mood_prompt_path, 'r') as mood_file:
+        with open(mood_prompt_path, 'r', encoding='utf-8') as mood_file:
             mood_prompt_content = mood_file.read()
 
-        with open(additional_prompt_path, 'r') as additional_file:
+        with open(additional_prompt_path, 'r',
+                  encoding='utf-8') as additional_file:
             additional_prompt_content = additional_file.read()
 
         return mood_prompt_content + "\n" + additional_prompt_content

classes/whisper.py

@@ -1,13 +1,39 @@
-import whisper
-import pyaudio
+"""
+This module provides functionality for transcribing speech to text using
+OpenAI's Whisper model. It includes audio recording capabilities and silence
+detection for automatic recording termination.
+"""
+
 import wave
+import pyaudio
+import whisper
 from pydub import AudioSegment
 
 
 class WhisperTranscriber:
+    """
+    A class for transcribing speech to text using OpenAI's Whisper model.
+    Provides functionality for real-time audio recording and transcription,
+    as well as transcription from existing audio files.
+    """
+
     def __init__(self):
+        """Initialize the WhisperTranscriber with the base Whisper model."""
         self.model = whisper.load_model("base")
 
+    def transcribe_file(self, audio_file_path):
+        """
+        Transcribe an existing audio file using the Whisper model.
+
+        Args:
+            audio_file_path (str): Path to the audio file to transcribe
+
+        Returns:
+            str: The transcribed text from the audio file
+        """
+        result = self.model.transcribe(audio_file_path)
+        return result['text']
+
     def get_speech_input(self):
         """
         Records audio input from the microphone, detects silence to stop
@@ -22,15 +48,15 @@ def get_speech_input(self):
         p = pyaudio.PyAudio()
 
         # Set audio recording parameters
-        format = pyaudio.paInt16
+        audio_format = pyaudio.paInt16
         channels = 1
         rate = 16000
         chunk = 1024
         silence_threshold = -40  # Silence threshold in dB
         silence_duration = 1000  # Duration of silence in ms (1 second)
 
         # Open the audio stream
-        stream = p.open(format=format,
+        stream = p.open(format=audio_format,
                         channels=channels,
                         rate=rate,
                         input=True,
@@ -47,7 +73,7 @@ def get_speech_input(self):
             # Convert audio chunk to Pydub's AudioSegment for silence detection
             audio_chunk = AudioSegment(
                 data,
-                sample_width=p.get_sample_size(format),
+                sample_width=p.get_sample_size(audio_format),
                 frame_rate=rate,
                 channels=channels
             )

commit_history.py

@@ -1,17 +1,42 @@
+"""
+GitHub Commit History Module
+
+This module provides functionality to fetch commit history from GitHub
+repositories and write it to a markdown file. It uses GitHub's REST API to
+retrieve commit information and formats it into a readable markdown document.
+
+Functions:
+    fetch_commits(repo_owner, repo_name): Fetches commit data from GitHub
+    write_commits_to_file(commits, file_path): Writes commits to markdown
+    main(): Entry point that demonstrates the module usage
+"""
+
 import requests
 
 
 def fetch_commits(repo_owner, repo_name):
+    """
+    Module for fetching commit history from GitHub repositories using the
+    GitHub API. This module provides functionality to interact with GitHub's
+    REST API to retrieve commit information for specified repositories.
+    """
+
     commits_url = (
         f"https://api.github.com/repos/{repo_owner}/{repo_name}/commits"
     )
-    response = requests.get(commits_url)
+    response = requests.get(commits_url, timeout=10)
     response.raise_for_status()  # Check for request errors
     return response.json()
 
 
 def write_commits_to_file(commits, file_path):
-    with open(file_path, 'w') as file:
+    """
+    Module for handling Git commit history and writing it to a file in
+    Markdown format. This module provides functionality to create a formatted
+    commit history log.
+    """
+
+    with open(file_path, 'w', encoding='utf-8') as file:
         file.write("# Commit History\n\n")
         for commit in commits:
             sha = commit['sha']
@@ -24,6 +49,20 @@ def write_commits_to_file(commits, file_path):
 
 
 def main():
+    """
+    Main function to fetch and write GitHub repository commits to a file.
+    The function uses predefined repository details:
+    - Repository owner: "S0L0GUY"
+    - Repository name: "NOVA-AI"
+    - Output file path: "commits.md"
+    It fetches all commits from the specified repository and writes them to a
+    markdown file.
+    Requires:
+    - fetch_commits() function to get commits from GitHub
+    - write_commits_to_file() function to write commits to file
+    Prints a confirmation message once the commits are written to the file.
+    """
+
     repo_owner = "S0L0GUY"
     repo_name = "NOVA-AI"
     file_path = "commits.md"

constants.py

@@ -1,4 +1,27 @@
+"""
+Constants module for Nova AI project.
+This module contains all the configuration constants used throughout the
+project.
+Constants:
+    Network Settings:
+        LOCAL_IP (str): Local IP address of the computer
+        VRC_PORT (int): VRChat port number, default is 9000
+    Audio Settings:
+        AUDIO_OUTPUT_INDEX (int): Index number for audio output device
+        (VB-Audio Cable B)
+    Language Model Settings:
+        MODEL_ID (str): Identifier for the language model being used
+        LM_TEMPERATURE (float): Temperature setting for language model output
+        generation
+    File Paths:
+        HISTORY_PATH (str): Path to the history JSON file
+Note:
+    Make sure to adjust LOCAL_IP and AUDIO_OUTPUT_INDEX according to your
+    system configuration.
+"""
+
 # Network Settings
+
 LOCAL_IP = "192.168.0.195"  # Your computers local IP
 VRC_PORT = 9000  # VR Chat VRC_PORT, 9000 is the default