TinyTorch/docs/tito/modules.md

Module Workflow

Build ML Systems from Scratch

The core workflow for implementing and exporting TinyTorch modules

Purpose: Master the module development workflow - the heart of TinyTorch. Learn how to implement modules, export them to your package, and validate with tests.

The Core Workflow

TinyTorch follows a simple build-export-validate cycle:

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

See Student Workflow for the complete development cycle and best practices.

---

Essential Commands

Check Environment

tito system health

Verify your setup is ready before starting

Start a Module (First Time)

tito module start 01

Opens Jupyter Lab for Module 01 (Tensor)

Resume Work (Continue Later)

tito module resume 01

Continue working on Module 01 where you left off

Export & Complete (Essential)

tito module complete 01

Export Module 01 to TinyTorch package - THE key command

Check Progress

tito module status

See which modules you've completed

---

Typical Development Session

Here's what a complete session looks like:

1. Start Session

cd TinyTorch
source activate.sh
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:

• Implement the required functionality
• Add docstrings and comments
• Run and test your code inline
• See immediate feedback

4. Export to Package

# From repository root
tito module complete 03

This command:

• Runs tests on your implementation
• Exports code to tinytorch/nn/layers.py
• Makes your code importable
• Tracks completion

5. 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

---

System Commands

Environment Health

Check Setup (Run This First)

tito system health

Verifies:

• Virtual environment activated
• Dependencies installed (NumPy, Jupyter, Rich)
• TinyTorch in development mode
• All systems ready

Output:

✅ Environment validation passed
  • Virtual environment: Active
  • Dependencies: NumPy, Jupyter, Rich installed
  • TinyTorch: Development mode

System Information

tito system info

Shows:

• Python version
• Environment paths
• Package versions
• Configuration settings

Start Jupyter Lab

tito system jupyter

Convenience command to launch Jupyter Lab from the correct directory.

---

Module Lifecycle Commands

Start a Module (First Time)

tito module start 01

What this does:

1. Opens Jupyter Lab for Module 01 (Tensor)
2. Shows module README and learning objectives
3. Provides clean starting point
4. Creates backup of any existing work

Example:

tito module start 05  # Start Module 05 (Autograd)

Jupyter Lab opens with the generated notebook for Module 05

Resume Work (Continue Later)

tito module resume 01

What this does:

1. Opens Jupyter Lab with your previous work
2. Preserves all your changes
3. Shows where you left off
4. No backup created (you're continuing)

Use this when: Coming back to a module you started earlier

Complete & Export (Essential)

tito module complete 01

THE KEY COMMAND - This is what makes your code real!

What this does:

1. Tests your implementation (inline tests)
2. Exports to tinytorch/ package
3. Tracks completion in .tito/progress.json
4. Validates NBGrader metadata
5. Makes read-only exported files (protection)

Example:

tito module complete 05  # Export Module 05 (Autograd)

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!

View Progress

tito module status

Shows:

• Which modules (01-20) you've completed
• Completion dates
• Next recommended module

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: Autograd (not started)

Progress: 3/20 modules (15%)

Next: Complete Module 04 to continue Foundation Tier

Reset Module (Advanced)

tito module reset 01

What this does:

1. Creates backup of current work
2. Unexports from tinytorch/ package
3. Restores module to clean state
4. Removes from completion tracking

Use this when: You want to start a module completely fresh

⚠️ Warning: This removes your implementation. Use with caution!

---

Understanding the Export Process

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

---

Module Structure

Development Structure

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/
│   └── 01_tensor.ipynb      ← AUTO-GENERATED for students
├── 02_activations/
│   └── 02_activations.ipynb ← AUTO-GENERATED for students
└── 03_layers/
    └── 03_layers.ipynb      ← AUTO-GENERATED for students

Where Code Exports

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

• Developers: Edit src/XX_name/XX_name.py → Run tito source export → Generates notebooks & package
• Students: Work in generated modules/XX_name/XX_name.ipynb notebooks
• Never edit tinytorch/ directly - it's auto-generated
• Changes in tinytorch/ will be lost on re-export

---

Troubleshooting

Environment Not Ready

Problem: tito system health shows errors

Solution:

# Re-run setup
./setup-environment.sh
source activate.sh

# Verify
tito system health

Export Fails

Problem: tito module complete XX fails

Common causes:

1. Syntax errors in your code
2. Failing tests
3. Missing required functions

Solution:

1. Check error message for details
2. Fix issues in modules/XX_name/
3. Test in Jupyter Lab first
4. Re-run tito module complete XX

Import Errors

Problem: 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.

---

Next Steps

Ready to Build Your First Module?

Start with Module 01 (Tensor) and build the foundation of neural networks

Foundation Tier → Milestone System →

---

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.