TinyTorch/.cursor/rules/nbdev-educational-pattern.mdc

# NBDev Educational Pattern for TinyTorch Modules

## File Format
Use Jupytext percent format with NBDev directives:

```python
# ---
# jupyter:
#   jupytext:
#     text_representation:
#       extension: .py
#       format_name: percent
#       format_version: '1.3'
#       jupytext_version: 1.17.1
# ---

# %% [markdown]
"""
# Module: {Title}

## Learning Objectives
- ✅ Build {core_concept} from scratch
- ✅ Use it with real data ({dataset_name})
- ✅ Understand {key_insight}
- ✅ Connect to production ML systems
"""

# %%
#| default_exp core.component_name

# Setup and imports
import required_libraries
import matplotlib.pyplot as plt  # For visual feedback

# %% [markdown]
"""
## Step 1: Concept Explanation
Educational content explaining the concept...
"""

# %%
#| export
class ComponentName:
    """
    Component description.
    
    TODO: Student implementation instructions.
    """
    def method(self):
        raise NotImplementedError("Student implementation required")

# %%
#| hide
#| export  
class ComponentName:
    """Complete implementation (hidden from students)."""
    def method(self):
        # Actual implementation
        pass

# %% [markdown]
"""
## 🧪 Test Your Implementation
"""

# %%
# Test with real data
try:
    result = ComponentName(real_data_example)
    print(f"✅ Success: {result}")
except NotImplementedError:
    print("⚠️ Implement the class above first!")
```

## Key NBDev Directives

- `#| default_exp core.module` - Sets export destination in tinytorch package
- `#| export` - Marks code for export to package
- `#| hide` - Hides cell from students (instructor solution)
- `# %% [markdown]` - Markdown cells for explanations
- `# %%` - Code cells

## Educational Structure Requirements

### 1. Conceptual Foundation
Each module must start with clear conceptual explanations:

```markdown
## What is [Concept]?

**Definition**: Clear, simple definition with examples
**Why it matters**: Real-world motivation and ML context
**How it works**: Intuitive explanation before math
**Connection**: How it builds on previous modules
```

### 2. Guided Implementation
Provide comprehensive TODO guidance:

```python
def method(self):
    """
    TODO: Step-by-step implementation guide
    
    APPROACH:
    1. First step with specific guidance
    2. Second step with specific guidance
    3. Third step with specific guidance
    
    EXAMPLE:
    Input: actual_data_example
    Expected: concrete_expected_output
    
    HINTS:
    - Helpful guidance without giving code
    - Systems thinking consideration
    - Real-world connection
    """
    raise NotImplementedError("Student implementation required")
```

### 3. Development vs Export Separation
- **Rich feedback in development**: Visual confirmation, progress bars
- **Clean exports to package**: No matplotlib dependencies in exported code
- **Use conditional display**: `if not _should_show_plots(): return`

## Module Structure Template

```python
# ---
# jupyter:
#   jupytext:
#     text_representation:
#       extension: .py
#       format_name: percent
#       format_version: '1.3'
#       jupytext_version: 1.17.1
# ---

# %% [markdown]
"""
# Module: {Title}

## Learning Objectives
- ✅ Build {core_concept} from scratch
- ✅ Use it with real data ({dataset_name})
- ✅ Understand {key_insight}
- ✅ Connect to production ML systems
"""

# %%
#| default_exp core.{module}
import numpy as np
import matplotlib.pyplot as plt
from typing import Union, List, Optional

# %%
#| export
class MainClass:
    """Student-facing implementation with comprehensive TODO."""
    def __init__(self, params):
        # Comprehensive TODO guidance here
        raise NotImplementedError("Student implementation required")

# %%
#| hide
#| export
class MainClass:
    """Complete implementation (hidden from students)."""
    def __init__(self, params):
        # Actual working implementation
        pass
```

## Educational Principles

1. **Build → Use → Understand → Repeat**: Each module follows this cycle
2. **Concrete Before Abstract**: Start with examples, then generalize
3. **Scaffolded Learning**: Provide hints and guidance, not just empty functions
4. **Standalone Modules**: Each module should be understandable independently
5. **Real-world Context**: Connect to practical ML applications

## Naming Convention

Module files should be named `{module_name}_dev.py` to indicate development notebooks.