How to Add New Lab Assignments to Existing Lesson Structures in AI-For-Beginners

To add a new lab assignment to the AI-For-Beginners curriculum, create a lab/ directory inside the target lesson folder, add a README.md describing the task and dataset, provide a starter Jupyter notebook, and update the lesson's main README to link to the new lab.

The AI-For-Beginners repository by Microsoft follows a modular curriculum structure where each lesson lives under lessons/<topic>/<lesson-id>/. When adding new lab assignments to existing lesson structures, you must mirror the established patterns for directory organization, documentation, and multilingual support to maintain consistency across the 12-week course.

Understanding the Lesson Architecture

The curriculum organizes content into topical modules, with each lesson typically containing a descriptive README, framework-specific Jupyter notebooks for TensorFlow and PyTorch implementations, and an optional lab folder for hands-on assignments. For example, the Convolutional Neural Networks lesson at lessons/4-ComputerVision/07-ConvNets/ demonstrates the standard layout: a main README linking to executable notebooks (ConvNetsPyTorch.ipynb and ConvNetsTF.ipynb), plus a lab/ subdirectory containing the practical assignment.

Step-by-Step Guide to Adding a New Lab

Step 1: Create the Lab Directory

Navigate to your target lesson directory and create a lab/ folder if it does not exist. According to the repository structure, this directory will house all assignment-specific materials separate from the core lesson content.

mkdir -p lessons/4-ComputerVision/07-ConvNets/lab

Step 2: Draft the Lab README

Create a README.md inside the lab/ directory that follows the established format from existing assignments like the Pet Faces lab at lessons/4-ComputerVision/07-ConvNets/lab/README.md. Your README should include:

• A concise introduction to the learning objective
• Detailed task description and evaluation criteria
• Dataset download instructions or acquisition commands
• Links to starter code and any required dependencies

Step 3: Provide a Starter Notebook

Include a starter Jupyter notebook that contains boilerplate code for data loading, model architecture, and evaluation metrics. Reference the repository's existing examples such as examples/02-simple-neural-network.py or examples/04-text-sentiment.py for structural patterns. Below is a skeleton implementation for a computer vision lab using TensorFlow:

import tensorflow as tf
import pathlib
import matplotlib.pyplot as plt

# 1️⃣ Load and preprocess the dataset

data_dir = pathlib.Path('images')
train_ds = tf.keras.preprocessing.image_dataset_from_directory(
    data_dir,
    validation_split=0.2,
    subset="training",
    seed=123,
    image_size=(224, 224),
    batch_size=32)

# 2️⃣ Build a simple CNN model

model = tf.keras.Sequential([
    tf.keras.layers.Rescaling(1./255, input_shape=(224, 224, 3)),
    tf.keras.layers.Conv2D(32, 3, activation='relu'),
    tf.keras.layers.MaxPooling2D(),
    tf.keras.layers.Conv2D(64, 3, activation='relu'),
    tf.keras.layers.MaxPooling2D(),
    tf.keras.layers.Flatten(),
    tf.keras.layers.Dense(128, activation='relu'),
    tf.keras.layers.Dense(train_ds.num_classes, activation='softmax')
])

model.compile(optimizer='adam',
              loss='sparse_categorical_crossentropy',
              metrics=['accuracy'])

# 3️⃣ Train the model

history = model.fit(train_ds, epochs=10, validation_data=val_ds)

# 4️⃣ Evaluate and visualize results

plt.plot(history.history['accuracy'], label='train')
plt.plot(history.history['val_accuracy'], label='val')
plt.legend()
plt.show()

Step 4: Update the Curriculum Documentation

Modify the lesson's main README.md to include a link to your new lab. Additionally, update the root-level README.md curriculum table (lines 81-108) to ensure learners can discover the assignment from the main repository page. Use the following markdown pattern:

| 07 | Convolutional Neural Networks | [PyTorch Notebook](./ConvNetsPyTorch.ipynb) / [TensorFlow Notebook](./ConvNetsTF.ipynb) | [Lab](./lab/README.md) |

Step 5: Include Data Acquisition Scripts

If your lab requires specific datasets, provide download commands directly in the notebook or as separate scripts. As implemented in the ConvNets lab, use standard utilities to fetch and extract data:

# Download Oxford-IIIT Pet Dataset

!wget https://thor.robots.ox.ac.uk/~vgg/data/pets/images.tar.gz
!tar xfz images.tar.gz
!rm images.tar.gz

Step 6: Synchronize Translations

Because the curriculum supports multiple languages, propagate your changes to the appropriate translation directories. For example, if adding a lab to the Computer Vision module, create corresponding files under translations/zh-TW/lessons/4-ComputerVision/07-ConvNets/lab/README.md to maintain parity with the English version.

Key Reference Files

The following files demonstrate the patterns you should follow when adding new lab assignments:

• lessons/4-ComputerVision/07-ConvNets/README.md — Lesson description and notebook links
• lessons/4-ComputerVision/07-ConvNets/lab/README.md — Example lab assignment showing required structure
• examples/02-simple-neural-network.py — Template for starter notebook logic
• etc/quiz-src/template.json — Quiz integration template for knowledge checks
• translations/zh-TW/lessons/4-ComputerVision/07-ConvNets/lab/README.md — Language-specific lab implementation

Summary

• Create a lab/ directory inside the target lesson folder to isolate assignment materials from core content.
• Write a comprehensive README following the Pet Faces lab format, including task descriptions and dataset instructions.
• Provide starter notebooks with boilerplate code for data loading and model building, referencing examples/02-simple-neural-network.py for structure.
• Update documentation in both the lesson README and root-level curriculum table (lines 81-108 of the main README).
• Include data download scripts using standard commands like wget and tar for reproducibility.
• Sync translations by adding corresponding lab files to language-specific directories under translations/.

Frequently Asked Questions

What is the exact directory structure required for a new lab?

You must create a lab/ subdirectory inside the lesson folder (e.g., lessons/4-ComputerVision/07-ConvNets/lab/). This directory should contain a README.md describing the assignment and any starter notebooks or data files. This structure separates hands-on exercises from the core lesson materials while maintaining the modular organization of the AI-For-Beginners curriculum.

How do I link the new lab in the main curriculum table?

Add a new entry to the markdown table in the root README.md (approximately lines 81-108), following the format used by existing lessons: include the lesson number, title, notebook links, and a direct link to your lab README (e.g., [Lab](./lab/README.md)). Also update the lesson-specific README to reference the lab folder.

Should I provide both TensorFlow and PyTorch starter notebooks?

While the core lessons typically provide both frameworks (e.g., ConvNetsPyTorch.ipynb and ConvNetsTF.ipynb), labs may focus on a single framework depending on the learning objectives. If the lab teaches framework-agnostic concepts, providing both implementations ensures accessibility for learners preferring either stack.

How do I ensure my lab works across different language translations?

After creating the lab in the primary English directory, replicate the exact structure under the appropriate translation path (e.g., translations/zh-TW/lessons/4-ComputerVision/07-ConvNets/lab/README.md). Keep the technical content identical while translating only the instructional text, ensuring code examples and file paths remain consistent across all language versions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}