{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "68a64fae",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| default_exp data.loader\n",
    "#| export"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3d0618b",
   "metadata": {
    "cell_marker": "\"\"\""
   },
   "source": [
    "# Module 08: DataLoader - Efficient Data Pipeline for ML Training\n",
    "\n",
    "Welcome to Module 08! You're about to build the data loading infrastructure that transforms how ML models consume data during training.\n",
    "\n",
    "## 🔗 Prerequisites & Progress\n",
    "**You've Built**: Tensor operations, activations, layers, losses, autograd, optimizers, and training loops\n",
    "**You'll Build**: Dataset abstraction, DataLoader with batching/shuffling, and real dataset support\n",
    "**You'll Enable**: Efficient data pipelines that feed hungry neural networks with properly formatted batches\n",
    "\n",
    "**Connection Map**:\n",
    "```\n",
    "Training Loop → DataLoader → Batched Data → Model\n",
    "(Module 07)    (Module 08)  (optimized)   (ready to learn)\n",
    "```\n",
    "\n",
    "## Learning Objectives\n",
    "By the end of this module, you will:\n",
    "1. Understand the data pipeline: individual samples → batches → training\n",
    "2. Implement Dataset abstraction and TensorDataset for tensor-based data\n",
    "3. Build DataLoader with intelligent batching, shuffling, and memory-efficient iteration\n",
    "4. Experience data pipeline performance characteristics firsthand\n",
    "5. Create download functions for real computer vision datasets\n",
    "\n",
    "Let's transform scattered data into organized learning batches!\n",
    "\n",
    "## 📦 Where This Code Lives in the Final Package\n",
    "\n",
    "**Learning Side:** You work in `modules/08_dataloader/dataloader_dev.py`  \n",
    "**Building Side:** Code exports to `tinytorch.data.loader`\n",
    "\n",
    "```python\n",
    "# How to use this module:\n",
    "from tinytorch.data.loader import Dataset, DataLoader, TensorDataset\n",
    "from tinytorch.data.loader import download_mnist, download_cifar10\n",
    "```\n",
    "\n",
    "**Why this matters:**\n",
    "- **Learning:** Complete data loading system in one focused module for deep understanding\n",
    "- **Production:** Proper organization like PyTorch's torch.utils.data with all core data utilities\n",
    "- **Efficiency:** Optimized data pipelines are crucial for training speed and memory usage\n",
    "- **Integration:** Works seamlessly with training loops to create complete ML systems"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "88086df7",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "# Essential imports for data loading\n",
    "import numpy as np\n",
    "import random\n",
    "from typing import Iterator, Tuple, List, Optional, Union\n",
    "from abc import ABC, abstractmethod\n",
    "\n",
    "# Import real Tensor class from tinytorch package\n",
    "from tinytorch.core.tensor import Tensor"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b43901bd",
   "metadata": {
    "cell_marker": "\"\"\"",
    "lines_to_next_cell": 1
   },
   "source": [
    "## Part 1: Understanding the Data Pipeline\n",
    "\n",
    "Before we implement anything, let's understand what happens when neural networks \"eat\" data. The journey from raw data to trained models follows a specific pipeline that every ML engineer must master.\n",
    "\n",
    "### The Data Pipeline Journey\n",
    "\n",
    "Imagine you have 50,000 images of cats and dogs, and you want to train a neural network to classify them:\n",
    "\n",
    "```\n",
    "Raw Data Storage          Dataset Interface         DataLoader Batching         Training Loop\n",
    "┌─────────────────┐      ┌──────────────────┐      ┌────────────────────┐      ┌─────────────┐\n",
    "│ cat_001.jpg     │      │ dataset[0]       │      │ Batch 1:           │      │ model(batch)│\n",
    "│ dog_023.jpg     │ ───> │ dataset[1]       │ ───> │ [cat, dog, cat]    │ ───> │ optimizer   │\n",
    "│ cat_045.jpg     │      │ dataset[2]       │      │ Batch 2:           │      │ loss        │\n",
    "│ ...             │      │ ...              │      │ [dog, cat, dog]    │      │ backward    │\n",
    "│ (50,000 files)  │      │ dataset[49999]   │      │ ...                │      │ step        │\n",
    "└─────────────────┘      └──────────────────┘      └────────────────────┘      └─────────────┘\n",
    "```\n",
    "\n",
    "### Why This Pipeline Matters\n",
    "\n",
    "**Individual Access (Dataset)**: Neural networks can't process 50,000 files at once. We need a way to access one sample at a time: \"Give me image #1,247\".\n",
    "\n",
    "**Batch Processing (DataLoader)**: GPUs are parallel machines - they're much faster processing 32 images simultaneously than 1 image 32 times.\n",
    "\n",
    "**Memory Efficiency**: Loading all 50,000 images into memory would require ~150GB. Instead, we load only the current batch (~150MB).\n",
    "\n",
    "**Training Variety**: Shuffling ensures the model sees different combinations each epoch, preventing memorization.\n",
    "\n",
    "### The Dataset Abstraction\n",
    "\n",
    "The Dataset class provides a uniform interface for accessing data, regardless of whether it's stored as files, in memory, in databases, or generated on-the-fly:\n",
    "\n",
    "```\n",
    "Dataset Interface\n",
    "┌─────────────────────────────────────┐\n",
    "│ __len__()     → \"How many samples?\" │\n",
    "│ __getitem__(i) → \"Give me sample i\" │\n",
    "└─────────────────────────────────────┘\n",
    "          ↑                ↑\n",
    "     Enables for     Enables indexing\n",
    "    loops/iteration   dataset[index]\n",
    "```\n",
    "\n",
    "**Connection to systems**: This abstraction is crucial because it separates *how data is stored* from *how it's accessed*, enabling optimizations like caching, prefetching, and parallel loading."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6d6abda4",
   "metadata": {
    "nbgrader": {
     "grade": false,
     "grade_id": "dataset-implementation",
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "#| export\n",
    "class Dataset(ABC):\n",
    "    \"\"\"\n",
    "    Abstract base class for all datasets.\n",
    "\n",
    "    Provides the fundamental interface that all datasets must implement:\n",
    "    - __len__(): Returns the total number of samples\n",
    "    - __getitem__(idx): Returns the sample at given index\n",
    "\n",
    "    TODO: Implement the abstract Dataset base class\n",
    "\n",
    "    APPROACH:\n",
    "    1. Use ABC (Abstract Base Class) to define interface\n",
    "    2. Mark methods as @abstractmethod to force implementation\n",
    "    3. Provide clear docstrings for subclasses\n",
    "\n",
    "    EXAMPLE:\n",
    "    >>> class MyDataset(Dataset):\n",
    "    ...     def __len__(self): return 100\n",
    "    ...     def __getitem__(self, idx): return idx\n",
    "    >>> dataset = MyDataset()\n",
    "    >>> print(len(dataset))  # 100\n",
    "    >>> print(dataset[42])   # 42\n",
    "\n",
    "    HINT: Abstract methods force subclasses to implement core functionality\n",
    "    \"\"\"\n",
    "\n",
    "    ### BEGIN SOLUTION\n",
    "    @abstractmethod\n",
    "    def __len__(self) -> int:\n",
    "        \"\"\"\n",
    "        Return the total number of samples in the dataset.\n",
    "\n",
    "        This method must be implemented by all subclasses to enable\n",
    "        len(dataset) calls and batch size calculations.\n",
    "        \"\"\"\n",
    "        pass\n",
    "\n",
    "    @abstractmethod\n",
    "    def __getitem__(self, idx: int):\n",
    "        \"\"\"\n",
    "        Return the sample at the given index.\n",
    "\n",
    "        Args:\n",
    "            idx: Index of the sample to retrieve (0 <= idx < len(dataset))\n",
    "\n",
    "        Returns:\n",
    "            The sample at index idx. Format depends on the dataset implementation.\n",
    "            Could be (data, label) tuple, single tensor, etc.\n",
    "        \"\"\"\n",
    "        pass\n",
    "    ### END SOLUTION"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dc6ce67d",
   "metadata": {
    "lines_to_next_cell": 2,
    "nbgrader": {
     "grade": true,
     "grade_id": "test-dataset",
     "locked": true,
     "points": 10
    }
   },
   "outputs": [],
   "source": [
    "def test_unit_dataset():\n",
    "    \"\"\"🔬 Test Dataset abstract base class.\"\"\"\n",
    "    print(\"🔬 Unit Test: Dataset Abstract Base Class...\")\n",
    "\n",
    "    # Test that Dataset is properly abstract\n",
    "    try:\n",
    "        dataset = Dataset()\n",
    "        assert False, \"Should not be able to instantiate abstract Dataset\"\n",
    "    except TypeError:\n",
    "        print(\"✅ Dataset is properly abstract\")\n",
    "\n",
    "    # Test concrete implementation\n",
    "    class TestDataset(Dataset):\n",
    "        def __init__(self, size):\n",
    "            self.size = size\n",
    "\n",
    "        def __len__(self):\n",
    "            return self.size\n",
    "\n",
    "        def __getitem__(self, idx):\n",
    "            return f\"item_{idx}\"\n",
    "\n",
    "    dataset = TestDataset(10)\n",
    "    assert len(dataset) == 10\n",
    "    assert dataset[0] == \"item_0\"\n",
    "    assert dataset[9] == \"item_9\"\n",
    "\n",
    "    print(\"✅ Dataset interface works correctly!\")\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    test_unit_dataset()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "71c543f0",
   "metadata": {
    "cell_marker": "\"\"\"",
    "lines_to_next_cell": 1
   },
   "source": [
    "## Part 2: TensorDataset - When Data Lives in Memory\n",
    "\n",
    "Now let's implement TensorDataset, the most common dataset type for when your data is already loaded into tensors. This is perfect for datasets like MNIST where you can fit everything in memory.\n",
    "\n",
    "### Understanding TensorDataset Structure\n",
    "\n",
    "TensorDataset takes multiple tensors and aligns them by their first dimension (the sample dimension):\n",
    "\n",
    "```\n",
    "Input Tensors (aligned by first dimension):\n",
    "  Features Tensor        Labels Tensor         Metadata Tensor\n",
    "  ┌─────────────────┐   ┌───────────────┐     ┌─────────────────┐\n",
    "  │ [1.2, 3.4, 5.6] │   │ 0 (cat)       │     │ \"image_001.jpg\" │ ← Sample 0\n",
    "  │ [2.1, 4.3, 6.5] │   │ 1 (dog)       │     │ \"image_002.jpg\" │ ← Sample 1\n",
    "  │ [3.0, 5.2, 7.4] │   │ 0 (cat)       │     │ \"image_003.jpg\" │ ← Sample 2\n",
    "  │ ...             │   │ ...           │     │ ...             │\n",
    "  └─────────────────┘   └───────────────┘     └─────────────────┘\n",
    "        (N, 3)               (N,)                   (N,)\n",
    "\n",
    "Dataset Access:\n",
    "  dataset[1] → (Tensor([2.1, 4.3, 6.5]), Tensor(1), \"image_002.jpg\")\n",
    "```\n",
    "\n",
    "### Why TensorDataset is Powerful\n",
    "\n",
    "**Memory Locality**: All data is pre-loaded and stored contiguously in memory, enabling fast access patterns.\n",
    "\n",
    "**Vectorized Operations**: Since everything is already tensors, no conversion overhead during training.\n",
    "\n",
    "**Supervised Learning Perfect**: Naturally handles (features, labels) pairs, plus any additional metadata.\n",
    "\n",
    "**Batch-Friendly**: When DataLoader needs a batch, it can slice multiple samples efficiently.\n",
    "\n",
    "### Real-World Usage Patterns\n",
    "\n",
    "```\n",
    "# Computer Vision\n",
    "images = Tensor(shape=(50000, 32, 32, 3))  # CIFAR-10 images\n",
    "labels = Tensor(shape=(50000,))            # Class labels 0-9\n",
    "dataset = TensorDataset(images, labels)\n",
    "\n",
    "# Natural Language Processing\n",
    "token_ids = Tensor(shape=(10000, 512))     # Tokenized sentences\n",
    "labels = Tensor(shape=(10000,))            # Sentiment labels\n",
    "dataset = TensorDataset(token_ids, labels)\n",
    "\n",
    "# Time Series\n",
    "sequences = Tensor(shape=(1000, 100, 5))   # 100 timesteps, 5 features\n",
    "targets = Tensor(shape=(1000, 10))         # 10-step ahead prediction\n",
    "dataset = TensorDataset(sequences, targets)\n",
    "```\n",
    "\n",
    "The key insight: TensorDataset transforms \"arrays of data\" into \"a dataset that serves samples\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7088cd2d",
   "metadata": {
    "nbgrader": {
     "grade": false,
     "grade_id": "tensordataset-implementation",
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "#| export\n",
    "class TensorDataset(Dataset):\n",
    "    \"\"\"\n",
    "    Dataset wrapping tensors for supervised learning.\n",
    "\n",
    "    Each sample is a tuple of tensors from the same index across all input tensors.\n",
    "    All tensors must have the same size in their first dimension.\n",
    "\n",
    "    TODO: Implement TensorDataset for tensor-based data\n",
    "\n",
    "    APPROACH:\n",
    "    1. Store all input tensors\n",
    "    2. Validate they have same first dimension (number of samples)\n",
    "    3. Return tuple of tensor slices for each index\n",
    "\n",
    "    EXAMPLE:\n",
    "    >>> features = Tensor([[1, 2], [3, 4], [5, 6]])  # 3 samples, 2 features each\n",
    "    >>> labels = Tensor([0, 1, 0])                    # 3 labels\n",
    "    >>> dataset = TensorDataset(features, labels)\n",
    "    >>> print(len(dataset))  # 3\n",
    "    >>> print(dataset[1])    # (Tensor([3, 4]), Tensor(1))\n",
    "\n",
    "    HINTS:\n",
    "    - Use *tensors to accept variable number of tensor arguments\n",
    "    - Check all tensors have same length in dimension 0\n",
    "    - Return tuple of tensor[idx] for all tensors\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, *tensors):\n",
    "        \"\"\"\n",
    "        Create dataset from multiple tensors.\n",
    "\n",
    "        Args:\n",
    "            *tensors: Variable number of Tensor objects\n",
    "\n",
    "        All tensors must have the same size in their first dimension.\n",
    "        \"\"\"\n",
    "        ### BEGIN SOLUTION\n",
    "        assert len(tensors) > 0, \"Must provide at least one tensor\"\n",
    "\n",
    "        # Store all tensors\n",
    "        self.tensors = tensors\n",
    "\n",
    "        # Validate all tensors have same first dimension\n",
    "        first_size = len(tensors[0].data)  # Size of first dimension\n",
    "        for i, tensor in enumerate(tensors):\n",
    "            if len(tensor.data) != first_size:\n",
    "                raise ValueError(\n",
    "                    f\"All tensors must have same size in first dimension. \"\n",
    "                    f\"Tensor 0: {first_size}, Tensor {i}: {len(tensor.data)}\"\n",
    "                )\n",
    "        ### END SOLUTION\n",
    "\n",
    "    def __len__(self) -> int:\n",
    "        \"\"\"Return number of samples (size of first dimension).\"\"\"\n",
    "        ### BEGIN SOLUTION\n",
    "        return len(self.tensors[0].data)\n",
    "        ### END SOLUTION\n",
    "\n",
    "    def __getitem__(self, idx: int) -> Tuple[Tensor, ...]:\n",
    "        \"\"\"\n",
    "        Return tuple of tensor slices at given index.\n",
    "\n",
    "        Args:\n",
    "            idx: Sample index\n",
    "\n",
    "        Returns:\n",
    "            Tuple containing tensor[idx] for each input tensor\n",
    "        \"\"\"\n",
    "        ### BEGIN SOLUTION\n",
    "        if idx >= len(self) or idx < 0:\n",
    "            raise IndexError(f\"Index {idx} out of range for dataset of size {len(self)}\")\n",
    "\n",
    "        # Return tuple of slices from all tensors\n",
    "        return tuple(Tensor(tensor.data[idx]) for tensor in self.tensors)\n",
    "        ### END SOLUTION"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "002e0d79",
   "metadata": {
    "lines_to_next_cell": 2,
    "nbgrader": {
     "grade": true,
     "grade_id": "test-tensordataset",
     "locked": true,
     "points": 15
    }
   },
   "outputs": [],
   "source": [
    "def test_unit_tensordataset():\n",
    "    \"\"\"🔬 Test TensorDataset implementation.\"\"\"\n",
    "    print(\"🔬 Unit Test: TensorDataset...\")\n",
    "\n",
    "    # Test basic functionality\n",
    "    features = Tensor([[1, 2], [3, 4], [5, 6]])  # 3 samples, 2 features\n",
    "    labels = Tensor([0, 1, 0])                   # 3 labels\n",
    "\n",
    "    dataset = TensorDataset(features, labels)\n",
    "\n",
    "    # Test length\n",
    "    assert len(dataset) == 3, f\"Expected length 3, got {len(dataset)}\"\n",
    "\n",
    "    # Test indexing\n",
    "    sample = dataset[0]\n",
    "    assert len(sample) == 2, \"Should return tuple with 2 tensors\"\n",
    "    assert np.array_equal(sample[0].data, [1, 2]), f\"Wrong features: {sample[0].data}\"\n",
    "    assert sample[1].data == 0, f\"Wrong label: {sample[1].data}\"\n",
    "\n",
    "    sample = dataset[1]\n",
    "    assert np.array_equal(sample[1].data, 1), f\"Wrong label at index 1: {sample[1].data}\"\n",
    "\n",
    "    # Test error handling\n",
    "    try:\n",
    "        dataset[10]  # Out of bounds\n",
    "        assert False, \"Should raise IndexError for out of bounds access\"\n",
    "    except IndexError:\n",
    "        pass\n",
    "\n",
    "    # Test mismatched tensor sizes\n",
    "    try:\n",
    "        bad_features = Tensor([[1, 2], [3, 4]])  # Only 2 samples\n",
    "        bad_labels = Tensor([0, 1, 0])           # 3 labels - mismatch!\n",
    "        TensorDataset(bad_features, bad_labels)\n",
    "        assert False, \"Should raise error for mismatched tensor sizes\"\n",
    "    except ValueError:\n",
    "        pass\n",
    "\n",
    "    print(\"✅ TensorDataset works correctly!\")\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    test_unit_tensordataset()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4a52948",
   "metadata": {
    "cell_marker": "\"\"\"",
    "lines_to_next_cell": 1
   },
   "source": [
    "## Part 3: DataLoader - The Batch Factory\n",
    "\n",
    "Now we build the DataLoader, the component that transforms individual dataset samples into the batches that neural networks crave. This is where data loading becomes a systems challenge.\n",
    "\n",
    "### Understanding Batching: From Samples to Tensors\n",
    "\n",
    "DataLoader performs a crucial transformation - it collects individual samples and stacks them into batch tensors:\n",
    "\n",
    "```\n",
    "Step 1: Individual Samples from Dataset\n",
    "  dataset[0] → (features: [1, 2, 3], label: 0)\n",
    "  dataset[1] → (features: [4, 5, 6], label: 1)\n",
    "  dataset[2] → (features: [7, 8, 9], label: 0)\n",
    "  dataset[3] → (features: [2, 3, 4], label: 1)\n",
    "\n",
    "Step 2: DataLoader Groups into Batch (batch_size=2)\n",
    "  Batch 1:\n",
    "    features: [[1, 2, 3],    ← Stacked into shape (2, 3)\n",
    "               [4, 5, 6]]\n",
    "    labels:   [0, 1]         ← Stacked into shape (2,)\n",
    "\n",
    "  Batch 2:\n",
    "    features: [[7, 8, 9],    ← Stacked into shape (2, 3)\n",
    "               [2, 3, 4]]\n",
    "    labels:   [0, 1]         ← Stacked into shape (2,)\n",
    "```\n",
    "\n",
    "### The Shuffling Process\n",
    "\n",
    "Shuffling randomizes which samples appear in which batches, crucial for good training:\n",
    "\n",
    "```\n",
    "Without Shuffling (epoch 1):          With Shuffling (epoch 1):\n",
    "  Batch 1: [sample 0, sample 1]         Batch 1: [sample 2, sample 0]\n",
    "  Batch 2: [sample 2, sample 3]         Batch 2: [sample 3, sample 1]\n",
    "  Batch 3: [sample 4, sample 5]         Batch 3: [sample 5, sample 4]\n",
    "\n",
    "Without Shuffling (epoch 2):          With Shuffling (epoch 2):\n",
    "  Batch 1: [sample 0, sample 1]  ✗      Batch 1: [sample 1, sample 4]  ✓\n",
    "  Batch 2: [sample 2, sample 3]  ✗      Batch 2: [sample 0, sample 5]  ✓\n",
    "  Batch 3: [sample 4, sample 5]  ✗      Batch 3: [sample 2, sample 3]  ✓\n",
    "\n",
    "  (Same every epoch = overfitting!)     (Different combinations = better learning!)\n",
    "```\n",
    "\n",
    "### DataLoader as a Systems Component\n",
    "\n",
    "**Memory Management**: DataLoader only holds one batch in memory at a time, not the entire dataset.\n",
    "\n",
    "**Iteration Interface**: Provides Python iterator protocol so training loops can use `for batch in dataloader:`.\n",
    "\n",
    "**Collation Strategy**: Automatically stacks tensors from individual samples into batch tensors.\n",
    "\n",
    "**Performance Critical**: This is often the bottleneck in training pipelines - loading and preparing data can be slower than the forward pass!\n",
    "\n",
    "### The DataLoader Algorithm\n",
    "\n",
    "```\n",
    "1. Create indices list: [0, 1, 2, ..., dataset_length-1]\n",
    "2. If shuffle=True: randomly shuffle the indices\n",
    "3. Group indices into chunks of batch_size\n",
    "4. For each chunk:\n",
    "   a. Retrieve samples: [dataset[i] for i in chunk]\n",
    "   b. Collate samples: stack individual tensors into batch tensors\n",
    "   c. Yield the batch tensor tuple\n",
    "```\n",
    "\n",
    "This transforms the dataset from \"access one sample\" to \"iterate through batches\" - exactly what training loops need."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "94032b16",
   "metadata": {
    "nbgrader": {
     "grade": false,
     "grade_id": "dataloader-implementation",
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "#| export\n",
    "class DataLoader:\n",
    "    \"\"\"\n",
    "    Data loader with batching and shuffling support.\n",
    "\n",
    "    Wraps a dataset to provide batched iteration with optional shuffling.\n",
    "    Essential for efficient training with mini-batch gradient descent.\n",
    "\n",
    "    TODO: Implement DataLoader with batching and shuffling\n",
    "\n",
    "    APPROACH:\n",
    "    1. Store dataset, batch_size, and shuffle settings\n",
    "    2. Create iterator that groups samples into batches\n",
    "    3. Handle shuffling by randomizing indices\n",
    "    4. Collate individual samples into batch tensors\n",
    "\n",
    "    EXAMPLE:\n",
    "    >>> dataset = TensorDataset(Tensor([[1,2], [3,4], [5,6]]), Tensor([0,1,0]))\n",
    "    >>> loader = DataLoader(dataset, batch_size=2, shuffle=True)\n",
    "    >>> for batch in loader:\n",
    "    ...     features_batch, labels_batch = batch\n",
    "    ...     print(f\"Features: {features_batch.shape}, Labels: {labels_batch.shape}\")\n",
    "\n",
    "    HINTS:\n",
    "    - Use random.shuffle() for index shuffling\n",
    "    - Group consecutive samples into batches\n",
    "    - Stack individual tensors using np.stack()\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, dataset: Dataset, batch_size: int, shuffle: bool = False):\n",
    "        \"\"\"\n",
    "        Create DataLoader for batched iteration.\n",
    "\n",
    "        Args:\n",
    "            dataset: Dataset to load from\n",
    "            batch_size: Number of samples per batch\n",
    "            shuffle: Whether to shuffle data each epoch\n",
    "        \"\"\"\n",
    "        ### BEGIN SOLUTION\n",
    "        self.dataset = dataset\n",
    "        self.batch_size = batch_size\n",
    "        self.shuffle = shuffle\n",
    "        ### END SOLUTION\n",
    "\n",
    "    def __len__(self) -> int:\n",
    "        \"\"\"Return number of batches per epoch.\"\"\"\n",
    "        ### BEGIN SOLUTION\n",
    "        # Calculate number of complete batches\n",
    "        return (len(self.dataset) + self.batch_size - 1) // self.batch_size\n",
    "        ### END SOLUTION\n",
    "\n",
    "    def __iter__(self) -> Iterator:\n",
    "        \"\"\"Return iterator over batches.\"\"\"\n",
    "        ### BEGIN SOLUTION\n",
    "        # Create list of indices\n",
    "        indices = list(range(len(self.dataset)))\n",
    "\n",
    "        # Shuffle if requested\n",
    "        if self.shuffle:\n",
    "            random.shuffle(indices)\n",
    "\n",
    "        # Yield batches\n",
    "        for i in range(0, len(indices), self.batch_size):\n",
    "            batch_indices = indices[i:i + self.batch_size]\n",
    "            batch = [self.dataset[idx] for idx in batch_indices]\n",
    "\n",
    "            # Collate batch - convert list of tuples to tuple of tensors\n",
    "            yield self._collate_batch(batch)\n",
    "        ### END SOLUTION\n",
    "\n",
    "    def _collate_batch(self, batch: List[Tuple[Tensor, ...]]) -> Tuple[Tensor, ...]:\n",
    "        \"\"\"\n",
    "        Collate individual samples into batch tensors.\n",
    "\n",
    "        Args:\n",
    "            batch: List of sample tuples from dataset\n",
    "\n",
    "        Returns:\n",
    "            Tuple of batched tensors\n",
    "        \"\"\"\n",
    "        ### BEGIN SOLUTION\n",
    "        if len(batch) == 0:\n",
    "            return ()\n",
    "\n",
    "        # Determine number of tensors per sample\n",
    "        num_tensors = len(batch[0])\n",
    "\n",
    "        # Group tensors by position\n",
    "        batched_tensors = []\n",
    "        for tensor_idx in range(num_tensors):\n",
    "            # Extract all tensors at this position\n",
    "            tensor_list = [sample[tensor_idx].data for sample in batch]\n",
    "\n",
    "            # Stack into batch tensor\n",
    "            batched_data = np.stack(tensor_list, axis=0)\n",
    "            batched_tensors.append(Tensor(batched_data))\n",
    "\n",
    "        return tuple(batched_tensors)\n",
    "        ### END SOLUTION"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7fcd3543",
   "metadata": {
    "lines_to_next_cell": 2,
    "nbgrader": {
     "grade": true,
     "grade_id": "test-dataloader",
     "locked": true,
     "points": 20
    }
   },
   "outputs": [],
   "source": [
    "def test_unit_dataloader():\n",
    "    \"\"\"🔬 Test DataLoader implementation.\"\"\"\n",
    "    print(\"🔬 Unit Test: DataLoader...\")\n",
    "\n",
    "    # Create test dataset\n",
    "    features = Tensor([[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]])  # 5 samples\n",
    "    labels = Tensor([0, 1, 0, 1, 0])\n",
    "    dataset = TensorDataset(features, labels)\n",
    "\n",
    "    # Test basic batching (no shuffle)\n",
    "    loader = DataLoader(dataset, batch_size=2, shuffle=False)\n",
    "\n",
    "    # Test length calculation\n",
    "    assert len(loader) == 3, f\"Expected 3 batches, got {len(loader)}\"  # ceil(5/2) = 3\n",
    "\n",
    "    batches = list(loader)\n",
    "    assert len(batches) == 3, f\"Expected 3 batches, got {len(batches)}\"\n",
    "\n",
    "    # Test first batch\n",
    "    batch_features, batch_labels = batches[0]\n",
    "    assert batch_features.data.shape == (2, 2), f\"Wrong batch features shape: {batch_features.data.shape}\"\n",
    "    assert batch_labels.data.shape == (2,), f\"Wrong batch labels shape: {batch_labels.data.shape}\"\n",
    "\n",
    "    # Test last batch (should have 1 sample)\n",
    "    batch_features, batch_labels = batches[2]\n",
    "    assert batch_features.data.shape == (1, 2), f\"Wrong last batch features shape: {batch_features.data.shape}\"\n",
    "    assert batch_labels.data.shape == (1,), f\"Wrong last batch labels shape: {batch_labels.data.shape}\"\n",
    "\n",
    "    # Test that data is preserved\n",
    "    assert np.array_equal(batches[0][0].data[0], [1, 2]), \"First sample should be [1,2]\"\n",
    "    assert batches[0][1].data[0] == 0, \"First label should be 0\"\n",
    "\n",
    "    # Test shuffling produces different order\n",
    "    loader_shuffle = DataLoader(dataset, batch_size=5, shuffle=True)\n",
    "    loader_no_shuffle = DataLoader(dataset, batch_size=5, shuffle=False)\n",
    "\n",
    "    batch_shuffle = list(loader_shuffle)[0]\n",
    "    batch_no_shuffle = list(loader_no_shuffle)[0]\n",
    "\n",
    "    # Note: This might occasionally fail due to random chance, but very unlikely\n",
    "    # We'll just test that both contain all the original data\n",
    "    shuffle_features = set(tuple(row) for row in batch_shuffle[0].data)\n",
    "    no_shuffle_features = set(tuple(row) for row in batch_no_shuffle[0].data)\n",
    "    expected_features = {(1, 2), (3, 4), (5, 6), (7, 8), (9, 10)}\n",
    "\n",
    "    assert shuffle_features == expected_features, \"Shuffle should preserve all data\"\n",
    "    assert no_shuffle_features == expected_features, \"No shuffle should preserve all data\"\n",
    "\n",
    "    print(\"✅ DataLoader works correctly!\")\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    test_unit_dataloader()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ab0b6005",
   "metadata": {
    "cell_marker": "\"\"\"",
    "lines_to_next_cell": 2
   },
   "source": [
    "## Part 4: Working with Real Datasets\n",
    "\n",
    "Now that you've built the DataLoader abstraction, you're ready to use it with real data!\n",
    "\n",
    "### Using Real Datasets: The TinyTorch Approach\n",
    "\n",
    "TinyTorch separates **mechanics** (this module) from **application** (examples/milestones):\n",
    "\n",
    "```\n",
    "Module 08 (DataLoader)          Examples & Milestones\n",
    "┌──────────────────────┐       ┌────────────────────────┐\n",
    "│ Dataset abstraction  │       │ Real MNIST digits      │\n",
    "│ TensorDataset impl   │  ───> │ CIFAR-10 images        │\n",
    "│ DataLoader batching  │       │ Custom datasets        │\n",
    "│ Shuffle & iteration  │       │ Download utilities     │\n",
    "└──────────────────────┘       └────────────────────────┘\n",
    "   (Learn mechanics)              (Apply to real data)\n",
    "```\n",
    "\n",
    "### Understanding Image Data\n",
    "\n",
    "**What does image data actually look like?**\n",
    "\n",
    "Images are just 2D arrays of numbers (pixels). Here are actual 8×8 handwritten digits:\n",
    "\n",
    "```\n",
    "Digit \"5\" (8×8):        Digit \"3\" (8×8):        Digit \"8\" (8×8):\n",
    " 0  0 12 13  5  0  0  0   0  0 11 12  0  0  0  0   0  0 10 14  8  1  0  0\n",
    " 0  0 13 15 10  0  0  0   0  2 16 16 16  7  0  0   0  0 16 15 15  9  0  0\n",
    " 0  3 15 13 16  7  0  0   0  0  8 16  8  0  0  0   0  0 15  5  5 13  0  0\n",
    " 0  8 13  6 15  4  0  0   0  0  0 12 13  0  0  0   0  1 16  5  5 13  0  0\n",
    " 0  0  0  6 16  5  0  0   0  0  1 16 15  9  0  0   0  6 16 16 16 16  1  0\n",
    " 0  0  5 15 16  9  0  0   0  0 14 16 16 16  7  0   1 16  3  1  1 15  1  0\n",
    " 0  0  9 16  9  0  0  0   0  5 16  8  8 16  0  0   0  9 16 16 16 15  0  0\n",
    " 0  0  0  0  0  0  0  0   0  3 16 16 16 12  0  0   0  0  0  0  0  0  0  0\n",
    "\n",
    "Visual representation:           \n",
    "░█████░          ░█████░          ░█████░\n",
    "░█░░░█░          ░░░░░█░          █░░░░█░\n",
    "░░░░█░░          ░░███░░          ░█████░\n",
    "░░░█░░░          ░░░░█░░          █░░░░█░\n",
    "░░█░░░░          ░█████░          ░█████░\n",
    "```\n",
    "\n",
    "**Shape transformations in DataLoader:**\n",
    "\n",
    "```\n",
    "Individual Sample (from Dataset):\n",
    "  image: (8, 8)      ← Single 8×8 image\n",
    "  label: scalar      ← Single digit (0-9)\n",
    "\n",
    "After DataLoader batching (batch_size=32):\n",
    "  images: (32, 8, 8)  ← Stack of 32 images\n",
    "  labels: (32,)       ← Array of 32 labels\n",
    "  \n",
    "This is what your model sees during training!\n",
    "```\n",
    "\n",
    "### Quick Start with Real Data\n",
    "\n",
    "**Tiny Datasets (ships with TinyTorch):**\n",
    "```python\n",
    "# 8×8 handwritten digits - instant, no downloads!\n",
    "import numpy as np\n",
    "data = np.load('datasets/tiny/digits_8x8.npz')\n",
    "images = Tensor(data['images'])  # (1797, 8, 8)\n",
    "labels = Tensor(data['labels'])  # (1797,)\n",
    "\n",
    "dataset = TensorDataset(images, labels)\n",
    "loader = DataLoader(dataset, batch_size=32, shuffle=True)\n",
    "\n",
    "# Each batch contains real digit images!\n",
    "for batch_images, batch_labels in loader:\n",
    "    # batch_images: (32, 8, 8) - 32 digit images\n",
    "    # batch_labels: (32,) - their labels (0-9)\n",
    "    break\n",
    "```\n",
    "\n",
    "**Full Datasets (for serious training):**\n",
    "```python\n",
    "# See milestones/03_mlp_revival_1986/ for MNIST download (28×28 images)\n",
    "# See milestones/04_cnn_revolution_1998/ for CIFAR-10 download (32×32×3 images)\n",
    "```\n",
    "\n",
    "### What You've Accomplished\n",
    "\n",
    "You've built the **data loading infrastructure** that powers all modern ML:\n",
    "- ✅ Dataset abstraction (universal interface)\n",
    "- ✅ TensorDataset (in-memory efficiency)\n",
    "- ✅ DataLoader (batching, shuffling, iteration)\n",
    "\n",
    "**Next steps:** Apply your DataLoader to real datasets in the milestones!\n",
    "\n",
    "**Real-world connection:** You've implemented the same patterns as:\n",
    "- PyTorch's `torch.utils.data.DataLoader`\n",
    "- TensorFlow's `tf.data.Dataset`\n",
    "- Production ML pipelines everywhere"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a9a8d990",
   "metadata": {
    "cell_marker": "\"\"\"",
    "lines_to_next_cell": 1
   },
   "source": [
    "## Part 5: Systems Analysis - Data Pipeline Performance\n",
    "\n",
    "**Note:** This section provides performance analysis tools for understanding DataLoader behavior. The analysis functions are defined below but not run automatically. To explore performance characteristics, uncomment and run `analyze_dataloader_performance()` or `analyze_memory_usage()` manually.\n",
    "\n",
    "Now let's understand data pipeline performance like production ML engineers. Understanding where time and memory go is crucial for building systems that scale.\n",
    "\n",
    "### The Performance Question: Where Does Time Go?\n",
    "\n",
    "In a typical training step, time is split between data loading and computation:\n",
    "\n",
    "```\n",
    "Training Step Breakdown:\n",
    "┌───────────────────────────────────────────────────────────────┐\n",
    "│ Data Loading        │ Forward Pass     │ Backward Pass     │\n",
    "│ ████████████         │ ███████         │ ████████         │\n",
    "│ 40ms               │ 25ms            │ 35ms              │\n",
    "└───────────────────────────────────────────────────────────────┘\n",
    "              100ms total per step\n",
    "\n",
    "Bottleneck Analysis:\n",
    "- If data loading > forward+backward: \"Data starved\" (CPU bottleneck)\n",
    "- If forward+backward > data loading: \"Compute bound\" (GPU bottleneck)\n",
    "- Ideal: Data loading ≈ computation time (balanced pipeline)\n",
    "```\n",
    "\n",
    "### Memory Scaling: The Batch Size Trade-off\n",
    "\n",
    "Batch size creates a fundamental trade-off in memory vs efficiency:\n",
    "\n",
    "```\n",
    "Batch Size Impact:\n",
    "\n",
    "Small Batches (batch_size=8):\n",
    "┌─────────────────────────────────────────┐\n",
    "│ Memory: 8 × 28 × 28 × 4 bytes = 25KB   │ ← Low memory\n",
    "│ Overhead: High (many small batches)    │ ← High overhead\n",
    "│ GPU Util: Poor (underutilized)         │ ← Poor efficiency\n",
    "└─────────────────────────────────────────┘\n",
    "\n",
    "Large Batches (batch_size=512):\n",
    "┌─────────────────────────────────────────┐\n",
    "│ Memory: 512 × 28 × 28 × 4 bytes = 1.6MB│ ← Higher memory\n",
    "│ Overhead: Low (fewer large batches)    │ ← Lower overhead\n",
    "│ GPU Util: Good (well utilized)         │ ← Better efficiency\n",
    "└─────────────────────────────────────────┘\n",
    "```\n",
    "\n",
    "### Shuffling Overhead Analysis\n",
    "\n",
    "Shuffling seems simple, but let's measure its real cost:\n",
    "\n",
    "```\n",
    "Shuffle Operation Breakdown:\n",
    "\n",
    "1. Index Generation:    O(n) - create [0, 1, 2, ..., n-1]\n",
    "2. Shuffle Operation:   O(n) - randomize the indices\n",
    "3. Sample Access:       O(1) per sample - dataset[shuffled_idx]\n",
    "\n",
    "Memory Impact:\n",
    "- No Shuffle: 0 extra memory (sequential access)\n",
    "- With Shuffle: 8 bytes × dataset_size (store indices)\n",
    "\n",
    "For 50,000 samples: 8 × 50,000 = 400KB extra memory\n",
    "```\n",
    "\n",
    "The key insight: shuffling overhead is typically negligible compared to the actual data loading and tensor operations.\n",
    "\n",
    "### Pipeline Bottleneck Identification\n",
    "\n",
    "We'll measure three critical metrics:\n",
    "\n",
    "1. **Throughput**: Samples processed per second\n",
    "2. **Memory Usage**: Peak memory during batch loading\n",
    "3. **Overhead**: Time spent on data vs computation\n",
    "\n",
    "These measurements will reveal whether our pipeline is CPU-bound (slow data loading) or compute-bound (slow model)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "226b8599",
   "metadata": {
    "nbgrader": {
     "grade": false,
     "grade_id": "systems-analysis",
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "def analyze_dataloader_performance():\n",
    "    \"\"\"📊 Analyze DataLoader performance characteristics.\"\"\"\n",
    "    print(\"📊 Analyzing DataLoader Performance...\")\n",
    "\n",
    "    import time\n",
    "\n",
    "    # Create test dataset of varying sizes\n",
    "    sizes = [1000, 5000, 10000]\n",
    "    batch_sizes = [16, 64, 256]\n",
    "\n",
    "    print(\"\\n🔍 Batch Size vs Loading Time:\")\n",
    "\n",
    "    for size in sizes:\n",
    "        # Create synthetic dataset\n",
    "        features = Tensor(np.random.randn(size, 100))  # 100 features\n",
    "        labels = Tensor(np.random.randint(0, 10, size))\n",
    "        dataset = TensorDataset(features, labels)\n",
    "\n",
    "        print(f\"\\nDataset size: {size} samples\")\n",
    "\n",
    "        for batch_size in batch_sizes:\n",
    "            # Time data loading\n",
    "            loader = DataLoader(dataset, batch_size=batch_size, shuffle=False)\n",
    "\n",
    "            start_time = time.time()\n",
    "            batch_count = 0\n",
    "            for batch in loader:\n",
    "                batch_count += 1\n",
    "            end_time = time.time()\n",
    "\n",
    "            elapsed = end_time - start_time\n",
    "            throughput = size / elapsed if elapsed > 0 else float('inf')\n",
    "\n",
    "            print(f\"  Batch size {batch_size:3d}: {elapsed:.3f}s ({throughput:,.0f} samples/sec)\")\n",
    "\n",
    "    # Analyze shuffle overhead\n",
    "    print(\"\\n🔄 Shuffle Overhead Analysis:\")\n",
    "\n",
    "    dataset_size = 10000\n",
    "    features = Tensor(np.random.randn(dataset_size, 50))\n",
    "    labels = Tensor(np.random.randint(0, 5, dataset_size))\n",
    "    dataset = TensorDataset(features, labels)\n",
    "\n",
    "    batch_size = 64\n",
    "\n",
    "    # No shuffle\n",
    "    loader_no_shuffle = DataLoader(dataset, batch_size=batch_size, shuffle=False)\n",
    "    start_time = time.time()\n",
    "    batches_no_shuffle = list(loader_no_shuffle)\n",
    "    time_no_shuffle = time.time() - start_time\n",
    "\n",
    "    # With shuffle\n",
    "    loader_shuffle = DataLoader(dataset, batch_size=batch_size, shuffle=True)\n",
    "    start_time = time.time()\n",
    "    batches_shuffle = list(loader_shuffle)\n",
    "    time_shuffle = time.time() - start_time\n",
    "\n",
    "    shuffle_overhead = ((time_shuffle - time_no_shuffle) / time_no_shuffle) * 100\n",
    "\n",
    "    print(f\"  No shuffle: {time_no_shuffle:.3f}s\")\n",
    "    print(f\"  With shuffle: {time_shuffle:.3f}s\")\n",
    "    print(f\"  Shuffle overhead: {shuffle_overhead:.1f}%\")\n",
    "\n",
    "    print(\"\\n💡 Key Insights:\")\n",
    "    print(\"• Larger batch sizes reduce per-sample overhead\")\n",
    "    print(\"• Shuffle adds minimal overhead for reasonable dataset sizes\")\n",
    "    print(\"• Memory usage scales linearly with batch size\")\n",
    "    print(\"🚀 Production tip: Balance batch size with GPU memory limits\")\n",
    "\n",
    "# analyze_dataloader_performance()  # Optional: Run manually for performance insights\n",
    "\n",
    "\n",
    "def analyze_memory_usage():\n",
    "    \"\"\"📊 Analyze memory usage patterns in data loading.\"\"\"\n",
    "    print(\"\\n📊 Analyzing Memory Usage Patterns...\")\n",
    "\n",
    "    # Memory usage estimation\n",
    "    def estimate_memory_mb(batch_size, feature_size, dtype_bytes=4):\n",
    "        \"\"\"Estimate memory usage for a batch.\"\"\"\n",
    "        return (batch_size * feature_size * dtype_bytes) / (1024 * 1024)\n",
    "\n",
    "    print(\"\\n💾 Memory Usage by Batch Configuration:\")\n",
    "\n",
    "    feature_sizes = [784, 3072, 50176]  # MNIST, CIFAR-10, ImageNet-like\n",
    "    feature_names = [\"MNIST (28×28)\", \"CIFAR-10 (32×32×3)\", \"ImageNet (224×224×1)\"]\n",
    "    batch_sizes = [1, 32, 128, 512]\n",
    "\n",
    "    for feature_size, name in zip(feature_sizes, feature_names):\n",
    "        print(f\"\\n{name}:\")\n",
    "        for batch_size in batch_sizes:\n",
    "            memory_mb = estimate_memory_mb(batch_size, feature_size)\n",
    "            print(f\"  Batch {batch_size:3d}: {memory_mb:6.1f} MB\")\n",
    "\n",
    "    print(\"\\n🎯 Memory Trade-offs:\")\n",
    "    print(\"• Larger batches: More memory, better GPU utilization\")\n",
    "    print(\"• Smaller batches: Less memory, more noisy gradients\")\n",
    "    print(\"• Sweet spot: Usually 32-128 depending on model size\")\n",
    "\n",
    "    # Demonstrate actual memory usage with our tensors\n",
    "    print(\"\\n🔬 Actual Tensor Memory Usage:\")\n",
    "\n",
    "    # Create different sized tensors\n",
    "    tensor_small = Tensor(np.random.randn(32, 784))    # Small batch\n",
    "    tensor_large = Tensor(np.random.randn(512, 784))   # Large batch\n",
    "\n",
    "    # Size in bytes (roughly)\n",
    "    small_bytes = tensor_small.data.nbytes\n",
    "    large_bytes = tensor_large.data.nbytes\n",
    "\n",
    "    print(f\"  Small batch (32×784): {small_bytes / 1024:.1f} KB\")\n",
    "    print(f\"  Large batch (512×784): {large_bytes / 1024:.1f} KB\")\n",
    "    print(f\"  Ratio: {large_bytes / small_bytes:.1f}×\")\n",
    "\n",
    "# analyze_memory_usage()  # Optional: Run manually for memory insights"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "251fd2d2",
   "metadata": {
    "cell_marker": "\"\"\"",
    "lines_to_next_cell": 1
   },
   "source": [
    "## Part 6: Integration Testing\n",
    "\n",
    "Let's test how our DataLoader integrates with a complete training workflow, simulating real ML pipeline usage."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "57ca5aa7",
   "metadata": {
    "nbgrader": {
     "grade": false,
     "grade_id": "integration-test",
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "def test_training_integration():\n",
    "    \"\"\"🔬 Test DataLoader integration with training workflow.\"\"\"\n",
    "    print(\"🔬 Integration Test: Training Workflow...\")\n",
    "\n",
    "    # Create a realistic dataset\n",
    "    num_samples = 1000\n",
    "    num_features = 20\n",
    "    num_classes = 5\n",
    "\n",
    "    # Synthetic classification data\n",
    "    features = Tensor(np.random.randn(num_samples, num_features))\n",
    "    labels = Tensor(np.random.randint(0, num_classes, num_samples))\n",
    "\n",
    "    dataset = TensorDataset(features, labels)\n",
    "\n",
    "    # Create train/val splits\n",
    "    train_size = int(0.8 * len(dataset))\n",
    "    val_size = len(dataset) - train_size\n",
    "\n",
    "    # Manual split (in production, you'd use proper splitting utilities)\n",
    "    train_indices = list(range(train_size))\n",
    "    val_indices = list(range(train_size, len(dataset)))\n",
    "\n",
    "    # Create subset datasets\n",
    "    train_samples = [dataset[i] for i in train_indices]\n",
    "    val_samples = [dataset[i] for i in val_indices]\n",
    "\n",
    "    # Convert back to tensors for TensorDataset\n",
    "    train_features = Tensor(np.stack([sample[0].data for sample in train_samples]))\n",
    "    train_labels = Tensor(np.stack([sample[1].data for sample in train_samples]))\n",
    "    val_features = Tensor(np.stack([sample[0].data for sample in val_samples]))\n",
    "    val_labels = Tensor(np.stack([sample[1].data for sample in val_samples]))\n",
    "\n",
    "    train_dataset = TensorDataset(train_features, train_labels)\n",
    "    val_dataset = TensorDataset(val_features, val_labels)\n",
    "\n",
    "    # Create DataLoaders\n",
    "    batch_size = 32\n",
    "    train_loader = DataLoader(train_dataset, batch_size=batch_size, shuffle=True)\n",
    "    val_loader = DataLoader(val_dataset, batch_size=batch_size, shuffle=False)\n",
    "\n",
    "    print(f\"📊 Dataset splits:\")\n",
    "    print(f\"  Training: {len(train_dataset)} samples, {len(train_loader)} batches\")\n",
    "    print(f\"  Validation: {len(val_dataset)} samples, {len(val_loader)} batches\")\n",
    "\n",
    "    # Simulate training loop\n",
    "    print(\"\\n🏃 Simulated Training Loop:\")\n",
    "\n",
    "    epoch_samples = 0\n",
    "    batch_count = 0\n",
    "\n",
    "    for batch_idx, (batch_features, batch_labels) in enumerate(train_loader):\n",
    "        batch_count += 1\n",
    "        epoch_samples += len(batch_features.data)\n",
    "\n",
    "        # Simulate forward pass (just check shapes)\n",
    "        assert batch_features.data.shape[0] <= batch_size, \"Batch size exceeded\"\n",
    "        assert batch_features.data.shape[1] == num_features, \"Wrong feature count\"\n",
    "        assert len(batch_labels.data) == len(batch_features.data), \"Mismatched batch sizes\"\n",
    "\n",
    "        if batch_idx < 3:  # Show first few batches\n",
    "            print(f\"  Batch {batch_idx + 1}: {batch_features.data.shape[0]} samples\")\n",
    "\n",
    "    print(f\"  Total: {batch_count} batches, {epoch_samples} samples processed\")\n",
    "\n",
    "    # Validate that all samples were seen\n",
    "    assert epoch_samples == len(train_dataset), f\"Expected {len(train_dataset)}, processed {epoch_samples}\"\n",
    "\n",
    "    print(\"✅ Training integration works correctly!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e99790e7",
   "metadata": {
    "cell_marker": "\"\"\"",
    "lines_to_next_cell": 1
   },
   "source": [
    "## 🧪 Module Integration Test\n",
    "\n",
    "Final validation that everything works together correctly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f22af370",
   "metadata": {
    "lines_to_next_cell": 1
   },
   "outputs": [],
   "source": [
    "def test_module():\n",
    "    \"\"\"\n",
    "    Comprehensive test of entire module functionality.\n",
    "\n",
    "    This final test runs before module summary to ensure:\n",
    "    - All unit tests pass\n",
    "    - Functions work together correctly\n",
    "    - Module is ready for integration with TinyTorch\n",
    "    \"\"\"\n",
    "    print(\"🧪 RUNNING MODULE INTEGRATION TEST\")\n",
    "    print(\"=\" * 50)\n",
    "\n",
    "    # Run all unit tests\n",
    "    print(\"Running unit tests...\")\n",
    "    test_unit_dataset()\n",
    "    test_unit_tensordataset()\n",
    "    test_unit_dataloader()\n",
    "\n",
    "    print(\"\\nRunning integration scenarios...\")\n",
    "\n",
    "    # Test complete workflow\n",
    "    test_training_integration()\n",
    "\n",
    "    print(\"\\n\" + \"=\" * 50)\n",
    "    print(\"🎉 ALL TESTS PASSED! Module ready for export.\")\n",
    "    print(\"Run: tito module complete 08\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5a49ad00",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Run comprehensive module test\n",
    "if __name__ == \"__main__\":\n",
    "    test_module()\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91161fcc",
   "metadata": {
    "cell_marker": "\"\"\""
   },
   "source": [
    "## 🎯 MODULE SUMMARY: DataLoader\n",
    "\n",
    "Congratulations! You've built a complete data loading pipeline for ML training!\n",
    "\n",
    "### Key Accomplishments\n",
    "- Built Dataset abstraction and TensorDataset implementation with proper tensor alignment\n",
    "- Created DataLoader with batching, shuffling, and memory-efficient iteration\n",
    "- Analyzed data pipeline performance and discovered memory/speed trade-offs\n",
    "- Learned how to apply DataLoader to real datasets (see examples/milestones)\n",
    "- All tests pass ✅ (validated by `test_module()`)\n",
    "\n",
    "### Systems Insights Discovered\n",
    "- **Batch size directly impacts memory usage and training throughput**\n",
    "- **Shuffling adds minimal overhead but prevents overfitting patterns**\n",
    "- **Data loading can become a bottleneck without proper optimization**\n",
    "- **Memory usage scales linearly with batch size and feature dimensions**\n",
    "\n",
    "### Ready for Next Steps\n",
    "Your DataLoader implementation enables efficient training of CNNs and larger models with proper data pipeline management.\n",
    "Export with: `tito export 08_dataloader`\n",
    "\n",
    "**Apply your knowledge:**\n",
    "- Milestone 03: Train MLP on real MNIST digits\n",
    "- Milestone 04: Train CNN on CIFAR-10 images\n",
    "\n",
    "**Then continue with:** Module 09 (Spatial) for Conv2d layers!\n",
    "\n",
    "### Real-World Connection\n",
    "You've implemented the same patterns used in:\n",
    "- **PyTorch's DataLoader**: Same interface design for batching and shuffling\n",
    "- **TensorFlow's Dataset API**: Similar abstraction for data pipeline optimization\n",
    "- **Production ML**: Essential for handling large-scale training efficiently\n",
    "- **Research**: Standard foundation for all deep learning experiments\n",
    "\n",
    "Your data loading pipeline is now ready to power the CNN training in Module 09!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
