Metadata-Version: 2.4
Name: rslearn-py
Version: 1.0.5
Summary: A simple sklearn-like ML library built from scratch
Author-email: ItzRustam <rustambhadouriya7@gmail.com>
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/rslearn-lib/rslearn-ML-py
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy
Dynamic: license-file

# 🚀 rslearn

> A beginner-friendly machine learning library that automates preprocessing, training, and evaluation.

![License](https://img.shields.io/badge/license-GPLv3-blue.svg)
![Python](https://img.shields.io/badge/python-3.11.x-blue.svg)
![Status](https://img.shields.io/badge/status-active-success.svg)
![Contributions](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)

---

## ✨ Why rslearn?

- ⚡ Minimal setup — no complex configuration  
- 🤖 Automatic pipeline (scaling, splitting, evaluation)  
- 📊 Built-in metrics for regression & classification  
- 🧠 Designed for beginners learning ML concepts  
- 🧩 Clean and simple API inspired by sklearn  
- 📈 Automated evaluations with `evaluate_model`

---

## Release & Changes
* **Version : 1.1.1 - 1.0.5** 
* **Release Date: 2026-08-20**
* [CHANGELOG](CHANGELOG.md)

# NOTE
tests/* will be changed for each functions after documantation update.


## Download Version Specific Module
***[Downloads - Module](download.md)***

### 📊 Linear Models

* Linear Regression (Single & Multi-feature)
* Logistic Regression (Binary & Multi-class)
* Ridge Regression (L2 Regularization)
* Lasso Regression (L1 Regularization)
* Elastic Net (L1 + L2)

---
### 📊 K-nearest Neighbors Models

* KNNRegressor (Single & Multi-feature)
* KNNClassifier (Binary & Multi-class)

---

### 📏 Metrics

* Mean Squared Error (MSE)
* Mean Absolute Error (MAE)
* Root Mean Squared Error (RMSE)
* R² Score
* Accuracy (for classification)
* Euclidian Distance (for KNN)

✔ Supports **single-output and multi-output** tasks

---

### 🔧 Preprocessing

* StandardScaler
* MinMaxScaler

---

### 🧪 Model Selection

* Train-Test Split

  * Supports `stratify` for balanced sampling

---

## ⚙️ Optimization Details

All models in **rslearn** are implemented using **Gradient Descent**.

⚠️ **Important:**

* Feature scaling is highly recommended for stable and faster convergence.
* Use:

  * `StandardScaler` (recommended)
  * or `MinMaxScaler`

* or just use `scale=True` parameter while `fit()`
---



## 🤖 Auto Standard Scaling (Linear, Logistic, Ridge, Lasso, ElasticNet)

models include Inbuilt StandardScaler Feature in fit() Method:

```python
scale=True  # default
```

* Automatically applies feature scaling internally
* Helps prevent numerical instability

---

## 📁 Project Structure

```text id="rslrn1"
rslearn-ML/
│
├── rslearn/
│   │
│   ├── BaseEstimators/
│   │   └── __init__.py  
│   │   └── _base.py  
│   │   └── _estimator.py  
│   │
│   ├── Errors/
│   │   ├── __init__.py
│   │   └── _errors.py  
│   │
│   ├── loader/
│   │   ├── __init__.py
│   │   └── _pipeline_loader.py
│   │   └── _model_loader.py  
│   │
│   ├── linear_model/
│   │   ├── __init__.py
│   │   ├── README.md
│   │   ├── _LinearRegression.py
│   │   ├── _LogisticRegression.py
│   │   └── _regulizations.py
│   │
│   ├── metrics/
│   │   ├── __init__.py
│   │   ├── README.md  
│   │   ├── _evaluations.py  
│   │   ├── regression_readme.md  
│   │   ├── evaluation.md  
│   │   ├── classification_readme.md
│   │   ├── _classification.py
│   │   ├── _distances.py
│   │   └── _regression.py
│   │
│   ├── model_selection/
│   │   ├── __init__.py
│   │   ├── README.md
│   │   └── _split.py
│   │
│   ├── neighbors/
│   │   ├── __init__.py
│   │   ├── README.md
│   │   ├── _knnClass.py
│   │   └── _knnReg.py
│   │
│   ├── Pipeline/
│   │   ├── __init__.py
│   │   ├── README.md
│   │   └── _pipeline.py
│   │
│   ├── preprocessing/
│   │   ├── __init__.py
│   │   ├── README.md
│   │   └── _scaler.py
│   │
│   └── __init__.py
│
├── README.md

```



📌 Each module contains its own **detailed README** with usage examples and explanations.

---

## 🛠️ Installation

### Clone the repository

```bash
git clone https://github.com/rslearn-lib/rslearn-ML-py.git
cd rslearn-ML-py/
```

### Install Usable Library (Stable - Latest)
``` bash
pip install rslearn-py
```
## Download Version Specific Module
***[Downloads Older Library](download.md)***

### Install dependencies

```bash
pip install -r requirements.txt
```

---

## 📌 Quick Example

```python
import rslearn
from rslearn.linear_model import LinearRegression
import numpy as np

print(rslearn.__version__)
print(rslearn.__github_version__)
X = np.array([10, 20, 30])
y = np.array([5, 10, 15])

model = LinearRegression()
model.fit(X, y, scale=True) # Auto Scale if True, else Gradient Stability Backend

print(model.predict([40]))
```

---

## 📚 Documentation

* Each folder includes its own **README.md**
* Covers:

  * Usage
  * Parameters
  * Examples
  * Internal working  
Good For `Developers` & `Contributors`

**User Guide** 
* [Docs](docs/README.md)
* [user guide](docs/user_guide/README.md)
* [quick start guide](docs/quick_start.md)


---

## 🧑‍💻 Author

**ItzRustam**

## 🔨 Origination
**rslearn-lib**

---

## 📜 License

This project is licensed under the GNU GPL v3 License.
