27:null 28:["$","title",null,{"children":"Visualizing Bostock’s Insights with a Word Cloud | Observable Ambassadors | Observable"}] 2d:T9b6,// ============================================================================ // dashboardShell2 — the STATIC layout/DOM shell for the SECOND dashboard // (keyword timeline + its own video player). Built exactly once, just like // `dashboardShell` (cell 151) above: references nothing reactive (no `words`, // no pipeline state), so it is never rebuilt/torn down for the life of the // page. The reactive pieces (the timeline SVG, the video player) are owned by // separate cells below that query mount points out of this container. // ============================================================================ dashboardShell2 = html`

Instructions:

Click any tick mark to jump this video to that word's mention timestamp.
Rows are the same top keywords/ranking as the word cloud above, just laid out over time instead of packed by size.

`2e:T135a,// ============================================================================ // dashboardShell — the STATIC layout/DOM shell for the dashboard. // ============================================================================ // This cell deliberately references NOTHING reactive (no words, // wordsObservableAI, pipelineTriggered, or selectedSource) so it is // built exactly ONCE, ever, for the life of the page. That's the whole // point: previously all of this lived inside "viewof dashboard" (old cell // 43), which ALSO referenced wordsObservableAI/pipelineTriggered (to // compute observableReady and fire the one-time build trigger) -- and // because Observable reruns an ENTIRE cell whenever any variable it // references changes, that meant the WHOLE dashboard (including the // YouTube iframe/YT.Player) was torn down and rebuilt from scratch: once // when pipelineTriggered flipped true, and AGAIN ~10-20s later the moment // wordsObservableAI finished computing in the background. That rebuild // (a brand new iframe replacing the old one) is what produced the "delay // in the video tied to wordsObservableAI" -- it wasn't a computation delay, // it was the whole player being remounted. // // The fix: this cell only builds the static shell (mount points as plain // DIVs, not the SVG/player themselves), as a single value -- the DOM node // itself, so it renders automatically. Separate cells below build/own the // YouTube player (ytPlayerController) and the word cloud SVG // (wordCloudRenderer) against these stable mount points (queried from this // container), so the video player is completely insulated from // word-cloud/pipeline reactivity. dashboardShell = html`

‡ = Manually added by the notebook author. See Acknowledgments & Collaboration below.

Instructions:

Click any word in the cloud to jump the video to its mention timestamp.
Clicking the same word repeatedly will cycle through each occurrence in the lecture.
Click any blank area of the word cloud to reset the selection and restart the video from the beginning.

`2f:T3150,## Acknowledgments & Collaboration This interactive Observable notebook was built collaboratively with two different AI assistants at two different stages of its life, and — deliberately, for teaching purposes — **both pipelines are kept side by side** rather than one replacing the other. Use the **"Words Source"** toggle above the word cloud to switch live between them and see how each one's choices, and the resulting cloud, differ. ### Original Pipeline: Gemini AI Logic Built with [**Gemini**](https://gemini.google.com/), Google's AI assistant, this was the notebook's first working keyword-extraction pipeline (`wordsGeminiAI`). AI assistance was leveraged for: * **Algorithm & Pipeline Design:** parsing engines for transcript ingestion, timestamp extraction, and keyword tokenization. * **Natural Language Processing:** a filtering pipeline built on [`compromise`](https://github.com/spencermountain/compromise)'s generic noun/proper-noun/topic tags, combined with one large, hand-curated stop-word list (~150 entries spanning pronouns, contractions, filler words, and function words) to remove unwanted terms. * **Ranking:** words are sized in the cloud purely by **how often they were said** (raw mention count). * **Interactive Dashboard Architecture:** the original event-driven DOM bridge connecting the SVG word cloud to the YouTube iFrame API for click-to-seek timestamp navigation. * **Code Quality & Documentation:** comprehensive inline commenting and error handling. ### Alternative Pipeline: Observable AI Logic Built with the Observable notebook assistant, this pipeline (`wordsObservableAI`) tackles the same problem — turning a messy, unpunctuated interview transcript into a curated keyword list — with a different technical philosophy: * **Precise grammatical filtering, not one big list:** instead of a generic noun tag plus a sprawling stop-word list, candidates are filtered using *specific* Compromise POS tags (excluding `#Pronoun`, `#Time`, `#Date`, `#Copula`, `#Determiner`, `#Possessive`), backed by two small, narrowly-scoped exception lists — a 10-word set of unavoidable spoken discourse markers ("like", "youknow", "ithink"...) and a 10-entry allowlist for short technical acronyms ("D3", "AI", "UI"...) that a generic length filter would otherwise discard. * **Semantic ranking via an in-browser AI model:** rather than sizing words by raw frequency, common nouns are ranked by **cosine similarity** to the talk's own "topic embedding" — computed by chunking the entire transcript and mean-pooling it through a small sentence-embedding model, [`Xenova/all-MiniLM-L6-v2`](https://huggingface.co/Xenova/all-MiniLM-L6-v2), running entirely client-side via [`@xenova/transformers`](https://github.com/xenova/transformers.js) (no API key, no server). * **A separate branch for names:** person and organization names (e.g. "Mike Bostock") don't semantically resemble a talk's *topic* even when they're clearly important, so proper nouns are deliberately ranked by frequency instead of similarity, then merged back in with a reserved quota of cloud slots. * **An interactive UI refinement:** the "Words Source" radio toggle itself was extended collaboratively — built with a `mutable` reactive cell (rather than a `viewof` input) specifically so the control could be fully relocated inside the dashboard's own layout, above the word cloud, without leaving any other notebook cell empty. * **Lazy activation for performance:** this pipeline downloads and runs a small ML model in-browser and makes ~130 embedding calls, which used to be a *hard dependency* of `viewof dashboard` itself — meaning every page load was blocked on this model loading and running, even for visitors who only ever wanted the (much cheaper) Gemini pipeline. It's now gated behind `mutable observableAIRequested` (starts `false`), so it only downloads the model and computes anything the first time a visitor actually selects "Observable AI Logic" — the dashboard shows a brief loading note, then switches over automatically once it's ready. ### A Human Override: The Theme Both Pipelines Missed Both pipelines above are, in their own ways, genuinely good-faith attempts at automated keyword extraction — and both of them missed the video's single most important idea. At **50:58**, asked to recap his thinking on AI coding agents, Bostock says, verbatim: > "Well, the main thing is really about **interpretability, verifiability, and trust**." He then spends the next couple of minutes unpacking exactly that: an AI coding agent's output is only *trustworthy* insofar as it's *verifiable*, and it's only verifiable if a human can *interpret* it. It's arguably the most direct, first-person answer in the whole interview to "what should any code-development effort — agentic or not — actually have?" A human watching the full video (rather than just running an algorithm over its transcript) immediately recognizes this as the dominant theme. Neither automated pipeline did. **Why not?** Both pipelines gate candidate words on `count >= 3` for one *exact literal token*, then rank by either frequency (Gemini) or semantic similarity (Observable AI). Checking the transcript directly: | literal token | occurrences | |---|---| | "interpretability" | 1 | | "interpretable" | 4 | | "verifiability" | 1 | | "verifiable" | 3 | | "trust" | 3 | | "trustworthy" | 1 | The two headline *nouns* Bostock actually says — "interpretability" and "verifiability" — each individually fail the `count >= 3` gate, because the idea is spoken across *several different word forms* rather than one repeated token. Frequency ranking and semantic-similarity ranking are both innocent bystanders here: the candidate was never assembled in the first place, so neither ranking method ever got a chance to evaluate it. This is a real, general failure mode worth internalizing — important ideas are often paraphrased or inflected across multiple forms rather than repeated verbatim, and a purely mechanical frequency gate can't see that the way a person who actually watched the video can. **What we did about it — on purpose, and visibly:** rather than quietly patching the stop-word/allow-list machinery to paper over this (which would hide the lesson), a human override was added deliberately and disclosed at every layer: * A single shared cell, `manualThemeWords`, is the one source of truth for these three words — used by *both* `wordsGeminiAI` and `wordsObservableAI`, so they stay consistent with each other. * Each theme word is matched by a regex **stem** (e.g. `interpretab`) that catches every spoken form, with real, verified timestamps — clicking/cycling through "Interpretability", "Verifiability", or "Trust" behaves exactly like any other word in the cloud. * Their `count` (the ranking input) is deliberately **boosted above every algorithmically-derived word** — per the notebook author's explicit judgment that these are the video's central theme, not a score the algorithm was allowed to decide for itself. This guarantees they're always included and always rank at the very top, regardless of what raw frequency/similarity alone would say. * They're kept within the existing 75-word budget (displacing the 3 lowest-ranked automated words) rather than growing the cloud, since the notebook author judged the added interpretive value well worth that trade. * Every returned object carries `isManual: true` and a `manualNote` explaining exactly why it's there — and in the rendered cloud itself, these three words get a distinct dark-red color, bold "impact" font, and a **"‡" marker** baked right into the label, so the human edit is visually obvious, not hidden. A short, permanent legend below the cloud, plus the word's own hover tooltip, explain what "‡" means. * (One genuinely interesting engineering wrinkle surfaced along the way: initially forcing these three words to also render at the *literal largest pixel size* in the cloud caused d3-cloud's spiral placement algorithm to silently **drop** "Interpretability" and "Verifiability" — the two longest words — because their rotated bounding box didn't fit an 800×600 canvas. The fix, still in place in `createWordCloudSvg`, forces manually-curated words to render horizontally and clamps their font size, via real canvas text measurement, to a size guaranteed to fit.) * **A second round of human review** then found the *rendered result* of that ranking boost — literally the largest words on screen — visually overwhelming relative to the rest of the cloud, even though the underlying ranking logic (boosting `count`, which guarantees inclusion + top rank) was working exactly as designed. Rather than touch that ranking logic, `createWordCloudSvg` now applies a separate, purely cosmetic `manualSizeScale` (0.5×) at render time, so these three still land at/near the top of the size range — distinct via color, font, and the "‡" marker — without dominating the whole cloud. This is a good example of "1 + 1 = 3" in the small: the algorithm's *ranking* decision and the human's *presentation* judgment are two genuinely separate concerns, and keeping them as two separate, independently-tunable knobs (`count` boost vs. `manualSizeScale`) made this round of feedback a one-line change instead of a re-derivation of the ranking math. This is really the point of keeping two AI-built pipelines side by side in one notebook at all: **1 + 1 = 3**. Neither the Gemini-built pipeline, nor the Observable-built pipeline, nor an unaided human skimming a 69-minute transcript would likely have produced this word cloud alone. It took an AI-assisted pipeline to make the *90% case* cheaply and consistently across any transcript, and it took a human who actually watched the video — and then reviewed the rendered result twice — to catch the one thing that mattered most and dial in exactly how it should be presented. ### A Teaching Note: Why Both Approaches Are Worth Seeing Neither pipeline is simply "better" — they illustrate two real, common strategies for extracting meaning from text, with different trade-offs: | | Gemini AI Logic | Observable AI Logic | |---|---|---| | **Candidate extraction** | Generic `#Noun` / `#ProperNoun` tags + `doc.topics()` | Precise POS-tag exclusions (drops pronouns, dates, possessives, etc. at the source) | | **Filtering** | One large, hand-tuned ~150-word stop list mixing many categories together | Two tiny, single-purpose lists (discourse markers, short acronyms) | | **Ranking** | Raw mention frequency | Semantic similarity to the talk's own topic embedding (common nouns); frequency only for names | | **Adapting to a new transcript** | Requires re-tuning the stop list by hand | Adapts automatically — no manual list-tuning needed | | **Dependencies** | `compromise` NLP only | `compromise` NLP + an in-browser ML embedding model | | **Initial page load cost** | Fast — NLP parsing only | Zero *until requested* — the ML model and ~130 embedding calls only run once "Observable AI Logic" is actually selected | | **A real failure mode found in testing** | Frequency-only ranking is vulnerable to mistagged filler words dominating by sheer repetition | Semantic similarity alone under-ranks real names/orgs, since they aren't "topical" words | | **A blind spot found in BOTH** | A theme spoken across multiple word forms, rather than one repeated token, is invisible to a `count >= 3` literal-token gate — fixed, in both, by the same disclosed manual override (see above) | *(same)* | That failure-mode row isn't hypothetical — all of these were actually observed and fixed during development (see the extensive header comments inside the `wordsObservableAI` cell for a blow-by-blow account of real bugs caught by testing, including one word that was mentioned 74 times yet meant nothing at all, and the manual-theme-override discussion above for the one gap that *no* amount of re-testing the algorithm would have caught, plus the presentation-only refinement that followed it). It's a useful, concrete reminder that AI-assisted code — from *either* assistant, or from both working together — still needs to be empirically tested against real data, checked against actual human understanding of the source material, and reviewed visually once rendered, not just trusted because the design sounds reasonable. --- *Built with [Observable](https://observablehq.com/), [D3.js](https://d3js.org/), [compromise NLP](https://github.com/spencermountain/compromise), and [Transformers.js](https://github.com/xenova/transformers.js).*30:T1789,// ============================================================================ // manualThemeWords — a deliberate, disclosed HUMAN override of both automated // pipelines below, and the single source of truth both `wordsGeminiAI` (cell // 40) and `wordsObservableAI` (cell 119) merge in. // ============================================================================ // // WHY THIS EXISTS // ---------------------------------------------------------------------------- // At 50:58 in the interview, in response to being asked to recap his "arson" // blog post on AI coding agents, Bostock says: // // "Well, the main thing is really about interpretability, verifiability, // and trust." // // He then spends the next ~2 minutes of the conversation unpacking exactly // that idea -- that AI coding agents are only trustworthy insofar as their // output is verifiable, and it's only verifiable if a human can interpret // it -- arguably the single most important claim in the entire talk, and a // direct, first-person answer to "what should any code-development effort // (agentic or not) have?" Neither automated pipeline in this notebook // surfaced it. That's not a bug to be quietly patched -- it's an instructive, // disclosed example of an automated pipeline's blind spot that only a human // who actually watched/understood the video could catch, which is exactly // why it's called out explicitly here instead of just being folded silently // into the stop-word/allow-list machinery of either pipeline. // // WHY BOTH AUTOMATED PIPELINES MISSED IT // ---------------------------------------------------------------------------- // Both pipelines gate candidate words on `count >= 3` for one exact literal // token, then (Gemini) rank by raw frequency or (Observable AI) rank common // nouns by semantic similarity. Checking the actual transcript: // // literal token occurrences // "interpretability" 1 // "interpretable" 4 (different literal token/POS form) // "verifiability" 1 // "verifiable" 3 // "trust" 3 // "trustworthy" 1 // // "Interpretability" and "verifiability" -- the two headline nouns Bostock // actually says -- each fail the `count >= 3` gate as literal tokens, because // the same idea is spoken across several *different* word forms rather than // one repeated word. Frequency-based and similarity-based ranking are both // bystanders here: the words were simply never assembled into one candidate // in the first place. This is a real, general failure mode of frequency/NLP // pipelines -- important ideas are often paraphrased or inflected across // multiple forms rather than repeated verbatim -- and it's worth keeping // visible rather than "fixing" via a bigger stop/allow list that would hide // the lesson. // // WHAT THIS CELL DOES // ---------------------------------------------------------------------------- // For each of the three theme words, this cell: // 1. Defines a regex STEM (e.g. `interpretab`) that matches every spoken // form of the idea, not just one literal token. // 2. Counts every matching occurrence across the whole transcript, for // transparency (`rawMentionCount` -- the true, unboosted count). // 3. Finds every real timestamp those forms occur at, via the same cue // text used everywhere else in the notebook, so click-to-seek behaves // identically to any automatically-derived word (per the notebook // author's decision: no special-casing of the interaction model). // 4. Flags the result `isManual: true` with a human-readable `manualNote`, // so this remains visibly, honestly a human edit at every downstream // consumer -- both pipeline cells below, and the cloud renderer (cell // 33), which gives these three a distinct visual treatment. // // `priority` (1 = spoken first) is used downstream by both pipelines to size // these three relative to EACH OTHER (Interpretability > Verifiability > // Trust), consistent with the order Bostock actually spoke them in. // // This cell deliberately does NOT decide these words' final `count`/`freq`/ // `score` in the output word-cloud data shape -- that's pipeline-specific // (each pipeline has a different notion of "top automated word" to boost // above), so each pipeline cell does that boosting itself, using the raw // ingredients (`rawMentionCount`, `startTimes`) produced here. manualThemeWords = { const themeDefinitions = [ { text: "Interpretability", stemPattern: "\\binterpretab\\w*\\b", priority: 1 }, { text: "Verifiability", stemPattern: "\\bverifiab\\w*\\b", priority: 2 }, { text: "Trust", stemPattern: "\\btrust\\w*\\b", priority: 3 } ]; function findStemTimestamps(stemPattern) { const pattern = new RegExp(stemPattern, "i"); const times = new Set(); for (const entry of parsedTranscript) { if (pattern.test(entry.text)) times.add(entry.start); } return Array.from(times).sort((a, b) => a - b); } return themeDefinitions.map(def => { const globalPattern = new RegExp(def.stemPattern, "gi"); const rawMentionCount = (completeTranscript.match(globalPattern) || []).length; return { text: def.text, priority: def.priority, rawMentionCount, startTimes: findStemTimestamps(def.stemPattern), isManual: true, manualNote: "Manually added by the notebook author. At 50:58 Bostock names " + "interpretability, verifiability, and trust as THE requirement for any " + "AI-assisted code-development workflow -- arguably the single most " + "important idea in the talk. Yet each word's exact literal form is " + "spoken only once (or its related forms only a handful of times), so " + "both automated pipelines' frequency-based inclusion gate silently " + "dropped it. This is a deliberate, disclosed human override, not a " + "pipeline bug fix -- see the 'Acknowledgments & Collaboration' section." }; }); }31:T61d0,// ============================================================================ // wordsObservableAI — AI-assisted, semantically-ranked candidate replacement for `words` // ============================================================================ // // STATUS: LIVE — one of two pipelines selectable via the "Words Source" radio // toggle built inside `viewof dashboard` (cell 43). The `mutable words` cell // (126) holds whichever pipeline is currently selected, defaulting to // `wordsGeminiAI` (cell 40). See the "Acknowledgments & Collaboration" // section (cell 87) for a full side-by-side comparison of both approaches. // // MANUAL CURATION NOTE: STAGE 3.5 below merges in `manualThemeWords` // (Interpretability / Verifiability / Trust) -- three words a human (the // notebook author) identified as the video's central theme at 50:58 (Bostock's // own explicit answer to "what does any code-development effort need?"), // which even semantic-similarity ranking cannot reliably surface (see STAGE // 3.5 for why). See the `manualThemeWords` cell for the full rationale. // // ONE-TIME BUILD, DECOUPLED FROM THE RADIO CONTROL: this cell short-circuits // to `null` until the dashboard's one-time build trigger, `pipelineTriggered` // (cell 137), flips to `true` -- which now happens AUTOMATICALLY, exactly // once, shortly after `viewof dashboard` (cell 43) completes its very first // render (see the "ONE-TIME BUILD TRIGGER" block near the bottom of that // cell), completely independent of whether/when the user ever selects // "Observable AI Logic". This keeps the in-browser embedding model (cell // 131) and the transcript chunk-embedding pass (cell 134) from blocking the // dashboard's OWN initial paint, while still letting the (slow) model // download + ~130 embedding calls happen once, quietly, in the background -- // so the data is USUALLY already sitting ready by the time anyone actually // picks "Observable AI Logic". Once this cell resolves to a real array, it // is never recomputed again for the rest of the session: nothing re-triggers // `pipelineTriggered`, and neither this cell nor `wordsGeminiAI` (cell 40) // depends on `selectedSource`/`words`/the radio control at all -- toggling // the radio only changes which ALREADY-BUILT array `mutable words` points // at, it never rebuilds either one. // // ---------------------------------------------------------------------------- // WHY THIS EXISTS (the problem with the original `words` cell) // ---------------------------------------------------------------------------- // The original `words` cell extracts keywords using Compromise NLP's generic // `#Noun` tag plus `doc.topics()`, then filters unwanted terms using ONE large // (~150-entry) hand-maintained stop-word list that mixes together many // unrelated categories at once: pronouns, contractions, common verbs, speech // fillers, function words, etc. That works, but: // // 1. It has to be hand-tuned all over again for any new/different transcript. // 2. It conflates several *different* linguistic problems into one bucket, // making it hard to reason about why any specific word was kept/dropped. // 3. It ranks purely by raw frequency, so a word's cloud size reflects how // often it was SAID, not how central it is to what the conversation was // ABOUT. (We proved this is a real problem below — see "there".) // // This cell replaces that single big stop-list with several small, narrowly- // scoped, INDEPENDENTLY JUSTIFIED mechanisms, plus a semantic ranking step // powered by a small sentence-embedding model that runs entirely IN-BROWSER // (no API key, no server, no external account — see the `@xenova/transformers` // import in cell 89 and the `pipeline`/`extractor` setup in cell 131). // // ---------------------------------------------------------------------------- // EVERYTHING BELOW WAS EMPIRICALLY VALIDATED AGAINST THE REAL TRANSCRIPT // (not just theorized) over the course of this conversation, INCLUDING FOUR // bugs/gaps caught by testing (three in the algorithm itself, one -- the // manual theme override -- caught not by re-running the code but by a human // actually watching the full video): // // • Loosening the noun-tag filter to a bare `#Noun` catches pronouns // ("you", "they", "them") that Compromise dual-tags as Noun+Pronoun on // this transcript. Fix: `.not("#Pronoun")`. // // • It ALSO catches words Compromise tags as pure `#Noun` with a MORE // SPECIFIC secondary tag that reveals their true role in context: // "now" → {Time, Date, Noun}, "it's" → {Pronoun, Noun, Contraction}, // "your" → {Possessive, Noun}. Excluding those secondary tags (`#Time`, // `#Date`, `#Copula`, `#Determiner`, `#Possessive`) removes them // precisely and surgically. // // • BUG #1 (caught in testing): ONE word — "there" — is tagged by // Compromise as bare {Singular, Noun} with NO distinguishing secondary // tag at all. It appears 74 times (more than any real content word!). An // earlier draft blended frequency and similarity into the ranking score // using Z-SCORES, assuming that would be robust to outliers. It was NOT: // "there"'s frequency is such an extreme outlier (74 vs. a typical // candidate's 3-20) that even a 0.35-weighted Z-scored frequency term // dragged its blended score back above many genuinely relevant words, // and it reappeared at the TOP of the test output. FIX: common nouns are // now ranked by SEMANTIC SIMILARITY ALONE (no frequency component at // all). Frequency is only used as a minimum-mention gate (`count >= 3`), // never as part of the ranking score. This matches the approach // empirically validated earlier in this project (see chat history), which // correctly demoted "there" to near-last place out of ~100 candidates. // // • Compromise ALSO mis-tags a small, ambiguous minority of occurrences of // "like" as bare `#Noun` (505 total occurrences of "like" in the // transcript; the vast majority are correctly tagged Verb/Adverb/ // Preposition, but ~37 slip through). Semantic similarity doesn't // reliably catch "like"/"youknow"/"ithink" either, because they are // extremely common, semantically-diffuse spoken discourse markers whose // single-word embeddings land in a deceptively "central" part of // embedding space. This is the ONE place we kept a small, explicit, // linguistically-principled exception list (`discourseMarkers` below) — // a closed category of ~10 words, not a general-purpose stoplist. // // • Named entities — "Mike Bostock" (the interview GUEST) and "New York // Times" (his former employer) — scored NEGATIVE cosine similarity // against the talk's topic embedding, because they're proper nouns, not // generic tech vocabulary. A pure similarity ranking would silently drop // genuinely important names. THIS IS WHY PROPER NOUNS GET THEIR OWN // SEPARATE BRANCH below, ranked by frequency alone (never penalized by // topical similarity), then merged back in with a reserved slot quota. // // • BUG #2 (caught in testing): "DOM" showed up TWICE in an earlier draft's // output — once via the proper-noun branch and once via the common-noun // branch — because Compromise tags some occurrences of "DOM" as // `#ProperNoun` (likely triggered by its all-caps casing) and other // occurrences of the same word as plain `#Noun`. Extracting proper/common // nouns as two independent match sets and tallying them separately // silently double-counted any word Compromise tags inconsistently across // its occurrences. FIX: term extraction now happens ONCE, tracking how // many times each cleaned term appeared as a proper-noun match vs. a // common-noun match, merging those counts into a single total per term, // and classifying the term into exactly one bucket by majority vote — // with a manual override so short technical acronyms (`shortAllowlist`) // always go through the common-noun/similarity path. // // • BUG #3 (caught in testing): `#ProperNoun+` can match MULTI-WORD spans // ("Mike Bostock", "New York Times", "DOM API"). The timestamp index in // BOTH the original `words` cell and an earlier draft of this cell is // built by splitting each transcript cue into INDIVIDUAL tokens, so a // multi-word key like "mike bostock" can never match a single-token map // key — the lookup silently returned an EMPTY array. That's a serious // bug: the dashboard's click-to-cycle logic (cell 33) divides by // `startTimes.length`, so any word with an empty array would be // permanently unclickable / could break the interaction entirely. FIX: // instead of pre-indexing single tokens, each final term is looked up by // directly searching every transcript cue's cleaned text for that exact // term (single- or multi-word) as a whole-word/phrase regex match. Slower // (O(terms × cues) instead of one pass) but at this scale (75 × ~550) // it's negligible, and it's correct for terms of any length. // // • GAP #4 (caught NOT by testing code, but by a human watching the full // video): at 50:58, Bostock explicitly names "interpretability, // verifiability, and trust" as the central requirement for any AI-assisted // code-development effort — arguably the single most important claim in // the talk. Semantic similarity ranking STILL doesn't reliably surface it, // because the idea is spoken across several different word forms rather // than one repeated token, and each individual literal token (barely) or // entirely fails the `count >= 3` minimum-mention gate before similarity // ranking ever runs (see `manualThemeWords` cell for the exact counts). // This is a structural blind spot, not a tuning problem: no amount of // re-weighting the similarity score would fix a candidate that never // became a candidate in the first place. FIX: these three words are // looked up directly (via `manualThemeWords`) and merged in as a fourth, // manually-curated bucket in STAGE 3.5 below — deliberately bypassing // similarity scoring entirely, exactly the way proper nouns bypass it, // but for the opposite reason (too important to trust an automatic score, // rather than structurally incompatible with topical similarity). // // ---------------------------------------------------------------------------- // PIPELINE STAGES // ---------------------------------------------------------------------------- // STAGE 1 — Candidate generation + deduplicated classification // STAGE 2 — Common-noun ranking (semantic similarity ONLY, see BUG #1 above) // STAGE 3 — Proper-noun ranking (frequency ONLY — see rationale above) // STAGE 3.5 — Manual theme override merge (see GAP #4 above) // STAGE 4 — Merge all three ranked lists into one list of 75 // STAGE 5 — Timestamp indexing via direct cue search (see BUG #3 above) // // ---------------------------------------------------------------------------- // DEPENDENCIES ON OTHER NOTEBOOK CELLS (all defined earlier in this notebook) // ---------------------------------------------------------------------------- // doc — Compromise NLP document over the full transcript (cell 22) // parsedTranscript — timestamped transcript cues, for the seek index (cell 3) // manualThemeWords — the 3 human-curated theme words, shared with // `wordsGeminiAI` so both pipelines stay consistent // embedBatch(texts) — embeds many strings at once via the in-browser MiniLM // model in a single call (cell 139) // cosine(a, b) — cosine similarity between two embedding vectors (cell 132) // derivedDocEmbedding — the talk's own "topic centroid" embedding, computed by // chunking the ENTIRE transcript and mean-pooling chunk // embeddings (cell 134) — this is NOT hand-authored text, // so it doesn't reintroduce fresh manual bias. // // ---------------------------------------------------------------------------- // OUTPUT SHAPE — matches `wordsGeminiAI`'s shape (plus `isManual`/`manualNote` // on the 3 manually-curated entries), so either pipeline can be assigned to // `mutable words` interchangeably: // [{ text, count, freq, startTimes, similarity, score, isManual?, manualNote? }, ...] (length <= 75) // (`similarity` and `score` are extra diagnostic fields, harmless to keep — // they make it easy to see WHY a word was ranked where it was during review. // `similarity` is `null` for proper nouns AND manually-curated words, since // neither is similarity-scored; `score` is `Infinity` for manually-curated // words, signaling "forced above the automated ranking" rather than a real // computed value.) // While the pipeline hasn't been triggered yet, or its inputs aren't ready, // this resolves to `null` instead -- callers must handle that. // // A validation check at the bottom asserts every returned word has at least // one startTime, specifically to guard against BUG #3 recurring silently. // ============================================================================ wordsObservableAI = { // BUILD-ONCE GUARD: bail out instantly (no NLP matching, no embedding // calls) until the dashboard's one-time build trigger has fired AND its // upstream topic embedding (cell 134) has finished computing. Once this // resolves to a real array below, nothing ever causes it to be recomputed // again -- `pipelineTriggered` only ever flips false -> true once (cell // 137/43), and everything this cell reads (`doc`, `manualThemeWords`, // `derivedDocEmbedding`, etc.) is otherwise static for the session. if (!pipelineTriggered || !derivedDocEmbedding) return null; // -------------------------------------------------------------------------- // SMALL, EXPLICIT, JUSTIFIED MANUAL LISTS // Unlike the original's one big ~150-word catch-all list, each of these is // narrow, named for exactly what it does, and independently justified above. // -------------------------------------------------------------------------- // Real nouns, grammatically — but too generic/content-free to ever be an // interesting word-cloud entry regardless of topic or transcript. const trivialStopWords = new Set([ "thing", "things", "way", "ways", "lot", "lots", "people", "person", "time", "times", "guy", "guys", "something", "someone", "everything", "everyone", "stuff", "part", "parts" ]); // Closed category of spoken discourse markers/fillers that survive BOTH // POS-tagging and semantic-embedding filtering on this messy, unpunctuated // ASR transcript (see "like"/"youknow"/"ithink" findings above). const discourseMarkers = new Set([ "like", "youknow", "yeah", "ithink", "um", "uh", "well", "right", "okay", "ok" ]); // Short technical acronyms that a naive minimum-length filter would // otherwise discard (e.g. "D3", "AI" are only 2 characters). ALSO used // below to force consistent bucket classification regardless of how // Compromise happens to tag any individual occurrence (see BUG #2 above). const shortAllowlist = new Set(["d3", "ai", "js", "ui", "svg", "api", "dom", "db", "3d", "2d"]); // Preserve canonical casing for display purposes only (matching lookup is // always done on the lowercased/cleaned form). const displayOverrides = new Map([ ["d3", "D3"], ["js", "JS"], ["ui", "UI"], ["ai", "AI"], ["svg", "SVG"], ["html", "HTML"], ["dom", "DOM"], ["api", "API"], ["3d", "3D"], ["2d", "2D"] ]); // -------------------------------------------------------------------------- // STAGE 1 — CANDIDATE GENERATION + DEDUPLICATED CLASSIFICATION // -------------------------------------------------------------------------- const commonNounMatches = doc.match("#Noun+") .not("#Pronoun") // "you", "they", "them", "it's" (dual-tagged) .not("#Time") // "now" (tagged {Time, Date, Noun} in context) .not("#Date") // ditto .not("#Copula") // linking-verb forms occasionally mistagged .not("#Determiner") // "this", "that", "these" style words .not("#Possessive"); // "your", "our", "my" (tagged {Possessive, Noun}) const properNounMatches = doc.match("#ProperNoun+"); function cleanTerm(raw) { return String(raw) .toLowerCase() .replace(/'s$/g, "") .replace(/[^\w\s-]/g, "") .trim(); } function isRejected(clean) { const isShortAllowed = shortAllowlist.has(clean); return ( !clean || (!isShortAllowed && clean.length < 3) || trivialStopWords.has(clean) || discourseMarkers.has(clean) || /^\d+$/.test(clean) ); } // Tally BOTH match sets into ONE combined map (fixes BUG #2). const termStats = new Map(); // clean -> { commonCount, properCount } function record(raw, isProper) { const clean = cleanTerm(raw); if (isRejected(clean)) return; if (!termStats.has(clean)) termStats.set(clean, { commonCount: 0, properCount: 0 }); const stats = termStats.get(clean); if (isProper) stats.properCount += 1; else stats.commonCount += 1; } commonNounMatches.out("array").forEach(raw => record(raw, false)); properNounMatches.out("array").forEach(raw => record(raw, true)); const commonNounCandidates = []; const properNounCandidates = []; for (const [text, stats] of termStats) { const count = stats.commonCount + stats.properCount; if (count < 3) continue; // minimum-mention gate, same threshold as the original cell const isForcedCommon = shortAllowlist.has(text); const isProperByVote = stats.properCount > stats.commonCount; if (!isForcedCommon && isProperByVote) { properNounCandidates.push({ text, count }); } else { commonNounCandidates.push({ text, count }); } } // -------------------------------------------------------------------------- // STAGE 2 — COMMON-NOUN RANKING (semantic similarity ONLY — see BUG #1) // Batched into a single `embedBatch` call instead of one `embed()` call per // candidate word (was ~65 sequential model calls). // -------------------------------------------------------------------------- const commonNounVectors = await embedBatch(commonNounCandidates.map(c => c.text)); const rankedCommonNouns = commonNounCandidates.map((candidate, i) => { const similarity = cosine(commonNounVectors[i], derivedDocEmbedding); return { ...candidate, similarity, score: similarity }; }); // -------------------------------------------------------------------------- // STAGE 3 — PROPER-NOUN RANKING (frequency ONLY — deliberately no similarity) // -------------------------------------------------------------------------- const rankedProperNouns = properNounCandidates.map(d => ({ ...d, similarity: null, // not applicable — flagged explicitly rather than left as 0 score: Math.log(d.count + 1) })); // -------------------------------------------------------------------------- // STAGE 3.5 — MANUAL THEME OVERRIDE (see GAP #4 above, and `manualThemeWords`) // -------------------------------------------------------------------------- // These three words bypass similarity scoring entirely -- not because // they're structurally incompatible with it (like proper nouns), but // because the notebook author has judged them, based on actually watching // the video, to be its dominant theme, and is not willing to let an // automatic score decide whether they appear or how prominently. Their // `count` is deliberately boosted above the current top-ranked automated // word so they render as the LARGEST words in the cloud (fontSize, cell // 71, sizes off `freq`, which is derived from `count`) -- ordered to // mirror the sequence Bostock actually spoke them in (priority 1 = largest). const automatedMaxCount = Math.max( 0, ...rankedCommonNouns.map(w => w.count), ...rankedProperNouns.map(w => w.count) ); const boostByPriority = [15, 10, 5]; // priority 1 (Interpretability) boosted most const manualWords = manualThemeWords.map(theme => { const boostedCount = automatedMaxCount + boostByPriority[theme.priority - 1]; return { text: theme.text, count: boostedCount, similarity: null, // not applicable -- deliberately not similarity-scored score: Infinity, // diagnostic flag: "forced above the automated ranking", not a real score startTimes: theme.startTimes, // REAL timestamps, precomputed via manualThemeWords isManual: true, manualNote: theme.manualNote, rawMentionCount: theme.rawMentionCount // diagnostic: true, unboosted mention count across all spoken forms }; }); // -------------------------------------------------------------------------- // STAGE 4 — MERGE INTO A SINGLE LIST OF <= 75 // -------------------------------------------------------------------------- // Budget: 75 total slots. 3 are now reserved for the manual theme override // (STAGE 3.5) -- honoring the agreed 75-word cloud size rather than growing // it to 78, at the cost of the 3 lowest-ranked automated words that would // otherwise have barely made the cut. 10 remain reserved for proper nouns // (names/orgs), as before. const TOTAL_SLOTS = 75; const PROPER_NOUN_SLOTS = 10; const MANUAL_SLOTS = manualWords.length; // 3 const topProperNouns = rankedProperNouns .sort((a, b) => b.count - a.count) .slice(0, PROPER_NOUN_SLOTS); const topCommonNouns = rankedCommonNouns .sort((a, b) => b.score - a.score) .slice(0, TOTAL_SLOTS - MANUAL_SLOTS - topProperNouns.length); const automatedMerged = [...topCommonNouns, ...topProperNouns]; // -------------------------------------------------------------------------- // STAGE 5 — TIMESTAMP INDEXING VIA DIRECT CUE SEARCH (fixes BUG #3) // -------------------------------------------------------------------------- // Rather than pre-indexing single tokens (which silently fails for // multi-word terms like "mike bostock" or "dom api"), search every // transcript cue directly for the exact term as a whole-word/phrase match. // (The 3 manually-curated words already have real timestamps precomputed // by `manualThemeWords`, via the same style of direct cue search but with // a multi-form STEM regex -- they skip this step.) function escapeRegExp(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } function findTimestamps(term) { const escaped = escapeRegExp(term).replace(/\s+/g, "\\s+"); const pattern = new RegExp(`\\b${escaped}\\b`, "i"); const times = new Set(); for (const entry of parsedTranscript) { // Normalize the cue text the same way terms were cleaned: strip // punctuation to spaces (not delete it) so word boundaries survive // punctuation-adjacent words, then collapse repeated whitespace. const normalized = entry.text.toLowerCase().replace(/[^\w\s-]/g, " ").replace(/\s+/g, " "); if (pattern.test(normalized)) times.add(entry.start); } return Array.from(times); } // Denominator for the `freq` field, mirroring the original cell's approach // of using total candidate-matching term count (not vocabulary size). const totalMatches = commonNounMatches.length + properNounMatches.length || 1; const automatedFinalWords = automatedMerged.map(item => { const displayText = displayOverrides.get(item.text) || item.text; return { text: displayText, count: item.count, freq: item.count / totalMatches, startTimes: findTimestamps(item.text), similarity: item.similarity, // diagnostic only — null for proper nouns score: item.score // diagnostic only }; }); const manualFinalWords = manualWords.map(item => ({ ...item, freq: item.count / totalMatches })); const finalWords = [...manualFinalWords, ...automatedFinalWords]; // -------------------------------------------------------------------------- // VALIDATION GUARD — fail loudly rather than silently shipping a word that // would break the dashboard's click-to-cycle interaction (see BUG #3). // -------------------------------------------------------------------------- const brokenWords = finalWords.filter(w => w.startTimes.length === 0); if (brokenWords.length > 0) { console.warn("wordsObservableAI: words with zero startTimes (would break click-to-seek):", brokenWords.map(w => w.text)); } // Final sort by raw count for a stable, human-readable default ordering // (matches the original cell's output ordering convention). This sort // happens AFTER selection, purely for display — it does not affect which // words made the cut in stages 2-4 above. return finalWords.sort((a, b) => b.count - a.count); }32:T21f9,// Observable Notebook Cell: wordsGeminiAI // Generates a filtered, weighted keyword frequency array with deduplicated video timestamp mappings // // MANUAL CURATION NOTE: the final block of this cell merges in `manualThemeWords` // (Interpretability / Verifiability / Trust) -- three words a human (the // notebook author) identified as the video's central theme at 50:58, which // this automated frequency-based pipeline structurally cannot detect on its // own. See the `manualThemeWords` cell for the full "why", and the // "Acknowledgments & Collaboration" section for the bigger-picture discussion // of human+AI collaboration in this notebook. wordsGeminiAI = { // Reuse the shared `completeTranscript` (cell 81) and `doc` (cell 22) rather // than recomputing them locally -- this cell used to redo an entire // Compromise NLP parse (~0.5s over this transcript) that had already been // done once for the whole notebook. // 1. FILTERING RULES & ALLOWLISTS const transcriptStopWords = new Set([ // Conversational fillers & speech markers "uh", "um", "like", "yeah", "okay", "ok", "so", "well", "right", "you know", "basically", "actually", "literally", "honestly", "obviously", "mean", "kind", "sort", "stuff", "thing", "things", "way", "ways", "lot", "lots", "guess", "maybe", "little", "part", "parts", "sense", "point", "idea", "example", "examples", // Common speech verbs "know", "think", "going", "just", "really", "see", "say", "said", "saying", "got", "get", "getting", "go", "goes", "went", "gone", "make", "makes", "made", "come", "comes", "came", "take", "takes", "took", "want", "wants", "look", "looks", "looking", "let", "lets", "tell", "tells", "told", "talk", "talking", "talked", "try", "trying", "tried", "need", "needs", "needed", "feel", "feeling", "call", "called", "use", "uses", "used", "using", "work", "works", // High-frequency pronouns, generic entities, & UI meta terms "people", "person", "somebody", "someone", "something", "anything", "everything", "nothing", "everybody", "everyone", "anybody", "nobody", "time", "times", "today", "day", "year", "years", "guy", "guys", "man", "user", "users", "human", "humans", "them", "our", "your", "yours", "their", "theirs", "him", "her", "me", "us", "you", "we", "they", // Word fragments, HTML elements, & transcript artifacts "pre", "re", "post", "sub", "pro", "non", "anti", "div", "span", // Grammatical function words "the", "be", "to", "of", "and", "a", "in", "that", "have", "i", "it", "for", "not", "on", "with", "he", "as", "do", "at", "this", "but", "his", "by", "from", "or", "an", "will", "my", "one", "all", "would", "there", "what", "up", "out", "if", "about", "who", "which", "when", "can", "here", "then", "than", "now", "also", "into", // Standard & Stripped Contractions "can't", "cant", "cannot", "could", "couldn't", "couldnt", "should", "shouldn't", "shouldnt", "wouldn't", "wouldnt", "don't", "dont", "doesn't", "doesnt", "didn't", "didnt", "isn't", "isnt", "aren't", "arent", "wasn't", "wasnt", "weren't", "werent", "haven't", "havent", "hasn't", "hasnt", "hadn't", "hadnt", "there's", "theres", "that's", "thats", "it's", "its", "what's", "whats", "here's", "heres", "who's", "whos", "where's", "wheres", "how's", "hows", "let's", "lets", "i'm", "im", "you're", "youre", "we're", "were", "they're", "theyre", "i've", "ive", "you've", "youve", "we've", "weve", "they've", "theyve", "i'll", "ill", "you'll", "youll", "he'll", "hell", "she'll", "shell", "we'll", "well", "they'll", "theyll", "i'd", "id", "you'd", "youd" ]); // Short technical acronyms/terms permitted despite length < 3 const shortAllowlist = new Set(["d3", "ai", "js", "ui", "svg", "api", "dom", "db", "3d", "2d"]); // Display map to preserve canonical casing const displayOverrides = new Map([ ["d3", "D3"], ["js", "JS"], ["ui", "UI"], ["ai", "AI"], ["svg", "SVG"], ["html", "HTML"], ["dom", "DOM"], ["api", "API"], ["3d", "3D"], ["2d", "2D"] ]); // 2. NLP EXTRACTION const matches = doc.match("(#Noun|#ProperNoun)").concat(doc.topics()); const termMap = new Map(); const totalMatches = matches.length || 1; matches.out('array').forEach(m => { let clean = String(m) .toLowerCase() .replace(/'s$/g, '') .replace(/[^\w\s-]/g, '') .trim(); const isAllowedShortTerm = shortAllowlist.has(clean); // Filter: bypass length check if term is present in shortAllowlist if ( !clean || (!isAllowedShortTerm && clean.length < 3) || transcriptStopWords.has(clean) || /^\d+$/.test(clean) ) { return; } const displayText = displayOverrides.get(clean) || clean; if (!termMap.has(displayText)) { termMap.set(displayText, { text: displayText, count: 0 }); } termMap.get(displayText).count += 1; }); // 3. METRIC COMPUTATION const rawTerms = Array.from(termMap.values()) .map(item => ({ ...item, freq: item.count / totalMatches })) .sort((a, b) => b.count - a.count); // 4. TIMESTAMP INDEXING (Deduplicated) // Uses Set structures to prevent identical timestamps caused by duplicate word occurrences // within a single transcript caption segment or overlapping transcript entries. const wordTimeMap = new Map(); for (const entry of parsedTranscript) { const extractedWords = entry.text .toLowerCase() .replace(/'s$/g, "") .replace(/[^\w\s]/g, "") .split(/\s+/); for (const word of extractedWords) { if (!word) continue; if (!wordTimeMap.has(word)) { wordTimeMap.set(word, new Set()); } wordTimeMap.get(word).add(entry.start); } } // Map deduplicated timestamps back to rawTerms as standard arrays rawTerms.forEach(item => { const normalizedLookup = item.text .toLowerCase() .replace(/'s$/g, "") .replace(/[^\w\s]/g, "") .trim(); const timeSet = wordTimeMap.get(normalizedLookup); item.startTimes = timeSet ? Array.from(timeSet) : []; }); // 5. OUTPUT THRESHOLD const qualifyingTerms = rawTerms.filter(item => item.count >= 3); // -------------------------------------------------------------------------- // 6. MANUAL CURATION OVERRIDE (see `manualThemeWords` cell for full rationale) // -------------------------------------------------------------------------- // Frequency-only ranking, by construction, cannot see a theme that's spoken // across several word FORMS rather than one repeated token -- exactly what // happens with "interpretability"/"verifiability" (see manualThemeWords). // The notebook author judged these three words -- Bostock's own explicit // answer, at 50:58, to what any code-development effort needs -- to be the // dominant theme of the entire video, and is deliberately overriding the // algorithm to guarantee they appear, and appear LARGEST, regardless of // what raw frequency alone would say. This is intentionally visible, not // silently patched: see `isManual` / `manualNote` on the returned objects, // and the dedicated "‡" marker + styling applied to these words in // `createWordCloudSvg` (cell 33). // // To honor the agreed 75-word cloud budget (rather than growing it to 78 // and further crowding the UI), room is made for these 3 by dropping the 3 // LOWEST-ranked automated words that would otherwise have barely made the // cut -- a trade-off the notebook author judged well worth it given how // much interpretive value these three words add versus marginal words like // e.g. "level" or "key" that would otherwise round out the bottom of the list. const topAutomatedCount = qualifyingTerms[0]?.count ?? 0; const boostByPriority = [15, 10, 5]; // priority 1 (Interpretability) boosted most const manualWords = manualThemeWords.map(theme => { const boostedCount = topAutomatedCount + boostByPriority[theme.priority - 1]; return { text: theme.text, count: boostedCount, // artificially boosted -- see comment above freq: boostedCount / totalMatches, startTimes: theme.startTimes, // REAL timestamps -- clicking/cycling behaves like any other word isManual: true, manualNote: theme.manualNote, rawMentionCount: theme.rawMentionCount // diagnostic: the true, unboosted mention count across all spoken forms }; }); const trimmedAutomated = qualifyingTerms.slice(0, 75 - manualWords.length); return [...manualWords, ...trimmedAutomated].sort((a, b) => b.count - a.count); }33:T4d4,// One-time BUILD TRIGGER for the "Observable AI Logic" pipeline (renamed from // `observableAIRequested` -- it's no longer tied to a user request at all). // Starts `false`. Instead of waiting for the user to click "Observable AI // Logic" in the dashboard's radio control, this is now flipped to `true` // exactly ONCE, automatically, right after `viewof dashboard` (cell 43) // completes its very first render -- see the "ONE-TIME BUILD TRIGGER" block // near the bottom of that cell. This lets the slow in-browser embedding // model download + ~130 embedding calls happen quietly in the background // immediately after the dashboard is on screen, so that by the time a // visitor actually selects "Observable AI Logic" the data is USUALLY already // sitting ready -- without ever blocking the dashboard's own initial paint // on it, and completely independent of whether the user ever touches that // radio at all. // // Once set to `true` here, nothing in the notebook ever sets it back to // `false`, and nothing sets it a second time (see the `if (!pipelineTriggered)` // guard in cell 43) -- so the pipeline it gates (cells 131/134/119) runs // its real work exactly once, ever, per page load. mutable pipelineTriggered = false;34:T4c2,// ============================================================================ // wordsSyncGuard — tiny persistent guard object used by `wordsSync` (cell 163) // to avoid REDUNDANT reassignments of `mutable words` (cell 126). // ============================================================================ // This is a plain object, computed once and never reassigned, so referencing // it does NOT create a reactive dependency that changes over time -- other // cells can freely mutate its properties without ever causing themselves (or // anything else) to re-run because of it. That makes it safe to use as // cross-run memory for `wordsSync` without introducing a self-referential // dependency on `words` itself (which would be circular, since that cell also // WRITES `mutable words`). // // Seeded to "gemini" because cell 126 already initializes `mutable words = // wordsGeminiAI` directly as the page's very first paint -- so the first time // `wordsSync` runs (which happens immediately on load, since all of its // inputs already have values then), it should recognize "gemini" as already // in effect and skip reassigning the same array a second time. wordsSyncGuard = ({ lastAssignedSource: "gemini" })35:Tc84,/** * Parses raw video/audio transcript text containing timestamps and text lines * into a structured array of cue objects. * * Supports both "MM:SS" and "HH:MM:SS" timestamp formats. * * @param {string} rawText - The unparsed transcript block. * @returns {Array