From 79b6de19f2c084ccf620cb2f9433a5faa35a4de6 Mon Sep 17 00:00:00 2001 From: Heiko Joerg Schick Date: Tue, 5 Sep 2023 22:32:55 +0200 Subject: [PATCH] Added more documentation information for residual functions --- yolo.py | 163 ++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 134 insertions(+), 29 deletions(-) diff --git a/yolo.py b/yolo.py index e096b61..f22e43f 100755 --- a/yolo.py +++ b/yolo.py @@ -4,13 +4,11 @@ TODO: Description Sources: — https://github.com/wunderwuzzi23/yolo-ai-cmdbot """ - import os import platform import subprocess import sys - import argparse import distro import dotenv @@ -80,17 +78,74 @@ def set_openai_api_key(config): def print_config(config): """ Print config information. + + Given an input configuration dictionary, this function prints out the + current configurations per yolo.yaml. This includes details on "model", + "temperature", "max_tokens", "safety", and "shell". + + Parameters + ---------- + config : dict + A dictionary containing the various configuration parameters. It should have + the following keys: "model", "temperature", "max_tokens", "safety", "shell". """ print("Current configuration per yolo.yaml:") - print("* Model : " + str(config["model"])) - print("* Temperature : " + str(config["temperature"])) - print("* Max. Tokens : " + str(config["max_tokens"])) - print("* Safety : " + str(bool(config["safety"]))) - print("* Shell : " + str(config["shell"])) + print("— Model : " + str(config["model"])) + print("— Temperature : " + str(config["temperature"])) + print("— Max. Tokens : " + str(config["max_tokens"])) + print("— Safety : " + str(bool(config["safety"]))) + print("— Shell : " + str(config["shell"])) + +def get_os_friendly_name(): + """ + Returns a friendly name of the user's operating system. + + The function retrieves the current system platform name using the `platform.system()` function. + For Linux, it appends the distribution name retrieved from `distro.name(pretty=True)` to give a + more descriptive representation. For Darwin (Apple's macOS), it appends "macOS" to "Darwin" to + make the output clearer to the user. + + Returns + ------- + str + A friendly name for the user's operating system. It will be one of the following: + + - "Linux/" + - "Darwin/macOS" + - The system string returned by `platform.system()` if it's not Linux or Darwin. + """ + os_name = platform.system() + + if os_name == "Linux": + os_name = "Linux/" + distro.name(pretty=True) + elif os_name == "Darwin": + os_name = "Darwin/macOS" + + return os_name def get_full_prompt(user_prompt, shell): """ - Construct the prompt, finding the executing directiory so we can find the prompt.txty file. + Constructs a full prompt string by appending the user's prompt to a predefined prompt template + located in the 'prompt.txt' file. + + The function finds the absolute path of the currently executing file, and based on this path, + identifies the directory of 'prompt.txt'. It reads this file, replaces placeholders {shell} + and {os} in the text file with a passed shell parameter and the friendly name of the operating + system respectively. The user prompt is then appended to this pre-prompt. If the resulting + prompt does not end with a question mark or a period, a question mark is added at last. + + Parameters + ---------- + user_prompt : str + The prompt supplied by the user to be appended to the pre-prompt. + shell : str + The shell information to be inserted in the place of {shell} placeholder in 'prompt.txt'. + + Returns + ------- + str + The full prompt, constructed from the template prompt in 'prompt.txt', + user-provided shell info, the OS name, and the user-supplied prompt string. """ yolo_path = os.path.abspath(__file__) prompt_path = os.path.dirname(yolo_path) @@ -102,25 +157,12 @@ def get_full_prompt(user_prompt, shell): pre_prompt = pre_prompt.replace("{os}", get_os_friendly_name()) prompt = pre_prompt + user_prompt - # be nice and make it a question + # Be nice and make it a question. if prompt[-1:] != "?" and prompt[-1:] != ".": prompt+="?" return prompt -def get_os_friendly_name(): - """ - Get the name of the operating system. - """ - os_name = platform.system() - - if os_name == "Linux": - os_name = "Linux/" + distro.name(pretty=True) - elif os_name == "Darwin": - os_name = "Darwin/macOS" - - return os_name - def call_open_ai(config, query): """ Do we have a prompt from the user? @@ -129,7 +171,7 @@ def call_open_ai(config, query): print ("No user prompt specified.") sys.exit(-1) - # Load the correct prompt based on Shell and OS and append the user's prompt + # Load the correct prompt based on shell and OS and append the user's prompt. prompt = get_full_prompt(query, config["shell"]) # Make the first line also the system prompt @@ -151,7 +193,16 @@ def call_open_ai(config, query): def check_for_issue(response): """ - Todo + Checks the given response for any issues and raise an error when detected. + + The function checks if the supplied text response begins with any of a set of predefined + prefixes, which indicate a problem with the response. If such a prefix is found, an error + message is printed to the console in red, and the program exits with a -1 status code. + + Parameters + ---------- + response : str + A response text string that needs to be examined for any issues. """ prefixes = ("sorry", "i'm sorry", "the question is not clear", "i'm", "i am") if response.lower().startswith(prefixes): @@ -160,7 +211,18 @@ def check_for_issue(response): def check_for_markdown(response): """ - Odd corner case, sometimes ChatCompletion returns markdown + Checks for the presence of markdown formatting (specifically, code snippet markdown) in the + provided response. + + This function considers the presence of markdown formatting (specifically, code block + formatting marked by ```) in the `response` as an "odd corner case". If such a case is + detected, it prints an error message in red, along with the markdown-contained response, and + then terminates the program with a -1 status code. + + Parameters + ---------- + response : str + A response text string that needs to be examined for markdown formatting. """ if response.count("```",2): print(colored( @@ -170,14 +232,40 @@ def check_for_markdown(response): def missing_posix_display(): """ - Todo + Checks if the DISPLAY environment variable is set in a POSIX-compliant shell. + + This function runs a shell subprocess that outputs the value of the DISPLAY environment + variable. It then checks if this value is unset (i.e., equals a newline 'b'\\n'') in the + current shell environment. If the DISPLAY variable is unset, the function returns `True` + indicating a "missing" display; otherwise, it returns `False`. + + Returns + ------- + bool + `True` if the DISPLAY environment variable is unset or empty, `False` otherwise. """ display = subprocess.check_output("echo $DISPLAY", shell=True) + return display == b'\n' def prompt_user_input(config, response): """ - Todo + Print the command proposal in blue and prompt the user for next action based on the safety + configuration. + + The user is given options to execute, modify, or copy the command to clipboard if the safety + configuration is enabled (config["safety"] = True). If the safety configuration is off + (config["safety"] = False), the function automatically assumes an execution action ('Y' for + Yes). In a POSIX-compliant shell with no display available (checked using + `missing_posix_display()`), the 'copy to clipboard' option is omitted. + + Parameters + ---------- + config : dict + The system configurations dictionary which contains a "safety" key + to determine user prompt options. + response : str + The proposed command which is to be printed and may be executed by the user. """ print("Command: " + colored(response, 'blue')) @@ -197,7 +285,24 @@ def prompt_user_input(config, response): def evaluate_input(config, user_input, command): """ - Todo + Evaluate the user input to either execute, modify, or copy the command. + + Based on the user's response, this function takes action: + - If the user response is 'Y' or blank, the given command gets executed in the shell. + - If the user response is 'M', user can modify the command and the modified command is executed + recursively. + - If the user response is 'C', the command is copied to the clipboard. + + Parameters + ---------- + config : dict + The system configurations dictionary. It should contain a "shell" key specifying the shell + environment. + user_input : str + The user response which determines the course of action. It can be 'Y', 'n', 'm', 'c', + or '' (empty string). + command : str + The command which is either executed, modified, or copied to clipboard. """ if user_input.upper() == "Y" or user_input == "": if config["shell"] == "powershell.exe": @@ -254,7 +359,7 @@ def main(): if args.config: print_config(config) - #Enable color output on Windows using colorama + # Enable color output on Windows using colorama init() res_command = call_open_ai(config, user_prompt)