github-starred/TinyTorch
2
0
Fork 0
mirror of https://github.com/MLSysBook/TinyTorch.git synced 2026-04-28 17:07:30 -05:00
Code Issues 7 Packages Projects Releases Wiki Activity

Clean up and modernize documentation

Browse Source 
- 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
This commit is contained in:
Vijay Janapa Reddi
2025-07-11 23:36:33 -04:00
parent b2794273f6
commit 71607f70e8
9 changed files with 493 additions and 1351 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
docs/README.md
View File

@@ -1,93 +1,108 @@
# 📚 TinyTorch Documentation
Welcome to the TinyTorch documentation! This directory contains guides organized by audience and purpose.
**Complete documentation for the TinyTorch ML Systems course.**
## 🎯 **Find Your Documentation**
## 🎯 **Quick Navigation**
### 🎓 **Students** (Taking the ML Systems Course)
**Start here if you're learning ML systems:**
### **For Students** 👨‍🎓
- **[Project Guide](students/project-guide.md)** - Complete course navigation and progress tracking
- **Start Here**: [`modules/setup/README.md`](../modules/setup/README.md) - First module setup
- **[Project Guide](students/project-guide.md)** - Track your progress through all 12 modules
- **[Quickstart](../quickstart.md)** - Get up and running quickly
- **[Main README](../README.md)** - Project overview and introduction
### **For Developers** 👨‍💻
- **[Development Guide](development/module-development-guide.md)** - Complete methodology and best practices
- **[Quick Reference](development/quick-module-reference.md)** - Commands and essential patterns
- **[Creation Checklist](development/module-creation-checklist.md)** - Step-by-step module creation
### 👨‍🏫 **Instructors** (Teaching or Designing the Course)
**Understanding the educational philosophy:**
### **For Instructors** 👨‍🏫
- **[Pedagogical Principles](pedagogy/pedagogical-principles.md)** - Educational philosophy and learning theory
- **[Testing Architecture](pedagogy/testing-architecture.md)** - Assessment and verification strategy
- **[Pedagogical Principles](pedagogy/pedagogical-principles.md)** - The "Build → Use → Understand" framework
- **[Vision](pedagogy/vision.md)** - High-level course philosophy and learning approach
- **[Testing Architecture](pedagogy/testing-architecture.md)** - Dual testing system for education
## 📁 **Documentation Structure**
### 🔧 **Human Developers** (Building New Modules)
**Creating or contributing to TinyTorch modules:**
### **Development** (`development/`)
**For module developers and contributors**
- `module-development-guide.md` - Complete development methodology
- `quick-module-reference.md` - Fast reference for commands and patterns
- `module-creation-checklist.md` - Comprehensive step-by-step process
- `module-template.md` - Reusable template snippets
- **[Development Guide](development/README.md)** - Start here for complete development methodology
- **[Module Development Guide](development/module-development-guide.md)** - Educational design and best practices
- **[Module Creation Checklist](development/module-creation-checklist.md)** - Step-by-step process
- **[Quick Reference](development/quick-module-reference.md)** - Commands and common patterns
### **Students** (`students/`)
**For course participants**
- `project-guide.md` - Course navigation and module progression
### 🤖 **AI Assistants** (Development Support)
**Coding patterns and quality enforcement:**
### **Pedagogy** (`pedagogy/`)
**For instructors and educational design**
- `pedagogical-principles.md` - Educational philosophy and learning theory
- `testing-architecture.md` - Assessment strategy and testing patterns
- `vision.md` - Course vision and goals
- **`.cursor/rules/`** - Specific implementation patterns, code examples, and anti-patterns
- **Automatic guidance** during development through cursor rules
## 🚀 **Quick Commands Reference**
## 📊 **Documentation Architecture**
### **Clear Audience Separation**
```
docs/
├── students/ # 🎓 Course participants
│ └── project-guide.md # Module progression and workflow
├── pedagogy/ # 👨‍🏫 Instructors and course designers
│ ├── pedagogical-principles.md # Educational theory
│ ├── vision.md # Course philosophy
│ └── testing-architecture.md # Assessment strategy
├── development/ # 🔧 Human module developers
│ ├── README.md # Development methodology
│ ├── module-development-guide.md # Complete guide
│ ├── module-creation-checklist.md # Step-by-step process
│ └── quick-module-reference.md # Commands and patterns
└── README.md # 📍 This file - navigation hub
.cursor/rules/ # 🤖 AI assistants (not in docs/)
├── module-development-best-practices.mdc # Coding patterns
├── testing-patterns.mdc # Test requirements
└── nbdev-educational-pattern.mdc # NBDev structure
### **System Commands**
```bash
tito system info # System information and course navigation
tito system doctor # Environment diagnosis
tito system jupyter # Start Jupyter Lab
```
### **No Duplication by Design**
- **Students**: Course navigation and module progression
- **Instructors**: Educational philosophy and theory
- **Human Developers**: Methodology, workflow, and educational design
- **AI Assistants**: Specific coding patterns and implementation examples
### **Module Development**
```bash
tito module status # Check all module status
tito module test --module X # Test specific module
tito module notebooks --module X # Convert Python to notebook
```
## 🚀 **Quick Navigation**
### **Package Management**
```bash
tito package sync # Export notebooks to package
tito package sync --module X # Export specific module
tito package reset # Reset package to clean state
```
| I am a... | I want to... | Go to... |
|-----------|--------------|----------|
| **Student** | Start the course | [Project Guide](students/project-guide.md) |
| **Student** | Get unstuck on setup | [Quickstart](../quickstart.md) |
| **Instructor** | Understand the pedagogy | [Pedagogical Principles](pedagogy/pedagogical-principles.md) |
| **Instructor** | Design a new course | [Vision](pedagogy/vision.md) |
| **Developer** | Build a new module | [Development Guide](development/README.md) |
| **Developer** | Need quick help | [Quick Reference](development/quick-module-reference.md) |
| **Contributor** | Understand the philosophy | [Pedagogical Principles](pedagogy/pedagogical-principles.md) |
## 🎓 **Educational Philosophy**
## 🔑 **Core Principles** (Across All Documentation)
TinyTorch follows a **"Build → Use → Understand → Repeat"** methodology where students:
### **Educational Excellence**
- **"Build → Use → Understand → Repeat"** - Every module follows this cycle
- **Real-world relevance** - Connect to production ML engineering
- **Immediate feedback** - Students see their code working
- **Progressive complexity** - Build understanding step by step
1. **Build** - Implement core ML components from scratch
2. **Use** - Apply their implementations to real problems
3. **Understand** - Reflect on design decisions and trade-offs
4. **Repeat** - Apply learnings to increasingly complex systems
### **Real Data, Real Systems**
- Use production datasets (CIFAR-10, ImageNet), not synthetic data
- Include progress feedback for downloads and long operations
- Test with realistic scales and performance constraints
- Think about caching, user experience, and systems concerns
### **Key Principles**
- **Real Data, Real Systems** - Use production datasets and realistic constraints
- **Progressive Complexity** - Build understanding step by step
- **Systems Thinking** - Connect to production ML engineering practices
- **Immediate Feedback** - Students see their code working quickly
## 🛠️ **Development Workflow**
### **For New Modules**
1. **Plan** - Choose real datasets, define learning objectives
2. **Implement** - Write complete working version first
3. **Structure** - Add educational content and TODO guidance
4. **Test** - Comprehensive testing with real data
5. **Export** - Convert to notebooks and export to package
### **For Students**
1. **Setup** - Complete environment setup in `modules/setup/`
2. **Develop** - Work in `modules/{name}/{name}_dev.py` files
3. **Export** - Use `tito package sync` to build package
4. **Test** - Use `tito module test` to verify implementation
5. **Progress** - Use `tito module status` to track completion
## 📊 **Course Structure**
TinyTorch is organized into progressive modules:
- **Setup** - Development environment and workflow
- **Tensor** - Core data structures and operations
- **Layers** - Neural network building blocks
- **Networks** - Complete model architectures
- **Training** - Optimization and learning algorithms
- **Advanced** - Production systems and MLOps
Each module builds on previous ones, creating a complete ML systems engineering curriculum.
---
*All documentation follows the TinyTorch principle: **Build → Use → Understand → Repeat***
**💡 Pro Tip**: Start with the [Project Guide](students/project-guide.md) if you're a student, or the [Development Guide](development/module-development-guide.md) if you're creating modules.

266
docs/development/cli-reorganization.md
View File

@@ -1,266 +0,0 @@
# CLI Reorganization: Hierarchical Command Structure
TinyTorch CLI has been reorganized into a clear hierarchical structure with three main command groups: `system`, `module`, and `package`. This provides better organization and makes it clear which subsystem each command operates on.
## New Command Structure
### System Commands (`tito system`)
**Environment, configuration, and system tools**
- `tito system info` - Show system information and course navigation
- `tito system doctor` - Run environment diagnosis
- `tito system jupyter` - Start Jupyter notebook server
### Module Commands (`tito module`)
**Development workflow and module management**
- `tito module status` - Check status of all modules
- `tito module test` - Run module tests
- `tito module notebooks` - Build notebooks from Python files
### Package Commands (`tito package`)
**nbdev integration and package management**
- `tito package sync` - Export notebook code to Python package
- `tito package reset` - Reset tinytorch package to clean state
- `tito package nbdev` - nbdev notebook development commands
## Benefits of Hierarchical Structure
### 1. **Clear Subsystem Separation**
Each command group operates on a specific subsystem:
- **System**: Environment and configuration
- **Module**: Individual module development
- **Package**: Overall package management
### 2. **Intuitive Command Discovery**
Users can explore commands by subsystem:
```bash
tito system # Shows all system commands
tito module # Shows all module commands
tito package # Shows all package commands
```
### 3. **Extensibility**
New commands can be easily categorized:
- Adding deployment tools? → `tito system deploy`
- Adding module generators? → `tito module create`
- Adding package publishing? → `tito package publish`
### 4. **Reduced Cognitive Load**
Instead of remembering 10+ flat commands, users think in terms of:
- What subsystem am I working with?
- What do I want to do in that subsystem?
## Usage Examples
### System Operations
```bash
# Check environment setup
tito system doctor
# Get system information
tito system info
# Start development environment
tito system jupyter
```
### Module Development
```bash
# Check module status with metadata
tito module status --metadata
# Test all modules
tito module test --all
# Test specific module
tito module test --module tensor
# Generate notebooks
tito module notebooks --module tensor
```
### Package Management
```bash
# Export modules to package
tito package sync
# Export specific module
tito package sync --module tensor
# Reset package to clean state
tito package reset
# Run nbdev commands
tito package nbdev --export
```
## Backward Compatibility
The old flat command structure is still supported for backward compatibility:
```bash
# These still work (legacy commands)
tito status
tito test --all
tito sync
tito info
```
However, the new hierarchical structure is recommended for new usage.
## Migration Guide
### For Users
**Old → New Command Mapping:**
```bash
# System commands
tito info → tito system info
tito doctor → tito system doctor
tito jupyter → tito system jupyter
# Module commands
tito status → tito module status
tito test → tito module test
tito notebooks → tito module notebooks
# Package commands
tito sync → tito package sync
tito reset → tito package reset
tito nbdev → tito package nbdev
```
### For Scripts
Update automation scripts to use the new structure:
```bash
# Old
./scripts/test-all.sh:
tito test --all
# New (recommended)
./scripts/test-all.sh:
tito module test --all
```
## Implementation Details
### Command Group Classes
Each command group is implemented as a separate class:
- `SystemCommand` - Handles system subcommands
- `ModuleCommand` - Handles module subcommands
- `PackageCommand` - Handles package subcommands
### Argument Parsing
Uses argparse subparsers for clean hierarchical structure:
```python
# Main parser
parser = argparse.ArgumentParser(prog="tito")
subparsers = parser.add_subparsers(dest='command')
# System group
system_parser = subparsers.add_parser('system')
system_subparsers = system_parser.add_subparsers(dest='system_command')
# System subcommands
system_subparsers.add_parser('info')
system_subparsers.add_parser('doctor')
system_subparsers.add_parser('jupyter')
```
### Help System
Each level provides contextual help:
```bash
tito # Shows command groups
tito system # Shows system subcommands
tito module # Shows module subcommands
tito package # Shows package subcommands
```
## Future Enhancements
### Additional Command Groups
The structure supports adding new command groups:
```bash
# Deployment commands
tito deploy status
tito deploy docker
tito deploy cloud
# Research commands
tito research benchmark
tito research profile
tito research compare
```
### Command Aliases
Short aliases for common commands:
```bash
# System
tito sys info # alias for tito system info
# Module
tito mod status # alias for tito module status
tito mod test # alias for tito module test
# Package
tito pkg sync # alias for tito package sync
```
### Interactive Mode
Enhanced interactive command discovery:
```bash
tito interactive
# → Shows menu of command groups
# → Allows drilling down into subcommands
# → Provides guided command building
```
## Best Practices
### 1. **Use Hierarchical Commands**
Prefer the new structure for clarity:
```bash
# Good
tito module status --metadata
# Avoid (legacy)
tito status --metadata
```
### 2. **Think in Subsystems**
When adding new functionality, consider which subsystem it belongs to:
- Environment/config → `system`
- Individual modules → `module`
- Overall package → `package`
### 3. **Consistent Naming**
Use consistent naming patterns within each group:
- `status` for checking state
- `test` for running tests
- `sync` for synchronization
- `reset` for cleanup
### 4. **Help Documentation**
Always provide clear help text for new commands:
```python
parser.add_parser('new-command', help='Clear description of what this does')
```
## Conclusion
The hierarchical CLI structure provides:
- **Better organization** with clear subsystem separation
- **Improved discoverability** through logical grouping
- **Enhanced extensibility** for future commands
- **Maintained compatibility** with existing workflows
This structure scales well as TinyTorch grows and provides a professional CLI experience that matches industry standards.

143
docs/development/command-cleanup-summary.md
View File

@@ -1,143 +0,0 @@
# TinyTorch CLI Command Cleanup Summary
## Overview
Cleaned up the TinyTorch CLI to remove duplication and provide clear separation of concerns between different types of status checking and testing.
## Commands Removed
### 1. `tito status` ❌ **REMOVED**
- **Reason**: Unimplemented stub that just showed "not yet implemented"
- **Replacement**: `tito modules` provides actual module status functionality
- **Files deleted**: `tito/commands/status.py`
### 2. `tito submit` ❌ **REMOVED**
- **Reason**: Unimplemented stub that just showed "not yet implemented"
- **Replacement**: Not needed for core workflow
- **Files deleted**: `tito/commands/submit.py`
## Commands Updated
### 1. `tito test` ✅ **UPDATED**
- **Before**: Duplicated functionality with `tito modules --test`
- **After**: Focused on individual module testing with detailed output
- **Key changes**:
- `tito test --all` now redirects to `tito modules --test` with recommendation
- `tito test --module X` provides detailed test output for single modules
- Better error handling with helpful available modules list
### 2. `tito modules` ✅ **NEW**
- **Purpose**: Comprehensive module status checking
- **Features**:
- Scans all modules in `modules/` directory
- Checks file structure (dev file, tests, README)
- Runs tests with `--test` flag
- Shows detailed breakdown with `--details` flag
## Final Command Structure
### Core Commands
```bash
tito info # TinyTorch package functionality status
tito modules # Module development status overview
tito modules --test # Run all module tests (recommended)
tito modules --details # Detailed module file structure
tito test --module X # Individual module test with detailed output
```
### Development Commands
```bash
tito sync # Export notebooks to package
tito notebooks # Build notebooks from Python files
tito doctor # Environment diagnosis
tito jupyter # Start Jupyter server
```
### Utility Commands
```bash
tito reset # Reset package state
tito nbdev # NBDev operations
```
## Benefits of Cleanup
### ✅ **Eliminated Duplication**
- No more overlapping functionality between `test --all` and `modules --test`
- Removed unimplemented stub commands
- Clear purpose for each command
### ✅ **Improved User Experience**
- `tito test --all` provides helpful redirection to better command
- Better error messages with available modules listed
- Clear separation between overview and detailed testing
### ✅ **Cleaner Architecture**
- Focused command purposes
- No confusing "not implemented" messages
- Consistent command patterns
## Command Purpose Matrix
| Command | Purpose | Scope | Output |
|---------|---------|-------|--------|
| `tito info` | Package functionality | TinyTorch package | What students can use |
| `tito modules` | Module development status | All modules | Development progress |
| `tito modules --test` | Test all modules | All modules | Test results overview |
| `tito test --module X` | Individual module testing | Single module | Detailed test output |
| `tito doctor` | Environment diagnosis | System | Environment health |
| `tito sync` | Export to package | Notebooks → Package | Build process |
## Usage Examples
### Check Overall Status
```bash
# What can students use?
tito info
# What modules are complete?
tito modules
# Which tests are passing?
tito modules --test
```
### Individual Module Development
```bash
# Test specific module with detailed output
tito test --module tensor
# Check detailed file structure
tito modules --details
# Export module to package
tito sync --module tensor
```
### Environment Management
```bash
# Check environment health
tito doctor
# Start development environment
tito jupyter
```
## Migration Guide
### Old → New Command Mapping
| Old Command | New Command | Notes |
|-------------|-------------|-------|
| `tito status --module X` | `tito modules` | Shows all modules, not just one |
| `tito test --all` | `tito modules --test` | Better overview format |
| `tito submit --module X` | *Removed* | Not needed for core workflow |
### Recommended Workflow
1. **Start development**: `tito doctor` → `tito info`
2. **Check progress**: `tito modules`
3. **Test modules**: `tito modules --test`
4. **Debug individual**: `tito test --module X`
5. **Export to package**: `tito sync`
This cleanup provides a much cleaner and more focused CLI experience with clear separation of concerns and no confusing duplicate functionality.

272
docs/development/module-creation-checklist.md
View File

@@ -1,175 +1,165 @@
# 📋 TinyTorch Module Creation Checklist
# 📋 Module Creation Checklist
**Step-by-step checklist for creating high-quality educational modules following TinyTorch standards.**
**Comprehensive step-by-step guide for creating high-quality TinyTorch modules.**
*📖 For complete methodology, see [Module Development Guide](module-development-guide.md)*
## 🎯 **Planning Phase**
## 🎯 Pre-Development
### **Module Design**
- [ ] **Choose real dataset** (CIFAR-10, ImageNet, etc. - no synthetic data)
- [ ] **Define learning objectives** (what will students build and understand?)
- [ ] **Identify production connections** (how does this relate to real ML systems?)
- [ ] **Plan visual feedback** (how will students see their code working?)
- [ ] **Design progression** (easy → medium → hard with clear indicators)
### Planning Phase
- [ ] Read [Module Development Guide](module-development-guide.md)
- [ ] Define learning objectives: What will students implement?
- [ ] Choose production dataset: What real data will they use?
- [ ] Map to real-world: How does this connect to production ML?
- [ ] Design progression: Easy → Medium → Hard complexity
### **Educational Approach**
- [ ] **Choose learning pattern**: Build → Use → [Reflect/Analyze/Optimize]
- [ ] **Plan immediate feedback** (students see results quickly)
- [ ] **Design real-world connections** (production ML relevance)
- [ ] **Structure progressive complexity** (build understanding step by step)
### Prerequisites Check
- [ ] Understand NBDev educational pattern
- [ ] Review existing modules (tensor, layers, activations) for patterns
- [ ] Identify module dependencies and integration points
## 🛠️ **Implementation Phase**
## 📁 Module Structure Setup
### **Core Development**
- [ ] **Create module directory**: `modules/{module}/`
- [ ] **Create main file**: `{module}_dev.py` with Jupytext header
- [ ] **Add NBDev directives**: `#| default_exp core.{module}` at top
- [ ] **Implement complete working version** first (get it working)
- [ ] **Add educational structure** (markdown explanations, TODO guidance)
- [ ] **Include visual feedback** (development only, not exported)
- [ ] **Add progress indicators** for long operations
### Required Files
- [ ] Create `modules/{module}/` directory
- [ ] Create `modules/{module}/tests/` directory
- [ ] Create `modules/{module}/{module}_dev.py` - Main implementation
- [ ] Create `modules/{module}/README.md` - Module guide
- [ ] Create `modules/{module}/tests/test_{module}.py` - Test suite
### **File Structure**
```
modules/{module}/
├── {module}_dev.py # Main development file
├── module.yaml # Simple metadata
├── tests/
│ └── test_{module}.py # Comprehensive tests
└── README.md # Module overview
```
## 🔧 Implementation Phase
### **Educational Content**
- [ ] **Clear conceptual explanations** before implementation
- [ ] **Comprehensive TODO guidance** with approach, examples, hints
- [ ] **Real-world context** and production connections
- [ ] **Visual confirmation** of working code (development only)
- [ ] **Progressive difficulty** with clear indicators
### File Header & Structure
- [ ] Add Jupytext header with correct format
- [ ] Add `#| default_exp core.{module}` directive
- [ ] Include module title and learning objectives in markdown
- [ ] Import required libraries with proper organization
## 🧪 **Testing Phase**
### Educational Content
- [ ] **Step 1**: Concept explanation with real-world motivation
- [ ] **Step 2**: Core implementation with comprehensive TODO guidance
- [ ] **Step 3**: Advanced features and system integration
- [ ] **Step 4**: Testing with real data and visual feedback
- [ ] **Step 5**: Summary and connections to next modules
### **Test Creation**
- [ ] **Create test file**: `tests/test_{module}.py`
- [ ] **Use real data** throughout (no mock/synthetic data)
- [ ] **Test realistic scales** (performance at real data sizes)
- [ ] **Include edge cases** (empty input, wrong shapes, etc.)
- [ ] **Add performance tests** (reasonable execution time)
### Implementation Pattern (for each major component)
- [ ] **Student version**: Complete signature + comprehensive TODO
- [ ] **Hidden implementation**: Working code with `#| hide` + `#| export`
- [ ] **Immediate testing**: Real data tests after each component
- [ ] **Visual feedback**: Show results working (development only)
### **Test Verification**
- [ ] **All tests pass**: `tito module test --module {module}`
- [ ] **Tests use real data** (production datasets, realistic parameters)
- [ ] **Performance acceptable** (reasonable execution time)
- [ ] **Edge cases covered** (error handling, boundary conditions)
## 📝 Code Quality Standards
## 📦 **Integration Phase**
### Student-Facing Code
- [ ] Complete function signatures with type hints
- [ ] Comprehensive docstrings (Args, Returns, Raises)
- [ ] Detailed TODO with APPROACH, EXAMPLE, HINTS, SYSTEMS THINKING
- [ ] Clear `NotImplementedError` messages
- [ ] Real data examples, not synthetic
### **Package Export**
- [ ] **Export to package**: `tito package sync --module {module}`
- [ ] **Verify exports**: Check `tinytorch/core/{module}.py` exists
- [ ] **Test imports**: `from tinytorch.core.{module} import ClassName`
- [ ] **No circular dependencies** or import issues
### Hidden Implementation
- [ ] Working, tested code that passes all tests
- [ ] Efficient implementation following best practices
- [ ] Proper error handling and edge cases
- [ ] Consistent with TinyTorch patterns
### **CLI Integration**
- [ ] **Status shows correctly**: `tito module status`
- [ ] **Tests run via CLI**: `tito module test --module {module}`
- [ ] **Notebooks convert**: `tito module notebooks --module {module}`
### Real Data Requirements
- [ ] Use production datasets (CIFAR-10, not mock data)
- [ ] Include progress bars for downloads/long operations
- [ ] Implement proper caching for repeated use
- [ ] Test with realistic data scales and timing
## 📚 **Documentation Phase**
## 🧪 Testing Requirements
### **Module Documentation**
- [ ] **Create README.md** with overview and usage examples
- [ ] **Document learning objectives** and key concepts
- [ ] **Include usage examples** (both Python and notebook)
- [ ] **Add troubleshooting** common issues
### Test Structure
- [ ] Import from `{module}_dev` (instructor version)
- [ ] Use real datasets, not mocks or synthetic data
- [ ] Test with actual data characteristics (shapes, types, ranges)
- [ ] Include performance tests with realistic constraints
### **Metadata**
- [ ] **Create module.yaml** with basic info (name, title, description)
- [ ] **Set dependencies** (prerequisites, builds_on, enables)
- [ ] **Define exports_to** (tinytorch package location)
### Test Coverage
- [ ] **Component Creation**: Object initialization with real data
- [ ] **Core Functionality**: Main methods work with production data
- [ ] **Integration**: Components work together in realistic scenarios
- [ ] **Edge Cases**: Error handling with actual edge cases
- [ ] **Performance**: Reasonable performance with real data scales
## ✅ **Quality Assurance**
## 📖 Documentation Standards
### **Code Quality**
- [ ] **Real data throughout** (no synthetic/mock data)
- [ ] **Progress feedback** for long operations
- [ ] **Visual confirmation** of working code
- [ ] **Performance optimized** for student experience
- [ ] **Clean exports** (development richness separate from package)
### README Requirements
- [ ] Module title with clear learning objectives
- [ ] "What You'll Build" section with concrete examples
- [ ] Getting started steps (1-4)
- [ ] Real-world connections and applications
- [ ] Technical requirements and dependencies
- [ ] Success criteria and verification steps
### **Educational Quality**
- [ ] **Clear learning progression** (Build → Use → [Pattern])
- [ ] **Immediate feedback** and validation
- [ ] **Real-world relevance** and connections
- [ ] **Comprehensive guidance** (approach, examples, hints)
- [ ] **Appropriate difficulty** progression
### Quality Standards
- [ ] Clear, motivating language
- [ ] Specific examples using real data
- [ ] Systems thinking connections
- [ ] Appropriate difficulty progression
- [ ] Consistent formatting and style
### **Systems Quality**
- [ ] **Error handling** and graceful failures
- [ ] **Memory efficiency** for large datasets
- [ ] **Caching** for repeated operations
- [ ] **User experience** considerations
- [ ] **Production-ready** patterns
## 🔄 Development Workflow
## 🔄 **Conversion & Export**
### Implementation Steps
- [ ] Write complete implementation first (get it working)
- [ ] Add NBDev markers and educational structure
- [ ] Create comprehensive tests with real data
- [ ] Add visual feedback and progress indicators
- [ ] Test both instructor and student paths
### **Notebook Generation**
- [ ] **Convert to notebook**: `tito module notebooks --module {module}`
- [ ] **Verify notebook structure** (cells, markdown, code)
- [ ] **Test in Jupyter**: Open and run the generated notebook
### Conversion & Export
- [ ] Convert to notebook: `python bin/tito.py notebooks --module {module}`
- [ ] Export to package: `python bin/tito.py sync --module {module}`
- [ ] Run tests: `python bin/tito.py test --module {module}`
- [ ] Verify imports: `from tinytorch.core.{module} import ClassName`
### **Package Integration**
- [ ] **Export to package**: `tito package sync --module {module}`
- [ ] **Verify package structure**: Check `tinytorch/core/`
- [ ] **Test imports**: Import from package works correctly
- [ ] **Run integration tests**: All modules still work together
## ✅ Quality Assurance
## 🎯 **Final Verification**
### Before Release
- [ ] All automated tests pass with real data
- [ ] Student TODO guidance is comprehensive and helpful
- [ ] Visual feedback works (development only, not exported)
- [ ] Progress indicators for long operations
- [ ] Clean separation between development and exports
- [ ] Follows "Build → Use → Understand" progression
### **Student Experience**
- [ ] **Clear learning objectives** achieved
- [ ] **Immediate feedback** throughout
- [ ] **Real-world connections** obvious
- [ ] **Smooth difficulty progression**
- [ ] **Comprehensive guidance** without being prescriptive
### Integration Testing
- [ ] Module exports correctly to `tinytorch.core.{module}`
- [ ] No circular import issues
- [ ] Compatible with existing modules
- [ ] Works with TinyTorch CLI tools
- [ ] Consistent with established patterns
### **Technical Excellence**
- [ ] **All tests pass** with real data
- [ ] **Performance acceptable** at realistic scales
- [ ] **Clean code structure** and organization
- [ ] **Proper error handling** and edge cases
- [ ] **Integration works** with existing modules
### Student Experience
- [ ] Clear learning progression
- [ ] Immediate feedback and validation
- [ ] Real-world relevance and connections
- [ ] Motivating and engaging content
- [ ] Smooth transition to next modules
### **Production Readiness**
- [ ] **Real datasets** used throughout
- [ ] **Production patterns** demonstrated
- [ ] **Systems thinking** integrated
- [ ] **Performance considerations** addressed
- [ ] **User experience** optimized
## 🎯 Final Verification
## 🚀 **Release Checklist**
### Technical Excellence
- [ ] Code follows TinyTorch style guidelines
- [ ] Efficient implementation with proper error handling
- [ ] Real data usage throughout
- [ ] Performance optimized for student experience
### **Final Steps**
- [ ] **All tests pass**: `tito module test --module {module}`
- [ ] **Package exports**: `tito package sync --module {module}`
- [ ] **Documentation complete**: README, docstrings, examples
- [ ] **Integration verified**: Works with other modules
- [ ] **Student path tested**: Follow your own guidance
### Educational Excellence
- [ ] Clear learning objectives achieved
- [ ] Progressive complexity with appropriate difficulty
- [ ] Real-world systems thinking integrated
- [ ] Immediate gratification and visual confirmation
### Documentation Complete
- [ ] README is comprehensive and motivating
- [ ] Code comments are clear and helpful
- [ ] TODO guidance includes systems thinking
- [ ] Integration with course progression documented
### **Commit and Deploy**
- [ ] **Commit changes**: Git commit with descriptive message
- [ ] **Update main status**: `tito module status` shows complete
- [ ] **Verify CLI integration**: All commands work correctly
- [ ] **Test end-to-end**: Full student workflow functions
---
## 🚀 Ready to Release
Once all items are checked:
- [ ] Module follows all TinyTorch standards
- [ ] Students can successfully complete the module
- [ ] Real data is used throughout
- [ ] Visual feedback enhances learning
- [ ] Systems thinking is integrated
- [ ] Production relevance is clear
**Remember**: We're teaching ML systems engineering with real-world practices, not just algorithms!
**💡 Remember**: This is ML systems engineering education. Every module should reflect real-world practices while maintaining educational excellence. Students are building production-quality skills, not just academic exercises.

4
docs/development/module-development-guide.md
View File

@@ -172,8 +172,8 @@ def test_with_real_data():
### Step 5: Convert and Export
```bash
# Convert to notebook
python bin/tito.py notebooks --module {module}
# Convert to notebook (using Jupytext)
tito module notebooks --module {module}
# Export to package
python bin/tito.py sync --module {module}

343
docs/development/module-metadata-system.md
View File

@@ -1,343 +0,0 @@
# Module Metadata System
TinyTorch uses a comprehensive metadata system to track module information, learning objectives, dependencies, and implementation status. Each module contains a `module.yaml` file that provides structured information for CLI tools, documentation generation, and progress tracking.
## Overview
The metadata system enables:
- **Rich status reporting** with `tito status --metadata`
- **Dependency tracking** and prerequisite checking
- **Learning objective documentation** for educational purposes
- **Progress tracking** for students and instructors
- **Automated documentation** generation
- **Component-level status** tracking
## Metadata Schema
Each `module.yaml` file follows this comprehensive schema:
### Basic Information
```yaml
name: "module_name"
title: "Module Title - Brief Description"
description: "Detailed description of what the module teaches and implements"
version: "1.0.0"
author: "TinyTorch Team"
last_updated: "2024-12-19"
```
### Module Status
```yaml
status: "complete" # complete, in_progress, not_started, deprecated
implementation_status: "stable" # stable, beta, alpha, experimental, planned
```
**Status Values:**
- `complete`: Module is fully implemented and tested
- `in_progress`: Module is being actively developed
- `not_started`: Module is planned but not yet implemented
- `deprecated`: Module is no longer maintained
**Implementation Status:**
- `stable`: Production-ready, well-tested
- `beta`: Feature-complete but may have minor issues
- `alpha`: Basic functionality working but incomplete
- `experimental`: Early development, may change significantly
- `planned`: Not yet implemented
### Learning Information
```yaml
learning_objectives:
- "Understand core concepts and their importance"
- "Implement key algorithms and data structures"
- "Apply knowledge to real-world problems"
key_concepts:
- "Concept 1"
- "Concept 2"
- "Concept 3"
```
### Dependencies
```yaml
dependencies:
prerequisites: ["setup", "tensor"] # Must complete before this module
builds_on: ["tensor"] # Direct dependencies
enables: ["layers", "networks"] # Modules that depend on this one
```
### Educational Metadata
```yaml
difficulty: "intermediate" # beginner, intermediate, advanced
estimated_time: "4-6 hours"
pedagogical_pattern: "Build → Use → Understand"
```
**Pedagogical Patterns:**
- `Build → Use → Understand`: Standard TinyTorch pattern
- `Build → Use → Reflect`: Emphasizes design trade-offs
- `Build → Use → Analyze`: Technical depth with profiling
- `Build → Use → Optimize`: Systems iteration focus
### Implementation Details
```yaml
components:
- name: "ComponentName"
type: "class" # class, function, methods, system
description: "What this component does"
status: "complete" # complete, in_progress, not_started
```
### Package Export Information
```yaml
exports_to: "tinytorch.core.module_name"
export_directive: "core.module_name"
```
### Testing Information
```yaml
test_coverage: "comprehensive" # comprehensive, partial, minimal, none, planned
test_count: 25
test_categories:
- "Basic functionality"
- "Edge cases"
- "Error handling"
```
### File Structure
```yaml
required_files:
- "module_dev.py"
- "module_dev.ipynb"
- "tests/test_module.py"
- "README.md"
```
### Systems Focus
```yaml
systems_concepts:
- "Memory management"
- "Performance optimization"
- "Error handling"
```
### Real-world Applications
```yaml
applications:
- "Neural network training"
- "Computer vision"
- "Natural language processing"
```
### Next Steps
```yaml
next_modules: ["next_module1", "next_module2"]
completion_criteria:
- "All tests pass"
- "Can implement basic functionality"
- "Understand core concepts"
```
## CLI Integration
The metadata system integrates with the TinyTorch CLI:
### Basic Status Check
```bash
tito status
```
Shows module completion status with basic file structure information.
### Enhanced Status with Metadata
```bash
tito status --metadata
```
Shows comprehensive table with:
- Module status (complete/in_progress/not_started)
- Difficulty level
- Time estimates
- File structure status
### Detailed Metadata View
```bash
tito status --metadata
```
Also includes detailed metadata section showing:
- Learning objectives
- Dependencies
- Component status
- Key concepts
- Next steps
## Creating Module Metadata
### 1. Create the metadata file
```bash
touch modules/your_module/module.yaml
```
### 2. Use the template
Copy from an existing module or use the schema above.
### 3. Customize for your module
- Set appropriate status and difficulty
- List learning objectives
- Define dependencies
- Document components
- Set time estimates
### 4. Test the metadata
```bash
tito status --metadata
```
## Example: Complete Module Metadata
```yaml
# modules/tensor/module.yaml
name: "tensor"
title: "Tensor - Core Data Structure"
description: "Implement the fundamental data structure that powers all ML systems"
version: "1.0.0"
author: "TinyTorch Team"
last_updated: "2024-12-19"
status: "complete"
implementation_status: "stable"
learning_objectives:
- "Understand tensors as N-dimensional arrays"
- "Implement arithmetic operations"
- "Handle shape management and broadcasting"
key_concepts:
- "N-dimensional arrays"
- "Broadcasting"
- "Memory layout"
dependencies:
prerequisites: ["setup"]
builds_on: ["setup"]
enables: ["activations", "layers", "networks"]
difficulty: "intermediate"
estimated_time: "4-6 hours"
pedagogical_pattern: "Build → Use → Understand"
components:
- name: "Tensor"
type: "class"
description: "Core tensor class"
status: "complete"
exports_to: "tinytorch.core.tensor"
export_directive: "core.tensor"
test_coverage: "comprehensive"
test_count: 25
required_files:
- "tensor_dev.py"
- "tensor_dev.ipynb"
- "tests/test_tensor.py"
- "README.md"
next_modules: ["activations", "layers"]
completion_criteria:
- "All tests pass"
- "Can perform tensor operations"
- "Ready for neural networks"
```
## Benefits
### For Students
- **Clear learning paths** with prerequisite tracking
- **Time estimation** for planning study sessions
- **Progress tracking** with component-level status
- **Learning objectives** for focused study
### For Instructors
- **Course planning** with dependency graphs
- **Progress monitoring** across all modules
- **Curriculum organization** with difficulty levels
- **Assessment planning** with completion criteria
### For Developers
- **System overview** with component status
- **Dependency management** for development planning
- **Testing coverage** tracking
- **Documentation generation** from metadata
## Best Practices
### 1. Keep Metadata Current
- Update status when implementation changes
- Refresh time estimates based on student feedback
- Add new components as they're implemented
### 2. Clear Learning Objectives
- Write specific, measurable objectives
- Focus on understanding, not just implementation
- Connect to real-world applications
### 3. Accurate Dependencies
- List only direct prerequisites
- Distinguish between prerequisites and enables
- Keep dependency graphs acyclic
### 4. Realistic Time Estimates
- Base on actual student completion times
- Include time for understanding, not just coding
- Account for debugging and testing
### 5. Component Granularity
- Break large modules into logical components
- Track status at meaningful granularity
- Use descriptive component names
## Integration with Other Systems
### Documentation Generation
Metadata can be used to automatically generate:
- Module overview pages
- Dependency graphs
- Learning path documentation
- Progress tracking dashboards
### Testing Integration
Metadata supports:
- Test coverage tracking
- Component-level test organization
- Automated test discovery
- Progress-based test selection
### CLI Enhancement
The metadata system enables:
- Rich status reporting
- Dependency checking
- Progress visualization
- Learning path recommendations
## Future Enhancements
### Planned Features
- **Dependency visualization** with graph generation
- **Learning path optimization** based on prerequisites
- **Progress dashboards** for course management
- **Automated testing** based on component status
- **Documentation generation** from metadata
- **Integration with git** for automatic updates
### Extensibility
The YAML format allows for:
- Custom fields for specific use cases
- Institution-specific metadata
- Research project tracking
- Performance benchmarking data
## Conclusion
The module metadata system provides a foundation for rich educational experiences in TinyTorch. By maintaining comprehensive metadata, we enable better learning outcomes, clearer progress tracking, and more effective course management.
The system balances simplicity with power, providing essential information while remaining easy to maintain and extend.

317
docs/development/quick-module-reference.md
View File

@@ -1,55 +1,43 @@
# 🚀 TinyTorch Module Development - Quick Reference
# 🚀 Quick Module Reference
## 🧠 Choose Your Learning Pattern First
**Fast reference for module development - commands, patterns, and essential workflows.**
**Before writing any code, decide which engagement pattern fits your module:**
## 🔥 **Essential Commands**
### **🤔 Build → Use → Reflect** (Design & Systems Thinking)
- **Best for**: Early modules, foundational concepts, design decisions
- **Focus**: "Why did we make this choice? What are the trade-offs?"
- **Activities**: Design comparisons, trade-off analysis, systems implications
- **Examples**: Setup, Tensor, Layers, Data
### **🔍 Build → Use → Analyze** (Technical Depth)
- **Best for**: Middle modules, performance-critical components
- **Focus**: "How does this actually work? Where are the bottlenecks?"
- **Activities**: Profiling, debugging, measurement, technical investigation
- **Examples**: Training, Autograd, Profiling, Benchmarking
### **⚡ Build → Use → Optimize** (Systems Iteration)
- **Best for**: Advanced modules, production-focused components
- **Focus**: "How can we make this better? How does it scale?"
- **Activities**: Performance improvement, scaling, iteration, optimization
- **Examples**: MLOps, Kernels, Compression, Distributed
### **Decision Questions**
1. **What type of learning is most important?** (Conceptual/Technical/Optimization)
2. **Where does this fit in progression?** (Early/Middle/Advanced)
3. **What skills do students need most?** (Design thinking/Debugging/Performance)
### **Document Your Choice**
```markdown
## 🎯 Learning Pattern: Build → Use → [Pattern]
**Pattern Choice**: [Reflect/Analyze/Optimize]
**Rationale**: [Why this pattern fits the learning objectives]
**Key Activities**:
- [Specific activity 1]
- [Specific activity 2]
- [Specific activity 3]
### **System Commands**
```bash
tito system info # System information and course navigation
tito system doctor # Environment diagnosis
tito system jupyter # Start Jupyter Lab
```
---
### **Module Commands**
```bash
tito module status # Check all module status
tito module status --details # Detailed file structure
tito module test --module X # Test specific module
tito module test --all # Test all modules
tito module notebooks --module X # Convert Python to notebook (Jupytext)
```
## 📋 Development Checklist
### **Package Commands**
```bash
tito package sync # Export all notebooks to package
tito package sync --module X # Export specific module
tito package reset # Reset package to clean state
tito package nbdev --export # Run nbdev export
```
### 1. Plan Module
- [ ] **Choose engagement pattern** (Reflect/Analyze/Optimize)
- [ ] Define learning objectives (what students will implement)
- [ ] Choose difficulty levels (🟢 easy → 🟡 medium → 🔴 hard)
## 🎯 **Development Workflow**
### **1. Module Planning**
- [ ] Choose real dataset (CIFAR-10, ImageNet, etc.)
- [ ] Define learning objectives and progression
- [ ] Identify production ML connections
- [ ] Plan visual feedback and progress indicators
- [ ] Decide what to provide vs. what students implement
### 2. Write Complete Implementation
### **2. Write Complete Implementation**
Create `modules/{module}/{module}_dev.py`:
```python
# %% [markdown]
@@ -62,129 +50,190 @@ Create `modules/{module}/{module}_dev.py`:
# Learning objectives and overview
# %%
#| keep_imports
#| default_exp core.{module}
import numpy as np
# %%
#| export
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
"""
{Description of the class}
TODO: {What students need to implement}
APPROACH:
1. {Step 1 with specific guidance}
2. {Step 2 with specific guidance}
3. {Step 3 with specific guidance}
EXAMPLE:
Input: {concrete_example}
Expected: {expected_output}
HINTS:
- {Helpful hint about approach}
- {Systems thinking hint}
- {Real-world connection}
"""
def __init__(self, params):
raise NotImplementedError("Student implementation required")
# %%
#| hide
#| export
class YourClass:
"""Complete implementation (hidden from students)."""
def __init__(self, params):
# Actual working implementation
pass
#| exercise_end
```
### 3. Design Pattern-Specific Activities
### **3. Design Pattern-Specific Activities**
- **Reflect**: Add reflection questions and trade-off analysis
- **Analyze**: Include profiling tools and debugging exercises
- **Optimize**: Create performance challenges and iteration tasks
### 4. Convert and Generate
### **4. Convert and Generate**
```bash
# Convert Python to notebook
python bin/tito.py notebooks --module {module}
# Convert Python to notebook (using Jupytext)
tito module notebooks --module {module}
# Generate student version
python3 bin/generate_student_notebooks.py --module {module}
```
### 5. Test and Verify
### **5. Test and Verify**
```bash
# 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}
tito package sync --module {module}
tito module test --module {module}
```
## 🏷️ Essential Markers
## 🏷️ **Essential NBDev Directives**
| Marker | Purpose | Example |
|--------|---------|---------|
| `#| exercise_start/end` | Mark student implementation | Method body |
| `#| difficulty: easy\|medium\|hard` | Visual indicator | 🟢🟡🔴 |
| `#| hint:` | Guide student thinking | Multiple allowed |
| `#| solution_test:` | Verification guidance | Expected behavior |
| `#| keep_imports` | Preserve imports | Setup code |
| `#| keep_complete` | Keep full implementation | Utilities |
| `#| remove_cell` | Remove from student version | Instructor notes |
| Directive | Purpose | Example |
|-----------|---------|---------|
| `#| default_exp core.{module}` | Set export destination | Top of file |
| `#| export` | Export to package | Classes/functions |
| `#| hide` | Hide from students | Instructor solutions |
| `#| hide #| export` | Export but hide | Complete implementations |
## 🎨 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
## 🎯 Pattern-Specific Activities
### **Reflection Activities**
- Design comparison questions
- Trade-off analysis exercises
- "What if we had different constraints?" scenarios
- Connection to production systems
### **Analysis Activities**
- Profiling memory usage and performance
- Debugging exercises with real issues
- Measurement and interpretation tasks
- Technical investigation challenges
### **Optimization Activities**
- Performance improvement challenges
- Scaling exercises with larger datasets
- Iteration on system design
- Benchmarking and comparison tasks
## ✅ Quality Check
**Before release:**
- [ ] **Pattern choice documented** with clear rationale
- [ ] **Pattern-specific activities** included and tested
- [ ] 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
## 📁 **Module Structure**
```
modules/{module}/
├── {module}_dev.py # 🔧 Write this first (with pattern choice)
├── {module}_dev.ipynb # 📓 Generated
├── {module}_dev_student.ipynb # 🎓 Auto-generated
├── test_{module}.py # 🧪 Test suite
└── README.md # 📖 Module guide (include pattern)
├── {module}_dev.py # Main development file (Jupytext format)
├── {module}_dev.ipynb # Jupyter notebook (auto-generated)
├── module.yaml # Simple metadata (name, title, description, etc.)
├── tests/
│ └── test_{module}.py # Comprehensive pytest tests
└── README.md # Module overview and usage
```
## 💡 Pro Tips
## ⚡ **Common Patterns**
1. **Choose pattern first** - Everything else flows from this decision
2. **Write complete implementation first** - Get it working before adding markers
3. **Design pattern-specific activities** - Make them engaging and educational
4. **Test the student path** - Follow your own hints to verify they work
5. **Be generous with hints** - Better too helpful than too cryptic
6. **Document your pattern choice** - Help future developers understand your reasoning
## 🛠️ Common Commands
```bash
# 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}
### **Real Data Loading**
```python
# ✅ Good: Real data with progress feedback
def load_cifar10():
"""Load CIFAR-10 with progress bar."""
from tqdm import tqdm
# Show download progress
# Cache for performance
# Handle errors gracefully
```
*See [Module Development Guide](module-development-guide.md) for complete details and [Pedagogical Principles](../pedagogy/pedagogical-principles.md) for the full framework.*
### **Visual Feedback (Development Only)**
```python
# Development visualization (not exported)
def _show_results(data):
"""Show visual confirmation (development only)."""
if not _in_development():
return
plt.figure(figsize=(10, 6))
# Rich visualization
plt.show()
```
### **Student Implementation Guidance**
```python
def method_to_implement(self):
"""
TODO: Implement this method
APPROACH:
1. Parse input data and validate shapes
2. Apply the core algorithm step by step
3. Return results in expected format
EXAMPLE:
Input: tensor([1, 2, 3])
Expected: tensor([2, 4, 6])
HINTS:
- Start with the simple case first
- Think about edge cases (empty input, wrong shapes)
- Use vectorized operations for performance
"""
raise NotImplementedError("Student implementation required")
```
## 🧪 **Testing Patterns**
### **Test with Real Data**
```python
def test_with_real_data():
"""Test with actual production data."""
# Load real dataset
data = load_real_cifar10_sample()
# Test with realistic parameters
model = YourClass(realistic_params)
result = model.process(data)
# Verify real properties
assert result.shape == expected_shape
assert result.dtype == expected_dtype
```
### **Performance Testing**
```python
def test_performance():
"""Ensure reasonable performance."""
import time
large_data = create_realistic_large_dataset()
start = time.time()
result = process(large_data)
elapsed = time.time() - start
# Should complete in reasonable time
assert elapsed < 5.0 # 5 seconds max
```
## 🎯 **Quality Checklist**
### **Before Release**
- [ ] Uses real data throughout (no synthetic/mock data)
- [ ] Includes progress feedback for long operations
- [ ] Provides visual confirmation of working code
- [ ] Tests with realistic data scales
- [ ] Follows "Build → Use → [Pattern]" progression
- [ ] Comprehensive TODO guidance with examples
- [ ] Clean separation: rich development, clean exports
### **Integration Testing**
- [ ] Module exports correctly to `tinytorch.core.{module}`
- [ ] No circular import issues
- [ ] Compatible with existing modules
- [ ] Works with TinyTorch CLI tools
- [ ] Consistent with established patterns
---
**💡 Pro Tip**: Start with real data and production concerns first. Educational structure and TODO guidance come after you have working, realistic code.

172
docs/development/testing-separation.md
View File

@@ -1,172 +0,0 @@
# Testing and Status Separation in TinyTorch
## Overview
TinyTorch now has **two separate systems** for checking different aspects of the project:
1. **Module Status Checking** - Are the individual modules working and passing their tests?
2. **TinyTorch Package Checking** - Are the core capabilities available in the exported package?
## 1. Module Status Checking: `tito modules`
**Purpose**: Check the development status of individual modules in the `modules/` directory.
**What it checks**:
- ✅ **File Structure**: Does the module have required files (`{module}_dev.py`, `tests/test_{module}.py`, `README.md`)?
- ✅ **Test Results**: Do the module's tests pass when run with pytest?
- ✅ **Development Progress**: Which modules are complete vs. incomplete?
**Commands**:
```bash
# Basic module status overview
tito modules
# Run tests for all modules and show results
tito modules --test
# Show detailed file structure breakdown
tito modules --details
```
**Example Output**:
```
Module Status Overview
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Module ┃ Dev File ┃ Tests ┃ README ┃ Test Results ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ activations │ ✅ │ ✅ │ ✅ │ ✅ Passed │
│ tensor │ ✅ │ ✅ │ ✅ │ ❌ Failed │
│ autograd │ ❌ │ ❌ │ ❌ │ No tests │
└─────────────────┴──────────────┴──────────────┴──────────────┴──────────────────────┘
📊 Summary: 7/16 modules complete, 4/16 tests passing
```
## 2. TinyTorch Package Checking: `tito info`
**Purpose**: Check if the exported TinyTorch package has the required functionality available.
**What it checks**:
- ✅ **Package Capabilities**: Can you import and use core TinyTorch functionality?
- ✅ **Functional Integration**: Do the different components work together?
- ✅ **Student Experience**: What can students actually use from the package?
**Commands**:
```bash
# Check TinyTorch package functionality
tito info
# Show hello message if setup is working
tito info --hello
```
**Example Output**:
```
🚀 Module Implementation Status
┏━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ Project ┃ Status ┃ Description ┃
┡━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ Tensor │ ✅ Implemented │ basic tensor operations │
│ 2 │ Layers │ ✅ Implemented │ neural network building blocks │
│ 6 │ DataLoader │ ✅ Implemented │ data loading pipeline │
│ 7 │ Training │ ⏳ Not Started │ autograd engine & optimization │
└─────┴──────────────┴────────────────────┴──────────────────────────────────────────┘
```
## Key Differences
### Module Status (`tito modules`)
- **Scope**: Individual module development files
- **Focus**: Development workflow and testing
- **Checks**: File structure, test execution, completion status
- **Audience**: Developers working on modules
- **Granularity**: Per-module basis
### Package Status (`tito info`)
- **Scope**: Exported TinyTorch package functionality
- **Focus**: Student experience and package capabilities
- **Checks**: Import capabilities, functional integration
- **Audience**: Students using the package
- **Granularity**: Functional capabilities
## Use Cases
### For Module Developers
```bash
# Check which modules need work
tito modules
# Test all modules during development
tito modules --test
# See detailed breakdown of missing files
tito modules --details
```
### For Students/Users
```bash
# Check what TinyTorch features are available
tito info
# Test that my environment is working
tito info --hello
```
### For Instructors
```bash
# Check overall course progress
tito modules --test
# Verify student experience
tito info
# Run specific module tests
tito test --module tensor
```
## Architecture Benefits
### ✅ **Clear Separation of Concerns**
- Module development workflow vs. package functionality
- Different audiences, different needs
- No confusion between "learning modules" and "package capabilities"
### ✅ **Accurate Status Reporting**
- Module status reflects development progress
- Package status reflects student experience
- No false positives from organizational mismatches
### ✅ **Educational Value**
- Students see what they can actually use
- Developers see what needs to be implemented
- Clear progression from module → package → student usage
## Implementation Notes
### Module Status Implementation
- Scans `modules/` directory automatically
- Checks for required files: `{module}_dev.py`, `tests/test_{module}.py`, `README.md`
- Runs pytest on test files when `--test` flag is used
- Provides detailed file structure breakdown with `--details`
### Package Status Implementation
- Tests actual import capabilities from `tinytorch` package
- Checks functional integration (e.g., can you create a tensor and use it?)
- Focuses on **capabilities** not **module organization**
- Maps learning modules to functional components
## Future Enhancements
### Module Status
- Add git status integration
- Show module dependencies
- Track completion percentages
- Add module-specific metrics
### Package Status
- Add performance benchmarks
- Show version compatibility
- Add integration test results
- Track API completeness
This separation provides a much clearer picture of both development progress and student experience, avoiding the confusion that arose from trying to map pedagogical structure directly to package organization.

170
docs/students/project-guide.md
View File

@@ -10,10 +10,10 @@ Track your progress through the course:
- [ ] **Module 0: Setup** - Environment & CLI setup
- [ ] **Module 1: Tensor** - Core tensor operations
- [ ] **Module 2: MLP** - Multi-layer perceptron
- [ ] **Module 3: CNN** - Convolutional networks
- [ ] **Module 2: Layers** - Neural network layers
- [ ] **Module 3: Networks** - Complete model architectures
- [ ] **Module 4: Autograd** - Automatic differentiation
- [ ] **Module 5: Data** - Data loading pipeline
- [ ] **Module 5: DataLoader** - Data loading pipeline
- [ ] **Module 6: Training** - Training loop & optimization
- [ ] **Module 7: Config** - Configuration system
- [ ] **Module 8: Profiling** - Performance profiling
@@ -26,24 +26,24 @@ Track your progress through the course:
### First Time Setup
1. **Clone the repository**
2. **Go to**: [`modules/setup/README.md`](modules/setup/README.md)
2. **Go to**: [`modules/setup/README.md`](../../modules/setup/README.md)
3. **Follow all setup instructions**
4. **Verify with**: `python modules/setup/check_setup.py`
4. **Verify with**: `tito system doctor`
### Daily Workflow
```bash
cd TinyTorch
source .venv/bin/activate # Always activate first!
python bin/tito.py info # Check system status
tito system info # Check system status
```
## 📋 Module Development Workflow
Each module follows this pattern:
1. **Read overview**: `modules/[name]/README.md`
2. **Work in notebook**: `modules/[name]/[name]_dev.ipynb`
3. **Export code**: `python bin/tito.py sync`
4. **Run tests**: `python bin/tito.py test --module [name]`
2. **Work in Python file**: `modules/[name]/[name]_dev.py`
3. **Export code**: `tito package sync`
4. **Run tests**: `tito module test --module [name]`
5. **Move to next module when tests pass**
## 📚 Module Details
@@ -51,7 +51,7 @@ Each module follows this pattern:
### 🔧 Module 0: Setup
**Goal**: Get your development environment ready
**Time**: 30 minutes
**Location**: [`modules/setup/`](modules/setup/)
**Location**: [`modules/setup/`](../../modules/setup/)
**Key Tasks**:
- [ ] Create virtual environment
@@ -62,8 +62,8 @@ Each module follows this pattern:
**Verification**:
```bash
python modules/setup/check_setup.py # Should show all ✅
python bin/tito.py test --module setup
tito system doctor # Should show all ✅
tito module test --module setup
```
---
@@ -71,10 +71,10 @@ python bin/tito.py test --module setup
### 🔢 Module 1: Tensor
**Goal**: Build the core tensor system
**Prerequisites**: Module 0 complete
**Location**: [`modules/tensor/`](modules/tensor/)
**Location**: [`modules/tensor/`](../../modules/tensor/)
**Key Tasks**:
- [ ] Implement `Tensor` class in notebook
- [ ] Implement `Tensor` class
- [ ] Basic operations (add, mul, reshape)
- [ ] Memory management
- [ ] Shape validation
@@ -82,37 +82,40 @@ python bin/tito.py test --module setup
**Verification**:
```bash
python bin/tito.py test --module tensor
tito module test --module tensor
```
---
### 🧠 Module 2: MLP
**Goal**: Build multi-layer perceptron
### 🧠 Module 2: Layers
**Goal**: Build neural network layers
**Prerequisites**: Module 1 complete
**Location**: [`modules/mlp/`](modules/mlp/)
**Location**: [`modules/layers/`](../../modules/layers/)
**Key Tasks**:
- [ ] Implement `Linear` layer
- [ ] Activation functions (ReLU, Sigmoid)
- [ ] Forward pass
- [ ] Basic backward pass
- [ ] Train on MNIST
- [ ] Forward pass implementation
- [ ] Parameter management
- [ ] Layer composition
**Target**: >95% accuracy on MNIST
**Verification**:
```bash
tito module test --module layers
```
---
### 🖼️ Module 3: CNN
**Goal**: Build convolutional neural networks
### 🖼️ Module 3: Networks
**Goal**: Build complete neural networks
**Prerequisites**: Module 2 complete
**Location**: [`modules/cnn/`](modules/cnn/)
**Location**: [`modules/networks/`](../../modules/networks/)
**Key Tasks**:
- [ ] Implement `Conv2d` layer
- [ ] `MaxPool2d` layer
- [ ] Padding and stride support
- [ ] Train CNN on CIFAR-10
- [ ] Implement `Sequential` container
- [ ] CNN architectures
- [ ] Model saving/loading
- [ ] Train on CIFAR-10
**Target**: >80% accuracy on CIFAR-10
@@ -121,7 +124,7 @@ python bin/tito.py test --module tensor
### ⚡ Module 4: Autograd
**Goal**: Automatic differentiation engine
**Prerequisites**: Module 3 complete
**Location**: [`modules/autograd/`](modules/autograd/)
**Location**: [`modules/autograd/`](../../modules/autograd/)
**Key Tasks**:
- [ ] Computational graph construction
@@ -136,7 +139,7 @@ python bin/tito.py test --module tensor
### 📊 Module 5: DataLoader
**Goal**: Efficient data loading
**Prerequisites**: Module 4 complete
**Location**: [`modules/dataloader/`](modules/dataloader/)
**Location**: [`modules/dataloader/`](../../modules/dataloader/)
**Key Tasks**:
- [ ] Custom `DataLoader` implementation
@@ -149,7 +152,7 @@ python bin/tito.py test --module tensor
### 🎯 Module 6: Training
**Goal**: Complete training system
**Prerequisites**: Module 5 complete
**Location**: [`modules/training/`](modules/training/)
**Location**: [`modules/training/`](../../modules/training/)
**Key Tasks**:
- [ ] Training loop implementation
@@ -163,7 +166,7 @@ python bin/tito.py test --module tensor
### ⚙️ Module 7: Config
**Goal**: Configuration management
**Prerequisites**: Module 6 complete
**Location**: [`modules/config/`](modules/config/)
**Location**: [`modules/config/`](../../modules/config/)
**Key Tasks**:
- [ ] YAML configuration system
@@ -176,7 +179,7 @@ python bin/tito.py test --module tensor
### 📊 Module 8: Profiling
**Goal**: Performance measurement
**Prerequisites**: Module 7 complete
**Location**: [`modules/profiling/`](modules/profiling/)
**Location**: [`modules/profiling/`](../../modules/profiling/)
**Key Tasks**:
- [ ] Memory profiler
@@ -189,7 +192,7 @@ python bin/tito.py test --module tensor
### 🗜️ Module 9: Compression
**Goal**: Model compression techniques
**Prerequisites**: Module 8 complete
**Location**: [`modules/compression/`](modules/compression/)
**Location**: [`modules/compression/`](../../modules/compression/)
**Key Tasks**:
- [ ] Pruning implementation
@@ -199,78 +202,87 @@ python bin/tito.py test --module tensor
---
### 🔥 Module 10: Kernels
### ⚡ Module 10: Kernels
**Goal**: Custom compute kernels
**Prerequisites**: Module 9 complete
**Location**: [`modules/kernels/`](modules/kernels/)
**Location**: [`modules/kernels/`](../../modules/kernels/)
**Key Tasks**:
- [ ] Optimized matrix multiplication
- [ ] Vectorized operations
- [ ] CPU optimization
- [ ] CUDA kernel implementation
- [ ] Performance optimization
- [ ] Memory coalescing
- [ ] Kernel benchmarking
---
### 📈 Module 11: Benchmarking
**Goal**: Performance benchmarking system
**Goal**: Performance benchmarking
**Prerequisites**: Module 10 complete
**Location**: [`modules/benchmarking/`](modules/benchmarking/)
**Location**: [`modules/benchmarking/`](../../modules/benchmarking/)
**Key Tasks**:
- [ ] Benchmark suite implementation
- [ ] Performance regression testing
- [ ] Comparative analysis
- [ ] Automated reporting
- [ ] Benchmarking framework
- [ ] Performance comparisons
- [ ] Scaling analysis
- [ ] Optimization recommendations
---
### 🚀 Module 12: MLOps
**Goal**: Production monitoring and deployment
**Goal**: Production monitoring
**Prerequisites**: Module 11 complete
**Location**: [`modules/mlops/`](modules/mlops/)
**Location**: [`modules/mlops/`](../../modules/mlops/)
**Key Tasks**:
- [ ] Model monitoring
- [ ] Performance tracking
- [ ] Alert systems
- [ ] Production deployment
- [ ] A/B testing framework
- [ ] Performance dashboards
## 🧪 Testing Strategy
## 🛠️ Essential Commands
### Module-Level Testing
### **System Commands**
```bash
# Test specific module
python bin/tito.py test --module tensor
# Test all modules
python bin/tito.py test
# Check overall status
python bin/tito.py info
tito system info # System information and course navigation
tito system doctor # Environment diagnosis
tito system jupyter # Start Jupyter Lab
```
### Integration Testing
Each module integrates into the main `tinytorch` package through nbdev:
- Notebooks automatically export to `tinytorch/core/`
- Integration tests verify cross-module compatibility
- Final package assembly validates the complete system
### **Module Development**
```bash
tito module status # Check all module status
tito module test --module X # Test specific module
tito module test --all # Test all modules
tito module notebooks --module X # Convert Python to notebook
```
## 🏆 Completion Criteria
### **Package Management**
```bash
tito package sync # Export all notebooks to package
tito package sync --module X # Export specific module
tito package reset # Reset package to clean state
```
A module is complete when:
- [ ] All notebook cells run without errors
- [ ] `tito sync` exports code successfully
- [ ] `tito test --module [name]` passes all tests
- [ ] Integration with previous modules works
- [ ] Ready to proceed to next module
## 🎯 **Success Criteria**
## 🎓 Learning Philosophy
Each module is complete when:
- [ ] **All tests pass**: `tito module test --module [name]`
- [ ] **Code exports**: `tito package sync --module [name]`
- [ ] **Understanding verified**: Can explain key concepts and trade-offs
- [ ] **Ready for next**: Prerequisites met for following modules
This course teaches **systems thinking** by building one cohesive ML system rather than isolated components. Each module contributes essential functionality that later modules depend upon, creating a complete, production-ready machine learning framework.
## 🆘 **Getting Help**
## 💡 Need Help?
### **Troubleshooting**
- **Environment Issues**: `tito system doctor`
- **Module Status**: `tito module status --details`
- **Integration Issues**: Check `tito system info`
- **Quick Start**: See [`modules/setup/QUICKSTART.md`](modules/setup/QUICKSTART.md)
- **Development Workflow**: Each module's README.md
- **CLI Reference**: `python bin/tito.py --help`
- **Integration Issues**: Check `python bin/tito.py info`
### **Resources**
- **Course Overview**: [Main README](../../README.md)
- **Development Guide**: [Module Development](../development/module-development-guide.md)
- **Quick Reference**: [Commands and Patterns](../development/quick-module-reference.md)
---
**💡 Pro Tip**: Use `tito module status` regularly to track your progress and see which modules are ready to work on next!