Module Workflow

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

Fig. 30 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.#

The essential command: tito module complete XX - exports your code to the TinyTorch package

Follow this workflow to build ML systems from scratch.

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

Contents