mlsampler 0.3.0__tar.gz → 0.3.3__tar.gz

mlsampler-0.3.3/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: mlsampler
+Version: 0.3.3
+Summary: Flexible constrained random sampler for reverse analysis in machine learning
+Author: Jugai O
+License: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: joblib
+Dynamic: license-file
+
+# RandomSampler
+
+mlsampler is a flexible, constraint-aware sampling library designed for reverse analysis and data exploration in machine learning workflows.
+
+It allows you to generate synthetic samples that satisfy complex constraints across continuous, integer, binary, and categorical features.
+
+## Features
+- Constraint-based sampling
+- Support for continuous / categorical features
+- Parallel generation
+
+## Documentation
+https://jugais.github.io/randsampler/
+
+## Installation
+
+```bash
+pip install mlsampler
+```
+
+## Use Cases
+- Reverse analysis (finding inputs that satisfy target conditions)
+- Candidate generation for optimization

mlsampler-0.3.3/README.md

@@ -0,0 +1,23 @@
+# RandomSampler
+
+mlsampler is a flexible, constraint-aware sampling library designed for reverse analysis and data exploration in machine learning workflows.
+
+It allows you to generate synthetic samples that satisfy complex constraints across continuous, integer, binary, and categorical features.
+
+## Features
+- Constraint-based sampling
+- Support for continuous / categorical features
+- Parallel generation
+
+## Documentation
+https://jugais.github.io/randsampler/
+
+## Installation
+
+```bash
+pip install mlsampler
+```
+
+## Use Cases
+- Reverse analysis (finding inputs that satisfy target conditions)
+- Candidate generation for optimization

{mlsampler-0.3.0 → mlsampler-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mlsampler"
-version = "0.3.0"
+version = "0.3.3"
 description = "Flexible constrained random sampler for reverse analysis in machine learning"
 authors = [
   { name="Jugai O" }

mlsampler-0.3.3/src/mlsampler/__init__.py

@@ -0,0 +1,12 @@
+from .base import BaseSampler, SamplerConfig, FeatureMeta
+from .engine.random import RandomSampler
+from .engine.hypergrid import HyperGridSampler
+
+__all__ = [
+    "BaseSampler",
+    "SamplerConfig",
+    "FeatureMeta",
+    "RandomSampler",
+    "HyperGridSampler",
+]
+

mlsampler-0.3.3/src/mlsampler/base.py

@@ -0,0 +1,160 @@
+import numpy as np
+from dataclasses import dataclass
+from typing import Optional
+from abc import ABC, abstractmethod
+from .constraints import Constraints
+
+@dataclass(frozen=True)
+class FeatureMeta:
+    index: Optional[int] = None
+    low: Optional[float] = None
+    high: Optional[float] = None
+    dtype: str = "float"  # "float", "int", "binary", "categorical"
+    categories:Optional[list] = None
+
+@dataclass(frozen=True)
+class DtypeMeta:
+    float: str = "float"
+    integer: str = "int"
+    bin:str = "binary"
+    cat:str = "categorical"
+    const:str = "constant"
+
+@dataclass
+class SamplerConfig:
+    features: list[FeatureMeta]
+    batch_size: int = 1000
+    random_state: Optional[int] = None
+    n_jobs: int = -1
+    max_retries: int = 1000
+
+
+class BaseSampler(ABC):
+    """
+    Base class for constraint-based samplers.
+
+    This class provides common functionality for sampling based on feature metadata
+    and registered constraints. It is designed to be extended by specific sampler implementations.
+
+    Parameters
+    ----------
+    config : SamplerConfig
+        Configuration object containing feature metadata and sampling settings.
+    """
+    constraints: list[Constraints]
+
+    def __init__(self, config: SamplerConfig) -> None:
+        self.config = config
+        self._constraints = []
+        
+    @classmethod
+    def setup(
+            cls,
+            X: np.ndarray,
+            random_state: Optional[int] = None,
+            n_jobs: int = -1,
+            max_retries: int = 1000,
+        ):
+        """
+        Create a RandomSampler from provided training data.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            Input dataset used to infer feature ranges and types.
+        batch_size : int, default=1000
+            Number of samples generated per batch.
+        random_state : int or None, default=None
+            Seed for reproducible sampling.
+        n_jobs : int, default=-1
+            Number of parallel jobs.
+        max_retries : int, default=1000
+            Maximum retries for satisfying constraints.
+
+        Returns
+        -------
+        RandomSampler
+        """
+
+        features = []
+
+        for col in range(X.shape[1]):
+            col_data = X[:, col]
+            
+            if any(val is None or (
+                    isinstance(val, float) and np.isnan(val)
+                ) for val in col_data):
+                raise ValueError(f"Column {col} contains missing values (NaN/None).")
+
+            low, high = None, None
+            categories = None
+            dtype = None
+            unique_vals = np.unique(col_data)
+            try:
+                numeric_data = col_data.astype(float)
+                low = numeric_data.min()
+                high = numeric_data.max()
+
+                if np.isclose(low, high, equal_nan=True):
+                    dtype = DtypeMeta.const
+                elif set(unique_vals).issubset({0, 1}):
+                    dtype = DtypeMeta.bin
+                elif np.all(numeric_data.astype(int) == numeric_data):
+                    dtype = DtypeMeta.integer
+                else:
+                    dtype = DtypeMeta.float
+            except (ValueError, TypeError):
+                if len(unique_vals) == 1:
+                    dtype = DtypeMeta.const
+                else:    
+                    dtype = DtypeMeta.cat
+                categories=np.unique(col_data).tolist()
+
+            features.append(
+                FeatureMeta(
+                    index=col,
+                    low=low,
+                    high=high,
+                    dtype=dtype,
+                    categories=categories
+                )
+            )
+
+        config = SamplerConfig(
+            features = features,
+            random_state = random_state,
+            n_jobs = n_jobs,
+            max_retries = max_retries,
+        )
+
+        return cls(config)
+    
+    def set_constraints(self, constraint_fn: str, **kwargs) -> None:
+        pass
+
+    def apply_constraints(self, row: np.ndarray) -> Optional[np.ndarray]:
+        pass
+
+    @abstractmethod
+    def sample(self, n_samples: int) -> np.ndarray:
+        pass
+
+    @property
+    def n_features(self) -> int:
+        return len(self.config.features)
+    
+    def __len__(self):
+        return len(self.constraints)
+    
+    def __getitem__(self, key):
+        return self.constraints[key]
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} with {len(self)} constraints>"
+    
+    def __iter__(self):
+        return iter(self._constraints)
+    
+    def __bool__(self):
+        return bool(self.constraints)
+    

{mlsampler-0.3.0/src → mlsampler-0.3.3/src/mlsampler}/constraints/__init__.py

@@ -6,7 +6,7 @@ from .constraints import (
     RangeConstraint, 
     CategoriesConstraint,
     StepConstraint, 
-    StepSumConstraint,
+    SumStepConstraint,
     FunctionConstraint
 )
 from .base import Constraints
@@ -20,6 +20,6 @@ __all__ = [
     "RangeConstraint", 
     "CategoriesConstraint",
     "StepConstraint",
-    "StepSumConstraint",
+    "SumStepConstraint",
     "FunctionConstraint"
 ]

{mlsampler-0.3.0/src → mlsampler-0.3.3/src/mlsampler}/constraints/constraints.py

@@ -4,7 +4,7 @@ from .base import Constraints, SelectConstraint
 from .. import validate as v
 from ..types import Numeric, ArrayLike, Bool, ConstraintFn
 from typing import Optional, Callable
-from ..errors import ConstraintViolationError, ConstraintError
+from ..errors import ConstraintViolationError, ConstraintError, ConstraintTypeError
 
 class MultihotConstraint(SelectConstraint):
     def __init__(
@@ -29,7 +29,7 @@ class MultihotConstraint(SelectConstraint):
         ) -> np.ndarray:
         row[selected] = 1
         return row
-    
+
 class RandomSelectConstraint(SelectConstraint):
     def __init__(
             self, 
@@ -53,7 +53,8 @@ class RandomSelectConstraint(SelectConstraint):
 class SumConstraint(SelectConstraint):
     def __init__(self, 
             cols: list[int], 
-            sum_value: Numeric = 1, 
+            sum_value: Numeric = 1,
+            method: str = 'dirichlet',
             alpha: Optional[np.ndarray] = None,
             rng: Optional[np.random.Generator] = None,
             **kwargs
@@ -62,6 +63,7 @@ class SumConstraint(SelectConstraint):
 
         super().__init__(cols, **kwargs)
         self.sum_value = sum_value
+        self.method = method
         self.alpha = alpha
         self.rng = self._rng(rng)
 
@@ -80,14 +82,20 @@ class SumConstraint(SelectConstraint):
         Returns:
             np.ndarray: The modified row
         """
-        if self.alpha is None:
-            alpha = np.ones(len(selected))
-        else:
-            alpha = self.alpha
+        
+        if self.method == 'dirichlet':
+            if self.alpha is None:
+                alpha = np.ones(len(selected))
+            else:
+                alpha = self.alpha
 
-        weights = self.rng.dirichlet(alpha)
+            weights = self.rng.dirichlet(alpha)
+            row[selected] = weights * self.sum_value
+        elif self.method == 'simple':
+            row[selected] = row / np.sum(row) * self.sum_value
+        else:
+            raise ConstraintTypeError(f'Method: {self.method} not implemented')
 
-        row[selected] = weights * self.sum_value
         return row
 
 class SumIntConstraint(SumConstraint):
@@ -103,7 +111,13 @@ class SumIntConstraint(SumConstraint):
             return row
 
         cuts = np.sort(self.rng.choice((self.sum_value + k - 1), k - 1, replace=False))
-        parts = np.diff(np.concatenate(([-1], cuts, [self.sum_value + k - 1]))) - 1
+        parts = np.diff(
+                    np.concatenate((
+                        np.array([-1], dtype=cuts.dtype),
+                        cuts,
+                        np.array([self.sum_value + k - 1], dtype=cuts.dtype)
+                    ))
+                ) - 1
 
         row[selected] = parts
         return row
@@ -134,11 +148,11 @@ class CategoriesConstraint(Constraints):
         elif self.strength == "soft":
             mask = mask
         else:
-            raise ConstraintError(f"{self.strength} was not supported")
+            raise ConstraintError(f"{self.strength} was not supported.")
         
         valid_patterns = self.values[mask]
         if len(valid_patterns) == 0:
-            raise ConstraintViolationError("No patterns found in categories")
+            raise ConstraintViolationError("No patterns found in categories.")
 
         idx = rng.integers(len(valid_patterns))
         selected_pattern = valid_patterns[idx]
@@ -159,7 +173,7 @@ class RangeConstraint(Constraints):
         return row
 
 class StepConstraint(Constraints):
-    def __init__(self, col:int, low: float, high: float, step: float, **kwargs):
+    def __init__(self, col:int, step: float, low: float, high: float,  **kwargs):
         super().__init__(cols=[col], **kwargs)
         self.values = np.arange(low, high + step, step)
         self.col = col
@@ -179,7 +193,7 @@ class StepConstraint(Constraints):
         row[self.col] = rng.choice(self.values)
         return row
 
-class StepSumConstraint(StepConstraint):
+class SumStepConstraint(StepConstraint):
     def __init__(
             self, 
             cols: list[int], 
@@ -210,10 +224,7 @@ class StepSumConstraint(StepConstraint):
     def _constrain(self, row: np.ndarray, rng: Optional[np.random.Generator] = None) -> np.ndarray:
         rng = self._rng(rng)
         
-        # 1. Initialize all target columns with their respective minimum (low) values
         current_values = self.lows.copy().astype(float)
-        
-        # 2. Calculate the difference to reach the target sum_value
         current_sum = np.sum(current_values)
         residual = self.sum_value - current_sum
         
@@ -224,7 +235,7 @@ class StepSumConstraint(StepConstraint):
         if not np.isclose(residual % self.step, 0) and not np.isclose(residual % self.step, self.step):
             raise ConstraintViolationError(f"Residual ({residual}) is not a multiple of step ({self.step}).")
 
-        # 3. Randomly distribute the residual in 'step' increments
+        # Randomly distribute the residual in 'step' increments
         num_steps = int(round(residual / self.step))
         
         for _ in range(num_steps):
@@ -237,18 +248,16 @@ class StepSumConstraint(StepConstraint):
             if not eligible_indices:
                 raise ConstraintViolationError("Target sum_value is unreachable within defined highs.")
             
-            # Pick a random column and increment it
             target_idx = rng.choice(eligible_indices)
             current_values[target_idx] += self.step
             
-        # 4. Final assignment to the row
         row[self.cols] = current_values
         return row
 
 
 class FunctionConstraint(Constraints):
-    def __init__(self, fn: ConstraintFn):
-        super().__init__(cols=[])
+    def __init__(self, fn: ConstraintFn, cols:list[int]):
+        super().__init__(cols=cols)
         self.fn = fn
     
     def _constrain(
@@ -256,15 +265,13 @@ class FunctionConstraint(Constraints):
             row: np.ndarray, 
             rng: Optional[np.random.Generator] = None
         ) -> Optional[np.ndarray]:
+        
         result = self.fn(row)
 
         if isinstance(result, Bool):
-            if not result:
-                return None
-            else:
-                return row
+            return row if result else None
         elif isinstance(result, np.ndarray):
-            return result
+            row[self.cols] = result
+            return row
         else:
-            from ..errors import ConstraintTypeError
-            raise ConstraintTypeError("Constraint function must return either a boolean or a numpy array")
+            raise ConstraintTypeError("Constraint function must return either a boolean or a numpy array")

{mlsampler-0.3.0/src → mlsampler-0.3.3/src/mlsampler}/engine/__init__.py

@@ -1,10 +1,13 @@
 from .random import RandomSampler
+from .hypergrid import HyperGridSampler
 from ..base import BaseSampler
 
 __annotations__ = {
     "RandomSampler": BaseSampler,
+    "HyperGridSampler": BaseSampler
 }
 
 __all__ = [
     "RandomSampler",
+    "HyperGridSampler"
 ]

mlsampler-0.3.3/src/mlsampler/engine/hypergrid.py

@@ -0,0 +1,136 @@
+import numpy as np
+from typing import Optional
+from scipy.stats import qmc
+from ..base import BaseSampler, DtypeMeta as dm
+from ..errors import ConstraintViolationError
+from ..terminals import spinning
+
+class HyperGridSampler(BaseSampler):
+    """
+    Hybrid grid and LHS-based constraint sampler.
+
+    This sampler generates samples based on feature metadata inferred
+    from training data. Continuous features are sampled using Latin
+    Hypercube Sampling (LHS), while discrete features (e.g., integer,
+    binary, categorical) are sampled using grid random selection
+    over their respective value spaces.
+
+    Parameters
+    ----------
+    config : SamplerConfig
+        Configuration object containing feature metadata and sampling settings.
+
+    Notes
+    -----
+    Sampling strategy depends on feature data types:
+
+    - Float features:
+        Sampled using Latin Hypercube Sampling (LHS), then scaled to
+        their respective [low, high] ranges.
+
+    - Integer features:
+        Sampled uniformly from the inclusive range [low, high].
+
+    - Binary features:
+        Sampled uniformly from {0, 1}.
+
+    - Categorical features:
+        Sampled uniformly from the provided category list.
+
+    - Constant features:
+        Always return the same fixed value.
+    """
+    
+    def __init__(self, config):
+        super().__init__(config)
+        self.rng = np.random.default_rng(config.random_state)
+
+    def _lhs(self, n_samples: int, float_features: list):
+        """LHS sampling for float columns"""
+        if not float_features:
+            return np.empty((n_samples, 0))
+
+        dim = len(float_features)
+        sampler = qmc.LatinHypercube(d=dim, seed=self.config.random_state)
+        sample = sampler.random(n=n_samples)
+
+        lows = np.array([f.low for f in float_features])
+        highs = np.array([f.high for f in float_features])
+
+        scaled = qmc.scale(sample, lows, highs)
+        return scaled
+
+    def _discrete(self, n_samples: int, features: list):
+        """Grid random sampling for discrete columns"""
+        cols = []
+
+        for f in features:
+            if f.dtype == dm.bin:
+                vals = np.array([0, 1])
+            elif f.dtype == dm.integer:
+                vals = np.arange(int(f.low), int(f.high) + 1)
+            elif f.dtype == dm.cat:
+                vals = np.array(f.categories)
+            elif f.dtype == dm.const:
+                vals = np.array([f.low])
+            else:
+                raise ConstraintViolationError(f"Unsupported dtype: {f.dtype}")
+
+            sampled = self.rng.choice(vals, size=n_samples)
+            cols.append(sampled)
+
+        return np.column_stack(cols) if cols else np.empty((n_samples, 0))
+
+    def _sample(self, n_samples: int) -> np.ndarray:
+        """
+        Generate samples based on feature data types.
+
+        Continuous features are sampled using Latin Hypercube Sampling (LHS),
+        while discrete features (e.g., "int", "binary", "categorical", "constant") are
+        sampled using uniform random selection over their respective value spaces.
+
+        Parameters
+        ----------
+        n_samples : int
+            Total number of samples to generate.
+
+        Returns
+        -------
+        np.ndarray
+            Array of shape (n_samples, n_features) containing the generated samples.
+            The column order matches the input feature configuration.
+
+        Notes
+        -----
+        - Float features are scaled to their respective [low, high] ranges.
+        - Integer features are sampled from the inclusive range [low, high].
+        - Categorical features are sampled from the provided category list.
+        - Constant features return the same value for all samples.
+        """
+
+        float_feats = [f for f in self.config.features if f.dtype == dm.float]
+        discrete_feats = [f for f in self.config.features if f.dtype != dm.float]
+
+        float_part = self._lhs(n_samples, float_feats)
+        discrete_part = self._discrete(n_samples, discrete_feats)
+
+        result = np.zeros((n_samples, self.n_features), dtype=object)
+
+        float_idx = 0
+        disc_idx = 0
+
+        for i, f in enumerate(self.config.features):
+            if f.dtype == dm.float:
+                result[:, i] = float_part[:, float_idx]
+                float_idx += 1
+            else:
+                result[:, i] = discrete_part[:, disc_idx]
+                disc_idx += 1
+
+        return result
+
+    def sample(self, n_samples: int) -> np.ndarray:
+        with spinning():
+            samples = self._sample(n_samples)
+        return samples
+

{mlsampler-0.3.0/src → mlsampler-0.3.3/src/mlsampler}/engine/random.py

@@ -1,5 +1,5 @@
 import numpy as np
-
+from ..terminals import spinning
 from ..base import BaseSampler, SamplerConfig, DtypeMeta as dm
 from ..constraints import *
 from ..errors import (
@@ -8,7 +8,8 @@ from ..errors import (
     DuplicateColumnWarning
 )
 
-from typing import Optional, Callable
+from typing import Optional, Callable, Any
+from types import MappingProxyType
 from collections import defaultdict
 from joblib import Parallel, delayed
 
@@ -19,7 +20,7 @@ class RandomSampler(BaseSampler):
     Random constraint-based sampler.
 
     This sampler generates samples based on feature metadata
-    inferred from training data. Users can register constraints 
+    inferred from training data. Users can register constraints
     that are applied during sample generation.
 
     Parameters
@@ -31,8 +32,15 @@ class RandomSampler(BaseSampler):
     -----
     Two types of constraints are supported:
 
-    - Validation constraints: return a boolean.
-    - Constructive constraints: return a modified numpy array.
+    - Validation constraints:
+        Return a boolean. If False, the sample is rejected.
+
+    - Constructive constraints:
+        Return a modified numpy array.
+
+    Internally, constraints are unified to return either:
+    - np.ndarray (valid sample)
+    - None (invalid sample)
 
     Sampling is performed with retry logic up to `max_retries`.
     Parallel generation is supported via joblib.
@@ -44,14 +52,14 @@ class RandomSampler(BaseSampler):
         super().__init__(config)
         self.rng = np.random.default_rng(config.random_state)
         self.features = config.features
-        self.batch_size = config.batch_size
         self.n_jobs = config.n_jobs
         self.seed = config.random_state
         self.max_retries = config.max_retries
 
         self.dim = len(self.features)
-        self.constraints:list[Constraints] = []
-        self._registry = {
+        self._constraints:list[Constraints] = []
+        self._funcs: list[FunctionConstraint] = []
+        self._registry = MappingProxyType({
             "sum": SumConstraint,
             "sumint": SumIntConstraint,
             "multihot": MultihotConstraint,
@@ -59,17 +67,23 @@ class RandomSampler(BaseSampler):
             "range": RangeConstraint,
             "categories": CategoriesConstraint,
             "step": StepConstraint,
-            "stepsum": StepSumConstraint
-        }
+            "stepsum": SumStepConstraint,
+            
+        })
+
+    @property
+    def constraints(self):
+        """Get a registered constraint class"""
+        return tuple(self._constraints.copy())
 
     def reset_constraints(self):
         """Clear all registered constraints."""
-        self.constraints = []
-    
+        self._constraints = []
+
     def set_constraints(
             self,
-            constraint_fn: str | Callable = "sum",
-            replace=False,
+            constraint_fn: str | Callable[[np.ndarray], bool],
+            reset=False,
             **kwargs
         ):
         """
@@ -78,14 +92,16 @@ class RandomSampler(BaseSampler):
         ----------
         constraint_fn : str or callable, default="sum"
             Type of constraint. Supported types:
-            - callable: user-defined function that takes a row and returns a boolean. Required `fn` parameter.
+            - callable: user-defined function that takes a row and returns a boolean or a new row. `cols` must be provided in kwargs.
             - "sum": constraint based on the sum of selected columns. `sum_value` and `cols` must be provided in kwargs.
             - "sumint": similar to "sum" but ensures the sum is an integer. `sum_value` and `cols` must be provided in kwargs.
             - "multihot": constraint ensuring a specified number of columns in a set are active.`n_hot` and `cols` must be provided in kwargs.
             - "random": constraint selecting a random subset of columns. `cols`, `min_used`, and `max_used` can be provided in kwargs.
-            - "range": constraint setting values within a specified range. `cols`, `min_val`, and `max_val` must be provided in kwargs.
-            - "categories": constraint selecting from a list of categorical values. `col` and `values` must be provided in kwargs.
-        replace : bool, default=True
+            - "range": constraint setting values within a specified range. `cols`, `low`, and `high` must be provided in kwargs.
+            - "categories": constraint selecting from a list of categorical values. `cols` and `values` must be provided in kwargs.
+            - "step": constraint selecting values that are multiples of a step. `cols` and `step`, `low`, and `high` must be provided in kwargs.
+            - "stepsum": constraint ensuring the sum of values is a multiple of a step.
+        reset : bool, default=True
             If True, clears existing constraints before adding the new one.
         **kwargs
             Additional parameters specific to the constraint type.
@@ -97,38 +113,40 @@ class RandomSampler(BaseSampler):
         >>> # Custom function constraint
         >>> sampler.set_constraints(lambda x: (0 < x[0] < 1) and (0 < x[1] < 1))
         >>> # Sum constraint
-        >>> sampler.set_constraints("sum", sum_value=1, cols=[2, 3, 4], max_used=3)
+        >>> sampler.set_constraints("sum", sum_value=1, cols=[2, 3, 4], max_used=2)
         """
 
-        if replace:
-            self.constraints = []
-        
+        if reset:
+            self._constraints = []
+            self._funcs = []
+
         if callable(constraint_fn):
-            self.constraints.append(FunctionConstraint(fn=constraint_fn))
+            self._constraints.append(FunctionConstraint(fn=constraint_fn, **kwargs))
+            self._funcs.append(FunctionConstraint(fn=constraint_fn, **kwargs))
         elif isinstance(constraint_fn, str) and constraint_fn in self._registry:
-            self.constraints.append(self._registry[constraint_fn](**kwargs))
+            self._constraints.append(self._registry[constraint_fn](**kwargs))
         else:
             raise ConstraintTypeError(
-                    f"Unsupported constraint type: {constraint_fn}"
-                )
+                f"Unsupported constraint type: {constraint_fn}"
+            )
         
     def _base_sample(self, rng: np.random.Generator):
-        # x = np.empty(self.dim, dtype=float)
-        x = np.empty(len(self.config.features), dtype=object)
-
+        x = np.empty(self.dim, dtype=object)
         for i, f in enumerate(self.features):
-            if f.dtype == dm.bin:
+            if f.dtype == dm.const:
+                x[i] = f.low
+            elif f.dtype == dm.bin:
                 x[i] = rng.integers(0, 2)
-            elif f.dtype == dm.integer:
+            elif f.dtype == dm.integer and f.low is not None and f.high is not None:
                 x[i] = rng.integers(int(f.low), int(f.high) + 1)
-            elif f.dtype == dm.flt:
+            elif f.dtype == dm.float and f.low is not None and f.high is not None:
                 x[i] = rng.uniform(f.low, f.high)
             else:
                 x[i] = 0
 
         return x
     
-    def _fill_categorical_features(self, x, rng: np.random.Generator):
+    def _fill_categoricals(self, x, rng: np.random.Generator):
         for i, f in enumerate(self.features):
             if f.dtype == dm.cat:
                 if f.categories:
@@ -139,34 +157,71 @@ class RandomSampler(BaseSampler):
 
     def _apply_constraints(self, row: np.ndarray) -> Optional[np.ndarray]:
         """
-        Apply registered constraints to a generated row.
+        Apply all registered constraints sequentially.
 
         Parameters
         ----------
-        row : np.ndarray
-            The generated sample to validate/modify.
+        row : np.ndarray Input sample.
 
         Returns
         -------
         np.ndarray or None
-            The modified row if constructive constraints are applied, 
-            or the original row if only validation constraints are present.
-            Returns None if any validation constraint fails.
+            - np.ndarray: if all constraints succeed
+            - None: if any constraint fails
+
+        Notes
+        -----
+        Each constraint must return either:
+        - np.ndarray (possibly modified)
+        - None (indicating failure)
         """
         for constraint in self:
-            row = constraint(row)
-            if row is None:
+            if isinstance(constraint, FunctionConstraint):
+                continue
+
+            result = constraint(row)
+            if result is None:
                 return None  # Constraint violation
+            row = result
         return row
     
+    def _apply_funcs(self, row: np.ndarray) -> Optional[np.ndarray]:
+        for constraint in self._funcs:
+            result = constraint(row)
+            if result is None:
+                return None
+        return row
+
     def _detect_conflicts(self):
         col_usage = defaultdict(list)
+        constraints_by_col = defaultdict(list)
 
-        for i, c in enumerate(self.constraints):
+        for i, c in enumerate(self._constraints):
             for col in getattr(c, "cols", []):
                 col_usage[col].append(i)
+                constraints_by_col[col].append(c)
 
         for col, ids in col_usage.items():
+            constraints = constraints_by_col[col]
+            types = {getattr(c, "constraint_fn", None) for c in constraints}
+
+            meta = self.config.features[col]
+            
+            if meta.dtype == dm.cat:
+                invalid = types & {"sum", "sumint", "range"}
+
+                if invalid:
+                    raise ConstraintViolationError(
+                        f"{invalid} cannot be applied to categorical column: {col}"
+                    )
+
+            if meta.dtype == dm.const:
+                if len(ids) > 1:
+                    warnings.warn(
+                        f"Const column {col} has multiple constraints {ids} (types={types})",
+                        DuplicateColumnWarning
+                    )
+
             if len(ids) > 1:
                 warnings.warn(
                     f"Column {col} used in multiple constraints {ids}",
@@ -176,22 +231,35 @@ class RandomSampler(BaseSampler):
     def _generate_one(self, seed_offset: int = 0):
         base_seed = self.seed if self.seed is not None else None
         rng = np.random.default_rng(
-            None if base_seed is None else base_seed + seed_offset
+            (base_seed + seed_offset) if base_seed else None
         )
 
         for _ in range(self.max_retries):
             x = self._base_sample(rng)
-            x = self._fill_categorical_features(x, rng)
-            x = self._apply_constraints(x) 
+            x = self._fill_categoricals(x, rng)
+            x = self._apply_constraints(x)
+            if x is None:
+                continue
+
+            x = self._apply_funcs(x)
             if x is not None:
                 return x
-        
+
         raise ConstraintViolationError("Max retries exceeded.")
-    
-    def _generate_batch(self, batch_size):
-        return np.array([self._generate_one() for _ in range(batch_size)])
 
-    def sample(self, n_samples: int):
+    def _sample(self, n_samples: int) -> np.ndarray:
+        if self.n_jobs == 1:
+            samples = [
+                self._generate_one(i) for i in range(n_samples)
+            ]
+        else:
+            samples = Parallel(n_jobs=self.n_jobs)(
+                delayed(self._generate_one)(i)
+                for i in range(n_samples)
+            )
+        return np.array(samples)
+
+    def sample(self, n_samples: int) -> np.ndarray:
         """
         Generate samples satisfying all registered constraints.
 
@@ -206,31 +274,13 @@ class RandomSampler(BaseSampler):
             Array of shape (n_samples, n_features).
 
         """
-
+        
         self._detect_conflicts()
 
-        batches = []
-        remaining = n_samples
-
-        print("sampling...", flush=True)
-
-        while remaining > 0:
-            current_batch = min(self.batch_size, remaining)
-
-            if self.n_jobs == 1:
-                batch = self._generate_batch(current_batch)
-            else:
-                results = Parallel(n_jobs=self.n_jobs)(
-                    delayed(self._generate_one)()
-                    for _ in range(current_batch)
-                )
-                batch = np.array(results)
-
-            batches.append(batch)
-
-            remaining -= current_batch
+        with spinning():
+            samples = self._sample(n_samples)
+            
+        return samples
 
-            print(f"{n_samples - remaining}/{n_samples}", flush=True)
 
-        return np.vstack(batches)
     

mlsampler-0.3.3/src/mlsampler/errors.py

@@ -0,0 +1,23 @@
+class ConstraintError(ValueError):
+    """Custom exception for constraint violations"""
+    pass
+
+class ConstraintTypeError(ConstraintError):
+    """Raised when an unsupported constraint type is specified."""
+    pass
+
+class ConstraintViolationError(ConstraintError):
+    """Raised when a constraint is violated during data generation"""
+    pass
+
+class ConstraintValidationError(ConstraintError):
+    """Raised when a constraint definition is invalid."""
+    pass
+
+class ConstraintWarning(UserWarning):
+    """Base warning for constraint-related issues."""
+    pass
+
+class DuplicateColumnWarning(ConstraintWarning):
+    """Column is used in multiple constraints."""
+    pass

mlsampler-0.3.3/src/mlsampler/terminals.py

@@ -0,0 +1,27 @@
+import sys
+import time
+import threading
+from contextlib import contextmanager
+
+def spinner(stop_event):
+    symbols = ["|", "/", "-", "\\"]
+    i = 0
+    while not stop_event.is_set():
+        sys.stdout.write(f"\rsampling... {symbols[i % len(symbols)]}")
+        sys.stdout.flush()
+        time.sleep(0.1)
+        i += 1
+
+    sys.stdout.write("\rsampling completed    \n")
+    sys.stdout.flush()
+
+@contextmanager
+def spinning(msg="sampling..."):
+    stop_event = threading.Event()
+    t = threading.Thread(target=spinner, args=(stop_event,))
+    t.start()
+    try:
+        yield
+    finally:
+        stop_event.set()
+        t.join()

mlsampler-0.3.3/src/mlsampler/types.py

@@ -0,0 +1,7 @@
+import numpy as np
+from typing import TypeAlias, Union, Callable
+
+Numeric: TypeAlias = Union[int, float, np.integer, np.floating]
+ArrayLike: TypeAlias = Union[np.ndarray, list, tuple]
+Bool: TypeAlias = Union[bool, np.bool_]
+ConstraintFn: TypeAlias = Callable[[np.ndarray], Union[Bool, np.ndarray]]

mlsampler-0.3.3/src/mlsampler/validate.py

@@ -0,0 +1,48 @@
+import numpy as np
+from typing import Optional
+from .errors import *
+from .types import Numeric, ArrayLike
+import warnings
+
+def validate_cols(cols):
+    if not isinstance(cols, ArrayLike):
+        raise ConstraintValidationError("cols must be an array-like of column indices")
+    
+    if len(set(cols)) != len(cols):
+        raise ConstraintValidationError("Column indices must be unique")
+    
+    for c in cols:
+        if not isinstance(c, (int, np.integer)) or c < 0:
+            raise ConstraintValidationError("Column indices must be non-negative integers")
+        
+def validate_usage(min_used: int, max_used: Optional[int]):
+    if min_used < 0:
+        raise ConstraintValidationError("min_used must be non-negative")
+        
+    if max_used is None:
+        raise ConstraintValidationError("max_used must be specified")
+    
+    if max_used is not None and max_used < 0:
+        raise ConstraintValidationError("max_used must be non-negative")
+    
+    if min_used > max_used:
+        raise ConstraintValidationError("min_used must be <= max_used")
+    
+def validate_values(value: Numeric):
+    if not isinstance(value, Numeric):
+        raise ConstraintValidationError("Value must be a numeric")
+    
+    if value < 0:
+        warnings.warn("Value should be non-negative", ConstraintWarning)
+        
+def validate_range(low: Numeric, high: Numeric):
+    if not isinstance(low, Numeric):
+        raise ConstraintTypeError("low must be a numeric")
+    
+    if not isinstance(high, Numeric):
+        raise ConstraintTypeError("high must be a numeric")
+    
+    if low > high:
+        raise ConstraintValidationError("low must be <= high")
+    
+        

mlsampler-0.3.3/src/mlsampler.egg-info/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: mlsampler
+Version: 0.3.3
+Summary: Flexible constrained random sampler for reverse analysis in machine learning
+Author: Jugai O
+License: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: joblib
+Dynamic: license-file
+
+# RandomSampler
+
+mlsampler is a flexible, constraint-aware sampling library designed for reverse analysis and data exploration in machine learning workflows.
+
+It allows you to generate synthetic samples that satisfy complex constraints across continuous, integer, binary, and categorical features.
+
+## Features
+- Constraint-based sampling
+- Support for continuous / categorical features
+- Parallel generation
+
+## Documentation
+https://jugais.github.io/randsampler/
+
+## Installation
+
+```bash
+pip install mlsampler
+```
+
+## Use Cases
+- Reverse analysis (finding inputs that satisfy target conditions)
+- Candidate generation for optimization

mlsampler-0.3.3/src/mlsampler.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/mlsampler/__init__.py
+src/mlsampler/base.py
+src/mlsampler/errors.py
+src/mlsampler/terminals.py
+src/mlsampler/types.py
+src/mlsampler/validate.py
+src/mlsampler.egg-info/PKG-INFO
+src/mlsampler.egg-info/SOURCES.txt
+src/mlsampler.egg-info/dependency_links.txt
+src/mlsampler.egg-info/requires.txt
+src/mlsampler.egg-info/top_level.txt
+src/mlsampler/constraints/__init__.py
+src/mlsampler/constraints/base.py
+src/mlsampler/constraints/constraints.py
+src/mlsampler/engine/__init__.py
+src/mlsampler/engine/hypergrid.py
+src/mlsampler/engine/random.py

mlsampler-0.3.3/src/mlsampler.egg-info/top_level.txt

@@ -0,0 +1 @@
+mlsampler

mlsampler-0.3.0/PKG-INFO

@@ -1,21 +0,0 @@
-Metadata-Version: 2.4
-Name: mlsampler
-Version: 0.3.0
-Summary: Flexible constrained random sampler for reverse analysis in machine learning
-Author: Jugai O
-License: LICENSE
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy
-Requires-Dist: joblib
-Dynamic: license-file
-
-# RandomSampler
-
-Flexible constrained random sampler for reverse analysis in machine learning.
-
-## Installation
-
-```bash
-pip install mlsampler

mlsampler-0.3.0/README.md

@@ -1,8 +0,0 @@
-# RandomSampler
-
-Flexible constrained random sampler for reverse analysis in machine learning.
-
-## Installation
-
-```bash
-pip install mlsampler

mlsampler-0.3.0/src/mlsampler.egg-info/PKG-INFO

@@ -1,21 +0,0 @@
-Metadata-Version: 2.4
-Name: mlsampler
-Version: 0.3.0
-Summary: Flexible constrained random sampler for reverse analysis in machine learning
-Author: Jugai O
-License: LICENSE
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy
-Requires-Dist: joblib
-Dynamic: license-file
-
-# RandomSampler
-
-Flexible constrained random sampler for reverse analysis in machine learning.
-
-## Installation
-
-```bash
-pip install mlsampler

mlsampler-0.3.0/src/mlsampler.egg-info/SOURCES.txt

@@ -1,13 +0,0 @@
-LICENSE
-README.md
-pyproject.toml
-src/constraints/__init__.py
-src/constraints/base.py
-src/constraints/constraints.py
-src/engine/__init__.py
-src/engine/random.py
-src/mlsampler.egg-info/PKG-INFO
-src/mlsampler.egg-info/SOURCES.txt
-src/mlsampler.egg-info/dependency_links.txt
-src/mlsampler.egg-info/requires.txt
-src/mlsampler.egg-info/top_level.txt

mlsampler-0.3.0/src/mlsampler.egg-info/top_level.txt

@@ -1,2 +0,0 @@
-constraints
-engine