dragon-ml-toolbox 6.2.1__py3-none-any.whl → 6.4.0__py3-none-any.whl

{dragon_ml_toolbox-6.2.1.dist-info → dragon_ml_toolbox-6.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dragon-ml-toolbox
-Version: 6.2.1
+Version: 6.4.0
 Summary: A collection of tools for data science and machine learning projects.
 Author-email: Karl Loza <luigiloza@gmail.com>
 License-Expression: MIT
@@ -160,6 +160,8 @@ SQL
 utilities
 ```
 
+---
+
 ### 🔬 MICE Imputation and Variance Inflation Factor [mice]
 
 ⚠️ Important: This group has strict version requirements. It is highly recommended to install this group in a separate virtual environment.
@@ -178,6 +180,8 @@ path_manager
 utilities
 ```
 
+---
+
 ### 📋 Excel File Handling [excel]
 
 Installs dependencies required to process and handle .xlsx or .xls files.
@@ -194,6 +198,8 @@ handle_excel
 path_manager
 ```
 
+---
+
 ### 🎰 GUI for Boosting Algorithms (XGBoost, LightGBM) [gui-boost]
 
 For GUIs that include plotting functionality, you must also install the [plot] extra.
@@ -215,6 +221,8 @@ ensemble_inference
 path_manager
 ```
 
+---
+
 ### 🤖 GUI for PyTorch Models [gui-torch]
 
 For GUIs that include plotting functionality, you must also install the [plot] extra.
@@ -232,10 +240,13 @@ pip install "dragon-ml-toolbox[gui-torch,plot]"
 ```Bash
 custom_logger
 GUI_tools
+ML_models
 ML_inference
 path_manager
 ```
 
+---
+
 ### 🎫 Base Tools [base]
 
 General purpose functions and classes.
@@ -254,6 +265,8 @@ utilities
 path_manager
 ```
 
+---
+
 ### ⚒️ APP bundlers
 
 Choose one if needed.

{dragon_ml_toolbox-6.2.1.dist-info → dragon_ml_toolbox-6.4.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-dragon_ml_toolbox-6.2.1.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
-dragon_ml_toolbox-6.2.1.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=lY4_rJPnLnMu7YBQaY-_iz1JRDcLdQzNCyeLAF1glJY,1837
+dragon_ml_toolbox-6.4.0.dist-info/licenses/LICENSE,sha256=2uUFNy7D0TLgHim1K5s3DIJ4q_KvxEXVilnU20cWliY,1066
+dragon_ml_toolbox-6.4.0.dist-info/licenses/LICENSE-THIRD-PARTY.md,sha256=lY4_rJPnLnMu7YBQaY-_iz1JRDcLdQzNCyeLAF1glJY,1837
 ml_tools/ETL_engineering.py,sha256=4wwZXi9_U7xfCY70jGBaKniOeZ0m75ppxWpQBd_DmLc,39369
 ml_tools/GUI_tools.py,sha256=n4ZZ5kEjwK5rkOCFJE41HeLFfjhpJVLUSzk9Kd9Kr_0,45410
 ml_tools/MICE_imputation.py,sha256=oFHg-OytOzPYTzBR_wIRHhP71cMn3aupDeT59ABsXlQ,11576
 ml_tools/ML_callbacks.py,sha256=noedVMmHZ72Odbg28zqx5wkhhvX2v-jXicKE_NCAiqU,13838
-ml_tools/ML_datasetmaster.py,sha256=bbKCNA_b_uDIfxP9YIYKZm-VSfUSD15LvegFxpE9DIQ,34315
+ml_tools/ML_datasetmaster.py,sha256=98dAfP-i7BjhGpmGSaxtuUOZeiUN_8KpjBwZEmPCpgk,35485
 ml_tools/ML_evaluation.py,sha256=-Z5fXQi2ou6l5Oyir06bO90SZIZVrjQfgoVAqKgSjks,13800
-ml_tools/ML_inference.py,sha256=blEDgzvDqatxbfloBKsyNPacRwoq9g6WTpIKQ3zoTak,5758
-ml_tools/ML_models.py,sha256=SJhKHGAN2VTBqzcHUOpFWuVZ2Y7U1M4P_axG_LNYWcI,6460
+ml_tools/ML_inference.py,sha256=62F5RPC19bTHXUMTjnj2KMMg-wJdhLdVZDw--xJyiwM,12715
+ml_tools/ML_models.py,sha256=QBPlu5d6QCKh-rlUJOAR3qVdFgOFqEzRPv1jXvRdOsw,10380
 ml_tools/ML_optimization.py,sha256=GX-qZ2mCI3gWRCTP5w7lXrZpfGle3J_mE0O68seIoio,13475
 ml_tools/ML_trainer.py,sha256=1q_CDXuMfndRsPuNofUn2mg2TlhG6MYuGqjWxTDgN9c,15112
 ml_tools/PSO_optimization.py,sha256=9Y074d-B5h4Wvp9YPiy6KAeXM-Yv6Il3gWalKvOLVgo,22705
@@ -17,7 +17,7 @@ ml_tools/VIF_factor.py,sha256=2nUMupfUoogf8o6ghoFZk_OwWhFXU0R3C9Gj0HOlI14,10415
 ml_tools/__init__.py,sha256=q0y9faQ6e17XCQ7eUiCZ1FJ4Bg5EQqLjZ9f_l5REUUY,41
 ml_tools/_logger.py,sha256=TpgYguxO-CWYqqgLW0tqFjtwZ58PE_W2OCfWNGZr0n0,1175
 ml_tools/_script_info.py,sha256=21r83LV3RubsNZ_RTEUON6RbDf7Mh4_udweNcvdF_Fk,212
-ml_tools/custom_logger.py,sha256=njM_0XPbQ1S-x5LeSQAaTo2if-XVOR_pQSGg4EDeiTU,4603
+ml_tools/custom_logger.py,sha256=nyLRxaRxkqYOFdSjI0X2BWXB8C2IU18QfmqIFKqSedI,5820
 ml_tools/data_exploration.py,sha256=P4f8OpRa7Q4i-11nkppxXw5Lx2lwlpn20GwWBbN_xbM,23901
 ml_tools/ensemble_evaluation.py,sha256=wnqoTPg4WYWf2A8z5XT0eSlW4snEuLCXQVj88sZKzQ4,24683
 ml_tools/ensemble_inference.py,sha256=rtU7eUaQne615n2g7IHZCJI-OvrBCcjxbTkEIvtCGFQ,9414
@@ -27,7 +27,7 @@ ml_tools/keys.py,sha256=HtPG8-MWh89C32A7eIlfuuA-DLwkxGkoDfwR2TGN9CQ,1074
 ml_tools/optimization_tools.py,sha256=EL5tgNFwRo-82pbRE1CFVy9noNhULD7wprWuKadPheg,5090
 ml_tools/path_manager.py,sha256=Z8e7w3MPqQaN8xmTnKuXZS6CIW59BFwwqGhGc00sdp4,13692
 ml_tools/utilities.py,sha256=LqXXTovaHbA5AOKRk6Ru6DgAPAM0wPfYU70kUjYBryo,19231
-dragon_ml_toolbox-6.2.1.dist-info/METADATA,sha256=acX_886jWy_IUIO9-HsSalgpD9HAh8a5Q22rbUlBzbU,6698
-dragon_ml_toolbox-6.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dragon_ml_toolbox-6.2.1.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
-dragon_ml_toolbox-6.2.1.dist-info/RECORD,,
+dragon_ml_toolbox-6.4.0.dist-info/METADATA,sha256=jzs_BIaUzjLYIMUOVOgDl2qkyO-Z7Q00rZLZDzkxBkQ,6738
+dragon_ml_toolbox-6.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dragon_ml_toolbox-6.4.0.dist-info/top_level.txt,sha256=wm-oxax3ciyez6VoO4zsFd-gSok2VipYXnbg3TH9PtU,9
+dragon_ml_toolbox-6.4.0.dist-info/RECORD,,

ml_tools/ML_datasetmaster.py

@@ -16,6 +16,7 @@ from pathlib import Path
 from .path_manager import make_fullpath
 from ._logger import _LOGGER
 from ._script_info import _script_info
+from .custom_logger import save_list_strings
 
 
 # --- public-facing API ---
@@ -144,6 +145,9 @@ class DatasetMaker(_BaseMaker):
         self.features = pandas_df.drop(columns=label_col)
         self.labels_map = None
         self.scaler = None
+        
+        self._feature_names = self.features.columns.tolist()
+        self._target_name = str(self.labels.name)
 
         self._is_split = False
         self._is_balanced = False
@@ -347,6 +351,23 @@ class DatasetMaker(_BaseMaker):
         if not self._is_split:
              raise RuntimeError("Data has not been split yet. Call .split_data() or .process() first.")
         return self.features_train, self.features_test, self.labels_train, self.labels_test # type: ignore
+    
+    @property
+    def feature_names(self) -> list[str]:
+        """Returns the list of feature column names."""
+        return self._feature_names
+
+    @property
+    def target_name(self) -> str:
+        """Returns the name of the target column."""
+        return self._target_name
+    
+    def save_feature_names(self, directory: Union[str, Path], verbose: bool=True) -> None:
+        """Saves a list of feature names as a text file"""
+        save_list_strings(list_strings=self._feature_names,
+                          directory=directory,
+                          filename="feature_names",
+                          verbose=verbose)
 
     @staticmethod
     def _embed_categorical(cat_df: pandas.DataFrame, random_state: Optional[int] = None, **kwargs) -> pandas.DataFrame:
@@ -413,7 +434,7 @@ class SimpleDatasetMaker:
         target = pandas_df.iloc[:, -1]
 
         self._feature_names = features.columns.tolist()
-        self._target_name = target.name
+        self._target_name = str(target.name)
         
         #set id
         self._id: Optional[str] = None
@@ -452,7 +473,7 @@ class SimpleDatasetMaker:
     @property
     def target_name(self) -> str:
         """Returns the name of the target column."""
-        return str(self._target_name)
+        return self._target_name
     
     @property
     def id(self) -> Optional[str]:
@@ -474,6 +495,13 @@ class SimpleDatasetMaker:
         print(f"  X_test shape:  {self._X_test_shape}")
         print(f"  y_test shape:  {self._y_test_shape}")
         print("-------------------------------------------")
+        
+    def save_feature_names(self, directory: Union[str, Path], verbose: bool=True) -> None:
+        """Saves a list of feature names as a text file"""
+        save_list_strings(list_strings=self._feature_names,
+                          directory=directory,
+                          filename="feature_names",
+                          verbose=verbose)
 
 
 # --- VisionDatasetMaker ---

ml_tools/ML_inference.py

@@ -2,7 +2,7 @@ import torch
 from torch import nn
 import numpy as np
 from pathlib import Path
-from typing import Union, Literal, Dict, Any
+from typing import Union, Literal, Dict, Any, Optional
 
 from ._script_info import _script_info
 from ._logger import _LOGGER
@@ -10,7 +10,9 @@ from .path_manager import make_fullpath
 from .keys import PyTorchInferenceKeys
 
 __all__ = [
-    "PyTorchInferenceHandler"
+    "PyTorchInferenceHandler",
+    "multi_inference_regression",
+    "multi_inference_classification"
 ]
 
 class PyTorchInferenceHandler:
@@ -22,7 +24,8 @@ class PyTorchInferenceHandler:
                  model: nn.Module,
                  state_dict: Union[str, Path],
                  task: Literal["classification", "regression"],
-                 device: str = 'cpu'):
+                 device: str = 'cpu',
+                 target_id: Optional[str]=None):
         """
         Initializes the handler by loading a model's state_dict.
 
@@ -31,10 +34,12 @@ class PyTorchInferenceHandler:
             state_dict (str | Path): The path to the saved .pth model state_dict file.
             task (str): The type of task, 'regression' or 'classification'.
             device (str): The device to run inference on ('cpu', 'cuda', 'mps').
+            target_id (str | None): Target name as used in the training set.
         """
         self.model = model
         self.task = task
         self.device = self._validate_device(device)
+        self.target_id = target_id
 
         model_p = make_fullpath(state_dict, enforce="file")
 
@@ -128,10 +133,155 @@ class PyTorchInferenceHandler:
         else: # classification
             return {
                 PyTorchInferenceKeys.LABELS: tensor_results[PyTorchInferenceKeys.LABELS].item(),
-                # ✅ Move tensor to CPU before converting to NumPy
+                # Move tensor to CPU before converting to NumPy
                 PyTorchInferenceKeys.PROBABILITIES: tensor_results[PyTorchInferenceKeys.PROBABILITIES].cpu().numpy()
             }
-     
+
+
+def multi_inference_regression(handlers: list[PyTorchInferenceHandler], 
+                               feature_vector: Union[np.ndarray, torch.Tensor], 
+                               output: Literal["numpy","torch"]="numpy") -> dict[str,Any]:
+    """
+    Performs regression inference using multiple models on a single feature vector.
+
+    This function iterates through a list of PyTorchInferenceHandler objects,
+    each configured for a different regression target. It runs a prediction for
+    each handler using the same input feature vector and returns the results
+    in a dictionary.
+    
+    The function adapts its behavior based on the input dimensions:
+    - 1D input: Returns a dictionary mapping target ID to a single value.
+    - 2D input: Returns a dictionary mapping target ID to a list of values.
+
+    Args:
+        handlers (list[PyTorchInferenceHandler]): A list of initialized inference
+            handlers. Each handler must have a unique `target_id` and be configured with `task="regression"`.
+        feature_vector (Union[np.ndarray, torch.Tensor]): An input sample (1D) or a batch of samples (2D) to be fed into each regression model.
+        output (Literal["numpy", "torch"], optional): The desired format for the output predictions.
+            - "numpy": Returns predictions as Python scalars or NumPy arrays.
+            - "torch": Returns predictions as PyTorch tensors.
+
+    Returns:
+        (dict[str, Any]): A dictionary mapping each handler's `target_id` to its
+        predicted regression values. 
+
+    Raises:
+        AttributeError: If any handler in the list is missing a `target_id`.
+        ValueError: If any handler's `task` is not 'regression' or if the input `feature_vector` is not 1D or 2D.
+    """
+    # check batch dimension
+    is_single_sample = feature_vector.ndim == 1
+    
+    # Reshape a 1D vector to a 2D batch of one for uniform processing.
+    if is_single_sample:
+        feature_vector = feature_vector.reshape(1, -1)
+    
+    # Validate that the input is a 2D tensor.
+    if feature_vector.ndim != 2:
+        raise ValueError("Input feature_vector must be a 1D or 2D array/tensor.")
+    
+    results: dict[str,Any] = dict()
+    for handler in handlers:
+        # validation
+        if handler.target_id is None:
+            raise AttributeError("All inference handlers must have a 'target_id' attribute.")
+        if handler.task != "regression":
+            raise ValueError(
+                f"Invalid task type: The handler for target_id '{handler.target_id}' "
+                f"is for '{handler.task}', but only 'regression' tasks are supported."
+            )
+        # inference
+        if output == "numpy":
+            result = handler.predict_batch_numpy(feature_vector)[PyTorchInferenceKeys.PREDICTIONS]
+        else: # torch
+            result = handler.predict_batch(feature_vector)[PyTorchInferenceKeys.PREDICTIONS]
+        
+        # Unpack single results and update result dictionary
+        # If the original input was 1D, extract the single prediction from the array.
+        if is_single_sample:
+            results[handler.target_id] = result[0]
+        else:
+            results[handler.target_id] = result
+
+    return results
+
+
+def multi_inference_classification(
+    handlers: list[PyTorchInferenceHandler], 
+    feature_vector: Union[np.ndarray, torch.Tensor], 
+    output: Literal["numpy","torch"]="numpy"
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+    """
+    Performs classification inference on a single sample or a batch.
+
+    This function iterates through a list of PyTorchInferenceHandler objects,
+    each configured for a different classification target. It returns two
+    dictionaries: one for the predicted labels and one for the probabilities.
+
+    The function adapts its behavior based on the input dimensions:
+    - 1D input: The dictionaries map target ID to a single label and a single probability array.
+    - 2D input: The dictionaries map target ID to an array of labels and an array of probability arrays.
+
+    Args:
+        handlers (list[PyTorchInferenceHandler]): A list of initialized inference handlers. Each must have a unique `target_id` and be configured
+            with `task="classification"`.
+        feature_vector (Union[np.ndarray, torch.Tensor]): An input sample (1D)
+            or a batch of samples (2D) for prediction.
+        output (Literal["numpy", "torch"], optional): The desired format for the
+            output predictions.
+
+    Returns:
+        (tuple[dict[str, Any], dict[str, Any]]): A tuple containing two dictionaries:
+        1.  A dictionary mapping `target_id` to the predicted label(s).
+        2.  A dictionary mapping `target_id` to the prediction probabilities.
+
+    Raises:
+        AttributeError: If any handler in the list is missing a `target_id`.
+        ValueError: If any handler's `task` is not 'classification' or if the input `feature_vector` is not 1D or 2D.
+    """
+    # Store if the original input was a single sample
+    is_single_sample = feature_vector.ndim == 1
+    
+    # Reshape a 1D vector to a 2D batch of one for uniform processing
+    if is_single_sample:
+        feature_vector = feature_vector.reshape(1, -1)
+    
+    if feature_vector.ndim != 2:
+        raise ValueError("Input feature_vector must be a 1D or 2D array/tensor.")
+
+    # Initialize two dictionaries for results
+    labels_results: dict[str, Any] = dict()
+    probs_results: dict[str, Any] = dict()
+
+    for handler in handlers:
+        # Validation
+        if handler.target_id is None:
+            raise AttributeError("All inference handlers must have a 'target_id' attribute.")
+        if handler.task != "classification":
+            raise ValueError(
+                f"Invalid task type: The handler for target_id '{handler.target_id}' "
+                f"is for '{handler.task}', but this function only supports 'classification'."
+            )
+            
+        # Always use the batch method to get both labels and probabilities
+        if output == "numpy":
+            result = handler.predict_batch_numpy(feature_vector)
+        else: # torch
+            result = handler.predict_batch(feature_vector)
+        
+        labels = result[PyTorchInferenceKeys.LABELS]
+        probabilities = result[PyTorchInferenceKeys.PROBABILITIES]
+        
+        # If the original input was 1D, unpack the single result from the batch array
+        if is_single_sample:
+            labels_results[handler.target_id] = labels[0]
+            probs_results[handler.target_id] = probabilities[0]
+        else:
+            labels_results[handler.target_id] = labels
+            probs_results[handler.target_id] = probabilities
+            
+    return labels_results, probs_results
+
 
 def info():
     _script_info(__all__)

ml_tools/ML_models.py

@@ -1,12 +1,18 @@
 import torch
 from torch import nn
 from ._script_info import _script_info
-from typing import List
+from typing import List, Union
+from pathlib import Path
+import json
+from ._logger import _LOGGER
+from .path_manager import make_fullpath
 
 
 __all__ = [
     "MultilayerPerceptron",
-    "SequencePredictorLSTM"
+    "SequencePredictorLSTM",
+    "save_architecture",
+    "load_architecture"
 ]
 
 
@@ -45,6 +51,12 @@ class MultilayerPerceptron(nn.Module):
             raise TypeError("hidden_layers must be a list of integers.")
         if not (0.0 <= drop_out < 1.0):
             raise ValueError("drop_out must be a float between 0.0 and 1.0.")
+        
+        # --- Save configuration ---
+        self.in_features = in_features
+        self.out_targets = out_targets
+        self.hidden_layers = hidden_layers
+        self.drop_out = drop_out
 
         # --- Build network layers ---
         layers = []
@@ -67,6 +79,15 @@ class MultilayerPerceptron(nn.Module):
         """Defines the forward pass of the model."""
         return self._layers(x)
     
+    def get_config(self) -> dict:
+        """Returns the configuration of the model."""
+        return {
+            'in_features': self.in_features,
+            'out_targets': self.out_targets,
+            'hidden_layers': self.hidden_layers,
+            'drop_out': self.drop_out
+        }
+    
     def __repr__(self) -> str:
         """Returns the developer-friendly string representation of the model."""
         # Extracts the number of neurons from each nn.Linear layer
@@ -114,7 +135,14 @@ class SequencePredictorLSTM(nn.Module):
             raise ValueError("recurrent_layers must be a positive integer.")
         if not (0.0 <= dropout < 1.0):
             raise ValueError("dropout must be a float between 0.0 and 1.0.")
-
+        
+        # --- Save configuration ---
+        self.features = features
+        self.hidden_size = hidden_size
+        self.recurrent_layers = recurrent_layers
+        self.dropout = dropout
+        
+        # Build model
         self.lstm = nn.LSTM(
             input_size=features,
             hidden_size=hidden_size,
@@ -144,6 +172,15 @@ class SequencePredictorLSTM(nn.Module):
         
         return predictions
     
+    def get_config(self) -> dict:
+        """Returns the configuration of the model."""
+        return {
+            'features': self.features,
+            'hidden_size': self.hidden_size,
+            'recurrent_layers': self.recurrent_layers,
+            'dropout': self.dropout
+        }
+    
     def __repr__(self) -> str:
         """Returns the developer-friendly string representation of the model."""
         return (
@@ -153,5 +190,80 @@ class SequencePredictorLSTM(nn.Module):
         )
 
 
+def save_architecture(model: nn.Module, directory: Union[str, Path], verbose: bool=True):
+    """
+    Saves a model's architecture to a 'architecture.json' file.
+
+    This function relies on the model having a `get_config()` method that
+    returns a dictionary of the arguments needed to initialize it.
+
+    Args:
+        model (nn.Module): The PyTorch model instance to save.
+        directory (str | Path): The directory to save the JSON file.
+
+    Raises:
+        AttributeError: If the model does not have a `get_config()` method.
+    """
+    if not hasattr(model, 'get_config'):
+        raise AttributeError(
+            f"Model '{model.__class__.__name__}' does not have a 'get_config()' method. "
+            "Please implement it to return the model's constructor arguments."
+        ) 
+
+    # Ensure the target directory exists
+    path_dir = make_fullpath(directory, make=True, enforce="directory")
+    full_path = path_dir / "architecture.json"
+
+    config = {
+        'model_class': model.__class__.__name__,
+        'config': model.get_config() # type: ignore
+    }
+
+    with open(full_path, 'w') as f:
+        json.dump(config, f, indent=4)
+    
+    if verbose:
+        _LOGGER.info(f"✅ Architecture for '{model.__class__.__name__}' saved to '{path_dir.name}'")
+
+
+def load_architecture(filepath: Union[str, Path], expected_model_class: type, verbose: bool=True) -> nn.Module:
+    """
+    Loads a model architecture from a JSON file.
+
+    This function instantiates a model by providing an explicit class to use
+    and checking that it matches the class name specified in the file.
+
+    Args:
+        filepath (Union[str, Path]): The path of the JSON architecture file.
+        expected_model_class (type): The model class expected to load (e.g., MultilayerPerceptron).
+
+    Returns:
+        nn.Module: An instance of the model with a freshly initialized state.
+
+    Raises:
+        FileNotFoundError: If the filepath does not exist.
+        ValueError: If the class name in the file does not match the `expected_model_class`.
+    """
+    path_obj = make_fullpath(filepath, enforce="file")
+
+    with open(path_obj, 'r') as f:
+        saved_data = json.load(f)
+
+    saved_class_name = saved_data['model_class']
+    config = saved_data['config']
+
+    if saved_class_name != expected_model_class.__name__:
+        raise ValueError(
+            f"Model class mismatch. File specifies '{saved_class_name}', "
+            f"but you expected '{expected_model_class.__name__}'."
+        )
+
+    # Create an instance of the model using the provided class and config
+    model = expected_model_class(**config)
+    if verbose:
+        _LOGGER.info(f"✅ Successfully loaded architecture for '{saved_class_name}'")
+    return model
+
+
 def info():
     _script_info(__all__)

ml_tools/custom_logger.py

@@ -10,7 +10,9 @@ from ._logger import _LOGGER
 
 
 __all__ = [
-    "custom_logger"
+    "custom_logger",
+    "save_list_strings",
+    "load_list_strings"
 ]
 
 
@@ -136,5 +138,39 @@ def _log_dict_to_json(data: Dict[Any, Any], path: Path) -> None:
         json.dump(data, f, indent=4, ensure_ascii=False)
 
 
+def save_list_strings(list_strings: list[str], directory: Union[str,Path], filename: str, verbose: bool=True):
+    """Saves a list of strings as a text file."""
+    target_dir = make_fullpath(directory, make=True, enforce="directory")
+    sanitized_name = sanitize_filename(filename)
+    
+    if not sanitized_name.endswith(".txt"):
+        sanitized_name = sanitized_name + ".txt"
+    
+    full_path = target_dir / sanitized_name
+    with open(full_path, 'w') as f:
+        for string_data in list_strings:
+            f.write(f"{string_data}\n")
+    
+    if verbose:
+        _LOGGER.info(f"✅ Text file saved as '{full_path.name}'.")
+
+
+def load_list_strings(text_file: Union[str,Path], verbose: bool=True) -> list[str]:
+    """Loads a text file as a list of strings."""
+    target_path = make_fullpath(text_file, enforce="file")
+    loaded_strings = []
+
+    with open(target_path, 'r') as f:
+        loaded_strings = [line.strip() for line in f]
+    
+    if len(loaded_strings) == 0:
+        raise ValueError("❌ The text file is empty.")
+    
+    if verbose:
+        _LOGGER.info(f"✅ Text file loaded as list of strings.")
+        
+    return loaded_strings
+
+
 def info():
     _script_info(__all__)