🧪 Classical ML Lab

Classical ML Lab is a practice repository for classical machine learning. It pairs hands-on Kaggle competition notebooks with study material on classical algorithms — from KNN, decision trees, and linear models to ensemble methods — built on scikit-learn, the gradient-boosting trio (XGBoost / CatBoost / LightGBM), and Optuna for tuning.

📂 Project Structure

.
├── learning/                   # Study material
│   ├── algorithms/             # Algorithm walkthroughs (classification + regression)
│   │   ├── decision_trees/
│   │   ├── knn/                # Brute force + Annoy / HNSW / k-d trees / LSH
│   │   ├── regression_algorithms/   # Linear & logistic regression
│   │   ├── ensemble_methods/   # Bagging, random forest, gradient boosting, stacking
│   │   └── hyperparameter_tuning/   # Grid search, random search
│   ├── metrics/                # Classification & regression metrics
│   └── libraries/              # Tooling notebooks (matplotlib, optuna)
├── competitions/               # Kaggle solutions (each with its own data/ folder)
│   ├── titanic/
│   └── spaceship_titanic/
├── src/                        # Reusable helpers imported by the notebooks
│   ├── evaluations/            # Metric tables for (multi)classification & regression
│   └── plots/                  # Confusion matrices, ROC/PR curves, boundaries, etc.
├── templates/                  # Starter notebooks (algorithm.ipynb, competition.ipynb)
├── pyproject.toml              # Dependencies, ruff, mypy, commitizen config
└── Taskfile.yml                # Common developer commands

📦 Dependencies

• Python 3.13+
• uv — environment & dependency management
• Task — task runner
• Jupyter — running the notebooks

Python packages are split into dependency groups in pyproject.toml:

Group	Purpose
data	numpy, pandas
ml	scikit-learn, XGBoost, CatBoost, LightGBM
viz	matplotlib, seaborn, plotly
tuning	optuna, hyperopt, scikit-optimize
notebook	ipywidgets, tqdm, and other notebook UX helpers
dev	ruff, mypy, pytest, pre-commit, commitizen, audit tooling

🚀 Getting Started

# 1. Clone the repository
git clone https://github.com/NKTKLN/classical-ml-lab.git
cd classical-ml-lab

# 2. Install dependencies and git hooks
task init

# 3. Launch Jupyter and open any notebook
uv run jupyter lab

task init runs uv sync --all-groups and installs the pre-commit hooks. Don't have Task? Run uv sync --all-groups and uv run pre-commit install --install-hooks directly.

🛠️ Common Tasks

Run task --list to see everything. The most useful commands:

Command	Description
task init	Full setup: sync dependencies + install hooks
task sync	Sync dependencies with uv
task fmt	Auto-fix lint issues and format code
task lint	Run ruff + format check + mypy
task audit	Security audit of dependencies (pip-audit)
task check	Full quality gate (lint, tests, audit, deps)
task cz-commit	Commit using Conventional Commits

📜 License

This project is licensed under the MIT License. See the LICENSE.md file for details.