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

ml_tools/{_core → ensemble_evaluation}/_ensemble_evaluation.py

@@ -22,10 +22,9 @@ from sklearn.metrics import (accuracy_score,
 from pathlib import Path
 from typing import Union, Optional, Literal
 
-from ._path_manager import sanitize_filename, make_fullpath
-from ._script_info import _script_info
-from ._logger import get_logger
-from ._keys import SHAPKeys
+from ..path_manager import sanitize_filename, make_fullpath
+from .._core import get_logger
+from ..keys._keys import SHAPKeys
 
 
 _LOGGER = get_logger("Ensemble Evaluation")
@@ -731,6 +730,3 @@ def plot_learning_curves(
     fig.savefig(full_save_path, bbox_inches="tight", format="svg")
     plt.close(fig)
     
-
-def info():
-    _script_info(__all__)

ml_tools/ensemble_evaluation/_imprimir.py

@@ -0,0 +1,14 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "evaluate_model_classification",
+    "plot_roc_curve",
+    "plot_precision_recall_curve",
+    "plot_calibration_curve",
+    "evaluate_model_regression",
+    "get_shap_values",
+    "plot_learning_curves"
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{ensemble_inference.py → ensemble_inference/__init__.py}

@@ -1,9 +1,11 @@
-from ._core._ensemble_inference import (
+from ._ensemble_inference import (
     DragonEnsembleInferenceHandler,
-    model_report,
-    info
+    model_report
 )
 
+from ._imprimir import info
+
+
 __all__ = [
     "DragonEnsembleInferenceHandler",
     "model_report"

ml_tools/{_core → ensemble_inference}/_ensemble_inference.py

@@ -1,4 +1,4 @@
-from typing import Union, Literal, Dict, Any, Optional, List
+from typing import Union, Literal, Any, Optional
 from pathlib import Path
 import json
 import numpy as np
@@ -6,11 +6,11 @@ import numpy as np
 import xgboost
 import lightgbm
 
-from ._script_info import _script_info
-from ._logger import get_logger
-from ._path_manager import make_fullpath, list_files_by_extension
-from ._keys import EnsembleKeys
-from ._serde import deserialize_object
+from ..serde import deserialize_object
+
+from .._core import get_logger
+from ..path_manager import make_fullpath, list_files_by_extension
+from ..keys._keys import EnsembleKeys
 
 
 _LOGGER = get_logger("Ensemble Inference")
@@ -37,10 +37,10 @@ class DragonEnsembleInferenceHandler:
             models_dir (Path): The directory containing the saved .joblib model files.
             task ("regression" | "classification"): The type of task the models perform.
         """
-        self.models: Dict[str, Any] = dict()
+        self.models: dict[str, Any] = dict()
         self.task: str = task
         self.verbose = verbose
-        self._feature_names: Optional[List[str]] = None
+        self._feature_names: Optional[list[str]] = None
         
         model_files = list_files_by_extension(directory=models_dir, extension="joblib", raise_on_empty=True)
         
@@ -53,7 +53,7 @@ class DragonEnsembleInferenceHandler:
                 
                 model: Any = full_object[EnsembleKeys.MODEL]
                 target_name: str = full_object[EnsembleKeys.TARGET]
-                feature_names_list: List[str] = full_object[EnsembleKeys.FEATURES]
+                feature_names_list: list[str] = full_object[EnsembleKeys.FEATURES]
                 
                 # Check that feature names match
                 if self._feature_names is None:
@@ -71,14 +71,14 @@ class DragonEnsembleInferenceHandler:
                 _LOGGER.error(f"Failed to load or parse {fname}.")
 
     @property
-    def feature_names(self) -> List[str]:
+    def feature_names(self) -> list[str]:
         """
         Getter for the list of feature names the models expect.
         Returns an empty list if no models were loaded.
         """
         return self._feature_names if self._feature_names is not None else []
     
-    def predict(self, features: np.ndarray) -> Dict[str, Any]:
+    def predict(self, features: np.ndarray) -> dict[str, Any]:
         """
         Predicts on a single feature vector.
 
@@ -97,7 +97,7 @@ class DragonEnsembleInferenceHandler:
             _LOGGER.error("The 'predict()' method is for a single sample. Use 'predict_batch()' for multiple samples.")
             raise ValueError()
 
-        results: Dict[str, Any] = dict()
+        results: dict[str, Any] = dict()
         for target_name, model in self.models.items():
             if self.task == "regression":
                 prediction = model.predict(features)
@@ -112,7 +112,7 @@ class DragonEnsembleInferenceHandler:
             _LOGGER.info("Inference process complete.")
         return results
 
-    def predict_batch(self, features: np.ndarray) -> Dict[str, Any]:
+    def predict_batch(self, features: np.ndarray) -> dict[str, Any]:
         """
         Predicts on a batch of feature vectors.
 
@@ -128,7 +128,7 @@ class DragonEnsembleInferenceHandler:
             _LOGGER.error("Input for batch prediction must be a 2D array.")
             raise ValueError()
 
-        results: Dict[str, Any] = dict()
+        results: dict[str, Any] = dict()
         for target_name, model in self.models.items():
             if self.task == "regression":
                 results[target_name] = model.predict(features)
@@ -147,7 +147,7 @@ def model_report(
         model_path: Union[str,Path],
         output_dir: Optional[Union[str,Path]] = None,
         verbose: bool = True
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
     """
     Deserializes a model and generates a summary report.
 
@@ -220,6 +220,3 @@ def model_report(
     # --- 5. Return the extracted data ---
     return report_data
 
-
-def info():
-    _script_info(__all__)

ml_tools/ensemble_inference/_imprimir.py

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

ml_tools/{ensemble_learning.py → ensemble_learning/__init__.py}

@@ -1,16 +1,14 @@
-from ._core._ensemble_learning import (
+from ._ensemble_learning import (
     RegressionTreeModels,
     ClassificationTreeModels,
-    dataset_pipeline,
-    train_test_pipeline,
     run_ensemble_pipeline,
-    info
 )
 
+from ._imprimir import info
+
+
 __all__ = [
     "RegressionTreeModels",
     "ClassificationTreeModels",
-    "dataset_pipeline",
-    "train_test_pipeline",
     "run_ensemble_pipeline",
 ]

ml_tools/{_core → ensemble_learning}/_ensemble_learning.py

@@ -13,13 +13,9 @@ import lightgbm as lgb
 from sklearn.model_selection import train_test_split
 from sklearn.base import clone
 
-from ._utilities import yield_dataframes_from_dir, train_dataset_yielder
-from ._serde import serialize_object_filename
-from ._path_manager import sanitize_filename, make_fullpath
-from ._script_info import _script_info
-from ._keys import EnsembleKeys
-from ._logger import get_logger
-from ._ensemble_evaluation import (evaluate_model_classification,
+from ..utilities import yield_dataframes_from_dir, train_dataset_yielder
+from ..serde import serialize_object_filename
+from ..ensemble_evaluation import (evaluate_model_classification,
                                   plot_roc_curve,
                                   plot_precision_recall_curve,
                                   plot_calibration_curve,
@@ -27,6 +23,10 @@ from ._ensemble_evaluation import (evaluate_model_classification,
                                   get_shap_values,
                                   plot_learning_curves)
 
+from ..path_manager import sanitize_filename, make_fullpath
+from ..keys._keys import EnsembleKeys
+from .._core import get_logger
+
 import warnings # Ignore warnings 
 warnings.filterwarnings('ignore', category=DeprecationWarning)
 warnings.filterwarnings('ignore', category=FutureWarning)
@@ -528,6 +528,3 @@ def run_ensemble_pipeline(datasets_dir: Union[str,Path], save_dir: Union[str,Pat
 
     _LOGGER.info("Training and evaluation complete.")
 
-
-def info():
-    _script_info(__all__)

ml_tools/ensemble_learning/_imprimir.py

@@ -0,0 +1,10 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "RegressionTreeModels",
+    "ClassificationTreeModels",
+    "run_ensemble_pipeline",
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{excel_handler.py → excel_handler/__init__.py}

@@ -1,13 +1,15 @@
-from ._core._excel_handler import (
+from ._excel_handler import (
     find_excel_files,
     unmerge_and_split_excel,
     unmerge_and_split_from_directory,
     validate_excel_schema,
     vertical_merge_transform_excel,
-    horizontal_merge_transform_excel,
-    info
+    horizontal_merge_transform_excel
 )
 
+from ._imprimir import info
+
+
 __all__ = [
     "find_excel_files",
     "unmerge_and_split_excel",

ml_tools/{_core → excel_handler}/_excel_handler.py

@@ -1,11 +1,10 @@
 from pathlib import Path
 from openpyxl import load_workbook, Workbook
 import pandas as pd
-from typing import List, Optional, Union
+from typing import Optional, Union
 
-from ._path_manager import sanitize_filename, make_fullpath
-from ._script_info import _script_info
-from ._logger import get_logger
+from ..path_manager import sanitize_filename, make_fullpath
+from .._core import get_logger
 
 
 _LOGGER = get_logger("Excel Handler")
@@ -167,7 +166,7 @@ def unmerge_and_split_from_directory(input_dir: Union[str,Path], output_dir: Uni
 
 def validate_excel_schema(
     target_dir: Union[str,Path],
-    expected_columns: List[str],
+    expected_columns: list[str],
     strict: bool = False
 ) -> None:
     """
@@ -236,8 +235,8 @@ def vertical_merge_transform_excel(
     target_dir: Union[str,Path],
     csv_filename: str,
     output_dir: Union[str,Path],
-    target_columns: Optional[List[str]] = None,
-    rename_columns: Optional[List[str]] = None
+    target_columns: Optional[list[str]] = None,
+    rename_columns: Optional[list[str]] = None
 ) -> None:
     """
     Merges multiple Excel files in a directory vertically and saves as a single CSV file.
@@ -371,6 +370,3 @@ def horizontal_merge_transform_excel(
 
     _LOGGER.info(f"Merged {len(excel_files)} Excel files into '{csv_filename}'.")
     
-
-def info():
-    _script_info(__all__)

ml_tools/excel_handler/_imprimir.py

@@ -0,0 +1,13 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "find_excel_files",
+    "unmerge_and_split_excel",
+    "unmerge_and_split_from_directory",
+    "validate_excel_schema",
+    "vertical_merge_transform_excel",
+    "horizontal_merge_transform_excel"
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{keys.py → keys/__init__.py}

@@ -1,10 +1,13 @@
-from ._core._keys import (
+from ._keys import (
     PyTorchInferenceKeys as InferenceKeys,
     _CheckpointCallbackKeys as CheckpointCallbackKeys,
     _FinalizedFileKeys as FinalizedFileKeys,
     _PublicTaskKeys as TaskKeys,
 )
 
+from ._imprimir import info
+
+
 __all__ = [
     "InferenceKeys",
     "CheckpointCallbackKeys",

ml_tools/keys/_imprimir.py

@@ -0,0 +1,11 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "InferenceKeys",
+    "CheckpointCallbackKeys",
+    "FinalizedFileKeys",
+    "TaskKeys",
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{_core → keys}/_keys.py

@@ -262,6 +262,8 @@ class SchemaKeys:
     """Used by the schema module."""
     SCHEMA_FILENAME = "FeatureSchema.json"
     GUI_SCHEMA_FILENAME = "GUISchema.json"
+    # Model architecture API
+    SCHEMA_DICT = "schema_dict"
     # GUI Schema
     TARGETS = "targets"
     CONTINUOUS = "continuous"

ml_tools/{math_utilities.py → math_utilities/__init__.py}

@@ -1,11 +1,14 @@
-from ._core._math_utilities import (
+from ._math_utilities import (
     normalize_mixed_list,
     threshold_binary_values,
     threshold_binary_values_batch,
     discretize_categorical_values,
-    info
 )
 
+
+from ._imprimir import info
+
+
 __all__ = [
     "normalize_mixed_list",
     "threshold_binary_values",

ml_tools/math_utilities/_imprimir.py

@@ -0,0 +1,11 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "normalize_mixed_list",
+    "threshold_binary_values",
+    "threshold_binary_values_batch",
+    "discretize_categorical_values",
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{_core → math_utilities}/_math_utilities.py

@@ -3,8 +3,7 @@ import numpy as np
 import math
 from typing import Union, Sequence, Optional
 
-from ._script_info import _script_info
-from ._logger import get_logger
+from .._core import get_logger
 
 
 _LOGGER = get_logger("Math Utilities")
@@ -260,6 +259,3 @@ def discretize_categorical_values(
     else:
         return final_output
 
-
-def info():
-    _script_info(__all__)

ml_tools/{optimization_tools.py → optimization_tools/__init__.py}

@@ -1,13 +1,18 @@
-from ._core._optimization_tools import (
+from ._optimization_plots import (
+    plot_optimal_feature_distributions,
+    plot_optimal_feature_distributions_from_dataframe,
+)
+
+from ._optimization_bounds import (
     make_continuous_bounds_template,
     load_continuous_bounds_template,
     create_optimization_bounds,
     parse_lower_upper_bounds,
-    plot_optimal_feature_distributions,
-    plot_optimal_feature_distributions_from_dataframe,
-    info
 )
 
+from ._imprimir import info
+
+
 __all__ = [
     "make_continuous_bounds_template",
     "load_continuous_bounds_template",

ml_tools/optimization_tools/_imprimir.py

@@ -0,0 +1,13 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "make_continuous_bounds_template",
+    "load_continuous_bounds_template",
+    "create_optimization_bounds",
+    "parse_lower_upper_bounds",
+    "plot_optimal_feature_distributions",
+    "plot_optimal_feature_distributions_from_dataframe",
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/optimization_tools/_optimization_bounds.py

@@ -0,0 +1,236 @@
+from typing import Union, Any, Optional
+from pathlib import Path
+
+from ..schema import FeatureSchema
+from ..IO_tools import save_json, load_json
+
+from ..keys._keys import OptimizationToolsKeys
+from ..path_manager import make_fullpath
+from .._core import get_logger
+
+
+_LOGGER = get_logger("Optimization Bounds")
+
+
+__all__ = [
+    "make_continuous_bounds_template",
+    "load_continuous_bounds_template",
+    "create_optimization_bounds",
+    "parse_lower_upper_bounds",
+]
+
+
+def make_continuous_bounds_template(
+    directory: Union[str, Path],
+    feature_schema: FeatureSchema,
+    default_bounds: tuple[float, float] = (0, 1)
+) -> None:
+    """
+    Creates a JSON template for manual entry of continuous feature optimization bounds.
+
+    The resulting file maps each continuous feature name to a [min, max] list 
+    populated with `default_bounds`. Edit the values in this file before using.
+
+    Args:
+        directory (str | Path): The directory where the template will be saved.
+        feature_schema (FeatureSchema): The loaded schema containing feature definitions.
+        default_bounds (Tuple[float, float]): Default (min, max) values to populate the template.
+    """
+    # validate directory path
+    dir_path = make_fullpath(directory, make=True, enforce="directory")
+    
+    # 1. Check if continuous features exist
+    if not feature_schema.continuous_feature_names:
+        _LOGGER.warning("No continuous features found in FeatureSchema. Skipping bounds template generation.")
+        return
+
+    # 2. Construct the dictionary: {feature_name: [min, max]}
+    bounds_map = {
+        name: list(default_bounds)
+        for name in feature_schema.continuous_feature_names
+    }
+    
+    # use a fixed key for the filename
+    filename = OptimizationToolsKeys.OPTIMIZATION_BOUNDS_FILENAME + ".json"
+
+    # 3. Save to JSON using the IO tool
+    save_json(
+        data=bounds_map,
+        directory=dir_path,
+        filename=filename,
+        verbose=False
+    )
+    
+    _LOGGER.info(f"💾 Continuous bounds template saved to: '{dir_path.name}/{filename}'")
+    
+
+def load_continuous_bounds_template(directory: Union[str, Path]) -> dict[str, list[float]]:
+    """
+    Loads the continuous feature bounds template from JSON. Expected filename: `optimization_bounds.json`.
+
+    Args:
+        directory (str | Path): The directory where the template is located.
+
+    Returns:
+        Dictionary (Dict[str, List[float]]): A dictionary mapping feature names to [min, max] bounds.
+    """
+    dir_path = make_fullpath(directory, enforce="directory")
+    full_path = dir_path / (OptimizationToolsKeys.OPTIMIZATION_BOUNDS_FILENAME + ".json")
+    
+    bounds_map = load_json(
+        file_path=full_path,
+        expected_type='dict',
+        verbose=False
+    )
+    
+    # validate loaded data
+    if not all(
+            isinstance(v, list) and     # Check type
+            len(v) == 2 and     # Check length
+            all(isinstance(i, (int, float)) for i in v) # Check contents are numbers
+            for v in bounds_map.values()
+        ):
+        _LOGGER.error(f"Invalid format in bounds template at '{full_path}'. Each value must be a list of [min, max].")
+        raise ValueError()
+    
+    _LOGGER.info(f"Continuous bounds template loaded from: '{dir_path.name}'")
+    
+    return bounds_map
+
+
+def create_optimization_bounds(
+    schema: FeatureSchema,
+    continuous_bounds_map: Union[dict[str, tuple[float, float]], dict[str, list[float]]],
+    start_at_zero: bool = True
+) -> tuple[list[float], list[float]]:
+    """
+    Generates the lower and upper bounds lists for the optimizer from a FeatureSchema.
+
+    This helper function automates the creation of unbiased bounds for
+    categorical features and combines them with user-defined bounds for
+    continuous features, using the schema as the single source of truth
+    for feature order and type.
+
+    Args:
+        schema (FeatureSchema):
+            The definitive schema object created by 
+            `data_exploration.finalize_feature_schema()`.
+        continuous_bounds_map (Dict[str, Tuple[float, float]], Dict[str, List[float]]):
+            A dictionary mapping the *name* of each **continuous** feature
+            to its (min_bound, max_bound).
+        start_at_zero (bool):
+            - If True, assumes categorical encoding is [0, 1, ..., k-1].
+              Bounds will be set as [-0.5, k - 0.5].
+            - If False, assumes encoding is [1, 2, ..., k].
+              Bounds will be set as [0.5, k + 0.5].
+
+    Returns:
+        Tuple[List[float], List[float]]:
+            A tuple containing two lists: (lower_bounds, upper_bounds).
+
+    Raises:
+        ValueError: If a feature is missing from `continuous_bounds_map`
+                    or if a feature name in the map is not a
+                    continuous feature according to the schema.
+    """
+    # validate length in the continuous_bounds_map values
+    for name, bounds in continuous_bounds_map.items():
+        if not (isinstance(bounds, (list, tuple)) and len(bounds) == 2):
+            _LOGGER.error(f"Bounds for feature '{name}' must be a list or tuple of length 2 (min, max). Found: {bounds}")
+            raise ValueError()
+    
+    # 1. Get feature names and map from schema
+    feature_names = schema.feature_names
+    categorical_index_map = schema.categorical_index_map
+    total_features = len(feature_names)
+
+    if total_features <= 0:
+        _LOGGER.error("Schema contains no features.")
+        raise ValueError()
+        
+    _LOGGER.info(f"Generating bounds for {total_features} total features...")
+
+    # 2. Initialize bound lists
+    lower_bounds: list[Optional[float]] = [None] * total_features
+    upper_bounds: list[Optional[float]] = [None] * total_features
+
+    # 3. Populate categorical bounds (Index-based)
+    if categorical_index_map:
+        for index, cardinality in categorical_index_map.items():
+            if not (0 <= index < total_features):
+                _LOGGER.error(f"Categorical index {index} is out of range for the {total_features} features.")
+                raise ValueError()
+                
+            if start_at_zero:
+                # Rule for [0, k-1]: bounds are [-0.5, k - 0.5]
+                low = -0.5
+                high = float(cardinality) - 0.5
+            else:
+                # Rule for [1, k]: bounds are [0.5, k + 0.5]
+                low = 0.5
+                high = float(cardinality) + 0.5
+                
+            lower_bounds[index] = low
+            upper_bounds[index] = high
+        
+        _LOGGER.info(f"Automatically set bounds for {len(categorical_index_map)} categorical features.")
+    else:
+        _LOGGER.info("No categorical features found in schema.")
+
+    # 4. Populate continuous bounds (Name-based)
+    # Use schema.continuous_feature_names for robust checking
+    continuous_names_set = set(schema.continuous_feature_names)
+    
+    if continuous_names_set != set(continuous_bounds_map.keys()):
+        missing_in_map = continuous_names_set - set(continuous_bounds_map.keys())
+        if missing_in_map:
+            _LOGGER.error(f"The following continuous features are missing from 'continuous_bounds_map': {list(missing_in_map)}")
+        
+        extra_in_map = set(continuous_bounds_map.keys()) - continuous_names_set
+        if extra_in_map:
+            _LOGGER.error(f"The following features in 'continuous_bounds_map' are not defined as continuous in the schema: {list(extra_in_map)}")
+            
+        raise ValueError("Mismatch between 'continuous_bounds_map' and schema's continuous features.")
+
+    count_continuous = 0
+    for name, (low, high) in continuous_bounds_map.items():
+        # Map name to its index in the *feature-only* list
+        # This is guaranteed to be correct by the schema
+        index = feature_names.index(name)
+
+        if lower_bounds[index] is not None:
+            # This should be impossible if schema is correct, but good to check
+            _LOGGER.error(f"Schema conflict: Feature '{name}' (at index {index}) is defined as both continuous and categorical.")
+            raise ValueError()
+
+        lower_bounds[index] = float(low)
+        upper_bounds[index] = float(high)
+        count_continuous += 1
+        
+    _LOGGER.info(f"Manually set bounds for {count_continuous} continuous features.")
+
+    # 5. Final Validation (all Nones should be filled)
+    if None in lower_bounds:
+        missing_indices = [i for i, b in enumerate(lower_bounds) if b is None]
+        missing_names = [feature_names[i] for i in missing_indices]
+        _LOGGER.error(f"Failed to create all bounds. This indicates an internal logic error. Missing: {missing_names}")
+        raise RuntimeError("Internal error: Not all bounds were populated.")
+    
+    # Cast to float lists, as 'None' sentinels are gone
+    return (
+        [float(b) for b in lower_bounds],  # type: ignore
+        [float(b) for b in upper_bounds] # type: ignore
+    )
+
+
+def parse_lower_upper_bounds(source: dict[str,tuple[Any,Any]]):
+    """
+    Parse lower and upper boundaries, returning 2 lists:
+    
+    `lower_bounds`, `upper_bounds`
+    """
+    lower = [low[0] for low in source.values()]
+    upper = [up[1] for up in source.values()]
+    
+    return lower, upper
+