TinyTorch/docs/development/quick-module-reference.md

🚀 TinyTorch Module Development - Quick Reference

📋 Development Checklist

1. Plan Module

• Define learning objectives (what students will implement)
• Choose difficulty levels (🟢 easy → 🟡 medium → 🔴 hard)
• Decide what to provide vs. what students implement

2. Write Complete Implementation

Create modules/{module}/{module}_dev.py:

# %% [markdown]
# # Module: {Title}
# Learning objectives and overview

# %%
#| keep_imports
import numpy as np

# %%
class YourClass:
    #| exercise_start
    #| difficulty: easy
    #| hint: Clear guidance without giving away code
    #| solution_test: How students verify their work
    def method_to_implement(self):
        """Full signature and docstring."""
        # Complete working implementation
        pass
    #| exercise_end

3. Convert and Generate

# Convert Python to notebook
python bin/tito.py notebooks --module {module}

# Generate student version
python3 bin/generate_student_notebooks.py --module {module}

4. Test and Verify

# Test both versions work
jupyter lab modules/{module}/{module}_dev.ipynb
jupyter lab modules/{module}/{module}_dev_student.ipynb

# Test integration
python bin/tito.py sync --module {module}
python bin/tito.py test --module {module}

🏷️ Essential Markers

Marker	Purpose	Example
`#	exercise_start/end`	Mark student implementation
`#	difficulty: easy|medium|hard`	Visual indicator
`#	hint:`	Guide student thinking
`#	solution_test:`	Verification guidance
`#	keep_imports`	Preserve imports
`#	keep_complete`	Keep full implementation
`#	remove_cell`	Remove from student version

🎨 Difficulty Guidelines

• 🟢 Easy (5-10 min): Constructor, properties, basic operations
• 🟡 Medium (10-20 min): Conditional logic, shape manipulation
• 🔴 Hard (20+ min): Complex algorithms, multiple concepts

✅ Quality Check

Before release:

• Complete version works and passes tests
• Student version preserves signatures and docstrings
• Hints are helpful but not prescriptive
• Tests provide clear verification guidance
• Exports correctly to tinytorch package

🔄 File Structure

modules/{module}/
├── {module}_dev.py              # 🔧 Write this first
├── {module}_dev.ipynb           # 📓 Generated 
├── {module}_dev_student.ipynb   # 🎓 Auto-generated
├── test_{module}.py             # 🧪 Test suite
└── README.md                    # 📖 Module guide

💡 Pro Tips

1. Write complete implementation first - Get it working before adding markers
2. Test the student path - Follow your own hints to verify they work
3. Be generous with hints - Better too helpful than too cryptic
4. Preserve all signatures - Students need to know the interface
5. Progressive difficulty - Start easy, build complexity

🛠️ Common Commands

# Create new module
mkdir modules/{module}
cp modules/example/example_dev.py modules/{module}/{module}_dev.py

# Full workflow
python bin/tito.py notebooks --module {module}
python bin/generate_student_notebooks.py --module {module}

# Test everything
python bin/tito.py test --module {module}

See MODULE_DEVELOPMENT_GUIDE.md for complete details.