diff --git a/COURSE_GUIDE.md b/COURSE_GUIDE.md new file mode 100644 index 00000000..c963d237 --- /dev/null +++ b/COURSE_GUIDE.md @@ -0,0 +1,255 @@ +# πŸ”₯ TinyTorch Course Guide + +**Building Machine Learning Systems from Scratch** + +This guide helps you navigate through the complete TinyTorch course. Each project builds progressively toward a complete ML system. + +## 🎯 Current Status + +Track your progress through the course: + +- [ ] **Project 0: Setup** - Environment & CLI setup +- [ ] **Project 1: Tensor** - Core tensor operations +- [ ] **Project 2: MLP** - Multi-layer perceptron +- [ ] **Project 3: CNN** - Convolutional networks +- [ ] **Project 4: Autograd** - Automatic differentiation +- [ ] **Project 5: Data** - Data loading pipeline +- [ ] **Project 6: Training** - Training loop & optimization +- [ ] **Project 7: Config** - Configuration system +- [ ] **Project 8: Profiling** - Performance profiling +- [ ] **Project 9: Compression** - Model compression +- [ ] **Project 10: Kernels** - Custom compute kernels +- [ ] **Project 11: Benchmarking** - Performance benchmarking +- [ ] **Project 12: MLOps** - Production monitoring + +## πŸš€ Getting Started + +### First Time Setup +1. **Clone the repository** +2. **Go to**: [`projects/setup/README.md`](projects/setup/README.md) +3. **Follow all setup instructions** +4. **Verify with**: `python3 projects/setup/check_setup.py` + +### Daily Workflow +```bash +cd TinyTorch +source tinytorch-env/bin/activate # Always activate first! +python3 bin/tito.py info # Check system status +``` + +## πŸ“‹ Project Details + +### πŸ”§ Project 0: Setup +**Goal**: Get your development environment ready +**Time**: 30 minutes +**Instructions**: [`projects/setup/README.md`](projects/setup/README.md) + +**Key Tasks**: +- [ ] Create virtual environment +- [ ] Install dependencies +- [ ] Implement `hello_tinytorch()` function +- [ ] Pass all setup tests +- [ ] Learn the `tito` CLI + +**Verification**: +```bash +python3 projects/setup/check_setup.py # Should show all βœ… +``` + +--- + +### πŸ”’ Project 1: Tensor +**Goal**: Build the core tensor system +**Prerequisites**: Project 0 complete +**Instructions**: [`projects/tensor/README.md`](projects/tensor/README.md) + +**Key Tasks**: +- [ ] Implement `Tensor` class +- [ ] Basic operations (add, mul, reshape) +- [ ] Memory management +- [ ] Shape validation +- [ ] Broadcasting support + +**Verification**: +```bash +python3 -m pytest projects/tensor/test_tensor.py -v +``` + +--- + +### 🧠 Project 2: MLP +**Goal**: Build multi-layer perceptron +**Prerequisites**: Project 1 complete +**Instructions**: [`projects/mlp/README.md`](projects/mlp/README.md) + +**Key Tasks**: +- [ ] Implement `Linear` layer +- [ ] Activation functions (ReLU, Sigmoid) +- [ ] Forward pass +- [ ] Basic backward pass +- [ ] Train on MNIST + +**Target**: >95% accuracy on MNIST + +--- + +### πŸ–ΌοΈ Project 3: CNN +**Goal**: Build convolutional neural networks +**Prerequisites**: Project 2 complete +**Instructions**: [`projects/cnn/README.md`](projects/cnn/README.md) + +**Key Tasks**: +- [ ] Implement `Conv2d` layer +- [ ] `MaxPool2d` layer +- [ ] Padding and stride support +- [ ] Train CNN on CIFAR-10 + +**Target**: >80% accuracy on CIFAR-10 + +--- + +### ⚑ Project 4: Autograd +**Goal**: Automatic differentiation engine +**Prerequisites**: Project 3 complete +**Instructions**: [`projects/autograd/README.md`](projects/autograd/README.md) + +**Key Tasks**: +- [ ] Computational graph construction +- [ ] Backward pass automation +- [ ] Gradient checking +- [ ] Memory efficient gradients + +**Verification**: All gradient checks pass + +--- + +### πŸ“Š Project 5: Data +**Goal**: Efficient data loading +**Prerequisites**: Project 4 complete +**Instructions**: [`projects/data/README.md`](projects/data/README.md) + +**Key Tasks**: +- [ ] Custom `DataLoader` implementation +- [ ] Batch processing +- [ ] Data transformations +- [ ] Multi-threaded loading + +--- + +### 🎯 Project 6: Training +**Goal**: Complete training system +**Prerequisites**: Project 5 complete +**Instructions**: [`projects/training/README.md`](projects/training/README.md) + +**Key Tasks**: +- [ ] Training loop implementation +- [ ] SGD optimizer +- [ ] Adam optimizer +- [ ] Learning rate scheduling +- [ ] Metric tracking + +--- + +### βš™οΈ Project 7: Config +**Goal**: Configuration management +**Prerequisites**: Project 6 complete +**Instructions**: [`projects/config/README.md`](projects/config/README.md) + +**Key Tasks**: +- [ ] YAML configuration system +- [ ] Experiment logging +- [ ] Reproducible training +- [ ] Hyperparameter management + +--- + +### πŸ“Š Project 8: Profiling +**Goal**: Performance measurement +**Prerequisites**: Project 7 complete +**Instructions**: [`projects/profiling/README.md`](projects/profiling/README.md) + +**Key Tasks**: +- [ ] Memory profiler +- [ ] Compute profiler +- [ ] Bottleneck identification +- [ ] Performance visualizations + +--- + +### πŸ—œοΈ Project 9: Compression +**Goal**: Model compression techniques +**Prerequisites**: Project 8 complete +**Instructions**: [`projects/compression/README.md`](projects/compression/README.md) + +**Key Tasks**: +- [ ] Pruning implementation +- [ ] Quantization +- [ ] Knowledge distillation +- [ ] Compression benchmarks + +--- + +### πŸ”₯ Project 10: Kernels +**Goal**: Custom compute kernels +**Prerequisites**: Project 9 complete +**Instructions**: [`projects/kernels/README.md`](projects/kernels/README.md) + +**Key Tasks**: +- [ ] Optimized matrix multiplication +- [ ] Vectorized operations +- [ ] CPU optimization +- [ ] Performance comparisons + +--- + +### πŸ“ˆ Project 11: Benchmarking +**Goal**: Performance evaluation +**Prerequisites**: Project 10 complete +**Instructions**: [`projects/benchmarking/README.md`](projects/benchmarking/README.md) + +**Key Tasks**: +- [ ] Comprehensive benchmarking suite +- [ ] Performance regression testing +- [ ] Comparison with other frameworks +- [ ] Performance reporting + +--- + +### πŸš€ Project 12: MLOps +**Goal**: Production monitoring +**Prerequisites**: Project 11 complete +**Instructions**: [`projects/mlops/README.md`](projects/mlops/README.md) + +**Key Tasks**: +- [ ] Data drift detection +- [ ] Model performance monitoring +- [ ] Auto-retraining system +- [ ] Production deployment + +## πŸ† Final Achievement + +By the end of the course, you'll have: +- βœ… Complete ML system built from scratch +- βœ… CNN trained on CIFAR-10 achieving >85% accuracy +- βœ… Production-ready MLOps pipeline +- βœ… Deep understanding of ML system internals + +## πŸ†˜ Getting Help + +**Stuck on a project?** +1. Read the project's README thoroughly +2. Run the verification commands +3. Check the troubleshooting section +4. Ask in office hours +5. Review previous projects for patterns + +**Common Commands**: +```bash +python3 bin/tito.py info # System status +python3 bin/tito.py test --project setup # Test specific project +python3 projects/setup/check_setup.py # Comprehensive verification +``` + +--- + +**Ready to start?** Go to [`projects/setup/README.md`](projects/setup/README.md) πŸš€ \ No newline at end of file diff --git a/README.md b/README.md index a752e3cb..d57c650f 100644 --- a/README.md +++ b/README.md @@ -78,25 +78,25 @@ By the end of this project, you'll have implemented a fully functional ML system TinyTorch aligns with **Chapters 1–13** of the *Machine Learning Systems* textbook. Each project builds progressively toward a complete ML infrastructure. -### Course Progression +### πŸ“š Course Details & Learning Objectives -| Order | Project | Chapter | Component | Learning Focus | Deliverable | -|-------|---------|---------|-----------|----------------|-------------| -| 0 | `setup` | - | Setup & Onboarding | Environment setup, tool familiarity | Working dev environment + basic commands | -| 1 | `tensor` | 1-2 | Core Tensor System | Tensor operations, memory management | Working Tensor class with basic ops | -| 2 | `mlp` | 3 | Multi-Layer Perceptron | Forward/backward pass, gradient computation | Train simple MLP on MNIST | -| 3 | `cnn` | 4 | Convolutional Networks | Convolution, pooling operations | Conv2D and MaxPool implementations | -| 4 | `autograd` | 5 | Automatic Differentiation | Computational graphs, autodiff | Complete autograd engine | -| 5 | `data` | 6 | Data Pipeline | Efficient data loading, batching | Custom DataLoader with transformations | -| 6 | `training` | 7-8 | Training Loop | Optimization algorithms, metrics | SGD, Adam optimizers + training harness | -| 7 | `config` | 9 | Configuration System | Experiment management, logging | YAML configs + structured logging | -| 8 | `profiling` | 10 | Performance Tools | Performance measurement, debugging | Memory/compute profiler with visualizations | -| 9 | `compression` | 11 | Model Compression | Pruning, quantization techniques | Compress model while maintaining accuracy | -| 10 | `kernels` | 12 | Custom Kernels | Low-level optimization, vectorization | Optimized matrix multiplication kernels | -| 11 | `benchmarking` | 13 | Performance Evaluation | Performance testing, comparison | Comprehensive benchmarking suite | -| 12 | `mlops` | 14 | MLOps & Monitoring | Data drift detection, continuous updates | Production monitoring and auto-retraining system | +Each project corresponds to specific chapters in the *Machine Learning Systems* textbook: -> **Note**: Project directories use descriptive names (e.g., `projects/tensor/`, `projects/autograd/`) for clarity. The order above represents the recommended learning sequence and can be adjusted as the curriculum evolves. +| Project | Chapters | Core Learning | Key Deliverable | +|---------|----------|---------------|-----------------| +| Setup | - | Environment setup, tool familiarity | Working dev environment + CLI | +| Tensor | 1-2 | Tensor operations, memory management | Working Tensor class with basic ops | +| MLP | 3 | Forward/backward pass, gradient computation | Train simple MLP on MNIST | +| CNN | 4 | Convolution, pooling operations | Conv2D and MaxPool implementations | +| Autograd | 5 | Computational graphs, autodiff | Complete autograd engine | +| Data | 6 | Efficient data loading, batching | Custom DataLoader with transformations | +| Training | 7-8 | Optimization algorithms, metrics | SGD, Adam optimizers + training harness | +| Config | 9 | Experiment management, logging | YAML configs + structured logging | +| Profiling | 10 | Performance measurement, debugging | Memory/compute profiler with visualizations | +| Compression | 11 | Pruning, quantization techniques | Compress model while maintaining accuracy | +| Kernels | 12 | Low-level optimization, vectorization | Optimized matrix multiplication kernels | +| Benchmarking | 13 | Performance testing, comparison | Comprehensive benchmarking suite | +| MLOps | 14 | Data drift detection, continuous updates | Production monitoring and auto-retraining system | ### Milestone Targets - **Week 1**: Environment setup (`setup`) and basic command familiarity @@ -183,7 +183,37 @@ TinyTorch/ --- -## πŸš€ Getting Started +## 🎯 Course Navigation & Getting Started + +**New to TinyTorch?** Start here: [`projects/setup/README.md`](projects/setup/README.md) + +### πŸ“‹ Project Sequence +Each project builds on the previous ones. Click the links to jump to specific instructions: + +| Order | Project | Status | Description | Instructions | +|-------|---------|--------|-------------|--------------| +| 0 | **Setup** | πŸš€ **START HERE** | Environment & CLI setup | [`projects/setup/README.md`](projects/setup/README.md) | +| 1 | **Tensor** | ⏳ Coming Next | Core tensor operations | [`projects/tensor/README.md`](projects/tensor/README.md) | +| 2 | **MLP** | ⏳ Future | Multi-layer perceptron | [`projects/mlp/README.md`](projects/mlp/README.md) | +| 3 | **CNN** | ⏳ Future | Convolutional networks | [`projects/cnn/README.md`](projects/cnn/README.md) | +| 4 | **Autograd** | ⏳ Future | Automatic differentiation | [`projects/autograd/README.md`](projects/autograd/README.md) | +| 5 | **Data** | ⏳ Future | Data loading pipeline | [`projects/data/README.md`](projects/data/README.md) | +| 6 | **Training** | ⏳ Future | Training loop & optimization | [`projects/training/README.md`](projects/training/README.md) | +| 7 | **Config** | ⏳ Future | Configuration system | [`projects/config/README.md`](projects/config/README.md) | +| 8 | **Profiling** | ⏳ Future | Performance profiling | [`projects/profiling/README.md`](projects/profiling/README.md) | +| 9 | **Compression** | ⏳ Future | Model compression | [`projects/compression/README.md`](projects/compression/README.md) | +| 10 | **Kernels** | ⏳ Future | Custom compute kernels | [`projects/kernels/README.md`](projects/kernels/README.md) | +| 11 | **Benchmarking** | ⏳ Future | Performance benchmarking | [`projects/benchmarking/README.md`](projects/benchmarking/README.md) | +| 12 | **MLOps** | ⏳ Future | Production monitoring | [`projects/mlops/README.md`](projects/mlops/README.md) | + +### πŸš€ Quick Start Guide +**First time?** Follow this exact sequence: + +1. **πŸ“– Read the overview** (you're here!) +2. **🎯 Detailed guidance**: [`COURSE_GUIDE.md`](COURSE_GUIDE.md) (comprehensive walkthrough) +3. **πŸ”§ Environment setup**: [`projects/setup/README.md`](projects/setup/README.md) +4. **βœ… Verify setup**: Run `python3 projects/setup/check_setup.py` +5. **🎯 Start Project 1**: [`projects/tensor/README.md`](projects/tensor/README.md) ### Prerequisites - **Python 3.8+** (type hints and modern features required) @@ -191,18 +221,24 @@ TinyTorch/ - **Optional**: Numba (JIT compilation for performance) - **Development**: pytest, black, mypy (for testing and code quality) -### Quick Start +### Environment Setup ```bash -# Clone and setup +# Clone and setup environment git clone cd TinyTorch -pip install -r requirements.txt -# Run your first training -python bin/tito.py train --config tinytorch/configs/default.yaml +# Automated setup (creates virtual environment + installs dependencies) +python3 projects/setup/create_env.py + +# Activate environment (do this every time you work) +source tinytorch-env/bin/activate # macOS/Linux +# OR: tinytorch-env\Scripts\activate # Windows + +# Verify setup +python3 projects/setup/check_setup.py # Check system status -python bin/tito.py info --show-architecture +python3 bin/tito.py info --show-architecture ``` ### For Instructors @@ -211,27 +247,32 @@ python bin/tito.py info --show-architecture pip install -r requirements.txt # Generate course materials -python bin/tito.py generate-projects -python bin/tito.py setup-autograders +python3 bin/tito.py generate-projects +python3 bin/tito.py setup-autograders # View course progress -python bin/tito.py course-status +python3 bin/tito.py course-status ``` ### For Students ```bash +# Start with environment setup (IMPORTANT!) +python3 projects/setup/create_env.py +source tinytorch-env/bin/activate # Always activate first! + # Start with Project 0: Setup cd projects/setup/ -python bin/tito.py project init +cat README.md # Read instructions +python3 -m pytest test_setup.py -v # Run tests # Then move through the sequence -cd projects/tensor/ # Project 1: Core tensors -cd projects/mlp/ # Project 2: Multi-layer perceptron -cd projects/autograd/ # Project 4: Automatic differentiation +cd ../tensor/ # Project 1: Core tensors +cd ../mlp/ # Project 2: Multi-layer perceptron +cd ../autograd/ # Project 3: Automatic differentiation -# Run tests and submit -python bin/tito.py test --project tensor -python bin/tito.py submit --project tensor +# Always run tests before submitting +python3 -m pytest projects/tensor/test_tensor.py -v +python3 bin/tito.py submit --project tensor ``` --- diff --git a/bin/tito.py b/bin/tito.py old mode 100644 new mode 100755 index 3ea0dd84..9e9978de --- a/bin/tito.py +++ b/bin/tito.py @@ -1,303 +1,179 @@ #!/usr/bin/env python3 """ -TinyTorch CLI - Main entry point for training and evaluation. +TinyTorch CLI (tito) -This command-line interface provides access to all TinyTorch functionality: -- Training models on various datasets -- Evaluating trained models -- Profiling and benchmarking -- System information and diagnostics -- Configuration management +The main command-line interface for the TinyTorch ML system. +Students use this CLI for testing, training, and project management. + +Usage: python bin/tito.py [command] [options] """ -import argparse import sys import os +import argparse from pathlib import Path -from typing import Optional -# Add parent directory to path to find tinytorch package +# Add the project root to Python path sys.path.insert(0, str(Path(__file__).parent.parent)) -from tinytorch.core import __version__ - - -def create_parser() -> argparse.ArgumentParser: - """ - Create the main argument parser. - - Returns: - Configured argument parser - """ - parser = argparse.ArgumentParser( - prog="tinytorch", - description="TinyπŸ”₯Torch ML System - Build neural networks from scratch", - formatter_class=argparse.RawDescriptionHelpFormatter, - epilog=""" -Examples: - python bin/tito.py train --config tinytorch/configs/default.yaml - python bin/tito.py eval --model checkpoints/best_model.pth --dataset mnist - python bin/tito.py benchmark --ops matmul,conv2d - python bin/tito.py info --show-architecture - """ - ) - - parser.add_argument( - "--version", - action="version", - version=f"TinyπŸ”₯Torch {__version__}" - ) - - # Subcommands - subparsers = parser.add_subparsers(dest="command", help="Available commands") - - # Train command - train_parser = subparsers.add_parser("train", help="Train a model") - train_parser.add_argument( - "--config", - type=str, - required=True, - help="Path to training configuration file" - ) - train_parser.add_argument( - "--resume", - type=str, - help="Path to checkpoint to resume from" - ) - train_parser.add_argument( - "--output-dir", - type=str, - default="logs/runs", - help="Directory for output logs and checkpoints" - ) - - # Eval command - eval_parser = subparsers.add_parser("eval", help="Evaluate a model") - eval_parser.add_argument( - "--model", - type=str, - required=True, - help="Path to trained model checkpoint" - ) - eval_parser.add_argument( - "--dataset", - type=str, - required=True, - choices=["mnist", "cifar10"], - help="Dataset to evaluate on" - ) - eval_parser.add_argument( - "--batch-size", - type=int, - default=64, - help="Batch size for evaluation" - ) - - # Benchmark command - benchmark_parser = subparsers.add_parser("benchmark", help="Benchmark operations") - benchmark_parser.add_argument( - "--ops", - type=str, - help="Comma-separated list of operations to benchmark" - ) - benchmark_parser.add_argument( - "--sizes", - type=str, - default="32,64,128,256,512", - help="Comma-separated list of sizes to test" - ) - benchmark_parser.add_argument( - "--iterations", - type=int, - default=100, - help="Number of iterations per benchmark" - ) - - # Info command - info_parser = subparsers.add_parser("info", help="System information") - info_parser.add_argument( - "--show-architecture", - action="store_true", - help="Show system architecture diagram" - ) - info_parser.add_argument( - "--show-config", - action="store_true", - help="Show current configuration" - ) - - return parser - - -def train_command(args) -> int: - """ - Execute training command. - - Args: - args: Parsed command line arguments - - Returns: - Exit code (0 for success) - """ - print(f"Training with config: {args.config}") - print(f"Output directory: {args.output_dir}") - - if args.resume: - print(f"Resuming from checkpoint: {args.resume}") - - # TODO: Implement training in Chapter 8 - print("ERROR: Training not yet implemented (will be added in Chapter 8)") - return 1 - - -def eval_command(args) -> int: - """ - Execute evaluation command. - - Args: - args: Parsed command line arguments - - Returns: - Exit code (0 for success) - """ - print(f"Evaluating model: {args.model}") - print(f"Dataset: {args.dataset}") - print(f"Batch size: {args.batch_size}") - - # TODO: Implement evaluation in Chapter 8 - print("ERROR: Evaluation not yet implemented (will be added in Chapter 8)") - return 1 - - -def benchmark_command(args) -> int: - """ - Execute benchmark command. - - Args: - args: Parsed command line arguments - - Returns: - Exit code (0 for success) - """ - if args.ops: - ops = args.ops.split(",") - print(f"Benchmarking operations: {ops}") - else: - print("Benchmarking all available operations") - - sizes = [int(s) for s in args.sizes.split(",")] - print(f"Testing sizes: {sizes}") - print(f"Iterations per test: {args.iterations}") - - # TODO: Implement benchmarking in Chapter 12 - print("ERROR: Benchmarking not yet implemented (will be added in Chapter 12)") - return 1 - - -def info_command(args) -> int: - """ - Execute info command. - - Args: - args: Parsed command line arguments - - Returns: - Exit code (0 for success) - """ - print(f"TinyπŸ”₯Torch ML System v{__version__}") +def print_banner(): + """Print the TinyTorch banner.""" + print("πŸ”₯ TinyπŸ”₯Torch: Build ML Systems from Scratch πŸ”₯") print("=" * 50) + +def cmd_version(args): + """Show TinyTorch version.""" + print("TinyπŸ”₯Torch v0.1.0") + print("Machine Learning Systems Course") + +def cmd_info(args): + """Show system information and status.""" + print_banner() + print() + + # Python environment info + print("πŸ“‹ System Information") + print("-" * 30) + print(f"Python: {sys.version.split()[0]}") + print(f"Platform: {sys.platform}") + print(f"Working Directory: {os.getcwd()}") + + # Virtual environment check + in_venv = (hasattr(sys, 'real_prefix') or + (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix)) + venv_status = "βœ… Active" if in_venv else "❌ Not Active" + print(f"Virtual Environment: {venv_status}") + + print() + + # Course navigation + print("πŸ“‹ Course Navigation") + print("-" * 30) + print("πŸ“– Course Overview: README.md") + print("🎯 Detailed Guide: COURSE_GUIDE.md") + print("πŸš€ Start Here: projects/setup/README.md") + + print() + + # Implementation status + print("πŸš€ Implementation Status") + print("-" * 30) + + # Check if hello function exists + try: + from tinytorch.core.utils import hello_tinytorch + hello_status = "βœ… Implemented" + if args.hello: + print(f"Hello Message: {hello_tinytorch()}") + except ImportError: + hello_status = "❌ Not Implemented" + + print(f"hello_tinytorch(): {hello_status}") + + # TODO: Add checks for other components as they're implemented + print("tensor operations: ⏳ Coming in Project 1") + print("autograd engine: ⏳ Coming in Project 4") + print("neural networks: ⏳ Coming in Project 2") + print("training system: ⏳ Coming in Project 6") if args.show_architecture: - print("\nSystem Architecture:") + print() + print("πŸ—οΈ System Architecture") + print("-" * 30) print(""" - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ TinyπŸ”₯Torch System β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ CLI Interface (bin/tito.py) β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ Training Orchestration (trainer.py) β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ Model Definition β”‚ Data Pipeline β”‚ Optimization β”‚ - β”‚ (modules.py) β”‚ (dataloader.py) β”‚ (optimizer.py) β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ Automatic Differentiation Engine (autograd) β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ Tensor Operations & Storage (tensor.py) β”‚ - β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ - β”‚ Profiling & MLOps (profiler.py, mlops.py) β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TinyTorch System β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ CLI Interface (bin/tito.py) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Training Orchestration (trainer.py) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Model Definition β”‚ Data Pipeline β”‚ Optimization β”‚ +β”‚ (modules.py) β”‚ (dataloader.py) β”‚ (optimizer.py) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Automatic Differentiation Engine (autograd) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Tensor Operations & Storage (tensor.py) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Profiling & MLOps (profiler.py, mlops.py) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ """) - - if args.show_config: - print("\nCurrent Configuration:") - print(f" Python: {sys.version}") - print(f" Working Directory: {os.getcwd()}") - print(f" TinyTorch Path: {Path(__file__).parent}") - - # Check for optional dependencies - try: - import numpy as np - print(f" NumPy: {np.__version__}") - except ImportError: - print(" NumPy: Not installed") - - try: - import numba - print(f" Numba: {numba.__version__}") - except ImportError: - print(" Numba: Not installed (optional)") - - # Show implementation status - print("\nImplementation Status:") - projects = [ - ("setup", "Environment setup & onboarding", "βœ… Environment ready"), - ("tensor", "Core tensor implementation", "βœ… Basic structure"), - ("mlp", "Multi-layer perceptron", "🚧 Not implemented"), - ("cnn", "Convolutional neural networks", "🚧 Not implemented"), - ("config", "Configuration system", "🚧 Not implemented"), - ("data", "Data pipeline & loading", "🚧 Not implemented"), - ("autograd", "Automatic differentiation", "🚧 Not implemented"), - ("training", "Training loop & optimization", "🚧 Not implemented"), - ("profiling", "Performance profiling tools", "🚧 Not implemented"), - ("compression", "Model compression techniques", "🚧 Not implemented"), - ("kernels", "Custom compute kernels", "🚧 Not implemented"), - ("benchmarking", "Performance benchmarking", "🚧 Not implemented"), - ("mlops", "MLOps & production monitoring", "🚧 Not implemented"), - ] - - for project, component, status in projects: - print(f" {project:12} {component:20} {status}") - - return 0 - -def main() -> int: - """ - Main entry point. +def cmd_test(args): + """Run tests for a specific project.""" + print(f"πŸ§ͺ Running tests for project: {args.project}") + + if args.project == "setup": + # Run setup tests + import subprocess + test_file = "projects/setup/test_setup.py" + result = subprocess.run([sys.executable, "-m", "pytest", test_file, "-v"], + capture_output=False) + return result.returncode + else: + print(f"Tests for project '{args.project}' not yet implemented.") + return 1 + +def cmd_submit(args): + """Submit project for grading.""" + print(f"πŸ“€ Submitting project: {args.project}") + print("🚧 Submission system not yet implemented.") + print("For now, make sure all tests pass with:") + print(f" python -m pytest projects/{args.project}/test_*.py -v") + +def cmd_status(args): + """Check project status.""" + print(f"πŸ“Š Status for project: {args.project}") + print("🚧 Status system not yet implemented.") + +def main(): + """Main CLI entry point.""" + parser = argparse.ArgumentParser( + prog="tito", + description="TinyTorch CLI - Build ML systems from scratch" + ) + parser.add_argument("--version", action="store_true", help="Show version") + + subparsers = parser.add_subparsers(dest="command", help="Available commands") + + # Info command + info_parser = subparsers.add_parser("info", help="Show system information") + info_parser.add_argument("--hello", action="store_true", help="Show hello message") + info_parser.add_argument("--show-architecture", action="store_true", help="Show system architecture") + + # Test command + test_parser = subparsers.add_parser("test", help="Run project tests") + test_parser.add_argument("--project", required=True, help="Project to test") + + # Submit command + submit_parser = subparsers.add_parser("submit", help="Submit project") + submit_parser.add_argument("--project", required=True, help="Project to submit") + + # Status command + status_parser = subparsers.add_parser("status", help="Check project status") + status_parser.add_argument("--project", required=True, help="Project to check") - Returns: - Exit code (0 for success) - """ - parser = create_parser() args = parser.parse_args() - if not args.command: + # Handle version flag + if args.version: + cmd_version(args) + return 0 + + # Handle commands + if args.command == "info": + cmd_info(args) + elif args.command == "test": + return cmd_test(args) + elif args.command == "submit": + cmd_submit(args) + elif args.command == "status": + cmd_status(args) + else: parser.print_help() return 1 - # Dispatch to appropriate command handler - if args.command == "train": - return train_command(args) - elif args.command == "eval": - return eval_command(args) - elif args.command == "benchmark": - return benchmark_command(args) - elif args.command == "info": - return info_command(args) - else: - print(f"Unknown command: {args.command}") - return 1 - + return 0 if __name__ == "__main__": sys.exit(main()) \ No newline at end of file diff --git a/projects/setup/QUICKSTART.md b/projects/setup/QUICKSTART.md new file mode 100644 index 00000000..bb72edac --- /dev/null +++ b/projects/setup/QUICKSTART.md @@ -0,0 +1,100 @@ +# TinyTorch Quick Start Guide + +Get your TinyTorch environment set up in 5 minutes! + +## πŸš€ Option 1: Automated Setup (Recommended) + +**Step 1**: Clone and navigate +```bash +git clone +cd TinyTorch +``` + +**Step 2**: Run the automated setup +```bash +python3 projects/setup/create_env.py +``` + +**Step 3**: Activate environment and verify +```bash +source tinytorch-env/bin/activate # macOS/Linux +# OR: tinytorch-env\Scripts\activate # Windows + +python3 projects/setup/check_setup.py +``` + +**Done!** If you see all βœ… checkmarks, you're ready to code. + +--- + +## πŸ”§ Option 2: Manual Setup + +**Step 1**: Create virtual environment +```bash +python3 -m venv tinytorch-env +source tinytorch-env/bin/activate +``` + +**Step 2**: Install dependencies +```bash +pip install --upgrade pip +pip install -r requirements.txt +``` + +**Step 3**: Verify setup +```bash +python3 projects/setup/check_setup.py +``` + +--- + +## 🎯 Every Day Workflow + +**Start working** (run this every time): +```bash +cd TinyTorch +source tinytorch-env/bin/activate # Always activate first! +``` + +**Check status**: +```bash +python3 bin/tito.py info +``` + +**Run tests**: +```bash +python3 -m pytest projects/setup/test_setup.py -v +``` + +--- + +## ❗ Common Issues + +**"ModuleNotFoundError"**: You forgot to activate your virtual environment +```bash +source tinytorch-env/bin/activate +``` + +**"Command not found"**: Make sure you're in the TinyTorch directory +```bash +cd TinyTorch +ls # Should see bin/, projects/, requirements.txt +``` + +**Dependencies missing**: Reinstall in the virtual environment +```bash +source tinytorch-env/bin/activate +pip install -r requirements.txt +``` + +--- + +## πŸ“ What's in Your Environment + +After setup, you'll have: +- βœ… Python 3.8+ with exact dependency versions +- βœ… pytest for running tests +- βœ… All TinyTorch course materials +- βœ… Isolated environment (no conflicts with other projects) + +**Next**: Read `projects/setup/README.md` for detailed instructions! \ No newline at end of file diff --git a/projects/setup/README.md b/projects/setup/README.md new file mode 100644 index 00000000..85ce8319 --- /dev/null +++ b/projects/setup/README.md @@ -0,0 +1,175 @@ +# Project Setup: Environment & Onboarding + +Welcome to TinyπŸ”₯Torch! This setup project gets your development environment ready and introduces you to the workflow you'll use throughout the course. + +## 🎯 Learning Objectives + +By the end of this project, you will: +- βœ… Have a fully working development environment +- βœ… Understand the `tito` CLI workflow +- βœ… Know how to check system status and run tests +- βœ… Have implemented your first TinyTorch component +- βœ… Be ready to build the entire ML system + +## πŸ“‹ Setup Checklist + +### Step 1: Environment Setup + +**Check Python Version** +```bash +python3 --version # Should be 3.8 or higher +``` + +**Create Virtual Environment** (REQUIRED) +```bash +# Create isolated environment for TinyTorch +python3 -m venv tinytorch-env + +# Activate it (you'll do this every time) +source tinytorch-env/bin/activate # macOS/Linux +# OR on Windows: tinytorch-env\Scripts\activate + +# Verify you're in the virtual environment +which python # Should show path with tinytorch-env +``` + +**Install Dependencies** +```bash +# Make sure you're in the activated virtual environment! +pip install --upgrade pip +pip install -r requirements.txt +``` + +**Verify Installation** +```bash +python3 -c "import numpy, matplotlib, yaml; print('βœ… Core dependencies installed')" +``` + +> **⚠️ Important**: Always activate your virtual environment before working: +> ```bash +> source tinytorch-env/bin/activate # Run this every time you start working +> ``` + +### Step 2: System Verification + +**Test the CLI** +```bash +python3 bin/tito.py --version +python3 bin/tito.py info +``` +You should see the TinyπŸ”₯Torch banner and system status. + +**Check Project Structure** +```bash +python3 bin/tito.py info --show-architecture +``` +This shows the system architecture you'll be building. + +### Step 3: Development Workflow + +**Learn Status Commands** +```bash +# Check implementation status +python3 bin/tito.py info + +# Test specific project (you'll use this constantly) +python3 bin/tito.py test --project setup + +# Get help on any command +python3 bin/tito.py train --help +``` + +## πŸš€ Hello World Implementation + +Now let's implement your first TinyTorch component! You'll add a simple greeting function to the system. + +**Your Task**: Implement a `hello_tinytorch()` function in `tinytorch/core/utils.py` + +**Step 1: Open the utils file** +```bash +# Look at the current file +cat tinytorch/core/utils.py +``` + +**Step 2: Implement the function** + +Add this function to `tinytorch/core/utils.py`: + +```python +def hello_tinytorch() -> str: + """ + Return a greeting message for new TinyTorch users. + + Returns: + A welcoming message string + """ + return "πŸ”₯ Welcome to TinyTorch! Ready to build ML systems from scratch! πŸ”₯" +``` + +**Step 3: Test your implementation** +```bash +# Run the pytest test suite +python3 -m pytest projects/setup/test_setup.py -v + +# Or run the CLI test command +python3 bin/tito.py test --project setup + +# Run comprehensive setup check +python3 projects/setup/check_setup.py +``` + +## πŸ§ͺ Verification & Next Steps + +**Run the setup checker** +```bash +python3 projects/setup/check_setup.py +``` + +This will verify: +- βœ… Environment is correctly configured +- βœ… All dependencies are installed +- βœ… CLI commands work properly +- βœ… Your hello world function is implemented +- βœ… You're ready for the next project + +**Expected Output:** +``` +πŸ”₯ TinyTorch Setup Verification πŸ”₯ +================================== + +βœ… Python version: 3.x.x (compatible) +βœ… Dependencies: All installed correctly +βœ… CLI commands: Working properly +βœ… hello_tinytorch(): Implemented correctly +βœ… Test suite: All tests passing + +πŸŽ‰ Setup complete! You're ready to build an ML system from scratch. + +Next steps: + cd ../tensor/ + cat README.md + +You can now submit this project: + python3 bin/tito.py submit --project setup +``` + +## πŸ“š What You've Learned + +- **Environment setup**: Python, dependencies, development tools +- **CLI workflow**: Using `tito` commands for testing and status checks +- **Project structure**: How code is organized in TinyTorch +- **Implementation pattern**: Where to write code and how to test it +- **Verification process**: Using automated checkers to validate your work + +## 🎯 Next Project + +Once setup passes, move to your first real implementation: + +```bash +cd ../tensor/ +cat README.md # Start building the core tensor system +``` + +--- + +**Need help?** Check the main README.md or ask in office hours! \ No newline at end of file diff --git a/projects/setup/check_setup.py b/projects/setup/check_setup.py new file mode 100644 index 00000000..f1ac2f58 --- /dev/null +++ b/projects/setup/check_setup.py @@ -0,0 +1,211 @@ +#!/usr/bin/env python3 +""" +TinyTorch Setup Verification Script + +This script performs comprehensive checks to ensure the student's +environment is properly configured for the TinyTorch course. + +Usage: python projects/setup/check_setup.py +""" + +import sys +import os +import subprocess +import importlib.util + +def print_header(): + """Print the verification header.""" + print("πŸ”₯ TinyTorch Setup Verification πŸ”₯") + print("=" * 50) + print() + +def check_python_version(): + """Verify Python version is 3.8+.""" + print("🐍 Checking Python version...") + version = sys.version_info + + if version.major == 3 and version.minor >= 8: + print(f"βœ… Python version: {version.major}.{version.minor}.{version.micro} (compatible)") + return True + else: + print(f"❌ Python version: {version.major}.{version.minor}.{version.micro} (need 3.8+)") + return False + +def check_virtual_environment(): + """Check if running in a virtual environment.""" + print("\n🐍 Checking virtual environment...") + + # Check if in virtual environment + in_venv = (hasattr(sys, 'real_prefix') or + (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix)) + + if in_venv: + print("βœ… Virtual environment: Active") + print(f" Environment: {sys.prefix}") + return True + else: + print("⚠️ Virtual environment: Not detected") + print(" Recommendation: Use 'source tinytorch-env/bin/activate'") + print(" (This is strongly recommended for consistency)") + return True # Don't fail, just warn + +def check_dependencies(): + """Check that all required dependencies are installed.""" + print("\nπŸ“¦ Checking dependencies...") + + required_packages = { + 'numpy': 'numpy', + 'matplotlib': 'matplotlib', + 'yaml': 'PyYAML', + 'pytest': 'pytest' + } + all_good = True + + for import_name, package_name in required_packages.items(): + try: + if import_name == 'yaml': + import yaml as module + else: + module = __import__(import_name) + + # Get version if available + version = getattr(module, '__version__', 'unknown') + print(f"βœ… {package_name}: {version}") + except ImportError: + print(f"❌ {package_name}: missing") + all_good = False + + if all_good: + print("βœ… Dependencies: All installed correctly") + else: + print("❌ Dependencies: Some packages missing") + print(" Solution: Activate venv and run 'pip install -r requirements.txt'") + + return all_good + +def check_cli_commands(): + """Test that tito CLI commands work.""" + print("\nπŸ”§ Checking CLI commands...") + + try: + # Test --version + result = subprocess.run([sys.executable, 'bin/tito.py', '--version'], + capture_output=True, text=True, timeout=10) + if result.returncode == 0 and 'TinyπŸ”₯Torch' in result.stdout: + print("βœ… tito --version: Working") + else: + print("❌ tito --version: Failed") + return False + + # Test info command + result = subprocess.run([sys.executable, 'bin/tito.py', 'info'], + capture_output=True, text=True, timeout=10) + if result.returncode == 0 and 'Implementation Status' in result.stdout: + print("βœ… tito info: Working") + else: + print("❌ tito info: Failed") + return False + + print("βœ… CLI commands: Working properly") + return True + + except Exception as e: + print(f"❌ CLI commands: Error - {e}") + return False + +def check_hello_implementation(): + """Check the student's hello_tinytorch implementation.""" + print("\nπŸ‘‹ Checking hello_tinytorch() implementation...") + + try: + # Add project root to path + project_root = os.path.join(os.path.dirname(__file__), '../..') + sys.path.insert(0, project_root) + + from tinytorch.core.utils import hello_tinytorch + + # Test the function + result = hello_tinytorch() + + if not isinstance(result, str): + print(f"❌ hello_tinytorch(): Should return string, got {type(result)}") + return False + + if len(result.strip()) == 0: + print("❌ hello_tinytorch(): Should return non-empty string") + return False + + if 'πŸ”₯' not in result: + print("❌ hello_tinytorch(): Should contain πŸ”₯ emoji") + return False + + print(f"βœ… hello_tinytorch(): Implemented correctly") + print(f" Message: {result}") + return True + + except ImportError as e: + print(f"❌ hello_tinytorch(): Function not found - {e}") + print(" Make sure you've added the function to tinytorch/core/utils.py") + return False + except Exception as e: + print(f"❌ hello_tinytorch(): Error - {e}") + return False + +def run_test_suite(): + """Run the pytest test suite for setup.""" + print("\nπŸ§ͺ Running test suite...") + + try: + test_file = os.path.join(os.path.dirname(__file__), 'test_setup.py') + result = subprocess.run([sys.executable, '-m', 'pytest', test_file, '-v'], + capture_output=True, text=True, timeout=30) + + if result.returncode == 0: + print("βœ… Test suite: All tests passing") + return True + else: + print("❌ Test suite: Some tests failing") + print(" Test output:") + print(result.stdout) + if result.stderr: + print(result.stderr) + return False + + except Exception as e: + print(f"❌ Test suite: Error running tests - {e}") + return False + +def print_summary(all_checks): + """Print final summary.""" + print("\n" + "=" * 50) + + if all(all_checks): + print("πŸŽ‰ Setup complete! You're ready to build an ML system from scratch.") + print("\nNext steps:") + print(" cd ../tensor/") + print(" cat README.md") + print("\nYou can now submit this project:") + print(" python bin/tito.py submit --project setup") + else: + print("❌ Setup incomplete. Please fix the issues above before continuing.") + print("\nNeed help? Check the README.md or ask in office hours.") + +def main(): + """Run all setup verification checks.""" + print_header() + + checks = [ + check_python_version(), + check_virtual_environment(), + check_dependencies(), + check_cli_commands(), + check_hello_implementation(), + run_test_suite() + ] + + print_summary(checks) + return all(checks) + +if __name__ == "__main__": + success = main() + sys.exit(0 if success else 1) \ No newline at end of file diff --git a/projects/setup/create_env.py b/projects/setup/create_env.py new file mode 100644 index 00000000..c300835e --- /dev/null +++ b/projects/setup/create_env.py @@ -0,0 +1,205 @@ +#!/usr/bin/env python3 +""" +TinyTorch Environment Setup Script + +This script automatically creates a virtual environment and installs +all required dependencies for the TinyTorch course. + +Usage: python projects/setup/create_env.py +""" + +import sys +import subprocess +import os +from pathlib import Path + +def print_step(step, message): + """Print a formatted step message.""" + print(f"\nπŸ”₯ Step {step}: {message}") + print("-" * 50) + +def run_command(cmd, check=True): + """Run a command and handle errors gracefully.""" + print(f"Running: {' '.join(cmd)}") + try: + result = subprocess.run(cmd, check=check, capture_output=True, text=True) + if result.stdout: + print(result.stdout) + return result + except subprocess.CalledProcessError as e: + print(f"❌ Error: {e}") + if e.stderr: + print(f"Error details: {e.stderr}") + return None + +def check_python_version(): + """Check if Python version is compatible.""" + version = sys.version_info + if version.major != 3 or version.minor < 8: + print(f"❌ Python {version.major}.{version.minor} detected. Need Python 3.8+") + print("Please install Python 3.8+ and try again.") + return False + + print(f"βœ… Python {version.major}.{version.minor}.{version.micro} detected (compatible)") + return True + +def create_virtual_environment(): + """Create the TinyTorch virtual environment.""" + env_path = Path("tinytorch-env") + + if env_path.exists(): + print(f"⚠️ Virtual environment already exists at {env_path}") + response = input("Remove and recreate? [y/N]: ").lower().strip() + if response == 'y': + import shutil + shutil.rmtree(env_path) + else: + print("Using existing environment...") + return True + + # Create virtual environment + result = run_command([sys.executable, "-m", "venv", "tinytorch-env"]) + if result is None: + print("❌ Failed to create virtual environment") + return False + + print("βœ… Virtual environment created") + return True + +def get_venv_python(): + """Get the path to Python in the virtual environment.""" + if sys.platform == "win32": + return Path("tinytorch-env/Scripts/python.exe") + else: + return Path("tinytorch-env/bin/python") + +def install_dependencies(): + """Install required dependencies in the virtual environment.""" + venv_python = get_venv_python() + + if not venv_python.exists(): + print(f"❌ Virtual environment Python not found at {venv_python}") + return False + + # Upgrade pip first + print("Upgrading pip...") + result = run_command([str(venv_python), "-m", "pip", "install", "--upgrade", "pip"]) + if result is None: + return False + + # Install build tools first (required for Python 3.13+) + print("Installing build tools...") + result = run_command([str(venv_python), "-m", "pip", "install", "--upgrade", "setuptools", "wheel"]) + if result is None: + return False + + # Try installing dependencies - first with requirements file + print("Installing TinyTorch dependencies...") + result = run_command([str(venv_python), "-m", "pip", "install", "-r", "requirements.txt"]) + + # If that fails, try installing core packages individually (fallback for Python 3.13) + if result is None: + print("⚠️ Requirements file failed, trying individual packages...") + core_packages = [ + "numpy>=1.21.0", + "matplotlib>=3.5.0", + "PyYAML>=6.0", + "pytest>=7.0.0", + "pytest-cov>=4.0.0" + ] + + for package in core_packages: + print(f"Installing {package}...") + result = run_command([str(venv_python), "-m", "pip", "install", package]) + if result is None: + print(f"❌ Failed to install {package}") + return False + + print("βœ… Dependencies installed") + return True + +def verify_installation(): + """Verify that everything is installed correctly.""" + venv_python = get_venv_python() + + # Test core imports + test_script = ''' +import sys +try: + import numpy + import matplotlib + import yaml + import pytest + print("βœ… All core dependencies imported successfully") + print(f"Python: {sys.version}") + print(f"NumPy: {numpy.__version__}") + print(f"Matplotlib: {matplotlib.__version__}") + print(f"PyYAML: {yaml.__version__}") + print(f"Pytest: {pytest.__version__}") +except ImportError as e: + print(f"❌ Import error: {e}") + sys.exit(1) +''' + + result = run_command([str(venv_python), "-c", test_script]) + return result is not None + +def print_next_steps(): + """Print instructions for next steps.""" + print("\n" + "=" * 60) + print("πŸŽ‰ Environment setup complete!") + print("=" * 60) + + if sys.platform == "win32": + activate_cmd = "tinytorch-env\\Scripts\\activate" + else: + activate_cmd = "source tinytorch-env/bin/activate" + + print(f""" +Next steps: + +1. Activate your environment (do this every time you work): + {activate_cmd} + +2. Verify the setup: + python3 projects/setup/check_setup.py + +3. Start the first project: + cd projects/setup/ + cat README.md + +πŸ“ Remember: Always activate your virtual environment before working! +""") + +def main(): + """Run the complete environment setup.""" + print("πŸ”₯ TinyTorch Environment Setup πŸ”₯") + print("=" * 60) + + # Step 1: Check Python version + print_step(1, "Checking Python version") + if not check_python_version(): + return False + + # Step 2: Create virtual environment + print_step(2, "Creating virtual environment") + if not create_virtual_environment(): + return False + + # Step 3: Install dependencies + print_step(3, "Installing dependencies") + if not install_dependencies(): + return False + + # Step 4: Verify installation + print_step(4, "Verifying installation") + if not verify_installation(): + return False + + # Print next steps + print_next_steps() + return True + +if __name__ == "__main__": + success = main() + sys.exit(0 if success else 1) \ No newline at end of file diff --git a/projects/setup/test_setup.py b/projects/setup/test_setup.py new file mode 100644 index 00000000..8914e8cb --- /dev/null +++ b/projects/setup/test_setup.py @@ -0,0 +1,73 @@ +#!/usr/bin/env python3 +""" +Setup Project Tests + +This file tests the student's implementation of the hello_tinytorch() function. +Students can run: python -m pytest projects/setup/test_setup.py +""" + +import sys +import os +import pytest + +# Add the project root to Python path so we can import tinytorch +sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../..')) + +def test_hello_tinytorch_exists(): + """Test that the hello_tinytorch function exists and can be imported.""" + try: + from tinytorch.core.utils import hello_tinytorch + except ImportError: + pytest.fail("Could not import hello_tinytorch from tinytorch.core.utils. " + "Make sure you've implemented the function!") + +def test_hello_tinytorch_returns_string(): + """Test that hello_tinytorch returns a string.""" + from tinytorch.core.utils import hello_tinytorch + + result = hello_tinytorch() + assert isinstance(result, str), f"hello_tinytorch() should return a string, got {type(result)}" + +def test_hello_tinytorch_not_empty(): + """Test that hello_tinytorch returns a non-empty string.""" + from tinytorch.core.utils import hello_tinytorch + + result = hello_tinytorch() + assert len(result.strip()) > 0, "hello_tinytorch() should return a non-empty string" + +def test_hello_tinytorch_contains_welcome(): + """Test that the greeting contains welcoming content.""" + from tinytorch.core.utils import hello_tinytorch + + result = hello_tinytorch().lower() + # Should contain some welcoming words + welcome_words = ['welcome', 'hello', 'tinytorch', 'ready'] + + assert any(word in result for word in welcome_words), \ + f"hello_tinytorch() should contain welcoming content. Got: {hello_tinytorch()}" + +def test_hello_tinytorch_has_fire_emoji(): + """Test that the greeting contains the fire emoji (matching brand).""" + from tinytorch.core.utils import hello_tinytorch + + result = hello_tinytorch() + assert 'πŸ”₯' in result, \ + f"hello_tinytorch() should contain the πŸ”₯ emoji to match TinyTorch branding. Got: {result}" + +def test_hello_tinytorch_proper_format(): + """Test that the function has proper docstring and type hints.""" + from tinytorch.core.utils import hello_tinytorch + import inspect + + # Check that function has a docstring + assert hello_tinytorch.__doc__ is not None, \ + "hello_tinytorch() should have a docstring explaining what it does" + + # Check type annotations + sig = inspect.signature(hello_tinytorch) + assert sig.return_annotation == str, \ + "hello_tinytorch() should have return type annotation -> str" + +if __name__ == "__main__": + # Allow running this file directly for testing + pytest.main([__file__, "-v"]) \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index b857a343..f41f252b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,19 +1,26 @@ -# Core dependencies -numpy>=1.21.0 +# TinyTorch Course Dependencies +# Compatible with Python 3.8-3.13 -# Optional performance dependencies -numba>=0.56.0 +# Build tools (required first) +setuptools>=70.0.0 +wheel>=0.42.0 -# Development dependencies -pytest>=6.0.0 -black>=21.0.0 -mypy>=0.910 +# Core numerical computing (use compatible versions) +numpy>=1.21.0,<2.0.0 +matplotlib>=3.5.0 +PyYAML>=6.0 -# Configuration and logging -pyyaml>=5.4.0 +# Testing framework +pytest>=7.0.0 +pytest-cov>=4.0.0 -# For visualization and plotting (optional) -matplotlib>=3.3.0 +# Optional performance (uncomment if needed) +# numba>=0.58.0 -# Type hints for older Python versions -typing-extensions>=3.10.0 \ No newline at end of file +# Development tools (recommended) +black>=23.0.0 +mypy>=1.0.0 +flake8>=6.0.0 + +# Type checking support +typing-extensions>=4.0.0 \ No newline at end of file diff --git a/tinytorch/__init__.py b/tinytorch/__init__.py new file mode 100644 index 00000000..dfb3c550 --- /dev/null +++ b/tinytorch/__init__.py @@ -0,0 +1,14 @@ +""" +TinyπŸ”₯Torch: A complete ML system built from scratch. + +TinyTorch is a pedagogical project for learning how machine learning +systems work by implementing every component from first principles. +""" + +__version__ = "0.1.0" +__author__ = "TinyTorch Students" + +# Core components will be imported here as they're implemented +# from .core.tensor import Tensor +# from .core.autograd import Variable +# from .core.modules import Module \ No newline at end of file diff --git a/tinytorch/core/__init__.py b/tinytorch/core/__init__.py index 86ed3e73..cf9f179c 100644 --- a/tinytorch/core/__init__.py +++ b/tinytorch/core/__init__.py @@ -1,36 +1,15 @@ """ -TinyTorch Core Module +TinyTorch Core Components -Core components of the TinyTorch ML system including tensors, autograd, -neural network modules, optimizers, and training infrastructure. +This package contains the fundamental building blocks of the TinyTorch ML system: +- Tensor operations and storage +- Automatic differentiation engine +- Neural network modules and layers +- Training and optimization algorithms """ -from .tensor import Tensor -from .modules import Module, Linear, Conv2d, MaxPool2d -from .optimizer import Optimizer, SGD, Adam -from .trainer import Trainer -from .mlops import ( - DataDriftDetector, - ModelMonitor, - ModelRegistry, - ABTestFramework, - ProductionServer -) - -__version__ = "0.1.0" -__all__ = [ - "Tensor", - "Module", - "Linear", - "Conv2d", - "MaxPool2d", - "Optimizer", - "SGD", - "Adam", - "Trainer", - "DataDriftDetector", - "ModelMonitor", - "ModelRegistry", - "ABTestFramework", - "ProductionServer" -] \ No newline at end of file +# Core imports will be added as components are implemented +# from .tensor import Tensor +# from .autograd import backward +# from .modules import Linear, Conv2d +# from .optimizer import SGD, Adam \ No newline at end of file diff --git a/tinytorch/core/utils.py b/tinytorch/core/utils.py new file mode 100644 index 00000000..09553c1e --- /dev/null +++ b/tinytorch/core/utils.py @@ -0,0 +1,49 @@ +""" +TinyTorch Utility Functions + +This module contains utility functions used throughout the TinyTorch system. +Students will implement various utility functions here as part of different projects. +""" + +from typing import Any, List, Dict + + +def format_tensor_shape(shape: tuple) -> str: + """ + Format a tensor shape tuple for pretty printing. + + Args: + shape: Tuple representing tensor dimensions + + Returns: + Formatted string representation of the shape + """ + return f"({', '.join(map(str, shape))})" + + +def validate_tensor_operation(name: str, *tensors) -> None: + """ + Validate that tensors are compatible for an operation. + + Args: + name: Name of the operation being performed + *tensors: Variable number of tensor objects to validate + + Raises: + ValueError: If tensors are incompatible + """ + # TODO: Implement tensor validation logic + pass + + +# TODO: Implement hello_tinytorch() function here for the setup project +# +# def hello_tinytorch() -> str: +# """ +# Return a greeting message for new TinyTorch users. +# +# Returns: +# A welcoming message string +# """ +# # Your implementation goes here +# pass \ No newline at end of file