dragon-ml-toolbox 6.0.1__tar.gz → 6.1.1__tar.gz

{dragon_ml_toolbox-6.0.1/dragon_ml_toolbox.egg-info → dragon_ml_toolbox-6.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dragon-ml-toolbox
-Version: 6.0.1
+Version: 6.1.1
 Summary: A collection of tools for data science and machine learning projects.
 Author-email: Karl Loza <luigiloza@gmail.com>
 License-Expression: MIT

{dragon_ml_toolbox-6.0.1 → dragon_ml_toolbox-6.1.1/dragon_ml_toolbox.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dragon-ml-toolbox
-Version: 6.0.1
+Version: 6.1.1
 Summary: A collection of tools for data science and machine learning projects.
 Author-email: Karl Loza <luigiloza@gmail.com>
 License-Expression: MIT

{dragon_ml_toolbox-6.0.1 → dragon_ml_toolbox-6.1.1}/ml_tools/ML_inference.py

@@ -66,47 +66,10 @@ class PyTorchInferenceHandler:
         
         # Ensure tensor is on the correct device
         return features.to(self.device)
-
-    def predict(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, Any]:
-        """
-        Predicts on a single feature vector.
-
-        Args:
-            features (np.ndarray | torch.Tensor): A 1D or 2D array/tensor for a single sample.
-
-        Returns:
-            Dict[str, Any]: A dictionary containing the prediction.
-                - For regression: {'predictions': float}
-                - For classification: {'labels': int, 'probabilities': np.ndarray}
+    
+    def predict_batch(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, torch.Tensor]:
         """
-        if features.ndim == 1:
-            features = features.reshape(1, -1)
-        
-        if features.shape[0] != 1:
-            raise ValueError("The predict() method is for a single sample. Use predict_batch() for multiple samples.")
-
-        results_batch = self.predict_batch(features)
-
-        # Extract the single result from the batch
-        if self.task == "regression":
-            return {PyTorchInferenceKeys.PREDICTIONS: results_batch[PyTorchInferenceKeys.PREDICTIONS].item()}
-        else: # classification
-            return {
-                PyTorchInferenceKeys.LABELS: results_batch[PyTorchInferenceKeys.LABELS].item(),
-                PyTorchInferenceKeys.PROBABILITIES: results_batch[PyTorchInferenceKeys.PROBABILITIES][0]
-            }
-
-    def predict_batch(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, Any]:
-        """
-        Predicts on a batch of feature vectors.
-
-        Args:
-            features (np.ndarray | torch.Tensor): A 2D array/tensor where each row is a sample.
-
-        Returns:
-            Dict[str, Any]: A dictionary containing the predictions.
-                - For regression: {'predictions': np.ndarray}
-                - For classification: {'labels': np.ndarray, 'probabilities': np.ndarray}
+        Core batch prediction method. Returns results as PyTorch tensors on the model's device.
         """
         if features.ndim != 2:
             raise ValueError("Input for batch prediction must be a 2D array or tensor.")
@@ -114,18 +77,61 @@ class PyTorchInferenceHandler:
         input_tensor = self._preprocess_input(features)
         
         with torch.no_grad():
-            output = self.model(input_tensor).cpu()
+            # Output tensor remains on the model's device (e.g., 'mps' or 'cuda')
+            output = self.model(input_tensor)
 
             if self.task == "classification":
                 probs = nn.functional.softmax(output, dim=1)
                 labels = torch.argmax(probs, dim=1)
                 return {
-                    PyTorchInferenceKeys.LABELS: labels.numpy(),
-                    PyTorchInferenceKeys.PROBABILITIES: probs.numpy()
+                    PyTorchInferenceKeys.LABELS: labels,
+                    PyTorchInferenceKeys.PROBABILITIES: probs
                 }
             else:  # regression
-                return {PyTorchInferenceKeys.PREDICTIONS: output.numpy()}
+                return {PyTorchInferenceKeys.PREDICTIONS: output}
 
+    def predict(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, torch.Tensor]:
+        """
+        Core single-sample prediction. Returns results as PyTorch tensors on the model's device.
+        """
+        if features.ndim == 1:
+            features = features.reshape(1, -1)
+        
+        if features.shape[0] != 1:
+            raise ValueError("The predict() method is for a single sample. Use predict_batch() for multiple samples.")
+
+        batch_results = self.predict_batch(features)
+        
+        single_results = {key: value[0] for key, value in batch_results.items()}
+        return single_results
+
+    # --- NumPy Convenience Wrappers (on CPU) ---
+
+    def predict_batch_numpy(self, features: Union[np.ndarray, torch.Tensor]) -> Dict[str, np.ndarray]:
+        """
+        Convenience wrapper for predict_batch that returns NumPy arrays.
+        """
+        tensor_results = self.predict_batch(features)
+        # Move tensor to CPU before converting to NumPy
+        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]:
+        """
+        Convenience wrapper for predict that returns NumPy arrays or scalars.
+        """
+        tensor_results = self.predict(features)
+        
+        if self.task == "regression":
+            # .item() implicitly moves to CPU
+            return {PyTorchInferenceKeys.PREDICTIONS: tensor_results[PyTorchInferenceKeys.PREDICTIONS].item()}
+        else: # classification
+            return {
+                PyTorchInferenceKeys.LABELS: tensor_results[PyTorchInferenceKeys.LABELS].item(),
+                # ✅ Move tensor to CPU before converting to NumPy
+                PyTorchInferenceKeys.PROBABILITIES: tensor_results[PyTorchInferenceKeys.PROBABILITIES].cpu().numpy()
+            }
+     
 
 def info():
     _script_info(__all__)

dragon_ml_toolbox-6.1.1/ml_tools/ML_optimization.py

@@ -0,0 +1,308 @@
+import pandas # logger
+import torch
+import numpy    #handling torch to numpy
+import evotorch
+from evotorch.algorithms import SNES, CEM, GeneticAlgorithm
+from evotorch.logging import PandasLogger
+from evotorch.operators import SimulatedBinaryCrossOver, GaussianMutation
+from typing import Literal, Union, Tuple, List, Optional, Any, Callable
+from pathlib import Path
+from tqdm.auto import trange
+from contextlib import nullcontext
+from functools import partial
+
+from .path_manager import make_fullpath, sanitize_filename
+from ._logger import _LOGGER
+from ._script_info import _script_info
+from .ML_inference import PyTorchInferenceHandler
+from .keys import PyTorchInferenceKeys
+from .SQL import DatabaseManager
+from .optimization_tools import _save_result
+from .utilities import threshold_binary_values, save_dataframe
+
+__all__ = [
+    "create_pytorch_problem",
+    "run_optimization"
+]
+
+
+def create_pytorch_problem(
+    inference_handler: PyTorchInferenceHandler,
+    bounds: Tuple[List[float], List[float]],
+    binary_features: int,
+    task: Literal["min", "max"],
+    algorithm: Literal["SNES", "CEM", "Genetic"] = "Genetic",
+    population_size: int = 200,
+    **searcher_kwargs
+) -> Tuple[evotorch.Problem, Callable[[], Any]]:
+    """
+    Creates and configures an EvoTorch Problem and a Searcher factory class for a PyTorch model.
+    
+    SNES and CEM do not accept bounds, the given bounds will be used as initial bounds only.
+    
+    The Genetic Algorithm works directly with the bounds, and operators such as SimulatedBinaryCrossOver and GaussianMutation.
+    
+    Args:
+        inference_handler (PyTorchInferenceHandler): An initialized inference handler containing the model and weights.
+        bounds (tuple[list[float], list[float]]): A tuple containing the lower and upper bounds for the solution features.
+        binary_features (int): Number of binary features located at the END of the feature vector. Will be automatically added to the bounds.
+        task (str): The optimization goal, either "minimize" or "maximize".
+        algorithm (str): The search algorithm to use.
+        population_size (int): Used for CEM and GeneticAlgorithm.
+        **searcher_kwargs: Additional keyword arguments to pass to the
+            selected search algorithm's constructor (e.g., stdev_init=0.5 for CMAES).
+
+    Returns:
+        Tuple:
+        A tuple containing the configured Problem and Searcher.
+    """
+    # Create copies to avoid modifying the original lists passed in the `bounds` tuple
+    lower_bounds = list(bounds[0])
+    upper_bounds = list(bounds[1])
+    
+    # add binary bounds
+    if binary_features > 0:
+        lower_bounds.extend([0.45] * binary_features)
+        upper_bounds.extend([0.55] * binary_features)
+    
+    solution_length = len(lower_bounds)
+    device = inference_handler.device
+
+    # Define the fitness function that EvoTorch will call.
+    def fitness_func(solution_tensor: torch.Tensor) -> torch.Tensor:
+        # Directly use the continuous-valued tensor from the optimizer for prediction
+        predictions = inference_handler.predict_batch(solution_tensor)[PyTorchInferenceKeys.PREDICTIONS]
+        return predictions.flatten()
+    
+    
+    # Create the Problem instance.
+    if algorithm == "CEM" or algorithm == "SNES":
+        problem = evotorch.Problem(
+            objective_sense=task,
+            objective_func=fitness_func,
+            solution_length=solution_length,
+            initial_bounds=(lower_bounds, upper_bounds),
+            device=device,
+            vectorized=True #Use batches
+        )
+        
+        # If stdev_init is not provided, calculate it based on the bounds (used for SNES and CEM)
+        if 'stdev_init' not in searcher_kwargs:
+            # Calculate stdev for each parameter as 25% of its search range
+            stdevs = [abs(up - low) * 0.25 for low, up in zip(lower_bounds, upper_bounds)]
+            searcher_kwargs['stdev_init'] = torch.tensor(stdevs, dtype=torch.float32, requires_grad=False)
+        
+        if algorithm == "SNES":
+            SearcherClass = SNES
+        elif algorithm == "CEM":
+            SearcherClass = CEM
+            # Set a defaults for CEM if not provided
+            if 'popsize' not in searcher_kwargs:
+                searcher_kwargs['popsize'] = population_size
+            if 'parenthood_ratio' not in searcher_kwargs:
+                searcher_kwargs['parenthood_ratio'] = 0.2   #float 0.0 - 1.0
+        
+    elif algorithm == "Genetic":
+        problem = evotorch.Problem(
+            objective_sense=task,
+            objective_func=fitness_func,
+            solution_length=solution_length,
+            bounds=(lower_bounds, upper_bounds),
+            device=device,
+            vectorized=True #Use batches
+        )
+
+        operators = [
+            SimulatedBinaryCrossOver(problem,
+                                    tournament_size=4,
+                                    eta=0.8),
+            GaussianMutation(problem,
+                            stdev=0.1)
+        ]
+        
+        searcher_kwargs["operators"] = operators
+        if 'popsize' not in searcher_kwargs:
+            searcher_kwargs['popsize'] = population_size
+        
+        SearcherClass = GeneticAlgorithm
+        
+    else:
+        raise ValueError(f"Unknown algorithm '{algorithm}'.")
+    
+    # Create a factory function with all arguments pre-filled
+    searcher_factory = partial(SearcherClass, problem, **searcher_kwargs)
+
+    return problem, searcher_factory
+
+
+def run_optimization(
+    problem: evotorch.Problem,
+    searcher_factory: Callable[[],Any],
+    num_generations: int,
+    target_name: str,
+    binary_features: int,
+    save_dir: Union[str, Path],
+    save_format: Literal['csv', 'sqlite', 'both'],
+    feature_names: Optional[List[str]],
+    repetitions: int = 1,
+    verbose: bool = True
+) -> Optional[dict]:
+    """
+    Runs the evolutionary optimization process, with support for multiple repetitions.
+
+    This function serves as the main engine for the optimization task. It takes a
+    configured Problem and a Searcher from EvoTorch and executes the optimization
+    for a specified number of generations.
+
+    It has two modes of operation:
+    1.  **Single Run (repetitions=1):** Executes the optimization once, saves the
+        single best result to a CSV file, and returns it as a dictionary.
+    2.  **Iterative Analysis (repetitions > 1):** Executes the optimization
+        multiple times. Results from each run are streamed incrementally to the
+        specified file formats (CSV and/or SQLite database). In this mode,
+        the function returns None.
+
+    Args:
+        problem (evotorch.Problem): The configured problem instance, which defines
+            the objective function, solution space, and optimization sense.
+        searcher_factory (Callable): The searcher factory to generate fresh evolutionary algorithms.
+        num_generations (int): The total number of generations to run the search algorithm for in each repetition.
+        target_name (str): Target name that will also be used for the CSV filename and SQL table.
+        binary_features (int): Number of binary features located at the END of the feature vector.
+        save_dir (str | Path): The directory where the result file(s) will be saved.
+        save_format (Literal['csv', 'sqlite', 'both'], optional): The format for
+            saving results during iterative analysis.
+        feature_names (List[str], optional): Names of the solution features for
+            labeling the output files. If None, generic names like 'feature_0',
+            'feature_1', etc., will be created.
+        repetitions (int, optional): The number of independent times to run the
+            entire optimization process.
+        verbose (bool): Add an Evotorch Pandas logger saved as a csv. Only for the first repetition.
+
+    Returns:
+        Optional[dict]: A dictionary containing the best feature values and the
+        fitness score if `repetitions` is 1. Returns `None` if `repetitions`
+        is greater than 1, as results are streamed to files instead.
+    """
+    # preprocess paths
+    save_path = make_fullpath(save_dir, make=True, enforce="directory")
+    
+    sanitized_target_name = sanitize_filename(target_name)
+    if not sanitized_target_name.endswith(".csv"):
+        sanitized_target_name = sanitized_target_name + ".csv"
+    
+    csv_path = save_path / sanitized_target_name
+    
+    db_path = save_path / "Optimization.db"
+    db_table_name = target_name
+    
+    # preprocess feature names
+    if feature_names is None:
+        feature_names = [f"feature_{i}" for i in range(problem.solution_length)] # type: ignore
+    
+    # --- SINGLE RUN LOGIC ---
+    if repetitions <= 1:
+        searcher = searcher_factory()
+        _LOGGER.info(f"🤖 Starting optimization with {searcher.__class__.__name__} Algorithm for {num_generations} generations...")
+        # for _ in trange(num_generations, desc="Optimizing"):
+        #     searcher.step()
+        
+        # Attach logger if requested
+        if verbose:
+            pandas_logger = PandasLogger(searcher)
+            
+        searcher.run(num_generations) # Use the built-in run method for simplicity
+            
+        # # DEBUG new searcher objects
+        # for status_key in searcher.iter_status_keys():
+        #     print("===", status_key, "===")
+        #     print(searcher.status[status_key])
+        #     print()
+        
+        # Get results from the .status dictionary 
+        # SNES and CEM use the key 'center' to get mean values if needed    best_solution_tensor = searcher.status["center"]
+        best_solution_container = searcher.status["pop_best"]
+        best_solution_tensor = best_solution_container.values
+        best_fitness = best_solution_container.evals
+
+        best_solution_np = best_solution_tensor.cpu().numpy()
+        
+        # threshold binary features
+        if binary_features > 0:
+            best_solution_thresholded = threshold_binary_values(input_array=best_solution_np, binary_values=binary_features)
+        else:
+            best_solution_thresholded = best_solution_np
+
+        result_dict = {name: value for name, value in zip(feature_names, best_solution_thresholded)}
+        result_dict[target_name] = best_fitness.item()
+        
+        _save_result(result_dict, 'csv', csv_path) # Single run defaults to CSV
+        
+        # Process logger
+        if verbose:
+            _handle_pandas_log(pandas_logger, save_path=save_path)
+        
+        _LOGGER.info(f"✅ Optimization complete. Best solution saved to '{csv_path.name}'")
+        return result_dict
+
+    # --- MULTIPLE REPETITIONS LOGIC ---
+    else:
+        _LOGGER.info(f"🏁 Starting optimal solution space analysis with {repetitions} repetitions...")
+
+        db_context = DatabaseManager(db_path) if save_format in ['sqlite', 'both'] else nullcontext()
+        
+        with db_context as db_manager:
+            if db_manager:
+                schema = {name: "REAL" for name in feature_names}
+                schema[target_name] = "REAL"
+                db_manager.create_table(db_table_name, schema)
+            
+            print("")
+            # Repetitions loop
+            pandas_logger = None
+            for i in trange(repetitions, desc="Repetitions"):
+                # CRITICAL: Create a fresh searcher for each run using the factory
+                searcher = searcher_factory()
+                
+                # Attach logger if requested
+                if verbose and i==0:
+                    pandas_logger = PandasLogger(searcher)
+                
+                searcher.run(num_generations) # Use the built-in run method for simplicity
+                
+                # Get results from the .status dictionary 
+                # SNES and CEM use the key 'center' to get mean values if needed    best_solution_tensor = searcher.status["center"]
+                best_solution_container = searcher.status["pop_best"]
+                best_solution_tensor = best_solution_container.values
+                best_fitness = best_solution_container.evals
+             
+                best_solution_np = best_solution_tensor.cpu().numpy()
+                
+                # threshold binary features
+                if binary_features > 0:
+                    best_solution_thresholded = threshold_binary_values(input_array=best_solution_np, binary_values=binary_features)
+                else:
+                    best_solution_thresholded = best_solution_np
+                
+                # make results dictionary
+                result_dict = {name: value for name, value in zip(feature_names, best_solution_thresholded)}
+                result_dict[target_name] = best_fitness.item()
+                
+                # Save each result incrementally
+                _save_result(result_dict, save_format, csv_path, db_manager, db_table_name)
+            
+        # Process logger
+        if pandas_logger is not None:
+            _handle_pandas_log(pandas_logger, save_path=save_path)      
+        
+        _LOGGER.info(f"✅ Optimal solution space complete. Results saved to '{save_path}'")
+        return None
+
+
+def _handle_pandas_log(logger: PandasLogger, save_path: Path):
+    log_dataframe = logger.to_dataframe()
+    save_dataframe(df=log_dataframe, save_dir=save_path / "EvolutionLog", filename="evolution")
+
+
+def info():
+    _script_info(__all__)

{dragon_ml_toolbox-6.0.1 → dragon_ml_toolbox-6.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dragon-ml-toolbox"
-version = "6.0.1"
+version = "6.1.1"
 description = "A collection of tools for data science and machine learning projects."
 authors = [
     { name = "Karl Loza", email = "luigiloza@gmail.com" }

dragon_ml_toolbox-6.0.1/ml_tools/ML_optimization.py

@@ -1,226 +0,0 @@
-import torch
-import numpy    #handling torch to numpy
-import evotorch
-from evotorch.algorithms import CMAES, SteadyStateGA
-from evotorch.logging import StdOutLogger
-from typing import Literal, Union, Tuple, List, Optional
-from pathlib import Path
-from tqdm.auto import trange
-from contextlib import nullcontext
-
-from .path_manager import make_fullpath, sanitize_filename
-from ._logger import _LOGGER
-from ._script_info import _script_info
-from .ML_inference import PyTorchInferenceHandler
-from .keys import PyTorchInferenceKeys
-from .SQL import DatabaseManager
-from .optimization_tools import _save_result
-from .utilities import threshold_binary_values
-
-
-__all__ = [
-    "create_pytorch_problem",
-    "run_optimization"
-]
-
-
-def create_pytorch_problem(
-    handler: PyTorchInferenceHandler,
-    bounds: Tuple[List[float], List[float]],
-    binary_features: int,
-    task: Literal["minimize", "maximize"],
-    algorithm: Literal["CMAES", "GA"] = "CMAES",
-    verbose: bool = False,
-    **searcher_kwargs
-) -> Tuple[evotorch.Problem, evotorch.Searcher]: # type: ignore
-    """
-    Creates and configures an EvoTorch Problem and Searcher for a PyTorch model.
-
-    Args:
-        handler (PyTorchInferenceHandler): An initialized inference handler
-            containing the model and weights.
-        bounds (tuple[list[float], list[float]]): A tuple containing the lower
-            and upper bounds for the solution features.
-        binary_features (int): Number of binary features located at the END of the feature vector. Will be automatically added to the bounds.
-        task (str): The optimization goal, either "minimize" or "maximize".
-        algorithm (str): The search algorithm to use, "CMAES" or "GA" (SteadyStateGA).
-        verbose (bool): Add an Evotorch logger for real-time console updates.
-        **searcher_kwargs: Additional keyword arguments to pass to the
-            selected search algorithm's constructor (e.g., stdev_init=0.5 for CMAES).
-
-    Returns:
-        Tuple:
-        A tuple containing the configured evotorch.Problem and evotorch.Searcher.
-    """
-    lower_bounds, upper_bounds = bounds
-    
-    # add binary bounds
-    if binary_features > 0:
-        lower_bounds.extend([0.45] * binary_features)
-        upper_bounds.extend([0.55] * binary_features)
-    
-    solution_length = len(lower_bounds)
-    device = handler.device
-
-    # Define the fitness function that EvoTorch will call.
-    @evotorch.decorators.to_tensor # type: ignore
-    @evotorch.decorators.on_aux_device(device)
-    def fitness_func(solution_tensor: torch.Tensor) -> torch.Tensor:
-        # Directly use the continuous-valued tensor from the optimizer for prediction
-        predictions = handler.predict_batch(solution_tensor)[PyTorchInferenceKeys.PREDICTIONS]
-        return predictions.flatten()
-
-    # Create the Problem instance.
-    problem = evotorch.Problem(
-        objective_sense=task,
-        objective_func=fitness_func,
-        solution_length=solution_length,
-        initial_bounds=(lower_bounds, upper_bounds),
-        device=device,
-    )
-
-    # Create the selected searcher instance.
-    if algorithm == "CMAES":
-        searcher = CMAES(problem, **searcher_kwargs)
-    elif algorithm == "GA":
-        searcher = SteadyStateGA(problem, **searcher_kwargs)
-    else:
-        raise ValueError(f"Unknown algorithm '{algorithm}'. Choose 'CMAES' or 'GA'.")
-
-    # Add a logger for real-time console updates.
-    # This gives the user immediate feedback on the optimization progress.
-    if verbose:
-        _ = StdOutLogger(searcher)
-
-    return problem, searcher
-
-
-def run_optimization(
-    problem: evotorch.Problem,
-    searcher: evotorch.Searcher, # type: ignore
-    num_generations: int,
-    target_name: str,
-    binary_features: int,
-    save_dir: Union[str, Path],
-    save_format: Literal['csv', 'sqlite', 'both'],
-    feature_names: Optional[List[str]],
-    repetitions: int = 1
-) -> Optional[dict]:
-    """
-    Runs the evolutionary optimization process, with support for multiple repetitions.
-
-    This function serves as the main engine for the optimization task. It takes a
-    configured Problem and a Searcher from EvoTorch and executes the optimization
-    for a specified number of generations.
-
-    It has two modes of operation:
-    1.  **Single Run (repetitions=1):** Executes the optimization once, saves the
-        single best result to a CSV file, and returns it as a dictionary.
-    2.  **Iterative Analysis (repetitions > 1):** Executes the optimization
-        multiple times. Results from each run are streamed incrementally to the
-        specified file formats (CSV and/or SQLite database). In this mode,
-        the function returns None.
-
-    Args:
-        problem (evotorch.Problem): The configured problem instance, which defines
-            the objective function, solution space, and optimization sense.
-        searcher (evotorch.Searcher): The configured searcher instance, which
-            contains the evolutionary algorithm (e.g., CMAES, GA).
-        num_generations (int): The total number of generations to run the
-            search algorithm for in each repetition.
-        target_name (str): Target name that will also be used for the CSV filename and SQL table.
-        binary_features (int): Number of binary features located at the END of the feature vector.
-        save_dir (str | Path): The directory where the result file(s) will be saved.
-        save_format (Literal['csv', 'sqlite', 'both'], optional): The format for
-            saving results during iterative analysis. Defaults to 'both'.
-        feature_names (List[str], optional): Names of the solution features for
-            labeling the output files. If None, generic names like 'feature_0',
-            'feature_1', etc., will be created. Defaults to None.
-        repetitions (int, optional): The number of independent times to run the
-            entire optimization process. Defaults to 1.
-
-    Returns:
-        Optional[dict]: A dictionary containing the best feature values and the
-        fitness score if `repetitions` is 1. Returns `None` if `repetitions`
-        is greater than 1, as results are streamed to files instead.
-    """
-    # preprocess paths
-    save_path = make_fullpath(save_dir, make=True, enforce="directory")
-    
-    sanitized_target_name = sanitize_filename(target_name)
-    if not sanitized_target_name.endswith(".csv"):
-        sanitized_target_name = sanitized_target_name + ".csv"
-    
-    csv_path = save_path / sanitized_target_name
-    
-    db_path = save_path / "Optimization.db"
-    db_table_name = target_name
-    
-    # preprocess feature names
-    if feature_names is None:
-        feature_names = [f"feature_{i}" for i in range(problem.solution_length)] # type: ignore
-    
-    # --- SINGLE RUN LOGIC ---
-    if repetitions <= 1:
-        _LOGGER.info(f"🤖 Starting optimization with {searcher.__class__.__name__} for {num_generations} generations...")
-        for _ in trange(num_generations, desc="Optimizing"):
-            searcher.step()
-
-        best_solution_tensor, best_fitness = searcher.best
-        best_solution_np = best_solution_tensor.cpu().numpy()
-        
-        # threshold binary features
-        if binary_features > 0:
-            best_solution_thresholded = threshold_binary_values(input_array=best_solution_np, binary_values=binary_features)
-        else:
-            best_solution_thresholded = best_solution_np
-
-        result_dict = {name: value for name, value in zip(feature_names, best_solution_thresholded)}
-        result_dict[target_name] = best_fitness.item()
-        
-        _save_result(result_dict, 'csv', csv_path) # Single run defaults to CSV
-        _LOGGER.info(f"✅ Optimization complete. Best solution saved to '{csv_path.name}'")
-        return result_dict
-
-    # --- MULTIPLE REPETITIONS LOGIC ---
-    else:
-        _LOGGER.info(f"🏁 Starting optimal solution space analysis with {repetitions} repetitions...")
-
-        db_context = DatabaseManager(db_path) if save_format in ['sqlite', 'both'] else nullcontext()
-        
-        with db_context as db_manager:
-            if db_manager:
-                schema = {name: "REAL" for name in feature_names}
-                schema[target_name] = "REAL"
-                db_manager.create_table(db_table_name, schema)
-
-            for i in trange(repetitions, desc="Repetitions"):
-                _LOGGER.info(f"--- Starting Repetition {i+1}/{repetitions} ---")
-                
-                # CRITICAL: Re-initialize the searcher to ensure each run is independent
-                searcher.reset()
-
-                for _ in range(num_generations): # Inner loop does not need a progress bar
-                    searcher.step()
-
-                best_solution_tensor, best_fitness = searcher.best
-                best_solution_np = best_solution_tensor.cpu().numpy()
-                
-                # threshold binary features
-                if binary_features > 0:
-                    best_solution_thresholded = threshold_binary_values(input_array=best_solution_np, binary_values=binary_features)
-                else:
-                    best_solution_thresholded = best_solution_np
-                
-                result_dict = {name: value for name, value in zip(feature_names, best_solution_thresholded)}
-                result_dict[target_name] = best_fitness.item()
-                
-                # Save each result incrementally
-                _save_result(result_dict, save_format, csv_path, db_manager, db_table_name)
-        
-        _LOGGER.info(f"✅ Optimal solution space complete. Results saved to '{save_path}'")
-        return None
-
-
-def info():
-    _script_info(__all__)