Added comments throughout

src/testing.py

@@ -35,6 +35,9 @@ class TestGenerator:
 
     @classmethod
     def question_count(cls) -> int:
+        """
+        The total number of questions in the question set
+        """
         cls.load_questions()
         return len(cls.questions)
 
@@ -109,6 +112,11 @@ class ArchitectureRequestRecord:
 
 
 class TestGroup:
+    """
+    A class representing a single batch run of tests from the UI. Identified by the tag
+    which was assigned from the UI when the test was run, and including summary items
+    (start, end, elapse) for convenience
+    """
     all: Dict[str, TestGroup] = None
 
     def __init__(self, test_group:str):
@@ -122,18 +130,36 @@ class TestGroup:
 
     @property
     def num_archs(self) -> int:
+        """
+        The number of LLM Architectures which were included in this test run from the UI
+        """
         return len(self.architectures)
 
     @property
     def num_tests(self) -> int:
+        """
+        The total number of Architecture tests (inferences) done in this test run from the UI
+        """
         return len(self.arch_request_records)
 
     @property
     def num_tests_per_arch(self) -> int:
+        """
+        The calculated number of tests run through each architecture (simple divide as the UI
+        forces each architecture to get the same number of requests)
+        """
         # Should always be an even number but cast to int just in case
         return int(self.num_tests / self.num_archs)
 
     def arch_request_records_by_arch(self) -> Dict[List[ArchitectureRequestRecord]]:
+        """
+        Get all the tests ArchitectureRequestRecords grouped by the architecture.
+        :return: dict keyed by the architecture name containing a list of ArchitectureRequestRecords
+        detailing the tests run through that architecture.  Note - the keys are intended to be used for
+        display purposes - attempting to use them to load the original architecture will be
+        dependent on the availability of that architecture at look up time and changes in architecture
+        config could cause that lookup to fail (i.e. the tested architecture is no longer configured).
+        """
         grouped = {}
         for arr in self.arch_request_records:
             if arr.arch not in grouped:
@@ -142,6 +168,13 @@ class TestGroup:
         return grouped
 
     def summary_stats_by_arch(self) -> List[Dict]:
+        """
+        Get a pack of statistics for use in the UI, detailing this TestGroup.
+        :return: a list, sorted by architecture name, of statistics per architecture. Each list item
+        is a dict of information (arch_name, elapsed[list of elapsed times in ms],
+        response_len[list of the lengthe of the final response in characters], steps[list of the
+        individual architecture steps each containing dict of name, mean_elapsed(ms)])
+        """
         arch_records = self.arch_request_records_by_arch()
         arch_names = list(arch_records.keys())
         arch_names.sort()
@@ -160,6 +193,10 @@ class TestGroup:
         return stats
 
     def add_record(self, arr: ArchitectureRequestRecord) -> None:
+        """
+        Add an ArchitectureRequestRecord into this test group. Update the
+        TestGroup level start, end and elapsed with the new data
+        """
         if arr.test_group != self.test_group:
             raise ValueError("Attempted to group a test record into the wrong group")
         self.arch_request_records.append(arr)
@@ -174,6 +211,9 @@ class TestGroup:
 
     @classmethod
     def load_db_records(cls) -> List[TestGroup]:
+        """
+        Load all the test groups from the DataBase
+        """
         db_file = os.path.join(data_dir, 'sqlite', 'test_records.db')
         con = sqlite3.connect(db_file)
         cur = con.cursor()
@@ -199,6 +239,10 @@ class TestGroup:
 
     @classmethod
     def load_all(cls, reload=False):
+        """
+        Load all the available TestGroups, from both the json file and the DB
+        into the class variable - for efficiency do not reload unless requested
+        """
         if cls.all is None or reload:
             ArchitectureRequestRecord.load_all(reload=reload)
             records = {}
@@ -214,6 +258,10 @@ class TestGroup:
 
     @classmethod
     def for_test_group_tag(cls, test_group_tag: str) -> TestGroup:
+        """
+        Get a single TestGroup based on the test_group_tag which was assigned
+        when the test was run
+        """
         cls.load_all()
         return cls.all[test_group_tag]
 
@@ -228,11 +276,17 @@ def move_test_records_to_db(hf_hub_token: str) -> None:
     them across.
     """
     def download_latest_json_file(hf_hub_token: str) -> Repository:
+        """
+        Wipe any local version of the json file and re-downlad from the HF Hub
+        """
         if os.path.exists(Architecture.trace_dir):
             shutil.rmtree(Architecture.trace_dir)
         return Repository(local_dir=Architecture.trace_dir, clone_from=Architecture.save_repo_url, token=hf_hub_token)
 
     def create_local_db():
+        """
+        Create the local database if it does not exist
+        """
         db_file = os.path.join(data_dir, 'sqlite', 'test_records.db')
         con = sqlite3.connect(db_file)
 
@@ -246,12 +300,19 @@ def move_test_records_to_db(hf_hub_token: str) -> None:
         con.execute(sql)
 
     def get_local_db() -> sqlite3.Connection:
+        """
+        Get a connection to the local database and create it if it is not already there
+        """
         db_file = os.path.join(data_dir, 'sqlite', 'test_records.db')
         if not os.path.exists(db_file):
             create_local_db()
         return sqlite3.connect(db_file)
 
     def load_test_group_to_db(test_group: TestGroup, con: sqlite3.Connection) -> None:
+        """
+        Load a single TestGroup object into the DB, decomposing to the TestGroup,
+        ArchitectureRequest within that and ArchitectureRequestSteps within those
+        """
         cur = con.cursor()
         sql = f'SELECT count(*) from test_groups where test_group ="{test_group.test_group}"'
         cur.execute(sql)
@@ -272,11 +333,16 @@ def move_test_records_to_db(hf_hub_token: str) -> None:
             print(f"Warning TestGroup {tg_not_in_db} was not added to the DB as it already existed there")
 
     def load_all_test_groups_to_db(con: sqlite3.Connection) -> None:
+        """
+        Load a list of TestGroups to the DB, one at a time
+        """
         TestGroup.load_all()
         for tg in TestGroup.all.values():
             load_test_group_to_db(tg, con)
 
-    # Main control flow using utility local functions above for better structure
+    """
+    Main control flow using utility nested functions above for better structure and readability
+    """
     download_latest_json_file(hf_hub_token)
     conn = get_local_db()
     load_all_test_groups_to_db(conn)