quicklearnkit 0.0.2__tar.gz → 0.2.1__tar.gz

{quicklearnkit-0.0.2 → quicklearnkit-0.2.1}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Masterhazi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Masterhazi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quicklearnkit-0.2.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: quicklearnkit
+Version: 0.2.1
+Summary: Learning-first machine learning utilities library for simplified imports, sampling, splitting, and probabilistic preprocessing.
+Author: Hazi Afrid
+License: MIT License
+        
+        Copyright (c) 2025 Masterhazi
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Requires-Dist: xgboost
+Dynamic: license-file
+
+````markdown
+# QuickLearnKit
+
+QuickLearnKit is a lightweight, learning-first machine learning utilities library designed to simplify model imports and streamline common ML workflows. No more deep module navigation—import models and tools effortlessly and start building.
+
+It focuses on removing *mechanical friction* so students and practitioners can spend more time understanding concepts, not fighting syntax.
+
+---
+
+## Installation
+
+Install QuickLearnKit using pip:
+
+```bash
+pip install quicklearnkit
+````
+
+---
+
+## Quick Model Imports
+
+QuickLearnKit provides seamless access to essential machine learning models with minimal syntax. Simply import and initialize models without the usual clutter.
+
+### Example Usage
+
+```python
+from quicklearnkit import (
+    LinearRegressionmodel,
+    RandomForestRegressionmodel,
+    XGBoostRegressionmodel,
+    KNeighborsClassifiermodel,
+    GradientBoostingClassifiermodel
+)
+
+# Initialize models directly
+lr_model = LinearRegressionmodel()
+rf_model = RandomForestRegressionmodel()
+xgb_model = XGBoostRegressionmodel()
+
+# Initialize classifiers
+knn_classifier = KNeighborsClassifiermodel()
+gb_classifier = GradientBoostingClassifiermodel()
+```
+
+---
+
+## Supported Models
+
+QuickLearnKit offers easy access to commonly used supervised learning models:
+
+### Regression Models
+
+* Linear Regression (`LinearRegressionmodel()`)
+* K-Nearest Neighbors Regression (`KNNRegressionmodel()`)
+* Decision Tree Regression (`DecisionTreeRegressionmodel()`)
+* Random Forest Regression (`RandomForestRegressionmodel()`)
+* Gradient Boosting Regression (`GradientBoostingRegressionmodel()`)
+* AdaBoost Regression (`AdaBoostRegressionmodel()`)
+* XGBoost Regression (`XGBoostRegressionmodel()`)
+* ElasticNet Regression (`ElasticNetRegressionmodel()`)
+
+### Classification Models
+
+* Logistic Regression (`LogisticRegressionmodel()`)
+* K-Nearest Neighbors Classifier (`KNeighborsClassifiermodel()`)
+* Decision Tree Classifier (`DecisionTreeClassifiermodel()`)
+* Random Forest Classifier (`RandomForestClassifiermodel()`)
+* AdaBoost Classifier (`AdaBoostClassifiermodel()`)
+* Gradient Boosting Classifier (`GradientBoostingClassifiermodel()`)
+* XGBoost Classifier (`XGBClassifiermodel()`)
+* Support Vector Classifier (`SVClassifiermodel()`)
+
+---
+
+## Utilities & Workflow Tools
+
+Beyond models, QuickLearnKit provides practical tools to support the full machine learning workflow.
+
+---
+
+### 🔀 Random Sampling — `Sampler`
+
+Randomly sample from lists, NumPy arrays, or pandas DataFrames. Supports both **stateless (reproducible)** and **stateful (streaming / simulation)** modes.
+
+```python
+from quicklearnkit import Sampler
+import seaborn as sns
+
+df = sns.load_dataset("titanic")
+
+sampler = Sampler(df, n=5, random_state=42)
+sampled_data = sampler.sample()
+
+print(sampled_data)
+```
+
+---
+
+### ✂️ Train–Test Splitting — `train_test_split`
+
+Split datasets into training and testing sets with support for:
+
+* Shuffling
+* Stratification
+* NumPy arrays and pandas DataFrames
+
+```python
+from quicklearnkit import train_test_split
+import numpy as np
+
+X = np.arange(20).reshape(10, 2)
+
+X_train, X_test = train_test_split(
+    X,
+    test_size=0.25,
+    shuffle=True,
+    random_state=42
+)
+
+print(X_train.shape, X_test.shape)
+```
+
+---
+
+### 🎲 Probabilistic Imputation — `ProbabilisticImputer`
+
+A group-aware, probabilistic categorical imputer that learns conditional distributions and samples missing values in a **reproducible** way by default.
+
+This is especially useful for:
+
+* Teaching how distributions work
+* Simulating realistic missing data handling
+* Data augmentation and robustness testing
+
+```python
+from quicklearnkit import ProbabilisticImputer
+import seaborn as sns
+
+df = sns.load_dataset("titanic")
+
+imputer = ProbabilisticImputer(
+    group_col="pclass",
+    target_col="deck",
+    random_state=42  # reproducible by default
+)
+
+df_imputed = imputer.fit_transform(df)
+
+print("Missing before:", df["deck"].isna().sum())
+print("Missing after:", df_imputed["deck"].isna().sum())
+```
+
+---
+
+## Randomized Data Generation
+
+Generate random arrays with specific characteristics:
+
+```python
+from quicklearnkit import create_random
+
+random_data = create_random(mean=0, std_dev=1, size=100)
+print(random_data)
+```
+
+---
+
+## Contribute
+
+Want to improve QuickLearnKit? Fork the repository, suggest enhancements, and help make machine learning more accessible and easier to teach.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+QuickLearnKit makes machine learning utilities effortless—so you can focus on **learning, experimenting, and building**, not writing complex import statements. 🚀
+
+````
+

quicklearnkit-0.2.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quicklearnkit"
+version = "0.2.1"
+description = "Learning-first machine learning utilities library for simplified imports, sampling, splitting, and probabilistic preprocessing."
+readme = "readme.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Hazi Afrid" }
+]
+requires-python = ">=3.8"
+dependencies = [
+    "numpy",
+    "pandas",
+    "scikit-learn",
+    "xgboost"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]

quicklearnkit-0.2.1/quicklearnkit/__init__.py

@@ -0,0 +1,2 @@
+from .quickimports import *
+from .randomizer import Sampler

{quicklearnkit-0.0.2 → quicklearnkit-0.2.1}/quicklearnkit/classifier.py

@@ -1,90 +1,90 @@
-from sklearn.linear_model import LogisticRegression as logisticregression
-from sklearn.neighbors import KNeighborsClassifier as knnclassifier
-from sklearn.tree import DecisionTreeClassifier as decisiontreeclassifier
-from sklearn.ensemble import RandomForestClassifier as randomforestclassifier
-from sklearn.ensemble import GradientBoostingClassifier as gradientboostingclassifier
-from sklearn.ensemble import AdaBoostClassifier as adaboostclassifier
-from xgboost import XGBClassifier as xgboostclassifier
-from sklearn.svm import SVC as supportvectorclassifer
-
-
-class LogisticRegressionmodel:
-    def __init__(self, **kwargs):
-        self.model = logisticregression(**kwargs)
-    
-    def fit(self, X,y):
-        self.model.fit(X,y)
-    
-    def predict(self,X):
-        self.model.predict(X)
-
-
-class KNeighborsClassifiermodel:
-    def __init__(self, **kwargs):
-        self.model = knnclassifier(**kwargs)
-
-    def fit(self, X,y):
-        self.model.fit(X,y)
-    
-    def predict(self,X):
-        self.model.predict(X)
-
-class DecisionTreeClassifiermodel:
-    def __init__(self, **kwargs):
-        self.model = decisiontreeclassifier(**kwargs)
-    
-    def fit(self,X,y):
-        self.model.fit(X,y)
-
-    def predict(self, X):
-        self.model.predict(X)
-
-class RandomForestClassifiermodel:
-    def __init__(self, **kwargs):
-        self.model = randomforestclassifier(**kwargs)
-    
-    def fit(self, X,y):
-        self.model.fit(X,y)
-    
-    def predict(self, X):
-        self.model.predict(X)
-
-class GradientBoostingClassifiermodel:
-    def __init__(self, **kwargs):
-        self.model = gradientboostingclassifier(**kwargs)
-    
-    def fit(self, X,y):
-        self.model.fit(X,y)
-    
-    def predict(self, X):
-        self.model.predict(X)
-
-class AdaBoostClassifiermodel:
-    def __init__(self, **kwargs):
-        self.model = adaboostclassifier(**kwargs)
-    
-    def fit(self, X,y):
-        self.model.fit(X,y)
-    
-    def predict(self, X):
-        self.model.predict(X)
-
-class SVClassifiermodel:
-    def __init__(self, **kwargs):
-        self.model = supportvectorclassifer(**kwargs)
-    
-    def fit(self, X,y):
-        self.model.fit(X,y)
-    
-    def predict(self, X):
-        self.model.predict(X)
-
-class XGBClassifiermodel:
-    def __init__(self, **kwargs):
-        self.model = xgboostclassifier(**kwargs)
-
-    def fit (self, X,y):
-        self.model.fit(X,y)
-
-    def predict(self, X):
+from sklearn.linear_model import LogisticRegression as logisticregression
+from sklearn.neighbors import KNeighborsClassifier as knnclassifier
+from sklearn.tree import DecisionTreeClassifier as decisiontreeclassifier
+from sklearn.ensemble import RandomForestClassifier as randomforestclassifier
+from sklearn.ensemble import GradientBoostingClassifier as gradientboostingclassifier
+from sklearn.ensemble import AdaBoostClassifier as adaboostclassifier
+from xgboost import XGBClassifier as xgboostclassifier
+from sklearn.svm import SVC as supportvectorclassifer
+
+
+class LogisticRegressionmodel:
+    def __init__(self, **kwargs):
+        self.model = logisticregression(**kwargs)
+    
+    def fit(self, X,y):
+        self.model.fit(X,y)
+    
+    def predict(self,X):
+        self.model.predict(X)
+
+
+class KNeighborsClassifiermodel:
+    def __init__(self, **kwargs):
+        self.model = knnclassifier(**kwargs)
+
+    def fit(self, X,y):
+        self.model.fit(X,y)
+    
+    def predict(self,X):
+        self.model.predict(X)
+
+class DecisionTreeClassifiermodel:
+    def __init__(self, **kwargs):
+        self.model = decisiontreeclassifier(**kwargs)
+    
+    def fit(self,X,y):
+        self.model.fit(X,y)
+
+    def predict(self, X):
+        self.model.predict(X)
+
+class RandomForestClassifiermodel:
+    def __init__(self, **kwargs):
+        self.model = randomforestclassifier(**kwargs)
+    
+    def fit(self, X,y):
+        self.model.fit(X,y)
+    
+    def predict(self, X):
+        self.model.predict(X)
+
+class GradientBoostingClassifiermodel:
+    def __init__(self, **kwargs):
+        self.model = gradientboostingclassifier(**kwargs)
+    
+    def fit(self, X,y):
+        self.model.fit(X,y)
+    
+    def predict(self, X):
+        self.model.predict(X)
+
+class AdaBoostClassifiermodel:
+    def __init__(self, **kwargs):
+        self.model = adaboostclassifier(**kwargs)
+    
+    def fit(self, X,y):
+        self.model.fit(X,y)
+    
+    def predict(self, X):
+        self.model.predict(X)
+
+class SVClassifiermodel:
+    def __init__(self, **kwargs):
+        self.model = supportvectorclassifer(**kwargs)
+    
+    def fit(self, X,y):
+        self.model.fit(X,y)
+    
+    def predict(self, X):
+        self.model.predict(X)
+
+class XGBClassifiermodel:
+    def __init__(self, **kwargs):
+        self.model = xgboostclassifier(**kwargs)
+
+    def fit (self, X,y):
+        self.model.fit(X,y)
+
+    def predict(self, X):
         self.model.fit(X)

{quicklearnkit-0.0.2 → quicklearnkit-0.2.1}/quicklearnkit/quickimports.py

@@ -1,21 +1,22 @@
-#from .regression import LinearRegression, KNeighborsRegression, DecisionTreeRegression, RandomForestRegression, AdaBoostRegression, GradientBoostingRegression, XGBRegressor,SVR
-#from .classifier import LogisticRegression, KNeighborsClassifier, DecisionTreeClassifier, RandomForestClassifier, AdaBoostClassifier, GradientBoostingClassifier, XGBClassifier, SVC
-
-#__all__= [
-#    'LinearRegression', ' KNeighborsRegressor', 'DecisionTreeRegressor', 'RandomForestRegressor', 'AdaBoostRegressor', 'GradientBoostingRegressor', 'XGBRegressor', 'SVR',
-#    'LogisticRegression', 'KNeighborsClassifier', 'DecisionTreeClassifier', 'RandomForestClassifier', 'AdaBoostClassifier', 'GradientBoostingClassifier', 'XGBClassifier', 'SVC'
-#]
-
-from .regressor import LinearRegressionmodel, KNNRegressionmodel, DecisionTreeRegressionmodel, RandomForestRegressionmodel, GradientBoostingRegressionmodel, AdaBoostRegressionmodel, XGBoostRegressionmodel, ElasticNetRegressionmodel
-from .classifier import LogisticRegressionmodel, KNeighborsClassifiermodel, DecisionTreeClassifiermodel, RandomForestClassifiermodel, AdaBoostClassifiermodel, GradientBoostingClassifiermodel, XGBClassifiermodel, SVClassifiermodel
-from .utils import create_random
-
-__all__=[
-    'LinearRegressionmodel','LogisticRegressionmodel', 'KNNRegressionmodel','GradientBoostingRegressionmodel',
-    'AdaBoostRegressionmodel', 'XGBoostRegressionmodel', 'ElasticNetRegressionmodel',
-    'DecisionTreeRegressionmodel', 'RandomForestRegressionmodel',
-    'KNeighborsClassifiermodel', 'DecisionTreeClassifiermodel', 'RandomForestClassifiermodel','AdaBoostClassifiermodel', 
-    'GradientBoostingClassifiermodel', 'XGBClassifiermodel', 'SVClassifiermodel',
-    'create_random'
-]
-
+#from .regression import LinearRegression, KNeighborsRegression, DecisionTreeRegression, RandomForestRegression, AdaBoostRegression, GradientBoostingRegression, XGBRegressor,SVR
+#from .classifier import LogisticRegression, KNeighborsClassifier, DecisionTreeClassifier, RandomForestClassifier, AdaBoostClassifier, GradientBoostingClassifier, XGBClassifier, SVC
+
+#__all__= [
+#    'LinearRegression', ' KNeighborsRegressor', 'DecisionTreeRegressor', 'RandomForestRegressor', 'AdaBoostRegressor', 'GradientBoostingRegressor', 'XGBRegressor', 'SVR',
+#    'LogisticRegression', 'KNeighborsClassifier', 'DecisionTreeClassifier', 'RandomForestClassifier', 'AdaBoostClassifier', 'GradientBoostingClassifier', 'XGBClassifier', 'SVC'
+#]
+
+from .regressor import LinearRegressionmodel, KNNRegressionmodel, DecisionTreeRegressionmodel, RandomForestRegressionmodel, GradientBoostingRegressionmodel, AdaBoostRegressionmodel, XGBoostRegressionmodel, ElasticNetRegressionmodel
+from .classifier import LogisticRegressionmodel, KNeighborsClassifiermodel, DecisionTreeClassifiermodel, RandomForestClassifiermodel, AdaBoostClassifiermodel, GradientBoostingClassifiermodel, XGBClassifiermodel, SVClassifiermodel
+from .utils import create_random, ProbabilisticImputer
+from .randomizer import Sampler
+from .split import train_test_split
+__all__=[
+    'LinearRegressionmodel','LogisticRegressionmodel', 'KNNRegressionmodel','GradientBoostingRegressionmodel',
+    'AdaBoostRegressionmodel', 'XGBoostRegressionmodel', 'ElasticNetRegressionmodel',
+    'DecisionTreeRegressionmodel', 'RandomForestRegressionmodel',
+    'KNeighborsClassifiermodel', 'DecisionTreeClassifiermodel', 'RandomForestClassifiermodel','AdaBoostClassifiermodel', 
+    'GradientBoostingClassifiermodel', 'XGBClassifiermodel', 'SVClassifiermodel',
+    'create_random', 'Sampler', 'train_test_split', "ProbabilisticImputer",
+]
+

quicklearnkit-0.2.1/quicklearnkit/randomizer.py

@@ -0,0 +1,175 @@
+import random
+import numpy as np
+import pandas as pd
+from typing import Union, Optional
+
+
+DataType = Union[list, tuple, np.ndarray, pd.DataFrame]
+
+
+class Sampler:
+    """
+    Unified random sampler supporting:
+
+    - Stateful and stateless sampling
+    - Sampling with or without replacement
+    - list, numpy.ndarray, pandas.DataFrame
+    - Row or column sampling for DataFrames
+
+    Parameters
+    ----------
+    data : list, tuple, numpy.ndarray, or pandas.DataFrame
+        Data to sample from.
+    replace : bool, default=False
+        Whether sampling is done with replacement.
+    stateful : bool, default=False
+        If True, sampled elements are removed from future draws.
+    seed : int, optional
+        Random seed for reproducibility.
+    """
+
+    def __init__(
+        self,
+        data: DataType,
+        replace: bool = False,
+        stateful: bool = False,
+        seed: Optional[int] = None
+    ):
+        self.replace = replace
+        self.stateful = stateful
+
+        if seed is not None:
+            random.seed(seed)
+            np.random.seed(seed)
+
+        # Detect data type
+        if isinstance(data, (list, tuple)):
+            self._type = "list"
+            self.data = list(data)
+
+        elif isinstance(data, np.ndarray):
+            self._type = "array"
+            self.data = data
+
+        elif isinstance(data, pd.DataFrame):
+            self._type = "df"
+            self.data = data
+
+        else:
+            raise TypeError(
+                "Unsupported data type. Use list, numpy array, or pandas DataFrame."
+            )
+
+        if self.stateful:
+            self._reset_pool()
+
+    # ---------------- INTERNAL ---------------- #
+
+    def _reset_pool(self):
+        """Initialize or reset internal sampling pool."""
+        if self._type == "list":
+            self.pool = self.data.copy()
+            random.shuffle(self.pool)
+
+        elif self._type == "array":
+            self.pool = self.data.copy()
+            np.random.shuffle(self.pool)
+
+        elif self._type == "df":
+            self.pool = self.data.copy()
+
+    # ---------------- PUBLIC API ---------------- #
+
+    def sample(self, n: int = 1, axis: int = 0):
+        """
+        Sample data.
+
+        Parameters
+        ----------
+        n : int, default=1
+            Number of items to sample.
+        axis : int, default=0
+            Axis to sample from when data is a DataFrame.
+            0 = rows, 1 = columns.
+
+        Returns
+        -------
+        Sampled data (same type as input).
+        """
+
+        if n <= 0:
+            raise ValueError("n must be a positive integer")
+
+        source = self.pool if self.stateful else self.data
+
+        # -------- LIST --------
+        if self._type == "list":
+            if self.stateful:
+                if n > len(self.pool):
+                    raise StopIteration("No items left to sample")
+                out = self.pool[:n]
+                self.pool = self.pool[n:]
+                return out
+
+            if not self.replace and n > len(source):
+                raise ValueError("Cannot sample more elements than population")
+
+            return (
+                random.sample(source, n)
+                if not self.replace
+                else random.choices(source, k=n)
+            )
+
+        # -------- NUMPY ARRAY --------
+        if self._type == "array":
+            if self.stateful:
+                if n > len(self.pool):
+                    raise StopIteration("No items left to sample")
+                out = self.pool[:n]
+                self.pool = self.pool[n:]
+                return out
+
+            return np.random.choice(source, size=n, replace=self.replace)
+
+        # -------- DATAFRAME --------
+        if self._type == "df":
+            if axis not in (0, 1):
+                raise ValueError("axis must be 0 (rows) or 1 (columns)")
+
+            # Row sampling
+            if axis == 0:
+                if self.stateful:
+                    if n > len(self.pool):
+                        raise StopIteration("No rows left to sample")
+                    out = self.pool.iloc[:n]
+                    self.pool = self.pool.iloc[n:]
+                    return out
+
+                return self.data.sample(n=n, replace=self.replace)
+
+            # Column sampling
+            cols = list(source.columns)
+
+            if n > len(cols):
+                raise StopIteration("No columns left to sample")
+
+            chosen = (
+                cols[:n]
+                if self.stateful
+                else random.sample(cols, n)
+                if not self.replace
+                else random.choices(cols, k=n)
+            )
+
+            if self.stateful:
+                self.pool = self.pool.drop(columns=chosen)
+
+            return self.data[chosen]
+
+    def reset(self):
+        """
+        Reset internal state (only for stateful sampler).
+        """
+        if not self.stateful:
+            raise RuntimeError("reset() is only available when stateful=True")
+        self._reset_pool()