chore: repo-wide quality improvements

.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: Notebook CI
+
+on:
+  push:
+    paths:
+      - 'notebooks/**/*.ipynb'
+      - 'requirements.txt'
+      - '.github/workflows/ci.yml'
+  pull_request:
+    paths:
+      - 'notebooks/**/*.ipynb'
+      - 'requirements.txt'
+
+jobs:
+  execute-notebooks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install nbconvert jupyter-client ipykernel
+          python -m ipykernel install --user --name python3
+
+      - name: Find changed notebooks
+        id: changed
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            NOTEBOOKS=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
+              | grep '\.ipynb$' | tr '\n' ' ')
+          else
+            NOTEBOOKS=$(git diff --name-only HEAD~1 HEAD \
+              | grep '\.ipynb$' | tr '\n' ' ')
+          fi
+          echo "notebooks=$NOTEBOOKS" >> "$GITHUB_OUTPUT"
+          echo "Changed notebooks: $NOTEBOOKS"
+
+      - name: Execute changed notebooks
+        if: steps.changed.outputs.notebooks != ''
+        run: |
+          FAILED=0
+          for nb in ${{ steps.changed.outputs.notebooks }}; do
+            echo "▶ Executing: $nb"
+            jupyter nbconvert \
+              --to notebook \
+              --execute \
+              --ExecutePreprocessor.timeout=300 \
+              --ExecutePreprocessor.kernel_name=python3 \
+              --inplace "$nb" || { echo "❌ FAILED: $nb"; FAILED=1; }
+          done
+          exit $FAILED
+
+      - name: Strip outputs before upload
+        if: always()
+        run: |
+          pip install nbstripout -q
+          find notebooks/ -name '*.ipynb' -exec nbstripout {} \;
+
+      - name: Upload executed notebooks on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: failed-notebooks
+          path: notebooks/**/*.ipynb
+          retention-days: 7

CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this repository are listed here.  
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [Unreleased]
+
+---
+
+## [1.3.0] — 2026-04-26
+
+### Added
+- **Topic 115** — End-to-End Real-World ML Project: Heart Disease Prediction capstone notebook covering EDA, preprocessing, PCA, SMOTE, multi-model benchmarking, hyperparameter tuning, ROC-AUC, and feature importance.
+- `imbalanced-learn==0.12.4` added to `requirements.txt`.
+- `nbstripout` added to `requirements.txt` and installed as a git filter — notebook outputs are now stripped automatically on every commit.
+- GitHub Actions CI workflow (`.github/workflows/ci.yml`) — executes changed notebooks on every push/PR and uploads failed notebooks as artifacts.
+- Binder URL validation script (`src/utils/check_binder_urls.py`).
+- Difficulty tags (`🟢` / `🟡` / `🔴`) and prerequisite notes added to each README section.
+- First-Time Setup section added to `CONTRIBUTING.md`.
+
+### Fixed
+- Replaced `fetch_openml` with `pandas.read_csv` in topic 115 notebook to avoid OpenML redirect errors.
+
+---
+
+## [1.2.0] — 2025-12-01
+
+### Added
+- Topics 108–114: Regression Evaluation Metrics, Linear Learning Machines, Kernel Function Matrix, Semi-Supervised Learning (SSL), Safe SSL, S3VM/TSVM, Softmax Activation Function.
+- Deep Learning section (topics 91–107): Introduction through LSTM.
+
+---
+
+## [1.1.0] — 2025-06-01
+
+### Added
+- Topics 66–90: Association Rules through Case-Based Reasoning.
+- Active Learning section (topics 47–56).
+- Multi-label & Multi-class Classification section (topics 57–64).
+
+---
+
+## [1.0.0] — 2025-01-01
+
+### Added
+- Initial release with topics 01–65.
+- Binder support for all notebooks.
+- `requirements.txt`, `environment.yml`, `runtime.txt` for reproducible environments.
+- `CONTRIBUTING.md` with branch strategy and naming conventions.

CONTRIBUTING.md

@@ -13,28 +13,33 @@ Thanks for contributing to this learning repository.
 - Notebook names use snake_case and end with `_starter.ipynb`
 - Optional helper scripts go in `src/`
 
+## First-Time Setup
+
+After cloning and installing dependencies, run these once:
+
+```bash
+pip install -r requirements.txt
+nbstripout --install   # strips notebook outputs before every commit
+git config core.hooksPath .githooks
+chmod +x .githooks/commit-msg
+```
+
 ## Pull Request Checklist
 
-- Notebook runs from top to bottom.
+- Notebook runs from top to bottom without errors.
+- Notebook outputs are **not** committed (nbstripout handles this automatically).
 - Code has clear section headers and short explanations.
-- Add or update the topic row in `README.md`.
-- Keep dependencies minimal.
+- Add or update the topic tile in `README.md` (include difficulty tag).
+- Keep dependencies minimal; add new packages to `requirements.txt` if needed.
 
 ## Co-Author Workflow
 
 For collaboration with `yatchmaster`:
 
 1. Add `yatchmaster` as a collaborator in repository settings.
 2. Work on a feature branch and open a PR.
-3. This repository includes a commit hook that auto-adds the co-author trailer for `yatchmaster` on every commit.
-4. Enable the hook once per clone:
-
-```bash
-git config core.hooksPath .githooks
-chmod +x .githooks/commit-msg
-```
-
-5. If needed, you can still add the trailer manually using this line:
+3. This repository includes a commit hook that auto-adds the co-author trailer for `yatchmaster` on every commit (enabled via First-Time Setup above).
+4. If needed, you can still add the trailer manually:
 
 ```text
 Co-authored-by: yatchmaster <yatchmaster@users.noreply.github.com>

README.md

@@ -36,6 +36,8 @@
 
 Practical Python examples for **115 Machine Learning and Data Science topics** from my YouTube channel.
 
+> **Difficulty legend:**   🟢 Beginner  ·  🟡 Intermediate  ·  🔴 Advanced
+
 ### 🎯 What you'll find here
 
 | | |
@@ -109,9 +111,11 @@ jupyter lab
 > **114 topics across 12 themes** — click a section to expand. Each tile links to the interactive Binder notebook and its companion YouTube video.
 
 <details open>
-<summary><b>🟦 Supervised Learning — Core Classifiers (01–17)</b></summary>
+<summary><b>🟦 Supervised Learning — Core Classifiers (01–17)</b> &nbsp;·&nbsp; 🟢 Beginner → 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Python basics, NumPy, pandas. Start here if you are new to ML.
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -199,9 +203,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🟨 Probabilistic & Rule-Based Methods (18–26)</b></summary>
+<summary><b>🟨 Probabilistic & Rule-Based Methods (18–26)</b> &nbsp;·&nbsp; 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Topics 01–07 (core classifiers).
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -250,9 +256,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🟧 Class Imbalance & Evaluation Curves (27–30)</b></summary>
+<summary><b>🟧 Class Imbalance & Evaluation Curves (27–30)</b> &nbsp;·&nbsp; 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Topics 01–07, 11 (cross-validation).
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -281,9 +289,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🟩 Clustering (31–46)</b></summary>
+<summary><b>🟩 Clustering (31–46)</b> &nbsp;·&nbsp; 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Topics 06 (PCA), 11 (cross-validation). No labelled data required.
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -368,9 +378,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🟪 Active Learning (47–56)</b></summary>
+<summary><b>🟪 Active Learning (47–56)</b> &nbsp;·&nbsp; 🔴 Advanced</summary>
 <br/>
 
+> **Prerequisites:** Topics 01–17, 27–30 (evaluation).
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -427,9 +439,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🔵 Multi-label & Multi-class Classification (57–64)</b></summary>
+<summary><b>🔵 Multi-label & Multi-class Classification (57–64)</b> &nbsp;·&nbsp; 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Topics 01–07, 11.
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -475,9 +489,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🟫 Pattern Mining & Statistical Theory (65–74)</b></summary>
+<summary><b>🟫 Pattern Mining & Statistical Theory (65–74)</b> &nbsp;·&nbsp; 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Topics 07 (Naive Bayes), basic probability.
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -534,9 +550,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>⬛ Concept Learning, Algorithms & Regression (75–85)</b></summary>
+<summary><b>⬛ Concept Learning, Algorithms & Regression (75–85)</b> &nbsp;·&nbsp; 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Topics 01, 03 (Decision Trees), 11.
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -596,9 +614,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🔶 Dimensionality Reduction & Lazy Learning (86–90)</b></summary>
+<summary><b>🔶 Dimensionality Reduction & Lazy Learning (86–90)</b> &nbsp;·&nbsp; 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Topics 05 (KNN), 06 (PCA).
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -630,9 +650,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🔴 Deep Learning (91–107)</b></summary>
+<summary><b>🔴 Deep Learning (91–107)</b> &nbsp;·&nbsp; 🔴 Advanced</summary>
 <br/>
 
+> **Prerequisites:** Topics 22–23 (Neural Networks), 80 (Gradient Descent). Familiarity with NumPy recommended.
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -720,9 +742,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>⚫ Advanced & Semi-Supervised Methods (108–113)</b></summary>
+<summary><b>⚫ Advanced & Semi-Supervised Methods (108–113)</b> &nbsp;·&nbsp; 🔴 Advanced</summary>
 <br/>
 
+> **Prerequisites:** Topics 01–30, 91–107 (Deep Learning basics).
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -756,9 +780,11 @@ jupyter lab
 
 </details>
 <details>
-<summary><b>🎯 Advanced Activation Functions (114–114)</b></summary>
+<summary><b>🎯 Advanced Activation Functions (114–114)</b> &nbsp;·&nbsp; 🔴 Advanced</summary>
 <br/>
 
+> **Prerequisites:** Topics 91–107 (Deep Learning).
+
 <table>
 <tr>
 <td align="center" width="33%">
@@ -771,9 +797,11 @@ jupyter lab
 </details>
 
 <details>
-<summary><b>🏁 End-to-End Real-World Project (115)</b></summary>
+<summary><b>🏁 End-to-End Real-World Project (115)</b> &nbsp;·&nbsp; 🟡 Intermediate</summary>
 <br/>
 
+> **Prerequisites:** Topics 01–30 recommended. This notebook deliberately revisits concepts from across the course.
+
 A capstone notebook that applies the concepts from the entire course to a real dataset.  
 We predict **Heart Disease** using the UCI Cleveland dataset, walking through every stage a practitioner faces:
 

requirements.txt

@@ -4,4 +4,5 @@ scikit-learn==1.5.2
 matplotlib==3.9.2
 seaborn==0.13.2
 imbalanced-learn==0.12.4
+nbstripout>=0.7
 jupyterlab>=4.3,<5