TinyTorch/development/archived/TINYTORCH_NBGRADER_PROPOSAL.md

TinyTorch + nbgrader Integration Proposal

Executive Summary

This proposal outlines how to integrate nbgrader with TinyTorch to create a comprehensive course management system that supports both self-paced learning and formal assessment from the same source materials.

The Problem

Current TinyTorch has excellent educational content but lacks:

• Automated grading for large courses
• Formal assessment workflow
• Immediate feedback for student implementations
• Grade tracking and LMS integration
• Scalable evaluation for hundreds of students

The Solution: Dual-Purpose Content

Current System (Enhanced)

class Tensor:
    def __init__(self, data):
        """Create tensor from data"""
        #| exercise_start                    # TinyTorch marker
        #| hint: Use np.array() to convert data
        #| difficulty: easy
        
        ### BEGIN SOLUTION                   # nbgrader marker
        self._data = np.array(data)
        ### END SOLUTION
        
        #| exercise_end
        
    ### BEGIN HIDDEN TESTS                  # nbgrader auto-grading
    def test_init():
        t = Tensor([1, 2, 3])
        assert t._data.tolist() == [1, 2, 3]
    ### END HIDDEN TESTS

Generates Two Student Versions

1. Self-Learning Version (Current TinyTorch Style)

class Tensor:
    def __init__(self, data):
        """Create tensor from data"""
        # 🟡 TODO: Implement tensor creation (easy)
        # HINT: Use np.array() to convert data
        # Your implementation here
        pass

2. Assignment Version (nbgrader Compatible)

class Tensor:
    def __init__(self, data):
        """Create tensor from data"""
        ### BEGIN SOLUTION
        # YOUR CODE HERE
        raise NotImplementedError()
        ### END SOLUTION
        
    ### BEGIN HIDDEN TESTS
    def test_init():
        t = Tensor([1, 2, 3])
        assert t._data.tolist() == [1, 2, 3]
    ### END HIDDEN TESTS

Implementation Strategy

Phase 1: Enhanced Marking System ✅

• Add nbgrader markers to existing framework
• Enhance student notebook generator
• Create dual generation system
• Demonstrate with tensor module example

Phase 2: nbgrader Integration

• Set up nbgrader environment
• Configure auto-grading workflows
• Extend tito CLI for assignment management
• Create grade tracking system

Phase 3: Course Deployment

• Deploy to production course
• Train instructors on new workflow
• Collect student feedback
• Iterate and improve

Benefits

For Instructors

1. Single Source, Multiple Outputs: Write once, generate both learning and assessment materials
2. Automated Grading: Reduce grading workload by 80%+
3. Consistent Evaluation: Standardized testing across all students
4. Immediate Feedback: Students get instant results
5. Analytics: Track student progress and identify common issues

For Students

1. Flexible Learning: Choose between self-paced exploration or structured assignments
2. Immediate Feedback: Know if implementation is correct instantly
3. Progressive Building: Verified implementations become foundation for next modules
4. Real-World Practice: Same testing standards as production ML frameworks

For Course Management

1. Scalability: Handle 100+ students with automated systems
2. Quality Assurance: Consistent educational experience
3. Data-Driven: Analytics on student learning patterns
4. Reusability: Assignments work across multiple semesters

Technical Implementation

Enhanced CLI Commands

# Generate regular student notebooks
tito notebooks --student --module tensor

# Generate nbgrader assignments  
tito notebooks --assignments --module tensor

# Batch generate all
tito notebooks --student --all
tito notebooks --assignments --all

# nbgrader integration
tito assignment --create tensor     # Create assignment
tito assignment --release tensor    # Release to students
tito assignment --collect tensor    # Collect submissions
tito assignment --grade tensor      # Auto-grade
tito assignment --feedback tensor   # Generate feedback

Workflow Integration

Instructor Development:
  modules/tensor/tensor_dev.py (complete implementation)
    ↓
  tito sync --module tensor (export to package)
    ↓
  tito notebooks --student --module tensor (self-learning)
    ↓
  tito notebooks --assignments --module tensor (formal assessment)
    ↓
  tito assignment --create tensor (nbgrader setup)
    ↓
  [Student work and submission]
    ↓
  tito assignment --grade tensor (auto-grading)
    ↓
  Grade feedback and analytics

Concrete Example: Tensor Module

Student Learning Experience

Self-Learning Track

1. Exploration: Rich educational content with step-by-step guidance
2. Implementation: TODO sections with extensive hints
3. Testing: Immediate feedback via notebook testing
4. Iteration: Self-paced learning with no pressure

Assignment Track

1. Structured Implementation: Clear requirements and hidden tests
2. Submission: Formal submission through nbgrader interface
3. Auto-grading: Instant feedback with partial credit
4. Analytics: Instructor sees class-wide performance patterns

Assessment Breakdown

• Tensor Creation (Easy): 10 points
• Properties (Easy): 10 points
• Basic Operations (Medium): 15 points
• Matrix Multiplication (Hard): 20 points
• Error Handling (Hard): 10 points
• Total: 65 points per module

Migration Path

Existing Modules

1. Minimal Changes: Add nbgrader markers alongside existing TinyTorch markers
2. Backward Compatible: Existing workflow continues to work
3. Gradual Adoption: Instructors can choose which modules to use for formal assessment

New Modules

1. Dual-Purpose by Default: All new modules support both tracks
2. Comprehensive Testing: Hidden tests for every major component
3. Progressive Complexity: Easy → Medium → Hard exercises within each module

Success Metrics

Educational Outcomes

• Completion Rate: % of students completing all modules
• Comprehension: Performance on assessments vs. self-learning
• Retention: Long-term retention of concepts
• Engagement: Time spent in learning vs. assessment modes

Operational Efficiency

• Grading Time: Reduction in instructor grading hours
• Feedback Speed: Time from submission to feedback
• Scalability: Students supported per instructor
• Quality Consistency: Variance in grading across instructors

Conclusion

The TinyTorch + nbgrader integration represents a paradigm shift from traditional course management to an intelligent, scalable educational system that:

1. Preserves TinyTorch's pedagogical philosophy while adding assessment capabilities
2. Scales to large courses without sacrificing educational quality
3. Provides flexibility for different learning styles and course structures
4. Maintains single-source truth for all educational materials
5. Enables data-driven improvement through comprehensive analytics

This system transforms TinyTorch from a learning framework into a complete course management solution that can handle everything from individual self-study to large-scale university courses.

Next Steps

1. Review and approve this proposal
2. Implement Phase 2 (nbgrader integration)
3. Pilot with one module (tensor recommended)
4. Gather feedback and iterate
5. Scale to full course deployment

The enhanced system is ready for immediate implementation and testing. The dual generation capability is already working, and the nbgrader integration requires only standard nbgrader setup and configuration.

---

This proposal demonstrates how thoughtful integration of existing tools can create something greater than the sum of its parts - a truly scalable, intelligent educational system that adapts to both students and instructors' needs.