Lesson 10-11: Supervised Learning: Classification

Introduction

Supervised classification is easy to learn in fragments: one notebook for decision trees, another for random forests, a third for fraud with SMOTE, then KNN and SVM in isolation. Each exercise works. None of them answer the question backend engineers actually face: how do these algorithms live together behind one API, one evaluation contract, and one product surface?

week_10_11_aiml_integrated_project closes that gap. It is a self-contained capstone that unifies eight classification topics into one repository:

• An installable Python package (week1011_python) holding domain logic for scratch decision trees, sklearn trees, random forests, fraud detection, scratch KNN, sklearn KNN pipelines, scratch SVM, and sklearn SVM fraud scoring

• A composition engine (classical_ml_engine) that wires those topics into product workflows—fraud training, model comparison, registry persistence, and end-to-end pipeline runs

• A FastAPI backend exposing two API surfaces: a lab path for per-topic exploration and a product path for composed risk and analytics workflows

• An optional React frontend—Risk Studio—for fraud operations, model comparison, and engine introspection

The goal is system-first learning. Entropy splits are not just a classroom exercise—they are a stage inside the model comparison lab. SMOTE and threshold tuning precede production fraud scoring in fraud_pipeline.train_fraud_model(). Algorithm theory becomes control flow.

For engineers, the payoff is traceability. Fraud scoring is not a one-off function call—it is POST /api/v1/risk/fraud/score with a persisted model bundle, request IDs, and timing metadata. Side-by-side algorithm comparison trains random forest, KNN, and SVM on shared fraud features in one call, returning EvaluationReportV1 metrics for each.

Core Components

The stack is layered. Each topic below is a distinct building block; together they form one coherent classification system.

Decision trees from scratch

Implements binary decision trees using entropy and information gain on synthetic customer churn data. DecisionTree supports configurable max_depth and min_samples_split, tracks tree depth after fitting, and returns predictions on held-out rows.

The week1011_apis module exposes JSON-safe training and prediction entry points. Lab routes accept n_samples, max_depth, and min_samples_split; responses return tree depth, EvaluationReportV1 metrics, feature names, and churn rate.

Scikit-learn decision trees

Trains a CustomerChurnPredictor with sklearn on synthetic churn tabular data. Supports optional grid search, cross-validation summaries, feature importance rankings, and ROC-AUC on the test split.

Lab endpoints return CV mean/std, test accuracy, confusion matrix, and top feature importances—bridging from manual tree construction to library-based classification with class-weight support.

Random forests

Compares a single decision tree against a random forest ensemble on the same churn dataset. CustomerChurnPredictor (forest variant) generates synthetic data, trains both estimators, evaluates side by side, and extracts top feature importances.

The forest comparison endpoint returns single_tree and random_forest metric blocks plus ranked features—making ensemble variance reduction tangible in one JSON payload.

Fraud detection with imbalance handling

A full fraud workflow: synthetic transaction generation at extreme fraud ratios (~0.2%), feature engineering, SMOTE oversampling, random forest training, and recall-targeted threshold optimization.

FraudDetectionSystem owns data generation, feature engineering, training, and per-transaction scoring. Product fraud training can select an engineered feature view (full pipeline with SMOTE) or a compact feature view (four numeric columns with SVM grid search). Threshold optimization targets a configurable recall (default 0.90).

KNN from scratch

Implements KNNClassifier with configurable k, Euclidean distance, and majority-vote prediction. The k-sweep lab endpoint trains across a list of k values on a 2D synthetic classification dataset and returns accuracy per k plus the best performer.

Useful for teaching similarity intuition before introducing scaling and sklearn pipelines.

KNN with sklearn pipelines