dragon-ml-toolbox 19.13.0__py3-none-any.whl → 20.0.0__py3-none-any.whl

ml_tools/ML_inference/_multi_inference.py

@@ -0,0 +1,180 @@
+import torch
+import numpy as np
+from typing import Union, Literal, Any
+
+from .._core import get_logger
+from ..keys._keys import PyTorchInferenceKeys, MLTaskKeys
+
+from ._dragon_inference import DragonInferenceHandler
+
+
+_LOGGER = get_logger("Multi Inference")
+
+
+__all__ = [
+    "multi_inference_regression",
+    "multi_inference_classification"
+]
+
+
+def multi_inference_regression(handlers: list[DragonInferenceHandler], 
+                               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 DragonInferenceHandler 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[DragonInferenceHandler]): 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:
+        _LOGGER.error("Input feature_vector must be a 1D or 2D array/tensor.")
+        raise ValueError()
+    
+    results: dict[str,Any] = dict()
+    for handler in handlers:
+        # validation
+        if handler.target_ids is None:
+            _LOGGER.error("All inference handlers must have a 'target_ids' attribute.")
+            raise AttributeError()
+        if handler.task != MLTaskKeys.REGRESSION:
+            _LOGGER.error(f"Invalid task type: The handler for target_id '{handler.target_ids[0]}' is for '{handler.task}', only single target regression tasks are supported.")
+            raise ValueError()
+            
+        # inference
+        if output == "numpy":
+            # This path returns NumPy arrays or standard Python scalars
+            numpy_result = handler.predict_batch_numpy(feature_vector)[PyTorchInferenceKeys.PREDICTIONS]
+            if is_single_sample:
+                # For a single sample, convert the 1-element array to a Python scalar
+                results[handler.target_ids[0]] = numpy_result.item()
+            else:
+                # For a batch, return the full NumPy array of predictions
+                results[handler.target_ids[0]] = numpy_result
+
+        else:  # output == "torch"
+            # This path returns PyTorch tensors on the model's device
+            torch_result = handler.predict_batch(feature_vector)[PyTorchInferenceKeys.PREDICTIONS]
+            if is_single_sample:
+                # For a single sample, return the 0-dim tensor
+                results[handler.target_ids[0]] = torch_result[0]
+            else:
+                # For a batch, return the full tensor of predictions
+                results[handler.target_ids[0]] = torch_result
+
+    return results
+
+
+def multi_inference_classification(
+    handlers: list[DragonInferenceHandler], 
+    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 DragonInferenceHandler 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[DragonInferenceHandler]): 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:
+        _LOGGER.error("Input feature_vector must be a 1D or 2D array/tensor.")
+        raise ValueError()
+
+    # 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_ids is None:
+            _LOGGER.error("All inference handlers must have a 'target_id' attribute.")
+            raise AttributeError()
+        if handler.task not in [MLTaskKeys.BINARY_CLASSIFICATION, MLTaskKeys.MULTICLASS_CLASSIFICATION]:
+            _LOGGER.error(f"Invalid task type: The handler for target_id '{handler.target_ids[0]}' is for '{handler.task}', but this function only supports binary and multiclass classification.")
+            raise ValueError()
+            
+        # Inference
+        if output == "numpy":
+            # predict_batch_numpy returns a dict of NumPy arrays
+            result = handler.predict_batch_numpy(feature_vector)
+        else: # torch
+            # predict_batch returns a dict of Torch tensors
+            result = handler.predict_batch(feature_vector)
+        
+        labels = result[PyTorchInferenceKeys.LABELS]
+        probabilities = result[PyTorchInferenceKeys.PROBABILITIES]
+        
+        if is_single_sample:
+            # For "numpy", convert the single label to a Python int scalar.
+            # For "torch", get the 0-dim tensor label.
+            if output == "numpy":
+                labels_results[handler.target_ids[0]] = labels.item()
+            else: # torch
+                labels_results[handler.target_ids[0]] = labels[0]
+            
+            # The probabilities are an array/tensor of values
+            probs_results[handler.target_ids[0]] = probabilities[0]
+        else:
+            labels_results[handler.target_ids[0]] = labels
+            probs_results[handler.target_ids[0]] = probabilities
+            
+    return labels_results, probs_results
+

ml_tools/ML_inference_sequence/__init__.py

@@ -0,0 +1,10 @@
+from ._sequence_inference import (
+    DragonSequenceInferenceHandler
+)
+
+from ._imprimir import info
+
+
+__all__ = [
+    "DragonSequenceInferenceHandler"
+]

ml_tools/ML_inference_sequence/_imprimir.py

@@ -0,0 +1,8 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "DragonSequenceInferenceHandler"
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{_core/_ML_sequence_inference.py → ML_inference_sequence/_sequence_inference.py}

@@ -2,19 +2,18 @@ import torch
 from torch import nn
 import numpy as np
 from pathlib import Path
-from typing import Union, Literal, Dict, Any, Optional
+from typing import Union, Literal, Any, Optional
 import matplotlib.pyplot as plt
 import seaborn as sns
 
-from ._ML_scaler import DragonScaler
-from ._script_info import _script_info
-from ._logger import get_logger
-from ._path_manager import make_fullpath, sanitize_filename
-from ._keys import PyTorchInferenceKeys, MLTaskKeys, PyTorchCheckpointKeys
-from ._ML_inference import _BaseInferenceHandler
+from .._core import get_logger
+from ..path_manager import make_fullpath, sanitize_filename
+from ..keys._keys import PyTorchInferenceKeys, MLTaskKeys, PyTorchCheckpointKeys
 
+from ..ML_inference._base_inference import _BaseInferenceHandler
 
-_LOGGER = get_logger("Inference Handler")
+
+_LOGGER = get_logger("DragonSequenceInference")
 
 
 __all__ = [
@@ -109,7 +108,7 @@ class DragonSequenceInferenceHandler(_BaseInferenceHandler):
 
         return scaled_features.to(self.device)
 
-    def predict_batch(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, torch.Tensor]:
+    def predict_batch(self, features: Union[np.ndarray, torch.Tensor]) -> dict[str, torch.Tensor]:
         """
         Core batch prediction method for sequences.
         Runs a batch of sequences through the model, de-scales the output,
@@ -161,7 +160,7 @@ class DragonSequenceInferenceHandler(_BaseInferenceHandler):
 
         return {PyTorchInferenceKeys.PREDICTIONS: descaled_output}
 
-    def predict(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, torch.Tensor]:
+    def predict(self, features: Union[np.ndarray, torch.Tensor]) -> dict[str, torch.Tensor]:
         """
         Core single-sample prediction method for sequences.
         Runs a single sequence through the model, de-scales the output,
@@ -187,7 +186,7 @@ class DragonSequenceInferenceHandler(_BaseInferenceHandler):
     
     # --- NumPy Convenience Wrappers (on CPU) ---
 
-    def predict_batch_numpy(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, np.ndarray]:
+    def predict_batch_numpy(self, features: Union[np.ndarray, torch.Tensor]) -> dict[str, np.ndarray]:
         """
         Convenience wrapper for predict_batch that returns NumPy arrays.
         
@@ -202,7 +201,7 @@ class DragonSequenceInferenceHandler(_BaseInferenceHandler):
         numpy_results = {key: value.cpu().numpy() for key, value in tensor_results.items()}
         return numpy_results
 
-    def predict_numpy(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, Any]:
+    def predict_numpy(self, features: Union[np.ndarray, torch.Tensor]) -> dict[str, Any]:
         """
         Convenience wrapper for predict that returns NumPy arrays or scalars.
         
@@ -371,6 +370,3 @@ class DragonSequenceInferenceHandler(_BaseInferenceHandler):
         finally:
             plt.close()
     
-
-def info():
-    _script_info(__all__)

ml_tools/ML_inference_vision/__init__.py

@@ -0,0 +1,10 @@
+from ._vision_inference import (
+    DragonVisionInferenceHandler
+)
+
+from ._imprimir import info
+
+
+__all__ = [
+    "DragonVisionInferenceHandler",
+]

ml_tools/ML_inference_vision/_imprimir.py

@@ -0,0 +1,8 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "DragonVisionInferenceHandler"
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{_core/_ML_vision_inference.py → ML_inference_vision/_vision_inference.py}

@@ -1,19 +1,18 @@
 import torch
 from torch import nn
-import numpy as np  #numpy array return value
 from pathlib import Path
-from typing import Union, Literal, Dict, Any, List, Optional, Callable
+from typing import Union, Literal, Any, Optional, Callable
 from PIL import Image
-from torchvision import transforms
 
-from ._script_info import _script_info
-from ._logger import get_logger
-from ._keys import PyTorchInferenceKeys, MLTaskKeys
-from ._ML_vision_transformers import _load_recipe_and_build_transform
-from ._ML_inference import _BaseInferenceHandler
+from ..ML_vision_transformers._core_transforms import _load_recipe_and_build_transform
 
+from .._core import get_logger
+from ..keys._keys import PyTorchInferenceKeys, MLTaskKeys
 
-_LOGGER = get_logger("Inference Handler")
+from ..ML_inference._base_inference import _BaseInferenceHandler
+
+
+_LOGGER = get_logger("DragonVisionInference")
 
 
 __all__ = [
@@ -84,7 +83,7 @@ class DragonVisionInferenceHandler(_BaseInferenceHandler):
             self.set_transform(transform_source)
             self._is_transformed = True
 
-    def _preprocess_batch(self, inputs: Union[torch.Tensor, List[torch.Tensor]]) -> Union[torch.Tensor, List[torch.Tensor]]:
+    def _preprocess_batch(self, inputs: Union[torch.Tensor, list[torch.Tensor]]) -> Union[torch.Tensor, list[torch.Tensor]]:
         """
         Validates input and moves it to the correct device.
         - For Classification/Segmentation: Expects 4D Tensor (B, C, H, W).
@@ -135,7 +134,7 @@ class DragonVisionInferenceHandler(_BaseInferenceHandler):
             _LOGGER.error(f"Invalid transform_source type: {type(transform_source)}. Must be str, Path, or Callable.")
             raise TypeError("transform_source must be a file path or a Callable.")
 
-    def predict_batch(self, inputs: Union[torch.Tensor, List[torch.Tensor]]) -> Dict[str, Any]:
+    def predict_batch(self, inputs: Union[torch.Tensor, list[torch.Tensor]]) -> dict[str, Any]:
         """
         Core batch prediction method for vision models.
         All preprocessing (resizing, normalization) should be done *before* calling this method.
@@ -207,7 +206,7 @@ class DragonVisionInferenceHandler(_BaseInferenceHandler):
                 # This should be unreachable due to validation
                 raise ValueError(f"Unknown task: {self.task}")
 
-    def predict(self, single_input: torch.Tensor) -> Dict[str, Any]:
+    def predict(self, single_input: torch.Tensor) -> dict[str, Any]:
         """
         Core single-sample prediction method for vision models.
         All preprocessing (resizing, normalization) should be done *before*
@@ -248,7 +247,7 @@ class DragonVisionInferenceHandler(_BaseInferenceHandler):
 
     # --- NumPy Convenience Wrappers (on CPU) ---
 
-    def predict_batch_numpy(self, inputs: Union[torch.Tensor, List[torch.Tensor]]) -> Dict[str, Any]:
+    def predict_batch_numpy(self, inputs: Union[torch.Tensor, list[torch.Tensor]]) -> dict[str, Any]:
         """
         Convenience wrapper for predict_batch that returns NumPy arrays. With Labels if set.
         
@@ -296,7 +295,7 @@ class DragonVisionInferenceHandler(_BaseInferenceHandler):
             
             return numpy_results
 
-    def predict_numpy(self, single_input: torch.Tensor) -> Dict[str, Any]:
+    def predict_numpy(self, single_input: torch.Tensor) -> dict[str, Any]:
         """
         Convenience wrapper for predict that returns NumPy arrays/scalars.
 
@@ -345,7 +344,7 @@ class DragonVisionInferenceHandler(_BaseInferenceHandler):
                 PyTorchInferenceKeys.PROBABILITIES: tensor_results[PyTorchInferenceKeys.PROBABILITIES].cpu().numpy()
             }
             
-    def predict_from_pil(self, image: Image.Image) -> Dict[str, Any]:
+    def predict_from_pil(self, image: Image.Image) -> dict[str, Any]:
         """
         Applies the stored transform to a single PIL image and returns the prediction.
 
@@ -383,7 +382,7 @@ class DragonVisionInferenceHandler(_BaseInferenceHandler):
         # Use the existing single-item predict method
         return self.predict_numpy(transformed_image)
 
-    def predict_from_file(self, image_path: Union[str, Path]) -> Dict[str, Any]:
+    def predict_from_file(self, image_path: Union[str, Path]) -> dict[str, Any]:
         """
         Loads a single image from a file, applies the stored transform, and returns the prediction.
 
@@ -416,6 +415,3 @@ class DragonVisionInferenceHandler(_BaseInferenceHandler):
         # Call the PIL-based prediction method
         return self.predict_from_pil(image)
 
-
-def info():
-    _script_info(__all__)

ml_tools/ML_models/__init__.py

@@ -0,0 +1,32 @@
+from ._mlp_attention import (
+    DragonMLP,
+    DragonAttentionMLP,
+    DragonMultiHeadAttentionNet
+)
+
+from ._advanced_models import (
+    DragonGateModel,
+    DragonNodeModel,
+    DragonAutoInt,
+    DragonTabNet
+)
+
+from ._dragon_tabular import DragonTabularTransformer
+
+from ._imprimir import info
+
+
+__all__ = [
+    # MLP and Attention Models
+    "DragonMLP",
+    "DragonAttentionMLP",
+    "DragonMultiHeadAttentionNet",
+    # Tabular Transformer Model
+    "DragonTabularTransformer",
+    # Advanced Models
+    "DragonGateModel",
+    "DragonNodeModel",
+    "DragonAutoInt",
+    "DragonTabNet",
+]
+

ml_tools/{_core/_ML_models_advanced.py → ML_models/_advanced_models.py}

@@ -1,12 +1,13 @@
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
-from typing import Dict, Any, Optional, Literal
+from typing import Any, Optional, Literal
 
-from ._models_advanced_base import _ArchitectureBuilder
-from ._schema import FeatureSchema
-from ._logger import get_logger
-from ._script_info import _script_info
+from ..schema import FeatureSchema
+from .._core import get_logger
+from ..keys._keys import SchemaKeys
+
+from ._base_save_load import _ArchitectureBuilder
 from ._models_advanced_helpers import (
     Embedding1dLayer,
     GatedFeatureLearningUnit,
@@ -335,16 +336,16 @@ class DragonGateModel(_ArchitectureBuilder):
                 if self.head.T0.shape == mean_target.shape:
                     self.head.T0.data = mean_target
                     _LOGGER.info(f"Initialized T0 to {mean_target.cpu().numpy()}")
-                elif self.head.T0.numel() == 1 and mean_target.numel() == 1:
+                elif self.head.T0.numel() == 1 and mean_target.numel() == 1: # type: ignore
                     # scalar case
-                    self.head.T0.data = mean_target.view(self.head.T0.shape)
+                    self.head.T0.data = mean_target.view(self.head.T0.shape) # type: ignore
                     _LOGGER.info("GATE Initialization Complete. Ready to train.")
                     # _LOGGER.info(f"Initialized T0 to {mean_target.item()}")
                 else:
                     _LOGGER.debug(f"Target shape mismatch for T0 init. Model: {self.head.T0.shape}, Data: {mean_target.shape}")
                     _LOGGER.warning(f"GATE initialization skipped due to shape mismatch:\n    Model: {self.head.T0.shape}\n    Data: {mean_target.shape}")
 
-    def get_architecture_config(self) -> Dict[str, Any]:
+    def get_architecture_config(self) -> dict[str, Any]:
         """Returns the full configuration of the model."""
         schema_dict = {
             'feature_names': self.schema.feature_names,
@@ -355,7 +356,7 @@ class DragonGateModel(_ArchitectureBuilder):
         }
         
         config = {
-            'schema_dict': schema_dict,
+            SchemaKeys.SCHEMA_DICT: schema_dict,
             'out_targets': self.out_targets,
             **self.model_hparams
         }
@@ -574,7 +575,7 @@ class DragonNodeModel(_ArchitectureBuilder):
             else:
                 _LOGGER.warning("NODE Backbone does not have an 'initialize' method. Skipping.")
             
-    def get_architecture_config(self) -> Dict[str, Any]:
+    def get_architecture_config(self) -> dict[str, Any]:
         """Returns the full configuration of the model."""
         schema_dict = {
             'feature_names': self.schema.feature_names,
@@ -585,7 +586,7 @@ class DragonNodeModel(_ArchitectureBuilder):
         }
         
         config = {
-            'schema_dict': schema_dict,
+            SchemaKeys.SCHEMA_DICT: schema_dict,
             'out_targets': self.out_targets,
             **self.model_hparams
         }
@@ -842,7 +843,7 @@ class DragonAutoInt(_ArchitectureBuilder):
             else:
                 _LOGGER.warning("AutoInt Head does not have a bias parameter. Skipping initialization.")
     
-    def get_architecture_config(self) -> Dict[str, Any]:
+    def get_architecture_config(self) -> dict[str, Any]:
         """Returns the full configuration of the model."""
         schema_dict = {
             'feature_names': self.schema.feature_names,
@@ -853,7 +854,7 @@ class DragonAutoInt(_ArchitectureBuilder):
         }
         
         config = {
-            'schema_dict': schema_dict,
+            SchemaKeys.SCHEMA_DICT: schema_dict,
             'out_targets': self.out_targets,
             **self.model_hparams
         }
@@ -1059,8 +1060,14 @@ class DragonTabNet(_ArchitectureBuilder):
 
         self.regularization_loss /= self.n_steps
         return self.final_mapping(out_accumulated)
+    
+    def data_aware_initialization(self, train_dataset, num_samples: int = 2000):
+        """  
+        TabNet does not require data-aware initialization. Method Implemented for compatibility.
+        """
+        _LOGGER.info("TabNet does not require data-aware initialization. Skipping.")
 
-    def get_architecture_config(self) -> Dict[str, Any]:
+    def get_architecture_config(self) -> dict[str, Any]:
         """Returns the full configuration of the model."""
         schema_dict = {
             'feature_names': self.schema.feature_names,
@@ -1071,12 +1078,9 @@ class DragonTabNet(_ArchitectureBuilder):
         }
         
         config = {
-            'schema_dict': schema_dict,
+            SchemaKeys.SCHEMA_DICT: schema_dict,
             'out_targets': self.out_targets,
             **self.model_hparams
         }
         return config
-    
 
-def info():
-    _script_info(__all__)