Intro

# ===== The core idea =====
# Given examples, learn a function f(x) -> y that generalises to new inputs.
# Generalisation is the whole point; memorisation is failure.

# ===== Families =====
# Supervised:    inputs X with labels y (classification, regression)
# Unsupervised:  inputs X only (clustering, dimensionality reduction)
# Self-supervised: labels generated from data itself (BERT, contrastive)
# Reinforcement: agent + environment + reward (game agents, robotics)

# ===== The smallest example =====
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score

X, y = load_iris(return_X_y=True)
Xtr, Xte, ytr, yte = train_test_split(X, y, stratify=y, random_state=42)

model = LogisticRegression(max_iter=2000).fit(Xtr, ytr)
pred = model.predict(Xte)
print('accuracy:', accuracy_score(yte, pred))

# ===== The 5-stage workflow =====
# 1. Frame the problem (regression? classification? recommendation?)
# 2. Gather + clean data
# 3. Split into train/val/test
# 4. Train + tune
# 5. Evaluate on held-out test

# ===== When ML wins =====
# - Patterns too complex for hand-written rules
# - Lots of historical data to learn from
# - Tasks with measurable success metrics

# ===== When ML hurts =====
# - When a rule would do (simpler, debuggable)
# - Small data + high stakes (model uncertainty bites)
# - No clear metric for success (model = expensive guesswork)

# ===== Toolkit landscape =====
# scikit-learn: classical ML
# PyTorch / TensorFlow: deep learning
# XGBoost / LightGBM: gradient-boosted trees
# Hugging Face: pre-trained models + transformers
# MLflow / Weights and Biases: experiment tracking

# ===== Patterns to internalise =====
# - Baseline first: predict the mean / most common class
# - Stratify on classification splits
# - Cross-validate; never tune on test
# - Log everything (params, metrics, data version)

# ===== Pitfalls =====
# - Data leakage: features that wouldnt exist at prediction time
# - Overfitting to validation by trying many model versions
# - Accuracy on imbalanced data is misleading; use F1 / AUC
# - Shipping a model without a monitoring plan

# Machine learning: programs that improve from data.
# Most production ML is supervised: x → y from labelled examples.