From 521305013132f1cf0a774c0edbb07a7edbbc4e10 Mon Sep 17 00:00:00 2001 From: Vijay Janapa Reddi Date: Sun, 13 Jul 2025 15:52:09 -0400 Subject: [PATCH] Update CLI references and virtual environment activation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace all 'python bin/tito.py' references with correct 'tito' commands - Update command structure to use proper subcommands (tito system info, tito module test, etc.) - Add virtual environment activation to all workflows - Update Makefile to use correct tito commands with .venv activation - Update activation script to use correct tito path and command examples - Add Tiny🔥Torch branding to activation script header - Update documentation to reflect correct CLI usage patterns --- .../module-development-best-practices.mdc | 7 +++- .cursor/rules/tinytorch-project-structure.mdc | 21 +++++----- .cursor/rules/user-preferences.mdc | 12 ++---- Makefile | 16 ++++---- bin/activate-tinytorch.sh | 14 +++---- modules/source/00_setup/README.md | 22 ++++++++-- modules/source/02_activations/README.md | 41 +++++++++++-------- modules/source/06_dataloader/README.md | 16 ++++---- modules/source/07_autograd/README.md | 19 +++++++-- 9 files changed, 100 insertions(+), 68 deletions(-) diff --git a/.cursor/rules/module-development-best-practices.mdc b/.cursor/rules/module-development-best-practices.mdc index ce1e158f..19b27162 100644 --- a/.cursor/rules/module-development-best-practices.mdc +++ b/.cursor/rules/module-development-best-practices.mdc @@ -314,11 +314,14 @@ class TestCompleteMLSystem: ### Running Tests (ALWAYS THROUGH PYTEST) ```bash +# Activate environment first +source bin/activate-tinytorch.sh + # Test specific module (recommended) -python bin/tito.py test --module networks +tito test --module networks # Test all modules -python bin/tito.py test --all +tito test --all # Run specific test file directly with pytest python -m pytest modules/source/04_networks/tests/test_networks.py -v diff --git a/.cursor/rules/tinytorch-project-structure.mdc b/.cursor/rules/tinytorch-project-structure.mdc index e8dd7ded..c6ed962a 100644 --- a/.cursor/rules/tinytorch-project-structure.mdc +++ b/.cursor/rules/tinytorch-project-structure.mdc @@ -1,6 +1,3 @@ ---- -description: A guide to the project structure of the TinyTorch ML framework. ---- # TinyTorch Project Structure Guide @@ -28,9 +25,12 @@ This is an educational ML Systems course repository organized into progressive m - [tinytorch/datasets/](mdc:tinytorch/datasets/) - Data loading utilities - [tinytorch/configs/](mdc:tinytorch/configs/) - Configuration management -### Development Tools -- [bin/tito.py](mdc:bin/tito.py) - Main CLI tool for sync, test, and build operations -- [bin/activate-tinytorch.sh](mdc:bin/activate-tinytorch.sh) - Environment activation script +## Core Infrastructure + +- [bin/tito](mdc:bin/tito) - Main CLI tool for sync, test, and build operations +- [bin/activate-tinytorch.sh](mdc:bin/activate-tinytorch.sh) - Virtual environment activation script +- [tito/](mdc:tito/) - CLI implementation with modular command structure +- [Makefile](mdc:Makefile) - Build automation and development shortcuts ## Module Structure Pattern @@ -46,10 +46,9 @@ modules/{module_name}/ ## Development Workflow -1. **Write**: Edit `modules/{module}/module_dev.py` with `#| export` directives -2. **Sync**: Run `python bin/tito.py sync --module {module}` -3. **Test**: Run `python bin/tito.py test --module {module}` -4. **Build**: Code exports to `tinytorch/core/{component}.py` +1. **Activate environment**: `source bin/activate-tinytorch.sh` +2. **Sync**: Run `tito module export --module {module}` +3. **Test**: Run `tito module test --module {module}` The `#| default_exp` directive controls where code exports to in the package. @@ -59,5 +58,7 @@ The `#| default_exp` directive controls where code exports to in the package. +The `#| default_exp` directive controls where code exports to in the package. + The `#| default_exp` directive controls where code exports to in the package. \ No newline at end of file diff --git a/.cursor/rules/user-preferences.mdc b/.cursor/rules/user-preferences.mdc index 6c511fb4..c5b83a81 100644 --- a/.cursor/rules/user-preferences.mdc +++ b/.cursor/rules/user-preferences.mdc @@ -1,7 +1,3 @@ ---- -description: User preferences and development conventions for TinyTorch, including module naming patterns, commit frequency, testing standards, and NBDev integration workflow. -alwaysApply: false ---- # User Preferences and Conventions @@ -13,6 +9,7 @@ alwaysApply: false - **README focus**: Keep main project README focused on overarching goals, not module details - **Component terminology**: Call code components 'modules' instead of 'parts' - **Testing framework**: Always use pytest for all tests - no manual testing or other frameworks +- **Brand formatting**: In headers and titles, use "Tiny🔥Torch" (with flame emoji after "Tiny"), not "🔥TinyTorch". In regular text, "TinyTorch" is acceptable ## Educational Workflow @@ -38,11 +35,8 @@ alwaysApply: false - **pytest only**: All tests must use pytest framework with proper test classes - **Comprehensive coverage**: Tests should cover functionality, edge cases, and integration - **Professional structure**: Use test classes, fixtures, and descriptive test names -- **CLI integration**: Tests must be compatible with `python bin/tito.py test --module {name}` - -These preferences ensure consistency across the TinyTorch educational framework and smooth development workflow. - -- **Package structure**: Code exports from `modules/` to `tinytorch/` package +- **CLI integration**: Tests must be compatible with `tito module test --module {name}` (requires virtual environment activation) +- **Environment setup**: Always activate virtual environment with `source bin/activate-tinytorch.sh` before running commands These preferences ensure consistency across the TinyTorch educational framework and smooth development workflow. \ No newline at end of file diff --git a/Makefile b/Makefile index 796a36b3..3f9bd5ca 100644 --- a/Makefile +++ b/Makefile @@ -36,22 +36,22 @@ install: # Export notebooks to Python package sync: @echo "🔄 Exporting notebooks to Python package..." - python bin/tito.py sync + @source .venv/bin/activate && python3 bin/tito export --all # Run all tests test: @echo "🧪 Running all tests..." - python bin/tito.py test --all + @source .venv/bin/activate && python3 bin/tito module test --all # Run setup module tests specifically test-setup: @echo "🧪 Running setup module tests..." - python bin/tito.py test --module setup + @source .venv/bin/activate && python3 bin/tito module test --module setup # Clean notebook outputs and Python cache clean: @echo "🧹 Cleaning notebook outputs and cache..." - python bin/tito.py nbdev --clean + @source .venv/bin/activate && python3 bin/tito module clean find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true find . -type f -name "*.pyc" -delete 2>/dev/null || true @echo "✅ Cleanup complete!" @@ -59,12 +59,12 @@ clean: # Build documentation docs: @echo "📚 Building documentation..." - python bin/tito.py nbdev --build-docs + @source .venv/bin/activate && python3 bin/tito package build-docs # Start Jupyter Lab jupyter: @echo "🚀 Starting Jupyter Lab..." - python bin/tito.py jupyter --lab + @source .venv/bin/activate && python3 bin/tito system jupyter --lab # Alias for jupyter lab: jupyter @@ -72,12 +72,12 @@ lab: jupyter # Show system information info: @echo "ℹ️ System information..." - python bin/tito.py info + @source .venv/bin/activate && python3 bin/tito system info # Run environment diagnosis doctor: @echo "🔬 Running environment diagnosis..." - python bin/tito.py doctor + @source .venv/bin/activate && python3 bin/tito system doctor # Setup new environment (for first-time users) setup: diff --git a/bin/activate-tinytorch.sh b/bin/activate-tinytorch.sh index 124a9daf..34a783b7 100755 --- a/bin/activate-tinytorch.sh +++ b/bin/activate-tinytorch.sh @@ -1,5 +1,5 @@ #!/bin/bash -# TinyTorch Environment Activation & Setup +# Tiny🔥Torch Environment Activation & Setup # Check if virtual environment exists, create if not if [ ! -d ".venv" ]; then @@ -16,15 +16,15 @@ if [ ! -d ".venv" ]; then echo "✅ Environment created!" fi -echo "🔥 Activating TinyTorch environment..." +echo "🔥 Activating Tiny🔥Torch environment..." source .venv/bin/activate # Create tito alias for convenience -alias tito="python3 bin/tito.py" +alias tito="python3 bin/tito" echo "✅ Ready to build ML systems!" echo "💡 Quick commands:" -echo " tito info - Check system status" -echo " tito test - Run tests" -echo " tito doctor - Diagnose issues" -echo " jupyter notebook - Start Jupyter for interactive development" +echo " tito system info - Check system status" +echo " tito module test - Run tests" +echo " tito system doctor - Diagnose issues" +echo " tito system jupyter - Start Jupyter for interactive development" diff --git a/modules/source/00_setup/README.md b/modules/source/00_setup/README.md index a2eb7b5b..bef90efe 100644 --- a/modules/source/00_setup/README.md +++ b/modules/source/00_setup/README.md @@ -74,7 +74,7 @@ Run the comprehensive test suite using pytest: ```bash # Using the TinyTorch CLI (recommended) -python bin/tito.py test --module setup +tito test --module setup # Or directly with pytest python -m pytest modules/setup/tests/test_setup.py -v @@ -92,14 +92,28 @@ The test suite includes **20 comprehensive tests** covering: - ✅ **Error recovery** - Graceful handling of missing files - ✅ **Integration testing** - All components work together +## Getting Started + +### Prerequisites + +1. **Activate the virtual environment**: + ```bash + source bin/activate-tinytorch.sh + ``` + +2. **Test the setup module**: + ```bash + tito test --module setup + ``` + ## Development Workflow This module teaches the core TinyTorch development cycle: 1. **Write code** in the notebook using `#| export` directives -2. **Export code** with `python bin/tito.py sync --module setup` -3. **Run tests** with `python bin/tito.py test --module setup` -4. **Check progress** with `python bin/tito.py info` +2. **Export code** with `tito sync --module setup` +3. **Run tests** with `tito test --module setup` +4. **Check progress** with `tito info` ## Key Concepts diff --git a/modules/source/02_activations/README.md b/modules/source/02_activations/README.md index ed43c9db..d1639120 100644 --- a/modules/source/02_activations/README.md +++ b/modules/source/02_activations/README.md @@ -46,11 +46,22 @@ This module teaches you the mathematical foundations that make deep learning pos ## 🚀 Getting Started +### Prerequisites + +1. **Activate the virtual environment**: + ```bash + source bin/activate-tinytorch.sh + ``` + +2. **Start development environment**: + ```bash + tito jupyter + ``` + ### Development Workflow 1. **Open the development file**: ```bash - python bin/tito.py jupyter # Then open assignments/source/02_activations/activations_dev.py ``` @@ -66,12 +77,12 @@ This module teaches you the mathematical foundations that make deep learning pos 4. **Test as you go**: ```bash - python bin/tito.py test --module activations + tito test --module activations ``` 5. **Export to package**: ```bash - python bin/tito.py sync + tito sync ``` ### 📊 Visual Learning Features @@ -127,19 +138,17 @@ def forward(self, x: Tensor) -> Tensor: return Tensor(np.tanh(x.data)) ``` -## 🧪 Testing Your Implementation +### Testing Your Implementation -### Unit Tests -```bash -python bin/tito.py test --module activations -``` +1. **Run the tests**: + ```bash + tito test --module activations + ``` -**Test Coverage**: -- ✅ Mathematical correctness -- ✅ Numerical stability -- ✅ Shape preservation -- ✅ Edge cases -- ✅ Function properties +2. **Export to package**: + ```bash + tito sync + ``` ### Manual Testing ```python @@ -201,7 +210,7 @@ output = relu(input_tensor) ### Issue 4: Import Errors **Problem**: Cannot import after implementation -**Solution**: Run `python bin/tito.py sync` to export to package +**Solution**: Run `tito sync` to export to package ## 📈 Performance Considerations @@ -234,7 +243,7 @@ These functions are the mathematical foundation for everything that follows! ## 🎉 Success Criteria You've mastered this module when: -- [ ] All tests pass (`python bin/tito.py test --module activations`) +- [ ] All tests pass (`tito test --module activations`) - [ ] You understand why each function is useful - [ ] You can explain the mathematical properties - [ ] You can use activations in neural networks diff --git a/modules/source/06_dataloader/README.md b/modules/source/06_dataloader/README.md index 54d49b63..7ef7d3c8 100644 --- a/modules/source/06_dataloader/README.md +++ b/modules/source/06_dataloader/README.md @@ -35,9 +35,9 @@ modules/dataloader/ ### Step 1: Complete Prerequisites Make sure you've completed the foundational modules: ```bash -python bin/tito.py test --module setup # Should pass -python bin/tito.py test --module tensor # Should pass -python bin/tito.py test --module layers # Should pass +tito test --module setup # Should pass +tito test --module tensor # Should pass +tito test --module layers # Should pass ``` ### Step 2: Open the Data Development File @@ -46,7 +46,7 @@ python bin/tito.py test --module layers # Should pass cd modules/dataloader/ # Convert to notebook if needed -python bin/tito.py notebooks --module dataloader +tito notebooks --module dataloader # Open the development notebook jupyter lab dataloader_dev.ipynb @@ -63,10 +63,10 @@ The development file guides you through building: ### Step 4: Export and Test ```bash # Export your dataloader implementation -python bin/tito.py sync --module dataloader +tito sync --module dataloader # Test your implementation -python bin/tito.py test --module dataloader +tito test --module dataloader ``` ## 📚 What You'll Implement @@ -150,7 +150,7 @@ The tests follow the **"Build → Use → Understand"** pattern with real CIFAR- ```bash # Run all tests (downloads real CIFAR-10 data) -python bin/tito.py test --module dataloader +tito test --module dataloader # Run specific test categories python -m pytest tests/test_dataloader.py::TestDatasetInterface -v # Test abstract interface @@ -226,7 +226,7 @@ The development notebook includes **visual feedback** for learning and debugging Your data module is complete when: -1. **All tests pass**: `python bin/tito.py test --module dataloader` +1. **All tests pass**: `tito test --module dataloader` 2. **Data classes import correctly**: `from tinytorch.core.dataloader import Dataset, DataLoader` 3. **Dataset loading works**: Can create datasets and access samples 4. **Batching works**: DataLoader produces correct batch shapes diff --git a/modules/source/07_autograd/README.md b/modules/source/07_autograd/README.md index 4f180e6a..c36b218b 100644 --- a/modules/source/07_autograd/README.md +++ b/modules/source/07_autograd/README.md @@ -75,11 +75,22 @@ print(layer.bias.grad) # Bias gradients ## 🚀 Getting Started +### Prerequisites + +1. **Activate the virtual environment**: + ```bash + source bin/activate-tinytorch.sh + ``` + +2. **Start development environment**: + ```bash + tito jupyter + ``` + ### Development Workflow 1. **Open the development file**: ```bash - python bin/tito.py jupyter # Then open modules/source/07_autograd/autograd_dev.py ``` @@ -91,7 +102,7 @@ print(layer.bias.grad) # Bias gradients 3. **Test your implementation**: ```bash - python bin/tito.py test --module 07_autograd + tito test --module 07_autograd ``` ## 📊 Understanding Automatic Differentiation @@ -137,7 +148,7 @@ df/dy = df/da * da/dy + df/db * db/dy = (-1)(1) + (5)(-1) = -6 ### Unit Tests ```bash -python bin/tito.py test --module 07_autograd +tito test --module 07_autograd ``` **Test Coverage**: @@ -217,7 +228,7 @@ print(layer2.weights.grad) Your autograd module is complete when: -1. **All tests pass**: `python bin/tito.py test --module 07_autograd` +1. **All tests pass**: `tito test --module 07_autograd` 2. **Variable imports correctly**: `from tinytorch.core.autograd import Variable` 3. **Basic operations work**: Can create Variables and do arithmetic 4. **Gradients compute correctly**: Backward pass produces correct gradients