Hands-On AI Projects

Building AI from first principles — from a NumPy neural network with hand-verified backprop,
all the way up to grounded RAG systems, tool-using agents, and a monitored production pipeline.

---

This is a curated index of 20 standalone projects that trace one path: understand the machinery well enough to build it from scratch, then learn to engineer it well enough to ship. Each project lives in its own repository — this page is the front door that ties them together and tells you where to start.

They are not tutorials-followed. Most start from a blank file: backpropagation is derived and checked against finite differences; a GPT's causal attention is written by hand and proven correct with a dedicated test; a fraud model's decision threshold is chosen by minimizing real dollars, not accuracy. The recurring theme across all 20 is engineering discipline — honest evaluation, no fabricated numbers, a real test suite, and green CI on every single one.

The arc

flowchart LR
    A["<b>Foundations</b><br/>build the primitives"] --> B["<b>Classical ML</b><br/>real data, honest metrics"]
    B --> C["<b>Deep Learning</b><br/>CNNs & transformers<br/>from scratch"]
    C --> D["<b>LLM Engineering</b><br/>extraction · eval · cost"]
    D --> E["<b>RAG Systems</b><br/>grounded, measurable<br/>retrieval"]
    E --> F["<b>Agents</b><br/>tool use &<br/>failure recovery"]
    F --> G["<b>Serving & MLOps</b><br/>ship it, then watch it"]

Loading

Start here (5-minute tour)

If you only look at three, look at these — they span the whole range from "I built it from scratch" to "I shipped it":

	Project	Why
🧠	neural-net-from-scratch	A multilayer perceptron with backpropagation written in pure NumPy — and proven correct by checking the analytical gradients against finite differences to 1e-6. 97.7% on MNIST, no framework.
🔎	rag-system	RAG you can actually measure: a labelled eval harness reporting recall@k, MRR, and hit@1, plus an honest before/after comparison of keyword vs. semantic retrieval.
🚀	model-service	An ML model shipped like a real service — FastAPI with CORS allowlisting, optional API-key auth, rate limiting, a hardened Docker image, and a React playground.

---

All projects

Grouped by the stage of the journey. 🖥️ marks projects that ship an interactive web UI. The badge on each shows its live CI status.

🔢 Foundations — build the primitives

Project	What it does
from-scratch-numpy	Linear regression (gradient descent) and a CART decision tree in pure NumPy, validated against scikit-learn, with hand-traced math notes and a ground-truth test suite.
neural-net-from-scratch	Hand-written NumPy MLP with full backpropagation for MNIST — gradient-checked against finite differences, fully seeded, reaching 97.7% test accuracy with no deep-learning framework.
data-cleaning-cli	Command-line CSV cleaning tool built on pandas: type coercion, missing-value strategies, deduplication, and a per-step cleaning report — a pure, fully tested core behind a thin CLI shell.
eda-penguins	Exploratory analysis of the Palmer Penguins dataset that surfaces a Simpson's-paradox reversal in bill dimensions — a storytelling notebook written for non-technical readers, rebuilt deterministically from code.

📊 Classical ML — real datasets, honest metrics

Project	What it does
housing-regression	California Housing price regression with leakage-safe sklearn pipelines, a dummy baseline, stratified splits, and a deep error analysis of censored targets and per-decile failure modes.
fraud-classification	Imbalanced fraud detection that picks its decision threshold by minimizing expected dollar cost — PR-AUC over accuracy, SMOTE inside the pipeline to prevent leakage, and an explicit business cost model.
text-classifier	20 Newsgroups topic classification built two ways — TF-IDF + logistic regression vs. fine-tuned DistilBERT — to measure the real cost/accuracy tradeoff, with the dataset's notorious leakage trap removed.

🧠 Deep Learning — from scratch, in PyTorch

Project	What it does
cifar-pytorch	CIFAR-10 image classification comparing a from-scratch CNN against ResNet-18 transfer learning, driven by one shared, model-agnostic PyTorch training engine for a fair head-to-head.
tiny-gpt 🖥️	Character-level GPT written from scratch in PyTorch — hand-rolled causal self-attention, pre-norm residual blocks, weight tying — trained on Shakespeare, with a FastAPI + React playground for live generation.

💬 LLM Engineering — extraction, evaluation, cost

Project	What it does
llm-extractor 🖥️	Provider-agnostic structured-data extraction with LLMs (Anthropic, OpenAI, Gemini): strict prompting, tolerant JSON parsing, Pydantic validation, and retry-with-feedback — plus a web playground.
llm-optimization	Deterministic benchmark showing how caching, model routing, batching, and streaming cut LLM cost and latency by ~75% with zero quality loss — reproducible without an API key.
eval-harness	Provider-agnostic evaluation and regression-testing harness for non-deterministic AI systems: labelled cases, heuristic and LLM-judge scorers, and case-by-case regression diffing between runs.
teaching-eval-harnesses	A short practical guide plus a 60-line dependency-free demo of evaluating LLM systems: labelled test set, scorers, aggregation, and a regression gate that catches a seeded bug.

🔎 RAG Systems — grounded and measurable

Project	What it does
rag-system 🖥️	A RAG pipeline you can actually measure: chunking, swappable TF-IDF/semantic embedders, a relevance gate, and a labelled eval harness reporting recall@k, MRR, and hit@1 — with a React retrieval explorer.
paper-rag 🖥️	Search across research papers with paper-and-page citations: a tested TF-IDF retrieval core shared by an offline CLI and a FastAPI + React web app.
nahjulbalagha-rag 🖥️	Citation-grounded Q&A that answers only from the source text — relevance gating with an honest decline mode, verbatim citations, and tests that assert the grounding guarantee itself.

🤖 Agents — tool use and recovery

Project	What it does
agent	ReAct-style tool-using agent with a stdlib-only core, built around failure recovery: every tool or LLM error becomes a recoverable observation, every loop is bounded, and offline tests cover the failure paths.

🚀 Serving & MLOps — ship it, then watch it

Project	What it does
model-service 🖥️	Sentiment classification as a deployable service: FastAPI with CORS allowlisting, optional API-key auth, per-client rate limiting, Pydantic validation, health checks, a hardened Docker image, and a React playground.
training-dashboard 🖥️	PyTorch experiment tracking done properly: TensorBoard logging of gradients, weights, and hyperparameters, a learning-rate ablation, and an optional FastAPI + React UI for launching and watching training live.
mlops-pipeline	Automated ML pipeline on GitHub Actions: data validation, training, a quality gate that blocks bad models, registry and deployment stages, plus PSI drift detection — with the registry persisted across runs.

---

What ties these together

Different domains, one set of standards. Across all 20 projects:

• Every project has an automated test suite that runs in CI — and every badge above is green.
• Honest evaluation. Metrics are chosen to fit the problem (PR-AUC under class imbalance, recall@k / MRR for retrieval, dollar-cost for fraud) and reported numbers are reproduced from real runs — never fabricated.
• Correctness is proven, not assumed. Hand-written backprop is gradient-checked; causal attention has a dedicated masking test; RAG grounding is asserted as a test invariant.
• Clean architecture. Pure, testable cores behind thin CLI/HTTP shells; provider-agnostic interfaces with deterministic mocks so LLM-facing code is testable offline.
• MIT-licensed and documented — each repo has its own README with a quickstart, architecture diagram, and honest limitations.

How to explore

Every project is self-contained. Open any repo and its README has a quickstart you can run in a minute or two. The 🖥️ projects ship a built web UI served by their own backend — start the server and open the page (see each repo's README for the exact command).

---

_{Maintained by @smafnan · each project is an independent repository; this is the index.}