simple-sklearn 0.1.0__tar.gz

simple_sklearn-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 (2026-07-15)
+
+
+* Initial release

simple_sklearn-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,156 @@
+# Contributing to simple-sklearn
+
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Typing](https://img.shields.io/pypi/types/simple-sklearn)](https://pypi.org/p/simple-sklearn)
+
+First off, thank you for considering contributing to **simple-sklearn**!
+
+Before starting work on a major feature or architectural change, please open an issue to discuss it.
+This ensures your approach aligns with the project's roadmap and prevents wasted effort.
+
+---
+
+## Conventional Commits
+
+This repository uses [Release Please](https://github.com/googleapis/release-please) to automate
+changelog generation and GitHub releases.
+
+Because of this, **all Pull Request titles must follow the
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.**
+
+* Example feature: `feat: implement KDTree for neighbors search`
+* Example bug fix: `fix(dbscan): resolve zero-division error`
+* Example docs: `docs: update roadmap in README`
+
+If your PR does not follow this structure, the automated CI/CD pipeline will fail to interpret
+the changes for semantic versioning.
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+* Python 3.10 or higher
+* Git
+
+### Workflow
+
+The project uses a Makefile to simplify development workflows.
+
+*Note for Windows users: the `make` tool is not natively installed on Windows, but manual fallback commands
+are provided below.*
+
+1. **Fork and clone the repository:**
+
+    Click the "Fork" button at the top right of the repository page, then clone your fork locally:
+
+    ```bash
+    git clone https://github.com/<YOUR-USERNAME>/simple-sklearn.git
+    cd simple-sklearn
+    ```
+
+2. **Add the upstream remote:**
+
+    This allows you to keep your fork synced with the main repository:
+
+    ```bash
+    git remote add upstream https://github.com/Artem259/simple-sklearn.git
+    ```
+
+3. **Create a feature branch:**
+
+    Always create a new branch for your work rather than committing to `main`:
+
+    ```bash
+    git checkout -b feat/my-new-feature
+    ```
+
+4. **Create and activate a virtual environment:**
+
+    ```bash
+    python -m venv .venv
+
+    # On Linux/macOS:
+    source .venv/bin/activate
+
+    # On Windows:
+    .venv\Scripts\activate
+    ```
+
+5. **Install Dependencies:**
+
+    **Using `make` (Linux/macOS):**
+
+    This command installs the package in editable mode along with all necessary dev dependencies,
+    and sets up the `pre-commit` hooks.
+
+    ```bash
+    make setup
+    ```
+
+    **Manual commands (Windows):**
+
+    ```bash
+    python -m pip install --upgrade pip
+    python -m pip install -e ".[docs,quality,build,test,dev]"
+    pre-commit install
+    ```
+
+6. **Run checks and tests:**
+
+    The project uses `ruff` for formatting/linting, `mypy` for static type checking, and `pytest` for testing.
+
+    ```bash
+    make lint        # Runs pre-commit checks across all files
+    make test        # Runs the pytest suite
+    make test-cov    # Runs the pytest suite and generates a coverage report
+    make check       # Runs linting, build verification (sdist/wheel), and tests sequentially
+    ```
+
+    You can also run `pytest` and `pre-commit run --all-files` manually.
+
+7. **Local CI/CD Simulation (Optional):**
+
+    If you have [act](https://nektosact.com/) installed locally, you can simulate the GitHub Actions pipeline
+    before opening a PR:
+
+    ```bash
+    make act-pr      # Simulates the pull-request workflow locally
+    ```
+
+8. **Build documentation locally:**
+
+    The project uses `mkdocs` with the `mkdocs-jupyter` plugin for demo Jupyter notebooks.
+
+    ```bash
+    make docs        # Preview documentation with live-reloading (no notebook execution)
+    make docs-build  # Build and verify documentation
+    ```
+
+---
+
+## Coding Standards & Guidelines
+
+To maintain the quality of code and architecture of simple-sklearn, please adhere to the following:
+
+* **Scikit-learn Compatibility:** Any new estimator must inherit from `BaseEstimator`, the appropriate mixin
+(`ClassifierMixin`/`ClusterMixin`), and successfully pass `sklearn.utils.estimator_checks`.
+* **Type Hinting:** The project utilizes strict `mypy` typing. Ensure all function signatures and
+class attributes are appropriately type-hinted.
+* **Docstrings:** Use **Google-style docstrings**. This is strictly required so that `mkdocstrings`
+can correctly generate the API reference documentation.
+
+---
+
+## Submitting Your Pull Request
+
+Before submitting your PR, please ensure you have completed the following checklist:
+
+* [ ] I have fetched the latest changes from `upstream/main` and rebased my branch if necessary.
+* [ ] My PR is narrowly scoped to address a single feature or bug fix.
+* [ ] `make check` and `make docs-build` (or the equivalent manual commands) pass locally without errors.
+* [ ] I have added or updated tests for my changes, and my changes do not decrease overall test coverage.
+* [ ] I have successfully run scikit-learn estimator checks against any new estimators.
+* [ ] I have updated the docstrings and documentation if my changes affect the API.
+* [ ] My PR title follows the Conventional Commits specification.

simple_sklearn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Artem Poliakov
+
+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.

simple_sklearn-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: simple-sklearn
+Version: 0.1.0
+Summary: Pythonic machine learning algorithms built for educational transparency and scikit-learn compatibility
+Author-email: Artem Poliakov <artem4250@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://Artem259.github.io/simple-sklearn
+Project-URL: Repository, https://github.com/Artem259/simple-sklearn
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: typing-extensions<5.0,>=4.1.0
+Provides-Extra: docs
+Requires-Dist: notebook>=7.3.2; extra == "docs"
+Requires-Dist: matplotlib>=3.9.4; extra == "docs"
+Requires-Dist: seaborn>=0.13.2; extra == "docs"
+Requires-Dist: mkdocs<2.0,>=1.6.1; extra == "docs"
+Requires-Dist: mkdocs-material>=9.7.5; extra == "docs"
+Requires-Dist: mkdocs-jupyter>=0.25.1; extra == "docs"
+Requires-Dist: mkdocstrings-python>=2.0.3; extra == "docs"
+Provides-Extra: quality
+Requires-Dist: mypy>=1.19.1; extra == "quality"
+Requires-Dist: pandas-stubs>=2.2.3; extra == "quality"
+Requires-Dist: scipy-stubs>=1.13.1; extra == "quality"
+Provides-Extra: build
+Requires-Dist: build==1.4.0; extra == "build"
+Requires-Dist: twine==6.2.0; extra == "build"
+Requires-Dist: check-sdist==1.4.0; extra == "build"
+Requires-Dist: check-wheel-contents==0.6.3; extra == "build"
+Provides-Extra: test
+Requires-Dist: pytest>=8.4.2; extra == "test"
+Requires-Dist: pytest-cov>=6.0.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0.0; extra == "dev"
+Requires-Dist: ruff==0.14.9; extra == "dev"
+Dynamic: license-file
+
+# simple-sklearn
+
+[![CI/CD](https://github.com/Artem259/simple-sklearn/actions/workflows/ci-cd.yml/badge.svg)][ci-cd-url]
+[![codecov](https://codecov.io/gh/Artem259/simple-sklearn/graph/badge.svg)][codecov-url]
+[![PyPI version](https://badge.fury.io/py/simple-sklearn.svg)][pypi-url]
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)][python-url]
+[![Docs](https://img.shields.io/badge/docs-GitHub_Pages-blue.svg)][docs-url]
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)][license-url]
+
+**simple-sklearn** is a Python package designed to provide clear, readable, and highly pythonic implementations of
+fundamental machine learning algorithms. Abstracting away from complex low-level optimizations, this library
+focuses on clarity and educational value using high-level libraries like `numpy`, `pandas`, and `scipy`.
+
+Every model is designed to integrate seamlessly with scikit-learn's estimator API, inheriting from
+`sklearn.base.BaseEstimator` and the appropriate mixins (`ClassifierMixin` or `ClusterMixin`). This allows you
+to plug these simple implementations directly into `scikit-learn` pipelines and cross-validation workflows.
+
+**WARNING: Not for Production Use.** This library is built for educational purposes and algorithmic transparency.
+The implementations prioritize readability and simplicity over execution speed and memory optimization.
+
+---
+
+## Available Models
+
+**Classification:**
+
+* OneRClassifier: 1R (One Rule) classification.
+* NaiveBayesClassifier: Categorical Naive Bayes classification.
+* KNeighborsClassifier: K-Nearest Neighbors classification.
+* DecisionTreeClassifier: Decision Tree classification using the ID3 algorithm.
+
+**Clustering:**
+
+* KMeans: K-Means clustering.
+* KMedoids: K-Medoids clustering.
+* DBSCAN: Density-Based Spatial Clustering of Applications with Noise.
+* AgglomerativeClustering: Hierarchical agglomerative clustering.
+
+---
+
+## Installation
+
+**Requirements:**
+
+* Python 3.10+
+
+**Install directly from PyPI** using `pip`:
+
+```bash
+pip install simple-sklearn
+```
+
+Core Dependencies:
+
+* scikit-learn (>= 1.6.1)
+* numpy (>= 1.26)
+* pandas (>= 2.2.3)
+* scipy (>= 1.13.1)
+* typing-extensions (>=4.1.0, <5.0)
+
+---
+
+## Quick Start
+
+Because simple-sklearn strictly implements the scikit-learn API, you can fit and predict models exactly as you would
+with scikit-learn.
+
+### Classification Example
+
+```python
+import numpy as np
+from simple_sklearn.classification import NaiveBayesClassifier
+
+# Categorical data
+X = np.array([[0, 0], [0, 1], [1, 0], [2, 2], [2, 3]])
+y = np.array([0, 0, 0, 1, 1])
+
+# Initialize and fit the model
+clf = NaiveBayesClassifier()
+clf.fit(X, y)
+
+# Predict on new data
+X_new = np.array([[2, 2], [1, 4]])
+predictions = clf.predict(X_new)  # Handles unseen category '4' gracefully
+print(f"Predictions: {predictions}")  # Output: [1 0]
+```
+
+### Clustering Example
+
+```python
+import numpy as np
+from simple_sklearn.clustering import KMeans
+
+# Continuous data
+X = np.array([[0.1, 0.1], [0.2, 0.1], [10.1, 10.1], [10.2, 10.1]])
+
+# Initialize and fit the model
+clusterer = KMeans(n_clusters=2, max_iter=10, random_state=42)
+clusterer.fit(X)
+
+print(f"Cluster labels: {clusterer.labels_}")  # Output: [0 0 1 1]
+print(f"Cluster centers: \n{clusterer.cluster_centers_}")  # Output: [[0.15, 0.1], [10.15, 10.1]]
+```
+
+---
+
+## Documentation
+
+Detailed API references, algorithm details, and Jupyter Notebook usage examples are available on the library website:
+
+**[Artem259.github.io/simple-sklearn][docs-url]**
+
+---
+
+## Development & Contributing
+
+Pull requests are welcome! If you'd like to contribute, please read the [Contributing Guide][contrib-url].
+
+---
+
+## Roadmap
+
+Future development focuses on:
+
+1. Estimator Enhancements and Performance Optimization:
+    * Implementing a custom KDTree for faster nearest-neighbor searches.
+    * Refactoring AgglomerativeClustering with Priority Queue (Min-Heap) to reduce time complexity
+      during cluster merging.
+    * Adding other estimator features (e.g., standard hyperparameters like `max_depth` for `DecisionTreeClassifier`).
+2. Documentation Upgrades:
+    * Configuring documentation versioning via the `mike` tool.
+
+---
+
+## License
+
+This project is licensed under the [MIT License][license-url].
+
+[ci-cd-url]: https://github.com/Artem259/simple-sklearn/actions/workflows/ci-cd.yml
+[codecov-url]: https://codecov.io/gh/Artem259/simple-sklearn
+[pypi-url]: https://pypi.org/p/simple-sklearn
+[python-url]: https://www.python.org/downloads/
+[docs-url]: https://Artem259.github.io/simple-sklearn
+[license-url]: https://github.com/Artem259/simple-sklearn/blob/main/LICENSE
+[contrib-url]: https://github.com/Artem259/simple-sklearn/blob/main/CONTRIBUTING.md

simple_sklearn-0.1.0/README.md

@@ -0,0 +1,145 @@
+# simple-sklearn
+
+[![CI/CD](https://github.com/Artem259/simple-sklearn/actions/workflows/ci-cd.yml/badge.svg)][ci-cd-url]
+[![codecov](https://codecov.io/gh/Artem259/simple-sklearn/graph/badge.svg)][codecov-url]
+[![PyPI version](https://badge.fury.io/py/simple-sklearn.svg)][pypi-url]
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)][python-url]
+[![Docs](https://img.shields.io/badge/docs-GitHub_Pages-blue.svg)][docs-url]
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)][license-url]
+
+**simple-sklearn** is a Python package designed to provide clear, readable, and highly pythonic implementations of
+fundamental machine learning algorithms. Abstracting away from complex low-level optimizations, this library
+focuses on clarity and educational value using high-level libraries like `numpy`, `pandas`, and `scipy`.
+
+Every model is designed to integrate seamlessly with scikit-learn's estimator API, inheriting from
+`sklearn.base.BaseEstimator` and the appropriate mixins (`ClassifierMixin` or `ClusterMixin`). This allows you
+to plug these simple implementations directly into `scikit-learn` pipelines and cross-validation workflows.
+
+**WARNING: Not for Production Use.** This library is built for educational purposes and algorithmic transparency.
+The implementations prioritize readability and simplicity over execution speed and memory optimization.
+
+---
+
+## Available Models
+
+**Classification:**
+
+* OneRClassifier: 1R (One Rule) classification.
+* NaiveBayesClassifier: Categorical Naive Bayes classification.
+* KNeighborsClassifier: K-Nearest Neighbors classification.
+* DecisionTreeClassifier: Decision Tree classification using the ID3 algorithm.
+
+**Clustering:**
+
+* KMeans: K-Means clustering.
+* KMedoids: K-Medoids clustering.
+* DBSCAN: Density-Based Spatial Clustering of Applications with Noise.
+* AgglomerativeClustering: Hierarchical agglomerative clustering.
+
+---
+
+## Installation
+
+**Requirements:**
+
+* Python 3.10+
+
+**Install directly from PyPI** using `pip`:
+
+```bash
+pip install simple-sklearn
+```
+
+Core Dependencies:
+
+* scikit-learn (>= 1.6.1)
+* numpy (>= 1.26)
+* pandas (>= 2.2.3)
+* scipy (>= 1.13.1)
+* typing-extensions (>=4.1.0, <5.0)
+
+---
+
+## Quick Start
+
+Because simple-sklearn strictly implements the scikit-learn API, you can fit and predict models exactly as you would
+with scikit-learn.
+
+### Classification Example
+
+```python
+import numpy as np
+from simple_sklearn.classification import NaiveBayesClassifier
+
+# Categorical data
+X = np.array([[0, 0], [0, 1], [1, 0], [2, 2], [2, 3]])
+y = np.array([0, 0, 0, 1, 1])
+
+# Initialize and fit the model
+clf = NaiveBayesClassifier()
+clf.fit(X, y)
+
+# Predict on new data
+X_new = np.array([[2, 2], [1, 4]])
+predictions = clf.predict(X_new)  # Handles unseen category '4' gracefully
+print(f"Predictions: {predictions}")  # Output: [1 0]
+```
+
+### Clustering Example
+
+```python
+import numpy as np
+from simple_sklearn.clustering import KMeans
+
+# Continuous data
+X = np.array([[0.1, 0.1], [0.2, 0.1], [10.1, 10.1], [10.2, 10.1]])
+
+# Initialize and fit the model
+clusterer = KMeans(n_clusters=2, max_iter=10, random_state=42)
+clusterer.fit(X)
+
+print(f"Cluster labels: {clusterer.labels_}")  # Output: [0 0 1 1]
+print(f"Cluster centers: \n{clusterer.cluster_centers_}")  # Output: [[0.15, 0.1], [10.15, 10.1]]
+```
+
+---
+
+## Documentation
+
+Detailed API references, algorithm details, and Jupyter Notebook usage examples are available on the library website:
+
+**[Artem259.github.io/simple-sklearn][docs-url]**
+
+---
+
+## Development & Contributing
+
+Pull requests are welcome! If you'd like to contribute, please read the [Contributing Guide][contrib-url].
+
+---
+
+## Roadmap
+
+Future development focuses on:
+
+1. Estimator Enhancements and Performance Optimization:
+    * Implementing a custom KDTree for faster nearest-neighbor searches.
+    * Refactoring AgglomerativeClustering with Priority Queue (Min-Heap) to reduce time complexity
+      during cluster merging.
+    * Adding other estimator features (e.g., standard hyperparameters like `max_depth` for `DecisionTreeClassifier`).
+2. Documentation Upgrades:
+    * Configuring documentation versioning via the `mike` tool.
+
+---
+
+## License
+
+This project is licensed under the [MIT License][license-url].
+
+[ci-cd-url]: https://github.com/Artem259/simple-sklearn/actions/workflows/ci-cd.yml
+[codecov-url]: https://codecov.io/gh/Artem259/simple-sklearn
+[pypi-url]: https://pypi.org/p/simple-sklearn
+[python-url]: https://www.python.org/downloads/
+[docs-url]: https://Artem259.github.io/simple-sklearn
+[license-url]: https://github.com/Artem259/simple-sklearn/blob/main/LICENSE
+[contrib-url]: https://github.com/Artem259/simple-sklearn/blob/main/CONTRIBUTING.md

simple_sklearn-0.1.0/data/README.md

@@ -0,0 +1,24 @@
+# Data
+
+This directory contains the datasets used in tests and the documentation's usage example notebooks.
+
+---
+
+## Datasets
+
+### Student Performance
+
+* **File:** `_student_performance.csv`
+* **Source:** [Students Performance Dataset on Kaggle][1.1]
+* **License:** [Attribution 4.0 International (CC BY 4.0)][1.2]
+
+### Country Data
+
+* **File:** `_country_data.csv`
+* **Source:** [Unsupervised Learning on Country Data on Kaggle][2.1]
+* **License:** [MIT License][2.2]
+
+[1.1]: https://www.kaggle.com/datasets/rabieelkharoua/students-performance-dataset
+[1.2]: https://creativecommons.org/licenses/by/4.0/
+[2.1]: https://www.kaggle.com/datasets/rohan0301/unsupervised-learning-on-country-data
+[2.2]: https://opensource.org/licenses/MIT

simple_sklearn-0.1.0/data/classification_4f.csv

@@ -0,0 +1,11 @@
+x0,x1,x2,x3,y
+0,0,1,0,0
+1,0,0,1,1
+2,0,1,0,1
+0,1,0,0,1
+0,1,1,0,1
+0,1,1,1,0
+1,0,0,1,0
+2,0,0,0,1
+2,1,1,0,1
+0,1,1,1,0

simple_sklearn-0.1.0/data/clustering_2f.csv

@@ -0,0 +1,11 @@
+x,y,label
+1,5,A
+2,4,B
+2,7,C
+2,9,D
+3,1,E
+5,5,F
+5,7,G
+6,6,H
+7,6,I
+10,6,J