github-starred/TinyTorch
2
0
Fork 0
mirror of https://github.com/MLSysBook/TinyTorch.git synced 2026-03-11 19:33:37 -05:00
Code Issues 7 Packages Projects Releases Wiki Activity

Clean up repository by removing planning and status documents

Browse Source 
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)
This commit is contained in:
Vijay Janapa Reddi
2025-11-22 21:05:57 -05:00
parent 0d6807cefb
commit 1517c6f83d
30 changed files with 6 additions and 5094 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
binder/ASSIGNMENTS_DYNAMIC.md
View File

@@ -1,105 +0,0 @@
# Assignments Are Dynamically Generated
## Important: Assignments Directory Structure
**All assignments are dynamically generated** from the `modules/` directory using `tito nbgrader` commands. The `assignments/` directory should **not** be manually maintained.
## How It Works
### Source of Truth: `modules/` Directory
The actual module content lives in:
```
modules/
├── 01_tensor/
│ └── tensor_dev.py ← Source of truth
├── 02_activations/
│ └── activations_dev.py ← Source of truth
└── ...
```
### Dynamic Generation: `assignments/` Directory
Assignments are **generated** from modules using:
```bash
# Generate assignment for a single module
tito nbgrader generate 01_tensor
# Generate assignments for all modules
tito nbgrader generate --all
# Generate assignments for a range
tito nbgrader generate --range 01-05
```
This creates:
```
assignments/
├── source/
│ ├── 01_tensor/
│ │ └── 01_tensor.ipynb ← Generated from modules/01_tensor/tensor_dev.py
│ └── 02_activations/
│ └── 02_activations.ipynb ← Generated from modules/02_activations/activations_dev.py
└── release/
└── ... (student versions, generated via 'tito nbgrader release')
```
## Process Flow
```
modules/01_tensor/tensor_dev.py
↓ (tito nbgrader generate)
↓ (jupytext converts .py → .ipynb)
↓ (NotebookGenerator processes with nbgrader markers)
assignments/source/01_tensor/01_tensor.ipynb
↓ (tito nbgrader release)
assignments/release/01_tensor/01_tensor.ipynb (student version)
```
## What This Means
1. **Don't manually edit** `assignments/source/` files - they're generated
2. **Edit modules** in `modules/` directory instead
3. **Regenerate assignments** when modules change: `tito nbgrader generate`
4. **Old assignments** (like `01_setup`) are outdated - regenerate from current modules
## Outdated Assignment: `01_setup`
The `assignments/source/01_setup/` directory is **outdated** because:
- Module 01 is now "Tensor" (`modules/01_tensor/`)
- It was created when Module 01 was "Setup" (old structure)
- Should be regenerated: `tito nbgrader generate 01_tensor`
## For Binder/Colab
**No impact** - Binder setup doesn't depend on assignment notebooks. However:
- If you want to include assignments in Binder, regenerate them first:
```bash
tito nbgrader generate --all
```
- Students can access modules directly from `modules/` directory
- Assignments are optional - modules are the source of truth
## Best Practices
1. **Always regenerate** assignments after modifying modules
2. **Don't commit** manually edited assignment files
3. **Use `tito nbgrader generate`** to create assignments
4. **Keep modules/** as the single source of truth
## Commands Reference
```bash
# Generate assignments
tito nbgrader generate 01_tensor # Single module
tito nbgrader generate --all # All modules
tito nbgrader generate --range 01-05 # Range
# Release to students (removes solutions)
tito nbgrader release 01_tensor
# Generate feedback
tito nbgrader feedback 01_tensor
```

449
binder/BENCHMARK_COMMUNITY_COMMANDS.md
View File

@@ -1,449 +0,0 @@
# Benchmark & Community Commands Design
## Command Structure
### Benchmark Commands (Performance)
**Two Types of Benchmarks:**
1. **Baseline Benchmark** (`tito benchmark baseline`)
- Lightweight, runs after setup
- Quick validation: "Everything works!"
- Basic operations: tensor ops, simple forward pass
- **Purpose**: Hello world moment, verify setup
2. **Capstone Benchmark** (`tito benchmark capstone`)
- Full benchmark suite (Module 20)
- Proper performance metrics
- All optimization tracks: Speed, Compression, Accuracy, Efficiency
- **Purpose**: Real performance evaluation, leaderboard
### Community Commands (Cohort Feeling)
1. **Join** (`tito community join`)
- Add to community map
- Share location, institution, course type
- **Purpose**: "I'm part of the cohort!"
2. **Update** (`tito community update`)
- Update progress: milestones, modules completed
- Refresh community entry
- **Purpose**: Track progress in community
3. **Stats** (`tito community stats`)
- See community statistics
- Your cohort info
- **Purpose**: "See who else is building"
4. **Cohort** (`tito community cohort`)
- See your cohort members
- Filter by institution, course type, date
- **Purpose**: "These are my peers!"
## Command Details
### 1. Baseline Benchmark
**Command**: `tito benchmark baseline`
**When to run**: After setup, anytime
**What it does**:
- Runs lightweight benchmarks (no full module 20 needed)
- Tests: tensor creation, matrix multiply, simple forward pass
- Generates JSON with baseline scores
- Shows celebration message
**Output**:
```
🎉 Baseline Benchmark Complete!
📊 Your Baseline Performance:
• Tensor Operations: ⚡ 0.5ms
• Matrix Multiply: ⚡ 2.3ms
• Forward Pass: ⚡ 5.2ms
• Score: 85/100
✅ Setup verified and working!
💡 Run 'tito benchmark capstone' after Module 20 for full benchmarks
```
**JSON Output**: `benchmarks/baseline_TIMESTAMP.json`
### 2. Capstone Benchmark
**Command**: `tito benchmark capstone [--track TRACK]`
**When to run**: After Module 20 (Capstone)
**What it does**:
- Runs full benchmark suite from Module 20
- Tests all optimization tracks:
- Speed: Inference latency, throughput
- Compression: Model size, quantization
- Accuracy: Task performance
- Efficiency: Memory, energy
- Generates comprehensive JSON
- Can submit to leaderboard
**Tracks**:
- `--track speed`: Latency/throughput benchmarks
- `--track compression`: Size/quantization benchmarks
- `--track accuracy`: Task performance benchmarks
- `--track efficiency`: Memory/energy benchmarks
- `--track all`: All tracks (default)
**Output**:
```
🏆 Capstone Benchmark Results
📊 Speed Track:
• Inference Latency: 45.2ms
• Throughput: 22.1 ops/sec
• Score: 92/100
📊 Compression Track:
• Model Size: 12.4MB
• Compression Ratio: 4.2x
• Score: 88/100
📊 Overall Score: 90/100
🌍 Submit to leaderboard: tito community submit --benchmark
```
**JSON Output**: `benchmarks/capstone_TIMESTAMP.json`
### 3. Community Join
**Command**: `tito community join`
**When to run**: After setup, anytime
**What it does**:
- Collects: country, institution, course type (optional)
- Validates setup
- Generates anonymous ID
- Adds to community map
- Shows cohort info
**Output**:
```
🌍 Join the TinyTorch Community
📍 Country: [Auto-detected: United States]
🏫 Institution (optional): Harvard University
📚 Course Type (optional): University course
✅ You've joined the TinyTorch Community!
📍 Location: United States
🏫 Institution: Harvard University
🌍 View map: https://tinytorch.ai/community
🎖️ You're builder #1,234 on the global map!
👥 Your Cohort:
• Fall 2024 cohort: 234 builders
• Harvard University: 15 builders
• University courses: 456 builders
💡 Run 'tito community cohort' to see your peers
```
**JSON Output**: `community/my_submission.json`
### 4. Community Update
**Command**: `tito community update`
**When to run**: After milestones pass, module completion
**What it does**:
- Updates existing community entry
- Adds: milestones passed, modules completed
- Refreshes cohort stats
- Shows updated progress
**Output**:
```
✅ Community Entry Updated!
📊 Your Progress:
• Milestones Passed: 6/6 ✅
• Modules Completed: 20/20 ✅
• Capstone Score: 90/100
👥 Your Cohort Stats:
• Fall 2024: 234 builders (you're #15 by progress!)
• Harvard: 15 builders (you're #3!)
• All milestones: 89 builders worldwide
🌍 View updated map: https://tinytorch.ai/community
```
### 5. Community Stats
**Command**: `tito community stats [--cohort]`
**What it does**:
- Shows global community statistics
- Shows your cohort information
- Shows progress comparisons
**Output**:
```
🌍 TinyTorch Community Stats
📊 Global:
• Total Builders: 1,234
• Countries: 45
• Institutions: 234
• This Week: 23 new builders
👥 Your Cohort (Fall 2024):
• Total: 234 builders
• Your Institution: 15 builders
• Your Progress Rank: #15/234
• Milestones Completed: 89/234 (38%)
📈 Progress Distribution:
• All Milestones: 89 (38%)
• Some Milestones: 123 (53%)
• Just Started: 22 (9%)
🌍 View full map: https://tinytorch.ai/community
```
### 6. Community Cohort
**Command**: `tito community cohort [--institution] [--course-type]`
**What it does**:
- Shows your cohort members
- Filter by institution, course type, date
- Shows progress comparisons
- Creates "these are my peers" feeling
**Output**:
```
👥 Your TinyTorch Cohort
🏫 Harvard University Cohort (15 builders):
Rank | Progress | Joined
-----|-----------------|----------
#1 | 20/20 modules ✅ | Sep 2024
#2 | 20/20 modules ✅ | Sep 2024
#3 | 20/20 modules ✅ | Oct 2024 ← You!
#4 | 15/20 modules | Oct 2024
...
📚 University Course Cohort (456 builders):
• Your rank: #45/456
• Top 10% by progress!
🌍 View full community: https://tinytorch.ai/community
```
## Cohort Features
### Creating "Cohort Feeling"
**1. Cohort Identification**
- "Fall 2024 Cohort"
- "Harvard University Cohort"
- "University Course Cohort"
- "Self-Paced Cohort"
**2. Progress Comparison**
- "You're #15 in your cohort"
- "Top 10% by progress"
- "89 builders in your cohort completed all milestones"
**3. Peer Visibility**
- See others from same institution
- See others in same course type
- See others who joined around same time
**4. Milestone Celebrations**
- "You and 23 others completed Milestone 3 this week!"
- "You're part of the 89 builders who completed all milestones!"
## Data Structure
### Community Submission
```json
{
"anonymous_id": "abc123...",
"timestamp": "2024-11-20T10:30:00Z",
"location": {
"country": "United States"
},
"institution": {
"name": "Harvard University",
"type": "university"
},
"context": {
"course_type": "university_course",
"cohort": "Fall 2024", // Auto-determined by date
"experience_level": "intermediate"
},
"progress": {
"setup_verified": true,
"milestones_passed": 6,
"modules_completed": 20,
"capstone_score": 90
},
"benchmarks": {
"baseline": {
"score": 85,
"timestamp": "2024-11-20T10:00:00Z"
},
"capstone": {
"score": 90,
"tracks": {
"speed": 92,
"compression": 88,
"accuracy": 95,
"efficiency": 85
},
"timestamp": "2024-11-25T15:30:00Z"
}
}
}
```
## Implementation Structure
### Commands to Create
**Benchmark Commands** (`tito/commands/benchmark.py`):
- `tito benchmark baseline` - Quick setup validation
- `tito benchmark capstone` - Full Module 20 benchmarks
- `tito benchmark submit` - Submit to leaderboard
**Community Commands** (`tito/commands/community.py`):
- `tito community join` - Join community map
- `tito community update` - Update progress
- `tito community stats` - View statistics
- `tito community cohort` - See your cohort
- `tito community submit` - Submit benchmarks to leaderboard
## User Journey with Cohort Feeling
```
1. Clone & Setup
↓
2. tito system doctor ✅
↓
3. tito community join
→ "You're builder #1,234"
→ "Fall 2024 cohort: 234 builders"
→ "Harvard: 15 builders"
↓
4. tito benchmark baseline
→ "Score: 85/100"
→ "You're in top 25% of your cohort!"
↓
5. Build modules...
↓
6. tito community update
→ "Milestones: 6/6 ✅"
→ "You're #15 in your cohort!"
↓
7. Complete Module 20...
↓
8. tito benchmark capstone
→ "Score: 90/100"
→ "You're #3 at Harvard!"
↓
9. tito community submit --benchmark
→ "Added to leaderboard!"
→ "Rank: #45 globally, #3 at Harvard"
↓
10. tito community cohort
→ See your peers
→ "These are the builders in my cohort!"
```
## Cohort Features
### What Creates Cohort Feeling
**1. Temporal Cohorts**
- "Fall 2024 Cohort" (by join date)
- "This Week's Cohort" (recent joiners)
- "All-Time Builders" (everyone)
**2. Institutional Cohorts**
- "Harvard University Cohort"
- "Stanford Cohort"
- "Self-Paced Cohort"
**3. Progress Cohorts**
- "All Milestones Cohort" (completed everything)
- "Foundation Tier Cohort" (completed modules 1-7)
- "Capstone Cohort" (completed module 20)
**4. Course Type Cohorts**
- "University Course Cohort"
- "Bootcamp Cohort"
- "Self-Paced Cohort"
### Cohort Messages
**After joining:**
```
👥 Welcome to the Fall 2024 Cohort!
You're joining 234 builders who started TinyTorch this semester.
15 builders are from Harvard University (your institution).
🌍 View your cohort: tito community cohort
```
**After milestones:**
```
🎉 Milestone Achievement!
You and 23 others in the Fall 2024 cohort completed Milestone 3 this week!
You're now part of the 89 builders who've completed all milestones.
👥 See your cohort progress: tito community cohort
```
**After capstone:**
```
🏆 Capstone Complete!
You're #3 in the Harvard cohort!
You're #45 globally among all builders.
👥 Your cohort stats: tito community cohort
```
## Implementation Priority
### Phase 1: Core Commands
1. ✅ `tito community join` - Join community
2. ✅ `tito benchmark baseline` - Quick validation
3. ✅ `tito community stats` - View stats
### Phase 2: Progress Tracking
4. ✅ `tito community update` - Update progress
5. ✅ `tito community cohort` - See cohort
### Phase 3: Capstone Integration
6. ✅ `tito benchmark capstone` - Full benchmarks
7. ✅ `tito community submit` - Submit to leaderboard
This creates a complete system where students feel part of a cohort from day one! 🎓🌍

169
binder/BUILD_INTEGRATION.md
View File

@@ -1,169 +0,0 @@
# Automatic Notebook Preparation in Site Build
## Overview
Notebook preparation is now **automatically integrated** into the site build process. When you build the site, notebooks are automatically prepared for launch buttons to work.
## How It Works
### Automatic Integration
The build process now includes notebook preparation:
```bash
cd site
make html # Automatically prepares notebooks, then builds site
jupyter-book build . # Also prepares notebooks automatically
```
### Build Flow
```
1. User runs: make html
↓
2. prepare_notebooks.sh runs automatically
↓
3. Script looks for existing assignment notebooks
↓
4. Copies them to site/chapters/modules/
↓
5. Jupyter Book builds site
↓
6. Launch buttons appear on notebook pages!
```
## What Gets Prepared
### Source: Assignment Notebooks
The script uses notebooks from `assignments/source/` (generated via `tito nbgrader generate`):
```
assignments/source/01_tensor/01_tensor.ipynb
↓ (copied during build)
site/chapters/modules/01_tensor.ipynb
```
### Why Assignment Notebooks?
- Already processed with nbgrader markers
- Student-ready format
- Generated from Python source files
- Consistent with assignment workflow
## Build Commands
All build commands now include notebook preparation:
### HTML Build
```bash
cd site
make html
# Or directly:
jupyter-book build .
```
### PDF Builds
```bash
make pdf-simple # HTML-to-PDF (includes notebook prep)
make pdf # LaTeX PDF (includes notebook prep)
```
## Manual Preparation (Optional)
If you want to prepare notebooks manually:
```bash
cd site
./prepare_notebooks.sh
```
This is useful for:
- Testing notebook preparation
- Debugging launch button issues
- Preparing notebooks before CI/CD builds
## Workflow Summary
### Complete Development → Site Flow
```
1. Development
Edit: modules/01_tensor/tensor_dev.py
2. Generate Assignments
Run: tito nbgrader generate 01_tensor
Creates: assignments/source/01_tensor/01_tensor.ipynb
3. Build Site (automatic)
Run: cd site && make html
Auto-prepares: Copies notebooks to site/chapters/modules/
Builds: Jupyter Book with launch buttons
4. Launch Buttons Work!
Users click → Binder/Colab opens with notebook
```
## Benefits
✅ **Automatic**: No manual steps needed
✅ **Consistent**: Always uses latest notebooks
✅ **Fast**: Uses existing assignment notebooks when available
✅ **Robust**: Falls back gracefully if notebooks don't exist
✅ **Integrated**: Works with all build commands
## Troubleshooting
### Launch Buttons Don't Appear
1. **Check notebooks exist**:
```bash
ls site/chapters/modules/*.ipynb
```
2. **Regenerate assignments**:
```bash
tito nbgrader generate --all
```
3. **Rebuild site**:
```bash
cd site && make html
```
### Notebooks Not Found
If you see "No notebooks prepared":
- Run `tito nbgrader generate --all` first
- Ensure modules have Python source files
- Check that `tito` command is available
### Build Fails
The prepare script is designed to fail gracefully:
- If `tito` is not available, it skips preparation
- If notebooks don't exist, it warns but continues
- Build continues even if preparation fails
## CI/CD Integration
For automated builds (GitHub Actions, etc.):
```yaml
# Example GitHub Actions step
- name: Build site
run: |
cd site
make html
```
The prepare script automatically handles:
- Missing `tito` command (skips gracefully)
- Missing notebooks (warns but continues)
- Non-git environments (works in CI/CD)
## Next Steps
1. ✅ Notebook preparation integrated into build
2. ✅ Launch buttons will work automatically
3. ⏳ Test Binder/Colab links after build
4. ⏳ Verify launch buttons appear on site

29
binder/CLEANUP_NOTES.md
View File

@@ -1,29 +0,0 @@
# Cleanup Notes: Old 01_setup Module
## Issue
The `assignments/source/01_setup/` directory contains an outdated notebook from when Module 01 was "Setup". Module 01 is now "Tensor" (`modules/01_tensor/`).
## Current State
- ✅ **Current Module 01**: `modules/01_tensor/` (Tensor)
- ⚠️ **Old Assignment**: `assignments/source/01_setup/` (outdated)
- ✅ **Current Assignment**: `assignments/source/02_tensor/` (Tensor)
## Impact on Binder/Colab
**No impact** - Binder setup doesn't depend on specific assignment notebooks. The `binder/` configuration:
- Installs TinyTorch package (`pip install -e .`)
- Provides JupyterLab environment
- Students can access any notebooks in the repository
## References Updated
- ✅ `binder/VERIFY.md` - Updated Colab example to use `02_tensor`
- ✅ `site/usage-paths/classroom-use.md` - Updated nbgrader commands
- ✅ `docs/STUDENT_QUICKSTART.md` - Updated module references
## Recommendation
The old `assignments/source/01_setup/` directory can be:
1. **Removed** if no longer needed (cleanest option)
2. **Kept** if you want to preserve old assignments for reference
3. **Moved** to an archive directory if you want to keep history
**For Binder/Colab**: No action needed - they work regardless of this old directory.

146
binder/CLOUD_NOTEBOOK_OPTIONS.md
View File

@@ -1,146 +0,0 @@
# Cloud Notebook Options for TinyTorch
## Current Setup
**Currently Configured:**
- ✅ **MyBinder** (`https://mybinder.org`) - Free, open-source, works well
- ✅ **Google Colab** (`https://colab.research.google.com`) - Free, popular, GPU access
## Available Options
### 1. MyBinder (Current) ✅
**Pros:**
- Free and open-source
- No account required
- Works directly from GitHub
- Good for educational use
- Already configured and working
**Cons:**
- Can be slow to start (2-5 minutes)
- Limited resources (CPU, memory)
- No GPU access
- Sessions timeout after inactivity
**Best For:** Educational use, quick demos, zero-setup access
### 2. Google Colab (Current) ✅
**Pros:**
- Free tier available
- GPU access (free tier: T4 GPU)
- Fast startup
- Popular and familiar to students
- Good integration with Google Drive
**Cons:**
- Requires Google account
- Free tier has usage limits
- Sessions disconnect after inactivity
- Can be slow during peak times
**Best For:** Students who need GPU, familiar Google ecosystem
### 3. Deepnote (Not Currently Configured)
**Pros:**
- Modern, polished interface
- Real-time collaboration
- Good for team projects
- Free tier available
- Better than Colab for some use cases
**Cons:**
- Less well-known than Colab
- Requires account
- Free tier limitations
**Best For:** Team collaboration, professional workflows
**How to Add:**
```yaml
# In site/_config.yml
launch_buttons:
deepnote_url: "https://deepnote.com"
```
### 4. JupyterHub (For Institutions)
**Pros:**
- Self-hosted control
- Institutional integration
- Can provide GPUs
- Scalable
**Cons:**
- Requires server infrastructure
- Setup complexity
- Maintenance overhead
**Best For:** Universities, institutions with IT support
### 5. Kaggle Notebooks
**Pros:**
- Free GPU access
- Popular ML community
- Good for competitions
**Cons:**
- Less flexible than Colab
- More focused on competitions
**Best For:** ML competitions, Kaggle users
## Recommendation for TinyTorch
### Current Setup is Good ✅
**MyBinder + Colab** covers most use cases:
- **MyBinder**: Zero-setup, no account needed, perfect for quick access
- **Colab**: GPU access when needed, familiar to students
### Optional Addition: Deepnote
If you want to add Deepnote for better collaboration:
1. **Add to config:**
```yaml
launch_buttons:
binderhub_url: "https://mybinder.org"
colab_url: "https://colab.research.google.com"
deepnote_url: "https://deepnote.com" # Add this
```
2. **Benefits:**
- Better collaboration features
- More modern interface
- Good for team projects
3. **Considerations:**
- Adds another option (might be confusing)
- Students need to create account
- Current setup already works well
## What About "Mariomi"?
I couldn't find a tool called "Mariomi" related to notebooks. You might be thinking of:
- **MyST** (MyST Markdown) - Already used by Jupyter Book (for documentation)
- **Miro** - Collaboration whiteboard (not for notebooks)
- **Deepnote** - Modern notebook platform (see above)
## My Recommendation
**Keep current setup (MyBinder + Colab)** because:
1. ✅ Already working
2. ✅ Covers all use cases
3. ✅ No additional complexity
4. ✅ Students familiar with Colab
5. ✅ MyBinder perfect for zero-setup access
**Optional:** Add Deepnote if you want better collaboration features, but it's not necessary.
## Testing Current Setup
To verify launch buttons work:
1. Build site: `cd site && make html`
2. Check notebook pages have launch buttons
3. Test Binder: Click "Launch Binder" → Should open MyBinder
4. Test Colab: Click "Launch Colab" → Should open in Colab

262
binder/COMMUNITY_BENCHMARK_DESIGN.md
View File

@@ -1,262 +0,0 @@
# Community Benchmark & "Hello World" Experience Design
## Goal: First Success Moment
Create an immediate "wow, I did it!" moment where students:
1. ✅ Clone and setup TinyTorch
2. ✅ Run all tests (validate installation)
3. ✅ Run milestones (validate their implementation)
4. 🎉 Get benchmark score and join the community
## User Journey Flow
```
Clone & Setup
↓
tito system doctor (verify setup)
↓
tito milestone validate --all (run all milestones)
↓
tito benchmark baseline (generate benchmark score)
↓
🎉 "Welcome to TinyTorch Community!"
↓
[Optional] Upload to leaderboard
```
## Implementation Design
### 1. Baseline Benchmark Command
**Command**: `tito benchmark baseline`
**What it does**:
- Runs a set of lightweight benchmarks (not full module 20)
- Tests basic operations: tensor creation, matrix multiplication, simple forward pass
- Measures: execution time, memory usage, basic throughput
- Generates JSON with results
**When to run**:
- After `tito system doctor` passes
- After `tito milestone validate --all` passes
- Can be run anytime to check baseline
### 2. Benchmark JSON Structure
```json
{
"timestamp": "2024-11-20T10:30:00Z",
"version": "1.0.0",
"system": {
"platform": "darwin",
"python_version": "3.11.0",
"numpy_version": "1.24.0",
"cpu_count": 8,
"memory_gb": 16
},
"baseline_benchmarks": {
"tensor_creation": {
"time_ms": 0.5,
"memory_mb": 0.1
},
"matrix_multiply": {
"time_ms": 2.3,
"throughput_ops_per_sec": 434.78
},
"simple_forward_pass": {
"time_ms": 5.2,
"memory_mb": 2.5
}
},
"milestone_status": {
"milestone_01_perceptron": "passed",
"milestone_02_xor": "passed",
"milestone_03_mlp": "passed"
},
"setup_validated": true,
"all_tests_passed": true
}
```
### 3. Upload/Submission System
**Command**: `tito benchmark submit [--public]`
**What it does**:
- Uploads benchmark JSON to server
- Gets back: community rank, percentile, badge
- Optional: make public on leaderboard
**Server endpoint** (to be created):
- `POST /api/benchmarks/submit`
- Returns: `{ "rank": 1234, "percentile": 75, "badge": "🚀 First Steps" }`
### 4. Community Leaderboard
**Features**:
- Public leaderboard (optional participation)
- Shows: rank, percentile, system info, timestamp
- Filterable by: system type, date, milestone status
- Badges: "🚀 First Steps", "⚡ Fast Setup", "🏆 All Milestones"
### 5. "Hello World" Experience
**After `tito benchmark baseline`**:
```
🎉 Congratulations! You've successfully set up TinyTorch!
📊 Your Baseline Performance:
• Tensor Operations: ⚡ Fast (0.5ms)
• Matrix Multiply: ⚡ Fast (2.3ms)
• Forward Pass: ⚡ Fast (5.2ms)
✅ Milestones Validated: 3/6 passed
🌍 Join the Community:
Run 'tito benchmark submit' to share your results
and see how you compare to others worldwide!
📈 Your Score: 85/100
You're in the top 25% of TinyTorch users!
🚀 Next Steps:
• Continue building modules
• Run 'tito benchmark baseline' anytime
• Complete all milestones for full score
```
## Implementation Steps
### Phase 1: Baseline Benchmark (Core)
1. **Create `tito/commands/benchmark.py`**:
- `tito benchmark baseline` - Run benchmarks, generate JSON
- `tito benchmark submit` - Upload to server (optional)
2. **Benchmark Suite**:
- Lightweight tests (don't require all modules)
- Basic tensor operations
- Simple forward pass
- Memory profiling
3. **JSON Generation**:
- Save to `benchmarks/baseline_YYYYMMDD_HHMMSS.json`
- Include system info, benchmark results, milestone status
### Phase 2: Server Integration
1. **API Endpoint**:
- Simple REST API
- Accepts benchmark JSON
- Returns rank/percentile/badge
- Stores in database
2. **Leaderboard**:
- Public web page
- Shows rankings
- Filterable/searchable
### Phase 3: Community Features
1. **Badges**:
- "🚀 First Steps" - Completed baseline
- "⚡ Fast Setup" - Top 10% performance
- "🏆 All Milestones" - All milestones passed
- "🌍 Community Member" - Submitted to leaderboard
2. **Sharing**:
- Generate shareable image/card
- "I just set up TinyTorch! Score: 85/100"
- Link to leaderboard
## Technical Considerations
### Benchmark Design
**Keep it lightweight**:
- Don't require all modules
- Use basic operations only
- Fast execution (< 30 seconds)
- Works after setup + milestone validation
**What to benchmark**:
- Tensor creation speed
- Matrix multiplication throughput
- Simple forward pass (2-layer network)
- Memory efficiency
- Basic autograd operations
### Privacy & Opt-in
- **Default**: Benchmarks saved locally only
- **Optional**: `--public` flag to share
- **Anonymized**: System info only (no personal data)
- **Consent**: Clear messaging about what's shared
### Server Architecture
**Simple approach**:
- Static JSON file storage (GitHub Pages?)
- Or simple API (Flask/FastAPI)
- Database: SQLite or PostgreSQL
- Leaderboard: Static site generator
**More advanced**:
- Real-time leaderboard
- User accounts (optional)
- Historical tracking
- Regional comparisons
## User Experience Flow
### First Time Setup
```bash
# 1. Clone and setup
git clone https://github.com/mlsysbook/TinyTorch.git
cd TinyTorch
./setup-environment.sh
source activate.sh
# 2. Verify setup
tito system doctor
# ✅ All checks passed!
# 3. Run milestones (if modules completed)
tito milestone validate --all
# ✅ Milestone 01: Perceptron - PASSED
# ✅ Milestone 02: XOR - PASSED
# ✅ Milestone 03: MLP - PASSED
# 4. Generate baseline benchmark
tito benchmark baseline
# 🎉 Congratulations! You've successfully set up TinyTorch!
# 📊 Your Baseline Performance: 85/100
# 🌍 Run 'tito benchmark submit' to join the community!
# 5. (Optional) Submit to leaderboard
tito benchmark submit --public
# ✅ Submitted! You're rank #1234 (top 25%)
# 🔗 View leaderboard: https://tinytorch.ai/leaderboard
```
## Benefits
1. **Immediate Gratification**: "I did it!" moment
2. **Community Feeling**: Part of something bigger
3. **Motivation**: See how they compare
4. **Validation**: Confirms setup worked
5. **Progress Tracking**: Can re-run anytime
## Next Steps
1. Design benchmark suite (what to test)
2. Implement `tito benchmark baseline` command
3. Create JSON schema
4. Design server API (or use GitHub Pages)
5. Build leaderboard page
6. Add badges/sharing features
This creates a "hello world" experience that makes students feel successful and part of the community immediately!

332
binder/COMMUNITY_DATA_COLLECTION.md
View File

@@ -1,332 +0,0 @@
# Community Data Collection Design
## Data We Collect (Privacy-Respecting)
### Required Fields
- **Country**: Geographic location (country-level only)
- **Setup Verified**: Confirmation that setup works
### Optional Fields (User Can Skip)
- **School/Institution**: University, bootcamp, or organization name
- **Course Type**: How they're using TinyTorch
- Self-paced learning
- University course
- Bootcamp/training
- Research project
- Industry training
- **System Type**: Hardware/platform
- Apple Silicon
- Linux x86
- Windows
- Cloud (Colab/Binder)
- **Experience Level**: (Optional)
- Beginner
- Intermediate
- Advanced
### What We DON'T Collect
- ❌ Personal name
- ❌ Email address
- ❌ Exact location (city/coordinates)
- ❌ IP address
- ❌ Any personally identifiable information
## Data Structure
### Submission JSON
```json
{
"anonymous_id": "abc123...", // Generated hash
"timestamp": "2024-11-20T10:30:00Z",
"location": {
"country": "United States" // Required
},
"institution": {
"name": "Harvard University", // Optional
"type": "university" // Optional: university, bootcamp, company, self-paced
},
"context": {
"course_type": "university_course", // Optional
"experience_level": "intermediate" // Optional
},
"system": {
"type": "Apple Silicon", // Optional
"platform": "darwin",
"python_version": "3.11.0"
},
"progress": {
"setup_verified": true,
"milestones_passed": 0, // Will update later
"modules_completed": 0 // Will update later
}
}
```
## Collection Flow
### Interactive Prompt
```bash
tito community join
🌍 Join the TinyTorch Global Community
This will add your location to the public community map.
All information is optional and completely anonymized.
📍 Country: [Auto-detected: United States]
(Press Enter to use detected, or type different country)
🏫 School/Institution (optional):
Examples: "Harvard University", "Stanford", "Self-paced"
[Press Enter to skip]
📚 Course Type (optional):
[1] Self-paced learning
[2] University course
[3] Bootcamp/training
[4] Research project
[5] Industry training
[6] Skip
Choose [1-6]:
💻 System Type (optional):
[Auto-detected: Apple Silicon]
[Press Enter to use detected, or type different]
🎓 Experience Level (optional):
[1] Beginner
[2] Intermediate
[3] Advanced
[4] Skip
Choose [1-4]:
📊 What will be shared:
• Country: United States ✅
• Institution: Harvard University ✅
• Course Type: University course ✅
• System Type: Apple Silicon ✅
• No personal information ✅
🔒 Privacy: Completely anonymized, country-level location only
Continue? [y/N]: y
✅ You've joined the TinyTorch Community!
📍 Location: United States
🏫 Institution: Harvard University
🌍 View map: https://tinytorch.ai/community
🎖️ You're builder #1,234 on the global map!
💡 Your institution will appear on the map (if provided)
```
## Map Visualization Features
### What the Map Shows
**Country View:**
- Dots/countries with builder counts
- "1,234 builders in 45 countries"
**Institution View** (Optional Filter):
- "Builders from 234 institutions"
- Top institutions by builder count
- "Harvard University: 15 builders"
- "Stanford: 12 builders"
- "Self-paced: 456 builders"
**Course Type Breakdown:**
- "University courses: 234"
- "Self-paced: 456"
- "Bootcamps: 89"
- "Research: 123"
**Diversity Stats:**
- "Builders from 45 countries"
- "234 institutions represented"
- "5 course types"
- "Diverse experience levels"
## Privacy Considerations
### Institution Privacy
**Options:**
1. **Show institution names** (if provided)
- Pros: More engaging, shows diversity
- Cons: Might identify users in small programs
2. **Show institution counts only**
- Pros: More private
- Cons: Less engaging
3. **Hybrid approach** (Recommended)
- Show institution names if ≥3 builders from that institution
- Otherwise: "Other institutions: 5 builders"
- Protects privacy while showing diversity
### Consent Flow
**Clear messaging:**
```
⚠️ Institution Information
If you provide your school/institution name, it may appear on the public map.
🔒 Privacy Protection:
• Institution names only shown if ≥3 builders from that institution
• No personal names or identifiers
• Completely anonymized
Provide institution? [y/N]:
```
## Map Features
### Interactive Map
**Country Level:**
- Click country → See stats:
- "United States: 456 builders"
- "Top institutions: Harvard (15), Stanford (12), MIT (10)"
- "Course types: University (234), Self-paced (189)"
**Institution Filter:**
- Filter by institution type
- Show: Universities, Bootcamps, Self-paced, etc.
- See geographic distribution
**Course Type View:**
- Color-code by course type
- Show: "Where are university students?"
- Show: "Where are self-paced learners?"
### Stats Dashboard
```
🌍 TinyTorch Community
📊 Global Stats:
• 1,234 builders worldwide
• 45 countries
• 234 institutions
• 5 course types
🏫 Top Institutions:
1. Harvard University: 15 builders
2. Stanford: 12 builders
3. MIT: 10 builders
4. Self-paced: 456 builders
...
🌎 Geographic Diversity:
• United States: 456 builders
• India: 234 builders
• United Kingdom: 123 builders
...
📚 Course Types:
• Self-paced: 456 (37%)
• University: 234 (19%)
• Bootcamp: 89 (7%)
...
```
## Benefits of Collecting This Data
### For Community
- **Visual diversity**: See global reach
- **Institutional connections**: "Wow, people from my school!"
- **Course type insights**: Understand how TinyTorch is used
- **Motivation**: "There are builders from 234 institutions!"
### For Users
- **Representation**: "I'm representing my school!"
- **Connection**: Find others from same institution
- **Pride**: "My institution is on the map!"
### For Project
- **Adoption tracking**: See where TinyTorch is used
- **Diversity metrics**: Geographic and institutional diversity
- **Success stories**: "Used in 234 institutions worldwide"
## Implementation
### Data Collection
**Command**: `tito community join`
**Flow:**
1. Auto-detect country (using system locale or geolocation API)
2. Ask for institution (optional)
3. Ask for course type (optional)
4. Auto-detect system type
5. Ask for experience level (optional)
6. Show summary
7. Get consent
8. Generate submission
### Privacy Protection
**Institution Anonymization:**
- If <3 builders from institution → Show as "Other institutions"
- If ≥3 builders → Show institution name
- Protects privacy while showing diversity
**Data Storage:**
- Anonymous ID (hash, not personal)
- No personal identifiers
- Country-level only (not city)
- Optional fields can be skipped
## Recommended Fields
### Required
- ✅ Country
### Highly Recommended (Optional)
- ✅ Institution/School name
- ✅ Course type
### Nice to Have (Optional)
- System type (auto-detected)
- Experience level
- Milestone progress (updates later)
### Skip
- Personal name
- Email
- Exact location
- Any PII
## Example Map Entry
**What users see:**
```
📍 United States
• 456 builders
• Top institutions: Harvard (15), Stanford (12), MIT (10)
• Course types: University (234), Self-paced (189)
```
**What gets stored:**
```json
{
"country": "United States",
"institution": "Harvard University",
"course_type": "university_course",
"anonymous_id": "abc123..."
}
```
This creates a rich, engaging community map while respecting privacy! 🌍✨

299
binder/COMMUNITY_EXPERT_RECOMMENDATION.md
View File

@@ -1,299 +0,0 @@
# Community Building Expert Recommendation for TinyTorch
## Core Principles
### 1. **Low Barrier to Entry** ✅
- Make it **opt-in**, not required
- Default: benchmarks saved locally only
- No account creation needed initially
- Can participate anonymously
### 2. **Early Wins & Celebration** 🎉
- Immediate "I did it!" moment after setup
- Celebrate small wins (setup, first milestone)
- Show progress, not just final scores
- Make it feel like joining a community, not a competition
### 3. **Privacy-First** 🔒
- **Default**: Everything local, nothing shared
- **Opt-in sharing**: Clear consent for public leaderboard
- **Anonymized**: System specs only, no personal data
- **Institutional friendly**: Works for classroom use
### 4. **Progressive Engagement** 📈
- Level 1: Local benchmark (everyone can do)
- Level 2: Share anonymously (low commitment)
- Level 3: Public leaderboard (for those who want it)
- Level 4: Badges/achievements (long-term engagement)
### 5. **Inclusive, Not Exclusive** 🌍
- Don't make it feel competitive
- Focus on "you're part of something bigger"
- Celebrate participation, not just top performers
- Show diversity (different systems, different progress levels)
## Recommended Design
### Phase 1: Local Celebration (Everyone)
**After `tito benchmark baseline`:**
```
🎉 Welcome to the TinyTorch Community!
✅ Setup Verified
✅ Milestones Validated: 3/6
📊 Baseline Score: 85/100
🌍 You're now part of a global community of ML systems builders!
💡 Tip: Run 'tito benchmark submit' to see how you compare
(completely optional, all data stays local by default)
```
**Key**: Celebrate success, mention community, but don't pressure sharing.
### Phase 2: Anonymous Comparison (Low Commitment)
**After `tito benchmark submit` (anonymous mode):**
```
✅ Benchmark submitted anonymously!
📊 Your Performance:
• Score: 85/100
• Percentile: Top 25%
• System: Similar to 1,234 other users
🎯 You're doing great! Keep building!
💡 Run 'tito benchmark baseline' anytime to track your progress
```
**Key**: Show comparison without requiring identity.
### Phase 3: Public Leaderboard (Opt-in)
**After `tito benchmark submit --public`:**
```
✅ Added to public leaderboard!
🏆 Your Rank: #1,234 (Top 25%)
🌍 View leaderboard: https://tinytorch.ai/leaderboard
🎖️ Badge Earned: "🚀 First Steps"
💡 Share your achievement: [Generate share card]
```
**Key**: Make sharing optional and rewarding.
## Implementation Strategy
### 1. Benchmark Command Structure
```bash
# Generate baseline (always local)
tito benchmark baseline
# → Creates: benchmarks/baseline_TIMESTAMP.json
# → Shows celebration message
# → No network calls
# Submit anonymously (low commitment)
tito benchmark submit
# → Uploads anonymized data
# → Gets back: percentile, comparison stats
# → No personal info shared
# Submit publicly (opt-in)
tito benchmark submit --public
# → Adds to leaderboard
# → Gets rank, badge
# → Can share achievement
```
### 2. Privacy Model
**Three Tiers:**
1. **Local Only** (Default)
- Benchmarks saved to `benchmarks/` directory
- No network calls
- Complete privacy
2. **Anonymous Submission**
- Uploads: system specs, benchmark scores, milestone status
- No personal identifiers
- Gets back: percentile, comparison stats
- Can't be traced back to user
3. **Public Leaderboard** (Opt-in)
- Requires `--public` flag
- Can optionally add: GitHub username, location (country)
- Shows on public leaderboard
- Can generate shareable card
### 3. Leaderboard Design
**Features:**
- **Anonymized by default**: Show system specs, not names
- **Filterable**: By system type, date, milestone status
- **Inclusive**: Show all participants, not just top 10
- **Progress-focused**: Show "milestones completed" not just "fastest"
- **Diverse**: Highlight different system types, not just fastest
**Example Leaderboard Entry:**
```
Rank | System Type | Milestones | Score | Date
-----|------------------|------------|-------|----------
#1 | Apple Silicon | 6/6 ✅ | 95 | Nov 2024
#234 | Linux x86 | 3/6 🚧 | 85 | Nov 2024
#567 | Windows | 1/6 🚧 | 70 | Nov 2024
```
### 4. Badge System
**Achievement Badges** (not competitive):
- 🚀 **First Steps**: Completed baseline benchmark
- ⚡ **Fast Setup**: Setup completed quickly
- 🏆 **Milestone Master**: All 6 milestones passed
- 🌍 **Community Member**: Submitted to leaderboard
- 📈 **Progress Maker**: Improved score over time
- 🎓 **Module Master**: Completed all 20 modules
**Philosophy**: Celebrate progress, not competition.
### 5. Server Architecture
**Simple & Scalable:**
**Option A: GitHub Pages + GitHub API** (Recommended)
- Store submissions as JSON files in `gh-pages` branch
- Use GitHub API for submissions
- Static leaderboard page
- Free, reliable, no server maintenance
**Option B: Simple API** (Future)
- Flask/FastAPI endpoint
- SQLite/PostgreSQL database
- Real-time leaderboard
- More features, but requires hosting
**Recommendation**: Start with GitHub Pages, scale later if needed.
## User Experience Flow
### First Time User
```bash
# 1. Setup
git clone ...
./setup-environment.sh
tito system doctor # ✅ All checks passed!
# 2. Run milestones (if completed)
tito milestone validate --all
# ✅ Milestone 01: PASSED
# ✅ Milestone 02: PASSED
# ✅ Milestone 03: PASSED
# 3. Generate baseline
tito benchmark baseline
# 🎉 Welcome to the TinyTorch Community!
# ✅ Setup Verified
# ✅ Milestones Validated: 3/6
# 📊 Baseline Score: 85/100
#
# 🌍 You're now part of a global community of ML systems builders!
#
# 💡 Tip: Run 'tito benchmark submit' to see how you compare
# (completely optional, all data stays local by default)
# 4. (Optional) See comparison
tito benchmark submit
# ✅ Benchmark submitted anonymously!
# 📊 Your Performance:
# • Score: 85/100
# • Percentile: Top 25%
# • Similar systems: 1,234 users
#
# 🎯 You're doing great! Keep building!
# 5. (Optional) Join public leaderboard
tito benchmark submit --public
# ✅ Added to public leaderboard!
# 🏆 Rank: #1,234 (Top 25%)
# 🎖️ Badge: "🚀 First Steps"
# 🔗 View: https://tinytorch.ai/leaderboard
```
## Key Recommendations
### ✅ DO:
1. **Make it opt-in**: Default to local-only
2. **Celebrate participation**: Not just winners
3. **Show progress**: Milestones completed, not just speed
4. **Respect privacy**: Anonymized by default
5. **Keep it simple**: Start with GitHub Pages
6. **Focus on community**: "You're part of something bigger"
7. **Make it inclusive**: All skill levels welcome
### ❌ DON'T:
1. **Don't make it required**: Some students/institutions can't share
2. **Don't make it competitive**: Focus on learning, not winning
3. **Don't collect personal data**: System specs only
4. **Don't overcomplicate**: Start simple, iterate
5. **Don't exclude anyone**: All systems, all progress levels
## Implementation Priority
### Phase 1: MVP (Week 1)
- ✅ `tito benchmark baseline` command
- ✅ Local JSON generation
- ✅ Celebration message
- ✅ Basic benchmark suite
### Phase 2: Community (Week 2)
- ✅ `tito benchmark submit` (anonymous)
- ✅ GitHub Pages leaderboard
- ✅ Percentile calculation
- ✅ Badge system
### Phase 3: Engagement (Week 3)
- ✅ Public leaderboard (opt-in)
- ✅ Shareable cards
- ✅ Progress tracking
- ✅ Achievement badges
## Success Metrics
**Community Health:**
- Number of baseline benchmarks generated (local)
- Number of anonymous submissions
- Number of public leaderboard entries
- Diversity of systems represented
- Milestone completion rates
**Not Success Metrics:**
- ❌ Highest scores (too competitive)
- ❌ Fastest times (excludes slower systems)
- ❌ Leaderboard rank (creates pressure)
## Final Recommendation
**Start Simple, Build Community:**
1. **Local celebration first** - Everyone gets the "wow" moment
2. **Anonymous comparison** - Low commitment, high value
3. **Public leaderboard** - Opt-in for those who want it
4. **Focus on progress** - Celebrate milestones, not speed
5. **Privacy-first** - Default to local, opt-in to share
**The goal**: Make students feel part of a global community of ML systems builders, not competitors.
This creates a welcoming, inclusive community that celebrates learning and progress! 🎉

371
binder/COMMUNITY_MAP_VISION.md
View File

@@ -1,371 +0,0 @@
# Community Map Vision: "We Are TinyTorch"
## The Vision
A **world map** that shows where TinyTorch builders are located, creating a visual sense of global community. When students complete milestones and submit, they see:
> "Wow, there's a community of people building ML systems all over the world!"
## Design Concept
### The Map Experience
**After `tito milestone validate --all` passes:**
```
🎉 Congratulations! All Milestones Validated!
✅ Setup Complete
✅ All Tests Passing
✅ All Milestones Passed: 6/6
🌍 Join the Global TinyTorch Community:
Run 'tito community submit' to add your location to the map
and see builders from around the world!
(Completely optional - only shares country, not exact location)
```
**After `tito community submit`:**
```
✅ You've joined the TinyTorch Community!
📍 Your Location: United States
🌍 View the map: https://tinytorch.ai/community
🎖️ You're builder #1,234 on the global map!
💡 See where other TinyTorch builders are located worldwide
```
### The Map Visualization
**Features:**
- **World map** with dots/countries highlighted
- **Interactive**: Click to see stats per country
- **Live counter**: "1,234 builders worldwide"
- **Diversity showcase**: "Builders in 45 countries"
- **Recent additions**: "5 new builders this week"
**Privacy:**
- **Country-level only** (not city/coordinates)
- **Opt-in**: Must explicitly submit
- **Anonymized**: No personal identifiers
- **Optional**: Can participate without location
## Implementation Design
### 1. Submission Flow
**Command**: `tito community submit [--country COUNTRY]`
**What it does:**
- Detects country (or asks user)
- Validates milestones passed
- Submits anonymized data:
```json
{
"timestamp": "2024-11-20T10:30:00Z",
"country": "United States", // Country only, not city
"milestones_passed": 6,
"system_type": "Apple Silicon",
"anonymous_id": "abc123..." // Generated hash, not personal
}
```
**Validation:**
- Checks: `tito system doctor` passed
- Checks: `tito milestone validate --all` passed
- Only submits if everything validated
### 2. Map Visualization
**Technology Options:**
**Option A: Simple Static Map** (Recommended for MVP)
- GitHub Pages + Leaflet.js or Mapbox
- JSON file with submissions
- Static map that updates on deploy
- Free, simple, works immediately
**Option B: Interactive Map**
- Leaflet.js or Mapbox GL
- Real-time updates
- Click countries for stats
- More engaging, requires API
**Option C: GitHub Pages + GeoJSON**
- Store submissions as GeoJSON
- Use GitHub's map rendering
- Simple, free, GitHub-native
**Recommendation**: Start with Option A (Leaflet.js), upgrade to Option B later.
### 3. Data Structure
**Submissions JSON** (`community/submissions.json`):
```json
{
"total_builders": 1234,
"countries": {
"United States": 456,
"India": 234,
"United Kingdom": 123,
"Germany": 89,
...
},
"recent_submissions": [
{
"timestamp": "2024-11-20T10:30:00Z",
"country": "United States",
"milestones": 6,
"system": "Apple Silicon"
},
...
],
"stats": {
"total_countries": 45,
"this_week": 23,
"this_month": 156
}
}
```
### 4. Map Page Design
**URL**: `https://tinytorch.ai/community` or `/community-map`
**Features:**
- **World map** with country highlights
- **Counter**: "1,234 builders worldwide"
- **Country list**: "Builders in 45 countries"
- **Recent activity**: "5 new builders this week"
- **Call to action**: "Join the map → `tito community submit`"
**Visual Design:**
- Clean, modern map
- Dots or country shading
- Hover shows country stats
- Mobile-friendly
- Fast loading
## User Journey
### Complete Flow
```bash
# 1. Setup and validate
git clone ...
./setup-environment.sh
tito system doctor # ✅ All checks passed
tito milestone validate --all # ✅ All 6 milestones passed
# 2. Join community
tito community submit
# Detecting your location...
# Country: United States
#
# ✅ You've joined the TinyTorch Community!
#
# 🌍 View the map: https://tinytorch.ai/community
# 🎖️ You're builder #1,234 on the global map!
#
# 💡 See where other TinyTorch builders are located worldwide
# 3. View the map (opens in browser)
# Shows: World map with dots, your country highlighted
# Shows: "1,234 builders in 45 countries"
# Shows: Recent additions
```
## Privacy & Consent
### Privacy Model
**What's Shared** (with consent):
- ✅ Country (not city/coordinates)
- ✅ System type (Apple Silicon, Linux x86, etc.)
- ✅ Milestone count (how many passed)
- ✅ Timestamp (when submitted)
**What's NOT Shared**:
- ❌ Exact location
- ❌ Personal information
- ❌ IP address
- ❌ Email/name
- ❌ Institution
**Consent Flow:**
```
tito community submit
⚠️ This will add your location to the public community map.
📊 What will be shared:
• Country: United States
• System type: Apple Silicon
• Milestones passed: 6
• No personal information
🔒 Privacy: Only country-level location, completely anonymized
Continue? [y/N]: y
✅ Submitted! View map: https://tinytorch.ai/community
```
## Implementation Steps
### Phase 1: MVP (Simple Map)
1. **Create `tito community submit` command**
- Detect/ask for country
- Validate milestones passed
- Generate submission JSON
- Save locally + optionally upload
2. **Create map page** (`site/community-map.md`)
- Static HTML with Leaflet.js
- Reads from `community/submissions.json`
- Shows world map with countries
- Displays stats
3. **Submission storage**
- GitHub Pages: `community/submissions.json`
- Or: Simple API endpoint
- Updates on each submission
### Phase 2: Enhanced (Interactive Map)
1. **Interactive features**
- Click countries for details
- Filter by system type
- Timeline view (growth over time)
- Recent submissions feed
2. **Engagement features**
- "Builder of the week" (random selection)
- Country leaderboards (optional)
- Milestone completion stats
### Phase 3: Community Features
1. **Social elements**
- Share: "I'm builder #1,234 on the TinyTorch map!"
- Badges: "🌍 Global Builder"
- Stories: "Builders from 45 countries"
2. **Analytics**
- Growth over time
- Geographic distribution
- System diversity
- Milestone completion rates
## Technical Implementation
### Simple Approach (GitHub Pages)
**File Structure:**
```
community/
├── submissions.json # All submissions
├── map.html # Map visualization page
└── submit.py # Submission script (optional API)
```
**Map Page** (`site/community-map.md` or HTML):
```html
<!-- Leaflet.js map -->
<div id="community-map"></div>
<!-- Stats -->
<div>
<h2>🌍 TinyTorch Community</h2>
<p>1,234 builders in 45 countries</p>
<p>5 new builders this week</p>
</div>
<!-- Call to action -->
<p>Join the map: <code>tito community submit</code></p>
```
**Submission Process:**
1. User runs `tito community submit`
2. Generates submission JSON
3. Option A: User manually PRs to `community/submissions.json`
4. Option B: API endpoint accepts submissions
5. Map page reads JSON and renders
### API Approach (Future)
**Endpoint**: `POST /api/community/submit`
- Accepts submission JSON
- Validates (check milestones)
- Stores in database
- Returns success + map URL
**Map Page**:
- Fetches submissions from API
- Renders interactive map
- Updates in real-time
## Success Metrics
**Community Growth:**
- Number of countries represented
- Total builders on map
- Growth rate (new builders/week)
- Geographic diversity
**Engagement:**
- Map page views
- Submission rate (after milestones pass)
- Return visits to map
- Social shares
## The "Wow" Moment
**When someone views the map:**
```
🌍 TinyTorch Community Map
[Interactive world map showing dots/countries]
📊 Stats:
• 1,234 builders worldwide
• 45 countries represented
• 5 new builders this week
• Top countries: US (456), India (234), UK (123)
🎯 Recent Activity:
• Builder from Germany just joined!
• Builder from Japan completed all milestones!
• Builder from Brazil reached milestone 3!
💡 Join the map: Run 'tito community submit' after completing milestones
```
**The Impact:**
- Visual proof of global community
- Sense of belonging
- Motivation to continue
- Pride in being part of something bigger
## Recommendation
**Start Simple, Build Community:**
1. **MVP**: Simple map with country dots
2. **Privacy**: Country-level only, opt-in
3. **Validation**: Only after milestones pass
4. **Visual**: Make it beautiful and engaging
5. **Growth**: Let it populate organically
**The goal**: Create a visual representation that makes students feel part of a global movement of ML systems builders!
This map becomes a symbol of the TinyTorch community - showing that people all over the world are building ML systems from scratch together. 🌍✨

144
binder/LAUNCH_READINESS.md
View File

@@ -1,144 +0,0 @@
# Launch Readiness Checklist
## ✅ Assignment Process - COMPLETE
### Dynamic Assignment Generation ✅
- **Source**: `modules/*/.*_dev.py` (Python files)
- **Command**: `tito nbgrader generate MODULE`
- **Output**: `assignments/source/MODULE/MODULE.ipynb`
- **Status**: Fully functional, dynamically generated
### Assignment Release ✅
- **Command**: `tito nbgrader release MODULE`
- **Output**: `assignments/release/MODULE/MODULE.ipynb` (solutions removed)
- **Status**: Ready for student distribution
### Auto-Grading ✅
- **Command**: `tito nbgrader autograde MODULE`
- **Status**: NBGrader integration complete
## ✅ Site Build Integration - COMPLETE
### Automatic Notebook Preparation ✅
- **Script**: `site/prepare_notebooks.sh`
- **Integration**: Runs automatically during `make html`
- **Process**: Copies assignment notebooks to `site/chapters/modules/`
- **Result**: Launch buttons appear on notebook pages
### Build Commands ✅
- `make html` - Includes notebook preparation
- `make pdf` - Includes notebook preparation
- `make pdf-simple` - Includes notebook preparation
## ✅ Paper Documentation Sync - COMPLETE
### Files Created ✅
- `INSTRUCTOR.md` - ✅ Created (matches paper reference)
- `MAINTENANCE.md` - ✅ Created (support commitment through 2027)
- `TA_GUIDE.md` - ✅ Created (common errors, debugging strategies)
- `docs/TEAM_ONBOARDING.md` - ✅ Created (Model 3 documentation)
- `site/usage-paths/team-onboarding.md` - ✅ Created (site version)
### Files Verified ✅
- `CONTRIBUTING.md` - ✅ Exists and matches paper description
- `docs/INSTRUCTOR_GUIDE.md` - ✅ Exists (source for INSTRUCTOR.md)
### Content Updates ✅
- Module numbers: All updated to `01_tensor` (not `01_setup`)
- Schedule: Updated to match current 20-module structure
- Three integration models: All documented
- Deployment environments: All documented
## ✅ Site Navigation - COMPLETE
### Getting Started Section ✅
- Quick Start Guide
- Student Workflow
- For Instructors
- **Team Onboarding** (newly added)
### All Three Integration Models Accessible ✅
1. Self-Paced Learning - Quick Start Guide
2. Institutional Integration - For Instructors
3. Team Onboarding - Team Onboarding page
## ✅ Binder/Colab Setup - COMPLETE
### Binder Configuration ✅
- `binder/requirements.txt` - Dependencies
- `binder/postBuild` - Installs TinyTorch
- Launch buttons configured in `site/_config.yml`
### Colab Configuration ✅
- Launch buttons configured
- Repository URL correct
- Documentation complete
## 🎯 Pre-Launch Checklist
### Required Actions
1. **Generate Assignment Notebooks**:
```bash
tito nbgrader generate --all
```
This creates notebooks for all modules in `assignments/source/`
2. **Test Site Build**:
```bash
cd site
make html
```
Verify:
- Notebooks are prepared automatically
- Launch buttons appear on notebook pages
- Site builds without errors
3. **Test Binder**:
- Visit: https://mybinder.org/v2/gh/mlsysbook/TinyTorch/main
- Verify build completes (2-5 minutes)
- Verify TinyTorch imports correctly
- Verify modules are accessible
4. **Test Colab**:
- Test with sample notebook
- Verify dependencies install
- Verify notebooks run correctly
5. **Verify Documentation Links**:
- Check all site navigation links work
- Verify INSTRUCTOR.md accessible
- Verify TA_GUIDE.md accessible
- Verify Team Onboarding page works
### Optional Enhancements
- Add sample solutions to INSTRUCTOR.md (if not already included)
- Create common errors FAQ page
- Add deployment guide consolidating JupyterHub/Colab/Local
- Test with actual assignment notebooks
## 📊 Final Status
| Component | Status | Ready for Launch |
|-----------|--------|-----------------|
| Assignment Generation | ✅ Complete | ✅ Yes |
| Site Build Integration | ✅ Complete | ✅ Yes |
| Paper Documentation | ✅ Complete | ✅ Yes |
| Site Navigation | ✅ Complete | ✅ Yes |
| Binder Setup | ✅ Complete | ⏳ Test needed |
| Colab Setup | ✅ Complete | ⏳ Test needed |
## 🚀 Launch Steps
1. Generate assignment notebooks: `tito nbgrader generate --all`
2. Build site: `cd site && make html`
3. Test Binder: Visit Binder URL
4. Test Colab: Test with sample notebook
5. Verify all links work
6. **LAUNCH!** 🎉
---
**Everything is synced and ready!** Just need to generate notebooks and test launch buttons.

117
binder/MARIMO_INTEGRATION.md
View File

@@ -1,117 +0,0 @@
# Marimo Integration for TinyTorch
## What is Marimo?
[Marimo](https://marimo.io/) is a modern, reactive Python notebook platform that:
- **Stores notebooks as pure Python** (`.py` files) - Git-friendly!
- **Reactive execution** - Cells update automatically when dependencies change
- **Interactive elements** - Built-in widgets, sliders, dataframes
- **AI-native** - Built-in AI assistance and copilots
- **Share as apps** - Export to HTML or serve as web apps
- **Reproducible** - Deterministic execution, no hidden state
## Why Marimo for TinyTorch?
**Perfect Fit:**
1. ✅ **Git-friendly** - Notebooks stored as `.py` files (matches TinyTorch's Python-first approach!)
2. ✅ **Reactive** - Great for teaching (students see changes propagate automatically)
3. ✅ **Educational** - Used by Stanford, UC Berkeley, Princeton, etc.
4. ✅ **Modern** - Better than Jupyter for many use cases
5. ✅ **Open source** - Free and community-driven
## Marimo vs Current Options
| Feature | MyBinder | Colab | Marimo |
|---------|----------|-------|--------|
| Git-friendly | ❌ (.ipynb) | ❌ (.ipynb) | ✅ (.py files) |
| Reactive | ❌ | ❌ | ✅ |
| AI assistance | ❌ | ✅ | ✅ |
| Free | ✅ | ✅ | ✅ |
| Zero-setup | ✅ | ⚠️ (needs account) | ✅ |
| GPU access | ❌ | ✅ | ⚠️ (limited) |
## Integration Options
### Option 1: Marimo Molab Badges
Marimo provides "molab" badges that can open notebooks directly from GitHub:
```
https://marimo.app/molab?repo=mlsysbook/TinyTorch&path=path/to/notebook.py
```
**How it works:**
- Notebooks stored as `.py` files in repo
- Badge links to marimo's cloud service
- Opens notebook in marimo's online editor
- No local installation needed
### Option 2: Add to Launch Buttons
Jupyter Book doesn't natively support marimo launch buttons, but we can:
1. Add custom HTML/JavaScript to create marimo badges
2. Use marimo's badge generator
3. Add manual links in notebook pages
### Option 3: Convert Notebooks to Marimo Format
Since marimo uses `.py` files, we could:
1. Keep current `.ipynb` files for Jupyter/Colab/Binder
2. Generate `.py` versions for marimo
3. Add marimo badges alongside existing launch buttons
## Recommendation
**Add Marimo as an Option:**
1. **Keep current setup** (MyBinder + Colab) - they work well
2. **Add marimo badges** to notebook pages for students who want reactive notebooks
3. **Generate `.py` versions** of notebooks for marimo compatibility
**Benefits:**
- Students get choice of notebook platforms
- Marimo's reactive execution helps with learning
- Git-friendly format aligns with TinyTorch's Python-first approach
- Modern, educational tool used by top universities
## Implementation Steps
### Step 1: Generate Marimo-Compatible Notebooks
Since TinyTorch already uses Python-first development (`*_dev.py` files), we could:
- Convert assignment notebooks to marimo format
- Or create marimo-specific versions
### Step 2: Add Marimo Badges
Add to notebook pages:
```html
<a href="https://marimo.app/molab?repo=mlsysbook/TinyTorch&path=site/chapters/modules/01_tensor.py">
<img src="https://marimo.app/badge.svg" alt="Open in Marimo">
</a>
```
### Step 3: Document Marimo Usage
Add to student documentation:
- How to use marimo with TinyTorch
- Benefits of reactive notebooks
- Comparison with Jupyter/Colab
## Current Status
**Not yet integrated** - but marimo would be a great addition!
**Next steps if you want to add it:**
1. Test marimo with TinyTorch notebooks
2. Generate marimo-compatible `.py` files
3. Add badges to site pages
4. Update documentation
## Resources
- [Marimo Website](https://marimo.io/)
- [Marimo Docs](https://docs.marimo.io/)
- [Marimo Gallery](https://marimo.io/gallery)
- [Marimo Badge Generator](https://marimo.io/badge)

104
binder/MARIMO_NBGRADER_COMPATIBILITY.md
View File

@@ -1,104 +0,0 @@
# Marimo and NBGrader Compatibility
## Short Answer: ✅ No, Marimo badges won't break NBGrader
**Why:**
- Marimo badges are just **frontend UI elements** (JavaScript links)
- They don't modify notebook files
- NBGrader reads from actual `.ipynb` files, not from the website
- Badges just create links to open notebooks in Marimo's cloud service
## How It Works
### Marimo Badges (What We Added)
- **What they do**: Add a "🍃 Open in Marimo" link to notebook pages
- **What they don't do**: Modify notebook files or NBGrader metadata
- **Impact on NBGrader**: **None** - they're just links
### NBGrader Workflow
1. Instructors generate notebooks: `tito nbgrader generate MODULE`
2. NBGrader adds metadata to `.ipynb` files (grade_id, points, etc.)
3. Students work in notebooks (Jupyter, Colab, or Marimo)
4. Students submit notebooks back
5. NBGrader reads metadata from submitted `.ipynb` files
## Potential Considerations
### If Students Use Marimo to Edit Notebooks
**Scenario 1: Students open `.ipynb` in Marimo**
- ✅ Marimo can import Jupyter notebooks
- ✅ NBGrader metadata preserved (it's in the `.ipynb` file)
- ✅ Students submit `.ipynb` files back
- ✅ **No problem** - NBGrader works normally
**Scenario 2: Students convert to Marimo `.py` format**
- ⚠️ Marimo stores notebooks as `.py` files (not `.ipynb`)
- ⚠️ NBGrader metadata is in `.ipynb` format
- ⚠️ Converting to `.py` might lose NBGrader metadata
- ✅ **Solution**: Students should submit `.ipynb` files, not `.py` files
## Best Practice for Students
**For NBGrader assignments:**
1. Students can use Marimo to **view and learn** from notebooks
2. For **submissions**, students should work in `.ipynb` format (Jupyter/Colab)
3. Or convert marimo `.py` back to `.ipynb` before submitting
**For non-graded exploration:**
- Students can freely use Marimo's `.py` format
- Great for learning and experimentation
- No NBGrader concerns
## Recommendation
**Keep Marimo badges** - they're safe:
- ✅ Don't interfere with NBGrader
- ✅ Give students more options for learning
- ✅ Students can use Marimo for exploration
- ✅ For graded work, students use standard `.ipynb` workflow
**Add to student instructions:**
- "Marimo badges are for exploration and learning"
- "For NBGrader assignments, submit `.ipynb` files (not `.py` files)"
- "Marimo can import `.ipynb` files and preserve NBGrader metadata"
## Technical Details
### NBGrader Metadata Format
NBGrader stores metadata in notebook cell metadata:
```json
{
"nbgrader": {
"grade": true,
"grade_id": "tensor_memory",
"points": 2,
"schema_version": 3
}
}
```
### Marimo Format
Marimo stores notebooks as pure Python:
```python
# Cell 1
import numpy as np
# Cell 2
def memory_footprint(self):
return self.data.nbytes
```
**Conversion between formats:**
- `.ipynb` → `.py`: Possible, but NBGrader metadata might be lost
- `.py` → `.ipynb`: Possible, but NBGrader metadata won't be restored
## Conclusion
✅ **Marimo badges are safe** - they don't break NBGrader
✅ **Students can use Marimo** for learning and exploration
✅ **For graded work**, students should use `.ipynb` format
✅ **No changes needed** to NBGrader workflow
The badges are just convenient links - they don't interfere with the actual grading system!

80
binder/MARIMO_SETUP.md
View File

@@ -1,80 +0,0 @@
# Marimo Setup for TinyTorch - No Extra Setup Required! ✅
## Good News: No Extra Setup Needed!
Marimo integration is now **automatically added** to your site. Here's what was done:
## What Was Added
1. **Marimo Badge JavaScript** (`site/_static/marimo-badges.js`)
- Automatically adds "Open in Marimo" badges to notebook pages
- Works alongside existing Binder/Colab buttons
2. **JavaScript Integration**
- Added to `site/_config.yml` so it loads on all pages
- Automatically detects notebook pages
- Creates marimo badges dynamically
## How It Works
When students visit a notebook page:
1. They see existing launch buttons (Binder, Colab)
2. **New**: They also see "🍃 Open in Marimo" badge
3. Clicking opens the notebook in Marimo's cloud service (molab)
4. No account needed for basic use!
## Marimo URLs
Marimo badges use this format:
```
https://marimo.app/molab?repo=mlsysbook/TinyTorch&path=site/chapters/modules/MODULE_NAME.ipynb
```
**Note**: Marimo can work with `.ipynb` files, but ideally we'd convert to `.py` files for full marimo features.
## Testing
To test marimo integration:
1. **Build the site:**
```bash
cd site
make html
```
2. **Open a notebook page** (e.g., `_build/html/chapters/modules/01_tensor.html`)
3. **Look for the marimo badge** - should appear below Binder/Colab buttons
4. **Click "Open in Marimo"** - should open in marimo's cloud editor
## Optional: Convert Notebooks to Marimo Format
For full marimo features (reactive execution, etc.), you could:
1. **Convert `.ipynb` to marimo `.py` format:**
```bash
# Marimo can import Jupyter notebooks
marimo convert notebook.ipynb notebook.py
```
2. **Store marimo versions** in `site/chapters/modules/` as `.py` files
3. **Update marimo URLs** to point to `.py` files instead of `.ipynb`
But this is **optional** - marimo badges work with `.ipynb` files too!
## Current Status
✅ **Marimo badges added** - Will appear on notebook pages
✅ **No extra setup needed** - Just build the site
✅ **Works with existing notebooks** - Uses `.ipynb` files
## Next Steps
1. **Build site** to see marimo badges: `cd site && make html`
2. **Test badges** on notebook pages
3. **Optional**: Convert notebooks to marimo `.py` format for full features
That's it! Marimo integration is ready to go. 🎉

91
binder/MODULE_ORDER.md
View File

@@ -1,91 +0,0 @@
# TinyTorch Module Order Verification
## ✅ Correct Module Order (modules/ directory)
```
01_tensor - Foundation: N-dimensional arrays
02_activations - Non-linearity functions (ReLU, Sigmoid, Softmax)
03_layers - Neural network layers (Linear, Module base)
04_losses - Loss functions (MSE, CrossEntropy)
05_autograd - Automatic differentiation
06_optimizers - Optimization algorithms (SGD, Adam)
07_training - Training loops
08_dataloader - Data batching and pipelines
09_spatial - Convolutional operations
10_tokenization - Text tokenization
11_embeddings - Word embeddings
12_attention - Attention mechanisms
13_transformers - Transformer architecture
14_profiling - Performance profiling
15_quantization - Model quantization
16_compression - Model compression
17_memoization - KV caching
18_acceleration - Hardware acceleration
19_benchmarking - Performance benchmarking
20_capstone - Torch Olympics competition
```
## ⚠️ Issue Found: Assignments Directory Mismatch
**Current assignments/source/ structure:**
```
01_setup ❌ OUTDATED - Module 01 is now "tensor", not "setup"
02_tensor ✅ Correct
```
**Problem:** The `assignments/source/01_setup/` directory contains an old notebook from when Module 01 was "Setup". Module 01 is now "Tensor" (`modules/01_tensor/`).
## Impact on Binder/Colab
**No impact** - Binder setup doesn't depend on assignment notebooks. The `binder/` configuration:
- Installs TinyTorch package (`pip install -e .`)
- Provides JupyterLab environment
- Students can access any notebooks in the repository
However, for consistency and to avoid confusion:
- Old `01_setup` assignment should be removed or renamed
- Documentation references should point to `01_tensor` (already fixed)
## Module Tiers (from site/_toc.yml)
### 🏗️ Foundation Tier (01-07)
- 01 Tensor
- 02 Activations
- 03 Layers
- 04 Losses
- 05 Autograd
- 06 Optimizers
- 07 Training
### 🏛️ Architecture Tier (08-13)
- 08 DataLoader
- 09 Spatial (Convolutions)
- 10 Tokenization
- 11 Embeddings
- 12 Attention
- 13 Transformers
### ⏱️ Optimization Tier (14-19)
- 14 Profiling
- 15 Quantization
- 16 Compression
- 17 Memoization
- 18 Acceleration
- 19 Benchmarking
### 🏅 Capstone (20)
- 20 Capstone (Torch Olympics)
## Verification Status
✅ **Modules directory**: Correct order (01-20)
✅ **Documentation**: References updated to `01_tensor`
✅ **Binder setup**: Not affected by assignment structure
⚠️ **Assignments**: Contains outdated `01_setup` (should be removed)
## Recommendations
1. **Remove old assignment**: Delete `assignments/source/01_setup/` and `assignments/release/01_setup/`
2. **Verify nbgrader**: Ensure nbgrader commands reference correct module numbers
3. **Update any remaining references**: Search for `01_setup` and update to `01_tensor`

89
binder/NOTEBOOK_PLATFORM_RECOMMENDATION.md
View File

@@ -1,89 +0,0 @@
# Notebook Platform Recommendation
## Current Setup
- **MyBinder**: Zero-setup, no account needed
- **Google Colab**: GPU access, familiar interface
- **Marimo**: Modern reactive notebooks, Git-friendly
## Analysis: Do We Need All Three?
### Use Case: Viewing/Exploration Only
Since online notebooks are **only for viewing/exploration** (not actual work), we should consider:
**Option 1: Keep All Three** ✅
- **Pros**:
- Students get choice
- Different platforms have different strengths
- Binder: Zero-setup, no account
- Colab: GPU access for exploration
- Marimo: Modern, educational
- **Cons**:
- Might be confusing (too many options)
- More maintenance
**Option 2: Keep Just Binder** ✅ Recommended
- **Pros**:
- Simplest option (zero-setup, no account)
- Works for viewing/exploration
- Less confusing for students
- Easier maintenance
- **Cons**:
- No GPU access (but not needed for viewing)
- No Marimo features (but not needed for viewing)
**Option 3: Keep Binder + One Other**
- Binder + Colab: Covers zero-setup + GPU exploration
- Binder + Marimo: Covers zero-setup + modern interface
## Recommendation: Keep Just Binder ✅
**Reasoning:**
1. **Primary use case**: Viewing/exploration (not actual work)
2. **Binder is sufficient**: Zero-setup, no account, works for viewing
3. **Simpler is better**: Less confusion, easier maintenance
4. **Local is required anyway**: Students need local setup for real work
**What to remove:**
- Colab launch buttons (students can still use Colab if they want, just not prominently featured)
- Marimo badges (can add back later if there's demand)
**What to keep:**
- Binder launch buttons (zero-setup viewing)
- Clear messaging: "For viewing only - local setup required for full package"
## Alternative: Keep Binder + Colab
If you want GPU access for exploration:
- **Keep**: Binder (zero-setup) + Colab (GPU exploration)
- **Remove**: Marimo (newest, least familiar)
## Implementation
If we simplify to just Binder:
1. **Update `site/_config.yml`:**
```yaml
launch_buttons:
binderhub_url: "https://mybinder.org"
# Remove colab_url
```
2. **Remove Marimo JavaScript:**
- Remove `marimo-badges.js` from `extra_js`
- Or keep it but make it optional
3. **Update documentation:**
- Clarify that Binder is for viewing only
- Emphasize local setup requirement
## Final Recommendation
**Keep just Binder** because:
- ✅ Simplest option
- ✅ Zero-setup (no account needed)
- ✅ Sufficient for viewing/exploration
- ✅ Less confusing
- ✅ Students need local setup anyway for real work
**Optional**: Keep Colab if you want GPU access for exploration, but it's not essential since students need local setup for actual coursework.

105
binder/ONLINE_VS_LOCAL.md
View File

@@ -1,105 +0,0 @@
# Online Notebooks vs Local Setup
## Important Distinction
### Online Notebooks (Binder, Colab, Marimo)
**Purpose**: Viewing, learning, exploration
**What you CAN do:**
- ✅ View notebook content
- ✅ Read code and explanations
- ✅ Run basic code cells
- ✅ Learn from examples
**What you CANNOT do:**
- ❌ Import from `tinytorch.*` package (not installed)
- ❌ Run milestone validation scripts
- ❌ Use `tito` CLI commands
- ❌ Execute full experiments
- ❌ Export modules to package
- ❌ Complete the full development workflow
### Local Setup (Required)
**Purpose**: Full package, experiments, milestone validation
**What you CAN do:**
- ✅ Full `tinytorch.*` package available
- ✅ Run milestone validation scripts
- ✅ Use `tito` CLI commands (`tito module complete`, `tito milestone validate`)
- ✅ Execute complete experiments
- ✅ Export modules to package
- ✅ Full development workflow
## When to Use What
### Use Online Notebooks When:
- 📖 **Learning**: Reading through modules to understand concepts
- 🔍 **Exploration**: Quick look at code examples
- 💡 **Inspiration**: Seeing how things work before implementing
- 🚀 **Quick Start**: Getting familiar with the structure
### Use Local Setup When:
- 🏗️ **Building**: Actually implementing modules
- ✅ **Validating**: Running milestone checks
- 🧪 **Experimenting**: Running full experiments
- 📦 **Exporting**: Completing modules and exporting to package
- 🎯 **Serious Work**: Doing the actual coursework
## Setup Instructions
### Local Setup (Required for Full Package)
```bash
# 1. Clone repository
git clone https://github.com/mlsysbook/TinyTorch.git
cd TinyTorch
# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Install TinyTorch package in editable mode
pip install -e .
# 5. Verify installation
tito system doctor
```
Now you have:
- ✅ Full `tinytorch.*` package available
- ✅ `tito` CLI commands working
- ✅ Milestone scripts executable
- ✅ Complete development environment
## Student Workflow
**Recommended approach:**
1. **Start Online**: Use Binder/Colab/Marimo to explore and understand modules
2. **Switch to Local**: When ready to build, set up local environment
3. **Work Locally**: Implement modules, run milestones, use CLI tools
4. **Submit**: Export and submit `.ipynb` files for grading
## Common Questions
**Q: Can I do everything online?**
A: No. Online notebooks are for viewing/learning. You need local setup for the full package and experiments.
**Q: Do I need both?**
A: Not required, but recommended. Use online for learning, local for building.
**Q: Can I use online notebooks for assignments?**
A: You can view notebooks online, but you'll need local setup to actually complete modules and run milestone validations.
**Q: What if I only have online access?**
A: You can learn from online notebooks, but you won't be able to complete the full coursework without local installation.
## Summary
- **Online Notebooks**: Great for learning and exploration
- **Local Setup**: Required for building, validating, and completing modules
- **Best Practice**: Use online to learn, local to build

165
binder/PAPER_DOCUMENTATION_SYNC.md
View File

@@ -1,165 +0,0 @@
# Paper Documentation Sync Checklist
## Analysis of paper.tex References
Based on analysis of `paper/paper.tex`, here are the documentation/resources mentioned and their status:
## ✅ Resources Mentioned in Paper
### 1. Module Notebooks ✅
**Paper says**: "module notebooks, NBGrader test suites, milestone validation scripts, and connection maps"
**Status**:
- ✅ Module notebooks exist: `modules/*/.*_dev.py` (source)
- ✅ Generated via: `tito nbgrader generate`
- ✅ Assignment notebooks: `assignments/source/`
- ⚠️ Need to ensure all modules have notebooks generated
### 2. NBGrader Test Suites ✅
**Paper says**: "NBGrader autograding infrastructure", "NBGrader test suites"
**Status**:
- ✅ NBGrader integration: `tito/commands/nbgrader.py`
- ✅ NBGrader guide: `docs/INSTRUCTOR_GUIDE.md`
- ✅ NBGrader style guide: `docs/nbgrader/NBGRADER_STYLE_GUIDE.md`
- ✅ NBGrader quick reference: `docs/nbgrader/NBGrader_Quick_Reference.md`
### 3. Milestone Validation Scripts ✅
**Paper says**: "historical milestone validation", "milestone validation scripts"
**Status**:
- ✅ Milestones exist: `milestones/` directory
- ✅ Milestone docs: `site/chapters/milestones.md`
- ✅ Milestone scripts: `milestones/*/` (Python scripts)
### 4. Connection Maps ✅
**Paper says**: "connection maps showing prerequisite dependencies", "Text-based ASCII connection maps"
**Status**:
- ✅ Connection maps in modules: Each module shows dependencies
- ✅ Learning path: `modules/LEARNING_PATH.md`
- ✅ Visual journey: `site/chapters/learning-journey.md`
- ✅ Learning journey visual: `site/learning-journey-visual.md`
### 5. Instructor Guide ✅
**Paper says**: "Institutional deployment provides NBGrader autograding infrastructure"
**Status**:
- ✅ Instructor guide: `docs/INSTRUCTOR_GUIDE.md`
- ✅ Classroom use: `site/usage-paths/classroom-use.md`
- ⚠️ Need to verify it's synced with paper claims
### 6. Student Quickstart ✅
**Paper says**: "Self-Paced Learning (Primary Use Case)", "zero infrastructure beyond Python"
**Status**:
- ✅ Student quickstart: `docs/STUDENT_QUICKSTART.md`
- ✅ Quickstart guide: `site/quickstart-guide.md`
- ✅ Student workflow: `site/student-workflow.md`
### 7. Deployment Environments ✅
**Paper says**: "JupyterHub (institutional server), Google Colab (zero installation), local installation (pip install tinytorch)"
**Status**:
- ✅ Binder setup: `binder/` directory (for JupyterHub/Binder)
- ✅ Colab setup: Configured in `site/_config.yml`
- ✅ Local install: `pyproject.toml` (pip install tinytorch)
- ✅ Documentation: `binder/README.md`, `binder/VERIFY.md`
### 8. Three Integration Models ✅
**Paper says**:
- Model 1: Self-Paced Learning
- Model 2: Institutional Integration
- Model 3: Team Onboarding
**Status**:
- ✅ Self-paced: `site/quickstart-guide.md`, `site/student-workflow.md`
- ✅ Institutional: `site/usage-paths/classroom-use.md`, `docs/INSTRUCTOR_GUIDE.md`
- ⚠️ Team onboarding: May need dedicated page
### 9. Tier Configurations ✅
**Paper says**: "Configuration 1: Foundation Only (Modules 01--07)", "Configuration 2: Foundation + Architecture", "Configuration 3: Optimization Focus"
**Status**:
- ✅ Tier pages: `site/tiers/foundation.md`, `site/tiers/architecture.md`, `site/tiers/optimization.md`
- ✅ Tier overviews in site structure
### 10. Lecture Materials ⚠️
**Paper says**: "Lecture slides for institutional courses remain future work"
**Status**:
- ⚠️ Correctly marked as future work
- ✅ No false promises
## 🔍 Files to Verify/Update
### Critical Files to Check
1. **docs/INSTRUCTOR_GUIDE.md**
- Verify it matches paper claims about NBGrader workflow
- Check that commands match current `tito` CLI
- Ensure module numbers are correct (01_tensor, not 01_setup)
2. **site/usage-paths/classroom-use.md**
- Verify it covers all three integration models
- Check NBGrader workflow matches paper description
- Ensure deployment options match paper
3. **docs/STUDENT_QUICKSTART.md**
- Verify it matches "zero infrastructure" claim
- Check setup instructions are accurate
- Ensure module references are correct
4. **site/quickstart-guide.md**
- Should match student quickstart
- Verify 15-minute claim is realistic
- Check all links work
### Files That Should Exist But May Be Missing
1. **Team Onboarding Guide** ⚠️
- Paper mentions "Model 3: Team Onboarding"
- May need dedicated page or section
- Check: `site/usage-paths/` or `docs/`
2. **Deployment Guide** ⚠️
- Paper describes three environments (JupyterHub, Colab, Local)
- Should have clear deployment instructions
- Check: `binder/README.md` covers this
3. **Connection Maps Documentation** ⚠️
- Paper mentions "connection maps showing prerequisite dependencies"
- Should be clearly documented
- Check: `modules/LEARNING_PATH.md` and site pages
## 📋 Sync Checklist
### Documentation Files
- [ ] `docs/INSTRUCTOR_GUIDE.md` - Verify module numbers, commands match paper
- [ ] `site/usage-paths/classroom-use.md` - Verify three models covered
- [ ] `docs/STUDENT_QUICKSTART.md` - Verify accuracy, module references
- [ ] `site/quickstart-guide.md` - Verify matches student quickstart
- [ ] `binder/README.md` - Verify deployment environments match paper
- [ ] `site/chapters/milestones.md` - Verify milestone descriptions match paper
### Missing Documentation
- [ ] Team Onboarding Guide (Model 3) - Create if missing
- [ ] Deployment Guide - Consolidate JupyterHub/Colab/Local instructions
- [ ] Connection Maps Guide - Document how to read/use connection maps
### Website Sync
- [ ] All documentation linked from site navigation
- [ ] Instructor guide accessible from site
- [ ] Student quickstart prominent on site
- [ ] Deployment options clearly explained
- [ ] Three integration models documented
## 🎯 Action Items
1. **Verify Instructor Guide** matches paper claims
2. **Check module numbers** throughout (01_tensor, not 01_setup)
3. **Create Team Onboarding guide** if missing
4. **Consolidate deployment docs** (JupyterHub/Colab/Local)
5. **Verify all links** in documentation work
6. **Check site navigation** includes all key docs

84
binder/PAPER_FILE_REQUIREMENTS.md
View File

@@ -1,84 +0,0 @@
# Exact File Requirements from paper.tex
## Files Explicitly Mentioned in Paper
Based on line-by-line analysis of `paper/paper.tex`, here are the exact files the paper says should exist:
### Line 988: Repository Instructor Resources
The paper states:
> "The repository includes instructor resources: \texttt{CONTRIBUTING.md} (guidelines for bug reports and curriculum improvements), \texttt{INSTRUCTOR.md} (30-minute setup guide, grading rubrics, common student errors), and \texttt{MAINTENANCE.md} (support commitment through 2027, succession planning for community governance)."
**Required Files**:
1. `CONTRIBUTING.md` - Guidelines for bug reports and curriculum improvements
2. `INSTRUCTOR.md` - 30-minute setup guide, grading rubrics, common student errors
3. ~~`MAINTENANCE.md`~~ - **User doesn't want this** (removed)
### Line 999: TA Guide
The paper states:
> "The repository provides \texttt{TA\_GUIDE.md} documenting frequent student errors (gradient shape mismatches, disconnected computational graphs, broadcasting failures) and debugging strategies."
**Required File**:
4. `TA_GUIDE.md` - Frequent student errors and debugging strategies
### Line 1003: Sample Solutions
The paper states:
> "Sample solutions and grading rubrics in \texttt{INSTRUCTOR.md} calibrate evaluation standards."
**Required Content** (in INSTRUCTOR.md):
- Sample solutions
- Grading rubrics
## Summary: Required Files
| File | Purpose | Status |
|------|---------|--------|
| `CONTRIBUTING.md` | Bug reports, curriculum improvements | ✅ Exists |
| `INSTRUCTOR.md` | Setup guide, grading rubrics, common errors, sample solutions | ✅ Created |
| `TA_GUIDE.md` | Common errors, debugging strategies | ✅ Created |
| `MAINTENANCE.md` | Support commitment | ❌ Removed (user preference) |
## What Each File Should Contain
### CONTRIBUTING.md
- Guidelines for bug reports
- Guidelines for curriculum improvements
- Contribution process
### INSTRUCTOR.md
- 30-minute setup guide
- Grading rubrics
- Common student errors
- Sample solutions (for grading calibration)
### TA_GUIDE.md
- Frequent student errors:
- Gradient shape mismatches
- Disconnected computational graphs
- Broadcasting failures
- Debugging strategies
- TA preparation guidance
## Files NOT Mentioned in Paper
These are NOT required by the paper (but may be useful):
- `TEAM_ONBOARDING.md` - Not explicitly mentioned (but Model 3 is described)
- `MAINTENANCE.md` - Mentioned but user doesn't want it
## Action Items
1. ✅ Remove MAINTENANCE.md (done)
2. ✅ Verify CONTRIBUTING.md matches paper description
3. ✅ Verify INSTRUCTOR.md contains all required content:
- 30-minute setup guide ✅
- Grading rubrics ✅
- Common student errors ✅
- Sample solutions ⚠️ Need to verify
4. ✅ Verify TA_GUIDE.md contains:
- Gradient shape mismatches ✅
- Disconnected computational graphs ✅
- Broadcasting failures ✅
- Debugging strategies ✅

348
binder/SETUP_PHASE_COMMUNITY_INTEGRATION.md
View File

@@ -1,348 +0,0 @@
# Community Integration in Setup Phase
## Revised Vision: Early Community Engagement
Make community participation part of the **initial setup experience**, not something that happens after completing everything. This creates an immediate "I'm part of something bigger" moment.
## Updated User Journey
### Initial Setup Flow
```
1. Clone & Setup
↓
2. tito system doctor (verify installation)
✅ All checks passed!
↓
3. 🎉 "Welcome to TinyTorch!"
↓
4. [Automatic] tito community join
→ Detects country
→ Validates setup
→ Adds to map
→ Shows celebration
↓
5. 🌍 "You're builder #1,234 on the global map!"
↓
6. View map → See community worldwide
```
## Integration Points
### Option 1: Automatic After Setup (Recommended)
**After `tito system doctor` passes:**
```
✅ All checks passed! Your TinyTorch environment is ready.
🎉 Welcome to the TinyTorch Community!
🌍 Join builders from around the world:
Run 'tito community join' to add your location to the map
(Completely optional - only shares country, not exact location)
💡 This is your "hello world" moment - you've successfully set up TinyTorch!
```
**After `tito community join`:**
```
✅ You've joined the TinyTorch Community!
📍 Your Location: United States
🌍 View the map: https://tinytorch.ai/community
🎖️ You're builder #1,234 on the global map!
📊 Community Stats:
• 1,234 builders worldwide
• 45 countries represented
• 5 new builders this week
💡 Continue building modules and run milestones to track your progress!
```
### Option 2: Integrated into Setup Script
**In `setup-environment.sh` or `activate.sh`:**
```bash
# After successful setup
echo ""
echo "🎉 Setup complete! Welcome to TinyTorch!"
echo ""
echo "🌍 Join the global community:"
echo " Run 'tito community join' to add your location to the map"
echo " (Optional - only shares country, completely anonymized)"
echo ""
```
### Option 3: Part of Quick Start Guide
**Update quickstart guide to include:**
```markdown
## Step 3: Join the Community (Optional)
After setup, join builders from around the world:
```bash
tito community join
```
This adds your location (country only) to the global TinyTorch community map.
See where other builders are located: https://tinytorch.ai/community
```
## What Gets Validated
**For community join (setup phase):**
- ✅ Setup verified (`tito system doctor` passed)
- ✅ Environment working
- ✅ Can import TinyTorch
**NOT required:**
- ❌ All milestones passed (can join anytime)
- ❌ All modules completed (can join anytime)
- ❌ Any specific progress (just setup)
**Why this works:**
- Lower barrier to entry
- Immediate community feeling
- Can update later with milestone progress
- More inclusive (everyone can join)
## Progressive Updates
**Users can update their community entry:**
```bash
# Initial join (after setup)
tito community join
# → Adds: Country, setup verified, timestamp
# Later: Update with milestone progress
tito community update
# → Updates: Milestones passed, system type, progress
# → Same anonymous ID, just more info
```
## Map Visualization
**The map shows:**
- **All builders**: Everyone who joined (not just completed)
- **Progress indicators**: Dots colored by milestone progress
- 🟢 All milestones passed
- 🟡 Some milestones passed
- 🔵 Setup complete (just joined)
- **Stats**: Total builders, countries, recent activity
**This creates:**
- Visual proof of global community
- Shows diversity of progress levels
- Encourages continued learning
- Makes everyone feel included
## Implementation Design
### Command: `tito community join`
**What it does:**
1. Validates setup (`tito system doctor` check)
2. Detects/asks for country
3. Generates anonymous ID
4. Creates submission JSON:
```json
{
"anonymous_id": "abc123...",
"timestamp": "2024-11-20T10:30:00Z",
"country": "United States",
"setup_verified": true,
"milestones_passed": 0, // Will update later
"system_type": "Apple Silicon"
}
```
5. Shows celebration message
6. Optionally uploads to map
### Command: `tito community update` (Optional)
**What it does:**
- Updates existing entry with:
- Milestones passed count
- Progress updates
- System type (if changed)
- Uses same anonymous ID
- Shows updated stats
## Setup Script Integration
### Update `setup-environment.sh`:
```bash
#!/bin/bash
# ... existing setup code ...
echo ""
echo "✅ TinyTorch setup complete!"
echo ""
echo "🌍 Join the global TinyTorch community:"
echo " Run 'tito community join' to add your location to the map"
echo " See builders from around the world: https://tinytorch.ai/community"
echo ""
```
### Or in `activate.sh`:
```bash
# After activation
if [ "$FIRST_ACTIVATION" = "true" ]; then
echo ""
echo "🎉 Welcome to TinyTorch!"
echo ""
echo "🌍 Join the community: 'tito community join'"
echo ""
fi
```
## Quick Start Guide Integration
**Add to quickstart guide:**
```markdown
## Step 3: Join the Community (30 seconds)
After setup, join builders from around the world:
```bash
tito community join
```
**What this does:**
- Adds your country to the global map
- Shows you're part of the TinyTorch community
- Completely optional and anonymized
**View the map**: https://tinytorch.ai/community
This is your "hello world" moment - you've successfully set up TinyTorch! 🎉
```
## Benefits of Setup-Phase Integration
### ✅ Immediate Engagement
- Community feeling from day one
- "I'm part of something bigger" moment
- Visual proof of global community
### ✅ Lower Barrier
- No need to complete milestones first
- Just setup verification required
- Everyone can participate
### ✅ Progressive Updates
- Join early (setup phase)
- Update later (milestone progress)
- Continuous engagement
### ✅ Inclusive
- All skill levels welcome
- All progress levels shown
- Not just "winners"
## Recommended Flow
### Phase 1: Setup Integration
1. **After `tito system doctor` passes:**
- Show celebration message
- Suggest `tito community join`
- Explain what it does (country only, optional)
2. **After `tito community join`:**
- Show map URL
- Display community stats
- Celebrate "you're builder #X"
3. **Update quickstart guide:**
- Add community join step
- Explain privacy model
- Link to map
### Phase 2: Map Page
1. **Create `site/community-map.md`:**
- Interactive world map
- Shows all builders (not just completed)
- Progress indicators
- Stats and recent activity
2. **Update site navigation:**
- Add "Community Map" to navigation
- Make it discoverable
### Phase 3: Progressive Updates
1. **Milestone integration:**
- After milestones pass, suggest update
- `tito community update` to add progress
- Map shows progress levels
## Privacy & Consent
**Setup-phase join:**
- Country only (not city)
- System type (optional)
- Setup verified status
- Anonymous ID (no personal info)
**Consent flow:**
```
tito community join
⚠️ This will add your location to the public community map.
📊 What will be shared:
• Country: United States (detected)
• System type: Apple Silicon
• Setup status: Verified ✅
• No personal information
🔒 Privacy: Only country-level location, completely anonymized
Continue? [y/N]: y
✅ You've joined the TinyTorch Community!
🌍 View map: https://tinytorch.ai/community
🎖️ You're builder #1,234 on the global map!
```
## Success Metrics
**Community Growth:**
- Number of builders who join (setup phase)
- Geographic diversity (countries)
- Growth rate (new builders/week)
- Map page views
**Engagement:**
- Join rate after setup
- Return visits to map
- Updates with milestone progress
- Social shares
## Final Recommendation
**Integrate into setup phase:**
1. ✅ **After `tito system doctor`**: Suggest community join
2. ✅ **Make it optional**: Clear consent, privacy-respecting
3. ✅ **Celebrate immediately**: "You're builder #X"
4. ✅ **Show the map**: Visual proof of community
5. ✅ **Allow updates**: Can add milestone progress later
**The goal**: Make students feel part of a global community from the moment they successfully set up TinyTorch, not after completing everything.
This creates an immediate "hello world" moment where they see: "Wow, there's a community of people building ML systems all over the world, and I'm one of them!" 🌍✨

167
binder/VERIFY.md
View File

@@ -1,167 +0,0 @@
# Binder & Colab Verification Guide
This guide helps you verify that Binder and Colab links are working correctly.
## Quick Verification Checklist
- [ ] Binder build completes successfully
- [ ] TinyTorch package imports correctly in Binder
- [ ] Colab can clone repository and install dependencies
- [ ] Launch buttons appear on notebook pages in documentation
- [ ] All three deployment environments work (JupyterHub, Colab, Local)
## Step-by-Step Verification
### 1. Test Binder Build
**Direct URL Test:**
```
https://mybinder.org/v2/gh/mlsysbook/TinyTorch/main
```
**What to check:**
- Build completes without errors (may take 2-5 minutes first time)
- JupyterLab launches successfully
- No import errors in terminal or notebook
**Test in Binder Notebook:**
```python
# Test 1: Import TinyTorch
import tinytorch
print(f"TinyTorch version: {tinytorch.__version__}")
# Test 2: Verify modules are accessible
import os
assert os.path.exists("modules"), "Modules directory not found"
assert os.path.exists("assignments"), "Assignments directory not found"
# Test 3: Test basic functionality
from tinytorch.core import Tensor
x = Tensor([1, 2, 3])
print(f"Tensor created: {x}")
```
### 2. Test Colab Integration
**For a specific notebook:**
```
https://colab.research.google.com/github/mlsysbook/TinyTorch/blob/main/assignments/source/02_tensor/02_tensor.ipynb
```
**What to check:**
- Notebook opens in Colab
- Can run cells without errors
- Dependencies install correctly
**Colab Setup Cell (add to notebooks if needed):**
```python
# Install TinyTorch
!pip install -e /content/TinyTorch
# Verify installation
import tinytorch
print("TinyTorch installed successfully!")
```
### 3. Verify Launch Buttons in Documentation
**Check that launch buttons appear:**
1. Build the site: `cd site && jupyter-book build .`
2. Open `_build/html/index.html` in browser
3. Navigate to any page with notebooks
4. Look for "Launch" buttons in the top-right corner
**Expected buttons:**
- 🚀 Launch Binder
- 🔵 Open in Colab
- 📥 Download notebook
### 4. Test All Three Deployment Environments
As documented in `paper/paper.tex`, TinyTorch supports:
#### A. JupyterHub (Institutional)
- Requires: 8-core/32GB server
- Supports: ~50 concurrent students
- Setup: Install via `pip install tinytorch` or mount repository
#### B. Google Colab (Zero Installation)
- Best for: MOOCs and self-paced learning
- Setup: Automatic via launch buttons
- Verify: Test with sample notebooks
#### C. Local Installation
- Best for: Self-paced learning and development
- Setup: `pip install tinytorch`
- Verify: Run `python -c "import tinytorch; print(tinytorch.__version__)"`
## Common Issues & Solutions
### Issue: Binder build times out
**Solution:**
- Check `binder/requirements.txt` for unnecessary heavy dependencies
- Ensure `postBuild` script is fast (< 2 minutes)
- Consider using `environment.yml` instead if you need conda packages
### Issue: "Module not found" errors in Binder
**Solution:**
- Verify `postBuild` script runs `pip install -e .`
- Check that `pyproject.toml` is in repository root
- Ensure all dependencies are in `binder/requirements.txt`
### Issue: Colab can't access repository
**Solution:**
- Ensure repository is public (Colab can't access private repos)
- Check that notebook path is correct in URL
- Verify GitHub repository URL in `site/_config.yml`
### Issue: Launch buttons don't appear
**Solution:**
- Verify `launch_buttons` configuration in `site/_config.yml`
- Ensure repository URL and branch are correct
- Rebuild the site: `jupyter-book build . --all`
## Automated Testing
You can add a GitHub Actions workflow to test Binder builds:
```yaml
# .github/workflows/test-binder.yml
name: Test Binder Build
on:
schedule:
- cron: '0 0 * * 0' # Weekly
workflow_dispatch:
jobs:
test-binder:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Test Binder Build
uses: jupyterhub/repo2docker-action@master
with:
image-name: tinytorch-binder-test
```
## Monitoring
**Binder Status:**
- Check build status: https://mybinder.org/v2/gh/mlsysbook/TinyTorch/main
- View build logs: Add `?urlpath=lab/tree/logs%2Fbuild.log` to URL
**Colab Status:**
- Test with sample notebooks from `assignments/` directory
- Monitor for import errors or dependency issues
## References
- [Binder Documentation](https://mybinder.readthedocs.io/)
- [Jupyter Book Launch Buttons](https://jupyterbook.org/en/stable/interactive/launchbuttons.html)
- [Google Colab GitHub Integration](https://colab.research.google.com/github/)