This commit includes:
- Exported tinytorch package files from nbdev (autograd, losses, optimizers, training, etc.)
- Updated activations.py and layers.py with __call__ methods
- New module exports: attention, spatial, tokenization, transformer, etc.
- Removed old _modidx.py file
- Cleanup of duplicate milestone directories
These are the generated package files that correspond to the source modules
we've been developing. Students will import from these when using TinyTorch.
PROBLEM:
- nbdev requires #| export directive on EACH cell to export when using # %% markers
- Cell markers inside class definitions split classes across multiple cells
- Only partial classes were being exported to tinytorch package
- Missing matmul, arithmetic operations, and activation classes in exports
SOLUTION:
1. Removed # %% cell markers INSIDE class definitions (kept classes as single units)
2. Added #| export to imports cell at top of each module
3. Added #| export before each exportable class definition in all 20 modules
4. Added __call__ method to Sigmoid for functional usage
5. Fixed numpy import (moved to module level from __init__)
MODULES FIXED:
- 01_tensor: Tensor class with all operations (matmul, arithmetic, shape ops)
- 02_activations: Sigmoid, ReLU, Tanh, GELU, Softmax classes
- 03_layers: Linear, Dropout classes
- 04_losses: MSELoss, CrossEntropyLoss, BinaryCrossEntropyLoss classes
- 05_autograd: Function, AddBackward, MulBackward, MatmulBackward, SumBackward
- 06_optimizers: Optimizer, SGD, Adam, AdamW classes
- 07_training: CosineSchedule, Trainer classes
- 08_dataloader: Dataset, TensorDataset, DataLoader classes
- 09_spatial: Conv2d, MaxPool2d, AvgPool2d, SimpleCNN classes
- 10-20: All exportable classes in remaining modules
TESTING:
- Test functions use 'if __name__ == "__main__"' guards
- Tests run in notebooks but NOT on import
- Rosenblatt Perceptron milestone working perfectly
RESULT:
✅ All 20 modules export correctly
✅ Perceptron (1957) milestone functional
✅ Clean separation: development (modules/source) vs package (tinytorch)
- Remove circular imports where modules imported from themselves
- Convert tinytorch.core imports to sys.path relative imports
- Only import dependencies that are actually used in each module
- Preserve documentation imports in markdown cells
- Use consistent relative path pattern across all modules
- Remove hardcoded absolute paths in favor of relative imports
Affected modules: 02_activations, 03_layers, 04_losses, 06_optimizers,
07_training, 09_spatial, 12_attention, 17_quantization
- Fixed module 03_layers Tensor/Parameter comparison issues
- Fixed module 05_autograd psutil dependency (made optional)
- Removed duplicate 04_networks module
- Created losses.py with MSELoss and CrossEntropyLoss
- Created minimal MNIST training examples
- All 20 modules now pass individual tests
Note: Gradient flow still needs work for full training capability
🎯 NORTH STAR VISION DOCUMENTED:
'Don't Just Import It, Build It' - Training AI Engineers, not just ML users
AI Engineering emerges as a foundational discipline like Computer Engineering,
bridging algorithms and systems to build the AI infrastructure of the future.
🧪 ROBUST TESTING FRAMEWORK ESTABLISHED:
- Created tests/regression/ for sandbox integrity tests
- Implemented test-driven bug prevention workflow
- Clear separation: student tests (pedagogical) vs system tests (robustness)
- Every bug becomes a test to prevent recurrence
✅ KEY IMPLEMENTATIONS:
- NORTH_STAR.md: Vision for AI Engineering discipline
- Testing best practices: Focus on robust student sandbox
- Git workflow standards: Professional development practices
- Regression test suite: Prevent infrastructure issues
- Conv->Linear dimension tests (found CNN bug)
- Transformer reshaping tests (found GPT bug)
🏗️ SANDBOX INTEGRITY:
Students need a solid, predictable environment where they focus on ML concepts,
not debugging framework issues. The framework must be invisible.
📚 EDUCATIONAL PHILOSOPHY:
TinyTorch isn't just teaching a framework - it's founding the AI Engineering
discipline by training engineers who understand how to BUILD ML systems.
This establishes the foundation for training the first generation of true
AI Engineers who will define this emerging discipline.
Committing all remaining autograd and training improvements:
- Fixed autograd bias gradient aggregation
- Updated optimizers to preserve parameter shapes
- Enhanced loss functions with Variable support
- Added comprehensive gradient shape tests
This commit preserves the working state before cleaning up
the examples directory structure.
Implements comprehensive demo system showing AI capabilities unlocked by each module export:
- 8 progressive demos from tensor math to language generation
- Complete tito demo CLI integration with capability matrix
- Real AI demonstrations including XOR solving, computer vision, attention mechanisms
- Educational explanations connecting implementations to production ML systems
Repository reorganization:
- demos/ directory with all demo files and comprehensive README
- docs/ organized by category (development, nbgrader, user guides)
- scripts/ for utility and testing scripts
- Clean root directory with only essential files
Students can now run 'tito demo' after each module export to see their framework's
growing intelligence through hands-on demonstrations.
- Regenerate all .ipynb files from fixed .py modules
- Update tinytorch package exports with corrected implementations
- Sync package module index with current 16-module structure
These generated files reflect all the module fixes and ensure consistent
.py ↔ .ipynb conversion with the updated module implementations.
Major Educational Framework Enhancements:
• Deploy interactive NBGrader text response questions across ALL modules
• Replace passive question lists with active 150-300 word student responses
• Enable comprehensive ML Systems learning assessment and grading
TinyGPT Integration (Module 16):
• Complete TinyGPT implementation showing 70% component reuse from TinyTorch
• Demonstrates vision-to-language framework generalization principles
• Full transformer architecture with attention, tokenization, and generation
• Shakespeare demo showing autoregressive text generation capabilities
Module Structure Standardization:
• Fix section ordering across all modules: Tests → Questions → Summary
• Ensure Module Summary is always the final section for consistency
• Standardize comprehensive testing patterns before educational content
Interactive Question Implementation:
• 3 focused questions per module replacing 10-15 passive questions
• NBGrader integration with manual grading workflow for text responses
• Questions target ML Systems thinking: scaling, deployment, optimization
• Cumulative knowledge building across the 16-module progression
Technical Infrastructure:
• TPM agent for coordinated multi-agent development workflows
• Enhanced documentation with pedagogical design principles
• Updated book structure to include TinyGPT as capstone demonstration
• Comprehensive QA validation of all module structures
Framework Design Insights:
• Mathematical unity: Dense layers power both vision and language models
• Attention as key innovation for sequential relationship modeling
• Production-ready patterns: training loops, optimization, evaluation
• System-level thinking: memory, performance, scaling considerations
Educational Impact:
• Transform passive learning to active engagement through written responses
• Enable instructors to assess deep ML Systems understanding
• Provide clear progression from foundations to complete language models
• Demonstrate real-world framework design principles and trade-offs
- Export all modules with CIFAR-10 and checkpointing enhancements
- Create demo_cifar10_training.py showing complete pipeline
- Fix module issues preventing clean imports
- Validate all components work together
- Confirm students can achieve 75% CIFAR-10 accuracy goal
Pipeline validated:
✅ CIFAR-10 dataset downloading
✅ Model creation and training
✅ Checkpointing for best models
✅ Evaluation tools
✅ Complete end-to-end workflow
Assessment Results:
- 75% real implementation vs 25% educational scaffolding
- Working end-to-end training on CIFAR-10 dataset
- Comprehensive architecture coverage (MLPs, CNNs, Attention)
- Production-oriented features (MLOps, profiling, compression)
- Professional development workflow with CLI tools
Key Findings:
- Students build functional ML framework from scratch
- Real datasets and meaningful evaluation capabilities
- Progressive complexity through 16-module structure
- Systems engineering principles throughout
- Ready for serious ML systems education
Gaps Identified:
- GPU acceleration and distributed training
- Advanced optimizers and model serialization
- Some memory optimization opportunities
Recommendation: Excellent foundation for ML systems engineering education
- Flattened tests/ directory structure (removed integration/ and system/ subdirectories)
- Renamed all integration tests with _integration.py suffix for clarity
- Created test_utils.py with setup_integration_test() function
- Updated integration tests to use ONLY tinytorch package imports
- Ensured all modules are exported before running tests via tito export --all
- Optimized module test timing for fast execution (under 5 seconds each)
- Fixed MLOps test reliability and reduced timing parameters across modules
- Exported all modules (compression, kernels, benchmarking, mlops) to tinytorch package
- Switched from direct nbdev_export to tito export for proper control
- tito export 09_training: Managed conversion and export workflow
- tito export 08_optimizers: Ensured proper dependency resolution
- All modules automatically re-exported through tito system
- Updated _modidx.py with proper module index
Benefits of tito export:
- Consistent with TinyTorch CLI workflow
- Proper control over export process
- Professional export summary and feedback
- Handles conversion from .py to .ipynb automatically
- Maintains proper module dependencies and order
- Integrates with tito test system seamlessly
Test results:
- 09_training: 6/6 inline tests passed
- 08_optimizers: 5/5 inline tests passed
- 17/17 integration tests passed
- All tito-exported components working correctly
- Complete training pipeline functional via tito system
- Added package structure documentation explaining modules/source/ vs tinytorch.core.
- Enhanced mathematical foundations with linear algebra refresher and Universal Approximation Theorem
- Added real-world applications for each activation function (ReLU, Sigmoid, Tanh, Softmax)
- Included mathematical properties, derivatives, ranges, and computational costs
- Added performance considerations and numerical stability explanations
- Connected to production ML systems (PyTorch, TensorFlow, JAX equivalents)
- Implemented streamlined 'tito export' command with automatic .py → .ipynb conversion
- All functionality preserved: scripts run correctly, tests pass, package integration works
- Ready to continue with remaining modules (layers, networks, cnn, dataloader)
- Remove unnecessary module_paths.txt file for cleaner architecture
- Update export command to discover modules dynamically from modules/source/
- Simplify nbdev command to support --all and module-specific exports
- Use single source of truth: nbdev settings.ini for module paths
- Clean up import structure in setup module for proper nbdev export
- Maintain clean separation between module discovery and export logic
This implements a proper software engineering approach with:
- Single source of truth (settings.ini)
- Dynamic discovery (no hardcoded paths)
- Clean CLI interface (tito package nbdev --export [--all|module])
- Robust error handling with helpful feedback
- 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.
- 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
- 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
- Rename modules/data/ → modules/dataloader/
- Rename data_dev.py → dataloader_dev.py
- Update NBDev export target: core.data → core.dataloader
- Rename test files: test_data.py → test_dataloader.py
- Update package exports to tinytorch.core.dataloader
- Update module imports and internal references
This makes the module name more descriptive and aligned with ML industry standards.
- Add matmul_naive function with for-loop implementation for learning
- Update Dense layer to support both NumPy (@) and naive matrix multiplication
- Add comprehensive tests comparing both implementations (correctness & performance)
- Include step-by-step computation visualization for 2x2 matrices
- Fix missing imports in tensor.py and activations.py
- Export both tensor and activations modules to package
This provides students with immediate success using NumPy while allowing them to
understand the underlying computation through explicit for-loops. The scaffolding
includes performance comparisons and educational insights about why NumPy is faster.
- Ported all commands from bin/tito.py to new tito/ CLI architecture
- Added InfoCommand with system info and module status
- Added TestCommand with pytest integration
- Added DoctorCommand with environment diagnosis
- Added SyncCommand for nbdev export functionality
- Added ResetCommand for package cleanup
- Added JupyterCommand for notebook server
- Added NbdevCommand for nbdev development tools
- Added SubmitCommand and StatusCommand (placeholders)
- Fixed missing imports in tinytorch/core/tensor.py
- All commands now work with 'tito' command in shell
- Maintains professional architecture while restoring full functionality
Commands restored:
✅ info - System information and module status
✅ test - Run module tests with pytest
✅ doctor - Environment diagnosis
✅ sync - Export notebooks to package
✅ reset - Clean tinytorch package
✅ nbdev - nbdev development commands
✅ jupyter - Start Jupyter server
✅ submit - Module submission
✅ status - Module status
✅ notebooks - Build notebooks from Python files
The CLI now has both the professional architecture and all original functionality.
��️ Major architectural improvement implementing clean separation of concerns:
✨ NEW: Activations Module
- Complete activations module with ReLU, Sigmoid, Tanh implementations
- Educational NBDev structure with student TODOs + instructor solutions
- Comprehensive testing suite (24 tests) with mathematical correctness validation
- Visual learning features with matplotlib plotting (disabled during testing)
- Clean export to tinytorch.core.activations
🔧 REFACTOR: Layers Module
- Removed duplicate activation function implementations
- Clean import from activations module: 'from tinytorch.core.activations import ReLU, Sigmoid, Tanh'
- Updated documentation to reflect modular architecture
- Preserved all existing functionality while improving code organization
🧪 TESTING: Comprehensive Test Coverage
- All 24 activations tests passing ✅
- All 17 layers tests passing ✅
- Integration tests verify clean architecture works end-to-end
- CLI testing with 'tito test --module' works for both modules
📦 ARCHITECTURE: Clean Dependency Graph
- activations (math functions) → layers (building blocks) → networks (applications)
- Separation of concerns: pure math vs. neural network components
- Reusable components across future modules
- Single source of truth for activation implementations
�� PEDAGOGY: Enhanced Learning Experience
- Week-sized chunks: students master activations, then build layers
- Clear progression from mathematical foundations to applications
- Real-world software architecture patterns
- Modular design principles in practice
This establishes the foundation for scalable, maintainable ML systems education.
Introduces a Tensor class that wraps numpy arrays, enabling
fundamental ML operations like addition, subtraction,
multiplication, and division.
Adds utility methods such as reshape, transpose, sum, mean, max,
min, item, and numpy to the Tensor class.
Updates tests to accommodate both scalar and Tensor results
when checking mean values.
✅ Setup Module Implementation:
- Created comprehensive setup_dev.ipynb with TinyTorch workflow tutorial
- Added hello_tinytorch(), add_numbers(), and SystemInfo class
- Updated README with clear learning objectives and development workflow
- All 11 tests passing for complete workflow validation
🔧 CLI Enhancements:
- Added --module flag to 'tito sync' for module-specific exports
- Implemented 'tito reset' command with --force option
- Smart auto-generated file detection and cleanup
- Interactive confirmation with safety preservations
📚 Documentation Updates:
- Updated all references to use [module]_dev.ipynb naming convention
- Enhanced test coverage for new functionality
- Clear error handling and user guidance
This establishes the foundation workflow that students will use throughout TinyTorch development.
