Audits and refactors Volume 2 chapters to ensure all Python calculation cells adhere to the P.I.C.O. (Parameters, Invariants, Calculation, Outputs) standard.
- Consolidates storage specifications and economics into StorageSetup and StorageEconomics classes in data_storage.qmd.
- Refactors collective communication math into the AllReduceCost class in collective_communication.qmd.
- Standardizes infrastructure and performance engineering setups in compute_infrastructure.qmd and performance_engineering.qmd.
- Corrects NameErrors and missing imports in benchmarking and platform ROI calculations.
- Ensures all prose variables are correctly exported and scoped within Safe Class Namespaces to prevent global pollution and ensure mathematical consistency across the fleet-scale narrative.
Audits all Volume 1 chapters to identify and repair structural errors in Python calculation cells introduced during the P.I.C.O. refactor.
- Consolidates redundant memory calculations and fixes missing imports in nn_computation.qmd.
- Refactors AttentionMemory in nn_architectures.qmd to resolve NameErrors and duplicated blocks.
- Cleans up QuantizationSpeedup and restores MobileNetCompressionAnchor in model_compression.qmd.
- Resolves missing Models and Hardware imports in benchmarking.qmd.
- Updates LighthouseModels in ml_systems.qmd with missing variables for MobileNet and KWS.
- Corrects indentation and structural integrity across all Volume 1 calculation scenarios to ensure valid rendering and mathematical consistency.
Refines the explanation of K,V computation savings in the memoization module,
quantifying redundant computations and highlighting the efficiency gain.
The paper and module now specify that generating 100 tokens requires 5,050
total K,V computations, but only 100 are necessary, resulting in 4,950
redundant calculations.
Restructures Volume II to improve narrative flow and address scale impediments, including reordering of sections and addition of introductory material.
Introduces "Master Map" to guide readers through the volume's layered progression.
Adds callout notes to bridge concepts between sections.
Moves references.qmd to backmatter and adjusts chapter organization for clarity.
Updates hardware parameterization and network performance modeling within code blocks.
Deepens understanding of abstract principles by adding concrete examples and numerical anchors.
These additions provide tangible context and illustrate the practical implications of the discussed concepts, which aids in comprehension and application. It also adds context to constraints, economics and performance.
Updates concept map YAML files for various chapters in volume 1, including introduction, benchmarking, data engineering, data selection, frameworks, hardware acceleration, ML systems, MLOps, ML workflow, model serving, NN architectures, NN computation, optimizations, responsible engineering, and training.
Replaces the old YAML structure with a new structure that focuses on primary, secondary concepts, technical terms, methodologies, and formulas. The change emphasizes the core concepts and their relationships within each chapter. The generated dates are updated to reflect a future date.
Insert thesis declarations, spine reconnections, and evidence elevations
that make the book's central claim explicit: ML systems engineering is a
distinct discipline governed by permanent physical laws. No restructuring
or deletions; insertions only, matching the surrounding rhetorical register.
ngbolin was correctly added to tinytorch (PR #1180) but the edited-comment
re-trigger on PR #1181 ran the old LLM code which hallucinated ngbolin as
the username instead of pipme.
The LLM (llama3.1:8b) was hallucinating usernames — e.g. returning
"pipmea" instead of "pipme". Since the username is always present as
an @mention in the trigger line, extract it deterministically via regex
in Step 1 and only use the LLM to classify contribution types.
- Remove 17 empty per-chapter .bib files (all contained only newlines)
- Consolidate HTML and EPUB configs to use central backmatter/references.bib
(matching the pattern already used by PDF configs and Vol1)
- Rename responsible_engineering/ to responsible_ai/ for consistency with
robust_ai/ and sustainable_ai/ in Part IV: The Responsible Fleet
- Update all 4 Quarto config files with new path
Major structural reorganization of Volume II:
- New 4-part structure: The Fleet, Distributed ML, Deployment at Scale, The Responsible Fleet
- Fleet Stack framework (Infrastructure/Distribution/Serving/Governance) replaces Systems Sandwich
- Renamed and reorganized 8 chapter directories to match new structure
- Absorbed ai_good/ into responsible_engineering and emerging_challenges/ into introduction
- Wrote/expanded 6 new chapters (collective_communication, compute_infrastructure,
fleet_orchestration, network_fabrics, data_systems, performance_engineering)
- Fixed 116+ broken @sec- cross-references across all 16 chapters and glossary
- Updated all 4 Quarto config files, part-openers, and summaries.yml
- Added \mlfleetstack LaTeX command for PDF rendering
- Removed old 5-part HTML artifacts and macOS resource fork files
- Converted grid tables to pipe tables in fleet_orchestration
- Fixed inline Python in display math blocks in collective_communication
- Resolved duplicate tbl-tco-comparison label and stale part key reference
- Add war story callout definition in custom-numbered-blocks.yml
- Create war story icon in all three formats (SVG, PNG, PDF) matching
the 64x64 stroke-only style used by all other callout icons
- Add war story bibliography and PDF config entry
- Add first war story ("The Quadratic Wall") in nn_architectures
- Include icon conversion utility script
Aligns the Distributed Training chapter with the Volume 2 'Systems Sandwich'
framework, establishing it as the 'Operational Layer' of the Machine Learning Fleet.
Key changes:
- Refactors 'Purpose' and 'Learning Objectives' to use rhetorical pivots and
focus on the 'Physics of the Fleet'.
- Updates Python setup cell to use the 'Safe Class Namespace' pattern (P.I.C.O.)
and adds Archetype A (GPT-4) constants.
- Rewrites 'Multi-Machine Scaling Fundamentals' to center on the
'Communication-Computation Ratio' and the 'Law of Distributed Efficiency'.
- Cross-references the Volume 2 Introduction definitions to create a cohesive narrative.
Aligns the rhetorical style and quantitative rigor of the Volume 2
Introduction with the established Volume 1 standards.
Introduces the "Machine Learning Fleet" narrative as the central
engineering challenge of Volume 2, shifting from single-node
optimization to cluster-scale orchestration.
Key changes:
- Establishes the "Law of Distributed Efficiency" and "CI Ratio"
(Communication Intensity) as new quantitative frameworks.
- Defines the "Reliability Gap" to address statistical failure
certainty in massive clusters.
- Refactors all TikZ diagrams (Systems Sandwich, Roadmap, AI Triad)
to use project-standard colors and Helvetica font.
- Updates the "Lighthouse Archetypes" to focus on throughput,
latency, and resource-bound fleet challenges.
- Implements P.I.C.O. math patterns for fleet-scale calculations.
Renames and restructures the framework evolution section to
"The Ladder of Abstraction," emphasizing the problem-solving
nature of each abstraction layer.
Clarifies the role of each layer (BLAS/LAPACK, NumPy,
Deep Learning Frameworks) in solving specific problems related
to performance, usability, and differentiation, respectively.
Highlights the trade-offs between productivity and transparency
as we move up the abstraction ladder.
Notebooks use short names (tensor.ipynb, not 01_tensor.ipynb) but docs
and Binder postBuild scripts used the prefixed form. This caused broken
Binder links and incorrect paths in troubleshooting guides.
Fixes: harvard-edge/cs249r_book#1176
Replace hardcoded numerical values across all module ABOUT.md files with
Python-computed values using myst_nb glue() references. Each file is now a
MyST Markdown Notebook that executes inline code cells to compute memory
sizes, FLOPs, compression ratios, and other quantitative values.
Key changes:
- Add file_format: mystnb frontmatter and code-cell blocks to all 20 files
- All arithmetic (memory calculations, speedups, ratios) now computed inline
- Fix multiple arithmetic errors discovered during conversion
- Enable execute_notebooks: "cache" in PDF config for glue resolution
- Fix jupyter-book version constraint in Makefile
Mermaid diagrams were oversized in PDF output. Reduced viewport width
from 800→600 and added LaTeX preamble to cap mermaid figures at
0.75\linewidth. Also fixed 7 admonition blocks across 5 ABOUT.md files
where nested triple-backtick code fences broke the MyST parser, causing
raw markdown to render in PDF output.
- Responsive progressive disclosure: hide date at 1024px, icons-only at 768px
- Add 44px touch targets for mobile nav links
- Restyle version badge with separate number/date spans
- Add link-secondary class for visual hierarchy in navbar
- Add npx pre-flight check for Mermaid CLI in PDF build
- Configure mermaid_cmd to use npx (no global install needed)
- Add Unicode box-drawing fallbacks for LaTeX
- Add Community section to PDF table of contents
Use vscode.openWith(uri, 'jupyter-notebook') for .ipynb files so they
render in VS Code's notebook editor with cell support, rather than
opening as raw JSON text via openTextDocument.
The VS Code extension no longer implements any business logic — every
capability (module discovery, path resolution, system info, builds,
tests, clean) lives in Tito CLI commands. The extension is a pure UI
shell that delegates via `python3 -m tito.main`.
Tito CLI additions:
- `module list --json` for machine-readable module discovery
- `module path <num> --notebook|--source|--about` for file resolution
- `system info --json` for environment info
- `dev build html|serve|pdf|paper` wrapping make targets
- `dev clean [all|site]` wrapping make clean
- Banner suppression for --json and module path output
Extension hardening:
- Centralized CLI integration in utils/tito.ts (single TITO_CMD constant,
callTito, callTitoJson, titoTerminalCommand, isTitoAvailable, log/logError)
- Replaced all silent catch{} blocks with logged errors and user feedback
- Module tree shows error/empty states with actionable Setup/Health buttons
- Info tree shows "Tito CLI unavailable" when CLI is unreachable
- Removed all setTimeout refresh hacks — file watcher on .tito/progress.json
is the sole refresh mechanism
- Exit code tracking via onDidEndTerminalShellExecution
- Tito availability pre-flight check on activation
- BUILD_OUTPUTS constants for build artifact paths
- Zero execSync calls outside tito.ts, zero hardcoded command strings
