Notebook Creation Guide

Create Amazing AI/ML Problems

Overview

MockSphere allows you to create interactive AI/ML problems using Jupyter notebooks. Your notebooks will be automatically parsed and converted into problems that students can solve online with flexible submission behaviors.

Get Started with a Template

New to creating problems? Download our template notebook to see the proper structure and format.

Download Template Notebook

Notebook Structure

1
Problem Header Cell

First cell must contain problem metadata and description.

2
Question Parts

Each question part should be in a separate markdown cell with clear formatting.

3
Code Blocks

Each markdown cell can have at most two code blocks: starter code and test code with a test() function.

4
Test Function

A test() function that returns True or False to validate the solution.

Question Types

Code Execution

Type: code

Students write Python code that gets executed and evaluated.

Best for: Programming problems, calculations, implementations
Free-Form Text

Type: text

Students write explanations, derivations, or proofs.

Best for: Mathematical proofs, explanations, theoretical problems
Mathematical Expression

Type: math

Students write LaTeX mathematical expressions.

Best for: Formula derivations, mathematical expressions
Simple Value

Type: value

Students provide numbers, strings, or boolean answers.

Best for: Quick calculations, simple answers
Multiple Choice

Type: multiple_choice

Students select from predefined options.

Best for: Conceptual questions, quick assessments

Code Blocks in Questions

For code type questions, each markdown cell should contain two and only two code blocks. The first is called starter code and second is test code.

Starter Code Block

Required template or skeleton for students to complete:

```python
def add_two_int(a, b):
    """
    Add two integers and return the result.
    """
    # Your code here
    pass
```
Test Code Block

Required test code that must define a test() function returning True or False:

```python
def test():
    # Method 1: Compare with reference implementation
    def add_two_int_real(a, b):
        return a + b
    
    # Test with various inputs
    test_cases = [(1, 2), (0, 0), (-1, 1), (100, -50)]
    
    for a, b in test_cases:
        if add_two_int(a, b) != add_two_int_real(a, b):
            return False
    return True
```
Two Approaches for Writing Test Functions
Method 1: Reference Implementation (Recommended)

Define a reference function and compare results:

def test():
    # Define reference implementation
    def add_two_int_real(a, b):
        return a + b
    
    # Test with various inputs
    test_cases = [(1, 2), (0, 0), (-1, 1)]
    
    for a, b in test_cases:
        if add_two_int(a, b) != add_two_int_real(a, b):
            return False
    return True

Advantages: Easy to write, more stable, flexible test cases

Method 2: Hardcoded Input/Output

Define specific test inputs and expected outputs:

def test():
    # Hardcoded test cases
    if add_two_int(1, 2) != 3:
        return False
    if add_two_int(0, 0) != 0:
        return False
    if add_two_int(-1, 1) != 0:
        return False
    return True

Use when: Specific edge cases need testing

Important Rules
  • For code type questions, each markdown cell must have exactly 2 code blocks
  • Test code block must define a test() function
  • The test() function must return True or False
  • Method 1(Reference Implementation) is recommended as it's easier to write and more stable

Metadata Format

Your first markdown cell must contain the following metadata:

Required Metadata Format
Problem Title
# Problem: [Your Problem Title]
Difficulty
**Difficulty:** [easy|medium|hard]
Points
**Points:** [number]
Time Limit
**Time Limit:** [seconds] seconds
Memory Limit
**Memory Limit:** [MB] MB
Submission Behavior
**Submission Behavior:** [interactive|guided]
Separator
---
Description
## Problem Description
[Detailed description...]
Example
# Problem: Linear Regression from Scratch

**Difficulty:** medium
**Points:** 150
**Time Limit:** 300 seconds
**Memory Limit:** 512 MB
**Submission Behavior:** interactive

---

## Problem Description

Implement linear regression from scratch using gradient descent...
Field Required Options Description
Difficulty Yes easy, medium, hard Problem difficulty level
Points Yes 1-1000 Points awarded for solving
Time Limit No 1-300 seconds Maximum execution time (default: 30)
Memory Limit No 2048-4096 MB Maximum memory usage (default: 2048)
Submission Behavior No interactive, guided How students interact with questions (default: interactive)

Submission Behavior

Control how students interact with your questions through different submission behaviors.

Interactive Mode

Default behavior - Students can submit answers multiple times until they get it correct.

  • Students can retry incorrect answers
  • Immediate feedback on correctness
  • Auto-advance only on correct answers
  • Best for practice and learning
**Submission Behavior:** interactive
Guided Mode

Educational mode - After each submission, show correct answer and explanation, then auto-advance.

  • Single submission per question
  • Always shows correct answer
  • Always shows explanation
  • Auto-advances to next question
  • Best for assessments and tutorials
**Submission Behavior:** guided
When to Use Each Mode
  • Interactive: Use for practice problems, coding exercises, and self-paced learning
  • Guided: Use for assessments, tutorials, and structured learning experiences

Video in Questions

You can embed videos directly in your problem questions using HTML iframe elements wrapped in a special container.

Magic Class Rule

Any HTML content wrapped in a <div class="mocksphere"> will be processed and displayed properly in the problem interface.

How to Embed Videos

Wrap your iframe elements in a div with class "mocksphere" to ensure proper rendering:

Video Embedding Format
<div class="mocksphere">
<iframe width="560" height="315" 
        src="https://www.youtube-nocookie.com/embed/VIDEO_ID" 
        frameborder="0" allowfullscreen>
</iframe>
</div>
Supported Video Platforms:
Important Notes
  • Use youtube-nocookie.com for YouTube videos to avoid cookie consent issues
  • Videos are automatically responsive and will scale to fit the content area
  • Always wrap iframe elements in <div class="mocksphere"> for proper processing
  • You can embed multiple videos in the same question by using multiple div containers
Example in Question Content:
Markdown Cell Content:
## Understanding Linear Regression

Watch this video to understand the mathematical foundation:

<div class="mocksphere">
<iframe width="560" height="315" 
        src="https://www.youtube-nocookie.com/embed/Cu6GHY0-0LY" 
        frameborder="0" allowfullscreen>
</iframe>
</div>

Now answer the following question based on the video content.

Examples

Example: Linear Regression Problem

Problem: Linear Regression from Scratch

Difficulty: medium
Points: 150
Time Limit: 60 seconds
Memory Limit: 512 MB


Problem Description

Implement linear regression from scratch using gradient descent.

Part 1: Cost Function

Implement the mean squared error cost function.

Question Type: code
Requirements:

  • Function should take X, y, theta as parameters
  • Return scalar cost value

Starter Code:

```python
def mean_squared_error(X, y, theta):
    """
    Calculate mean squared error cost function.
    
    Parameters:
    X: feature matrix (m, n)
    y: target vector (m,)
    theta: parameter vector (n,)
    
    Returns:
    cost: scalar cost value
    """
    # Your code here
    pass
```

Test Code:

```python
def test():
    # Method 1: Compare with reference implementation
    def mean_squared_error_real(X, y, theta):
        m = len(y)
        predictions = X @ theta
        return (1 / (2 * m)) * np.sum((predictions - y) ** 2)
    
    # Test with sample data
    X = np.array([[1, 2], [3, 4], [5, 6]])
    y = np.array([3, 7, 11])
    theta = np.array([1.0, 1.0])
    
    # Test the implementation
    result = mean_squared_error(X, y, theta)
    expected = mean_squared_error_real(X, y, theta)
    
    return abs(result - expected) < 1e-10
```

Part 2: Mathematical Formula

Write the gradient formula.

Question Type: math
Expected: $\frac{\partial J}{\partial \theta} = \frac{1}{m} \sum_{i=1}^{m} (h_\theta(x^{(i)}) - y^{(i)}) x^{(i)}$

Part 3: Multiple Choice

What is the main advantage of stochastic gradient descent?

Question Type: multiple_choice
Options:

  • A) More accurate results
  • B) Faster convergence for large datasets
  • C) Less memory usage
  • D) Better for non-convex functions

Correct Answer: B

Part 4: Gradient Descent Implementation

Implement the gradient descent algorithm for linear regression.

Question Type: code
Requirements:

  • Function should take X, y, learning_rate, num_iterations as parameters
  • Return weights, bias, and cost history

Starter Code:

```python
def gradient_descent(X, y, learning_rate=0.01, num_iterations=1000):
    """
    Implement gradient descent for linear regression.
    
    Parameters:
    X: feature matrix (m, n)
    y: target vector (m,)
    learning_rate: step size
    num_iterations: number of iterations
    
    Returns:
    weights: learned weights (n,)
    bias: learned bias term
    costs: list of cost values
    """
    # Your code here
    pass
```

Test Code:

```python
def test():
    # Method 1: Compare with reference implementation
    def gradient_descent_real(X, y, learning_rate=0.01, num_iterations=1000):
        m, n = X.shape
        weights = np.zeros(n)
        bias = 0
        costs = []
        
        for i in range(num_iterations):
            predictions = X @ weights + bias
            error = predictions - y
            dw = (1 / m) * X.T @ error
            db = (1 / m) * np.sum(error)
            weights -= learning_rate * dw
            bias -= learning_rate * db
            cost = (1 / (2 * m)) * np.sum(error ** 2)
            costs.append(cost)
        
        return weights, bias, costs
    
    # Test with sample data
    X = np.array([[1, 2], [3, 4], [5, 6]])
    y = np.array([3, 7, 11])
    
    # Test the implementation
    weights, bias, costs = gradient_descent(X, y, 0.01, 100)
    weights_real, bias_real, costs_real = gradient_descent_real(X, y, 0.01, 100)
    
    return (np.allclose(weights, weights_real, atol=1e-6) and 
            abs(bias - bias_real) < 1e-6 and
            len(costs) == len(costs_real))
```

Ready to Submit?

Once you've created your problem notebook following these guidelines, you can submit it using our secure upload system.