Added: markdown documentation (#66)

docs/gptty/config.md

@@ -0,0 +1,28 @@
+Module gptty.config
+===================
+
+Functions
+---------
+
+
+`get_config_data(config_file='gptty.ini')`
+:   The get_config_data() function reads a configuration file and returns a dictionary containing the parsed data. 
+    If the configuration file does not exist or does not contain a particular key, a default value is used. 
+    The default configuration values are defined in the function itself. 
+    By default, the function reads the gptty.ini configuration file, but you can specify a different file name by passing it as an argument.
+
+    The returned dictionary has the following keys:
+
+        api_key: An API key used to authenticate with the OpenAI API.
+        your_name: The name of the user (you) who is running the program.
+        gpt_name: The name of the GPT model to use.
+        output_file: The name of the output file to write the generated text to.
+        model: The ID of the GPT model to use.
+        temperature: The temperature value to use when generating text.
+        max_tokens: The maximum number of tokens to generate in the generated text.
+        max_context_length: The maximum number of tokens to use as context when generating text.
+        context_keywords_only: A boolean value indicating whether to use only the keywords in the context when generating text.
+        preserve_new_lines: A boolean value indicating whether to preserve new lines in the generated text.
+        verify_internet_endpoint: The internet endpoint to use when verifying the internet connection.
+
+    Note: This function uses the configparser module to parse configuration files.

docs/gptty/context.md

@@ -0,0 +1,63 @@
+Module gptty.context
+====================
+
+Functions
+---------
+
+
+`get_context(tag: str, max_context_length: int, output_file: str, model_name: str, context_keywords_only: bool = True, additional_context: str = '', model_type: str = None, question: str = None, debug: bool = False)`
+:   Returns a full query context for a given tag, question and additional context.
+
+    Parameters:
+        tag: str
+            Tag to identify a conversation with a specific topic
+        max_context_length: int
+            Maximum length of the context to return.
+        output_file: str
+            Path to the file to read the context from.
+        model_name: str
+            Name of the language model to use
+        context_keywords_only: bool, optional
+            If True, use only the most common phrases and words from the context and additional context.
+            Default is True.
+        additional_context: str, optional
+            Additional context to add to the context.
+            Default is an empty string.
+        model_type: str, optional
+            Type of the language model. If 'v1/chat/completions', return a list of dicts with 'role' and 'content' keys
+            If not, return a string.
+            Default is None.
+        question: str, optional
+            Question to add to the context. If None, return only the context.
+            Default is None.
+        debug: bool, optional
+            If True, print debug information.
+            Default is False.
+
+    Returns:
+        If `model_type` is 'v1/chat/completions', returns a list of dicts with 'role' and 'content' keys
+        If not, returns a string.
+
+
+`get_token_count(s, model_name)`
+:   Returns the number of tokens in a text string encoded using a specified model.
+
+    Args:
+
+        s (str): The input text string.
+        model_name (str): The name of the model used for encoding.
+
+    Returns:
+
+        num_tokens (int): The number of tokens in the encoded text string.
+
+
+`return_most_common_phrases(text: str, weight_recent=True) ‑> list`
+:   Returns a list of the most common noun phrases in the input text, with an option to weight more recent phrases more heavily.
+
+    Args:
+    - text (str): The input text.
+    - weight_recent (bool): If True, more recent phrases are weighted more heavily.
+
+    Returns:
+    - list: A list of the most common noun phrases in the input text. Each item in the list is a string representing a noun phrase.

docs/gptty/gptty.md

@@ -0,0 +1,103 @@
+Module gptty.gptty
+==================
+
+Functions
+---------
+
+
+`create_chat_room(configs={'api_key': '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', 'org_id': 'org-5S6J4UCSlZmQFBoi7415svhC', 'your_name': 'question', 'gpt_name': 'response', 'output_file': 'output.txt', 'model': 'gpt-4-0314', 'temperature': 0.0, 'max_tokens': 1500, 'max_context_length': 1000, 'context_keywords_only': True, 'preserve_new_lines': True, 'verify_internet_endpoint': 'google.com'}, log_responses: bool = True, config_path=None, verbose: bool = False)`
+:   This function creates a chat room using the OpenAI API to generate responses to user inputs. 
+    The user input is prompted and the response is displayed on the console. 
+    The chat session is continuously open until the user enters ':quit' or ':q' to terminate the session. 
+    The session log is stored in a csv file. 
+
+    Parameters:
+    - configs: A dictionary containing OpenAI API key, model name, temperature, max_tokens, max_context_length, context_keywords_only, preserve_new_lines, gpt_name and your_name.
+    - log_responses: A boolean indicating whether or not to log the responses in a csv file. Default is True.
+    - config_path: The path to the configuration file.
+    - verbose: A boolean indicating whether or not to print debugging information. Default is False.
+
+    Returns:
+    - None
+
+
+`fetch_response(prompt, model_engine, max_tokens, temperature, model_type)`
+:   This module provides a function to fetch a response from the OpenAI API based on the given prompt and model specifications.
+
+    Parameters:
+    - prompt (str): The prompt to use for the API request.
+    - model_engine (str): The engine ID to use for the API request.
+    - max_tokens (int): The maximum number of tokens to generate in the response.
+    - temperature (float): The temperature to use for the API request.
+    - model_type (str): The API endpoint to use for the API request.
+
+    Returns:
+    - OpenAICompletion: The completion response object from the OpenAI API.
+
+    Raises:
+    - Exception: If the model type is not recognized or supported.
+
+
+`get_available_models()`
+:   Returns:
+        - List: list of available OpenAI model IDs.
+
+
+`is_valid_model(model_name)`
+:   Validates whether a given model name is available in the OpenAI platform.
+
+    Parameters:
+    - model_name (str): The name of the model to validate.
+
+    Returns:
+    - bool: True if the model name is available, False otherwise.
+
+
+`run_query(questions: list, tag: str, configs={'api_key': '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', 'org_id': 'org-5S6J4UCSlZmQFBoi7415svhC', 'your_name': 'question', 'gpt_name': 'response', 'output_file': 'output.txt', 'model': 'gpt-4-0314', 'temperature': 0.0, 'max_tokens': 1500, 'max_context_length': 1000, 'context_keywords_only': True, 'preserve_new_lines': True, 'verify_internet_endpoint': 'google.com'}, additional_context: str = '', log_responses: bool = True, config_path=None, verbose: bool = False, return_json: bool = False, quiet: bool = False)`
+:   This function is used to run a query command using OpenAI. 
+    It takes in a list of questions, a tag, additional context, and various configuration options. 
+    It authenticates with OpenAI using the API key specified in the configuration file, and then continuously sends and receives messages until all the questions 
+    have been answered. The responses are either printed to the console in color or returned in a JSON format, depending on the options specified. Additionally, 
+    the function logs the questions and responses in a pandas dataframe if specified in the configuration file.
+
+    Parameters:
+        questions (list): a list of questions to ask the GPT-3 model
+        tag (str): a tag to associate with the questions and responses
+        configs (dict): a dictionary containing configuration options (default: get_config_data())
+        additional_context (str): additional context to provide to the GPT-3 model (default: "")
+        log_responses (bool): whether to log the questions and responses in a pandas dataframe (default: True)
+        config_path (str): the path to the configuration file (default: None)
+        verbose (bool): whether to enable debug mode (default: False)
+        return_json (bool): whether to return the responses in a JSON format (default: False)
+        quiet (bool): whether to suppress console output (default: False)
+
+    Returns:
+        None if the function fails to authenticate with OpenAI or if there are no questions to ask
+        if return_json is True and quiet is False, prints a JSON representation of the question/response data to the console and returns None
+        if return_json is True and quiet is True, returns a JSON representation of the question/response data
+        if return_json is False and quiet is False, prints the responses to the console in color and returns None
+        if return_json is False and quiet is True, returns None
+
+
+`usage_stats_today()`
+:   
+
+
+`validate_model_type(model_name)`
+:   Validates whether a given model name is a supported model type for OpenAI API completion requests.
+
+    Parameters:
+    - model_name (str): The name of the model to validate.
+
+    Returns:
+    - str: The API endpoint to use for completion requests if the model name is valid and supported.
+
+    Raises:
+    - Exception: If the model name is not valid or not supported.
+
+
+`wait_graphic()`
+:   This module provides a function to display a wait graphic while awaiting responses.
+
+    Returns:
+    - None

docs/gptty/index.md

@@ -0,0 +1,155 @@
+Module gptty
+============
+
+Sub-modules
+-----------
+* gptty.config
+* gptty.context
+* gptty.gptty
+* gptty.tagging
+
+Classes
+-------
+
+`UniversalCompletion(api_key: str = '', org_id: str = '', output_file: str = 'output.txt', your_name: str = 'question', gpt_name: str = 'response', model: str = 'text-davinci-003', temperature: float = 0.0, max_tokens: int = 250, max_context_length: int = 150, context_keywords_only: bool = True, preserve_new_lines: bool = False)`
+:   Initializes a new instance of the UniversalCompletion class.
+
+    Parameters:
+        api_key (str): The OpenAI API key.
+        org_id (str): The OpenAI organization ID.
+        output_file (str): The name of the file where the output should be stored.
+        your_name (str): The name that will be used to identify user inputs in the chat history.
+        gpt_name (str): The name that will be used to identify GPT outputs in the chat history.
+        model (str): The name of the model to use for generating text.
+        temperature (float): The temperature to use for the text generation process. Higher values make output more random.
+        max_tokens (int): The maximum number of tokens in the output text.
+        max_context_length (int): The maximum number of tokens in the input text.
+        context_keywords_only (bool): If True, only keywords from the input text are taken into account in the generation process.
+        preserve_new_lines (bool): If True, new lines in the output text are preserved.
+
+    Returns:
+        None
+
+    ### Methods
+
+    `a_fetch_response(self, prompt: Union[str, List[Dict[str, str]]], max_tokens: Optional[int] = None, temperature: Optional[float] = None, model_type: Optional[str] = None) ‑> Union[openai.api_resources.completion.Completion, openai.api_resources.chat_completion.ChatCompletion, None]`
+    :   Asynchronously fetches a response from the model based on the provided prompt.
+        
+        Parameters:
+            prompt (Union[str, List[Dict[str, str]]]): The input prompt for the model. This can either be a string or a list of message dictionaries for chat models.
+            max_tokens (Optional[int]): The maximum number of tokens for the model to generate. Defaults to None, in which case it uses the instance's default.
+            temperature (Optional[float]): The randomness factor for the model's output. Defaults to None, in which case it uses the instance's default.
+            model_type (Optional[str]): The type of the model. Defaults to None, in which case it uses the instance's default.
+        
+        Returns:
+            Optional[Union[openai.Completion, openai.ChatCompletion]]: The model's response as a Completion or ChatCompletion object, or None if the model type is not recognized.
+        
+        Example usage:
+            >>> g = UniversalCompletion(api_key="your-api-key", org_id="your-org-id")
+            >>> g.connect()
+            >>> g.set_model('gpt-3.5-turbo')
+            >>> prompt = [{"role": "user", "content": "What is an abstraction?"}]
+            >>> response = asyncio.run(g.a_fetch_response(prompt=prompt))
+            >>> print(response.choices[0].message['content'])
+
+    `build_context(self, prompt: str, context: List[Dict[str, str]], max_context_length: int, model_type: Optional[str] = None, context_keywords_only: bool = True, additional_context: str = '') ‑> Union[str, List[Dict[str, str]]]`
+    :   Builds a full query context for a given prompt and context.
+        
+        Parameters:
+            prompt (str): The main prompt to build the context around.
+            context (List[Dict[str, str]]): List of past prompts and responses.
+            max_context_length (int): Maximum length of the context to return.
+            model_type (Optional[str]): Type of the language model. If 'v1/chat/completions', return a list of dicts 
+                                        with 'role' and 'content' keys. If not, return a string. Default is None.
+            context_keywords_only (bool, optional): If True, use only the most common phrases and words from the context 
+                                                    and additional context. Default is True.
+            additional_context (str, optional): Additional context to add to the context. Default is an empty string.
+        
+        Returns:
+            Union[str, List[Dict[str, str]]]: If `model_type` is 'v1/chat/completions', returns a list of dicts with 
+                                              'role' and 'content' keys. If not, returns a string.
+
+    `connect(self, api_key=None, org_id=None) ‑> None`
+    :   Connects to the OpenAI API using the provided organization ID and API key.
+        
+        Parameters:
+            api_key (str): The OpenAI API key, defaults to the corresponding class element.
+            org_id (str): The OpenAI organization ID, defaults to the corresponding class element.
+        
+        Returns:
+            None
+
+    `fetch_response(self, prompt: Union[str, List[Dict[str, str]]], max_tokens: Optional[int] = None, temperature: Optional[float] = None, model_type: Optional[str] = None) ‑> Union[openai.api_resources.completion.Completion, openai.api_resources.chat_completion.ChatCompletion, None]`
+    :   Fetches a response from the model based on the provided prompt.
+        
+        Parameters:
+            prompt (Union[str, List[Dict[str, str]]]): The input prompt for the model. This can either be a string or a list of message dictionaries for chat models.
+            max_tokens (Optional[int]): The maximum number of tokens for the model to generate. Defaults to None, in which case it uses the instance's default.
+            temperature (Optional[float]): The randomness factor for the model's output. Defaults to None, in which case it uses the instance's default.
+            model_type (Optional[str]): The type of the model. Defaults to None, in which case it uses the instance's default.
+        
+        Returns:
+            Optional[Union[openai.Completion, openai.ChatCompletion]]: The model's response as a Completion or ChatCompletion object, or None if the model type is not recognized.
+        
+        Example usage:
+            >>> g = UniversalCompletion(api_key="your-api-key", org_id="your-org-id")
+            >>> g.connect()
+            >>> g.set_model('gpt-3.5-turbo')
+            >>> prompt = [{"role": "user", "content": "What is an abstraction?"}]
+            >>> response = g.fetch_response(prompt=prompt)
+            >>> print(response.choices[0].message['content'])
+
+    `get_available_models(self) ‑> List[str]`
+    :   Retrieves a list of available models from the OpenAI API.
+        
+        Parameters:
+            None
+        
+        Returns:
+            List[str]: A list of model IDs available for use.
+
+    `is_valid_model(self, model_name: str) ‑> bool`
+    :   Checks whether the given model name is valid and available.
+        
+        Parameters:
+            model_name (str): The name of the model to validate.
+        
+        Returns:
+            bool: True if the model name is valid and available, False otherwise.
+
+    `set_model(self, model_name: str) ‑> None`
+    :   Sets the model to be used for the class instance. The model name provided must be a valid and available model.
+        
+        Parameters:
+            model_name (str): The name of the model to set.
+        
+        Returns:
+            None
+        
+        Raises:
+            AssertionError: If the model name is not valid or available.
+
+    `usage_stats_today(self) ‑> Optional[Tuple[int, int, int]]`
+    :   Retrieves usage statistics for the current day from the OpenAI API.
+        
+        Parameters:
+            None
+        
+        Returns:
+            requests_today (int): The total number of requests made today.
+            query_tokens_today (int): The total number of context tokens used in queries today.
+            response_tokens_today (int): The total number of generated tokens in responses today.
+            
+        If any error occurs during the process, this method will return None.
+
+    `validate_model_type(self, model_name: str) ‑> str`
+    :   Validates the model type based on the model name provided.
+        
+        Parameters:
+            model_name (str): The name of the model to validate.
+        
+        Returns:
+            str: The corresponding API endpoint ('v1/completions' or 'v1/chat/completions') based on the model type.
+        
+        Raises:
+            Exception: If the model name does not match any of the known model types or is not a valid or available model.

docs/gptty/tagging.md

@@ -0,0 +1,18 @@
+Module gptty.tagging
+====================
+
+Functions
+---------
+
+
+`get_tag_from_text(user_input, replacement_string='-')`
+:   This function takes a user input and returns the first tag found within square brackets along with the remaining text after the tag. The square brackets are removed from the tag and any spaces within the tag are replaced with the provided replacement string. If no tag is found, an empty string is returned as the tag.
+
+    Parameters:
+
+        user_input (str): The input string to search for a tag.
+        replacement_string (str): The string to replace any spaces within the tag. Defaults to '-' if no replacement string is provided.
+
+    Returns:
+
+        Tuple: A tuple containing the tag (str) and the remaining text after the tag (str). If no tag is found, the tag will be an empty string.