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.)
## 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>
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.
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)
- Implement tito benchmark baseline and capstone commands
- Add SPEC-style normalization for baseline benchmarks
- Implement tito community join, update, leave, stats, profile commands
- Use project-local storage (.tinytorch/) for user data
- Add privacy-by-design with explicit consent prompts
- Update site documentation for community and benchmark features
- Add Marimo integration for online notebooks
- Clean up redundant milestone setup exploration docs
- Finalize baseline design: fast setup validation (~1 second) with normalized results
The itemize environment parameters [leftmargin=*, itemsep=1pt, parsep=0pt]
were appearing as visible text in the PDF because the enumitem package
wasn't loaded. This fix adds \usepackage{enumitem} to the preamble.
All itemized lists now format correctly with proper spacing and margins.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Improve site navigation and content structure
- Update development testing documentation
- Enhance site styling and visual consistency
- Update release notes and milestone templates
- Improve site rebuild script functionality
- Add TESTING_QUICK_REFERENCE.md for quick access to common testing commands
- Add comprehensive-module-testing-plan.md with module-by-module test requirements
- Add gradient-flow-testing-strategy.md for gradient flow test coverage analysis
- Add testing-architecture.md explaining two-tier testing approach
- Update TEST_STRATEGY.md to reference master testing plan
These documents define clear boundaries between unit tests (modules/),
integration tests (tests/), and milestones, with comprehensive coverage
analysis and implementation roadmap.
Documentation updates across the codebase:
Root documentation:
- README.md: Updated references from book/ to site/
- CONTRIBUTING.md: Updated build and workflow instructions
- .shared-ai-rules.md: Updated AI assistant rules for new structure
GitHub configuration:
- Issue templates updated for new module locations
- Workflow references updated from book/ to site/
docs/ updates:
- STUDENT_QUICKSTART.md: New paths and structure
- module-rules.md: Updated module development guidelines
- NBGrader documentation: Updated for module restructuring
- Archive documentation: Updated references
Module documentation:
- modules/17_memoization/README.md: Updated after reordering
All documentation now correctly references:
- site/ instead of book/
- modules/XX_name/ instead of modules/source/
Created unified setup-environment.sh script that:
- Detects Apple Silicon and creates arm64-optimized venv
- Handles all dependencies automatically
- Creates activation helper with architecture awareness
- Works across macOS (Intel/Apple Silicon), Linux, Windows
Updated all documentation to use ONE setup command:
- README.md: Updated Quick Start
- docs/STUDENT_QUICKSTART.md: Updated Getting Started
- book/quickstart-guide.md: Updated 2-Minute Setup
Enhanced tito setup command with:
- Apple Silicon detection (checks for Rosetta vs native)
- Automatic arm64 enforcement when on Apple Silicon
- Architecture verification after venv creation
- Changed venv path from tinytorch-env to standard .venv
Students now have ONE clear path: ./setup-environment.sh
- Enhanced module-developer agent with Dr. Sarah Rodriguez persona
- Added comprehensive educational frameworks and Golden Rules
- Implemented Progressive Disclosure Principle (no forward references)
- Added Immediate Testing Pattern (test after each implementation)
- Integrated package structure template (📦 where code exports to)
- Applied clean NBGrader structure with proper scaffolding
- Fixed tensor module formatting and scope boundaries
- Removed confusing transparent analysis patterns
- Added visual impact icons system for consistent motivation
🎯 Ready to apply these proven educational principles to all modules
🎯 NORTH STAR VISION DOCUMENTED:
'Don't Just Import It, Build It' - Training AI Engineers, not just ML users
AI Engineering emerges as a foundational discipline like Computer Engineering,
bridging algorithms and systems to build the AI infrastructure of the future.
🧪 ROBUST TESTING FRAMEWORK ESTABLISHED:
- Created tests/regression/ for sandbox integrity tests
- Implemented test-driven bug prevention workflow
- Clear separation: student tests (pedagogical) vs system tests (robustness)
- Every bug becomes a test to prevent recurrence
✅ KEY IMPLEMENTATIONS:
- NORTH_STAR.md: Vision for AI Engineering discipline
- Testing best practices: Focus on robust student sandbox
- Git workflow standards: Professional development practices
- Regression test suite: Prevent infrastructure issues
- Conv->Linear dimension tests (found CNN bug)
- Transformer reshaping tests (found GPT bug)
🏗️ SANDBOX INTEGRITY:
Students need a solid, predictable environment where they focus on ML concepts,
not debugging framework issues. The framework must be invisible.
📚 EDUCATIONAL PHILOSOPHY:
TinyTorch isn't just teaching a framework - it's founding the AI Engineering
discipline by training engineers who understand how to BUILD ML systems.
This establishes the foundation for training the first generation of true
AI Engineers who will define this emerging discipline.
✅ Phase 1-2 Complete: Modules 1-10 aligned with tutorial master plan
✅ CNN Training Pipeline: Autograd → Spatial → Optimizers → DataLoader → Training
✅ Technical Validation: All modules import and function correctly
✅ CIFAR-10 Ready: Multi-channel Conv2D, BatchNorm, MaxPool2D, complete pipeline
Key Achievements:
- Fixed module sequence alignment (spatial now Module 7, not 6)
- Updated tutorial master plan for logical pedagogical flow
- Phase 2 milestone achieved: Students can train CNNs on CIFAR-10
- Complete systems engineering focus throughout all modules
- Production-ready CNN pipeline with memory profiling
Next Phase: Language models (Modules 11-15) for TinyGPT milestone
MAJOR FEATURE: Multi-channel convolutions for real CNN architectures
Key additions:
- MultiChannelConv2D class with in_channels/out_channels support
- Handles RGB images (3 channels) and arbitrary channel counts
- He initialization for stable training
- Optional bias parameters
- Batch processing support
Testing & Validation:
- Comprehensive unit tests for single/multi-channel
- Integration tests for complete CNN pipelines
- Memory profiling and parameter scaling analysis
- QA approved: All mandatory tests passing
CIFAR-10 CNN Example:
- Updated train_cnn.py to use MultiChannelConv2D
- Architecture: Conv(3→32) → Pool → Conv(32→64) → Pool → Dense
- Demonstrates why convolutions matter for vision
- Shows parameter reduction vs MLPs (18KB vs 12MB)
Systems Analysis:
- Parameter scaling: O(in_channels × out_channels × kernel²)
- Memory profiling shows efficient scaling
- Performance characteristics documented
- Production context with PyTorch comparisons
This enables proper CNN training on CIFAR-10 with ~60% accuracy target.
Clean, dependency-driven organization:
- Part I (1-5): MLPs for XORNet
- Part II (6-10): CNNs for CIFAR-10
- Part III (11-15): Transformers for TinyGPT
Key improvements:
- Dropped modules 16-17 (regularization/systems) to maintain scope
- Moved normalization to module 13 (Part III where it's needed)
- Created three CIFAR-10 examples: random, MLP, CNN
- Each part introduces ONE major innovation (FC → Conv → Attention)
CIFAR-10 now showcases progression:
- test_random_baseline.py: ~10% (random chance)
- train_mlp.py: ~55% (no convolutions)
- train_cnn.py: ~60%+ (WITH Conv2D - shows why convolutions matter!)
This follows actual ML history and each module is needed for its capstone.
- Part I: Foundations (Modules 1-5) - Build MLPs, solve XOR
- Part II: Computer Vision (Modules 6-11) - Build CNNs, classify CIFAR-10
- Part III: Language Models (Modules 12-17) - Build transformers, generate text
Key changes:
- Renamed 05_dense to 05_networks for clarity
- Moved 08_dataloader to 07_dataloader (swap with attention)
- Moved 07_attention to 13_attention (Part III)
- Renamed 12_compression to 16_regularization
- Created placeholder dirs for new language modules (12,14,15,17)
- Moved old modules 13-16 to temp_holding for content migration
- Updated README with three-part structure
- Added comprehensive documentation in docs/three-part-structure.md
This structure gives students three natural exit points with concrete achievements at each level.
Major changes:
- Moved TinyGPT from Module 16 to examples/tinygpt (capstone demo)
- Fixed Module 10 (optimizers) and Module 11 (training) bugs
- All 16 modules now passing tests (100% health)
- Added comprehensive testing with 'tito test --comprehensive'
- Renamed example files for clarity (train_xor_network.py, etc.)
- Created working TinyGPT example structure
- Updated documentation to reflect 15 core modules + examples
- Added KISS principle and testing framework documentation
