Startup: Check File Structure (#6)

### Description
<!---Why are we making this change? What does it do?--->
Adds in a check to the directory structure when starting up. Validates
the (not yet implemented) `metadata.json` file exists, and that the
directory structure adheres to the expected structure.
### Testing
<!---How was this tested?--->
not tested yet, going to take a loop once we are somewhat feature
complete
### Impact
<!---What components does this impact? How can it affect prod?--->

### Other
<!---What else can this impact? What special considerations are needed
when reviewing the PR?--->

Author: echavemann

file_structure.md

@@ -0,0 +1,50 @@
+```
+lens/
+├── avax
+│   ├── depth
+│   │   ├── 2025-02-21.csv
+│   │   ├── 2025-02-22.csv
+│   │   ├── 2025-02-23.csv
+│   │   ├── 2025-02-24.csv
+│   │   ├── 2025-02-25.csv
+│   │   ├── 2025-02-26.csv
+│   │   ├── 2025-02-27.csv
+│   │   ├── 2025-02-28.csv
+│   │   ├── 2025-03-01.csv
+│   │   └── 2025-03-02.csv
+│   └── trades
+│       ├── 2025-02-21.csv
+│       ├── 2025-02-22.csv
+│       ├── 2025-02-23.csv
+│       ├── 2025-02-24.csv
+│       ├── 2025-02-25.csv
+│       ├── 2025-02-26.csv
+│       ├── 2025-02-27.csv
+│       ├── 2025-02-28.csv
+│       ├── 2025-03-01.csv
+│       └── 2025-03-02.csv
+├── btc
+│   ├── depth
+│   │   ├── 2025-02-21.csv
+│   │   ├── 2025-02-22.csv
+│   │   ├── 2025-02-23.csv
+│   │   ├── 2025-02-24.csv
+│   │   ├── 2025-02-25.csv
+│   │   ├── 2025-02-26.csv
+│   │   ├── 2025-02-27.csv
+│   │   ├── 2025-02-28.csv
+│   │   ├── 2025-03-01.csv
+│   │   └── 2025-03-02.csv
+│   └── trades
+│       ├── 2025-02-21.csv
+│       ├── 2025-02-22.csv
+│       ├── 2025-02-23.csv
+│       ├── 2025-02-24.csv
+│       ├── 2025-02-25.csv
+│       ├── 2025-02-26.csv
+│       ├── 2025-02-27.csv
+│       ├── 2025-02-28.csv
+│       ├── 2025-03-01.csv
+│       └── 2025-03-02.csv
+└── metadata.json
+```

lens/core.py

@@ -1,13 +1,23 @@
+from pathlib import Path
+
 from loguru import logger
 
 from lens.util.hostname import check_valid_lens_hostname, get_hostname
+from lens.util.paths import check_file_structure_correct, check_metadata_exists
 
 
 class Lens:
     def __init__(self) -> None:
         pass
 
-    def startup(self) -> None:
+    def startup(self, data_root: Path) -> None:
         if not check_valid_lens_hostname(get_hostname()):
             raise RuntimeError("Cannot start lens on invalid host.")
+        logger.info("Host check succeeded.")
+        if not check_metadata_exists(data_root):
+            raise RuntimeError("Failed to find metadata.json file in the data directory.")
+        logger.info("Metadata found.")
+        if not check_file_structure_correct(data_root):
+            raise RuntimeError("File structure does not match expected directory structure.")
+        logger.info("File structure is correct.")
         logger.info("Lens startup succeeded.")

lens/descriptor.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+TRADE_DIRNAME = "trades"
+DEPTH_DIRNAME = "depth"
+
+
+@dataclass
+class DataPathContainer:
+    trade_paths: list[Path]
+    depth_paths: list[Path]
+
+
+@dataclass
+class DataDescriptor:
+    root: Path
+    data_paths: dict[str, DataPathContainer]
+
+
+def load_data_descriptor(base_path: Path) -> DataDescriptor:
+    data_paths = {}
+    coin_paths = [child for child in base_path.iterdir() if child.is_dir()]
+
+    for coin_path in coin_paths:
+        trade_path = coin_path / TRADE_DIRNAME
+        depth_path = coin_path / DEPTH_DIRNAME
+        trade_files = [child for child in trade_path.iterdir()]
+        depth_files = [child for child in depth_path.iterdir()]
+        data_paths[coin_path.name] = DataPathContainer(trade_files, depth_files)
+
+    return DataDescriptor(base_path, data_paths)

lens/main.py

@@ -1,14 +1,28 @@
+import argparse
+from pathlib import Path
+from typing import Any
+
 from loguru import logger
 
 from lens.core import Lens
 
 
+def parse_arguments() -> Any:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-d", "--directory", type=str, required=True)
+
+    args = parser.parse_args()
+    return args
+
+
 @logger.catch
-def main() -> None:
+def main(data_root: Path) -> None:
     ln = Lens()
     logger.info("Starting lens initialization check.")
-    ln.startup()
+    ln.startup(data_root)
 
 
 if __name__ == "__main__":
-    main()
+    args = parse_arguments()
+    data_root = Path(args.directory)
+    main(data_root)

lens/util/paths.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+from loguru import logger
+
+from lens.descriptor import load_data_descriptor
+
+METADATA_FILENAME = "metadata.json"
+
+
+def check_metadata_exists(base_path: Path) -> bool:
+    return (base_path / METADATA_FILENAME).exists()
+
+
+def check_file_structure_correct(base_path: Path) -> bool:
+    try:
+        descriptor = load_data_descriptor(base_path)
+    except FileNotFoundError:
+        logger.warning("Failed to build data descriptor - missing files.")
+        return False
+    data_file_counts = set()
+    for _, data_container in descriptor.data_paths.items():
+        data_file_counts.add(len(data_container.trade_paths))
+        data_file_counts.add(len(data_container.depth_paths))
+
+    if len(data_file_counts) != 1:
+        logger.warning("Data files are not uniform in counts.")
+        return False
+    return True