Task-330 Setup basic documentation

Pipfile

@@ -15,6 +15,8 @@ joblib = "*"
 nltk = "*"
 htbuilder = "*"
 nest-asyncio = "*"
+mkdocs = "*"
+mkdocstrings-python = "*"
 
 [dev-packages]
 

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "675e02cbb23625b60f9b1ab6ac0ae5b84786b0def940f4f98e8000207075ba67"
+            "sha256": "011a0284b34b98265fb35b5b99964b701b6a30f703a45de6b092a7d7c631032d"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -167,7 +167,7 @@
                 "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44",
                 "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"
             ],
-            "markers": "platform_system == 'Windows'",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6'",
             "version": "==0.4.6"
         },
         "filelock": {
@@ -186,6 +186,13 @@
             "markers": "python_version >= '3.8'",
             "version": "==2025.3.0"
         },
+        "ghp-import": {
+            "hashes": [
+                "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619",
+                "sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343"
+            ],
+            "version": "==2.1.0"
+        },
         "gitdb": {
             "hashes": [
                 "sha256:5ef71f855d191a3326fcfbc0d5da835f26b13fbcba60c32c21091c349ffdb571",
@@ -202,6 +209,14 @@
             "markers": "python_version >= '3.7'",
             "version": "==3.1.44"
         },
+        "griffe": {
+            "hashes": [
+                "sha256:3a46fa7bd83280909b63c12b9a975732a927dd97809efe5b7972290b606c5d91",
+                "sha256:6399f7e663150e4278a312a8e8a14d2f3d7bd86e2ef2f8056a1058e38579c2ee"
+            ],
+            "markers": "python_version >= '3.9'",
+            "version": "==1.6.2"
+        },
         "htbuilder": {
             "hashes": [
                 "sha256:58c0bc5502c1a46b42ae9e074c43ec0f6fdc24ed334936cb17e1ed5a8938aee2"
@@ -260,6 +275,14 @@
             "markers": "python_version >= '3.9'",
             "version": "==2024.10.1"
         },
+        "markdown": {
+            "hashes": [
+                "sha256:2ae2471477cfd02dbbf038d5d9bc226d40def84b4fe2986e49b59b6b472bbed2",
+                "sha256:7eb6df5690b81a1d7942992c97fad2938e956e79df20cbc6186e9c3a77b1c803"
+            ],
+            "markers": "python_version >= '3.8'",
+            "version": "==3.7"
+        },
         "markupsafe": {
             "hashes": [
                 "sha256:0bff5e0ae4ef2e1ae4fdf2dfd5b76c75e5c2fa4132d05fc1b0dabcd20c7e28c4",
@@ -327,6 +350,56 @@
             "markers": "python_version >= '3.9'",
             "version": "==3.0.2"
         },
+        "mergedeep": {
+            "hashes": [
+                "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8",
+                "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==1.3.4"
+        },
+        "mkdocs": {
+            "hashes": [
+                "sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2",
+                "sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e"
+            ],
+            "index": "pypi",
+            "markers": "python_version >= '3.8'",
+            "version": "==1.6.1"
+        },
+        "mkdocs-autorefs": {
+            "hashes": [
+                "sha256:4b5b6235a4becb2b10425c2fa191737e415b37aa3418919db33e5d774c9db079",
+                "sha256:9793c5ac06a6ebbe52ec0f8439256e66187badf4b5334b5fde0b128ec134df4f"
+            ],
+            "markers": "python_version >= '3.9'",
+            "version": "==1.4.1"
+        },
+        "mkdocs-get-deps": {
+            "hashes": [
+                "sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c",
+                "sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134"
+            ],
+            "markers": "python_version >= '3.8'",
+            "version": "==0.2.0"
+        },
+        "mkdocstrings": {
+            "hashes": [
+                "sha256:3657be1384543ce0ee82112c3e521bbf48e41303aa0c229b9ffcccba057d922e",
+                "sha256:8ea98358d2006f60befa940fdebbbc88a26b37ecbcded10be726ba359284f73d"
+            ],
+            "markers": "python_version >= '3.9'",
+            "version": "==0.29.0"
+        },
+        "mkdocstrings-python": {
+            "hashes": [
+                "sha256:211b7aaf776cd45578ecb531e5ad0d3a35a8be9101a6bfa10de38a69af9d8fd8",
+                "sha256:9453ccae69be103810c1cf6435ce71c8f714ae37fef4d87d16aa92a7c800fe1d"
+            ],
+            "index": "pypi",
+            "markers": "python_version >= '3.9'",
+            "version": "==1.16.8"
+        },
         "mpmath": {
             "hashes": [
                 "sha256:7a28eb2a9774d00c7bc92411c19a89209d5da7c4c9a9e227be8330a23a25b91f",
@@ -487,6 +560,14 @@
             "markers": "python_version >= '3.9'",
             "version": "==2.2.3"
         },
+        "pathspec": {
+            "hashes": [
+                "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08",
+                "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712"
+            ],
+            "markers": "python_version >= '3.8'",
+            "version": "==0.12.1"
+        },
         "pillow": {
             "hashes": [
                 "sha256:015c6e863faa4779251436db398ae75051469f7c903b043a48f078e437656f83",
@@ -564,6 +645,14 @@
             "markers": "python_version >= '3.9'",
             "version": "==11.1.0"
         },
+        "platformdirs": {
+            "hashes": [
+                "sha256:a03875334331946f13c549dbd8f4bac7a13a50a895a0eb1e8c6a8ace80d40a94",
+                "sha256:eb437d586b6a0986388f0d6f74aa0cde27b48d0e3d66843640bfb6bdcdb6e351"
+            ],
+            "markers": "python_version >= '3.9'",
+            "version": "==4.3.7"
+        },
         "protobuf": {
             "hashes": [
                 "sha256:13eb236f8eb9ec34e63fc8b1d6efd2777d062fa6aaa68268fb67cf77f6839ad7",
@@ -637,6 +726,14 @@
             "markers": "python_version >= '3.8'",
             "version": "==0.9.1"
         },
+        "pymdown-extensions": {
+            "hashes": [
+                "sha256:05e0bee73d64b9c71a4ae17c72abc2f700e8bc8403755a00580b49a4e9f189e9",
+                "sha256:41e576ce3f5d650be59e900e4ceff231e0aed2a88cf30acaee41e02f063a061b"
+            ],
+            "markers": "python_version >= '3.8'",
+            "version": "==10.14.3"
+        },
         "python-dateutil": {
             "hashes": [
                 "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3",
@@ -711,6 +808,14 @@
             "markers": "python_version >= '3.8'",
             "version": "==6.0.2"
         },
+        "pyyaml-env-tag": {
+            "hashes": [
+                "sha256:70092675bda14fdec33b31ba77e7543de9ddc88f2e5b99160396572d11525bdb",
+                "sha256:af31106dec8a4d68c60207c1886031cbf839b68aa7abccdb19868200532c2069"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==0.1"
+        },
         "referencing": {
             "hashes": [
                 "sha256:df2e89862cd09deabbdba16944cc3f10feb6b3e6f18e902f7cc25609a34775aa",
@@ -1070,7 +1175,7 @@
                 "sha256:e7631a77ffb1f7d2eefa4445ebbee491c720a5661ddf6df3498ebecae5ed375c",
                 "sha256:ef810fbf7b781a5a593894e4f439773830bdecb885e6880d957d5b9382a960d2"
             ],
-            "markers": "platform_system != 'Darwin'",
+            "markers": "python_version >= '3.9'",
             "version": "==6.0.0"
         }
     },

README.md

@@ -12,25 +12,55 @@ license: mit
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
+# NLPinitiative Streamlit Web Application
 
-# Setup for Pushing to GitHub and HF Space:
-#### Due to the project being configured to use hugging face spaces to host the python web-app, the instructions will outline how to setup the project to push to any newly created Hugging Face Space.
-Note: Streamlit can still be developed and deployed to environments other than Hugging Face Spaces. Refer to the appropriate documentation associated with a chosen hosting service for how to deploy the web-app to the services environment.
+---
 
-### After Creation of a Streamlit Hugging Face Space:
- - In the directory of the cloned repository, add the hugging face space as an additional remote origin:
-    - You can specify any name to use for the origin name (i.e., hf_origin)
-```
-git remote add <hf-origin-name> <hf-space-url>
-```
+## Project Details
 
- - Once the space is linked, you will need to force update the space with the contents of the current repository as follows (This will sync the HF Space with the main repositories history):
-```
-git push --force <hf-origin-name> main
-```
+### Description
+
+Codebase for the Streamlit app hosted on Hugging Face Spaces that provides a basic user interface for performing inference on text input by the user using the models training within the NLPinitiative project.
+
+---
+### Project Setup
+
+**Setup for Pushing to GitHub and HF Space**:
+
+Due to the project being configured to use hugging face spaces to host the python web-app, the instructions will outline how to setup the project to push to any newly created Hugging Face Space.
+
+**Note**: Streamlit can still be developed and deployed to environments other than Hugging Face Spaces. Refer to the appropriate documentation associated with a chosen hosting service for how to deploy the web-app to the services environment.
+
+**After Creation of a Streamlit Hugging Face Space**:
+
+In the directory of the cloned repository, add the hugging face space as an additional remote origin: 
+`git remote add <hf-origin-name> <hf-space-url>`
+
+ - **NOTE**: *You can specify any name to use for the origin name (i.e., hf_origin)*
+
+Once the space is linked, you will need to force update the space with the contents of the current repository as follows (This will sync the HF Space with the main repositories history):
+`git push --force <hf-origin-name> main`
+
+Following these steps, any new commits made can be pushed to the HF Space by using the following command:
+`git push <hf-space-name> main`
+
+---
+### Project layout
 
- - Following these steps, any new commits made can be pushed to the HF Space by using the following command:
 ```
-git push <hf-space-name> main
+├── docs                <- A directory containing documentation used for generating and serving 
+│                          project documentation
+├── scripts             <- Source code for model inference               
+│      ├── __init__.py         <- Makes modeling a Python module        
+│      └── predict.py          <- Code to run model inference with trained models
+├── app.py              <- Entry point for the application
+├── config.py           <- Store useful variables and configuration
+├── LICENSE             <- Open-source license if one is chosen
+├── mkdocs.yml          <- mkdocs project configuration
+├── Pipfile             <- The project dependency file for reproducing the analysis environment, 
+│                          e.g., generated with `pipenv install`
+├── Pipfile.lock        <- Locked file containing hashes for dependencies
+├── README.md           <- The top-level README for developers using this project
+├── requirements.txt    <- Plaintext dependency information (necessary for app hosting)
+└── setup.sh            <- Bash script containing convenience commands for managing the project
 ```
-

docs/index.md

@@ -0,0 +1,52 @@
+# NLPinitiative Streamlit Documentation 
+
+---
+
+## Project Details
+
+### Description
+
+Codebase for the Streamlit app hosted on Hugging Face Spaces that provides a basic user interface for performing inference on text input by the user using the models training within the NLPinitiative project.
+
+---
+### Project Setup
+
+**Setup for Pushing to GitHub and HF Space**:
+
+Due to the project being configured to use hugging face spaces to host the python web-app, the instructions will outline how to setup the project to push to any newly created Hugging Face Space.
+
+**Note**: Streamlit can still be developed and deployed to environments other than Hugging Face Spaces. Refer to the appropriate documentation associated with a chosen hosting service for how to deploy the web-app to the services environment.
+
+**After Creation of a Streamlit Hugging Face Space**:
+
+In the directory of the cloned repository, add the hugging face space as an additional remote origin: 
+`git remote add <hf-origin-name> <hf-space-url>`
+
+ - **NOTE**: *You can specify any name to use for the origin name (i.e., hf_origin)*
+
+Once the space is linked, you will need to force update the space with the contents of the current repository as follows (This will sync the HF Space with the main repositories history):
+`git push --force <hf-origin-name> main`
+
+Following these steps, any new commits made can be pushed to the HF Space by using the following command:
+`git push <hf-space-name> main`
+
+---
+### Project layout
+
+```
+├── docs                <- A directory containing documentation used for generating and serving 
+│                          project documentation
+├── scripts             <- Source code for model inference               
+│      ├── __init__.py         <- Makes modeling a Python module        
+│      └── predict.py          <- Code to run model inference with trained models
+├── app.py              <- Entry point for the application
+├── config.py           <- Store useful variables and configuration
+├── LICENSE             <- Open-source license if one is chosen
+├── mkdocs.yml          <- mkdocs project configuration
+├── Pipfile             <- The project dependency file for reproducing the analysis environment, 
+│                          e.g., generated with `pipenv install`
+├── Pipfile.lock        <- Locked file containing hashes for dependencies
+├── README.md           <- The top-level README for developers using this project
+├── requirements.txt    <- Plaintext dependency information (necessary for app hosting)
+└── setup.sh            <- Bash script containing convenience commands for managing the project
+```

mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: NLPinitiative Streamlit Documentation 
+
+nav:
+  - Home: index.md
+
+theme:
+  name: readthedocs
+
+plugins:
+- search
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          docstring_style: numpy

scripts/predict.py

@@ -16,23 +16,53 @@ from transformers import (
 BIN_REPO = 'dlsmallw/NLPinitiative-Binary-Classification'
 ML_REPO = 'dlsmallw/NLPinitiative-Multilabel-Regression'
 
-## Class used to encapsulate and handle the logic for inference
 class InferenceHandler:
-    def __init__(self, api_token):
+    """A class that handles performing inference using the trained binary classification and multilabel regression models."""
+
+    def __init__(self, api_token: str):
+        """Constructor for instantiating an InferenceHandler object.
+
+        Parameters
+        ----------
+        api_token : str
+            A Hugging Face token with read/write access privileges to allow exporting the trained models (default is None).
+        """
+
         self.api_token = api_token
-        self.bin_tokenizer, self.bin_model = self.init_model_and_tokenizer(BIN_REPO)
-        self.ml_regr_tokenizer, self.ml_regr_model = self.init_model_and_tokenizer(ML_REPO)
+        self.bin_tokenizer, self.bin_model = self._init_model_and_tokenizer(BIN_REPO)
+        self.ml_regr_tokenizer, self.ml_regr_model = self._init_model_and_tokenizer(ML_REPO)
         nltk.download('punkt_tab')
 
-    def get_config(self, repo_id):
+    def _get_config(self, repo_id: str) -> str:
+        """Retrieves the config.json file from the specified model repository.
+
+        Parameters
+        ----------
+        repo_id : str
+            The repository id (i.e., <owner username>/<repository name>).
+        
+        """
+
         config = None
         if repo_id and self.api_token:
             config = huggingface_hub.hf_hub_download(repo_id, filename='config.json', token=self.api_token)
         return config
 
-    ## Initializes a model and tokenizer for use in inference using the models path
-    def init_model_and_tokenizer(self, repo_id):
-        config = self.get_config(repo_id)
+    def _init_model_and_tokenizer(self, repo_id: str):
+        """Initializes a model and tokenizer for use in inference using the models path.
+
+        Parameters
+        ----------
+        model_path : Path
+            Directory path to the models tensor file.
+
+        Returns
+        -------
+        tuple[PreTrainedTokenizer | PreTrainedTokenizerFast, PreTrainedModel]
+            A tuple containing the tokenizer and model objects.
+        """
+
+        config = self._get_config(repo_id)
         with open(config) as config_file:
             config_json = json.load(config_file)
         model_name = config_json['_name_or_path']
@@ -43,24 +73,75 @@ class InferenceHandler:
         model.eval()
         return tokenizer, model
 
-    ## Handles logic used to encode the text for use in binary classification
-    def encode_binary(self, text):
+    def _encode_binary(self, text: str):
+        """Preprocesses and tokenizes the input text for binary classification.
+
+        Parameters
+        ----------
+        text : str
+            The input text to be preprocessed and tokenized.
+
+        Returns
+        -------
+        BatchEncoding
+            The preprocessed and tokenized input text.
+        """
+
         bin_tokenized_input = self.bin_tokenizer(text, return_tensors="pt", truncation=True, padding=True, max_length=512)
         return bin_tokenized_input
 
-    ## Handles logic used to encode the text for use in multilabel regression
-    def encode_multilabel(self, text):
+    def _encode_multilabel(self, text: str):
+        """Preprocesses and tokenizes the input text for multilabel regression.
+
+        Parameters
+        ----------
+        text : str
+            The input text to be preprocessed and tokenized.
+
+        Returns
+        -------
+        BatchEncoding
+            The preprocessed and tokenized input text.
+        """
+
         ml_tokenized_input = self.ml_regr_tokenizer(text, return_tensors="pt", truncation=True, padding=True, max_length=512)
         return ml_tokenized_input
 
-    ## Handles text encoding for both binary classification and multilabel regression
-    def encode_input(self, text):
-        bin_inputs = self.encode_binary(text)
-        ml_inputs = self.encode_multilabel(text)
+    def _encode_input(self, text: str):
+        """Preprocesses and tokenizes the input text sentiment classification (both models).
+
+        Parameters
+        ----------
+        text : str
+            The input text to be preprocessed and tokenized.
+
+        Returns
+        -------
+        tuple[BatchEncoding, BatchEncoding]
+            A tuple containing preprocessed and tokenized input text for both the binary and multilabel regression models.
+        """
+
+        bin_inputs = self._encode_binary(text)
+        ml_inputs = self._encode_multilabel(text)
         return bin_inputs, ml_inputs
     
-    ## Handles performing the full sentiment analysis (binary classification and multilabel regression)
-    def classify_text(self, input):
+    def classify_text(self, input: str):
+        """Performs inference on the input text to determine the binary classification and the multilabel regression for the categories.
+
+        Determines whether the text is discriminatory. If it is discriminatory, it will then perform regression on the input text to determine the
+        assesed percentage that each category applies.
+
+        Parameters
+        ----------
+        input : str
+            The input text to be classified.
+
+        Returns
+        -------
+        dict[str, Any]
+            The resulting classification and regression values for each category.
+        """
+
         result = {
             'text_input': input,
             'results': []
@@ -100,9 +181,21 @@ class InferenceHandler:
         result['results'] = sent_res_arr
         return result
     
-    ## Handles logic for checking the binary classfication of the text 
-    def discriminatory_inference(self, text):
-        bin_inputs = self.encode_binary(text)
+    def discriminatory_inference(self, text: str):
+        """Performs inference on the input text to determine the binary classification.
+
+        Parameters
+        ----------
+        text : str
+            The input text to be classified.
+
+        Returns
+        -------
+        tuple[str, Number]
+            A tuple consisting of the string classification (Discriminatory or Non-Discriminatory) and the numeric prediction class (1 or 0).
+        """
+
+        bin_inputs = self._encode_binary(text)
 
         with torch.no_grad():
             bin_logits = self.bin_model(**bin_inputs).logits
@@ -114,9 +207,21 @@ class InferenceHandler:
 
         return bin_text_pred, pred_class
     
-    ## Handles logic for assessing the categories of discrimination
-    def category_inference(self, text):
-        ml_inputs = self.encode_multilabel(text)
+    def category_inference(self, text: str):
+        """Performs inference on the input text to determine the regression values for the categories of discrimination.
+
+        Parameters
+        ----------
+        text : str
+            The input text to be classified.
+
+        Returns
+        -------
+        list[float]
+            A tuple consisting of the string classification (Discriminatory or Non-Discriminatory) and the numeric prediction class (1 or 0).
+        """
+
+        ml_inputs = self._encode_multilabel(text)
 
         with torch.no_grad():
             ml_outputs = self.ml_regr_model(**ml_inputs).logits

setup.sh

@@ -23,16 +23,16 @@ requirements() {
     pipenv requirements > requirements.txt
 }
 
-# docs() {
-#     case $1 in
-#         build)
-#             mkdocs build
-#             ;;
-#         serve)
-#             mkdocs serve
-#             ;;
-#         *)
-#             log_error "Specify 'build' or 'serve'. For example: docs build"
-#             ;;
-#     esac
-# }
+docs() {
+    case $1 in
+        build)
+            mkdocs build
+            ;;
+        serve)
+            mkdocs serve
+            ;;
+        *)
+            log_error "Specify 'build' or 'serve'. For example: docs build"
+            ;;
+    esac
+}