Clean /tmp/TinyTorch before EACH GIF generation, not just once at the start.
VHS executes real commands and captures actual output, so if /tmp/TinyTorch exists from a previous GIF, the git clone will fail with 'already exists' error.
Now each GIF gets a clean environment:
🧹 Cleaning /tmp/TinyTorch for this GIF...
This ensures GIF 01 shows successful clone on every generation.
Fixed GIFs 02, 03, and 04 to activate the environment before running tito commands.
Without activation, tito commands fail with 'command not found' error.
Each GIF now starts with:
Type "source activate.sh"
Sleep 300ms
Enter
Sleep 1s
This ensures tito is available in PATH before any tito commands execute.
GIF 01 already had activation as part of the setup workflow demo.
Test script now measures actual execution time for every command using Python's time.time(), outputting recommendations to /tmp/tinytorch_timing.txt.
Measured timings:
- git clone: 3s (varies by network, using safe 3s)
- setup-environment.sh: 9s (measured 8.6s)
- tito system health: 0.5s (show for 3s for readability)
- tito module status: 0.2s (show for 3s)
- tito logo: 0.1s (show for 6s)
Updated 01-zero-to-ready.tape with measured delays to ensure:
- GIF shows actual command completion
- No typing ahead before previous command finishes
- Realistic demo of student experience
This fixes the issue where VHS would type commands faster than they execute.
Students should see the clean first-time workflow, not our test infrastructure.
Changes:
- VHS tape: Shows 'cd /tmp' then 'git clone' (no rm -rf)
- generate.sh: Cleans /tmp/TinyTorch BEFORE running VHS
- test_demo_workflow.sh: Already cleaned before testing
- README: Documents the separation of concerns
This presents the ideal student experience while maintaining reproducibility:
- Students: See clean setup flow (cd → clone → setup)
- Scripts: Handle cleanup behind the scenes
- Tests: Validate fresh environment every time
GIF size: 494KB → 467KB (optimized further)
Document the improved demo testing and generation workflow:
- Explains test_demo_workflow.sh purpose and usage
- Describes cleanup strategy to prevent 'directory exists' errors
- Provides troubleshooting guide for common issues
- Documents best practices for updating demo commands
- Maps file locations and workflow architecture
This ensures future demo updates maintain quality and accuracy.
- Create comprehensive test script for demo workflow validation
- Clean /tmp/TinyTorch before cloning to avoid conflicts
- Test full workflow: clone, setup, tito commands
- Update VHS tapes with proper cleanup steps
- Fix command names (tito status -> tito module status)
- Regenerate all 4 demo GIFs with corrected commands
- Log all test output for validation
Removed orphaned/duplicate files not referenced in table of contents:
- INSTRUCTOR_GUIDE.md (duplicate of instructor-guide.md)
- STUDENT_QUICKSTART.md (duplicate of quickstart-guide.md)
- TEAM_ONBOARDING.md (moved to usage-paths/)
- checkpoint-system.md (not in TOC, minimal refs)
- learning-progress.md (not in TOC, minimal refs)
- learning-journey-visual.md (not in TOC, self-ref only)
- cifar10-training-guide.md (no references)
- cover.md (not in TOC)
- PRIVACY_DATA_RETENTION.md (internal doc)
- INSTRUCTOR.md (root level, moved to docs/)
- Various old scripts (activate-tinytorch, cleanup scripts, etc.)
Website rebuilt successfully with 46 warnings (same as before).
All critical content preserved (student-workflow, quickstart-guide, etc.)
- Delete tito/commands/doctor.py (replaced by health/check commands)
- Update export.py: system doctor → system health
- Update help.py: system doctor → system health (4 occurrences)
- Update module_workflow.py: system doctor → system health
- Update setup.py: system doctor → system health
- Update src.py: system doctor → system health
Completes migration from 'tito system doctor' to new command structure.
- Add quiet=False parameter to enable_autograd()
- Suppress print statements when quiet=True
- Check TINYTORCH_QUIET env var on module import
- Allows CLI tools to import tinytorch silently
- Students still see helpful messages in notebooks
- health: Show only ✅/❌ status (no version numbers)
- info: Remove dependency table (use 'system version' instead)
- Clear separation: health=status, info=resources, version=versions
Enhanced the tito logo command with a personal message from Professor Vijay
Janapa Reddi explaining how TinyTorch grew from the TinyML movement at Harvard.
The message emphasizes the importance of engineering ML systems from first
principles and includes the memorable Lego/Star Wars analogy.
Key changes:
- Added personal signature with Harvard CS 249R affiliation
- Included TinyML movement origin story in conversational, italic style
- Emphasized "engineer" as the core philosophy
- Added Lego blocks analogy for building from scratch
- Updated catchphrase: "The future of ML is tiny and bright—don't just 'import torch', build it."
- Updated tagline: "Start tiny. Go deep. Build big."
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changed banner to display 'Tiny🔥TORCH' with capital T to match
the official brand style.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
## Symlink Updates (modules/ → src/)
- Update all 20 site/modules/*_ABOUT.md symlinks to point to src/
- Update all 20 src/*/ABOUT.md internal references
## Infrastructure Changes
- Remove bin/ directory scripts (moved to scripts/ in previous commit)
- Update .envrc: Reference new scripts/ directory structure
- Update pyproject.toml: Reflect src/ as primary source location
- Update docs/development/MODULE_ABOUT_TEMPLATE.md: src/ paths
- Update site/requirements.txt: Documentation dependencies
## Restructuring Complete
The repository now has clean separation:
- `src/`: Developer source code (graded notebooks with solutions)
- `modules/`: Student workspace (generated from src/)
- `scripts/`: Build and utility scripts
- `site/`: Documentation and Jupyter Book website
This enables the intended workflow:
1. Developers work in src/
2. Students receive generated notebooks in modules/
3. Both can coexist without conflicts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added comprehensive role-based documentation:
- 👥 Three user personas: Student, Instructor, Developer
- Visual 3-column layout with workflows for each role
- New Developer Commands section with tito src commands
- Separate workflow sections for Students vs Developers
- Clear directory structure explanation
Benefits:
- Users immediately see relevant commands for their role
- Reduces confusion about src/ vs modules/
- Makes tito src commands discoverable
- Professional UX with visual separation
Fixes:
- module complete: Update paths to use src/ for source files
- module complete: Fix export call to use new SourceCommand API
- milestone run: Remove nonexistent progress_tracker dependency
- milestone run: Use progress.json directly for prerequisite checking
Both commands now work correctly with new directory structure
Documents:
- COMMAND_HIERARCHY.md: Complete command structure and workflows
- TEST_RESULTS.md: Detailed test findings and bug list
Shows what works, what's broken, and what needs implementation
Major directory restructure to support both developer and learner workflows:
Structure Changes:
- NEW: src/ directory for Python source files (version controlled)
- Files renamed: tensor.py → 01_tensor.py (matches directory naming)
- All 20 modules moved from modules/ to src/
- CHANGED: modules/ now holds generated notebooks (gitignored)
- Generated from src/*.py using jupytext
- Learners work in notebooks, developers work in Python source
- UNCHANGED: tinytorch/ package (still auto-generated from notebooks)
Workflow: src/*.py → modules/*.ipynb → tinytorch/*.py
Command Updates:
- Updated export command to read from src/ and generate to modules/
- Export flow: discovers modules in src/, converts to notebooks in modules/, exports to tinytorch/
- All 20 modules tested and working
Configuration:
- Updated .gitignore to ignore modules/ directory
- Updated README.md with new three-layer architecture explanation
- Updated export.py source mappings and paths
Benefits:
- Clean separation: developers edit Python, learners use notebooks
- Better version control: only Python source committed, notebooks generated
- Flexible learning: can work in notebooks OR Python source
- Maintains backward compatibility: tinytorch package unchanged
Tested:
- Single module export: tito export 01_tensor ✅
- All modules export: tito export --all ✅
- Package imports: from tinytorch.core.tensor import Tensor ✅
- 20/20 modules successfully converted and exported
Documents all JSON formats used for module progress, milestones, and system status. Includes combined export format for website integration and API endpoint suggestions.
Changed from 66 years (1958-2024) to nearly 70 years (1958-2025):
- Abstract: 66 years → nearly 70 years, 2024 → 2025
- Conclusion: 66 years → nearly 70 years, 2024 → 2025
- Milestone M20: 2024 Capstone → 2025 Capstone
Reflects current year and provides better framing (67 years ≈ 70).
Paper compiles successfully with lualatex (25 pages, 383K).
- Add 🧪 emoji to all test_module() docstrings (20 modules)
- Fix Module 16 (compression): Add if __name__ guards to 6 test functions
- Fix Module 08 (dataloader): Add if __name__ guard to test_training_integration
All modules now follow consistent formatting standards for release.
This commit implements a comprehensive quality assurance system and removes
outdated backup files from the repository.
## Release Check Workflow
Added GitHub Actions workflow for systematic release validation:
- Manual-only workflow (workflow_dispatch) - no automatic PR triggers
- 6 sequential quality gates: educational, implementation, testing, package, documentation, systems
- 13 validation scripts (4 fully implemented, 9 stubs for future work)
- Comprehensive documentation in .github/workflows/README.md
- Release process guide in .github/RELEASE_PROCESS.md
Implemented validators:
- validate_time_estimates.py - Ensures consistency between LEARNING_PATH.md and ABOUT.md files
- validate_difficulty_ratings.py - Validates star rating consistency across modules
- validate_testing_patterns.py - Checks for test_unit_* and test_module() patterns
- check_checkpoints.py - Recommends checkpoint markers for long modules (8+ hours)
## Pedagogical Improvements
Added checkpoint markers to Module 05 (Autograd):
- Checkpoint 1: After computational graph construction (~40% progress)
- Checkpoint 2: After automatic differentiation implementation (~80% progress)
- Helps students track progress through the longest foundational module (8-10 hours)
## Codebase Cleanup
Removed 20 legacy *_dev.py files across all modules:
- Confirmed via export system analysis: only *.py files (without _dev suffix) are used
- Export system explicitly reads from {name}.py (see tito/commands/export.py line 461)
- All _dev.py files were outdated backups not used by the build/export pipeline
- Verified all active .py files contain current implementations with optimizations
This cleanup:
- Eliminates confusion about which files are source of truth
- Reduces repository size
- Makes development workflow clearer (work in modules/XX_name/name.py)
## Formatting Standards Documentation
Documents formatting and style standards discovered through systematic
review of all 20 TinyTorch modules.
### Key Findings
Overall Status: 9/10 (Excellent consistency)
- All 20 modules use correct test_module() naming
- 18/20 modules have proper if __name__ guards
- All modules use proper Jupytext format (no JSON leakage)
- Strong ASCII diagram quality
- All 20 modules missing 🧪 emoji in test_module() docstrings
### Standards Documented
1. Test Function Naming: test_unit_* for units, test_module() for integration
2. if __name__ Guards: Immediate guards after every test/analysis function
3. Emoji Protocol: 🔬 for unit tests, 🧪 for module tests, 📊 for analysis
4. Markdown Formatting: Jupytext format with proper section hierarchy
5. ASCII Diagrams: Box-drawing characters, labeled dimensions, data flow arrows
6. Module Structure: Standard template with 9 sections
### Quick Fixes Identified
- Add 🧪 emoji to test_module() in all 20 modules (~5 min)
- Fix Module 16 if __name__ guards (~15 min)
- Fix Module 08 guard (~5 min)
Total quick fixes: 25 minutes to achieve 10/10 consistency
Refactors difficulty levels to use star ratings for better visual representation.
Adjusts time estimates for modules based on user feedback and complexity,
resulting in a more accurate learning path.
Replaces explicit loops in scaled dot-product attention with
matrix operations for significant performance improvement.
Applies softmax activation from `tinytorch.core.activations` instead of numpy.
Includes a pedagogical note explaining the previous loop implementation.
Refactors multi-head attention to leverage the optimized
`scaled_dot_product_attention`.
- Fix README.md: Replace broken references to non-existent files
- Remove STUDENT_VERSION_TOOLING.md references (file does not exist)
- Remove .claude/ directory references (internal development files)
- Remove book/ directory references (does not exist)
- Update instructor documentation links to point to existing files
- Point to INSTRUCTOR.md, TA_GUIDE.md, and docs/ for resources
- Fix paper.tex: Update instructor resources list
- Replace non-existent MAINTENANCE.md with TA_GUIDE.md
- Maintenance commitment details remain in paragraph text
- All referenced files now exist in repository
All documentation links now point to actual files in the repository
Removed 42 planning, brainstorming, and status tracking documents that served their purpose during development but are no longer needed for release.
Changes:
- Root: Removed 4 temporary/status files
- binder/: Removed 20 planning documents (kept essential setup files)
- docs/: Removed 16 planning/status documents (preserved all user-facing docs and website dependencies)
- tests/: Removed 2 status documents (preserved all test docs and milestone system)
Preserved files:
- All user-facing documentation (README, guides, quickstarts)
- All website dependencies (INSTRUCTOR_GUIDE, PRIVACY_DATA_RETENTION, TEAM_ONBOARDING)
- All functional configuration files
- All milestone system documentation (7 files in tests/milestones/)
Updated .gitignore to prevent future accumulation of internal development files (.claude/, site/_build/, log files, progress.json)
- Single source of truth in milestone_tracker.py
- Zero code duplication across codebase
- Clean API: check_module_export(module_name, console)
- Gamified learning experience through ML history
- Progressive unlocking of 5 major milestones
- Comprehensive documentation for students and developers
- Integration with module workflow and CLI commands
