github-starred/cs249r_book
2
0
Fork 0
mirror of https://github.com/harvard-edge/cs249r_book.git synced 2026-07-16 23:24:55 -05:00
Code Issues 276 Packages Projects Releases 26 Wiki Activity

[PR #1851] [MERGED] feat(staffml): link each question to recommended textbook reading (topic → chapter) #30953

New Issue
Closed
opened 2026-06-21 20:35:44 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-06-21 20:35:44 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/harvard-edge/cs249r_book/pull/1851
Author: @farhan523
Created: 6/9/2026
Status: ✅ Merged
Merged: 6/16/2026
Merged by: @profvjreddi

Base: dev ← Head: feat/staffml-book-refs

📝 Commits (1)

  • 09fc983 feat(staffml): link each question to recommended textbook reading

📊 Changes

13 files changed (+430 additions, -137 deletions)

View changed files

📝 interviews/staffml/src/app/plans/page.tsx (+2 -2)
📝 interviews/staffml/src/app/practice/page.tsx (+2 -2)
➕ interviews/staffml/src/components/BookRefCard.tsx (+71 -0)
➖ interviews/staffml/src/components/ChapterLinks.tsx (+0 -36)
📝 interviews/staffml/src/components/Footer.tsx (+3 -3)
➖ interviews/staffml/src/data/chapter-map.json (+0 -66)
📝 interviews/staffml/src/data/corpus-summary.json (+1 -1)
📝 interviews/staffml/src/data/vault-manifest.json (+2 -2)
➖ interviews/staffml/src/lib/chapters.ts (+0 -24)
📝 interviews/staffml/src/lib/corpus.ts (+27 -0)
➕ interviews/vault-cli/src/vault_cli/book_refs.py (+164 -0)
📝 interviews/vault-cli/src/vault_cli/legacy_export.py (+13 -1)
➕ interviews/vault-cli/tests/test_book_refs.py (+145 -0)

📄 Description

Implements #1822 (Phase 1): a "go deeper" pointer from each StaffML question back into the textbook, tied to the question's topic (not its answer), derived once per topic and inherited by all ~10.7k questions.

Builds on the draft topic_chapter_map.yaml + design analysis from ed68fda.

What changed

vault-cli (build join + link-checker)

  • New BookRefResolver joins topic → chapter via schema/topic_chapter_map.yaml, reads each chapter's display title from its .qmd H1, and link-checks every mapped chapter at build time — a mapped chapter with no .qmd source fails the build. This turns the original "defer until mlsysbook.ai URLs stabilize" blocker into "URLs are enforced valid."
  • book_refs is emitted as a top-level field so it rides into the summary bundle and renders synchronously (no worker fetch).
  • Regenerated corpus-summary.json: all 9,525 published questions now carry book_refs (100% of the 87 topics mapped, 0 orphaned).

staffml (UI)

  • New BookRefCard renders a "Learn more in the textbook" card after the attempt — primary chapter with a Volume badge + an authored why line, plus 0–2 "also see" chapters.
  • Supersedes the older area-level ChapterLinks; retires chapter-map.json / chapters.ts.

Fixes a live 404 bug

ChapterLinks was already shipping per-question links (keyed on competency_area), but its URLs 404'd:

URL Result
…/contents/vol1/nn_architectures/ (old ChapterLinks) 404
…/vol1/contents/vol1/nn_architectures/nn_architectures.html (new book_refs) 200

The new links are topic-granular (87 vs 13), carry a why line, and are build-link-checked against the verified-200 pattern.

Pedagogy

The card is a recommended-reading pointer tied to the topic, not an answer key — it renders after the solution is revealed, so it's a consolidation/go-deeper step rather than a shortcut around the reasoning.
image

Tests

  • test_book_refs.py — resolver resolution, primary/also_see ordering, .qmd title extraction, link-check fails on missing chapter, standalone slug fallback, and book_refs survives into the summary bundle.
  • Full suites green: vault-cli 96 passed (1 pre-existing codegen --check baseline failure, unrelated — confirmed failing on a clean tree); staffml tsc --noEmit clean + vitest 93 passed.

Follow-ups (Phase 2/3, not in this PR)

Prerequisite-on-wrong-answer remediation; per-question details.resources overrides + kind enum; bidirectional chapter→practice links; section-level deep links once anchors are stabilized.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/harvard-edge/cs249r_book/pull/1851 **Author:** [@farhan523](https://github.com/farhan523) **Created:** 6/9/2026 **Status:** ✅ Merged **Merged:** 6/16/2026 **Merged by:** [@profvjreddi](https://github.com/profvjreddi) **Base:** `dev` ← **Head:** `feat/staffml-book-refs` --- ### 📝 Commits (1) - [`09fc983`](https://github.com/harvard-edge/cs249r_book/commit/09fc983dbf562f3e243b8e0f2c09aad0191e3565) feat(staffml): link each question to recommended textbook reading ### 📊 Changes **13 files changed** (+430 additions, -137 deletions) <details> <summary>View changed files</summary> 📝 `interviews/staffml/src/app/plans/page.tsx` (+2 -2) 📝 `interviews/staffml/src/app/practice/page.tsx` (+2 -2) ➕ `interviews/staffml/src/components/BookRefCard.tsx` (+71 -0) ➖ `interviews/staffml/src/components/ChapterLinks.tsx` (+0 -36) 📝 `interviews/staffml/src/components/Footer.tsx` (+3 -3) ➖ `interviews/staffml/src/data/chapter-map.json` (+0 -66) 📝 `interviews/staffml/src/data/corpus-summary.json` (+1 -1) 📝 `interviews/staffml/src/data/vault-manifest.json` (+2 -2) ➖ `interviews/staffml/src/lib/chapters.ts` (+0 -24) 📝 `interviews/staffml/src/lib/corpus.ts` (+27 -0) ➕ `interviews/vault-cli/src/vault_cli/book_refs.py` (+164 -0) 📝 `interviews/vault-cli/src/vault_cli/legacy_export.py` (+13 -1) ➕ `interviews/vault-cli/tests/test_book_refs.py` (+145 -0) </details> ### 📄 Description Implements #1822 (Phase 1): a "go deeper" pointer from each StaffML question back into the textbook, tied to the question's **topic** (not its answer), derived once per topic and inherited by all ~10.7k questions. Builds on the draft `topic_chapter_map.yaml` + design analysis from ed68fda. ## What changed **vault-cli (build join + link-checker)** - New `BookRefResolver` joins `topic → chapter` via `schema/topic_chapter_map.yaml`, reads each chapter's display title from its `.qmd` H1, and **link-checks every mapped chapter at build time** — a mapped chapter with no `.qmd` source fails the build. This turns the original "defer until mlsysbook.ai URLs stabilize" blocker into "URLs are enforced valid." - `book_refs` is emitted as a top-level field so it rides into the summary bundle and renders **synchronously** (no worker fetch). - Regenerated `corpus-summary.json`: **all 9,525 published questions now carry `book_refs`** (100% of the 87 topics mapped, 0 orphaned). **staffml (UI)** - New `BookRefCard` renders a "Learn more in the textbook" card **after the attempt** — primary chapter with a Volume badge + an authored *why* line, plus 0–2 "also see" chapters. - Supersedes the older area-level `ChapterLinks`; retires `chapter-map.json` / `chapters.ts`. ## Fixes a live 404 bug `ChapterLinks` was already shipping per-question links (keyed on `competency_area`), but its URLs **404'd**: | URL | Result | |---|---| | `…/contents/vol1/nn_architectures/` (old `ChapterLinks`) | **404** | | `…/vol1/contents/vol1/nn_architectures/nn_architectures.html` (new `book_refs`) | **200** | The new links are topic-granular (87 vs 13), carry a *why* line, and are build-link-checked against the verified-200 pattern. ## Pedagogy The card is a recommended-reading pointer tied to the topic, **not an answer key** — it renders after the solution is revealed, so it's a consolidation/go-deeper step rather than a shortcut around the reasoning. <img width="824" height="731" alt="image" src="https://github.com/user-attachments/assets/7de8c842-e228-4a3c-aabb-5df3a3c33cca" /> ## Tests - `test_book_refs.py` — resolver resolution, primary/also_see ordering, `.qmd` title extraction, **link-check fails on missing chapter**, standalone slug fallback, and `book_refs` survives into the summary bundle. - Full suites green: vault-cli `96 passed` (1 pre-existing `codegen --check` baseline failure, unrelated — confirmed failing on a clean tree); staffml `tsc --noEmit` clean + vitest `93 passed`. ## Follow-ups (Phase 2/3, not in this PR) Prerequisite-on-wrong-answer remediation; per-question `details.resources` overrides + `kind` enum; bidirectional chapter→practice links; section-level deep links once anchors are stabilized. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-06-21 20:35:44 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area: book
area: collabs
area: kits
area: labs
area: socratiq
area: staffml
area: tinytorch
area: tools
area: website
bug
dependencies
format: epub
format: pdf
javascript
link-health
link-rot
priority-high
pull-request
Mirrored from GitHub Pull Request
 staffml
type: bug
type: citation
type: code
type: errata
type: improvement
type: new
type: question
vault-sli
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/cs249r_book#30953
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?