- Phase 1: Inline unit tests (quick sanity checks)
- Phase 2: Module pytest with --tinytorch educational output
- Phase 3: Integration tests for modules 01-N
Added --unit-only and --no-integration flags for flexibility.
Students can now run comprehensive tests with clear feedback
about what each phase is checking and why it matters.
- Add --tinytorch flag documentation for Rich educational output
- Document WHAT/WHY/STUDENT LEARNING docstring format
- Show example of the docstring structure
New command shows all 21 modules with descriptions:
- tito module list - Shows numbered table of all modules
- Educational descriptions explain what each module covers
- Links to start and status commands for next steps
All 20 modules now have *_core.py test files with:
- Module-level context explaining WHY the component matters
- WHAT each test does
- WHY that behavior is important
- STUDENT LEARNING tips for understanding
Works with --tinytorch pytest flag for Rich CLI output.
- Create pytest_tinytorch.py plugin for educational test output
- Update test_tensor_core.py with WHAT/WHY/STUDENT LEARNING docstrings
- Show test purpose on pass, detailed context on failure
- Use --tinytorch flag to enable educational mode
Students can now understand what each test checks and why it matters.
- Update TransformerBlock to use mlp_ratio instead of hidden_dim
- Update PositionalEncoding argument order
- Fix MultiHeadAttention to use self-attention API
- Add missing MultiHeadAttention import
- tests/performance/: Referenced non-existent modules/ directory
- tests/system/: Required tinytorch.nn.functional which does not exist
- tests/regression/test_conv_linear_dimensions.py: Same issue
- These tests predated the API consolidation
- Module 06: 7 tests for SGD/Adam optimizer weight updates
- Module 12: 9 tests for attention computation and gradient flow
- Modules 14-20: Educational tests with skip for unexported modules
- All tests include docstrings explaining WHAT, WHY, and HOW
Removed tests that used old APIs (Variable, learning_rate, etc.):
- test_optimizers_integration.py
- test_module_dependencies.py
- integration_simple_test.py
- integration_xor_test.py
These are replaced by the new comprehensive tests:
- test_training_flow.py (8 tests)
- test_gradient_flow.py (6 tests)
- test_nlp_pipeline_flow.py (8 tests)
- test_cnn_integration.py (10 tests)
All 67 integration tests now pass.
The tests were creating losses incorrectly by breaking the computation graph:
WRONG: loss = Tensor(np.sum(output.data)) # Breaks graph!
RIGHT: loss = output.sum() # Maintains graph
Fixed:
- test_cnn_integration.py: Conv2d and CNN gradient tests
- test_nlp_pipeline_flow.py: Attention gradient tests
- Removed xfail marker from attention test (now passing)
The underlying Conv2d and Attention implementations were correct all along.
- Fix nn/__init__.py: alias Layer as Module for PyTorch compatibility
- Fix test_layers_integration.py: use package imports instead of sys.exit
- Fix test_optimizers_integration.py: use package imports instead of exec()
- Add ReLU, Sigmoid, Softmax, Tanh exports to nn module
New tests that catch module boundary bugs:
test_training_flow.py:
- Optimizer actually updates weights (SGD, Adam)
- Training reduces loss over iterations
- Gradient chain not broken through 5 layers
- Input receives gradients
- zero_grad works correctly
- Batch gradients are averaged
test_nlp_pipeline_flow.py:
- Embedding receives gradients
- Repeated tokens accumulate gradients
- Attention projections receive gradients
- Attention input receives gradients (xfail - known issue)
- Transformer block gradient flow
- Complete NLP pipeline end-to-end
README.md:
- Integration test philosophy
- Good vs bad integration test examples
- Coverage gaps and how to fill them
- Add --verbose flag to show commands as they execute
- Capture stdout/stderr for each check
- Save debug log to .tito/logs/preflight_TIMESTAMP.log
- Show failure details with command and output on failures
- Log file location shown when checks fail
- Shows 🚧 Under Construction badge next to brand
- Bar hides on scroll down, reappears on scroll up
- Always visible at top of page
- Badge hidden on mobile to save space
- Clean navigation bar: brand left, links right
- Icon+text buttons: MLSysBook, Subscribe, Star, Community
- Responsive: icons only on mobile
- Removed old WIP banner complexity
- Change from yellow 'Under Construction' to blue professional banner
- Add MLSysBook link, Community join CTA, GitHub link
- Remove duplicate header from intro.md (banner is on all pages now)
- Consistent branding across every page
- Add jupytext dependency to binder/requirements.txt
- Update postBuild to convert src/*.py files to modules/*.ipynb
- Document the notebook generation workflow in README.md
This ensures Binder users get ready-to-use notebooks that are
always in sync with the source Python files.
- Remove standalone verify command (redundant with system health)
- Add community map registration prompt at end of setup
- Setup now includes: venv, packages, profile, validation, community prompt
- Simplifies student journey: one command to get started
- Add tito verify command for setup validation and community registration
- Fix broken Dense import in tinytorch/__init__.py (class does not exist)
- Clean up layers.py __all__ to remove non-existent Dense and internal constants
- Add commonly used components to top-level exports:
- AvgPool2d, BatchNorm2d (spatial operations)
- RandomHorizontalFlip, RandomCrop, Compose (data augmentation)
- Total exports now 41 (was 35)
Package exports:
- Fix tinytorch/__init__.py to export all required components for milestones
- Add Dense as alias for Linear for compatibility
- Add loss functions (MSELoss, CrossEntropyLoss, BinaryCrossEntropyLoss)
- Export spatial operations, data loaders, and transformer components
Test infrastructure:
- Create tests/conftest.py to handle path setup
- Create tests/test_utils.py with shared test utilities
- Rename test_progressive_integration.py files to include module number
- Fix syntax errors in test files (spaces in class names)
- Remove stale test file referencing non-existent modules
Documentation:
- Update README.md with correct milestone file names
- Fix milestone requirements to match actual module dependencies
Export system:
- Run tito export --all to regenerate package from source modules
- Ensure all 20 modules are properly exported
Changes to README.md:
- Update Quick Start section to use `tito setup` instead of setup-environment.sh
- Change activation command to `source .venv/bin/activate`
- Update system check command from `tito system health` to `tito system doctor`
- Update module commands to use numbers (tito module start 01) instead of full names
- Update milestone/checkpoint commands to current CLI interface
- Change release banner to "December 2025 Pre-Release" with CLI focus
- Add user profile creation to setup features list
Changes to module ABOUT.md files:
- Update activation command from `source scripts/activate-tinytorch` to `source .venv/bin/activate`
- Update system check from `tito system health` to `tito system doctor`
Binder configuration verified:
- requirements.txt includes all necessary dependencies (numpy, rich, PyYAML, jupyter, matplotlib)
- postBuild script correctly installs TinyTorch package
- All deployment environments documented
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changes:
- Move profile.json from nested community/ to flat ~/.tinytorch/profile.json
- Add file update notifications when .tinytorch files are created/updated
- Print "📝 Updated: ~/.tinytorch/filename" for better visibility
- Update benchmark.py to use new flat structure
- Update auth.py to print when credentials are saved
Benefits:
- Simpler, flatter directory structure (no unnecessary nesting)
- Users see exactly which files are being modified during setup
- Consistent location for all user data (~/.tinytorch/)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
When user declined venv recreation, setup was still printing
"Setting up virtual environment..." before checking if it existed,
making it appear that recreation was proceeding anyway.
Changes:
- Check for existing venv before printing any messages
- Show "✅ Using existing virtual environment" when user declines
- Show "🐍 Recreating..." only when actually recreating
- Show "🐍 Setting up..." only for new venv creation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace plain argparse help with custom Rich-formatted output:
- Intercept --help flag before argparse processes it
- Show ASCII logo at top (consistent with tito alone)
- Display commands in beautiful Rich table with colors
- Reuse _generate_welcome_text() for consistency
- Add formatted global options section
Benefits:
- Consistent Rich formatting across tito and tito --help
- Professional table layout for commands (green names, dim descriptions)
- Color-coded sections (cyan headers, yellow options, green commands)
- Same visual experience whether you run tito or tito --help
- All command info dynamically pulled from self.commands dict
Before: Plain black-and-white argparse output
After: Colorful, formatted Rich output with ASCII logo and tables
Replace static hardcoded help text with dynamic generation from command registry:
- Create welcome_sections dict as single source of truth for examples
- Add _generate_welcome_text() for interactive mode (tito)
- Add _generate_epilog() for help mode (tito --help)
- Both screens now pull from same data structure
Benefits:
- No more forgetting to update help when commands change
- Student/Developer command lists auto-generated from self.commands dict
- Quick Start examples defined once, used in both places
- Ensures consistency between tito and tito --help outputs
Changes:
- tito/main.py: Replace 40+ lines of static text with 70 lines of dynamic generation
- Commands automatically categorized from student_commands/developer_commands lists
- Rich formatting maintained for interactive mode, stripped for plain --help
Standardize color usage to match TinyTorch CLI style guide:
- Replace [blue] with [cyan] for all action/info messages (10 instances)
- Replace [bold blue] with [bold cyan] for headers (1 instance)
- Replace "bold blue" with "bold cyan" for table headers (3 instances)
- Replace "bright_blue" with "bright_cyan" for panel borders (1 instance)
Files updated:
- tito/main.py: Welcome screen community commands now use [cyan]
- tito/commands/login.py: URL display now uses [cyan]
- tito/commands/protect.py: All 7 blue instances → cyan
- tito/commands/milestone.py: Table headers → bold cyan
- tito/commands/test.py: Table headers → bold cyan
- tito/commands/grade.py: Border style → bright_cyan
Result: Holistic CLI consistency with [cyan] for actions, [green] for success,
[yellow] for warnings, [red] for errors across all 15+ commands.
- Move login/logout from standalone commands to tito community subcommands
- Reduce community.py from 860 to 264 lines by removing placeholder profile code
- Delegate login/logout to existing LoginCommand/LogoutCommand (no auth code changes)
- Maintain leaderboard, compete, and submit functionality
- Apply consistent Rich formatting: ✅ emoji, [cyan] for actions, [green] for success
- Update main.py help text to show new command structure
Commands:
tito community login - OAuth login via browser
tito community logout - Clear credentials
tito community leaderboard - Open leaderboard
tito community compete - Open competitions
tito community submit - Validate/submit benchmarks
All auth/submission code unchanged. Style consistent with TinyTorch CLI conventions.
Changed all three URL references in paper.tex:
- Title page: mlsysbook.ai/tinytorch (was tinytorch.ai)
- Abstract: mlsysbook.ai/tinytorch (was tinytorch.ai)
- Conclusion: mlsysbook.ai/tinytorch (or tinytorch.ai)
This emphasizes the ML Systems Book ecosystem connection in academic
context while maintaining tinytorch.ai as alternate URL. The ecosystem
domain is more stable and institutional for paper citations.
Cleaned up Module 20 Capstone and MLPerf milestone descriptions:
- Removed CLI command examples (BenchmarkReport, generate_submission, tito community submit)
- Removed detailed infrastructure implementation
- Focused on learning outcomes and systems thinking pedagogy
- Maintained academic tone throughout
These changes complete the paper cleanup for release.
