quicklearnkit 0.2.2__tar.gz → 0.4.0__tar.gz

quicklearnkit-0.4.0/PKG-INFO

@@ -0,0 +1,680 @@
+Metadata-Version: 2.4
+Name: quicklearnkit
+Version: 0.4.0
+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
+Requires-Dist: seaborn
+Requires-Dist: matplotlib
+Dynamic: license-file
+
+# QuickLearnKit
+
+QuickLearnKit is a **learning-first machine learning utilities library** designed to make common ML and data science workflows simple, readable, and beginner-friendly — without blocking advanced users from full customization.
+
+The philosophy is:
+
+> **Remove mechanical friction so students can focus on concepts, not syntax.**
+
+QuickLearnKit provides:
+
+* Easy model imports
+* Random sampling utilities
+* Train–test splitting
+* Probabilistic, group-aware imputation
+* Teaching-friendly plotting with optional value labels
+
+---
+
+## Installation
+
+```bash
+pip install quicklearnkit
+```
+
+---
+
+## Quick Start
+
+```python
+from quicklearnkit import (
+    Sampler,
+    train_test_split,
+    ProbabilisticImputer,
+    bar_plot
+)
+
+import seaborn as sns
+
+# Load example dataset
+df = sns.load_dataset("titanic")
+
+# Sample data
+sampler = Sampler(df, n=5, random_state=42)
+print(sampler.sample())
+
+# Split data
+train, test = train_test_split(df, test_size=0.25)
+
+# Impute missing values
+imputer = ProbabilisticImputer("pclass", "deck", random_state=42)
+df_imputed = imputer.fit_transform(df)
+
+# Plot
+bar_plot(df, x="class", y="fare", show_values="yes")
+```
+
+---
+
+# Model Imports
+
+QuickLearnKit allows you to import commonly used machine learning models without navigating deep module paths.
+
+### Example
+
+```python
+from quicklearnkit import (
+    LinearRegressionmodel,
+    RandomForestRegressionmodel,
+    XGBoostRegressionmodel,
+    KNeighborsClassifiermodel,
+    GradientBoostingClassifiermodel
+)
+
+lr_model = LinearRegressionmodel()
+rf_model = RandomForestRegressionmodel()
+xgb_model = XGBoostRegressionmodel()
+
+knn_classifier = KNeighborsClassifiermodel()
+gb_classifier = GradientBoostingClassifiermodel()
+```
+
+---
+
+## Supported Models
+
+### Regression Models
+
+* `LinearRegressionmodel()`
+* `KNNRegressionmodel()`
+* `DecisionTreeRegressionmodel()`
+* `RandomForestRegressionmodel()`
+* `GradientBoostingRegressionmodel()`
+* `AdaBoostRegressionmodel()`
+* `XGBoostRegressionmodel()`
+* `ElasticNetRegressionmodel()`
+
+### Classification Models
+
+* `LogisticRegressionmodel()`
+* `KNeighborsClassifiermodel()`
+* `DecisionTreeClassifiermodel()`
+* `RandomForestClassifiermodel()`
+* `AdaBoostClassifiermodel()`
+* `GradientBoostingClassifiermodel()`
+* `XGBClassifiermodel()`
+* `SVClassifiermodel()`
+
+---
+
+# Utilities
+
+## 1. Sampler
+
+The `Sampler` class allows you to randomly select elements from:
+
+* Python lists
+* NumPy arrays
+* pandas DataFrames
+
+It supports both **stateless** (reproducible) and **stateful** (streaming/simulation) modes.
+
+### Initialization
+
+```python
+Sampler(data, n=1, random_state=None, replace=False, axis=0, stateful=False)
+```
+
+### Parameters Explained
+
+| Parameter      | Type                                  | Description                                                                                      |
+| -------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `data`         | list, numpy.ndarray, pandas.DataFrame | The dataset to sample from                                                                       |
+| `n`            | int                                   | Number of samples to return                                                                      |
+| `random_state` | int or None                           | Seed for reproducibility. Same seed = same result                                                |
+| `replace`      | bool                                  | If `True`, sampling is done **with replacement** (duplicates allowed). If `False`, no duplicates |
+| `axis`         | int                                   | Only applies to DataFrames. `0` = sample rows, `1` = sample columns                              |
+| `stateful`     | bool                                  | If `True`, RNG state continues across calls. If `False`, sampling is reproducible on every call  |
+
+### Example
+
+```python
+from quicklearnkit import Sampler
+import seaborn as sns
+
+df = sns.load_dataset("tips")
+
+sampler = Sampler(df, n=3, random_state=42, replace=False)
+
+sample1 = sampler.sample()
+sample2 = sampler.sample()  # Same output if stateful=False
+```
+
+---
+
+## 2. Train–Test Split
+
+Split datasets into training and testing sets with support for:
+
+* Shuffling
+* Stratification
+* NumPy arrays
+* pandas DataFrames
+
+### Function
+
+```python
+train_test_split(data, test_size=0.25, shuffle=True, stratify=None, random_state=None)
+```
+
+### Parameters Explained
+
+| Parameter      | Type                           | Description                                                |
+| -------------- | ------------------------------ | ---------------------------------------------------------- |
+| `data`         | array-like or pandas.DataFrame | Dataset to split                                           |
+| `test_size`    | float                          | Proportion of data to use as test set (e.g., `0.25` = 25%) |
+| `shuffle`      | bool                           | If `True`, data is shuffled before splitting               |
+| `stratify`     | array-like or str              | Column or labels to preserve class distribution in splits  |
+| `random_state` | int or None                    | Seed for reproducibility                                   |
+
+### Example
+
+```python
+from quicklearnkit import train_test_split
+
+train, test = train_test_split(df, test_size=0.3, shuffle=True, random_state=42)
+```
+
+---
+
+## 3. ProbabilisticImputer
+
+A **group-aware, probabilistic categorical imputer**. It learns probability distributions from observed data and fills missing values by sampling from those distributions.
+
+This allows:
+
+* Realistic missing data handling
+* Teaching probability-based imputation
+* Reproducible preprocessing
+
+### Initialization
+
+```python
+ProbabilisticImputer(group_col, target_col, random_state=None, stateful=False)
+```
+
+### Parameters Explained
+
+| Parameter      | Type        | Description                                                                                            |
+| -------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
+| `group_col`    | str         | Column used to group data (e.g., class, category)                                                      |
+| `target_col`   | str         | Column where missing values will be imputed                                                            |
+| `random_state` | int or None | Seed for reproducibility                                                                               |
+| `stateful`     | bool        | If `True`, RNG state advances across calls (useful for simulation). If `False`, output is reproducible |
+
+### Methods
+
+| Method              | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `fit(df)`           | Learns probability distributions from known values |
+| `transform(df)`     | Imputes missing values using learned distributions |
+| `fit_transform(df)` | Fit and transform in one step                      |
+
+### Example
+
+```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
+)
+
+imputed_df = imputer.fit_transform(df)
+```
+
+---
+
+# Plotting (Teaching-Friendly Visualization)
+
+QuickLearnKit provides wrappers around **seaborn + matplotlib** that allow students to display values on plots using a simple switch:
+
+```python
+show_values="yes"
+```
+
+All plotting functions:
+
+* Return a **matplotlib Axes object**
+* Allow full customization (labels, limits, grids, styles)
+* Automatically display the plot by default
+
+---
+
+## Common Parameters (All Plot Functions)
+
+| Parameter     | Type             | Description                                                                      |
+| ------------- | ---------------- | -------------------------------------------------------------------------------- |
+| `data`        | pandas.DataFrame | Dataset used for plotting                                                        |
+| `x`           | str              | Column for x-axis                                                                |
+| `y`           | str              | Column for y-axis (if applicable)                                                |
+| `title`       | str or None      | Plot title                                                                       |
+| `show_values` | str              | "yes" or "no" — whether to display numeric values                                |
+| `fmt`         | str              | Format string for value labels (e.g. `{:.2f}`)                                   |
+| `show`        | bool             | If `True`, displays plot immediately. If `False`, returns Axes for customization |
+
+---
+
+## bar_plot
+
+```python
+bar_plot(data, x, y, title=None, show_values="no", fmt="{:.1f}", show=True)
+```
+
+### Example
+
+```python
+from quicklearnkit import bar_plot
+import seaborn as sns
+
+_df = sns.load_dataset("tips")
+
+ax = bar_plot(
+    _df,
+    x="day",
+    y="total_bill",
+    show_values="yes",
+    show=False
+)
+
+ax.set_xlabel("Day of Week")
+ax.set_ylabel("Average Bill")
+ax.set_ylim(0, 40)
+
+import matplotlib.pyplot as plt
+plt.show()
+```
+
+---
+
+## line_plot
+
+```python
+line_plot(data, x, y, title=None, show_values="no", fmt="{:.2f}", show=True)
+```
+
+---
+
+## scatter_plot
+
+```python
+scatter_plot(data, x, y, title=None, show_values="no", fmt="{:.2f}", show=True)
+```
+
+---
+
+## count_plot
+
+```python
+count_plot(data, x, title=None, show_values="no", show=True)
+```
+
+---
+
+## box_plot
+
+Displays **mean values** when `show_values="yes"`.
+
+```python
+box_plot(data, x=None, y=None, title=None, show_values="no", fmt="{:.2f}", show=True)
+```
+
+---
+
+## hist_plot
+
+Displays **bin counts** when `show_values="yes"`.
+
+```python
+hist_plot(data, x, bins=10, title=None, show_values="no", fmt="{:.0f}", show=True)
+```
+
+---
+
+# Random Data Generation
+
+Generate random numerical arrays for experiments and demonstrations.
+
+```python
+from quicklearnkit import create_random
+
+random_data = create_random(mean=0, std_dev=1, size=100)
+```
+
+---
+
+# Pipeline (Notebook → Script Bridge)
+
+QuickLearnKit now includes a **Pipeline system** that helps you move from interactive notebook experimentation to clean, structured Python scripts.
+
+The goal is to make transitioning from:
+
+> 🧪 Exploration in notebooks → 🧾 Reproducible `.py` pipelines
+
+simple, explicit, and disciplined.
+
+---
+
+## Creating a Pipeline
+
+```python
+from quicklearnkit import Pipeline
+
+pipe = Pipeline()
+```
+
+Each `Pipeline()` instance is isolated and independent.
+
+---
+
+## 1. Manual Commit
+
+Commit top-level functions explicitly:
+
+```python
+def preprocess(X):
+    return X
+
+def train(X):
+    return "model"
+
+pipe.commit(preprocess, outputs=["X_scaled"], stage="Preprocessing")
+pipe.commit(train, inputs=["X_scaled"], outputs=["model"], stage="Training")
+```
+
+### Parameters Explained
+
+| Parameter | Type        | Description                                      |
+| --------- | ----------- | ------------------------------------------------ |
+| `func`    | Callable    | Top-level function to include in the pipeline    |
+| `inputs`  | list of str | Expected input variable names (for validation)   |
+| `outputs` | list of str | Output variable names produced by the function   |
+| `stage`   | str         | Optional grouping label for script organization  |
+| `mode`    | str         | `"functions"` enables semi-automatic commit mode |
+
+---
+
+## 2. Semi-Automatic Commit
+
+Capture all user-defined top-level functions in the current notebook:
+
+```python
+pipe.commit(mode="functions")
+```
+
+Semi-auto mode:
+
+* Detects user-defined functions
+* Skips built-in functions
+* Skips private functions (`_helper`)
+* Skips nested functions
+* Avoids duplicates
+
+Metadata can later be updated:
+
+```python
+pipe.commit(train, inputs=["X_scaled"], outputs=["model"])
+```
+
+---
+
+## 3. Pipeline Summary
+
+Inspect committed functions and metadata:
+
+```python
+pipe.summary()
+```
+
+Example output:
+
+```
+[QuickLearn] 📦 Pipeline Summary
+
+1. preprocess
+   Stage: Preprocessing
+   Inputs: []
+   Outputs: ['X_scaled']
+
+2. train
+   Stage: Training
+   Inputs: ['X_scaled']
+   Outputs: ['model']
+```
+
+---
+
+## 4. Register Imports
+
+QuickLearnKit does **not** automatically capture notebook imports.
+Imports must be registered explicitly to be included in the compiled script.
+
+### Multiline string:
+
+```python
+pipe.add_import("""
+import pandas as pd
+import numpy as np
+from quicklearnkit import RandomForestClassifiermodel
+""")
+```
+
+### List format:
+
+```python
+pipe.add_import([
+    "import pandas as pd",
+    "import numpy as np"
+])
+```
+
+Imports are:
+
+* Validated
+* Deduplicated
+* Inserted at the top of the generated script
+
+---
+
+## 5. Dependency Validation
+
+If `inputs` and `outputs` metadata are provided, QuickLearnKit can validate logical ordering.
+
+```python
+pipe.compile("pipeline.py", validate=True)
+```
+
+Validation checks:
+
+* Missing inputs
+* Duplicate outputs
+* Incorrect dependency flow
+
+### Strict Mode
+
+```python
+pipe.compile("pipeline.py", validate="strict")
+```
+
+Strict mode raises an error instead of warning.
+
+---
+
+## 6. Compile to Script
+
+Generate a clean Python script:
+
+```python
+pipe.compile("pipeline.py")
+```
+
+Generated file includes:
+
+* Registered imports
+* Stage-based comment grouping
+* Ordered function definitions
+* A clean execution block
+
+Example structure:
+
+```python
+import pandas as pd
+
+# ==============================
+# Preprocessing
+# ==============================
+
+def preprocess(X):
+    return X
+
+# ==============================
+# Training
+# ==============================
+
+def train(X):
+    return "model"
+
+if __name__ == '__main__':
+    print('Pipeline ready.')
+```
+
+---
+
+## 7. Reset Pipeline
+
+Clear committed functions and imports:
+
+```python
+pipe.reset()
+```
+
+This resets:
+
+* Committed functions
+* Metadata
+* Imports
+* Compile lock
+
+---
+
+## Guard Rails
+
+To ensure clean compilation, QuickLearnKit prevents committing:
+
+* Lambda functions
+* Built-in functions
+* Class methods
+* Nested functions
+* Non-user-defined callables
+
+Only top-level Python functions can be committed.
+
+---
+
+## Example: Full Hybrid Workflow
+
+```python
+from quicklearnkit import Pipeline
+
+pipe = Pipeline()
+
+pipe.add_import("""
+import pandas as pd
+from quicklearnkit import RandomForestClassifiermodel
+""")
+
+def preprocess(X):
+    return X
+
+def train(X):
+    model = RandomForestClassifiermodel()
+    return model
+
+pipe.commit(preprocess, outputs=["X_clean"], stage="Preprocessing")
+pipe.commit(train, inputs=["X_clean"], outputs=["model"], stage="Training")
+
+pipe.compile("ml_pipeline.py", validate=True)
+```
+
+---
+
+This extends QuickLearnKit from a learning utility library into a structured bridge between experimentation and scripting — while keeping full control in the developer’s hands.
+
+---
+
+If you’d like next, we can:
+
+* Add a **Table of Contents** (recommended now that it's growing)
+* Split README into sections for docs hosting
+* Or prepare a clean `CHANGELOG.md` for this release
+
+# Contributing
+
+Want to improve QuickLearnKit?
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests and documentation
+4. Submit a pull request
+
+---
+
+# License
+
+MIT License
+
+---
+
+QuickLearnKit helps you move from *learning* to *building* faster — without sacrificing clarity or control. 🚀

{quicklearnkit-0.2.2 → quicklearnkit-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quicklearnkit"
-version = "0.2.2"
+version = "0.4.0"
 description = "Learning-first machine learning utilities library for simplified imports, sampling, splitting, and probabilistic preprocessing."
 readme = "readme.md"
 license = { file = "LICENSE" }
@@ -16,7 +16,9 @@ dependencies = [
     "numpy",
     "pandas",
     "scikit-learn",
-    "xgboost"
+    "xgboost",
+    "seaborn",
+    "matplotlib"
 ]
 
 [tool.setuptools.packages.find]