tinytorch/site/tito/modules.md
Purpose: Master the module development workflow - the heart of TinyTorch. Learn how to implement modules, export them to your package, and validate with tests.
TinyTorch follows a simple build-export-validate cycle:
:align: center
:caption: "**Module Development Workflow.** The core cycle for building TinyTorch: start a module, edit in Jupyter, export to the package, test your imports, then move to the next module."
graph LR
A[Start/Resume Module] --> B[Edit in Jupyter]
B --> C[Complete & Export]
C --> D[Test Import]
D --> E[Next Module]
style A fill:#e3f2fd
style B fill:#fffbeb
style C fill:#f0fdf4
style D fill:#fef3c7
style E fill:#f3e5f5
The essential command: tito module complete XX - exports your code to the TinyTorch package
Follow this workflow to build ML systems from scratch.
Here's what a complete session looks like:
<div style="background: #f8f9fa; padding: 1.5rem; border: 1px solid #dee2e6; border-radius: 0.5rem; margin: 1.5rem 0;">1. Start Session
cd tinytorch
source .venv/bin/activate
tito system health # Verify environment
2. Start or Resume Module
# First time working on Module 03
tito module start 03
# OR: Continue from where you left off
tito module resume 03
This opens Jupyter Lab with the module notebook.
3. Edit in Jupyter Lab
# In the generated notebook
class Linear:
def __init__(self, in_features, out_features):
# YOUR implementation here
...
Work interactively:
4. Export to Package
# From repository root
tito module complete 03
This command:
tinytorch/nn/layers.py5. Test Your Implementation
# Your code is now in the package!
python -c "from tinytorch import Linear; print(Linear(10, 5))"
6. Check Progress
tito module status
Check Setup (Run This First)
tito system health
Verifies:
Output:
Environment validation passed
• Virtual environment: Active
• Dependencies: NumPy, Jupyter, Rich installed
• TinyTorch: Development mode
System Information
tito system info
Shows:
Start Jupyter Lab
tito system jupyter
Convenience command to launch Jupyter Lab from the correct directory.
</div>tito module list
What this does: Shows all 20 modules with names and tier groupings.
</div>tito module start 01
What this does:
Example:
tito module start 05 # Start Module 05 (DataLoader)
Jupyter Lab opens with the generated notebook for Module 05
</div>tito module resume 01
What this does:
Use this when: Coming back to a module you started earlier
</div>tito module view 01
What this does: Opens the module notebook in Jupyter Lab without updating any status tracking. Useful for reviewing a module you've already completed or browsing ahead.
Difference from start/resume: No progress tracking changes, no backup creation.
</div>tito module complete 01
THE KEY COMMAND - This is what makes your code real!
What this does:
tinytorch/ package.tito/progress.jsonExample:
tito module complete 05 # Export Module 05 (DataLoader)
After exporting:
# YOUR code is now importable!
from tinytorch.autograd import backward
from tinytorch import Tensor
# Use YOUR implementations
x = Tensor([[1.0, 2.0]], requires_grad=True)
y = x * 2
y.backward()
print(x.grad) # Uses YOUR autograd!
tito module test 01
What this does: Runs inline, pytest, and integration tests for a module without exporting or updating progress. Useful for checking your work before committing to complete.
Options:
--all — Test all modules--verbose / -v — Show detailed output--unit-only — Skip integration tests--stop-on-fail — Stop at first failuretito module status
Shows:
Example Output:
Module Progress
Module 01: Tensor (completed 2025-11-16)
Module 02: Activations (completed 2025-11-16)
Module 03: Layers (completed 2025-11-16)
Module 04: Losses (not started)
Module 05: DataLoader (not started)
Progress: 3/20 modules (15%)
Next: Complete Module 04 to continue Foundation Tier
tito module reset 01
What this does:
tinytorch/ packageUse this when: You want to start a module completely fresh
Warning: This removes your implementation. Use with caution!
</div>When you run tito module complete XX, here's what happens:
Step 1: Validation
Checking NBGrader metadata
Validating Python syntax
Running inline tests
Step 2: Export
Converting src/XX_name/XX_name.py
→ modules/XX_name/XX_name.ipynb (notebook)
→ tinytorch/path/name.py (package)
Adding "DO NOT EDIT" warning
Making file read-only
Step 3: Tracking
Recording completion in .tito/progress.json
Updating module status
Step 4: Success
Module XX complete!
Your code is now part of TinyTorch!
Import with: from tinytorch import YourClass
src/ ← Developer source code
├── 01_tensor/
│ └── 01_tensor.py ← SOURCE OF TRUTH (devs edit)
├── 02_activations/
│ └── 02_activations.py ← SOURCE OF TRUTH (devs edit)
└── 03_layers/
└── 03_layers.py ← SOURCE OF TRUTH (devs edit)
modules/ ← Generated notebooks (students use)
├── 01_tensor/
│ └── tensor.ipynb ← AUTO-GENERATED for students
├── 02_activations/
│ └── activations.ipynb ← AUTO-GENERATED for students
└── 03_layers/
└── layers.ipynb ← AUTO-GENERATED for students
tinytorch/
├── core/
│ └── tensor.py ← AUTO-GENERATED (DO NOT EDIT)
├── nn/
│ ├── activations.py ← AUTO-GENERATED (DO NOT EDIT)
│ └── layers.py ← AUTO-GENERATED (DO NOT EDIT)
└── ...
IMPORTANT: Understanding the flow
src/XX_name/XX_name.py → Run tito dev export → Generates notebooks & packagemodules/XX_name/XX_name.ipynb notebookstinytorch/ directly - it's auto-generatedtinytorch/ will be lost on re-exportProblem: tito system health shows errors
Solution:
# Re-activate environment
cd tinytorch
source .venv/bin/activate
# Re-run setup if needed
tito setup
# Verify
tito system health
Problem: tito module complete XX fails
Common causes:
Solution:
modules/XX_name/tito module complete XXProblem: from tinytorch import X fails
Solution:
# Re-export the module
tito module complete XX
# Test import
python -c "from tinytorch import Tensor"
See Troubleshooting Guide for more issues and solutions.
The module workflow is the heart of TinyTorch. Master these commands and you'll build ML systems with confidence. Every line of code you write becomes part of a real, working framework.