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

> Easily add new lab assignments to AI-For-Beginners lessons. Learn to structure new labs by creating directories, adding READMEs, starter notebooks, and updating lesson links.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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.

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

```

### Step 2: Draft the Lab README

Create a [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/examples/02-simple-neural-network.py) or [`examples/04-text-sentiment.py`](https://github.com/microsoft/AI-For-Beginners/blob/main/examples/04-text-sentiment.py) for structural patterns. Below is a skeleton implementation for a computer vision lab using TensorFlow:

```python
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`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) to include a link to your new lab. Additionally, update the root-level [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) curriculum table (lines 81-108) to ensure learners can discover the assignment from the main repository page. Use the following markdown pattern:

```markdown
| 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:

```python

# 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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/4-ComputerVision/07-ConvNets/README.md)** — Lesson description and notebook links
- **[`lessons/4-ComputerVision/07-ConvNets/lab/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/4-ComputerVision/07-ConvNets/lab/README.md)** — Example lab assignment showing required structure
- **[`examples/02-simple-neural-network.py`](https://github.com/microsoft/AI-For-Beginners/blob/main/examples/02-simple-neural-network.py)** — Template for starter notebook logic
- **[`etc/quiz-src/template.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-src/template.json)** — Quiz integration template for knowledge checks
- **[`translations/zh-TW/lessons/4-ComputerVision/07-ConvNets/lab/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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.