- Simplified to 4 core problems: student profile, email validation, environment check, configuration test
- Changed from complex programming tasks to simple configuration validation
- Used proper NBGrader syntax with ### BEGIN SOLUTION ### and ### BEGIN HIDDEN TESTS ###
- Added instructor mark schemes with point allocation and deduction guidelines
- Focused on TinyTorch-relevant setup tasks: configuring student info and validating environment
- Reduced from 95 to 100 points with better balanced distribution (40+20+20+20)
- Uses instructor's actual information as example template
- Maintains comprehensive educational content while being much more focused
- Convert from complex nbgrader metadata to simple 'nbgrader: grade, solution' format
- Add inline test blocks with 'nbgrader: tests' directives
- Remove separate test files - use inline tests instead
- Follow the jupytext percent format with NBGrader directives
- Maintain comprehensive educational content and hints
- Clean up generated notebooks (Python-first development)
- Ready for NBGrader autograding workflow
- Remove setup_dev.ipynb (development artifact)
- Remove 00_setup.ipynb (generated student assignment)
- Follow Python-first development workflow: .py files are source of truth
- .ipynb files should only be generated when ready for NBGrader work
- Clean separation: develop in .py, generate .ipynb on demand
- Add complex_calculation() function demonstrating multiple solution blocks within single function
- Shows how NBGrader can guide students through step-by-step implementation
- Each solution block replaced with '# YOUR CODE HERE' + 'raise NotImplementedError()' in student version
- Update total points from 85 to 95 to account for new 10-point problem
- Add comprehensive test coverage for multi-step function
- Demonstrate educational pattern: Step 1 → Step 2 → Step 3 within one function
- Perfect example of NBGrader's guided learning capabilities
- Remove 5 outdated development guides that contradicted clean NBGrader/nbdev architecture
- Update all documentation to reflect assignments/ directory structure
- Remove references to deprecated #| hide approach and old command patterns
- Ensure clean separation: NBGrader for assignments, nbdev for package export
- Update README, Student Guide, and Instructor Guide with current workflows
- Migrated all Python source files to assignments/source/ structure
- Updated nbdev configuration to use assignments/source as nbs_path
- Updated all tito commands (nbgrader, export, test) to use new structure
- Fixed hardcoded paths in Python files and documentation
- Updated config.py to use assignments/source instead of modules
- Fixed test command to use correct file naming (short names vs full module names)
- Regenerated all notebook files with clean metadata
- Verified complete workflow: Python source → NBGrader → nbdev export → testing
All systems now working: NBGrader (14 source assignments, 1 released), nbdev export (7 generated files), and pytest integration.
The modules/ directory has been retired and replaced with standard NBGrader structure.
✅ PYTHON-FIRST DEVELOPMENT:
- Always work in raw Python files (modules/XX/XX_dev.py)
- Generate Jupyter notebooks on demand using Jupytext
- NBGrader compliance through automated cell metadata
- nbdev for package building and exports
🔧 WORKFLOW IMPROVEMENTS:
- Fixed file priority: use XX_dev.py over XX_dev_enhanced.py
- Clean up enhanced files to use standard files as source of truth
- Updated documentation to highlight Python-first approach
📚 COMPLETE INSTRUCTOR WORKFLOW:
1. Edit modules/XX/XX_dev.py (Python source of truth)
2. Export to package: tito module export XX (nbdev)
3. Generate assignment: tito nbgrader generate XX (Python→Jupyter→NBGrader)
4. Release to students: tito nbgrader release XX
5. Auto-grade with pytest: tito nbgrader autograde XX
✅ VERIFIED WORKING:
- Python file editing ✅
- nbdev export to tinytorch package ✅
- Jupytext conversion to notebooks ✅
- NBGrader assignment generation ✅
- pytest integration for auto-grading ✅🎯 TOOLS INTEGRATION:
- Raw Python development (version control friendly)
- Jupytext (Python ↔ Jupyter conversion)
- nbdev (package building and exports)
- NBGrader (student assignments and auto-grading)
- pytest (testing within notebooks)
Perfect implementation of user's ideal workflow
- Move development artifacts to development/archived/ directory
- Remove NBGrader artifacts (assignments/, testing/, gradebook.db, logs)
- Update root README.md to match actual repository structure
- Provide clear navigation paths for instructors and students
- Remove outdated documentation references
- Clean root directory while preserving essential files
- Maintain all functionality while improving organization
Repository is now optimally structured for classroom use with clear entry points:
- Instructors: docs/INSTRUCTOR_GUIDE.md
- Students: docs/STUDENT_GUIDE.md
- Developers: docs/development/
✅ All functionality verified working after restructuring
- Create comprehensive INSTRUCTOR_GUIDE.md with verified modules, teaching sequence, and practical commands
- Create new STUDENT_GUIDE.md based on actual working state with correct module numbering
- Update main docs/README.md to reflect current capabilities and clean structure
- Remove outdated docs/students/project-guide.md that had incorrect information
- Focus on 6+ weeks of proven curriculum content currently ready for classroom use
- Base all documentation on verified test results and working module status
- Document all implemented features and achievements
- Provide clear next steps for production deployment
- Include testing status and performance metrics
- Detail technical architecture and benefits
- Ready for immediate testing and implementation
- CNN builds directly on layers/networks concepts while fresh
- Creates natural progression: layers → networks → cnn → dataloader
- 'Complete the layer toolkit first' before moving to data systems
- Move compression to 10 (right after training - model optimization)
- Move mlops to 11 (deployment comes next - production readiness)
- Move profiling to 12 (optimization tools - when needed)
- Move benchmarking to 13 (comparative analysis - with profiling)
- Move kernels to 14 (advanced optimization)
- Move transformer to 15 (final advanced topic)
Better Learning Flow:
- Training → 'I have a model, now what?' → Deployment
- Deployment → 'Now let me optimize' → Profiling/Benchmarking
- Mirrors real ML engineering: Deploy first, optimize second
- Profiling + Benchmarking work together naturally
Final progression (00-15):
00_setup → 01_tensor → 02_activations → 03_layers → 04_networks →
05_dataloader → 06_cnn → 07_autograd → 08_optimizers → 09_training →
10_compression → 11_mlops → 12_profiling → 13_benchmarking →
14_kernels → 15_transformer
- Add CNN as module 06 (after networks, before autograd)
- Shift all subsequent modules up by one number
- Add Transformer as module 15 (advanced/final module)
- Complete logical progression from foundations to production systems
Final progression:
00_setup → 01_tensor → 02_activations → 03_layers → 04_networks →
05_dataloader → 06_cnn → 07_autograd → 08_training → 09_config →
10_profiling → 11_compression → 12_kernels → 13_benchmarking →
14_mlops → 15_transformer
Clear student learning path: Foundation → Core ML → Advanced Architectures →
Training Systems → Production Systems → Advanced Topics
- Update all test files to import from tinytorch.core.* instead of relative paths
- Consistent with rock solid foundation principle
- Tests now use stable package imports, not local module imports
- Ensures tests validate the actual exported package functionality
- Aligns with production usage patterns
- Fix module imports to use tinytorch.core.* instead of local module imports
- Activations module now imports from tinytorch.core.tensor for stability
- Layers module imports from tinytorch.core.tensor and tinytorch.core.activations
- Test files updated to use main package imports for dependencies
- This ensures students can focus on current module without dependency issues
- Previous modules are 'locked in' and guaranteed to work
- Mirrors real-world usage patterns like PyTorch
- Maintains educational progression while ensuring system stability
- Reorganize hidden solutions to follow correct NBDev pattern (after each student implementation)
- Add comprehensive visualization system with _should_show_plots() control
- Implement smart test/development mode detection to suppress visualizations during pytest
- Add individual activation function plots and sample data visualizations
- Include comprehensive comparison plots for all activation functions
- Maintain educational inline tests with immediate feedback
- All 24 tests pass cleanly with proper visualization control
- Follows same structure as layers and tensor modules
Features:
- ReLU, Sigmoid, Tanh, Softmax visualizations with mathematical properties
- Real-time visual feedback during development
- Clean test execution without visual noise
- Educational context and use-case guidance for each activation
- Remove duplicate class definitions (was 800 lines → 517 lines)
- Follow consistent educational pattern like other modules
- Improve Build → Use → Reflect pedagogical framework
- Clean up TODO sections with proper implementation guidance
- Add comprehensive docstrings and examples
- Organize student and instructor implementations properly
- Maintain all functionality while improving readability
- All tests still pass (24/24 activations tests)
- Change --all flag meaning from 'clean both file types' to 'clean all modules'
- Make clean command consistent with test and export commands
- Require explicit module name or --all flag (no implicit behavior)
- Update help text and examples
- Now supports both:
- tito module clean tensor (specific module)
- tito module clean --all (all modules)
- Update test, export, and clean commands to use positional arguments
- Change from 'tito module test --module dataloader' to 'tito module test dataloader'
- Eliminates redundant --module flag within module command group
- Update help text and examples to reflect new syntax
- Maintains backward compatibility with --all flag
- More intuitive and consistent CLI design
- Move export functionality from 'tito package export' to 'tito module export'
- Require --all flag for exporting all modules (consistent with test command)
- Remove export from package command group to eliminate duplication
- Update help text and examples across all commands
- Fix tensor module arithmetic operators for complete functionality
- Clean up duplicate _quarto.yml and sidebar.yml files in modules/
This creates a consistent CLI pattern:
- tito module export --all (export all modules)
- tito module export --module <name> (export specific module)
- tito module test --all (test all modules)
- tito module test --module <name> (test specific module)
- Remove redundant fields from module.yaml files: exports_to, files, components
- Keep only essential system metadata: name, title, description, dependencies
- Export command now reads actual export targets from dev files (#| default_exp directive)
- Status command updated to use dev files as source of truth for export targets
- Export command shows detailed source → target mapping for better clarity
- Dependencies field retained as it's useful for CLI module ordering and prerequisites
- Eliminates duplication between YAML and dev files - dev files are the real truth
- Rename SyncCommand to ExportCommand and sync.py to export.py
- Update all CLI references from 'tito package sync' to 'tito package export'
- Update help text and internal messages to use 'Export' terminology
- Update imports across all command files
- Update help text in main CLI, reset, clean, info, and notebooks commands
- Command now clearly communicates that it exports notebook code to Python package
- Maintains same functionality but with clearer naming for user experience
- Add Module Info sections with difficulty ratings to all README.md files
- Use consistent 4-star difficulty scale: ⭐ Beginner, ⭐⭐ Intermediate, ⭐⭐⭐ Advanced, ⭐⭐⭐⭐ Expert
- Include time estimates, prerequisites, and next steps for each module
- Maintain clear separation: README.md = student experience, module.yaml = system metadata
- Difficulty progression: Setup (⭐) → Tensor/Activations/Layers (⭐⭐) → Networks/CNN/DataLoader (⭐⭐⭐) → Transformer (⭐⭐⭐⭐)
- Help students plan their learning journey and set appropriate expectations
- Add new CleanCommand for cleaning up module directories
- Supports cleaning notebooks (*.ipynb) and cache files (__pycache__, *.pyc)
- Can clean specific modules or all modules
- Provides preview of files to be cleaned with confirmation
- Includes --force flag to skip confirmation
- Integrates with module command group as 'tito module clean'
- Preserves Python source files (*_dev.py) and other important files
- Fixes issue with duplicate file removal from __pycache__ directories
- Remove outdated documentation files (cli-reorganization, command-cleanup-summary, module-metadata-system, testing-separation)
- Update all CLI commands to use current hierarchical structure (tito system/module/package)
- Align documentation with simplified metadata system
- Update student project guide with current module structure
- Modernize development guides and quick reference
- Remove references to removed features (py_to_notebook, complex metadata)
- Ensure all documentation reflects current system state
Documentation now focuses on:
- Current CLI structure and commands
- Simplified module development workflow
- Real data and production patterns
- Clean educational progression
- Delete bin/py_to_notebook.py and tito/tools/py_to_notebook.py
- Update notebooks command to use Jupytext directly
- Jupytext is already configured in all *_dev.py files
- Simpler, more standard workflow using established tools
- Better integration with NBDev ecosystem
Benefits:
- Eliminates duplicate conversion tools
- Uses industry-standard Jupytext instead of custom tool
- Reduces maintenance burden
- Better error handling and compatibility
- Skip environment validation for 'tito system doctor' command
- Fix dependency detection in doctor command for packages without __version__
- Doctor command now works correctly and shows comprehensive system diagnosis
- Remove version field from all module.yaml files
- Update template generator to exclude version field
- Further simplify metadata to focus on system information only
- Status remains dynamically determined by test results
- Reduce module.yaml files from 100+ lines to ~25 lines focused on system needs
- Remove pedagogical details (learning objectives, difficulty, time estimates)
- Keep only essential fields: name, title, description, status, dependencies, exports, files, components
- Update status command to work with simplified metadata format
- Update metadata generation script to create simplified templates
- Focus on system metadata for CLI tools and build systems, not educational content
Before: Verbose pedagogical metadata with 20+ fields
After: Concise system metadata with 8 core fields
This aligns with the principle that module.yaml should be for systems, not pedagogy.
- Change doctor command check from 'bin/tito.py' to 'bin/tito'
- The actual CLI script is 'bin/tito' (without .py extension)
- Doctor command now correctly shows CLI script as found instead of missing
- Resolves false positive error in environment diagnosis
- Remove legacy flat commands (info, test, sync, etc.) from main parser
- Keep only hierarchical command groups (system, module, package)
- Eliminate confusing positional arguments showing both flat and hierarchical commands
- Update help text to remove references to deprecated commands
- CLI now shows clean 3-command structure: system, module, package
- Old flat commands like 'tito info' now properly error with helpful message
- Maintains all functionality through hierarchical structure:
- tito info → tito system info
- tito status → tito module status
- tito sync → tito package sync
Result: Clean, focused CLI with clear command organization
- Add brief descriptions to YAML frontmatter for all rule files
- Descriptions explain the purpose and content of each rule
- Follow consistent format matching ml-systems-course-context.mdc
- Improve rule discoverability and understanding
Files updated:
- user-preferences.mdc: User preferences and development conventions
- tinytorch-project-structure.mdc: Dual-structure architecture guide
- testing-patterns.mdc: Testing standards with pytest and real data
- nbdev-educational-pattern.mdc: Educational NBDev patterns
- module-development-best-practices.mdc: Real Data, Real Systems principles
- git-workflow.mdc: Git workflow guidelines for incremental commits
- development-workflow.mdc: Complete development workflow with tito CLI
- cli-patterns.mdc: CLI development patterns for tito tool
- Changed all module titles to be short and clean (e.g., 'Autograd' not 'Autograd - Automatic Differentiation')
- Updated metadata generation template to use concise titles by default
- Fixed CLI reference in metadata generator to use new hierarchical structure
- Titles are now consistent: just the module name capitalized
- Detailed descriptions remain in the description field where they belong
- Add system, module, and package command groups for clear subsystem separation
- Create SystemCommand, ModuleCommand, and PackageCommand classes
- Maintain backward compatibility with existing flat commands
- Enhanced help system with contextual guidance at each level
- Updated main CLI to show organized command groups
- Added comprehensive documentation for CLI reorganization
New structure:
- tito system (info, doctor, jupyter)
- tito module (status, test, notebooks)
- tito package (sync, reset, nbdev)
Benefits:
- Clear subsystem separation
- Intuitive command discovery
- Better extensibility for future commands
- Reduced cognitive load for users
- Add module.yaml files for setup, tensor, activations, layers, and autograd modules
- Enhanced tito status command with --metadata flag for rich information display
- Created metadata schema with learning objectives, dependencies, components, and more
- Added metadata generation script (bin/generate_module_metadata.py)
- Comprehensive documentation in docs/development/module-metadata-system.md
- Status command now shows module status, difficulty, time estimates, and detailed metadata
- Supports dependency tracking, component-level status, and educational information
- Enables rich CLI experience with structured module information
Vijay Janapa Reddi