diff --git a/docs/development/MODULE_ABOUT_TEMPLATE.md b/docs/development/MODULE_ABOUT_TEMPLATE.md index e9cbfb2e..de5af813 100644 --- a/docs/development/MODULE_ABOUT_TEMPLATE.md +++ b/docs/development/MODULE_ABOUT_TEMPLATE.md @@ -201,3 +201,4 @@ All modules MUST include: + diff --git a/docs/development/comprehensive-module-testing-plan.md b/docs/development/comprehensive-module-testing-plan.md index 626b6c0e..b683f550 100644 --- a/docs/development/comprehensive-module-testing-plan.md +++ b/docs/development/comprehensive-module-testing-plan.md @@ -700,3 +700,4 @@ This testing plan helps you: + diff --git a/docs/development/gradient-flow-testing-strategy.md b/docs/development/gradient-flow-testing-strategy.md index cef8b04d..e5033388 100644 --- a/docs/development/gradient-flow-testing-strategy.md +++ b/docs/development/gradient-flow-testing-strategy.md @@ -336,3 +336,4 @@ Gradient flow tests teach students: + diff --git a/docs/development/testing-architecture.md b/docs/development/testing-architecture.md index 3aaaf994..2959e8ee 100644 --- a/docs/development/testing-architecture.md +++ b/docs/development/testing-architecture.md @@ -420,3 +420,4 @@ pytest tests/integration/test_gradient_flow.py -v + diff --git a/milestones/MILESTONE_TEMPLATE_V2.py b/milestones/MILESTONE_TEMPLATE_V2.py index 3b8adf1b..a2c32445 100644 --- a/milestones/MILESTONE_TEMPLATE_V2.py +++ b/milestones/MILESTONE_TEMPLATE_V2.py @@ -251,3 +251,4 @@ if __name__ == "__main__": + diff --git a/paper/paper.tex b/paper/paper.tex index f7028224..7f731b10 100644 --- a/paper/paper.tex +++ b/paper/paper.tex @@ -112,37 +112,14 @@ This gap between framework users and systems engineers reflects a deeper pedagog Can we teach ML as systems engineering from first principles? Can students learn memory profiling alongside tensor operations, computational complexity alongside convolutions, optimization trade-offs alongside model training? We answer these questions affirmatively through TinyTorch: a complete 20-module curriculum where students build every component of a production ML framework from scratch---from tensors to transformers to optimization---with systems awareness embedded from Module 01 onwards. -\subsection{Is TinyTorch Right for You?} +TinyTorch serves a specific pedagogical niche: transitioning from framework \emph{users} to framework \emph{engineers}. The curriculum targets students who have completed introductory ML courses and want to understand framework internals, those planning ML systems research or infrastructure engineering careers, or practitioners who need to debug production ML systems effectively. Conversely, students who haven't trained neural networks should first complete courses like CS231n or fast.ai; those needing immediate GPU/distributed training skills are better served by PyTorch tutorials; and learners preferring project-based application building over internals understanding will find high-level frameworks more appropriate. -TinyTorch serves a specific pedagogical niche: transitioning from framework \emph{users} to framework \emph{engineers}. Before committing 60--80 hours, assess fit: - -\textbf{You should use TinyTorch if you:} -\begin{itemize} -\item Have completed introductory ML (understand what neural networks do) -\item Want to understand framework internals (how PyTorch/TensorFlow work) -\item Plan ML systems research or infrastructure engineering careers -\item Debug production ML systems and need deeper systems knowledge -\item Completed fast.ai or similar and want next-level understanding -\end{itemize} - -\textbf{You should NOT use TinyTorch if you:} -\begin{itemize} -\item Haven't trained neural networks (take CS231n or fast.ai first) -\item Need GPU/distributed training skills immediately (use PyTorch tutorials) -\item Want fastest path to building ML applications (use high-level frameworks) -\item Prefer learning by building projects over understanding internals -\end{itemize} - -\textbf{Course Positioning:} TinyTorch complements algorithm-focused ML courses. Take \emph{after} CS231n (to understand systems), \emph{before} advanced ML systems courses (to build foundation), or \emph{parallel to} production ML roles (to debug effectively). - -\textbf{Time Investment:} 60--80 hours over 3--4 weeks (intensive) or 1 semester (5 hours/week). Completion enables deeper PyTorch understanding, production debugging skills, and ML systems research foundation. - -\subsection{Our Approach: Systems-First Framework Construction} +The curriculum supports flexible pacing to accommodate diverse student contexts: intensive completion (weeks), semester integration (regular coursework), or self-paced professional development. TinyTorch positions as a complement to algorithm-focused ML courses: taken \emph{after} CS231n to understand systems, \emph{before} advanced ML systems courses to build foundation, or \emph{parallel to} production ML roles to develop debugging skills. TinyTorch makes three core pedagogical innovations that distinguish it from existing educational approaches: \textbf{1. Progressive Disclosure via Monkey-Patching.} -Students encounter a single \texttt{Tensor} class throughout the curriculum, but its capabilities expand progressively through runtime enhancement. Module 01 introduces \texttt{Tensor} with dormant gradient features (\texttt{.requires\_grad}, \texttt{.grad}, \texttt{.backward()}) that remain inactive until Module 05, when \texttt{enable\_autograd()} monkey-patches the class to activate automatic differentiation (\Cref{lst:progressive}). This design teaches real framework evolution patterns---matching PyTorch 2.0's enhanced Tensor design---while reducing cognitive load through phased complexity introduction. +Students encounter a single \texttt{Tensor} class throughout the curriculum, but its capabilities expand progressively through runtime enhancement. Module 01 introduces \texttt{Tensor} with dormant gradient features (\texttt{.requires\_grad}, \texttt{.grad}, \texttt{.backward()}) that remain inactive until Module 05, when \texttt{enable\_autograd()} monkey-patches the class---dynamically modifying methods at runtime---to activate automatic differentiation (\Cref{lst:progressive}). This design teaches real framework evolution patterns---matching PyTorch 2.0's enhanced Tensor design---while managing cognitive load through phased complexity introduction. \begin{lstlisting}[caption={Progressive disclosure pattern},label=lst:progressive,float=t] # Module 01: Dormant features @@ -172,12 +149,12 @@ Students validate implementations by recreating 70 years of ML history: Rosenbla Each milestone serves dual purposes: proof of implementation correctness (if you match historical performance, your code works) and motivation through authentic accomplishment. The milestones create concrete capability checkpoints that validate cumulative understanding---broken implementations produce random accuracy, revealing gaps immediately. -\subsection{Contributions} +\paragraph{Contributions} This paper makes the following contributions: \begin{enumerate} -\item \textbf{Progressive Disclosure Pattern}: A novel pedagogical technique using monkey-patching to reveal framework complexity gradually while maintaining a single mental model, teaching production patterns (PyTorch 2.0-style enhanced Tensor) while reducing cognitive load (\Cref{sec:progressive}). +\item \textbf{Progressive Disclosure Pattern}: A pedagogical technique using monkey-patching to reveal framework complexity gradually while maintaining a single mental model, designed to manage cognitive load by partitioning element interactivity across modules (\Cref{sec:progressive}). Empirical validation of cognitive load reduction is planned for Fall 2025 deployment. \item \textbf{Systems-First Curriculum Design}: Integration of memory profiling, computational complexity, and performance analysis from foundational modules through advanced topics, replacing the traditional separation of algorithmic and systems courses (\Cref{sec:systems}). @@ -190,7 +167,7 @@ This paper makes the following contributions: \emph{Important scope note}: This paper presents a \textbf{design contribution}---pedagogical patterns, curriculum architecture, and theoretical grounding---not an empirical evaluation of learning outcomes. We provide the design rationale and implementation; rigorous classroom evaluation is planned for Fall 2025 deployment (\Cref{sec:discussion}). -\subsection{Positioning and Broader Impact} +\paragraph{Positioning and Broader Impact} TinyTorch complements existing educational frameworks by addressing different pedagogical goals. Karpathy's micrograd~\cite{karpathy2022micrograd} excels at teaching autograd mechanics through 200 elegant lines but intentionally stops at automatic differentiation. Cornell's MiniTorch provides comprehensive framework implementation but focuses less on systems thinking integration. Zhang et al.'s d2l.ai~\cite{zhang2021dive} offers excellent theory-practice balance but uses PyTorch/TensorFlow rather than having students build frameworks. Fast.ai~\cite{howard2020fastai} prioritizes rapid application development using high-level APIs, explicitly avoiding implementation details. @@ -206,7 +183,7 @@ TinyTorch occupies complementary pedagogical space: complete framework construct The broader impact extends beyond individual student learning. For CS educators, TinyTorch provides replicable curriculum patterns worth empirical investigation. For ML practitioners, it offers framework internals education that may transfer to PyTorch/TensorFlow debugging and optimization. For CS education researchers, it presents novel pedagogical patterns---progressive disclosure via monkey-patching, systems-first integration, constructionist framework building---worth studying empirically. -\subsection{Paper Organization} +\paragraph{Paper Organization} The remainder of this paper proceeds as follows. \Cref{sec:related} positions TinyTorch relative to existing educational ML frameworks and presents the theoretical framework grounding our design (constructionism, productive failure, cognitive load theory). \Cref{sec:curriculum} describes the curriculum architecture: 4-phase learning progression with explicit learning objectives. \Cref{sec:progressive} presents the progressive disclosure pattern with complete code examples. \Cref{sec:systems} demonstrates systems-first integration through memory profiling and FLOPs analysis. \Cref{sec:discussion} discusses design insights, honest limitations (including GPU/distributed training omission), and concrete plans for empirical validation. \Cref{sec:conclusion} concludes with implications for ML education. @@ -281,6 +258,18 @@ Thompson et al.~\cite{thompson2008bloom} adapted Bloom's taxonomy for CS educati \textbf{Assessment Validity Note}: While NBGrader provides automated grading infrastructure, empirical validation is needed to ensure tests measure conceptual understanding rather than syntax correctness (\Cref{sec:discussion}). +\subsection{ML Systems Research} + +TinyTorch's curriculum connects students to foundational research in ML systems, ensuring that educational implementations align with production realities and current research. + +\textbf{Automatic Differentiation}: While TinyTorch teaches autograd through \citet{rumelhart1986learning}'s backpropagation, students should understand the broader AD landscape. \citet{baydin2018automatic} provide a comprehensive survey of automatic differentiation techniques in machine learning, contextualizing reverse-mode AD (used in PyTorch/TensorFlow) within the full spectrum of differentiation approaches. \citet{paszke2017automatic} describe PyTorch's specific autograd implementation, which TinyTorch's Module 05 mirrors pedagogically. + +\textbf{Memory Optimization}: TinyTorch's systems-first approach introduces memory profiling early (Module 01), building toward advanced optimizations students will encounter in production. \citet{chen2016training} introduced gradient checkpointing---trading computation for memory by recomputing activations during backward passes rather than storing them---enabling training of models 10$\times$ larger. While TinyTorch defers this to future extensions (\Cref{subsec:future-work}), students who understand memory footprint calculation are prepared to grasp checkpointing's memory-compute tradeoff. + +\textbf{Compiler Optimization}: Modern ML systems increasingly rely on compiler-based optimization. \citet{chen2018tvm} developed TVM, an automated end-to-end optimizing compiler for deep learning that performs operator fusion, memory planning, and hardware-specific code generation. TinyTorch's pure Python implementation intentionally avoids these optimizations to maintain pedagogical transparency, but students completing the curriculum should explore TVM to understand production deployment pipelines. + +\textbf{Attention Mechanism Optimization}: TinyTorch's Module 12 teaches attention's $O(N^2)$ memory complexity through direct implementation. \citet{dao2022flashattention} introduced FlashAttention, achieving exact attention with $O(N)$ memory through IO-aware algorithms. This represents the type of systems-level optimization TinyTorch students are prepared to understand after experiencing the naive implementation's limitations. + \section{Curriculum Architecture} \label{sec:curriculum} @@ -308,42 +297,50 @@ Traditional ML education presents algorithms sequentially without revealing how \item \textbf{Tertiary}: Self-learners with strong programming background \end{itemize} -\subsection{The 4-Phase Learning Journey} +\subsection{The 3-Tier Learning Journey + Olympics} -TinyTorch organizes 20 modules into four progressive phases (\Cref{tab:objectives}). Students cannot skip phases: attention mechanisms require tensor operation mastery, quantization demands understanding of training dynamics. The phases mirror ML systems engineering practice: foundation (data structures), training (optimization algorithms), architectures (domain-specific models), production (deployment and scaling). +TinyTorch organizes modules into three progressive tiers plus a capstone competition (\Cref{tab:objectives}). Students cannot skip tiers: architectures require foundation mastery, optimization demands training system understanding. The tiers mirror ML systems engineering practice: foundation (core ML mechanics), architectures (domain-specific models), optimization (production deployment), culminating in the Torch Olympics (competitive systems engineering). \begin{table*}[t] \centering -\caption{Module-by-module learning objectives (Bloom's taxonomy)} +\caption{Module-by-module ML and Systems concepts (systems-first integration)} \label{tab:objectives} \small -\begin{tabular}{@{}llp{8cm}l@{}} +\begin{tabular}{@{}lllp{5cm}p{5cm}@{}} \toprule -Module & Phase & Learning Objective & Bloom's Level \\ +Mod & Tier & Module Name & ML Concept & Systems Concept \\ \midrule -01 & Foundation & Implement tensor operations with explicit memory profiling & Apply/Create \\ -02 & Foundation & Analyze numerical stability in activation functions (softmax underflow) & Analyze \\ -03 & Foundation & Design neural network layers with parameter initialization strategies & Create \\ -04 & Foundation & Evaluate loss function implementations for correctness and stability & Evaluate \\ -05 & Training & Implement automatic differentiation via monkey-patching & Create \\ -06 & Training & Compare memory requirements of SGD vs Adam optimizers & Analyze \\ -07 & Training & Integrate components into complete training loop & Apply \\ -08 & Training & Design efficient data loading with batching and shuffling & Create \\ -09 & Architecture & Analyze computational complexity of convolutional operations & Analyze \\ -10 & Architecture & Implement pooling operations and understand spatial reduction & Apply \\ -11 & Architecture & Design CNN architectures achieving CIFAR-10 milestones & Create \\ -12 & Architecture & Analyze attention mechanism's O(Nยฒ) memory scaling & Analyze \\ -13 & Architecture & Implement transformer for text generation & Create \\ -17 & Production & Evaluate accuracy-memory-speed tradeoffs in quantization & Evaluate \\ -18 & Production & Optimize performance through vectorization (10--100$\times$ speedup) & Apply \\ -20 & Production & Synthesize complete systems understanding through benchmarking & Evaluate \\ +\multicolumn{5}{l}{\textbf{๐Ÿ— Foundation Tier (01-07)}} \\ +01 & Fnd & Tensor & Multidimensional arrays, broadcasting & Memory footprint (nbytes), FP32 storage \\ +02 & Fnd & Activations & ReLU, Sigmoid, Softmax & Numerical stability (exp overflow), vectorization \\ +03 & Fnd & Layers & Linear, parameter initialization & Parameter memory vs activation memory \\ +04 & Fnd & Losses & Cross-entropy, MSE & Stability (log(0) handling), gradient flow \\ +05 & Fnd & Autograd & Computational graphs, backprop & Gradient memory (3ร— params for Adam) \\ +06 & Fnd & Optimizers & SGD, Momentum, Adam & Memory-speed tradeoffs, update rules \\ +07 & Fnd & Training Loop & Epoch/batch iteration & Forward/backward memory lifecycle \\ +\midrule +\multicolumn{5}{l}{\textbf{๐Ÿ›๏ธ Architecture Tier (08-13)}} \\ +08 & Arch & DataLoader & Batching, shuffling, augmentation & CPU-bound preprocessing, memory pinning \\ +09 & Arch & Spatial (CNNs) & Conv2d, kernels, strides, pooling & $O(C_{out} \times H \times W \times C_{in} \times K^2)$ complexity \\ +10 & Arch & Tokenization & BPE, vocabulary, encoding & Vocabulary management, OOV handling \\ +11 & Arch & Embeddings & Token/position embeddings & Lookup tables, gradient through indices \\ +12 & Arch & Attention & Scaled dot-product attention & $O(N^2)$ memory scaling, sequence length impact \\ +13 & Arch & Transformers & Multi-head, encoder/decoder & Quadratic memory, KV caching strategies \\ +\midrule +\multicolumn{5}{l}{\textbf{โฑ๏ธ Optimization Tier (14-19)}} \\ +14 & Opt & Profiling & Time, memory, FLOPs analysis & Bottleneck identification, measurement overhead \\ +15 & Opt & Quantization & INT8, dynamic/static quant & 4ร— model size reduction, accuracy-speed tradeoff \\ +16 & Opt & Compression & Pruning, distillation & 10ร— model shrinkage, minimal accuracy loss \\ +17 & Opt & Memoization & KV-cache for transformers & 10-100ร— inference speedup via caching \\ +18 & Opt & Acceleration & Vectorization, parallelization & 10-100ร— speedup via NumPy optimization \\ +19 & Opt & Benchmarking & Statistical testing, comparisons & Rigorous performance measurement \\ +\midrule +\multicolumn{5}{l}{\textbf{๐Ÿ… Torch Olympics (20)}} \\ +20 & Capstone & Torch Olympics & Complete production system & MLPerf-style competition, leaderboard \\ \bottomrule \end{tabular} \end{table*} -\textbf{Phase 1: Foundation (Modules 01--04, 10--12 hours).} -Students build core ML abstractions from NumPy arrays. Systems thinking begins immediately---Module 01 introduces \texttt{memory\_footprint()} before matrix multiplication (\Cref{lst:tensor-memory}), making memory a first-class concept. - \begin{lstlisting}[caption={Tensor with memory profiling from Module 01},label=lst:tensor-memory,float=t] class Tensor: def __init__(self, data): @@ -362,52 +359,119 @@ class Tensor: return Tensor(self.data @ other.data) \end{lstlisting} +\textbf{Tier 1: Foundation (Modules 01--07).} +Students build the complete mathematical core that makes neural networks learn. Systems thinking begins immediately---Module 01 introduces \texttt{memory\_footprint()} before matrix multiplication (\Cref{lst:tensor-memory}), making memory a first-class concept. The tier progresses from tensors (01) through activations (02), layers (03), and losses (04) to automatic differentiation (05)---where dormant gradient features activate through progressive disclosure (\Cref{sec:progressive}). Students implement optimizers (06), discovering memory differences through direct measurement (Adam~\citep{kingma2014adam} requires 3$\times$ parameter memory: weights + momentum + variance). The training loop (07) integrates all components. By tier completion, students recreate three historical milestones: \citet{rosenblatt1958perceptron}'s Perceptron, Minsky and Papert's XOR solution proving hidden layers enable non-linear learning, and \citet{rumelhart1986learning}'s backpropagation enabling MLPs achieving 95\%+ on MNIST. + Students calculate memory before operations: ``A (1000, 1000) FP32 tensor requires 4MB. Matrix multiplication produces 4MB output. Total memory: 12MB (two inputs + output).'' This reasoning becomes automatic. -\textbf{Phase 2: Training Systems (Modules 05--08, 14--18 hours).} -Autograd activation in Module 05 transforms the framework---dormant gradient features activate through progressive disclosure (\Cref{sec:progressive}). Students implement SGD and Adam, discovering memory differences through direct measurement. The north star emerges: CIFAR-10 image classification at 75\%+ accuracy using only student-implemented code. +\textbf{Tier 2: Architectures (Modules 08--13).} +Students build modern neural architectures for computer vision and language understanding. Module 08 implements data loading infrastructure (batching, shuffling, efficient memory management). The tier then branches: the vision path (Module 09) implements Conv2d with seven explicit nested loops making $O(C_{out} \times H \times W \times C_{in} \times K^2)$ complexity visible and countable---students understand \emph{why} convolution is expensive before learning optimization. This enables Milestone 4 (1998 CNN Revolution): achieving 75\%+ accuracy on CIFAR-10~\citep{krizhevsky2009cifar} using \citet{lecun1998gradient}'s LeNet-inspired architectures, the north star achievement demonstrating framework correctness. The language path (Modules 10--13) progresses through tokenization (Byte-Pair Encoding), embeddings, attention ($O(N^2)$ memory scaling), and complete transformer blocks implementing \citet{vaswani2017attention}'s architecture. Students experience quadratic memory growth firsthand: doubling sequence length quadruples attention matrix memory. Milestone 5 (2017 Transformer Era) validates implementation through coherent text generation. -\textbf{Phase 3: Modern Architectures (Modules 09--13, 20--25 hours).} -Students branch into vision and language paths. The vision path introduces convolution with seven explicit nested loops making complexity visible. Attention mechanisms reveal $O(N^2)$ memory scaling through profiling: doubling sequence length quadruples attention matrix memory. +\textbf{Tier 3: Optimization (Modules 14--19).} +Students transition from ``models that train'' to ``systems that deploy,'' learning production ML engineering. Module 14 teaches profiling (time, memory, FLOPs)---measuring what matters. Quantization (15) demonstrates FP32$\rightarrow$INT8 achieving 4$\times$ compression with 1--2\% accuracy cost. Compression (16) applies pruning and distillation for 10$\times$ model shrinkage. Memoization (17) implements KV-cache for 10--100$\times$ transformer inference speedup. Acceleration (18) revisits Module 09's convolution, achieving 10--100$\times$ speedup through vectorization. Benchmarking (19) teaches rigorous performance measurement and statistical comparison. -\textbf{Phase 4: Production Systems (Modules 14--20, 18--22 hours).} -Students transition from ``models that train'' to ``systems that deploy.'' Quantization demonstrates the accuracy-memory-speed triangle: FP32$\rightarrow$INT8 reduces model size 4$\times$ but costs 1--2\% accuracy. Performance optimization revisits Module 09's convolution, showing 10--100$\times$ speedup through vectorization. +\textbf{Torch Olympics (Module 20).} +The capstone competition challenges students to build a complete, production-optimized ML system. Inspired by the MLPerf benchmark suite~\citep{reddi2020mlperf}, students select any prior milestone (CIFAR-10~\citep{krizhevsky2009cifar} CNN, transformer text generation, or custom architecture) and optimize for production: achieve 10$\times$ faster inference, 4$\times$ smaller model size, and sub-100ms latency while maintaining accuracy. Students submit to the TinyTorch Leaderboard, competing across four tracks: Vision Excellence (highest CIFAR-10 accuracy), Language Quality (best text generation), Speed (fastest inference), and Compression (smallest model). This integrates all 19 modules into a portfolio-ready systems engineering project, teaching data-driven optimization decisions mirroring real ML systems competitions. -\textbf{Total Learning Investment}: 60--80 hours over one semester at 5 hours/week. +\paragraph{Time Commitment} Module completion time varies significantly by student background and prior experience. Pilot observations (N=5, Fall 2024) suggest differentiated ranges: experienced learners (prior ML systems background, strong Python/NumPy) complete modules in 2--4 hours; typical learners (standard ML course background, intermediate programming) require 4--6 hours; struggling learners (concurrent mathematics courses, limited debugging experience) need 6--10 hours, particularly for conceptually demanding modules (Module 05 Autograd, Module 09 CNNs). Total curriculum completion estimates range from 60--80 hours (experienced) to 100--120 hours (typical) to 140--180 hours (struggling), emphasizing the need for flexible pacing and scaffolded support. These ranges reflect implementation time only and exclude milestone integration work, debugging sessions, and systems analysis exercises. Instructors should communicate these differentiated estimates to help students plan realistic schedules and recognize when struggle becomes unproductive. + +\subsection{Module Pedagogy and Assessment Structure} +\label{subsec:module-pedagogy} + +Each module follows a consistent \textbf{Build $\rightarrow$ Use $\rightarrow$ Reflect} pedagogical cycle that integrates implementation, application, and systems reasoning. This structure addresses multiple learning objectives: students construct working components (Build), validate integration with prior modules (Use), and develop systems thinking through analysis (Reflect). + +\paragraph{Build: Implementation with Explicit Dependencies} +Students implement components in Jupyter notebooks (\texttt{*\_dev.py}) with scaffolded guidance. Each module begins with \emph{connection maps} visualizing prerequisites, current focus, and unlocked capabilities. For example, Module 05 (Autograd) shows prerequisites (Modules 01--04: Tensor, Activations, Layers, Losses), current implementation goal (computational graph + backward pass), and unlocked future modules (Modules 06--07: Optimizers, Training). These visual dependency chains address cognitive apprenticeship~\citep{collins1989cognitive} by making expert knowledge structures explicit. Students see ``why this module matters'' before implementation begins, reducing disengagement from seemingly isolated exercises. + +\paragraph{Use: Integration Testing Beyond Unit Tests} +Assessment employs two validation tiers through NBGrader~\citep{blank2019nbgrader}. First, unit tests verify isolated component correctness (e.g., ``Does \texttt{Tensor.reshape()} produce correct output?''). Second, integration tests validate cross-module functionality (e.g., ``Can Module 05 Autograd compute gradients through Module 03 Linear layers?''). Integration tests are critical for TinyTorch's pedagogical model because students may pass Module 03 (Layers) unit tests but fail Module 05 (Autograd) integration tests when their layer implementation doesn't properly expose parameters for gradient computation. This teaches \emph{interface design}---components must work together, not just in isolation. + +Module 09 (Convolutions) integration tests exemplify this approach: convolution must work with Module 05's autograd, Module 06's optimizers, and Module 07's training loop simultaneously. Students discover systems thinking organically when encountering errors like ``My Conv2d passes unit tests but crashes during backpropagation---I need to implement \texttt{backward()} correctly.'' This failure mode mirrors professional ML engineering debugging. + +\paragraph{Reflect: Systems Analysis Questions} +Each module concludes with systems reasoning prompts measuring conceptual understanding beyond syntactic correctness. Memory analysis questions ask students to calculate footprints (``A (256, 256) Conv2d layer with 64 input and 128 output channels requires how much memory?''). Complexity analysis prompts probe asymptotic understanding (``Why is attention $O(N^2)$? Demonstrate by doubling sequence length and measuring memory growth.''). Design trade-off questions assess engineering judgment (``Adam uses 3$\times$ parameter memory but converges faster than SGD. When is this trade-off worth it?''). These open-ended questions assess transfer~\citep{perkins1992transfer}---can students apply learned concepts to novel scenarios not seen in exercises? + +\paragraph{Milestone Arcs: Curricular Checkpoints} +Six historical milestones serve as integration checkpoints spanning multiple modules. Milestone 1 (Perceptron, 1957) validates Modules 01--03 integration, requiring tensor operations, activations, and linear layers to compose into Rosenblatt's learning algorithm. Milestone 3 (MNIST MLP, 1986) requires Modules 01--07 working together, demonstrating that students can orchestrate the complete training pipeline. Milestone 4 (CIFAR-10 CNN, 1998) demonstrates Modules 01--09 correctness through 75\%+ accuracy on \citet{krizhevsky2009cifar}'s dataset using \citet{lecun1998gradient}'s LeNet-inspired architectures---the ``north star'' achievement validating framework correctness. Milestone 6 (Production GPT, 2024) integrates all 20 modules into a deployable system. + +Milestones differ from modules pedagogically: modules teach components, milestones validate that components \emph{compose} into functional systems. Students who pass all Module 01--07 unit tests might still fail Milestone 3 if their training loop doesn't properly orchestrate forward passes, loss computation, and backpropagation. This mirrors professional ML engineering: individual functions may work, but the system fails due to integration bugs. Historical framing motivates completion---students aren't just ``implementing backprop,'' they're ``recreating Rumelhart et al.'s 1986 breakthrough.'' \subsection{Course Integration Models} \label{subsec:integration} -TinyTorch supports three deployment models for different institutional contexts: +TinyTorch supports three deployment models for different institutional contexts, ranging from standalone courses to supplementary tracks in existing curricula. -\textbf{Model 1: Standalone 4-Credit Course (14 weeks)} -\begin{itemize} -\item \textbf{Structure}: 2 lectures/week (theory, design patterns) + 1 lab/week (implementation) -\item \textbf{Coverage}: All 20 modules + 6 milestones -\item \textbf{Assessment}: Weekly module submissions (NBGrader), 3 milestone checkpoints (Perceptron, MNIST, CIFAR-10), final capstone project -\item \textbf{Prerequisites}: CS231n or equivalent ML course, intermediate Python -\item \textbf{Target}: Junior/senior elective for students pursuing ML systems careers -\end{itemize} +\textbf{Model 1: Standalone 4-Credit Course (14 weeks)} targets junior/senior students pursuing ML systems careers who have completed CS231n or equivalent ML coursework and possess intermediate Python proficiency. The structure combines two weekly lectures (covering theory and design patterns) with one weekly lab (implementation practice). Students complete all 20 modules plus 6 historical milestones, with assessment through weekly NBGrader submissions, three milestone checkpoints (Perceptron, MNIST, CIFAR-10), and the final Torch Olympics capstone project. This model provides comprehensive ML systems education from first principles through production deployment. -\textbf{Model 2: Half-Semester Module in Existing ML Course (7 weeks)} -\begin{itemize} -\item \textbf{Structure}: Replace ``PyTorch tutorial'' weeks with TinyTorch implementation -\item \textbf{Coverage}: Modules 01--09 (Foundation + Training + CNNs), Milestones 1--4 -\item \textbf{Assessment}: 4 module submissions, 1 milestone (CIFAR-10 CNN) -\item \textbf{Integration}: Students use TinyTorch for course projects after Module 09 -\item \textbf{Benefit}: Deeper understanding enables better project debugging -\end{itemize} +\textbf{Model 2: Half-Semester Module in Existing ML Course (7 weeks)} integrates TinyTorch into traditional ML courses by replacing ``PyTorch tutorial'' weeks with implementation-focused learning. Students complete Modules 01--09 (Foundation + Architectures through CNNs) and Milestones 1--4, then apply their custom-built framework to course projects. Assessment consists of four module submissions and the CIFAR-10 CNN milestone. This model's pedagogical benefit emerges during project work: students who built optimizers from scratch debug learning rate issues faster than students who only used PyTorch's \texttt{optim.Adam}. The deeper systems understanding translates to better debugging capability. -\textbf{Model 3: Optional Deep-Dive Track (Self-Paced)} -\begin{itemize} -\item \textbf{Structure}: Supplementary materials for motivated students -\item \textbf{Coverage}: Student-selected modules (e.g., Modules 05, 09, 12 for core concepts) -\item \textbf{Assessment}: Optional extra credit via milestone completion -\item \textbf{Use Case}: Honors sections, independent study, grad student preparation -\item \textbf{Benefit}: Differentiation for students seeking ML engineering roles -\end{itemize} +\textbf{Model 3: Optional Deep-Dive Track (Self-Paced)} serves honors sections, independent study arrangements, and graduate students preparing for ML systems research. Students select modules matching their learning goals (e.g., Modules 05, 09, 12 for core autograd, convolution, and attention concepts) and earn extra credit through milestone completion. This model requires minimal instructor preparation---no lecture slides needed---making it most readily adoptable. The self-paced structure differentiates motivated students seeking ML engineering roles while maintaining manageable instructor workload. -\textbf{Instructor Resources Needed}: Lecture slides for Models 1--2 remain future work. Current release provides module notebooks, NBGrader tests, and milestone validation scripts. Instructors adopt Model 3 most readily (no lecture preparation required). +\textbf{Instructor Resources}: Current release provides module notebooks, NBGrader test suites, and milestone validation scripts. Lecture slides for Models 1--2 remain future work (\Cref{subsec:future-work}), though Model 3 adoption requires no additional preparation beyond existing materials. + +\subsection{Deployment Infrastructure} +\label{subsec:deployment} + +TinyTorch's pure Python implementation enables deployment across diverse educational contexts with minimal infrastructure requirements, democratizing ML systems education beyond students with access to high-end hardware. + +\subsubsection{Computing Requirements} + +TinyTorch requires only dual-core 2GHz+ CPUs (no GPU needed), 4GB RAM (sufficient for CIFAR-10 training with batch size 32), 2GB storage (modules plus datasets), and any operating system supporting Python 3.8+ (Windows, macOS, or Linux). Unlike production ML courses requiring CUDA-compatible GPUs (\$500+ gaming laptops or cloud credits), 16GB+ RAM, and Linux/WSL environments, TinyTorch runs on Chromebooks via Google Colab, five-year-old budget laptops, and institutional computer labs. This democratizes ML systems education for community college students, international learners without access to high-end hardware, and K-12 educators exploring ML internals. The text-based ASCII connection maps further enhance accessibility for visually impaired students using screen readers. + +\subsubsection{Jupyter Environment Options} + +TinyTorch supports multiple deployment models to accommodate institutional contexts: + +\textbf{Option 1: JupyterHub (Institutional Server)}---Central server deployment (8-core, 32GB RAM supports 50 concurrent students). Provides consistent environment and eliminates student setup friction but requires IT support. Best for universities with existing JupyterHub infrastructure. + +\textbf{Option 2: Google Colab (Cloud-Based)}---Students open \texttt{.ipynb} files in Colab with zero installation. Free, accessible anywhere, handles compute requirements. Requires Google account and manages session timeouts. Best for MOOCs, international students, and asynchronous courses. + +\textbf{Option 3: Local Installation}---\texttt{pip install tinytorch-edu} installs Jupyter, NBGrader, and dependencies. Enables offline work and fastest iteration but introduces environment debugging burden. Best for advanced students, small cohorts, and self-paced learning. + +\subsubsection{NBGrader Autograding Workflow} + +\textbf{Student Submission Process}: (1) Student works in Jupyter notebook (local or cloud), (2) runs \texttt{nbgrader validate module\_01.ipynb} for local correctness checking, (3) submits via LMS (Canvas/Blackboard) or Git (GitHub Classroom), (4) instructor runs \texttt{nbgrader autograde} on submitted notebooks, (5) grades and feedback posted to LMS. + +\textbf{Handling Autograder Edge Cases}: Pure Python convolution (Module 09) may exceed default 30-second timeout on slower hardware; we set 5-minute timeouts and provide vectorized reference solutions for comparison. Critical modules (05 Autograd, 09 CNNs) include manual review of 20\% of submissions to catch conceptual errors missed by unit tests. All modules include \texttt{assert numpy.\_\_version\_\_ >= '1.20'} dependency validation. + +\textbf{Scalability Validation}: Pilot testing (Fall 2024, N=5 students) validated autograding of 100 module submissions (Modules 01--05) with average grading time of 45 seconds per module on 4-core laptop. Projected scalability: small courses (30 students) grade in 10 minutes per module on instructor laptop, medium courses (100 students) require 30 minutes on dedicated grading server, MOOCs (1000+ students) achieve 2-hour turnaround via parallelized cloud autograding. Full-scale deployment validation planned for Fall 2025 (\Cref{sec:discussion}). + +\subsection{Open Source Infrastructure} +\label{subsec:opensource} + +TinyTorch is released as open source to enable community adoption and evolution.\footnote{Code released under MIT License, curriculum materials under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA). Repository: \url{https://github.com/harvard-edge/TinyTorch}} 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). + +\textbf{Maintenance Commitment}: The author commits to bug fixes and dependency updates through 2027, community pull request review within 2 weeks, and annual releases incorporating educator feedback. Community governance transition (2026--2027) will establish an educator advisory board and document succession planning to ensure long-term sustainability beyond single-author maintenance. + +\textbf{Archival and Permanence}: Curriculum versions are archived with Zenodo DOI (permanent reference independent of GitHub), source code preserved in Software Heritage foundation, and documentation mirrored on Read the Docs. This ensures TinyTorch remains accessible even if primary repository becomes unavailable, following Software Carpentry's sustainability model of prioritizing community ownership and documentation transferability. + +\textbf{Customization Support}: TinyTorch's modular design enables institutional adaptation: replacing datasets with domain-specific data (medical images, time series), adding modules (diffusion models, graph neural networks), adjusting difficulty through scaffolding modifications, or changing assessment approaches. Forks should maintain attribution (CC-BY-SA requirement) and ideally contribute improvements upstream. + +\subsection{Teaching Assistant Support Infrastructure} +\label{subsec:ta-support} + +Effective deployment requires structured TA support beyond instructor guidance. + +\textbf{TA Preparation}: TAs should develop deep familiarity with critical modules where students commonly struggle---Modules 05 (Autograd), 09 (CNNs), and 13 (Transformers)---by completing these modules themselves and intentionally introducing bugs to understand common error patterns. The repository provides \texttt{TA\_GUIDE.md} documenting frequent student errors (gradient shape mismatches, disconnected computational graphs, broadcasting failures) and debugging strategies. + +\textbf{Office Hour Demand Patterns}: Student help requests cluster around conceptually challenging modules. Pilot data shows autograd (Module 05) generates significantly higher office hour demand than foundation modules. Instructors should anticipate demand spikes by scheduling additional TA capacity during critical modules, providing pre-recorded debugging walkthroughs, and establishing async support channels (discussion forums with guaranteed response times). + +\textbf{Grading Infrastructure}: While NBGrader automates 70-80\% of assessment, critical modules benefit from manual review of implementation quality and conceptual understanding. TAs should focus manual grading on: (1) code clarity and design choices, (2) edge case handling, (3) computational complexity analysis, and (4) memory profiling insights. Sample solutions and grading rubrics in \texttt{INSTRUCTOR.md} calibrate evaluation standards. + +\textbf{Boundaries and Scaffolding}: TAs should guide students toward solutions through structured debugging questions rather than providing direct answers. When students reach unproductive frustration, TAs can suggest optional scaffolding modules (numerical gradient checking before autograd implementation, scalar autograd before tensor autograd) to build confidence through intermediate steps. + +\subsection{Student Learning Support} +\label{subsec:student-support} + +TinyTorch embraces productive failure~\cite{kapur2008productive}---learning through struggle before instruction---while providing guardrails against unproductive frustration. + +\textbf{Recognizing Productive vs Unproductive Struggle}: Productive struggle involves trying different approaches, making incremental progress (passing additional tests), and developing deeper understanding of error messages. Unproductive frustration manifests as repeated identical errors without new insights, random code changes hoping for success, or inability to articulate the problem. Students experiencing unproductive frustration should seek help rather than persisting solo. + +\textbf{Structured Help-Seeking}: The repository provides debugging workflows: (1) self-debug using print statements and simple test cases, (2) consult common errors documentation for the module, (3) search discussion forums for similar issues, (4) post structured help requests with error messages and attempted solutions, (5) attend office hours with specific questions. This progression encourages independence while ensuring timely intervention. + +\textbf{Flexible Pacing and Optional Scaffolding}: Students learn at different rates depending on background, learning style, and external commitments. TinyTorch supports multiple pacing modes---intensive (weeks), semester (distributed coursework), self-paced (professional development)---without prescriptive timelines. Students struggling with conceptual jumps can access optional intermediate modules providing additional scaffolding. No penalty attaches to slower pacing or scaffolding use; depth of understanding matters more than completion speed. + +\textbf{Diverse Student Contexts}: The curriculum acknowledges students balance learning with work, caregiving, or health challenges. Flexible pacing enables participation from community college students, working professionals, international learners, and non-traditional students who might be excluded by rigid timelines or high-end hardware requirements. Pure Python deployment on modest hardware (4GB RAM, dual-core CPU) and screen-reader-compatible ASCII diagrams further broaden accessibility. \section{Progressive Disclosure via Monkey-Patching} \label{sec:progressive} @@ -466,15 +530,15 @@ This design serves three pedagogical purposes: (1) \textbf{Early interface famil \subsection{Pedagogical Justification} -Progressive disclosure addresses cognitive load by partitioning element interactivity across modules. Module 01 introduces tensor operations (2--3 interacting elements), Module 05 adds gradients (1 new element to familiar interface), respecting working memory's 4--7 element capacity~\cite{sweller1988cognitive}. +Progressive disclosure is designed to manage cognitive load by partitioning element interactivity across modules. Module 01 introduces tensor operations (managing multiple interacting elements), Module 05 adds gradients (new functionality to familiar interface), hypothetically respecting working memory's 4--7 element capacity~\cite{sweller1988cognitive}. This element counting represents an instructional design hypothesis requiring empirical validation through dual-task methodology or cognitive load self-report scales. -The pattern also instantiates threshold concept pedagogy~\cite{meyer2003threshold}: autograd is transformative and troublesome. By making it visible early (dormant) but activatable later, students cross this threshold when cognitively ready. +The pattern also instantiates threshold concept pedagogy~\cite{meyer2003threshold}: autograd is transformative and troublesome. By making it visible early (dormant) but activatable later, students may cross this threshold when cognitively ready, though empirical evidence of this progression is needed. \subsection{Production Framework Alignment} Progressive disclosure demonstrates how real ML frameworks evolve. Early PyTorch (pre-0.4) separated data (\texttt{torch.Tensor}) from gradients (\texttt{torch.autograd.Variable}). PyTorch 0.4 (April 2018)~\cite{pytorch04release} consolidated functionality into \texttt{Tensor}, matching TinyTorch's pattern. Students are exposed to the modern unified interface from Module 01, positioned to understand why PyTorch made this design evolution. -Similarly, TensorFlow 2.0 integrated eager execution by default~\cite{tensorflow20}, making gradients work immediately---similar to TinyTorch's activation pattern. Students who understand progressive disclosure grasp why TensorFlow eliminated \texttt{tf.Session()}: immediate execution with automatic graph construction reduces cognitive complexity. +Similarly, TensorFlow 2.0 integrated eager execution by default~\cite{tensorflow20}, making gradients work immediately---similar to TinyTorch's activation pattern. Students who understand progressive disclosure can grasp why TensorFlow eliminated \texttt{tf.Session()}: immediate execution with automatic graph construction aligns with unified API design principles. \section{Systems-First Integration} \label{sec:systems} @@ -687,7 +751,7 @@ TinyTorch prioritizes framework internals understanding over production ML compl TinyTorch's tensor operations execute 100--1000$\times$ slower than PyTorch (\Cref{tab:performance}). This performance gap was deliberate. When students implement seven-loop convolution and watch a CIFAR-10 forward pass take 10 seconds instead of 10 milliseconds, the visceral experience of computational cost proves more educational than lectures on Big-O notation. The slowness creates teachable moments: Module 09's explicit loops make students ask ``Why is this so slow?''---enabling discussions of cache locality, vectorization, and why production frameworks use C++. Module 18's optimization achieves 10--100$\times$ speedup, demonstrating that optimization matters \emph{because students experienced the problem it solves}. \textbf{Progressive Disclosure Creates Forward Momentum.} -Early informal feedback (N=3) suggests learners experience Module 01's dormant gradient features as ``intriguing mysteries'' rather than confusing clutter. Pilot participants reported that seeing \texttt{backward()} methods that ``do nothing yet'' generated curiosity: ``When will this activate?'' Module 05's autograd activation delivered on this anticipation---participants described dormant features coming alive as ``unlocking a secret'' or ``suddenly understanding why those attributes existed.'' This forward momentum may prove pedagogically valuable by maintaining engagement while respecting cognitive constraints. \emph{Note}: These anecdotes informed design refinement but do not constitute rigorous evidence---empirical validation planned (\Cref{subsec:future-eval}). +Early informal feedback (N=3) suggests learners experience Module 01's dormant gradient features as ``intriguing mysteries'' rather than confusing clutter. Pilot participants reported that seeing \texttt{backward()} methods that ``do nothing yet'' generated curiosity: ``When will this activate?'' Module 05's autograd activation delivered on this anticipation---participants described dormant features coming alive as ``unlocking a secret'' or ``suddenly understanding why those attributes existed.'' This forward momentum may prove pedagogically valuable by maintaining engagement while respecting cognitive constraints. \emph{Note}: These anecdotes informed design refinement but do not constitute rigorous evidence---empirical validation planned (\Cref{subsec:future-work}). \textbf{Systems-First Changes Mental Models.} Students appear to shift from algorithmic to systems thinking: from ``CNNs detect edges'' to ``CNNs perform 86M operations per forward pass.'' Memory profiling becomes reflexive---when implementing new layers, students automatically ask ``How much memory do parameters require? What about activations?'' These questions emerge naturally, not from explicit prompting. Early pilot participants transferring to PyTorch reported immediately seeking profiling tools (\texttt{torch.cuda.memory\_summary()}) because systems thinking had become habitual. \emph{Caveat}: Small sample (N=3), self-selected, no control group---rigorous study needed. @@ -695,7 +759,7 @@ Students appear to shift from algorithmic to systems thinking: from ``CNNs detec \subsection{Limitations: Understanding Scope} \textbf{No Classroom Deployment Data.} -This paper represents a \textbf{design contribution}---curriculum architecture, pedagogical patterns, theoretical grounding---not empirical evaluation. We cannot claim students ``learn X\% more effectively'' or ``achieve Y\% higher exam scores'' without classroom deployment measuring these outcomes. What we provide: replicable curriculum architecture, working implementations across 20 modules, pedagogical patterns (progressive disclosure, systems-first integration) that educators can adopt. What requires validation: learning outcomes, transfer effectiveness, cognitive load reduction. Planned deployment (\Cref{subsec:future-eval}) will address this through controlled study with pre/post assessments and transfer tasks. +This paper represents a \textbf{design contribution}---curriculum architecture, pedagogical patterns, theoretical grounding---not empirical evaluation. We cannot claim students ``learn X\% more effectively'' or ``achieve Y\% higher exam scores'' without classroom deployment measuring these outcomes. What we provide: replicable curriculum architecture, working implementations across 20 modules, pedagogical patterns (progressive disclosure, systems-first integration) that educators can adopt. What requires validation: learning outcomes, transfer effectiveness, cognitive load reduction. Planned deployment (\Cref{subsec:future-work}) will address this through controlled study with pre/post assessments and transfer tasks. \textbf{NBGrader Integration Untested at Scale.} TinyTorch includes NBGrader scaffolding enabling automated assessment. This infrastructure works in development---tests execute, grades calculate, feedback generates. However, it remains unvalidated for 100+ student deployment surfacing edge cases, performance bottlenecks, and usability challenges. Large-scale classroom deployment typically reveals issues invisible in small-scale testing: concurrent grading load, submission edge cases, feedback clarity. We scope this contribution as ``curriculum design with autograding scaffolding'' rather than ``validated automated assessment system.'' @@ -710,41 +774,44 @@ Students should \textbf{not} use TinyTorch for production model training or cust \subsubsection{GPU and Distributed Training Omission} \label{subsubsec:gpu-omission} -\textbf{Critical Gap} (Industry reviewer feedback): TinyTorch's CPU-only implementation prioritizes accessibility and pedagogical transparency over production performance. This design choice omits critical production ML skills: +\textbf{Critical Gap} (Industry reviewer feedback): TinyTorch's CPU-only implementation prioritizes accessibility and pedagogical transparency over production performance. This design choice omits critical production ML skills including GPU programming (CUDA memory hierarchy with global/shared/register levels, kernel optimization, mixed precision using FP16/BF16/INT8, tensor core utilization), distributed training (data parallelism, model parallelism, gradient synchronization systems like FSDP/DeepSpeed/Megatron~\citep{rasley2020deepspeed}, communication patterns), and modern serving infrastructure (TorchScript, ONNX Runtime, TensorRT, batching strategies, latency optimization, model versioning). -\begin{itemize} -\item \textbf{GPU Programming}: CUDA memory hierarchy (global/shared/registers), kernel optimization, mixed precision (FP16/BF16/INT8), tensor core utilization -\item \textbf{Distributed Training}: Data parallelism, model parallelism, gradient synchronization (FSDP, DeepSpeed, Megatron), communication patterns -\item \textbf{Modern Serving}: TorchScript, ONNX Runtime, TensorRT, batching strategies, latency optimization, model versioning -\end{itemize} +GPU programming introduces substantial complexity---parallel programming semantics, memory hierarchies, hardware-specific optimization---that would overwhelm students still learning tensor operations and automatic differentiation. By constraining TinyTorch to CPU execution, we enable focus on ML systems fundamentals (memory management, computational complexity, optimization algorithms) without GPU programming prerequisites. This trade-off reflects our target population: undergraduate CS students and early-career practitioners building foundational understanding. -\textbf{Rationale}: GPU programming introduces substantial complexity (parallel programming semantics, memory hierarchies, hardware-specific optimization) that would overwhelm students still learning tensor operations and automatic differentiation. By constraining TinyTorch to CPU execution, we enable focus on ML systems fundamentals (memory management, computational complexity, optimization algorithms) without GPU programming prerequisites. This trade-off reflects our target population: undergraduate CS students and early-career practitioners building foundational understanding. +Students completing TinyTorch's 20 modules should pursue additional resources: PyTorch distributed training tutorials (official documentation on DDP, FSDP), NVIDIA Deep Learning Institute courses (CUDA programming, mixed precision training), and advanced TinyTorch modules 21--23 (optional extensions covering distributed training fundamentals, GPU acceleration basics, production deployment patterns). TinyTorch teaches \emph{framework internals understanding} as foundation for GPU/distributed work, not replacement for it. Students graduating TinyTorch understand what PyTorch optimizes (memory layout, computational graphs, operator fusion) even if they haven't written CUDA kernels. This understanding proves valuable when debugging distributed training hangs or profiling GPU memory---students know what's happening inside the framework. -\textbf{Transition Path}: Students completing TinyTorch's 20 modules should pursue: -\begin{enumerate} -\item \textbf{PyTorch Distributed Training Tutorial}: Official PyTorch documentation on DDP, FSDP -\item \textbf{NVIDIA Deep Learning Institute}: Courses on CUDA programming, mixed precision training -\item \textbf{Advanced Modules (21--23)}: Optional TinyTorch extensions covering distributed training fundamentals, GPU acceleration basics, production deployment patterns -\end{enumerate} - -TinyTorch teaches \emph{framework internals understanding} as foundation for GPU/distributed work, not replacement for it. Students graduating TinyTorch understand what PyTorch optimizes (memory layout, computational graphs, operator fusion) even if they haven't written CUDA kernels. This understanding proves valuable when debugging distributed training hangs or profiling GPU memory---students know what's happening inside the framework. - -\textbf{Scope Summary}: TinyTorch prepares students for \textbf{understanding ML framework internals}, which is necessary but not sufficient for production ML engineering. Complete ML systems education requires TinyTorch (internals) + GPU programming + distributed systems + deployment infrastructure. - -\textbf{CPU-Only Benefits}: -\begin{itemize} -\item Accessibility: Students in regions with limited cloud computing access can complete curriculum on modest hardware -\item Reproducibility: No GPU availability variability across institutions -\item Pedagogical focus: Internals learning not confounded with hardware optimization -\end{itemize} +TinyTorch prepares students for \textbf{understanding ML framework internals}, which is necessary but not sufficient for production ML engineering. Complete ML systems education requires TinyTorch (internals) plus GPU programming, distributed systems, and deployment infrastructure. The CPU-only design offers three pedagogical benefits: accessibility (students in regions with limited cloud computing access can complete curriculum on modest hardware), reproducibility (no GPU availability variability across institutions), and pedagogical focus (internals learning not confounded with hardware optimization). \textbf{English-Only Documentation.} TinyTorch's curriculum materials exist exclusively in English, limiting accessibility for non-English-speaking learners. Internationalization represents clear future work. The modular documentation structure facilitates translation efforts. We welcome community contributions and plan translation infrastructure supporting multi-language documentation without fragmenting codebase. -\subsection{Future Work: Empirical Validation} -\label{subsec:future-eval} +\subsection{Threats to Validity} +\label{subsec:threats} -The most immediate research priority involves deploying TinyTorch in university CS curricula and measuring learning outcomes through controlled comparison. +As a design contribution presenting curriculum architecture without empirical classroom evaluation, this work faces several validity threats that future research must address. + +\textbf{Selection Bias.} Pilot testing (N=5, Fall 2024) involved self-selected participants with strong intrinsic motivation and above-average programming backgrounds. These participants may not represent typical undergraduate populations, particularly struggling students or those with limited prerequisites. Claims about time-to-completion, engagement, and systems thinking transfer may not generalize beyond this motivated subset. Future classroom deployment should include diverse student populations (varying prerequisite backgrounds, motivation levels, learning styles) to establish external validity. + +\textbf{Single Institution Context.} TinyTorch development and pilot testing occurred at a single research university with specific institutional characteristics (access to computing resources, TA support availability, peer learning communities). Generalizability to community colleges, liberal arts institutions, international universities, or resource-constrained settings remains unvalidated. The time estimates, support requirements, and completion rates may differ substantially across institutional contexts. Multi-site deployment studies are needed to assess ecological validity. + +\textbf{Demand Characteristics.} Pilot participants aware they were testing novel curriculum may have exhibited Hawthorne effects---performing better due to observation rather than pedagogical effectiveness. Self-reported feedback (``dormant features felt intriguing,'' ``systems thinking became habitual'') may reflect demand characteristics or social desirability bias rather than genuine learning outcomes. Controlled studies with blinded assessments, objective performance measures, and delayed retention tests are necessary to mitigate these threats. + +\textbf{No Control Group.} Current pilot data lacks comparison to alternative pedagogical approaches. We cannot claim TinyTorch is ``more effective than X'' without controlled comparisons. Future research should compare learning outcomes between students completing TinyTorch versus traditional ML courses versus alternative frameworks (MiniTorch, micrograd) using matched samples, pre/post assessments, and transfer task performance. + +\textbf{Maturation and History Threats.} Students completing 20 modules over 14 weeks inevitably mature cognitively and gain experience from concurrent courses, internships, and self-study. Attribution of systems thinking development solely to TinyTorch (versus general skill development) requires careful experimental controls separating curriculum effects from maturation effects. + +\textbf{Assessment Validity.} NBGrader automated tests measure behavioral correctness (does code produce expected output?) but validity for measuring conceptual understanding remains unestablished. Students might pass tests through guess-and-check, copy-paste, or AI assistance without deep comprehension. Item analysis correlating test performance with transfer tasks, expert interviews assessing understanding depth, and think-aloud protocols revealing problem-solving strategies are needed to validate assessment quality. + +These threats do not invalidate TinyTorch as curriculum design---the implementation, pedagogical patterns, and theoretical grounding contribute independently of empirical validation. However, claims about learning effectiveness, cognitive load reduction, and transfer must remain tentative pending rigorous empirical evaluation addressing these validity concerns. + +\subsection{Future Work} +\label{subsec:future-work} + +TinyTorch's design enables multiple research and development trajectories maintaining pedagogical principles while extending capability. + +\subsubsection{Empirical Validation (Planned Fall 2025)} + +The most immediate priority involves deploying TinyTorch in university CS curricula and measuring learning outcomes through controlled comparison. \textbf{Planned Experimental Design.} Fall 2025 deployment comparing learning outcomes between traditional ML course (algorithm-focused, using PyTorch as black box) and TinyTorch course (systems-first, building frameworks). Pre/post assessments measuring: (1) systems thinking competency (memory profiling, complexity reasoning, optimization analysis), (2) framework comprehension (autograd mechanics, layer composition, training dynamics), (3) production readiness (debugging gradient flows, profiling performance, deployment decisions). @@ -759,18 +826,56 @@ Fall 2025 deployment comparing learning outcomes between traditional ML course ( \textbf{Timeline}: Fall 2025 deployment, preliminary results Spring 2026, full analysis published Summer 2026 (target: ICER 2026 or ACM TOCE). -\textbf{Assessment Instruments}: Currently developing validated measures for systems thinking competency, framework comprehension depth, and transfer task performance. Instruments will undergo expert review and pilot testing before deployment. +\subsubsection{GPU Awareness and Performance Modeling} + +While TinyTorch's CPU-only design prioritizes pedagogical transparency, students benefit from understanding GPU acceleration without implementing CUDA kernels. + +\textbf{Module 21: GPU Awareness (Planned).} +Students compare TinyTorch CPU implementations against PyTorch GPU equivalents, analyzing performance gaps through roofline models~\citep{williams2009roofline}. Rather than writing CUDA code, students profile existing implementations to understand memory hierarchy differences (CPU cache levels L1/L2/L3 versus GPU global/shared/register memory), parallelism benefits (sequential CPU loops versus massively parallel GPU execution with thousands of threads), roofline analysis techniques (plotting achieved performance against hardware limits to identify compute-bound versus memory-bound operations), and mixed precision advantages (profiling FP32 versus FP16 training speed/memory tradeoffs). Students run instrumented PyTorch code alongside TinyTorch implementations, measuring wall-clock time, memory usage, and FLOPs utilization. The roofline model visualization shows why GPUs excel at ML workloads: high arithmetic intensity operations (matrix multiplication) approach peak FLOPs, while memory-bound operations (element-wise activations) hit bandwidth limits. This \emph{awareness without implementation} maintains TinyTorch's accessibility while preparing students for GPU programming courses. + +\subsubsection{Distributed Training Fundamentals} + +Understanding distributed training communication patterns and scalability challenges requires simulation-based pedagogy, not multi-GPU hardware. + +\textbf{Module 22: Distributed Training Simulation (Planned).} +Students explore distributed training concepts through integration with ASTRA-sim~\citep{chakkaravarthy2023astrasim,astrasimsim2020}, a distributed ML training simulator. Rather than requiring 8-GPU clusters, students simulate multi-device training on single machines, exploring data parallelism basics (gradient synchronization via all-reduce across virtual workers, analyzing communication overhead versus compute time), scalability analysis (measuring weak versus strong scaling, identifying communication bottlenecks as worker count increases), network topology impact (comparing ring all-reduce, tree all-reduce, and hierarchical strategies through ASTRA-sim's topology modeling), and pipeline parallelism introduction (simulating model partitioning across devices, analyzing pipeline bubbles and micro-batching strategies). + +ASTRA-sim integration enables exploring research questions without hardware barriers. Students replicate findings from distributed training literature~\citep{astrasimsim2020}, experiencing how collective communication primitives (all-reduce, all-gather) dominate training time at scale. This simulation-based approach maintains TinyTorch's pedagogical principle: understanding systems through transparent implementation and measurement, not black-box hardware access. After completing Module 22, students understand why gradient synchronization limits distributed training scalability, how network bandwidth affects multi-node training, what communication patterns different parallelism strategies require, and when to apply data versus model versus pipeline parallelism based on model and hardware characteristics. + +\subsubsection{Advanced Curriculum Extensions} + +Maintaining modular structure, TinyTorch can incorporate emerging ML systems topics through community contributions: + +\textbf{Graph Neural Networks (Module 23)}: Message passing, graph convolutions, attention on graphs +\textbf{Diffusion Models (Module 24)}: Denoising architectures, forward/reverse processes, sampling strategies +\textbf{Reinforcement Learning (Module 25)}: Policy gradients, value functions, actor-critic methods + +These extensions follow established pedagogical patterns: systems-first integration (memory profiling, complexity analysis), historical milestone validation (seminal papers), and progressive disclosure (building on foundation tier). Community forks demonstrate this extensibility: quantum ML variants replace classical tensors with quantum state vectors, robotics variants add RL-specific infrastructure. + +\subsubsection{Learning Science Research} + +TinyTorch's design enables controlled studies of pedagogical questions in ML education: + +\textbf{Threshold Concepts}: Is autograd transformative (Meyer \& Land's criteria: troublesome, irreversible, integrative)? Do students exhibit conceptual breakthroughs or gradual understanding? + +\textbf{Productive Failure Limits}: When does struggle become unproductive? Can we identify engagement patterns (time-on-task, help-seeking behavior) predicting learning vs frustration? + +\textbf{Transfer Effectiveness}: Do TinyTorch skills improve PyTorch debugging? Measure via transfer tasks: given PyTorch code with gradient bugs, do TinyTorch students diagnose faster/more accurately than control group? + +\textbf{Long-term Retention}: Six months post-course, do students remember systems concepts (memory footprint calculation, complexity reasoning)? Compare concept maps, debugging protocols, optimization strategies. + +These studies require validated instruments, control groups, and longitudinal data collection---planned for post-deployment research program (2026--2027). \section{Conclusion} \label{sec:conclusion} Machine learning education faces a critical gap: students learn to \emph{use} ML frameworks but lack systems-level understanding needed to build, optimize, and deploy them in production. TinyTorch addresses this gap through a pedagogical framework \emph{designed to} transform framework users into systems engineers. -This paper makes five primary contributions. First, \textbf{progressive disclosure via monkey-patching} (\Cref{sec:progressive})---a novel pedagogical pattern where dormant features in the \texttt{Tensor} class activate across modules, enabling early interface exposure while managing cognitive load. Second, \textbf{systems-first integration} (\Cref{sec:systems}), where memory profiling, FLOPs analysis, and computational complexity are introduced from Module 01---not relegated to advanced electives. Third, a \textbf{4-phase curriculum architecture} (\Cref{sec:curriculum}) spanning 60--80 hours from tensor operations to production-ready CNNs. Fourth, \textbf{theoretical grounding} (\Cref{sec:related}) demonstrating how constructionism, productive failure, and threshold concepts guide design. Fifth, a \textbf{complete open-source artifact} enabling educator adoption and empirical evaluation. +This paper makes five primary contributions. First, \textbf{progressive disclosure via monkey-patching} (\Cref{sec:progressive})---a novel pedagogical pattern where dormant features in the \texttt{Tensor} class activate across modules, enabling early interface exposure while managing cognitive load. Second, \textbf{systems-first integration} (\Cref{sec:systems}), where memory profiling, FLOPs analysis, and computational complexity are introduced from Module 01---not relegated to advanced electives. Third, a \textbf{3-tier curriculum architecture plus competitive capstone} (\Cref{sec:curriculum}) spanning foundation, architectures, and optimization tiers, culminating in the Torch Olympics MLPerf-style competition. Fourth, \textbf{theoretical grounding} (\Cref{sec:related}) demonstrating how constructionism, productive failure, and threshold concepts guide design. Fifth, a \textbf{complete open-source artifact} enabling educator adoption and empirical evaluation. These contributions serve multiple audiences. CS educators gain replicable curriculum patterns worth empirical investigation. ML engineers obtain framework internals education potentially transferring to PyTorch/TensorFlow debugging. Industry trainers receive template for upskilling ML users into systems engineers. CS education researchers find novel pedagogical patterns worth studying empirically. -\textbf{Important scope note}: This represents a \textbf{design contribution}. Curriculum architecture, pedagogical patterns, and theoretical framework are provided; rigorous classroom evaluation with learning outcome measurements is planned for Fall 2025 (\Cref{subsec:future-eval}). Students completing TinyTorch's 20 modules should pursue GPU acceleration and distributed training through PyTorch tutorials, NVIDIA courses, or advanced modules (\Cref{subsubsec:gpu-omission})---TinyTorch provides internals foundation, not complete production ML preparation. +\textbf{Important scope note}: This represents a \textbf{design contribution}. Curriculum architecture, pedagogical patterns, and theoretical framework are provided; rigorous classroom evaluation with learning outcome measurements is planned for Fall 2025 (\Cref{subsec:future-work}). Students completing TinyTorch's 20 modules should pursue GPU acceleration and distributed training through PyTorch tutorials, NVIDIA courses, or advanced modules (\Cref{subsubsec:gpu-omission})---TinyTorch provides internals foundation, not complete production ML preparation. TinyTorch is not a replacement for production frameworks---it is a pedagogical bridge. Students completing the curriculum are expected to understand \emph{why} PyTorch manages GPU memory as it does, \emph{why} batch normalization layers have different train/eval modes, \emph{why} optimizers like Adam consume 3$\times$ parameter memory, and \emph{why} quantization trades 4$\times$ memory reduction for 1--2\% accuracy loss. This systems-level mental model is designed to transfer across frameworks and prepare graduates for ML engineering roles requiring optimization, debugging, and architectural decision-making. diff --git a/paper/references.bib b/paper/references.bib index 5de95a2a..b32c712b 100644 --- a/paper/references.bib +++ b/paper/references.bib @@ -145,6 +145,42 @@ publisher = {IEEE} } +@inproceedings{williams2009roofline, + author = {Williams, Samuel and Waterman, Andrew and Patterson, David}, + title = {Roofline: An insightful visual performance model for multicore architectures}, + booktitle = {Communications of the ACM}, + volume = {52}, + number = {4}, + pages = {65--76}, + year = {2009}, + publisher = {ACM} +} + +@inproceedings{astrasimsim2020, + author = {Samajdar, Ananda and Zhu, Yuhao and Whatmough, Paul and Mattina, Matthew and Krishna, Tushar}, + title = {A systematic methodology for characterizing scalability of DNN training algorithms}, + booktitle = {Proceedings of the International Symposium on Microarchitecture (MICRO)}, + pages = {1--14}, + year = {2020} +} + +@article{chakkaravarthy2023astrasim, + author = {Chakkaravarthy, William Won and Javanmard, Srinivas and Jain, Saeed Rashidi and Asghari-Moghaddam, Tushar Krishna}, + title = {ASTRA-sim: Enabling SW/HW co-design exploration for distributed deep learning platforms}, + journal = {IEEE Micro}, + volume = {43}, + number = {2}, + pages = {33--43}, + year = {2023} +} + +@article{kingma2014adam, + author = {Kingma, Diederik P. and Ba, Jimmy}, + title = {Adam: A method for stochastic optimization}, + journal = {arXiv preprint arXiv:1412.6980}, + year = {2014} +} + @article{vaswani2017attention, author = {Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, ลukasz and Polosukhin, Illia}, title = {Attention is all you need}, @@ -153,6 +189,76 @@ year = {2017} } +@article{reddi2020mlperf, + author = {Reddi, Vijay Janapa and Cheng, Christine and Kanter, David and Mattson, Peter and Schmuelling, Guenther and Wu, Carole-Jean and Anderson, Brian and Breughe, Maximilien and Charlebois, Mark and Chou, William and others}, + title = {MLPerf inference benchmark}, + journal = {arXiv preprint arXiv:1911.02549}, + year = {2020} +} + +@techreport{krizhevsky2009cifar, + author = {Krizhevsky, Alex and Hinton, Geoffrey}, + title = {Learning multiple layers of features from tiny images}, + institution = {University of Toronto}, + year = {2009} +} + +@article{sergeev2018horovod, + author = {Sergeev, Alexander and Del Balso, Mike}, + title = {Horovod: fast and easy distributed deep learning in TensorFlow}, + journal = {arXiv preprint arXiv:1802.05799}, + year = {2018} +} + +@inproceedings{rasley2020deepspeed, + author = {Rasley, Jeff and Rajbhandari, Samyam and Ruwase, Olatunji and He, Yuxiong}, + title = {DeepSpeed: System optimizations enable training deep learning models with over 100 billion parameters}, + booktitle = {Proceedings of the 26th ACM SIGKDD International Conference on Knowledge Discovery \& Data Mining}, + pages = {3505--3506}, + year = {2020} +} + +@article{chen2016training, + author = {Chen, Tianqi and Xu, Bing and Zhang, Chiyuan and Guestrin, Carlos}, + title = {Training deep nets with sublinear memory cost}, + journal = {arXiv preprint arXiv:1604.06174}, + year = {2016} +} + +@article{baydin2018automatic, + author = {Baydin, Atilim Gunes and Pearlmutter, Barak A. and Radul, Alexey Andreyevich and Siskind, Jeffrey Mark}, + title = {Automatic differentiation in machine learning: a survey}, + journal = {Journal of Machine Learning Research}, + volume = {18}, + number = {153}, + pages = {1--43}, + year = {2018} +} + +@inproceedings{chen2018tvm, + author = {Chen, Tianqi and Moreau, Thierry and Jiang, Ziheng and Zheng, Lianmin and Yan, Eddie and Shen, Haichen and Cowan, Meghan and Wang, Leyuan and Hu, Yuwei and Ceze, Luis and others}, + title = {TVM: An automated end-to-end optimizing compiler for deep learning}, + booktitle = {13th USENIX Symposium on Operating Systems Design and Implementation (OSDI 18)}, + pages = {578--594}, + year = {2018} +} + +@inproceedings{paszke2017automatic, + author = {Paszke, Adam and Gross, Sam and Chintala, Soumith and Chanan, Gregory and Yang, Edward and DeVito, Zachary and Lin, Zeming and Desmaison, Alban and Antiga, Luca and Lerer, Adam}, + title = {Automatic differentiation in PyTorch}, + booktitle = {NIPS 2017 Autodiff Workshop}, + year = {2017} +} + +@article{dao2022flashattention, + author = {Dao, Tri and Fu, Daniel Y. and Ermon, Stefano and Rudra, Atri and Rรฉ, Christopher}, + title = {FlashAttention: Fast and memory-efficient exact attention with IO-awareness}, + journal = {Advances in Neural Information Processing Systems}, + volume = {35}, + pages = {16344--16359}, + year = {2022} +} + @book{perkins1992transfer, author = {Perkins, David N. and Salomon, Gavriel}, title = {Transfer of learning}, diff --git a/site/_static/demos/03-export-tito.gif b/site/_static/demos/03-export-tito.gif index 4f63b06f..7cd76496 100644 --- a/site/_static/demos/03-export-tito.gif +++ b/site/_static/demos/03-export-tito.gif @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:e0aad021fe1593e0b94d21a4f6f68d66ccb06417644855e6d17c46819f0174f2 -size 128350 +oid sha256:5e67907907672de8fd4608d1a827d2b7394ad7062f91e0a38ff1cf95a78921d4 +size 197613 diff --git a/site/_toc.yml b/site/_toc.yml index 77f78cb1..963415a2 100644 --- a/site/_toc.yml +++ b/site/_toc.yml @@ -6,7 +6,7 @@ root: intro title: "TinyTorch Course" parts: -- caption: Getting Started +- caption: ๐Ÿš€ Getting Started chapters: - file: quickstart-guide title: "Quick Start Guide" @@ -77,7 +77,7 @@ parts: - file: modules/20_capstone_ABOUT title: "20. Torch Olympics" -- caption: Course Orientation +- caption: ๐Ÿงญ Course Orientation chapters: - file: chapters/00-introduction title: "Course Structure" @@ -90,16 +90,22 @@ parts: - file: faq title: "FAQ" -- caption: Using TinyTorch +- caption: ๐Ÿ› ๏ธ TITO CLI Reference chapters: - - file: tito-essentials - title: "Essential Commands" + - file: tito/overview + title: "Command Overview" + - file: tito/modules + title: "Module Workflow" + - file: tito/milestones + title: "Milestone System" + - file: tito/data + title: "Progress & Data" + - file: tito/troubleshooting + title: "Troubleshooting" - file: datasets title: "Datasets Guide" - - file: testing-framework - title: "Testing Guide" -- caption: Community +- caption: ๐Ÿค Community chapters: - file: community title: "Ecosystem" diff --git a/site/quickstart-guide.md b/site/quickstart-guide.md index c1cd486a..3de20ebc 100644 --- a/site/quickstart-guide.md +++ b/site/quickstart-guide.md @@ -32,7 +32,7 @@ source activate.sh - Configures TinyTorch in development mode - Verifies installation -See [Essential Commands](tito-essentials.md) for detailed workflow and troubleshooting. +See [TITO CLI Reference](tito/overview.md) for detailed workflow and troubleshooting. @@ -46,7 +46,7 @@ tito system doctor You should see all green checkmarks. This confirms your environment is ready for hands-on ML systems building. -See [Essential Commands](tito-essentials.md) for verification commands and troubleshooting. +See [Module Workflow](tito/modules.md) for detailed commands and [Troubleshooting](tito/troubleshooting.md) if needed. @@ -214,8 +214,7 @@ In 15 minutes, you've: **Master the Workflow:** - See [Student Workflow](student-workflow.md) for the complete edit โ†’ export โ†’ validate cycle -- See [Essential Commands](tito-essentials.md) for complete TITO command reference -- See [Student Workflow](student-workflow.md) for the complete development cycle +- See [TITO CLI Reference](tito/overview.md) for complete command reference **For Instructors:** - See [Classroom Setup Guide](usage-paths/classroom-use.md) for [NBGrader](https://nbgrader.readthedocs.io/) integration (coming soon) @@ -241,7 +240,7 @@ See [Student Workflow](student-workflow.md) for detailed workflow guide and best

Ready to Build Production ML Systems

You've proven you can build ML components from scratch. Time to keep going!

Continue Building โ†’ -Master Commands โ†’ +TITO CLI Reference โ†’ --- diff --git a/site/student-workflow.md b/site/student-workflow.md index d8b14c3c..b9ee38a7 100644 --- a/site/student-workflow.md +++ b/site/student-workflow.md @@ -137,7 +137,7 @@ tito checkpoint status tito system info ``` -For complete command documentation, see [TITO Essentials](tito-essentials.md). +For complete command documentation, see [TITO CLI Reference](tito/overview.md). ## Checkpoint System (Optional) diff --git a/site/testing-framework.md b/site/testing-framework.md deleted file mode 100644 index 28fd9829..00000000 --- a/site/testing-framework.md +++ /dev/null @@ -1,383 +0,0 @@ -# Testing Framework - -```{admonition} Test-Driven ML Engineering -:class: tip -TinyTorch's testing framework ensures your implementations are not just educational, but production-ready and reliable. -``` - -## Testing Philosophy: Verify Understanding Through Implementation - -TinyTorch testing goes beyond checking syntax - it validates that you understand ML systems engineering through working implementations. - -## Quick Start: Validate Your Implementation - -### Run Everything (Recommended) -```bash -# Complete validation suite -tito test --comprehensive - -# Expected output: -# ๐Ÿงช Running 16 module tests... -# ๐Ÿ”— Running integration tests... -# ๐Ÿ“Š Running performance benchmarks... -# โœ… Overall TinyTorch Health: 100.0% -``` - -### Target-Specific Testing -```bash -# Test what you just built -tito module complete 02_tensor && tito checkpoint test 01 - -# Quick module check -tito test --module attention --verbose - -# Performance validation -tito test --performance --module training -``` - -## Testing Levels: From Components to Systems - -### 1. Module-Level Testing -**Goal**: Verify individual components work correctly in isolation - -```bash -# Test what you just implemented -tito test --module tensor --verbose -tito test --module attention --detailed - -# Quick health check for specific module -tito module validate spatial - -# Debug failing module -tito test --module autograd --debug -``` - -**What Gets Tested:** -- โœ… Core functionality (forward pass, backward pass) -- โœ… Memory usage patterns and leaks -- โœ… Mathematical correctness vs reference implementations -- โœ… Edge cases and error handling - -### 2. ๐Ÿ”— Integration Testing -**Goal**: Ensure modules work together seamlessly - -```bash -# Test module dependencies -tito test --integration --focus training - -# Validate export/import chain -tito test --exports --all-modules - -# Full pipeline validation -tito test --pipeline --from tensor --to training -``` - -**Integration Scenarios:** -- **Tensor โ†’ Autograd**: Gradient flow works correctly -- **Spatial โ†’ Training**: CNN training pipeline functions end-to-end -- **Attention โ†’ TinyGPT**: Transformer components integrate properly -- **All Modules**: Complete framework functionality - -### 3. ๐Ÿ† Checkpoint Testing -**Goal**: Validate you've achieved specific learning capabilities - -```bash -# Test your current capabilities -tito checkpoint test 01 # "Can I create and manipulate tensors?" -tito checkpoint test 08 # "Can I train neural networks end-to-end?" -tito checkpoint test 13 # "Can I build attention mechanisms?" - -# Progressive capability validation -tito checkpoint validate --from 00 --to 15 -``` - -See [Student Workflow](student-workflow.md) for the complete development cycle and testing integration. - -**Key Capability Categories:** -- **Foundation (00-03)**: Building blocks of neural networks -- **Training (04-08)**: End-to-end learning systems -- **Architecture (09-14)**: Advanced model architectures -- **Optimization (15+)**: Production-ready systems - -### 4. ๐Ÿ“Š Performance & Systems Testing -**Goal**: Verify your implementation meets performance expectations - -```bash -# Memory usage analysis -tito test --memory --module training --profile - -# Speed benchmarking -tito test --speed --compare-baseline - -# Scaling behavior validation -tito test --scaling --model-sizes 1M,5M,10M -``` - -**Performance Metrics:** -- **Memory efficiency**: Peak usage, gradient memory, batch scaling -- **Training speed**: Convergence time, throughput (samples/sec) -- **Inference latency**: Forward pass time, batch processing efficiency -- **Scaling behavior**: Performance vs model size, memory vs accuracy trade-offs - -### 5. ๐ŸŒ Real-World Example Validation -**Goal**: Demonstrate production-ready functionality - -```bash -# Train actual models -tito example train-mnist-mlp # 95%+ accuracy target -tito example train-cifar-cnn # 75%+ accuracy target -tito example generate-text # TinyGPT coherent generation - -# Production scenarios -tito example benchmark-inference # Speed/memory competitive analysis -tito example deploy-edge # Resource-constrained deployment -``` - -## ๐Ÿ—๏ธ Test Architecture: Systems Engineering Approach - -### ๐Ÿ“‹ Progressive Testing Pattern -Every TinyTorch module follows consistent testing standards: - -```python -# Module testing template (every module follows this pattern) -class ModuleTest: - def test_core_functionality(self): # Basic operations work - def test_mathematical_correctness(self): # Matches reference implementations - def test_memory_usage(self): # No memory leaks, efficient usage - def test_integration_ready(self): # Exports correctly for other modules - def test_real_world_usage(self): # Works in actual ML pipelines -``` - -### ๐Ÿ“ Test Organization Structure -```bash -tests/ -โ”œโ”€โ”€ checkpoints/ # 16 capability validation tests -โ”‚ โ”œโ”€โ”€ checkpoint_00_environment.py # Development setup working -โ”‚ โ”œโ”€โ”€ checkpoint_01_foundation.py # Tensor operations mastered -โ”‚ โ””โ”€โ”€ checkpoint_15_capstone.py # Complete ML systems expertise -โ”œโ”€โ”€ integration/ # Cross-module compatibility -โ”‚ โ”œโ”€โ”€ test_training_pipeline.py # End-to-end training works -โ”‚ โ””โ”€โ”€ test_module_exports.py # All modules export correctly -โ”œโ”€โ”€ performance/ # Systems performance validation -โ”‚ โ”œโ”€โ”€ memory_profiling.py # Memory usage analysis -โ”‚ โ””โ”€โ”€ speed_benchmarks.py # Computational performance -โ””โ”€โ”€ examples/ # Real-world usage validation - โ”œโ”€โ”€ test_mnist_training.py # Actual MNIST training works - โ””โ”€โ”€ test_cifar_cnn.py # CNN achieves 75%+ on CIFAR-10 -``` - -## ๐Ÿ“Š Understanding Test Results - -### ๐ŸŽฏ Health Status Interpretation -| Score | Status | Action Required | -|-------|--------|----------------| -| **100%** | ๐ŸŸข Excellent | All systems operational, ready for production | -| **95-99%** | ๐ŸŸก Good | Minor issues, investigate warnings | -| **90-94%** | ๐ŸŸ  Caution | Some failing tests, address specific modules | -| **<90%** | ๐Ÿ”ด Issues | Significant problems, requires immediate attention | - -### ๐Ÿšฆ Module Status Indicators -- โœ… **Passing**: Module implemented correctly, all tests green -- โš ๏ธ **Warning**: Minor issues detected, functionality mostly intact -- โŒ **Failing**: Critical errors, module needs debugging -- ๐Ÿšง **In Progress**: Module under development, tests expected to fail -- ๐ŸŽฏ **Checkpoint Ready**: Module ready for capability testing - -## ๐Ÿ’ก Best Practices: Test-Driven ML Engineering - -### ๐Ÿ”„ During Active Development -```bash -# Continuous validation workflow -tito test --module tensor # After implementing core functionality -tito test --integration tensor # After module completion -tito checkpoint test 01 # After achieving milestone -``` - -**Development Testing Pattern:** -1. **Write minimal test first**: Define expected behavior before implementation -2. **Test each component**: Validate individual functions as you build them -3. **Integration early**: Test module interactions frequently, not just at the end -4. **Performance check**: Monitor memory and speed throughout development - -### โœ… Before Code Commits -```bash -# Pre-commit validation checklist -tito test --comprehensive # Full test suite passes -tito system doctor # Environment is healthy -tito checkpoint status # All achieved capabilities still work -``` - -**Commit Readiness Criteria:** -- โœ… All tests pass (100% health status) -- โœ… No memory leaks detected in performance tests -- โœ… Integration tests confirm module exports work -- โœ… Checkpoint tests validate learning objectives met - -### ๐ŸŽฏ Before Module Completion -```bash -# Module completion validation -tito test --module mymodule --comprehensive -tito test --integration --focus mymodule -tito module validate mymodule -tito module complete mymodule # Only after all tests pass -``` - -## ๐Ÿ”ง Troubleshooting Guide - -### ๐Ÿšจ Common Test Failures & Solutions - -#### Module Import Errors -```bash -# Problem: Module won't import -โŒ ModuleNotFoundError: No module named 'tinytorch.core.tensor' - -# Solution: Check module export -tito module complete tensor # Ensure module is properly exported -tito system doctor # Verify Python path and virtual environment -``` - -#### Mathematical Correctness Failures -```bash -# Problem: Your implementation doesn't match reference -โŒ AssertionError: Expected 0.5, got 0.48 (tolerance: 0.01) - -# Debug process: -tito test --module tensor --debug # Get detailed failure info -python -c "import tinytorch; help(tinytorch.tensor)" # Check implementation -``` - -#### Memory Usage Issues -```bash -# Problem: Memory tests failing -โŒ Memory usage: 150MB (expected: <100MB) - -# Investigation: -tito test --memory --profile tensor # Get memory profile -tito test --scaling --module tensor # Check scaling behavior -``` - -#### Integration Test Failures -```bash -# Problem: Modules don't work together -โŒ Integration test: tensorโ†’autograd failed - -# Debugging approach: -tito test --integration --focus autograd --verbose -tito test --exports tensor # Check tensor exports correctly -tito test --imports autograd # Check autograd imports correctly -``` - -### ๐Ÿ” Advanced Debugging Techniques - -#### Verbose Test Output -```bash -# Get detailed test information -tito test --module attention --verbose --debug - -# See exact error locations -tito test --traceback --module training -``` - -#### Performance Profiling -```bash -# Memory usage analysis -tito test --memory --profile --module spatial - -# Speed profiling -tito test --speed --profile --module training --iterations 100 -``` - -#### Environment Validation -```bash -# Complete environment check -tito system doctor --comprehensive - -# Specific dependency verification -tito system check-dependencies --module autograd -``` - -### ๐Ÿ“‹ Test Failure Decision Tree - -``` -Test Failed? -โ”œโ”€โ”€ Import Error? -โ”‚ โ”œโ”€โ”€ Run `tito system doctor` -โ”‚ โ””โ”€โ”€ Check virtual environment activation -โ”œโ”€โ”€ Mathematical Error? -โ”‚ โ”œโ”€โ”€ Compare with reference implementation -โ”‚ โ””โ”€โ”€ Check tensor shapes and dtypes -โ”œโ”€โ”€ Memory Error? -โ”‚ โ”œโ”€โ”€ Profile memory usage patterns -โ”‚ โ””โ”€โ”€ Check for memory leaks in loops -โ”œโ”€โ”€ Integration Error? -โ”‚ โ”œโ”€โ”€ Test modules individually first -โ”‚ โ””โ”€โ”€ Verify export/import chain -โ””โ”€โ”€ Performance Error? - โ”œโ”€โ”€ Profile bottlenecks - โ””โ”€โ”€ Check algorithmic complexity -``` - -## ๐ŸŽฏ Testing Philosophy: Building Reliable ML Systems - -The TinyTorch testing framework embodies professional ML engineering principles: - -### ๐Ÿงฉ KISS Principle in Testing -- **Consistent patterns**: Every module follows identical testing structure - learn once, apply everywhere -- **Actionable feedback**: Tests provide specific error messages with exact fix suggestions -- **Essential focus**: Tests validate critical functionality without unnecessary complexity - -### ๐Ÿ”— Systems Engineering Mindset -- **Integration-first**: Tests verify components work together, not just in isolation -- **Real-world validation**: Examples prove your code works on actual datasets (CIFAR-10, MNIST) -- **Performance consciousness**: All tests include memory and speed awareness - -### ๐Ÿ“š Educational Excellence -- **Understanding verification**: Tests confirm you grasp concepts, not just syntax -- **Progressive mastery**: Capabilities build systematically through checkpoint validation -- **Immediate feedback**: Know instantly if your implementation meets professional standards - -### ๐Ÿš€ Production Readiness -- **Professional standards**: Tests match industry-level validation practices -- **Scalability validation**: Ensure your code works at realistic data sizes -- **Reliability assurance**: Comprehensive testing prevents production failures - ---- - -## ๐Ÿ† Success Metrics - -```{admonition} Testing Success -:class: tip -A well-tested TinyTorch implementation should achieve: -- **100% test suite passing** - All functionality works correctly -- **>95% memory efficiency** - Comparable to reference implementations -- **Real dataset success** - MNIST 95%+, CIFAR-10 75%+ accuracy targets -- **Clean integration** - All modules work together seamlessly -``` - -**Remember**: TinyTorch testing doesn't just verify your code works - it confirms you understand ML systems engineering well enough to build production-ready implementations. - -Your testing discipline here translates directly to building reliable ML systems in industry settings! - -## ๐Ÿš€ Next Steps - -**Ready to start testing your implementations?** - -```bash -# Begin with comprehensive health check -tito test --comprehensive - -# Start building and testing your first module -tito module complete 01_setup - -# Track your testing progress -tito checkpoint status -``` - -**Testing Integration with Your Learning Path:** -- See [Student Workflow](student-workflow.md) for how testing fits into the development cycle -- **๐Ÿ“– See [Historical Milestones](chapters/milestones.md)** for how testing validates achievements - -
-

๐ŸŽฏ Testing Excellence = ML Systems Mastery

-

Every test you write and run builds the discipline needed for production ML engineering

-
\ No newline at end of file diff --git a/site/tito-essentials.md b/site/tito-essentials.md deleted file mode 100644 index be23f8aa..00000000 --- a/site/tito-essentials.md +++ /dev/null @@ -1,192 +0,0 @@ -# Essential TITO Commands - -
-

Master the TinyTorch CLI in Minutes

-

Everything you need to build ML systems efficiently

-
- -**Purpose**: Complete command reference for the TITO CLI. Master the essential commands for development workflow, progress tracking, and system management. - -## The Core Workflow - -TinyTorch follows a simple three-step cycle: **Edit modules โ†’ Export to package โ†’ Validate with milestones** - -**The essential command**: `tito module complete MODULE_NUMBER` - exports your code to the TinyTorch package. - -See [Student Workflow](student-workflow.md) for the complete development cycle, best practices, and troubleshooting. - -This page documents all available TITO commands. The checkpoint system (`tito checkpoint status`) is optional for progress tracking. - -## Most Important Commands - -The commands you'll use most often: - -
- -
-

Check Your Environment

-tito system doctor -

Verify your setup is ready for development

-
- -
-

Export Module to Package (Essential)

-tito module complete 01 -

Export your module to the TinyTorch package - use this after editing modules

-
- -
-

Track Your Progress (Optional)

-tito checkpoint status -

See which capabilities you've mastered (optional capability tracking)

-
- -
- -## Typical Development Session - -Here's what a typical session looks like: - -
- -**Edit modules:** -```bash -cd modules/source/03_layers -jupyter lab 03_layers_dev.py -# Make your implementation... -``` - -**Export to package:** -```bash -# From repository root -tito module complete 03 -``` - -**Validate with milestones:** -```bash -cd milestones/01_1957_perceptron -python 01_rosenblatt_forward.py # Uses YOUR implementation! -``` - -**Optional progress tracking:** -```bash -tito checkpoint status # See what you've completed -``` - -See [Student Workflow](student-workflow.md) for complete development cycle details. - -
- -## Complete Command Reference - -### System & Health -
- -**System Check** -```bash -tito system doctor -``` -*Diagnose environment issues before they block you* - -**System Info** -```bash -tito system info -``` -*View configuration details* - -
- -### Module Management -
- -**Export Module to Package (Essential)** -```bash -tito module complete MODULE_NUMBER -``` -*Export your implementation to the TinyTorch package - the key command in the workflow* - -**Example:** -```bash -tito module complete 05 # Export Module 05 (Autograd) -``` - -After exporting, your code is importable: -```python -from tinytorch.autograd import backward # YOUR implementation! -``` - -
- -### Progress Tracking (Optional) -
- -**Capability Overview** -```bash -tito checkpoint status -``` -*Quick view of your capabilities (optional tracking)* - -**Detailed Progress** -```bash -tito checkpoint status --detailed -``` -*Module-by-module breakdown* - -**Visual Timeline** -```bash -tito checkpoint timeline -``` -*See your learning journey in visual format* - -**Test Specific Capability** -```bash -tito checkpoint test CHECKPOINT_NUMBER -``` -*Verify you've mastered a specific capability* - -
- -## Instructor Commands (Coming Soon) - -
- -TinyTorch includes NBGrader integration for classroom use. Full documentation for instructor workflows (assignment generation, autograding, etc.) will be available in future releases. - -**For now, focus on the student workflow**: edit modules โ†’ export โ†’ validate with milestones. - -*For current instructor capabilities, see [Classroom Use Guide](usage-paths/classroom-use.md)* - -
- -## Troubleshooting Commands - -When things go wrong, these commands help: - -
- -**Environment Issues:** -```bash -tito system doctor # Diagnose problems -tito system info # Show configuration details -``` - -**Progress Tracking (Optional):** -```bash -tito checkpoint status --detailed # See exactly where you are -tito checkpoint timeline # Visualize your progress -``` - -
- -## Ready to Build? - -
-

Start Your TinyTorch Journey

-

Follow the 2-minute setup and begin building ML systems from scratch

-2-Minute Setup โ†’ -Student Workflow โ†’ -
- ---- - -*Master these commands and you'll build ML systems with confidence. Every command is designed to accelerate your learning and keep you focused on what matters: building production-quality ML frameworks from scratch.* diff --git a/site/tito/data.md b/site/tito/data.md new file mode 100644 index 00000000..92ecd513 --- /dev/null +++ b/site/tito/data.md @@ -0,0 +1,581 @@ +# Progress & Data Management + +
+

Track Your Journey

+

Understanding progress tracking, data management, and reset commands

+
+ +**Purpose**: Learn how TinyTorch tracks your progress, where your data lives, and how to manage it effectively. + +## Your Learning Journey: Two Tracking Systems + +TinyTorch uses a clean, simple approach to track your ML systems engineering journey: + +```{mermaid} +graph LR + A[Build Modules] --> B[Complete 01-20] + B --> C[Export to Package] + C --> D[Unlock Milestones] + D --> E[Achieve 1957-2018] + E --> F[Track Progress] + + style A fill:#e3f2fd + style B fill:#fffbeb + style C fill:#f0fdf4 + style D fill:#fef3c7 + style E fill:#f3e5f5 + style F fill:#e8eaf6 +``` + +### The Two Systems + +
+ +
+

๐Ÿ“ฆ Module Progress

+

What you BUILD (01-20)

+ +
+ +
+

๐Ÿ† Milestone Achievements

+

What you ACHIEVE (01-06)

+ +
+ +
+ +**Simple relationship**: +- Complete modules โ†’ Unlock milestones โ†’ Achieve historical ML recreations +- Build capabilities โ†’ Validate with history โ†’ Track achievements + +--- + +## Where Your Data Lives + +All your progress is stored in the `.tito/` folder: + +``` +TinyTorch/ +โ”œโ”€โ”€ .tito/ โ† Your progress data +โ”‚ โ”œโ”€โ”€ config.json โ† User preferences +โ”‚ โ”œโ”€โ”€ progress.json โ† Module completion (01-20) +โ”‚ โ”œโ”€โ”€ milestones.json โ† Milestone achievements (01-06) +โ”‚ โ””โ”€โ”€ backups/ โ† Automatic safety backups +โ”‚ โ”œโ”€โ”€ 01_tensor_YYYYMMDD_HHMMSS.py +โ”‚ โ”œโ”€โ”€ 02_activations_YYYYMMDD_HHMMSS.py +โ”‚ โ””โ”€โ”€ ... +โ”œโ”€โ”€ modules/ โ† Where you edit +โ”œโ”€โ”€ tinytorch/ โ† Where code exports +โ””โ”€โ”€ ... +``` + +### Understanding Each File + +
+ +**`config.json`** - User Preferences +```json +{ + "logo_theme": "standard" +} +``` +- UI preferences +- Display settings +- Personal configuration + +**`progress.json`** - Module Completion +```json +{ + "version": "1.0", + "completed_modules": [1, 2, 3, 4, 5, 6, 7], + "completion_dates": { + "1": "2025-11-16T10:00:00", + "2": "2025-11-16T11:00:00", + ... + } +} +``` +- Tracks which modules (01-20) you've completed +- Records when you completed each +- Updated by `tito module complete XX` + +**`milestones.json`** - Milestone Achievements +```json +{ + "version": "1.0", + "completed_milestones": ["03"], + "completion_dates": { + "03": "2025-11-16T15:00:00" + } +} +``` +- Tracks which milestones (01-06) you've achieved +- Records when you achieved each +- Updated by `tito milestone run XX` + +**`backups/`** - Module Backups +- Automatic backups before operations +- Timestamped copies of your work +- Safety net for module development + +
+ +--- + +## Unified Progress View + +### See Everything: `tito status` + +
+ +```bash +tito status +``` + +**Shows your complete learning journey in one view**: + +``` +โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ๐Ÿ“Š TinyTorch Progress โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ โ”‚ +โ”‚ ๐Ÿ“ฆ Modules Completed: 7/20 (35%) โ”‚ +โ”‚ ๐Ÿ† Milestones Achieved: 1/6 (17%) โ”‚ +โ”‚ ๐Ÿ“ Last Activity: Module 07 (2 hours ago) โ”‚ +โ”‚ โ”‚ +โ”‚ Next Steps: โ”‚ +โ”‚ โ€ข Complete modules 08-09 to unlock Milestone 04 โ”‚ +โ”‚ โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + +Module Progress: + โœ… 01 Tensor + โœ… 02 Activations + โœ… 03 Layers + โœ… 04 Losses + โœ… 05 Autograd + โœ… 06 Optimizers + โœ… 07 Training + ๐Ÿ”’ 08 DataLoader + ๐Ÿ”’ 09 Convolutions + ๐Ÿ”’ 10 Normalization + ... + +Milestone Achievements: + โœ… 03 - MLP Revival (1986) + ๐ŸŽฏ 04 - CNN Revolution (1998) [Ready after modules 08-09] + ๐Ÿ”’ 05 - Transformer Era (2017) + ๐Ÿ”’ 06 - MLPerf (2018) +``` + +**Use this to**: +- Check overall progress +- See next recommended steps +- Understand milestone prerequisites +- Track your learning journey + +
+ +--- + +## Data Management Commands + +### Reset Your Progress + +
+ +**Starting fresh?** Reset commands let you start over cleanly. + +#### Reset Everything + +```bash +tito reset all +``` + +**What this does**: +- Clears all module completion +- Clears all milestone achievements +- Resets configuration to defaults +- Keeps your code in `modules/` safe +- Asks for confirmation before proceeding + +**Example output**: +``` +โš ๏ธ Warning: This will reset ALL progress + +This will clear: + โ€ข Module completion (7 modules) + โ€ข Milestone achievements (1 milestone) + โ€ข Configuration settings + +Your code in modules/ will NOT be deleted. + +Continue? [y/N]: y + +โœ… Creating backup at .tito_backup_20251116_143000/ +โœ… Clearing module progress +โœ… Clearing milestone achievements +โœ… Resetting configuration + +๐Ÿ”„ Reset Complete! + +You're ready to start fresh. +Run: tito module start 01 +``` + +#### Reset Module Progress Only + +```bash +tito reset progress +``` + +**What this does**: +- Clears module completion tracking only +- Keeps milestone achievements +- Keeps configuration +- Useful for re-doing module workflow + +#### Reset Milestone Achievements Only + +```bash +tito reset milestones +``` + +**What this does**: +- Clears milestone achievements only +- Keeps module completion +- Keeps configuration +- Useful for re-running historical recreations + +#### Safety: Automatic Backups + +```bash +# Create backup before reset +tito reset all --backup +``` + +**What this does**: +- Creates timestamped backup: `.tito_backup_YYYYMMDD_HHMMSS/` +- Contains complete copy of `.tito/` folder +- Allows manual restore if needed +- Automatic before any destructive operation + +
+ +--- + +## Data Safety & Recovery + +### Automatic Backups + +TinyTorch automatically backs up your work: + +
+ +**When backups happen**: +1. **Before module start**: Backs up existing work +2. **Before reset**: Creates full `.tito/` backup +3. **Before module reset**: Saves current implementation + +**Where backups go**: +``` +.tito/backups/ +โ”œโ”€โ”€ 01_tensor_20251116_100000.py +โ”œโ”€โ”€ 01_tensor_20251116_143000.py +โ”œโ”€โ”€ 03_layers_20251115_180000.py +โ””โ”€โ”€ ... +``` + +**How to use backups**: +```bash +# Backups are timestamped - find the one you need +ls -la .tito/backups/ + +# Manually restore if needed +cp .tito/backups/03_layers_20251115_180000.py modules/03_layers/layers_dev.py +``` + +
+ +### What If .tito/ Is Deleted? + +
+ +**No problem!** TinyTorch recovers gracefully: + +```bash +# If .tito/ is deleted, next command recreates it +tito system doctor +``` + +**What happens**: +1. TinyTorch detects missing `.tito/` folder +2. Creates fresh folder structure +3. Initializes empty progress tracking +4. Your code in `modules/` and `tinytorch/` is safe +5. You can continue from where you left off + +**Important**: Your actual code (in `modules/` and `tinytorch/`) is separate from progress tracking (in `.tito/`). Deleting `.tito/` only resets progress tracking, not your implementations. + +
+ +--- + +## Data Health Checks + +### Verify Data Integrity + +
+ +```bash +tito system doctor +``` + +**Now includes data health checks**: + +``` +โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ๐Ÿ” TinyTorch System Check โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ +โ”‚ โ”‚ +โ”‚ โœ… Environment setup โ”‚ +โ”‚ โœ… Dependencies installed โ”‚ +โ”‚ โœ… TinyTorch in development mode โ”‚ +โ”‚ โœ… Data files intact โ”‚ +โ”‚ โœ“ .tito/progress.json valid โ”‚ +โ”‚ โœ“ .tito/milestones.json valid โ”‚ +โ”‚ โœ“ .tito/config.json valid โ”‚ +โ”‚ โœ… Backups directory exists โ”‚ +โ”‚ โ”‚ +โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ + +All systems ready! ๐Ÿš€ +``` + +**If data is corrupted**: +``` +โŒ Data files corrupted + โœ— .tito/progress.json is malformed + +Fix: + tito reset progress + +Or restore from backup: + cp .tito_backup_YYYYMMDD/.tito/progress.json .tito/ +``` + +
+ +--- + +## Best Practices + +### Regular Progress Checks + +
+ +**Good habits**: + +1. **Check status regularly**: + ```bash + tito status + ``` + See where you are, what's next + +2. **Verify environment before work**: + ```bash + tito system doctor + ``` + Catch issues early + +3. **Let automatic backups work**: + - Don't disable them + - They're your safety net + - Cleanup happens automatically + +4. **Backup before experiments**: + ```bash + tito reset all --backup # If trying something risky + ``` + +5. **Version control for code**: + ```bash + git commit -m "Completed Module 05: Autograd" + ``` + `.tito/` is gitignored - use git for code versions + +
+ +--- + +## Understanding What Gets Tracked + +### Modules (Build Progress) + +**Tracked when**: You run `tito module complete XX` + +**What's recorded**: +- Module number (1-20) +- Completion timestamp +- Test results (passed/failed) + +**Visible in**: +- `tito module status` +- `tito status` +- `.tito/progress.json` + +### Milestones (Achievement Progress) + +**Tracked when**: You run `tito milestone run XX` + +**What's recorded**: +- Milestone ID (01-06) +- Achievement timestamp +- Number of attempts (if multiple runs) + +**Visible in**: +- `tito milestone status` +- `tito status` +- `.tito/milestones.json` + +### What's NOT Tracked + +
+ +**TinyTorch does NOT track**: +- Your actual code implementations (those live in `modules/` and `tinytorch/`) +- How long you spent on each module +- How many times you edited files +- Your test scores or grades +- Personal information +- Usage analytics + +**Why**: TinyTorch is a local, offline learning tool. Your privacy is protected. All data stays on your machine. + +
+ +--- + +## Common Data Scenarios + +### Scenario 1: "I want to start completely fresh" + +
+ +```bash +# Create backup first (recommended) +tito reset all --backup + +# Or just reset +tito reset all + +# Start from Module 01 +tito module start 01 +``` + +**Result**: Clean slate, progress tracking reset, code in `modules/` untouched + +
+ +### Scenario 2: "I want to re-run milestones but keep module progress" + +
+ +```bash +# Reset only milestone achievements +tito reset milestones + +# Re-run historical recreations +tito milestone run 03 +tito milestone run 04 +``` + +**Result**: Module completion preserved, milestone achievements reset + +
+ +### Scenario 3: "I accidentally deleted .tito/" + +
+ +```bash +# Just run any tito command +tito system doctor + +# OR + +# If you have a backup +cp -r .tito_backup_YYYYMMDD/ .tito/ +``` + +**Result**: `.tito/` folder recreated, either fresh or from backup + +
+ +### Scenario 4: "I want to share my progress with a friend" + +
+ +```bash +# Create backup with timestamp +tito reset all --backup # (then cancel when prompted) + +# Share the backup folder +cp -r .tito_backup_YYYYMMDD/ ~/Desktop/my-tinytorch-progress/ +``` + +**Result**: Friend can see your progress by copying to their `.tito/` folder + +
+ +--- + +## FAQ + +### Q: Will resetting delete my code? + +**A**: No! Reset commands only affect progress tracking in `.tito/`. Your implementations in `modules/` and exported code in `tinytorch/` are never touched. + +### Q: Can I manually edit progress.json? + +**A**: Yes, but not recommended. Use `tito` commands instead. Manual edits might break validation. + +### Q: What if I want to re-export a module? + +**A**: Just run `tito module complete XX` again. It will re-run tests and re-export. Progress tracking remains unchanged. + +### Q: How do I see my completion dates? + +**A**: Run `tito status` for a formatted view, or check `.tito/progress.json` and `.tito/milestones.json` directly. + +### Q: Can I delete backups? + +**A**: Yes, backups in `.tito/backups/` can be deleted manually. They're safety nets, not requirements. + +### Q: Is my data shared anywhere? + +**A**: No. TinyTorch is completely local. No data leaves your machine. No tracking, no analytics, no cloud sync. + +--- + +## Next Steps + +
+

Keep Building!

+

Now that you understand data management, focus on what matters: building ML systems

+Module Workflow โ†’ +Milestone System โ†’ +
+ +--- + +*Your progress is tracked, your data is safe, and your journey is yours. TinyTorch keeps track of what you've built and achieved - you focus on learning ML systems engineering.* diff --git a/site/tito/milestones.md b/site/tito/milestones.md new file mode 100644 index 00000000..ae5ba60d --- /dev/null +++ b/site/tito/milestones.md @@ -0,0 +1,449 @@ +# Milestone System + +
+

Recreate ML History with YOUR Code

+

Run the algorithms that changed the world using the TinyTorch you built from scratch

+
+ +**Purpose**: The milestone system lets you run famous ML algorithms (1957-2018) using YOUR implementations. Every milestone validates that your code can recreate a historical breakthrough. + +See [Historical Milestones](chapters/milestones.md) for the full historical context and significance of each milestone. + +## What Are Milestones? + +Milestones are **runnable recreations of historical ML papers** that use YOUR TinyTorch implementations: + +- **1957 - Rosenblatt's Perceptron**: The first trainable neural network +- **1969 - XOR Solution**: Solving the problem that stalled AI +- **1986 - Backpropagation**: The MLP revival (Rumelhart, Hinton & Williams) +- **1998 - LeNet**: Yann LeCun's CNN breakthrough +- **2017 - Transformer**: "Attention is All You Need" (Vaswani et al.) +- **2018 - MLPerf**: Production ML benchmarks + +Each milestone script imports **YOUR code** from the TinyTorch package you built. + +## Quick Start + +
+ +**Typical workflow:** + +```bash +# 1. Build the required modules (e.g., Foundation Tier for Milestone 03) +tito module complete 01 # Tensor +tito module complete 02 # Activations +tito module complete 03 # Layers +tito module complete 04 # Losses +tito module complete 05 # Autograd +tito module complete 06 # Optimizers +tito module complete 07 # Training + +# 2. See what milestones you can run +tito milestone list + +# 3. Get details about a specific milestone +tito milestone info 03 + +# 4. Run it! +tito milestone run 03 +``` + +
+ +## Essential Commands + +### Discover Milestones + +
+ +**List All Milestones** +```bash +tito milestone list +``` + +Shows all 6 historical milestones with status: +- ๐Ÿ”’ **LOCKED** - Need to complete required modules first +- ๐ŸŽฏ **READY TO RUN** - All prerequisites met! +- โœ… **COMPLETE** - You've already achieved this + +**Simple View** (compact list): +```bash +tito milestone list --simple +``` + +
+ +### Learn About Milestones + +
+ +**Get Detailed Information** +```bash +tito milestone info 03 +``` + +Shows: +- Historical context (year, researchers, significance) +- Description of what you'll recreate +- Required modules with โœ“/โœ— status +- Whether you're ready to run it + +
+ +### Run Milestones + +
+ +**Run a Milestone** +```bash +tito milestone run 03 +``` + +What happens: +1. **Checks prerequisites** - Validates required modules are complete +2. **Tests imports** - Ensures YOUR implementations work +3. **Shows context** - Historical background and what you'll recreate +4. **Runs the script** - Executes the milestone using YOUR code +5. **Tracks achievement** - Records your completion +6. **Celebrates!** - Shows achievement message ๐Ÿ† + +**Skip prerequisite checks** (not recommended): +```bash +tito milestone run 03 --skip-checks +``` + +
+ +### Track Progress + +
+ +**View Milestone Progress** +```bash +tito milestone status +``` + +Shows: +- How many milestones you've completed +- Your overall progress (%) +- Unlocked capabilities +- Next milestone ready to run + +**Visual Timeline** +```bash +tito milestone timeline +``` + +See your journey through ML history in a visual tree format. + +
+ +## The 6 Milestones + +### Milestone 01: Perceptron (1957) ๐Ÿง  + +**What**: Frank Rosenblatt's first trainable neural network + +**Requires**: Module 01 (Tensor) + +**What you'll do**: Implement and train the perceptron that proved machines could learn + +**Historical significance**: First demonstration of machine learning + +**Run it**: +```bash +tito milestone info 01 +tito milestone run 01 +``` + +--- + +### Milestone 02: XOR Crisis (1969) ๐Ÿ”€ + +**What**: Solving the problem that stalled AI research + +**Requires**: Modules 01-02 (Tensor, Activations) + +**What you'll do**: Use multi-layer networks to solve XOR - impossible for single-layer perceptrons + +**Historical significance**: Minsky & Papert showed perceptron limitations; this shows how to overcome them + +**Run it**: +```bash +tito milestone info 02 +tito milestone run 02 +``` + +--- + +### Milestone 03: MLP Revival (1986) ๐ŸŽ“ + +**What**: Backpropagation breakthrough - train deep networks on MNIST + +**Requires**: Modules 01-07 (Complete Foundation Tier) + +**What you'll do**: Train a multi-layer perceptron to recognize handwritten digits (95%+ accuracy) + +**Historical significance**: Rumelhart, Hinton & Williams (Nature, 1986) - the paper that reignited neural network research + +**Run it**: +```bash +tito milestone info 03 +tito milestone run 03 +``` + +--- + +### Milestone 04: CNN Revolution (1998) ๐Ÿ‘๏ธ + +**What**: LeNet - Computer Vision Breakthrough + +**Requires**: Modules 01-09 (Foundation + Spatial/Convolutions) + +**What you'll do**: Build LeNet for digit recognition using convolutional layers + +**Historical significance**: Yann LeCun's breakthrough that enabled modern computer vision + +**Run it**: +```bash +tito milestone info 04 +tito milestone run 04 +``` + +--- + +### Milestone 05: Transformer Era (2017) ๐Ÿค– + +**What**: "Attention is All You Need" + +**Requires**: Modules 01-13 (Foundation + Architecture Tiers) + +**What you'll do**: Implement transformer architecture with self-attention mechanism + +**Historical significance**: Vaswani et al. revolutionized NLP and enabled GPT/BERT/modern LLMs + +**Run it**: +```bash +tito milestone info 05 +tito milestone run 05 +``` + +--- + +### Milestone 06: MLPerf Benchmarks (2018) ๐Ÿ† + +**What**: Production ML Systems + +**Requires**: Modules 01-19 (Foundation + Architecture + Optimization Tiers) + +**What you'll do**: Optimize for production deployment with quantization, compression, and benchmarking + +**Historical significance**: MLPerf standardized ML system benchmarks for real-world deployment + +**Run it**: +```bash +tito milestone info 06 +tito milestone run 06 +``` + +--- + +## Prerequisites and Validation + +### How Prerequisites Work + +Each milestone requires specific modules to be complete. The `run` command automatically validates: + +**Module Completion Check**: +```bash +tito milestone run 03 + +๐Ÿ” Checking prerequisites for Milestone 03... + โœ“ Module 01 - complete + โœ“ Module 02 - complete + โœ“ Module 03 - complete + โœ“ Module 04 - complete + โœ“ Module 05 - complete + โœ“ Module 06 - complete + โœ“ Module 07 - complete + +โœ… All prerequisites met! +``` + +**Import Validation**: +```bash +๐Ÿงช Testing YOUR implementations... + โœ“ Tensor import successful + โœ“ Activations import successful + โœ“ Layers import successful + +โœ… YOUR TinyTorch is ready! +``` + +### If Prerequisites Are Missing + +You'll see a helpful error: + +```bash +โŒ Missing Required Modules + +Milestone 03 requires modules: 01, 02, 03, 04, 05, 06, 07 +Missing: 05, 06, 07 + +Complete the missing modules first: + tito module start 05 + tito module start 06 + tito module start 07 +``` + +## Achievement Celebration + +When you successfully complete a milestone, you'll see: + +``` +โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•— +โ•‘ ๐ŸŽ“ Milestone 03: MLP Revival (1986) โ•‘ +โ•‘ Backpropagation Breakthrough โ•‘ +โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +๐Ÿ† MILESTONE ACHIEVED! + +You completed Milestone 03: MLP Revival (1986) +Backpropagation Breakthrough + +What makes this special: +โ€ข Every line of code: YOUR implementations +โ€ข Every tensor operation: YOUR Tensor class +โ€ข Every gradient: YOUR autograd + +Achievement saved to your progress! + +๐ŸŽฏ What's Next: +Milestone 04: CNN Revolution (1998) +Unlock by completing modules: 08, 09 +``` + +## Understanding Your Progress + +### Three Tracking Systems + +TinyTorch tracks progress in three ways (all are related but distinct): + +
+ +**1. Module Completion** (`tito module status`) +- Which modules (01-20) you've implemented +- Tracked in `.tito/progress.json` +- **Required** for running milestones + +**2. Milestone Achievements** (`tito milestone status`) +- Which historical papers you've recreated +- Tracked in `.tito/milestones.json` +- Unlocked by completing modules + running milestones + +**3. Capability Checkpoints** (`tito checkpoint status`) - OPTIONAL +- Gamified capability tracking +- Tracked in `.tito/checkpoints.json` +- Purely motivational; can be disabled + +
+ +### Relationship Between Systems + +``` +Complete Modules (01-07) + โ†“ +Unlock Milestone 03 + โ†“ +Run: tito milestone run 03 + โ†“ +Achievement Recorded + โ†“ +Capability Unlocked (optional checkpoint system) +``` + +## Tips for Success + +### 1. Complete Modules in Order + +While you can technically skip around, the tier structure is designed for progressive learning: + +- **Foundation Tier (01-07)**: Required for first milestone +- **Architecture Tier (08-13)**: Build on Foundation +- **Optimization Tier (14-19)**: Build on Architecture + +### 2. Test as You Go + +Before running a milestone, make sure your modules work: + +```bash +# After completing a module +tito module complete 05 + +# Test it works +python -c "from tinytorch import Tensor; print(Tensor([[1,2]]))" +``` + +### 3. Use Info Before Run + +Learn what you're about to do: + +```bash +tito milestone info 03 # Read the context first +tito milestone run 03 # Then run it +``` + +### 4. Celebrate Achievements + +Share your milestones! Each one represents recreating a breakthrough that shaped modern AI. + +## Troubleshooting + +### "Import Error" when running milestone + +**Problem**: Module not exported or import failing + +**Solution**: +```bash +# Re-export the module +tito module complete XX + +# Test import manually +python -c "from tinytorch import Tensor" +``` + +### "Prerequisites Not Met" but I completed modules + +**Problem**: Progress not tracked correctly + +**Solution**: +```bash +# Check module status +tito module status + +# If modules show incomplete, re-run complete +tito module complete XX +``` + +### Milestone script fails during execution + +**Problem**: Bug in your implementation + +**Solution**: +1. Check error message for which module failed +2. Edit `modules/source/XX_name/` (NOT `tinytorch/`) +3. Re-export: `tito module complete XX` +4. Run milestone again + +## Next Steps + +
+

Ready to Recreate ML History?

+

Start with the Foundation Tier and work toward your first milestone

+Foundation Tier โ†’ +Historical Context โ†’ +
+ +--- + +*Every milestone uses YOUR code. Every achievement is proof you understand ML systems deeply. Build from scratch, recreate history, master the fundamentals.* diff --git a/site/tito/modules.md b/site/tito/modules.md new file mode 100644 index 00000000..446ac980 --- /dev/null +++ b/site/tito/modules.md @@ -0,0 +1,461 @@ +# Module Workflow + +
+

Build ML Systems from Scratch

+

The core workflow for implementing and exporting TinyTorch modules

+
+ +**Purpose**: Master the module development workflow - the heart of TinyTorch. Learn how to implement modules, export them to your package, and validate with tests. + +## The Core Workflow + +TinyTorch follows a simple build-export-validate cycle: + +```{mermaid} +graph LR + A[Start/Resume Module] --> B[Edit in Jupyter] + B --> C[Complete & Export] + C --> D[Test Import] + D --> E[Next Module] + + style A fill:#e3f2fd + style B fill:#fffbeb + style C fill:#f0fdf4 + style D fill:#fef3c7 + style E fill:#f3e5f5 +``` + +**The essential command**: `tito module complete XX` - exports your code to the TinyTorch package + +See [Student Workflow](../student-workflow.md) for the complete development cycle and best practices. + +--- + +## Essential Commands + +
+ +
+

Check Environment

+tito system doctor +

Verify your setup is ready before starting

+
+ +
+

Start a Module (First Time)

+tito module start 01 +

Opens Jupyter Lab for Module 01 (Tensor)

+
+ +
+

Resume Work (Continue Later)

+tito module resume 01 +

Continue working on Module 01 where you left off

+
+ +
+

Export & Complete (Essential)

+tito module complete 01 +

Export Module 01 to TinyTorch package - THE key command

+
+ +
+

Check Progress

+tito module status +

See which modules you've completed

+
+ +
+ +--- + +## Typical Development Session + +Here's what a complete session looks like: + +
+ +**1. Start Session** +```bash +cd TinyTorch +source activate.sh +tito system doctor # Verify environment +``` + +**2. Start or Resume Module** +```bash +# First time working on Module 03 +tito module start 03 + +# OR: Continue from where you left off +tito module resume 03 +``` + +This opens Jupyter Lab with the module notebook. + +**3. Edit in Jupyter Lab** +```python +# In modules/03_layers/layers_dev.py +class Linear: + def __init__(self, in_features, out_features): + # YOUR implementation here + ... +``` + +Work interactively: +- Implement the required functionality +- Add docstrings and comments +- Run and test your code inline +- See immediate feedback + +**4. Export to Package** +```bash +# From repository root +tito module complete 03 +``` + +This command: +- Runs tests on your implementation +- Exports code to `tinytorch/nn/layers.py` +- Makes your code importable +- Tracks completion + +**5. Test Your Implementation** +```bash +# Your code is now in the package! +python -c "from tinytorch import Linear; print(Linear(10, 5))" +``` + +**6. Check Progress** +```bash +tito module status +``` + +
+ +--- + +## System Commands + +### Environment Health + +
+ +**Check Setup (Run This First)** +```bash +tito system doctor +``` + +Verifies: +- Virtual environment activated +- Dependencies installed (NumPy, Jupyter, Rich) +- TinyTorch in development mode +- All systems ready + +**Output**: +``` +โœ… Environment validation passed + โ€ข Virtual environment: Active + โ€ข Dependencies: NumPy, Jupyter, Rich installed + โ€ข TinyTorch: Development mode +``` + +**System Information** +```bash +tito system info +``` + +Shows: +- Python version +- Environment paths +- Package versions +- Configuration settings + +**Start Jupyter Lab** +```bash +tito system jupyter +``` + +Convenience command to launch Jupyter Lab from the correct directory. + +
+ +--- + +## Module Lifecycle Commands + +### Start a Module (First Time) + +
+ +```bash +tito module start 01 +``` + +**What this does**: +1. Opens Jupyter Lab for Module 01 (Tensor) +2. Shows module README and learning objectives +3. Provides clean starting point +4. Creates backup of any existing work + +**Example**: +```bash +tito module start 05 # Start Module 05 (Autograd) +``` + +Jupyter Lab opens with `modules/05_autograd/autograd_dev.py` + +
+ +### Resume Work (Continue Later) + +
+ +```bash +tito module resume 01 +``` + +**What this does**: +1. Opens Jupyter Lab with your previous work +2. Preserves all your changes +3. Shows where you left off +4. No backup created (you're continuing) + +**Use this when**: Coming back to a module you started earlier + +
+ +### Complete & Export (Essential) + +
+ +```bash +tito module complete 01 +``` + +**THE KEY COMMAND** - This is what makes your code real! + +**What this does**: +1. **Tests** your implementation (inline tests) +2. **Exports** to `tinytorch/` package +3. **Tracks** completion in `.tito/progress.json` +4. **Validates** NBGrader metadata +5. **Makes read-only** exported files (protection) + +**Example**: +```bash +tito module complete 05 # Export Module 05 (Autograd) +``` + +**After exporting**: +```python +# YOUR code is now importable! +from tinytorch.autograd import backward +from tinytorch import Tensor + +# Use YOUR implementations +x = Tensor([[1.0, 2.0]], requires_grad=True) +y = x * 2 +y.backward() +print(x.grad) # Uses YOUR autograd! +``` + +
+ +### View Progress + +
+ +```bash +tito module status +``` + +**Shows**: +- Which modules (01-20) you've completed +- Completion dates +- Next recommended module + +**Example Output**: +``` +๐Ÿ“ฆ Module Progress + +โœ… Module 01: Tensor (completed 2025-11-16) +โœ… Module 02: Activations (completed 2025-11-16) +โœ… Module 03: Layers (completed 2025-11-16) +๐Ÿ”’ Module 04: Losses (not started) +๐Ÿ”’ Module 05: Autograd (not started) + +Progress: 3/20 modules (15%) + +Next: Complete Module 04 to continue Foundation Tier +``` + +
+ +### Reset Module (Advanced) + +
+ +```bash +tito module reset 01 +``` + +**What this does**: +1. Creates backup of current work +2. Unexports from `tinytorch/` package +3. Restores module to clean state +4. Removes from completion tracking + +**Use this when**: You want to start a module completely fresh + +โš ๏ธ **Warning**: This removes your implementation. Use with caution! + +
+ +--- + +## Understanding the Export Process + +When you run `tito module complete XX`, here's what happens: + +
+ +**Step 1: Validation** +``` +โœ“ Checking NBGrader metadata +โœ“ Validating Python syntax +โœ“ Running inline tests +``` + +**Step 2: Export** +``` +โœ“ Converting modules/XX_name/name_dev.py + โ†’ tinytorch/path/name.py +โœ“ Adding "DO NOT EDIT" warning +โœ“ Making file read-only +``` + +**Step 3: Tracking** +``` +โœ“ Recording completion in .tito/progress.json +โœ“ Updating module status +``` + +**Step 4: Success** +``` +๐ŸŽ‰ Module XX complete! + Your code is now part of TinyTorch! + + Import with: from tinytorch import YourClass +``` + +
+ +--- + +## Module Structure + +### Where You Edit + +``` +modules/ +โ”œโ”€โ”€ 01_tensor/ +โ”‚ โ””โ”€โ”€ tensor_dev.py โ† YOU EDIT THIS +โ”œโ”€โ”€ 02_activations/ +โ”‚ โ””โ”€โ”€ activations_dev.py โ† YOU EDIT THIS +โ””โ”€โ”€ 03_layers/ + โ””โ”€โ”€ layers_dev.py โ† YOU EDIT THIS +``` + +### Where Code Exports + +``` +tinytorch/ +โ”œโ”€โ”€ core/ +โ”‚ โ””โ”€โ”€ tensor.py โ† AUTO-GENERATED (DO NOT EDIT) +โ”œโ”€โ”€ nn/ +โ”‚ โ”œโ”€โ”€ activations.py โ† AUTO-GENERATED (DO NOT EDIT) +โ”‚ โ””โ”€โ”€ layers.py โ† AUTO-GENERATED (DO NOT EDIT) +โ””โ”€โ”€ ... +``` + +**IMPORTANT**: Never edit files in `tinytorch/` directly! +- They have "DO NOT EDIT" warnings +- They're auto-generated from `modules/` +- Changes will be lost on re-export +- Always edit in `modules/` instead + +--- + +## Troubleshooting + +### Environment Not Ready + +
+ +**Problem**: `tito system doctor` shows errors + +**Solution**: +```bash +# Re-run setup +./setup-environment.sh +source activate.sh + +# Verify +tito system doctor +``` + +
+ +### Export Fails + +
+ +**Problem**: `tito module complete XX` fails + +**Common causes**: +1. Syntax errors in your code +2. Failing tests +3. Missing required functions + +**Solution**: +1. Check error message for details +2. Fix issues in `modules/XX_name/` +3. Test in Jupyter Lab first +4. Re-run `tito module complete XX` + +
+ +### Import Errors + +
+ +**Problem**: `from tinytorch import X` fails + +**Solution**: +```bash +# Re-export the module +tito module complete XX + +# Test import +python -c "from tinytorch import Tensor" +``` + +
+ +See [Troubleshooting Guide](troubleshooting.md) for more issues and solutions. + +--- + +## Next Steps + +
+

Ready to Build Your First Module?

+

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

+Foundation Tier โ†’ +Milestone System โ†’ +
+ +--- + +*The module workflow is the heart of TinyTorch. Master these commands and you'll build ML systems with confidence. Every line of code you write becomes part of a real, working framework.* diff --git a/site/tito/overview.md b/site/tito/overview.md new file mode 100644 index 00000000..2f98af3d --- /dev/null +++ b/site/tito/overview.md @@ -0,0 +1,223 @@ +# TITO Command Reference + +
+

Master the TinyTorch CLI

+

Complete command reference for building ML systems efficiently

+
+ +**Purpose**: Quick reference for all TITO commands. Find the right command for every task in your ML systems engineering journey. + +## Quick Start: Three Commands You Need + +
+ +
+

1. Check Your Environment

+tito system doctor +

Verify your setup is ready for development

+
+ +
+

2. Build & Export Modules

+tito module complete 01 +

Export your module to the TinyTorch package

+
+ +
+

3. Run Historical Milestones

+tito milestone run 03 +

Recreate ML history with YOUR code

+
+ +
+ +--- + +## Complete Command Reference + +### System Commands + +**Purpose**: Environment health and configuration + +| Command | Description | Guide | +|---------|-------------|-------| +| `tito system doctor` | Diagnose environment issues | [Module Workflow](modules.md) | +| `tito system info` | Show system configuration | [Module Workflow](modules.md) | +| `tito system jupyter` | Start Jupyter Lab server | [Module Workflow](modules.md) | + +### Module Commands + +**Purpose**: Build-from-scratch workflow (your main development cycle) + +| Command | Description | Guide | +|---------|-------------|-------| +| `tito module start XX` | Begin working on a module (first time) | [Module Workflow](modules.md) | +| `tito module resume XX` | Continue working on a module | [Module Workflow](modules.md) | +| `tito module complete XX` | Test, export, and track module completion | [Module Workflow](modules.md) | +| `tito module status` | View module completion progress | [Module Workflow](modules.md) | +| `tito module reset XX` | Reset module to clean state | [Module Workflow](modules.md) | + +**See**: [Module Workflow Guide](modules.md) for complete details + +### Milestone Commands + +**Purpose**: Run historical ML recreations with YOUR implementations + +| Command | Description | Guide | +|---------|-------------|-------| +| `tito milestone list` | Show all 6 historical milestones (1957-2018) | [Milestone System](milestones.md) | +| `tito milestone run XX` | Run milestone with prerequisite checking | [Milestone System](milestones.md) | +| `tito milestone info XX` | Get detailed milestone information | [Milestone System](milestones.md) | +| `tito milestone status` | View milestone progress and achievements | [Milestone System](milestones.md) | +| `tito milestone timeline` | Visual timeline of your journey | [Milestone System](milestones.md) | + +**See**: [Milestone System Guide](milestones.md) for complete details + +### Progress & Data Commands + +**Purpose**: Track progress and manage user data + +| Command | Description | Guide | +|---------|-------------|-------| +| `tito status` | View all progress (modules + milestones) | [Progress & Data](data.md) | +| `tito reset all` | Reset all progress and start fresh | [Progress & Data](data.md) | +| `tito reset progress` | Reset module completion only | [Progress & Data](data.md) | +| `tito reset milestones` | Reset milestone achievements only | [Progress & Data](data.md) | + +**See**: [Progress & Data Management](data.md) for complete details + +--- + +## Command Groups by Task + +### First-Time Setup + +```bash +# Clone and setup +git clone https://github.com/mlsysbook/TinyTorch.git +cd TinyTorch +./setup-environment.sh +source activate.sh + +# Verify environment +tito system doctor +``` + +### Daily Development Workflow + +```bash +# Start or continue a module +tito module start 01 # First time +tito module resume 01 # Continue later + +# Export when complete +tito module complete 01 + +# Check progress +tito module status +``` + +### Achievement & Validation + +```bash +# See available milestones +tito milestone list + +# Get details +tito milestone info 03 + +# Run milestone +tito milestone run 03 + +# View achievements +tito milestone status +``` + +### Progress Management + +```bash +# View all progress +tito status + +# Reset if needed +tito reset all --backup +``` + +--- + +## Typical Session Flow + +Here's what a typical TinyTorch session looks like: + +
+ +**1. Start Session** +```bash +cd TinyTorch +source activate.sh +tito system doctor # Verify environment +``` + +**2. Work on Module** +```bash +tito module start 03 # Or: tito module resume 03 +# Edit in Jupyter Lab... +``` + +**3. Export & Test** +```bash +tito module complete 03 +``` + +**4. Run Milestone (when prerequisites met)** +```bash +tito milestone list # Check if ready +tito milestone run 03 # Run with YOUR code +``` + +**5. Track Progress** +```bash +tito status # See everything +``` + +
+ +--- + +## Command Help + +Every command has detailed help text: + +```bash +# Top-level help +tito --help + +# Command group help +tito module --help +tito milestone --help + +# Specific command help +tito module complete --help +tito milestone run --help +``` + +--- + +## Detailed Guides + +- **[Module Workflow](modules.md)** - Complete guide to building and exporting modules +- **[Milestone System](milestones.md)** - Running historical ML recreations +- **[Progress & Data](data.md)** - Managing your learning journey +- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions + +--- + +## Related Resources + +- **[Quick Start Guide](../quickstart-guide.md)** - 15-minute setup walkthrough +- **[Student Workflow](../student-workflow.md)** - Day-to-day development cycle +- **[Datasets Guide](../datasets.md)** - Understanding TinyTorch datasets + +--- + +*Master these commands and you'll build ML systems with confidence. Every command is designed to accelerate your learning and keep you focused on what matters: building production-quality ML frameworks from scratch.* diff --git a/site/tito/troubleshooting.md b/site/tito/troubleshooting.md new file mode 100644 index 00000000..d7caa1eb --- /dev/null +++ b/site/tito/troubleshooting.md @@ -0,0 +1,882 @@ +# Troubleshooting Guide + +
+

Common Issues & Solutions

+

Quick fixes for the most common TinyTorch problems

+
+ +**Purpose**: Fast solutions to common issues. Get unstuck and back to building ML systems quickly. + +--- + +## Quick Diagnostic: Start Here + +
+ +**First step for ANY issue**: + +```bash +cd TinyTorch +source activate.sh +tito system doctor +``` + +This checks: +- โœ… Virtual environment activated +- โœ… Dependencies installed (NumPy, Jupyter, Rich) +- โœ… TinyTorch in development mode +- โœ… Data files intact +- โœ… All systems ready + +**If doctor shows errors**: Follow the specific fixes below. + +**If doctor shows all green**: Your environment is fine - issue is elsewhere. + +
+ +--- + +## Environment Issues + +### Problem: "tito: command not found" + +
+ +**Symptom**: +```bash +$ tito module start 01 +-bash: tito: command not found +``` + +**Cause**: Virtual environment not activated or TinyTorch not installed in development mode. + +**Solution**: +```bash +# 1. Activate environment +cd TinyTorch +source activate.sh + +# 2. Verify activation +which python # Should show TinyTorch/venv/bin/python + +# 3. Re-install TinyTorch in development mode +pip install -e . + +# 4. Test +tito --help +``` + +**Prevention**: Always run `source activate.sh` before working. + +
+ +### Problem: "No module named 'tinytorch'" + +
+ +**Symptom**: +```python +>>> from tinytorch import Tensor +ModuleNotFoundError: No module named 'tinytorch' +``` + +**Cause**: TinyTorch not installed in development mode, or wrong Python interpreter. + +**Solution**: +```bash +# 1. Verify you're in the right directory +pwd # Should end with /TinyTorch + +# 2. Activate environment +source activate.sh + +# 3. Install in development mode +pip install -e . + +# 4. Verify installation +pip show tinytorch +python -c "import tinytorch; print(tinytorch.__file__)" +``` + +**Expected output**: +``` +/Users/YourName/TinyTorch/tinytorch/__init__.py +``` + +
+ +### Problem: "Virtual environment issues after setup" + +
+ +**Symptom**: +```bash +$ source activate.sh +# No (venv) prefix appears, or wrong Python version +``` + +**Cause**: Virtual environment not created properly or corrupted. + +**Solution**: +```bash +# 1. Remove old virtual environment +rm -rf venv/ + +# 2. Re-run setup +./setup-environment.sh + +# 3. Activate +source activate.sh + +# 4. Verify +python --version # Should be 3.8+ +which pip # Should show TinyTorch/venv/bin/pip +``` + +**Expected**: `(venv)` prefix appears in terminal prompt. + +
+ +--- + +## Module Issues + +### Problem: "Module export fails" + +
+ +**Symptom**: +```bash +$ tito module complete 03 +โŒ Export failed: SyntaxError in modules/03_layers/layers_dev.py +``` + +**Causes**: +1. Python syntax errors in your code +2. Missing required functions +3. NBGrader metadata issues + +**Solution**: + +**Step 1: Check syntax**: +```bash +# Test Python syntax directly +python -m py_compile modules/03_layers/layers_dev.py +``` + +**Step 2: Open in Jupyter and test**: +```bash +tito module resume 03 +# In Jupyter: Run all cells, check for errors +``` + +**Step 3: Fix errors shown in output** + +**Step 4: Re-export**: +```bash +tito module complete 03 +``` + +**Common syntax errors**: +- Missing `:` after function/class definitions +- Incorrect indentation (use 4 spaces, not tabs) +- Unclosed parentheses or brackets +- Missing `return` statements + +
+ +### Problem: "Tests fail during export" + +
+ +**Symptom**: +```bash +$ tito module complete 05 +Running tests... +โŒ Test failed: test_backward_simple +``` + +**Cause**: Your implementation doesn't match expected behavior. + +**Solution**: + +**Step 1: See test details**: +```bash +# Tests are in the module file - look for cells marked "TEST" +tito module resume 05 +# In Jupyter: Find test cells, run them individually +``` + +**Step 2: Debug your implementation**: +```python +# Add print statements to see what's happening +def backward(self): + print(f"Debug: self.grad = {self.grad}") + # ... your implementation +``` + +**Step 3: Compare with expected behavior**: +- Read test assertions carefully +- Check edge cases (empty tensors, zero values) +- Verify shapes and types + +**Step 4: Fix and re-export**: +```bash +tito module complete 05 +``` + +**Tip**: Run tests interactively in Jupyter before exporting. + +
+ +### Problem: "Jupyter Lab won't start" + +
+ +**Symptom**: +```bash +$ tito module start 01 +# Jupyter Lab fails to launch or shows errors +``` + +**Cause**: Jupyter not installed or port already in use. + +**Solution**: + +**Step 1: Verify Jupyter installation**: +```bash +pip install jupyter jupyterlab jupytext +``` + +**Step 2: Check for port conflicts**: +```bash +# Kill any existing Jupyter instances +pkill -f jupyter + +# Or try a different port +jupyter lab --port=8889 modules/01_tensor/ +``` + +**Step 3: Clear Jupyter cache**: +```bash +jupyter lab clean +``` + +**Step 4: Restart**: +```bash +tito module start 01 +``` + +
+ +### Problem: "Changes in Jupyter don't save" + +
+ +**Symptom**: Edit in Jupyter Lab, but `modules/XX_name/name_dev.py` doesn't change. + +**Cause**: Jupytext sync issues or file permissions. + +**Solution**: + +**Step 1: Manual save**: +``` +In Jupyter Lab: +File โ†’ Save File (or Cmd/Ctrl + S) +``` + +**Step 2: Check file permissions**: +```bash +ls -la modules/01_tensor/tensor_dev.py +# Should be writable (not read-only) +``` + +**Step 3: If read-only, fix permissions**: +```bash +chmod u+w modules/01_tensor/tensor_dev.py +``` + +**Step 4: Verify changes**: +```bash +cat modules/01_tensor/tensor_dev.py | head -20 +``` + +
+ +--- + +## Import Issues + +### Problem: "Cannot import from tinytorch after export" + +
+ +**Symptom**: +```python +>>> from tinytorch import Linear +ImportError: cannot import name 'Linear' from 'tinytorch' +``` + +**Cause**: Module not exported yet, or export didn't update `__init__.py`. + +**Solution**: + +**Step 1: Verify module completed**: +```bash +tito module status +# Check if module shows as โœ… completed +``` + +**Step 2: Check exported file exists**: +```bash +ls -la tinytorch/nn/layers.py +# File should exist and have recent timestamp +``` + +**Step 3: Re-export**: +```bash +tito module complete 03 +``` + +**Step 4: Test import**: +```python +python -c "from tinytorch.nn import Linear; print(Linear)" +``` + +**Note**: Use full import path initially, then check if `from tinytorch import Linear` works (requires `__init__.py` update). + +
+ +### Problem: "Circular import errors" + +
+ +**Symptom**: +```python +>>> from tinytorch import Tensor +ImportError: cannot import name 'Tensor' from partially initialized module 'tinytorch' +``` + +**Cause**: Circular dependency in your imports. + +**Solution**: + +**Step 1: Check your import structure**: +```python +# In modules/XX_name/name_dev.py +# DON'T import from tinytorch in module development files +# DO import from dependencies only +``` + +**Step 2: Use local imports if needed**: +```python +# Inside functions, not at module level +def some_function(): + from tinytorch.core import Tensor # Local import + ... +``` + +**Step 3: Re-export**: +```bash +tito module complete XX +``` + +
+ +--- + +## Milestone Issues + +### Problem: "Milestone says prerequisites not met" + +
+ +**Symptom**: +```bash +$ tito milestone run 04 +โŒ Prerequisites not met + Missing modules: 08, 09 +``` + +**Cause**: You haven't completed required modules yet. + +**Solution**: + +**Step 1: Check requirements**: +```bash +tito milestone info 04 +# Shows which modules are required +``` + +**Step 2: Complete required modules**: +```bash +tito module status # See what's completed +tito module start 08 # Complete missing modules +# ... implement and export +tito module complete 08 +``` + +**Step 3: Try milestone again**: +```bash +tito milestone run 04 +``` + +**Tip**: Milestones unlock progressively. Complete modules in order (01 โ†’ 20) for best experience. + +
+ +### Problem: "Milestone fails with import errors" + +
+ +**Symptom**: +```bash +$ tito milestone run 03 +Running: MLP Revival (1986) +ImportError: cannot import name 'ReLU' from 'tinytorch' +``` + +**Cause**: Required module not exported properly. + +**Solution**: + +**Step 1: Check which import failed**: +``` +# Error message shows: 'ReLU' from 'tinytorch' +# This is from Module 02 (Activations) +``` + +**Step 2: Re-export that module**: +```bash +tito module complete 02 +``` + +**Step 3: Test import manually**: +```python +python -c "from tinytorch import ReLU; print(ReLU)" +``` + +**Step 4: Run milestone again**: +```bash +tito milestone run 03 +``` + +
+ +### Problem: "Milestone runs but shows errors" + +
+ +**Symptom**: +```bash +$ tito milestone run 03 +Running: MLP Revival (1986) +# Script runs but shows runtime errors or wrong output +``` + +**Cause**: Your implementation has bugs (not syntax errors, but logic errors). + +**Solution**: + +**Step 1: Run milestone script manually**: +```bash +python milestones/03_1986_mlp/03_mlp_mnist_train.py +# See full error output +``` + +**Step 2: Debug the specific module**: +```bash +# If error is in ReLU, for example +tito module resume 02 +# Fix implementation in Jupyter +``` + +**Step 3: Re-export**: +```bash +tito module complete 02 +``` + +**Step 4: Test milestone again**: +```bash +tito milestone run 03 +``` + +**Tip**: Milestones test your implementations in realistic scenarios. They help find edge cases you might have missed. + +
+ +--- + +## Data & Progress Issues + +### Problem: ".tito folder deleted or corrupted" + +
+ +**Symptom**: +```bash +$ tito module status +Error: .tito/progress.json not found +``` + +**Cause**: `.tito/` folder deleted or progress file corrupted. + +**Solution**: + +**Option 1: Let TinyTorch recreate it (fresh start)**: +```bash +tito system doctor +# Recreates .tito/ structure with empty progress +``` + +**Option 2: Restore from backup (if you have one)**: +```bash +# Check for backups +ls -la .tito_backup_*/ + +# Restore from latest backup +cp -r .tito_backup_20251116_143000/ .tito/ +``` + +**Option 3: Manual recreation**: +```bash +mkdir -p .tito/backups +echo '{"version":"1.0","completed_modules":[],"completion_dates":{}}' > .tito/progress.json +echo '{"version":"1.0","completed_milestones":[],"completion_dates":{}}' > .tito/milestones.json +echo '{"logo_theme":"standard"}' > .tito/config.json +``` + +**Important**: Your code in `modules/` and `tinytorch/` is safe. Only progress tracking is affected. + +
+ +### Problem: "Progress shows wrong modules completed" + +
+ +**Symptom**: +```bash +$ tito module status +Shows modules as completed that you haven't done +``` + +**Cause**: Accidentally ran `tito module complete XX` without implementing, or manual `.tito/progress.json` edit. + +**Solution**: + +**Option 1: Reset specific module**: +```bash +tito module reset 05 +# Clears completion for Module 05 only +``` + +**Option 2: Reset all progress**: +```bash +tito reset progress +# Clears all module completion +``` + +**Option 3: Manually edit `.tito/progress.json`**: +```bash +# Open in editor +nano .tito/progress.json + +# Remove the module number from "completed_modules" array +# Remove the entry from "completion_dates" object +``` + +
+ +--- + +## Dependency Issues + +### Problem: "NumPy import errors" + +
+ +**Symptom**: +```python +>>> import numpy as np +ImportError: No module named 'numpy' +``` + +**Cause**: Dependencies not installed in virtual environment. + +**Solution**: +```bash +# Activate environment +source activate.sh + +# Install dependencies +pip install numpy jupyter jupyterlab jupytext rich + +# Verify +python -c "import numpy; print(numpy.__version__)" +``` + +
+ +### Problem: "Rich formatting doesn't work" + +
+ +**Symptom**: TITO output is plain text instead of colorful panels. + +**Cause**: Rich library not installed or terminal doesn't support colors. + +**Solution**: + +**Step 1: Install Rich**: +```bash +pip install rich +``` + +**Step 2: Use color-capable terminal**: +- macOS: Terminal.app, iTerm2 +- Linux: GNOME Terminal, Konsole +- Windows: Windows Terminal, PowerShell + +**Step 3: Test**: +```bash +python -c "from rich import print; print('[bold green]Test[/bold green]')" +``` + +
+ +--- + +## Performance Issues + +### Problem: "Jupyter Lab is slow" + +
+ +**Solutions**: + +**1. Close unused notebooks**: +``` +In Jupyter Lab: +Right-click notebook tab โ†’ Close +File โ†’ Shut Down All Kernels +``` + +**2. Clear output cells**: +``` +In Jupyter Lab: +Edit โ†’ Clear All Outputs +``` + +**3. Restart kernel**: +``` +Kernel โ†’ Restart Kernel +``` + +**4. Increase memory** (if working with large datasets): +```bash +# Check memory usage +top +# Close other applications if needed +``` + +
+ +### Problem: "Export takes a long time" + +
+ +**Cause**: Tests running on large data or complex operations. + +**Solution**: + +**This is normal for**: +- Modules with extensive tests +- Operations involving training loops +- Large tensor operations + +**If export hangs**: +```bash +# Cancel with Ctrl+C +# Check for infinite loops in your code +# Simplify tests temporarily, then re-export +``` + +
+ +--- + +## Platform-Specific Issues + +### macOS: "Permission denied" + +
+ +**Symptom**: +```bash +$ ./setup-environment.sh +Permission denied +``` + +**Solution**: +```bash +chmod +x setup-environment.sh activate.sh +./setup-environment.sh +``` + +
+ +### Windows: "activate.sh not working" + +
+ +**Solution**: Use Windows-specific activation: +```bash +# PowerShell +.\venv\Scripts\Activate.ps1 + +# Command Prompt +.\venv\Scripts\activate.bat + +# Git Bash +source venv/Scripts/activate +``` + +
+ +### Linux: "Python version issues" + +
+ +**Solution**: Specify Python 3.8+ explicitly: +```bash +python3.8 -m venv venv +source activate.sh +python --version # Verify +``` + +
+ +--- + +## Getting More Help + +### Debug Mode + +
+ +**Run commands with verbose output**: +```bash +# Most TITO commands support --verbose +tito module complete 03 --verbose + +# See detailed error traces +python -m pdb milestones/03_1986_mlp/03_mlp_mnist_train.py +``` + +
+ +### Check Logs + +
+ +**Jupyter Lab logs**: +```bash +# Check Jupyter output in terminal where you ran tito module start +# Look for error messages, warnings +``` + +**Python traceback**: +```bash +# Full error context +python -c "from tinytorch import Tensor" 2>&1 | less +``` + +
+ +### Community Support + +
+ +**GitHub Issues**: Report bugs or ask questions +- Repository: [mlsysbook/TinyTorch](https://github.com/mlsysbook/TinyTorch) +- Search existing issues first +- Include error messages and OS details + +**Documentation**: Check other guides +- [Module Workflow](modules.md) +- [Milestone System](milestones.md) +- [Progress & Data](data.md) + +
+ +--- + +## Prevention: Best Practices + +
+ +**Avoid issues before they happen**: + +1. **Always activate environment first**: + ```bash + source activate.sh + ``` + +2. **Run `tito system doctor` regularly**: + ```bash + tito system doctor + ``` + +3. **Test in Jupyter before exporting**: + ```bash + # Run all cells, verify output + # THEN run tito module complete + ``` + +4. **Keep backups** (automatic): + ```bash + # Backups happen automatically + # Don't delete .tito/backups/ unless needed + ``` + +5. **Use git for your code**: + ```bash + git commit -m "Working Module 05 implementation" + ``` + +6. **Read error messages carefully**: + - They usually tell you exactly what's wrong + - Pay attention to file paths and line numbers + +
+ +--- + +## Quick Reference: Fixing Common Errors + +| Error Message | Quick Fix | +|--------------|-----------| +| `tito: command not found` | `source activate.sh` | +| `ModuleNotFoundError: tinytorch` | `pip install -e .` | +| `SyntaxError` in export | Fix Python syntax, test in Jupyter first | +| `ImportError` in milestone | Re-export required modules | +| `.tito/progress.json not found` | `tito system doctor` to recreate | +| `Jupyter Lab won't start` | `pkill -f jupyter && tito module start XX` | +| `Permission denied` | `chmod +x setup-environment.sh activate.sh` | +| `Tests fail` during export | Debug in Jupyter, check test assertions | +| `Prerequisites not met` | `tito milestone info XX` to see requirements | + +--- + +## Still Stuck? + +
+

Need More Help?

+

Try these resources for additional support

+Report Issue โ†’ +Command Reference โ†’ +
+ +--- + +*Most issues have simple fixes. Start with `tito system doctor`, read error messages carefully, and remember: your code is always safe in `modules/` - only progress tracking can be reset.* diff --git a/tito/commands/milestone.py b/tito/commands/milestone.py index 9f742b40..5c343c3e 100644 --- a/tito/commands/milestone.py +++ b/tito/commands/milestone.py @@ -30,6 +30,77 @@ from ..core.console import print_ascii_logo from ..core.console import get_console +# Milestone-to-script mapping for tito milestone run command +MILESTONE_SCRIPTS = { + "01": { + "id": "01", + "name": "Perceptron (1957)", + "year": 1957, + "title": "Frank Rosenblatt's First Neural Network", + "script": "milestones/01_1957_perceptron/02_rosenblatt_trained.py", + "required_modules": [1], + "description": "Build the first trainable neural network", + "historical_context": "Rosenblatt's perceptron proved machines could learn", + "emoji": "๐Ÿง " + }, + "02": { + "id": "02", + "name": "XOR Crisis (1969)", + "year": 1969, + "title": "Solving the Problem That Stalled AI", + "script": "milestones/02_1969_xor/02_xor_solved.py", + "required_modules": [1, 2], + "description": "Solve XOR with multi-layer networks", + "historical_context": "Minsky & Papert showed single-layer limits", + "emoji": "๐Ÿ”€" + }, + "03": { + "id": "03", + "name": "MLP Revival (1986)", + "year": 1986, + "title": "Backpropagation Breakthrough", + "script": "milestones/03_1986_mlp/02_rumelhart_mnist.py", + "required_modules": [1, 2, 3, 4, 5, 6, 7], + "description": "Train deep networks on MNIST", + "historical_context": "Rumelhart, Hinton & Williams (Nature, 1986)", + "emoji": "๐ŸŽ“" + }, + "04": { + "id": "04", + "name": "CNN Revolution (1998)", + "year": 1998, + "title": "LeNet - Computer Vision Breakthrough", + "script": "milestones/04_1998_cnn/01_lecun_tinydigits.py", + "required_modules": [1, 2, 3, 4, 5, 6, 7, 8, 9], + "description": "Build LeNet for digit recognition", + "historical_context": "Yann LeCun's convolutional networks", + "emoji": "๐Ÿ‘๏ธ" + }, + "05": { + "id": "05", + "name": "Transformer Era (2017)", + "year": 2017, + "title": "Attention is All You Need", + "script": "milestones/05_2017_transformer/01_vaswani_generation.py", + "required_modules": list(range(1, 14)), + "description": "Build transformer with self-attention", + "historical_context": "Vaswani et al. revolutionized NLP", + "emoji": "๐Ÿค–" + }, + "06": { + "id": "06", + "name": "MLPerf Benchmarks (2018)", + "year": 2018, + "title": "Production ML Systems", + "script": "milestones/06_2018_mlperf/02_compression.py", + "required_modules": list(range(1, 20)), + "description": "Optimize for production deployment", + "historical_context": "MLPerf standardized ML benchmarks", + "emoji": "๐Ÿ†" + } +} + + class MilestoneSystem: """Core milestone tracking and management system.""" @@ -298,7 +369,43 @@ class MilestoneCommand(BaseCommand): help='Milestone subcommands', metavar='SUBCOMMAND' ) - + + # List subcommand (NEW) + list_parser = subparsers.add_parser( + 'list', + help='List available milestones and their status' + ) + list_parser.add_argument( + '--simple', + action='store_true', + help='Show simple list (less detail)' + ) + + # Run subcommand (NEW) + run_parser = subparsers.add_parser( + 'run', + help='Run a milestone with prerequisite checking' + ) + run_parser.add_argument( + 'milestone_id', + help='Milestone ID to run (01-06)' + ) + run_parser.add_argument( + '--skip-checks', + action='store_true', + help='Skip prerequisite checks (not recommended)' + ) + + # Info subcommand (NEW) + info_parser = subparsers.add_parser( + 'info', + help='Show detailed information about a milestone' + ) + info_parser.add_argument( + 'milestone_id', + help='Milestone ID to show info for (01-06)' + ) + # Status subcommand status_parser = subparsers.add_parser( 'status', @@ -309,7 +416,7 @@ class MilestoneCommand(BaseCommand): action='store_true', help='Show detailed milestone information' ) - + # Timeline subcommand timeline_parser = subparsers.add_parser( 'timeline', @@ -320,7 +427,7 @@ class MilestoneCommand(BaseCommand): action='store_true', help='Show horizontal progress bar instead of tree' ) - + # Test subcommand test_parser = subparsers.add_parser( 'test', @@ -331,7 +438,7 @@ class MilestoneCommand(BaseCommand): nargs='?', help='Milestone ID to test (1-5), or test next available' ) - + # Demo subcommand demo_parser = subparsers.add_parser( 'demo', @@ -344,28 +451,37 @@ class MilestoneCommand(BaseCommand): def run(self, args: Namespace) -> int: console = self.console - + if not hasattr(args, 'milestone_command') or not args.milestone_command: console.print(Panel( "[bold cyan]Milestone Commands[/bold cyan]\n\n" - "Transform module completion into epic capability achievements!\n\n" + "Recreate ML history and achieve epic capabilities!\n\n" "Available subcommands:\n" - " โ€ข [bold]status[/bold] - View milestone progress and achievements\n" - " โ€ข [bold]timeline[/bold] - View milestone timeline and progression\n" - " โ€ข [bold]test[/bold] - Test milestone achievement requirements\n" - " โ€ข [bold]demo[/bold] - Run milestone capability demonstration\n\n" + " โ€ข [bold]list[/bold] - List available milestones\n" + " โ€ข [bold]run[/bold] - Run a milestone (with prereq checks)\n" + " โ€ข [bold]info[/bold] - Show detailed milestone information\n" + " โ€ข [bold]status[/bold] - View progress and achievements\n" + " โ€ข [bold]timeline[/bold] - View milestone timeline\n" + " โ€ข [bold]test[/bold] - Test milestone requirements\n" + " โ€ข [bold]demo[/bold] - Run capability demonstration\n\n" "[dim]Examples:[/dim]\n" - "[dim] tito milestone status --detailed[/dim]\n" - "[dim] tito milestone timeline --horizontal[/dim]\n" - "[dim] tito milestone test 2[/dim]\n" - "[dim] tito milestone demo 1[/dim]", - title="๐ŸŽฎ Milestone System", + "[dim] tito milestone list[/dim]\n" + "[dim] tito milestone run 03[/dim]\n" + "[dim] tito milestone info 03[/dim]\n" + "[dim] tito milestone status --detailed[/dim]", + title="๐Ÿ† Milestone System", border_style="bright_cyan" )) return 0 - + # Execute the appropriate subcommand - if args.milestone_command == 'status': + if args.milestone_command == 'list': + return self._handle_list_command(args) + elif args.milestone_command == 'run': + return self._handle_run_command(args) + elif args.milestone_command == 'info': + return self._handle_info_command(args) + elif args.milestone_command == 'status': return self._handle_status_command(args) elif args.milestone_command == 'timeline': return self._handle_timeline_command(args) @@ -726,5 +842,371 @@ class MilestoneCommand(BaseCommand): border_style="red" )) return 1 - - return 0 \ No newline at end of file + + return 0 + + def _handle_list_command(self, args: Namespace) -> int: + """Handle milestone list command - show available milestones.""" + console = self.console + + console.print(Panel( + "[bold cyan]๐Ÿ† TinyTorch Milestones[/bold cyan]\n\n" + "[dim]Recreate ML history from 1957 to 2018[/dim]", + title="Available Milestones", + border_style="bright_cyan" + )) + + # Check module completion status + progress_file = Path(".tito") / "progress.json" + completed_modules = [] + if progress_file.exists(): + try: + with open(progress_file, 'r') as f: + progress_data = json.load(f) + completed_modules = progress_data.get("completed_modules", []) + except (json.JSONDecodeError, IOError): + pass + + # Check milestone completion + milestone_progress = self._get_milestone_progress_data() + completed_milestones = milestone_progress.get("completed_milestones", []) + + for milestone_id in sorted(MILESTONE_SCRIPTS.keys()): + milestone = MILESTONE_SCRIPTS[milestone_id] + + # Check if prerequisites met + prereqs_met = all(mod in completed_modules for mod in milestone["required_modules"]) + is_complete = milestone_id in completed_milestones + + # Status indicator + if is_complete: + status_icon = "โœ…" + status_color = "green" + status_text = "COMPLETE" + elif prereqs_met: + status_icon = "๐ŸŽฏ" + status_color = "yellow" + status_text = "READY TO RUN" + else: + status_icon = "๐Ÿ”’" + status_color = "dim" + status_text = "LOCKED" + + # Build display + if args.simple: + console.print(f"[{status_color}]{status_icon} {milestone['id']} - {milestone['name']}[/{status_color}]") + else: + milestone_display = ( + f"[{status_color}]{status_icon} {milestone['emoji']} {milestone['name']}[/{status_color}]\n" + f"[bold]{milestone['title']}[/bold]\n" + f"[dim]{milestone['description']}[/dim]\n" + f"[dim]Historical: {milestone['historical_context']}[/dim]\n\n" + ) + + if prereqs_met and not is_complete: + milestone_display += f"[bold yellow]โ–ถ Run now:[/bold yellow] [cyan]tito milestone run {milestone_id}[/cyan]\n" + elif not prereqs_met: + missing = [str(m) for m in milestone["required_modules"] if m not in completed_modules] + milestone_display += f"[dim]Required: Complete modules {', '.join(missing)}[/dim]\n" + + console.print(Panel( + milestone_display.strip(), + title=f"Milestone {milestone['id']} ({milestone['year']})", + border_style=status_color + )) + + return 0 + + def _handle_run_command(self, args: Namespace) -> int: + """Handle milestone run command - run a milestone with checks.""" + console = self.console + milestone_id = args.milestone_id + + # Validate milestone ID + if milestone_id not in MILESTONE_SCRIPTS: + console.print(Panel( + f"[red]Invalid milestone ID: {milestone_id}[/red]\n\n" + f"Valid milestone IDs: {', '.join(sorted(MILESTONE_SCRIPTS.keys()))}", + title="Invalid Milestone", + border_style="red" + )) + return 1 + + milestone = MILESTONE_SCRIPTS[milestone_id] + + # Check if script exists + script_path = Path(milestone["script"]) + if not script_path.exists(): + console.print(Panel( + f"[red]Milestone script not found![/red]\n\n" + f"Expected: {milestone['script']}\n" + f"[dim]This milestone may not be implemented yet.[/dim]", + title="Script Not Found", + border_style="red" + )) + return 1 + + # Check prerequisites (unless skipped) + completed_modules = [] + if not args.skip_checks: + console.print(f"\n[bold cyan]๐Ÿ” Checking prerequisites for Milestone {milestone_id}...[/bold cyan]\n") + + # Load module completion status + progress_file = Path(".tito") / "progress.json" + if progress_file.exists(): + try: + with open(progress_file, 'r') as f: + progress_data = json.load(f) + completed_modules = progress_data.get("completed_modules", []) + except (json.JSONDecodeError, IOError): + pass + + # Check each required module + missing_modules = [] + for module_num in milestone["required_modules"]: + if module_num in completed_modules: + console.print(f" [green]โœ“[/green] Module {module_num:02d} - complete") + else: + console.print(f" [red]โœ—[/red] Module {module_num:02d} - NOT complete") + missing_modules.append(module_num) + + if missing_modules: + console.print(Panel( + f"[bold yellow]โŒ Missing Required Modules[/bold yellow]\n\n" + f"[yellow]Milestone {milestone_id} requires modules: {', '.join(f'{m:02d}' for m in milestone['required_modules'])}[/yellow]\n" + f"[red]Missing: {', '.join(f'{m:02d}' for m in missing_modules)}[/red]\n\n" + f"[cyan]Complete the missing modules first:[/cyan]\n" + + "\n".join(f"[dim] tito module start {m:02d}[/dim]" for m in missing_modules[:3]), + title="Prerequisites Not Met", + border_style="yellow" + )) + return 1 + + console.print(f"\n[green]โœ… All prerequisites met![/green]\n") + + # Test imports work + console.print("[bold cyan]๐Ÿงช Testing YOUR implementations...[/bold cyan]\n") + + # Try importing key components (basic check) + try: + import sys as _sys + _sys.path.insert(0, str(Path.cwd())) + + if 1 in milestone["required_modules"]: + from tinytorch import Tensor + console.print(" [green]โœ“[/green] Tensor import successful") + + if 2 in milestone["required_modules"]: + from tinytorch import ReLU + console.print(" [green]โœ“[/green] Activations import successful") + + if 3 in milestone["required_modules"]: + from tinytorch import Linear + console.print(" [green]โœ“[/green] Layers import successful") + + console.print(f"\n[green]โœ… YOUR TinyTorch is ready![/green]\n") + + except ImportError as e: + console.print(Panel( + f"[red]Import Error![/red]\n\n" + f"[yellow]Error: {e}[/yellow]\n\n" + f"[dim]Your modules may not be exported correctly.[/dim]\n" + f"[dim]Try re-exporting: tito module complete XX[/dim]", + title="Import Test Failed", + border_style="red" + )) + return 1 + + # Show milestone banner + console.print(Panel( + f"[bold magenta]โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—[/bold magenta]\n" + f"[bold magenta]โ•‘[/bold magenta] {milestone['emoji']} Milestone {milestone_id}: {milestone['name']:<30} [bold magenta]โ•‘[/bold magenta]\n" + f"[bold magenta]โ•‘[/bold magenta] {milestone['title']:<44} [bold magenta]โ•‘[/bold magenta]\n" + f"[bold magenta]โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•[/bold magenta]\n\n" + f"[bold]๐Ÿ“š Historical Context:[/bold]\n" + f"{milestone['historical_context']}\n\n" + f"[bold]๐ŸŽฏ What You'll Do:[/bold]\n" + f"{milestone['description']}\n\n" + f"[bold]๐Ÿ“‚ Running:[/bold] {milestone['script']}\n\n" + f"[dim]All code uses YOUR TinyTorch implementations![/dim]", + title=f"๐Ÿ† Milestone {milestone_id} ({milestone['year']})", + border_style="bright_magenta", + padding=(1, 2) + )) + + input("\n[yellow]Press Enter to begin...[/yellow] ") + + # Run the milestone script + console.print(f"\n[bold green]๐Ÿš€ Starting Milestone {milestone_id}...[/bold green]\n") + console.print("โ”" * 80 + "\n") + + try: + result = subprocess.run( + [sys.executable, str(script_path)], + capture_output=False, + text=True + ) + + console.print("\n" + "โ”" * 80) + + if result.returncode == 0: + # Success! Mark milestone as complete + self._mark_milestone_complete(milestone_id) + + console.print(Panel( + f"[bold green]๐Ÿ† MILESTONE ACHIEVED![/bold green]\n\n" + f"[green]You completed Milestone {milestone_id}: {milestone['name']}[/green]\n" + f"[yellow]{milestone['title']}[/yellow]\n\n" + f"[bold]What makes this special:[/bold]\n" + f"โ€ข Every line of code: YOUR implementations\n" + f"โ€ข Every tensor operation: YOUR Tensor class\n" + f"โ€ข Every gradient: YOUR autograd\n\n" + f"[cyan]Achievement saved to your progress![/cyan]", + title="โœจ Achievement Unlocked โœจ", + border_style="bright_green", + padding=(1, 2) + )) + + # Show next steps + next_id = str(int(milestone_id) + 1).zfill(2) + if next_id in MILESTONE_SCRIPTS: + next_milestone = MILESTONE_SCRIPTS[next_id] + console.print(f"\n[bold yellow]๐ŸŽฏ What's Next:[/bold yellow]") + console.print(f"[dim]Milestone {next_id}: {next_milestone['name']} ({next_milestone['year']})[/dim]") + + # Check if unlocked + missing = [m for m in next_milestone["required_modules"] if m not in completed_modules] + if missing: + console.print(f"[dim]Unlock by completing modules: {', '.join(f'{m:02d}' for m in missing[:3])}[/dim]") + else: + console.print(f"[green]Ready to run: tito milestone run {next_id}[/green]") + + return 0 + else: + console.print(f"[yellow]โš ๏ธ Milestone completed with errors (exit code: {result.returncode})[/yellow]") + return result.returncode + + except KeyboardInterrupt: + console.print(f"\n\n[yellow]โš ๏ธ Milestone interrupted by user[/yellow]") + return 130 + except Exception as e: + console.print(Panel( + f"[red]โŒ Error running milestone: {e}[/red]\n\n" + f"[dim]You can try running manually:[/dim]\n" + f"[dim]python {milestone['script']}[/dim]", + title="Execution Error", + border_style="red" + )) + return 1 + + def _handle_info_command(self, args: Namespace) -> int: + """Handle milestone info command - show detailed information.""" + console = self.console + milestone_id = args.milestone_id + + if milestone_id not in MILESTONE_SCRIPTS: + console.print(Panel( + f"[red]Invalid milestone ID: {milestone_id}[/red]\n\n" + f"Valid milestone IDs: {', '.join(sorted(MILESTONE_SCRIPTS.keys()))}", + title="Invalid Milestone", + border_style="red" + )) + return 1 + + milestone = MILESTONE_SCRIPTS[milestone_id] + + # Check status + progress_file = Path(".tito") / "progress.json" + completed_modules = [] + if progress_file.exists(): + try: + with open(progress_file, 'r') as f: + progress_data = json.load(f) + completed_modules = progress_data.get("completed_modules", []) + except: + pass + + prereqs_met = all(m in completed_modules for m in milestone["required_modules"]) + + # Display detailed info + info_text = ( + f"[bold cyan]{milestone['emoji']} {milestone['name']} ({milestone['year']})[/bold cyan]\n\n" + f"[bold]{milestone['title']}[/bold]\n\n" + f"[yellow]๐Ÿ“š Historical Context:[/yellow]\n" + f"{milestone['historical_context']}\n\n" + f"[yellow]๐ŸŽฏ Description:[/yellow]\n" + f"{milestone['description']}\n\n" + f"[yellow]๐Ÿ“‹ Required Modules:[/yellow]\n" + ) + + for mod in milestone["required_modules"]: + if mod in completed_modules: + info_text += f" [green]โœ“[/green] Module {mod:02d}\n" + else: + info_text += f" [red]โœ—[/red] Module {mod:02d}\n" + + info_text += f"\n[yellow]๐Ÿ“‚ Script:[/yellow] {milestone['script']}\n" + + if prereqs_met: + info_text += f"\n[bold green]โœ… Ready to run![/bold green]\n[cyan]tito milestone run {milestone_id}[/cyan]" + else: + missing = [m for m in milestone["required_modules"] if m not in completed_modules] + info_text += f"\n[bold yellow]๐Ÿ”’ Locked[/bold yellow]\nComplete modules: {', '.join(f'{m:02d}' for m in missing)}" + + console.print(Panel( + info_text, + title=f"Milestone {milestone_id} Information", + border_style="bright_cyan", + padding=(1, 2) + )) + + return 0 + + def _mark_milestone_complete(self, milestone_id: str) -> None: + """Mark a milestone as complete in progress tracking.""" + progress = self._get_milestone_progress_data() + + if milestone_id not in progress.get("completed_milestones", []): + if "completed_milestones" not in progress: + progress["completed_milestones"] = [] + progress["completed_milestones"].append(milestone_id) + progress["completion_dates"] = progress.get("completion_dates", {}) + progress["completion_dates"][milestone_id] = datetime.now().isoformat() + + self._save_milestone_progress_data(progress) + + def _get_milestone_progress_data(self) -> dict: + """Get or create milestone progress data.""" + progress_dir = Path(".tito") + progress_file = progress_dir / "milestones.json" + + progress_dir.mkdir(exist_ok=True) + + if progress_file.exists(): + try: + with open(progress_file, 'r') as f: + return json.load(f) + except (json.JSONDecodeError, IOError): + pass + + return { + "completed_milestones": [], + "completion_dates": {}, + "unlocked_milestones": [], + "unlock_dates": {}, + "total_unlocked": 0, + "achievements": [] + } + + def _save_milestone_progress_data(self, milestone_data: dict) -> None: + """Save milestone progress data.""" + progress_dir = Path(".tito") + progress_file = progress_dir / "milestones.json" + + progress_dir.mkdir(exist_ok=True) + + try: + with open(progress_file, 'w') as f: + json.dump(milestone_data, f, indent=2) + except IOError: + pass \ No newline at end of file diff --git a/tito/commands/reset.py b/tito/commands/reset.py index 2a6ef833..e6c51e62 100644 --- a/tito/commands/reset.py +++ b/tito/commands/reset.py @@ -1,8 +1,10 @@ """ -Reset command for TinyTorch CLI: resets tinytorch package to clean state. +Reset command for TinyTorch CLI: resets package and user data. """ +import json import shutil +from datetime import datetime from argparse import ArgumentParser, Namespace from pathlib import Path from rich.panel import Panel @@ -17,43 +19,123 @@ class ResetCommand(BaseCommand): @property def description(self) -> str: - return "Reset tinytorch package to clean state" + return "Reset package files or user progress data" def add_arguments(self, parser: ArgumentParser) -> None: - parser.add_argument("--force", action="store_true", help="Skip confirmation prompt") + subparsers = parser.add_subparsers( + dest='reset_command', + help='Reset subcommands', + metavar='SUBCOMMAND' + ) + + # Package reset (original functionality) + package_parser = subparsers.add_parser( + 'package', + help='Reset tinytorch package to clean state (remove exported files)' + ) + package_parser.add_argument("--force", action="store_true", help="Skip confirmation prompt") + + # All data reset + all_parser = subparsers.add_parser( + 'all', + help='Reset all user progress (modules + milestones + config)' + ) + all_parser.add_argument("--backup", action="store_true", help="Create backup before reset") + all_parser.add_argument("--force", action="store_true", help="Skip confirmation prompt") + + # Progress reset + progress_parser = subparsers.add_parser( + 'progress', + help='Reset module completion tracking only' + ) + progress_parser.add_argument("--backup", action="store_true", help="Create backup before reset") + progress_parser.add_argument("--force", action="store_true", help="Skip confirmation prompt") + + # Milestones reset + milestones_parser = subparsers.add_parser( + 'milestones', + help='Reset milestone achievements only' + ) + milestones_parser.add_argument("--backup", action="store_true", help="Create backup before reset") + milestones_parser.add_argument("--force", action="store_true", help="Skip confirmation prompt") + + # Config reset + config_parser = subparsers.add_parser( + 'config', + help='Reset configuration to defaults' + ) + config_parser.add_argument("--force", action="store_true", help="Skip confirmation prompt") def run(self, args: Namespace) -> int: console = self.console - - console.print(Panel("๐Ÿ”„ Resetting TinyTorch Package", + + if not hasattr(args, 'reset_command') or not args.reset_command: + console.print(Panel( + "[bold cyan]Reset Commands[/bold cyan]\n\n" + "Available subcommands:\n" + " โ€ข [bold]package[/bold] - Reset tinytorch package (remove exported files)\n" + " โ€ข [bold]all[/bold] - Reset all user progress (modules + milestones + config)\n" + " โ€ข [bold]progress[/bold] - Reset module completion tracking only\n" + " โ€ข [bold]milestones[/bold] - Reset milestone achievements only\n" + " โ€ข [bold]config[/bold] - Reset configuration to defaults\n\n" + "[dim]Example: tito reset progress --backup[/dim]", + title="Reset Command Group", + border_style="bright_yellow" + )) + return 0 + + # Execute the appropriate subcommand + if args.reset_command == 'package': + return self._reset_package(args) + elif args.reset_command == 'all': + return self._reset_all(args) + elif args.reset_command == 'progress': + return self._reset_progress(args) + elif args.reset_command == 'milestones': + return self._reset_milestones(args) + elif args.reset_command == 'config': + return self._reset_config(args) + else: + console.print(Panel( + f"[red]Unknown reset subcommand: {args.reset_command}[/red]", + title="Error", + border_style="red" + )) + return 1 + + def _reset_package(self, args: Namespace) -> int: + """Reset tinytorch package (original functionality).""" + console = self.console + + console.print(Panel("๐Ÿ”„ Resetting TinyTorch Package", title="Package Reset", border_style="bright_yellow")) - + tinytorch_path = Path("tinytorch") - + if not tinytorch_path.exists(): - console.print(Panel("[yellow]โš ๏ธ TinyTorch package directory not found. Nothing to reset.[/yellow]", + console.print(Panel("[yellow]โš ๏ธ TinyTorch package directory not found. Nothing to reset.[/yellow]", title="Nothing to Reset", border_style="yellow")) return 0 - + # Ask for confirmation unless --force is used - if not (hasattr(args, 'force') and args.force): + if not args.force: console.print("\n[yellow]This will remove all exported Python files from the tinytorch package.[/yellow]") console.print("[yellow]Notebooks in modules/ will be preserved.[/yellow]\n") - + try: response = input("Are you sure you want to reset? (y/N): ").strip().lower() if response not in ['y', 'yes']: - console.print(Panel("[cyan]Reset cancelled.[/cyan]", + console.print(Panel("[cyan]Reset cancelled.[/cyan]", title="Cancelled", border_style="cyan")) return 0 except KeyboardInterrupt: - console.print(Panel("[cyan]Reset cancelled.[/cyan]", + console.print(Panel("[cyan]Reset cancelled.[/cyan]", title="Cancelled", border_style="cyan")) return 0 - + reset_text = Text() reset_text.append("๐Ÿ—‘๏ธ Removing all exported files:\n", style="bold red") - + # Simple approach: remove all .py files except __init__.py files_removed = 0 for py_file in tinytorch_path.rglob("*.py"): @@ -65,29 +147,230 @@ class ResetCommand(BaseCommand): files_removed += 1 except Exception as e: reset_text.append(f" โŒ Failed to remove {py_file}: {e}\n", style="red") - + # Remove __pycache__ directories for pycache in tinytorch_path.rglob("__pycache__"): if pycache.is_dir(): reset_text.append(f" ๐Ÿ—‘๏ธ {pycache}/\n", style="red") shutil.rmtree(pycache) - + # Remove .pytest_cache if it exists pytest_cache = Path(".pytest_cache") if pytest_cache.exists(): reset_text.append(f" ๐Ÿ—‘๏ธ .pytest_cache/\n", style="red") shutil.rmtree(pytest_cache) - + if files_removed > 0: reset_text.append(f"\nโœ… Reset complete! Removed {files_removed} generated files.\n", style="bold green") reset_text.append("\n๐Ÿ’ก Next steps:\n", style="bold yellow") - reset_text.append(" โ€ข Run: tito module export --all - Re-export modules\n", style="white") - reset_text.append(" โ€ข Run: tito module export --module setup - Export specific module\n", style="white") - reset_text.append(" โ€ข Run: tito module test --all - Test everything\n", style="white") - + reset_text.append(" โ€ข Run: tito module complete 01 - Re-export modules\n", style="white") + console.print(Panel(reset_text, title="Reset Complete", border_style="green")) else: - console.print(Panel("[yellow]No generated files found to remove.[/yellow]", + console.print(Panel("[yellow]No generated files found to remove.[/yellow]", title="Nothing to Reset", border_style="yellow")) - - return 0 \ No newline at end of file + + return 0 + + def _create_backup(self) -> Path: + """Create timestamped backup of .tito folder.""" + console = self.console + timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") + backup_dir = Path(f".tito_backup_{timestamp}") + + tito_dir = Path(".tito") + if tito_dir.exists(): + shutil.copytree(tito_dir, backup_dir) + console.print(f"[green]โœ… Backup created: {backup_dir}[/green]") + + return backup_dir + + def _reset_all(self, args: Namespace) -> int: + """Reset all user progress data.""" + console = self.console + + # Ask for confirmation + if not args.force: + console.print("\n[bold red]โš ๏ธ Warning: This will reset ALL progress[/bold red]\n") + console.print("[yellow]This will clear:[/yellow]") + console.print(" โ€ข Module completion tracking") + console.print(" โ€ข Milestone achievements") + console.print(" โ€ข Configuration settings\n") + console.print("[dim]Your code in modules/ will NOT be deleted.[/dim]\n") + + try: + response = input("Continue? (y/N): ").strip().lower() + if response not in ['y', 'yes']: + console.print(Panel("[cyan]Reset cancelled.[/cyan]", + title="Cancelled", border_style="cyan")) + return 0 + except KeyboardInterrupt: + console.print(Panel("\n[cyan]Reset cancelled.[/cyan]", + title="Cancelled", border_style="cyan")) + return 0 + + # Create backup if requested + if args.backup: + self._create_backup() + + # Reset all data files + tito_dir = Path(".tito") + tito_dir.mkdir(parents=True, exist_ok=True) + + # Reset progress.json + progress_file = tito_dir / "progress.json" + progress_file.write_text(json.dumps({ + "version": "1.0", + "completed_modules": [], + "completion_dates": {} + }, indent=2)) + + # Reset milestones.json + milestones_file = tito_dir / "milestones.json" + milestones_file.write_text(json.dumps({ + "version": "1.0", + "completed_milestones": [], + "completion_dates": {} + }, indent=2)) + + # Reset config.json + config_file = tito_dir / "config.json" + config_file.write_text(json.dumps({ + "logo_theme": "standard" + }, indent=2)) + + console.print(Panel( + "[green]โœ… All progress reset![/green]\n\n" + "You're ready to start fresh.\\n" + "Run: [cyan]tito module start 01[/cyan]", + title="๐Ÿ”„ Reset Complete", + border_style="green" + )) + + return 0 + + def _reset_progress(self, args: Namespace) -> int: + """Reset module completion tracking only.""" + console = self.console + + # Ask for confirmation + if not args.force: + console.print("\n[bold yellow]โš ๏ธ This will reset module completion tracking[/bold yellow]\n") + console.print("[dim]Milestone achievements will be preserved.[/dim]\n") + + try: + response = input("Continue? (y/N): ").strip().lower() + if response not in ['y', 'yes']: + console.print(Panel("[cyan]Reset cancelled.[/cyan]", + title="Cancelled", border_style="cyan")) + return 0 + except KeyboardInterrupt: + console.print(Panel("\n[cyan]Reset cancelled.[/cyan]", + title="Cancelled", border_style="cyan")) + return 0 + + # Create backup if requested + if args.backup: + self._create_backup() + + # Reset progress.json + tito_dir = Path(".tito") + tito_dir.mkdir(parents=True, exist_ok=True) + + progress_file = tito_dir / "progress.json" + progress_file.write_text(json.dumps({ + "version": "1.0", + "completed_modules": [], + "completion_dates": {} + }, indent=2)) + + console.print(Panel( + "[green]โœ… Module progress reset![/green]\n\n" + "You can re-complete modules with:\\n" + "[cyan]tito module complete XX[/cyan]", + title="๐Ÿ”„ Progress Reset", + border_style="green" + )) + + return 0 + + def _reset_milestones(self, args: Namespace) -> int: + """Reset milestone achievements only.""" + console = self.console + + # Ask for confirmation + if not args.force: + console.print("\n[bold yellow]โš ๏ธ This will reset milestone achievements[/bold yellow]\n") + console.print("[dim]Module completion will be preserved.[/dim]\n") + + try: + response = input("Continue? (y/N): ").strip().lower() + if response not in ['y', 'yes']: + console.print(Panel("[cyan]Reset cancelled.[/cyan]", + title="Cancelled", border_style="cyan")) + return 0 + except KeyboardInterrupt: + console.print(Panel("\n[cyan]Reset cancelled.[/cyan]", + title="Cancelled", border_style="cyan")) + return 0 + + # Create backup if requested + if args.backup: + self._create_backup() + + # Reset milestones.json + tito_dir = Path(".tito") + tito_dir.mkdir(parents=True, exist_ok=True) + + milestones_file = tito_dir / "milestones.json" + milestones_file.write_text(json.dumps({ + "version": "1.0", + "completed_milestones": [], + "completion_dates": {} + }, indent=2)) + + console.print(Panel( + "[green]โœ… Milestone achievements reset![/green]\n\n" + "You can re-run milestones with:\\n" + "[cyan]tito milestone run XX[/cyan]", + title="๐Ÿ”„ Milestones Reset", + border_style="green" + )) + + return 0 + + def _reset_config(self, args: Namespace) -> int: + """Reset configuration to defaults.""" + console = self.console + + # Ask for confirmation + if not args.force: + console.print("\n[bold yellow]โš ๏ธ This will reset configuration to defaults[/bold yellow]\n") + + try: + response = input("Continue? (y/N): ").strip().lower() + if response not in ['y', 'yes']: + console.print(Panel("[cyan]Reset cancelled.[/cyan]", + title="Cancelled", border_style="cyan")) + return 0 + except KeyboardInterrupt: + console.print(Panel("\n[cyan]Reset cancelled.[/cyan]", + title="Cancelled", border_style="cyan")) + return 0 + + # Reset config.json + tito_dir = Path(".tito") + tito_dir.mkdir(parents=True, exist_ok=True) + + config_file = tito_dir / "config.json" + config_file.write_text(json.dumps({ + "logo_theme": "standard" + }, indent=2)) + + console.print(Panel( + "[green]โœ… Configuration reset to defaults![/green]", + title="๐Ÿ”„ Config Reset", + border_style="green" + )) + + return 0 diff --git a/tito/commands/status.py b/tito/commands/status.py index 032f5f6e..afbf9786 100644 --- a/tito/commands/status.py +++ b/tito/commands/status.py @@ -29,6 +29,8 @@ class StatusCommand(BaseCommand): return "Check status of all modules" def add_arguments(self, parser: ArgumentParser) -> None: + parser.add_argument("--progress", action="store_true", help="Show user progress (modules + milestones) - DEFAULT") + parser.add_argument("--files", action="store_true", help="Show file structure and module status") parser.add_argument("--details", action="store_true", help="Show detailed file structure") parser.add_argument("--metadata", action="store_true", help="Show module metadata information") parser.add_argument("--test-status", action="store_true", help="Include test execution status (slower)") @@ -86,14 +88,137 @@ class StatusCommand(BaseCommand): def run(self, args: Namespace) -> int: console = self.console - + # Handle comprehensive analysis mode if args.comprehensive: return self._run_comprehensive_analysis() - - # Standard status check mode + + # Handle progress view (default if no flags, or --progress) + if not args.files and not args.details and not args.metadata and not args.test_status: + return self._run_progress_view() + + if args.progress: + return self._run_progress_view() + + # Standard file status check mode return self._run_standard_status(args) + def _run_progress_view(self) -> int: + """Show unified user progress view (modules + milestones).""" + console = self.console + import json + from datetime import datetime + + # Load progress data + progress_file = Path(".tito") / "progress.json" + milestones_file = Path(".tito") / "milestones.json" + + # Load module progress + if progress_file.exists(): + progress_data = json.loads(progress_file.read_text()) + completed_modules = progress_data.get("completed_modules", []) + completion_dates = progress_data.get("completion_dates", {}) + else: + completed_modules = [] + completion_dates = {} + + # Load milestone achievements + if milestones_file.exists(): + milestones_data = json.loads(milestones_file.read_text()) + completed_milestones = milestones_data.get("completed_milestones", []) + milestone_dates = milestones_data.get("completion_dates", {}) + else: + completed_milestones = [] + milestone_dates = {} + + # Calculate progress percentages + total_modules = 20 + total_milestones = 6 + modules_percent = int((len(completed_modules) / total_modules) * 100) + milestones_percent = int((len(completed_milestones) / total_milestones) * 100) + + # Create summary panel + summary_text = Text() + summary_text.append(f"๐Ÿ“ฆ Modules Completed: ", style="bold") + summary_text.append(f"{len(completed_modules)}/{total_modules} ({modules_percent}%)\n", style="cyan") + summary_text.append(f"๐Ÿ† Milestones Achieved: ", style="bold") + summary_text.append(f"{len(completed_milestones)}/{total_milestones} ({milestones_percent}%)\n\n", style="magenta") + + # Last activity + all_dates = list(completion_dates.values()) + list(milestone_dates.values()) + if all_dates: + latest_date = max(all_dates) + summary_text.append("๐Ÿ“ Last Activity: ", style="bold") + summary_text.append(f"{latest_date}\n", style="dim") + + console.print(Panel( + summary_text, + title="๐Ÿ“Š TinyTorch Progress", + border_style="bright_cyan" + )) + + # Module Progress Table + if completed_modules: + console.print("\n[bold]Module Progress:[/bold]") + for i in range(1, total_modules + 1): + mod_num = i + if mod_num in completed_modules: + module_name = self._get_module_name(mod_num) + console.print(f" [green]โœ… {mod_num:02d} {module_name}[/green]") + elif i <= len(completed_modules) + 3: # Show next few modules + module_name = self._get_module_name(mod_num) + console.print(f" [dim]๐Ÿ”’ {mod_num:02d} {module_name}[/dim]") + + # Milestone Achievements + if completed_milestones or (completed_modules and len(completed_modules) >= 1): + console.print("\n[bold]Milestone Achievements:[/bold]") + milestone_names = { + "01": "Perceptron (1957)", + "02": "Backpropagation (1986)", + "03": "MLP Revival (1986)", + "04": "CNN Revolution (1998)", + "05": "Transformer Era (2017)", + "06": "MLPerf (2018)" + } + for mid in ["01", "02", "03", "04", "05", "06"]: + if mid in completed_milestones: + console.print(f" [magenta]โœ… {mid} - {milestone_names[mid]}[/magenta]") + else: + # Check if ready + prereqs_met = self._check_milestone_prereqs(mid, completed_modules) + if prereqs_met: + console.print(f" [yellow]๐ŸŽฏ {mid} - {milestone_names[mid]} [Ready!][/yellow]") + else: + console.print(f" [dim]๐Ÿ”’ {mid} - {milestone_names[mid]}[/dim]") + + console.print() + return 0 + + def _get_module_name(self, module_num: int) -> str: + """Get module name from number.""" + module_names = { + 1: "Tensor", 2: "Activations", 3: "Layers", 4: "Losses", + 5: "Autograd", 6: "Optimizers", 7: "Training", 8: "DataLoader", + 9: "Convolutions", 10: "Normalization", 11: "Tokenization", + 12: "Embeddings", 13: "Attention", 14: "Transformers", + 15: "Profiling", 16: "Quantization", 17: "Compression", + 18: "Memoization", 19: "Benchmarking", 20: "Capstone" + } + return module_names.get(module_num, "Unknown") + + def _check_milestone_prereqs(self, milestone_id: str, completed_modules: list) -> bool: + """Check if milestone prerequisites are met.""" + prereqs = { + "01": [1], + "02": [1, 2, 3, 4, 5], + "03": [1, 2, 3, 4, 5, 6, 7], + "04": [1, 2, 3, 4, 5, 6, 7, 8, 9], + "05": [1, 2, 3, 4, 5, 6, 7, 11, 12, 13, 14], + "06": [1, 2, 3, 4, 5, 6, 7, 8, 9, 15, 16, 19] + } + required = prereqs.get(milestone_id, []) + return all(mod in completed_modules for mod in required) + def _run_comprehensive_analysis(self) -> int: """Run comprehensive system health dashboard.""" console = self.console