learnx-cli 0.3.0__py3-none-any.whl

tutor/player/player.py

@@ -0,0 +1,308 @@
+import logging
+import os
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from tutor.infra.llm import LLMFn
+
+import pygame
+
+from tutor.constants import PLAYER_POLL_HZ
+from tutor.models import Chunk, SessionLog, TeachingUnit
+from tutor.player import input_handler, player_display
+
+log = logging.getLogger(__name__)
+
+PlayerState = Literal["PLAYING", "PAUSED", "ASKING", "ANSWERING", "STOPPED"]
+
+MUSIC_END = pygame.USEREVENT + 1
+
+
+@dataclass
+class TutorPlayer:
+    unit_files: list[str]
+    units: list[TeachingUnit]
+    chunks: list[Chunk] = field(default_factory=list)
+    session: SessionLog | None = None
+    llm_fn: "LLMFn | None" = None
+    no_qa: bool = False
+    qa_count: int = 0
+    _state: PlayerState = field(default="PAUSED", init=False)
+    _current_idx: int = field(default=0, init=False)
+    _start_time: float = field(default=0.0, init=False)
+    _pause_start: float = field(default=0.0, init=False)
+    _current_unit_duration_s: int = field(default=0, init=False)
+    _duration_cache: dict[str, int] = field(default_factory=dict, init=False)
+
+    def run(self) -> None:
+        os.environ.setdefault("SDL_VIDEODRIVER", "dummy")
+        pygame.init()
+        pygame.mixer.init()
+        pygame.mixer.music.set_endevent(MUSIC_END)
+
+        self._load_unit(0)
+        self._play()
+
+        poll_interval = 1.0 / PLAYER_POLL_HZ
+
+        try:
+            while self._state != "STOPPED":
+                self._handle_events()
+                self._handle_keys()
+                self._redraw()
+                time.sleep(poll_interval)
+        except KeyboardInterrupt:
+            pass
+        finally:
+            pygame.mixer.quit()
+            pygame.quit()
+
+    def _play(self) -> None:
+        pygame.mixer.music.play()
+        self._state = "PLAYING"
+        self._start_time = time.time()
+
+    def _pause(self) -> None:
+        pygame.mixer.music.pause()
+        self._pause_start = time.time()
+        self._state = "PAUSED"
+
+    def _resume(self) -> None:
+        pygame.mixer.music.unpause()
+        paused_for = time.time() - self._pause_start
+        self._start_time += paused_for
+        self._state = "PLAYING"
+
+    def _load_unit(self, idx: int) -> None:
+        if idx >= len(self.unit_files):
+            self._on_session_complete()
+            return
+        self._current_idx = idx
+        path = self.unit_files[idx]
+        pygame.mixer.music.load(path)
+        if path not in self._duration_cache:
+            try:
+                from pydub import AudioSegment
+
+                audio = AudioSegment.from_mp3(path)
+                self._duration_cache[path] = len(audio) // 1000
+            except Exception:
+                self._duration_cache[path] = 0
+        self._current_unit_duration_s = self._duration_cache[path]
+        log.info("Loaded unit %d: %s", idx, path)
+
+    def _handle_events(self) -> None:
+        for event in pygame.event.get():
+            if event.type == MUSIC_END and self._state == "PLAYING":
+                next_idx = self._current_idx + 1
+                if next_idx < len(self.unit_files):
+                    self._load_unit(next_idx)
+                    self._play()
+                else:
+                    self._on_session_complete()
+
+    def _handle_keys(self) -> None:
+        if self._state in ("ASKING", "ANSWERING"):
+            return
+        key = input_handler.get_key()
+        if key is None:
+            return
+        dispatch: dict[str, Callable[[], None]] = {
+            " ": self._toggle_play_pause,
+            "p": self._toggle_play_pause,
+            "n": self._next_unit,
+            "b": self._prev_unit,
+            "r": self._replay_unit,
+            "s": self._print_summary,
+            "q": self._quit,
+            "?": self._ask_question,
+        }
+        action = dispatch.get(key)
+        if action:
+            action()
+
+    def _toggle_play_pause(self) -> None:
+        if self._state == "PLAYING":
+            self._pause()
+        elif self._state == "PAUSED":
+            self._resume()
+
+    def _next_unit(self) -> None:
+        was_playing = self._state == "PLAYING"
+        pygame.mixer.music.stop()
+        next_idx = min(self._current_idx + 1, len(self.unit_files) - 1)
+        self._load_unit(next_idx)
+        if was_playing:
+            self._play()
+
+    def _prev_unit(self) -> None:
+        was_playing = self._state == "PLAYING"
+        pygame.mixer.music.stop()
+        prev_idx = max(self._current_idx - 1, 0)
+        self._load_unit(prev_idx)
+        if was_playing:
+            self._play()
+
+    def _replay_unit(self) -> None:
+        pygame.mixer.music.stop()
+        self._load_unit(self._current_idx)
+        self._play()
+
+    def _print_summary(self) -> None:
+        if self._current_idx < len(self.units):
+            player_display.print_summary(self.units[self._current_idx])
+
+    def _quit(self) -> None:
+        pygame.mixer.music.stop()
+        self._state = "STOPPED"
+
+    def _ask_question(self) -> None:
+        if self.no_qa or self.llm_fn is None:
+            player_display.print_qa_disabled()
+            return
+
+        if self._state == "PLAYING":
+            self._pause()
+
+        self._state = "ASKING"
+        player_display.clear_status()
+        question = self._prompt_for_question()
+
+        if question is None:
+            self._state = "PAUSED"
+            return
+
+        self._state = "ANSWERING"
+        player_display.print_thinking()
+
+        from tutor.qa import qa
+
+        current_unit = (
+            self.units[self._current_idx] if self._current_idx < len(self.units) else None
+        )
+        if current_unit is None:
+            player_display.print_no_context()
+            self._state = "PAUSED"
+            return
+
+        assert self.session is not None
+        answer_text = qa.answer(
+            question=question,
+            current_unit=current_unit,
+            all_chunks=self.chunks,
+            session=self.session,
+            llm_fn=self.llm_fn,
+            position_seconds=self._elapsed_seconds(),
+        )
+        self.qa_count += 1
+
+        player_display.print_answer(answer_text, current_unit.concept)
+        self._state = "PAUSED"
+        player_display.print_resume_hint()
+
+    def _prompt_for_question(self) -> str | None:
+        unit = self.units[self._current_idx] if self._current_idx < len(self.units) else None
+        topic = unit.concept if unit else "current topic"
+        player_display.print_question_header(
+            topic, player_display._fmt_time(self._elapsed_seconds())
+        )
+        try:
+            return input("Your question: ").strip() or None
+        except (KeyboardInterrupt, EOFError):
+            player_display.print_cancelled()
+            return None
+
+    def _redraw(self) -> None:
+        if self._state == "STOPPED" or self._current_idx >= len(self.units):
+            return
+        unit = self.units[self._current_idx]
+        elapsed_s = self._elapsed_seconds()
+        total_s = self._unit_duration_s()
+        player_display.render_status(
+            unit=unit,
+            unit_idx=self._current_idx + 1,
+            total_units=len(self.units),
+            elapsed_s=elapsed_s,
+            total_s=total_s,
+            state=self._state,
+        )
+
+    def _elapsed_seconds(self) -> int:
+        if self._state == "PAUSED":
+            return int(self._pause_start - self._start_time)
+        if self._state == "PLAYING":
+            return int(time.time() - self._start_time)
+        return 0
+
+    def _unit_duration_s(self) -> int:
+        return self._current_unit_duration_s
+
+    def _get_duration(self, filepath: str) -> int:
+        return self._duration_cache.get(filepath, 0)
+
+    def run_in_shell(self) -> None:
+        """Headless playback loop for the interactive shell — no keyboard, no status bar."""
+        os.environ.setdefault("SDL_VIDEODRIVER", "dummy")
+        pygame.init()
+        pygame.mixer.init()
+        pygame.mixer.music.set_endevent(MUSIC_END)
+
+        self._load_unit(0)
+        self._play()
+
+        poll_interval = 1.0 / PLAYER_POLL_HZ
+
+        try:
+            while self._state != "STOPPED":
+                self._handle_events()
+                time.sleep(poll_interval)
+        finally:
+            pygame.mixer.quit()
+            pygame.quit()
+
+    def _ask_question_from_shell(self, question: str) -> None:
+        """Answer a question posed from the shell thread (question already collected)."""
+        if self.no_qa or self.llm_fn is None:
+            from tutor.cli import theme
+
+            print(theme.yellow("  Q&A is disabled (no API key or --no-qa set)."))
+            return
+        if self._current_idx >= len(self.units):
+            from tutor.cli import theme
+
+            print(theme.red("  No unit loaded."))
+            return
+
+        self._state = "ANSWERING"
+        from tutor.cli import theme
+
+        print(theme.dim("  Thinking..."))
+
+        from tutor.qa import qa
+
+        current_unit = self.units[self._current_idx]
+        assert self.session is not None
+        answer_text = qa.answer(
+            question=question,
+            current_unit=current_unit,
+            all_chunks=self.chunks,
+            session=self.session,
+            llm_fn=self.llm_fn,
+            position_seconds=self._elapsed_seconds(),
+        )
+        self.qa_count += 1
+
+        print(f"\n  {theme.bold(current_unit.concept)}")
+        print(f"  {answer_text}\n")
+        self._state = "PAUSED"
+
+    def _on_session_complete(self) -> None:
+        self._state = "STOPPED"
+        player_display.print_session_complete(
+            unit_count=len(self.units),
+            total_s=sum(self._get_duration(f) for f in self.unit_files),
+            qa_count=self.qa_count,
+        )

tutor/player/player_display.py

@@ -0,0 +1,117 @@
+import logging
+import sys
+
+from tutor.constants import PLAYER_BAR_WIDTH
+from tutor.models import TeachingUnit
+
+log = logging.getLogger(__name__)
+
+BORDER = "━" * 56
+COMMANDS_PLAYING = "  [space] pause   [?] ask   [n] next   [b] prev   [q] quit"
+COMMANDS_PAUSED = (
+    "  [space] resume   [?] ask   [n] next   [b] prev   [r] replay   [s] summary   [q] quit"
+)
+
+_first_render = True
+
+
+def render_status(
+    unit: TeachingUnit,
+    unit_idx: int,
+    total_units: int,
+    elapsed_s: int,
+    total_s: int,
+    state: str,
+) -> None:
+    """Redraw the status bar in-place using ANSI escape codes. Does not scroll."""
+    global _first_render
+    if not _first_render:
+        clear_status()
+    _first_render = False
+
+    bar = _progress_bar(elapsed_s, total_s)
+    elapsed_fmt = _fmt_time(elapsed_s)
+    total_fmt = _fmt_time(total_s)
+    state_tag = "  ⏸ PAUSED" if state == "PAUSED" else ""
+
+    line1 = f"  {unit.concept} — Unit {unit_idx}/{total_units}{state_tag}"
+    line2 = f"  {bar}  {elapsed_fmt} / {total_fmt}"
+    cmds = COMMANDS_PAUSED if state in ("PAUSED", "ASKING") else COMMANDS_PLAYING
+
+    sys.stdout.write(f"{BORDER}\n{line1}\n{line2}\n{BORDER}\n{cmds}\n")
+    sys.stdout.flush()
+
+
+def clear_status() -> None:
+    """Move cursor up 5 lines and clear each line."""
+    for _ in range(5):
+        sys.stdout.write("\033[F\033[2K")
+    sys.stdout.flush()
+
+
+def print_summary(unit: TeachingUnit) -> None:
+    print(f"\n{BORDER}")
+    print(f"  Summary: {unit.concept}")
+    print("  Key facts:")
+    for fact in unit.key_facts:
+        print(f"    • {fact}")
+    print(f"  Remember: {unit.memory_hook}")
+    print(f"{BORDER}\n")
+
+
+def print_session_complete(unit_count: int, total_s: int, qa_count: int) -> None:
+    print(f"\n{BORDER}")
+    print(f"  Session complete: {unit_count} units, {_fmt_time(total_s)}")
+    if qa_count:
+        print(f"  You asked {qa_count} question(s) this session.")
+    print(f"{BORDER}")
+    print("  [r] replay session   [q] quit\n")
+
+
+def print_qa_disabled() -> None:
+    print("\nQ&A disabled (--no-qa). Press [space] to resume.")
+
+
+def print_thinking() -> None:
+    print("\nThinking...", end="", flush=True)
+
+
+def print_no_context() -> None:
+    print("\n(No unit context available)")
+
+
+def print_resume_hint() -> None:
+    print("Press [space] to resume or [?] to ask another question.\n")
+
+
+def print_question_header(topic: str, position_fmt: str) -> None:
+    print("\n── Ask a question ──────────────────────────────────")
+    print(f"Topic: {topic}  |  Position: {position_fmt}")
+    print()
+
+
+def print_cancelled() -> None:
+    print(" (cancelled)")
+
+
+def print_answer(answer: str, unit_concept: str) -> None:
+    border = "─" * 56
+    print(f"\n{border}")
+    print(f"Answer:\n{answer}")
+    suffix = border[len(unit_concept) + 10 :]
+    print(f"\n── Source: §{unit_concept} {suffix}")
+    print()
+
+
+def _progress_bar(elapsed_s: int, total_s: int) -> str:
+    if total_s <= 0:
+        return "[" + "░" * PLAYER_BAR_WIDTH + "]"
+    ratio = min(elapsed_s / total_s, 1.0)
+    filled = int(ratio * PLAYER_BAR_WIDTH)
+    empty = PLAYER_BAR_WIDTH - filled
+    return "[" + "█" * filled + "░" * empty + "]"
+
+
+def _fmt_time(seconds: int) -> str:
+    m, s = divmod(max(seconds, 0), 60)
+    return f"{m:02d}:{s:02d}"

tutor/prompts/curriculum.txt

@@ -0,0 +1,67 @@
+You are an expert educator planning an audio episode in which two Java experts
+explain a document to listeners in a clear, step-by-step conversation.
+
+Document title: {doc_title}
+Target duration: {duration_min} minutes
+Difficulty: {difficulty}
+Audience: {difficulty_context}
+
+AUDIENCE BACKGROUND: The listener already knows JavaScript — functions, objects,
+prototypes, dynamic typing. Calibrate accordingly:
+- If Java behaves the same as JS, note it briefly and move on.
+- If Java behaves differently, that contrast is the most valuable thing to highlight.
+- Never explain what a variable or loop is from scratch.
+
+YOUR TASK: Read the section summaries and plan 3–8 teaching units that together
+walk the listener through the document's key concepts from start to finish.
+
+Each unit must:
+- Cover one clear, focused concept from the document
+- Have a concrete analogy that works in spoken audio (no code symbols, no diagrams)
+- Flow naturally from the previous unit — sequence matters
+- Build the listener's understanding progressively
+
+Sequencing rule: start with the most foundational idea, move towards more nuanced
+or complex ones. The listener should feel understanding accumulating across the episode.
+
+Java concept reference — use this to identify what is most important in the source:
+
+Tier 1 — Type system
+  primitives vs reference types | pass-by-value | autoboxing traps
+
+Tier 2 — OOP mechanics
+  constructors and this() | inheritance: extends / super() / @Override
+  is-a vs has-a | what is NOT inherited | overloading vs overriding | final
+
+Tier 3 — Contracts and polymorphism
+  interface as contract | interface vs abstract class | dynamic dispatch
+  compile-time vs runtime polymorphism | instanceof | Comparable / Iterable
+
+Tier 4 — Core contracts
+  equals() and hashCode() | == vs .equals() | Comparable vs Comparator
+
+Tier 5 — Collections
+  List / Set / Map | ArrayList vs LinkedList | HashMap internals
+
+Tier 6 — Error handling
+  exception hierarchy | checked vs unchecked | try-catch / finally
+  throw vs throws | custom exceptions | never swallow silently
+
+Section summaries:
+{summaries}
+
+Respond with a raw JSON array only. No text outside the array. Each element must have:
+- concept (string) — the concept name, as a listener would hear it
+- source_sections (array of chunk IDs from the summaries above)
+- complexity (integer 1, 2, or 3)
+- key_facts (array of 2–4 strings — the most important things to say about this concept)
+- common_misconception (string — the key insight that makes this concept click once you
+  truly understand it; the thing most explanations leave vague)
+- good_analogy (string — a concrete everyday analogy that works purely in spoken words;
+  no code, no symbols — something a non-programmer could picture)
+- js_contrast (string — "In JavaScript X; in Java Y" — empty string if not applicable)
+- question_style (string — one of: recall, error-spotting, judgment, predict-output, teach-back)
+- memory_hook (string — one short, memorable sentence the listener will carry away)
+- prerequisite_concepts (array of strings — concepts from earlier units this one builds on)
+- production_relevance (string — one sentence grounding this in real backend work:
+  Spring Boot, REST APIs, databases, or microservices)

tutor/prompts/dialogue.txt

@@ -0,0 +1,62 @@
+You are writing a script for two Java experts hosting an educational audio episode.
+
+ALEX is male. MAYA is female. Both are experienced Java engineers and clear communicators.
+They are NOT teacher and student — they are co-hosts explaining a concept to the listener
+together. Their tone is warm, natural, and direct. They complement each other: one sets
+up an idea, the other deepens or grounds it.
+
+WORD BUDGET: approximately {word_budget} words total (±15%).
+
+CODE IN SPEECH — never write symbols, only spoken English:
+  List<String>    →  "a List of Strings"
+  !=              →  "not equal to"
+  ==              →  "double equals"
+  .equals()       →  "dot equals"
+  @Override       →  "the Override annotation"
+  int[]           →  "int array"
+  super()         →  "super constructor call"
+  try-catch       →  "try-catch block"
+  instanceof      →  "instance of"
+  extends         →  "extends"
+  implements      →  "implements"
+  throws          →  "throws declaration"
+
+RULES:
+- Use the provided analogy exactly as given. Do not invent a different one.
+- If js_contrast is non-empty, work it in naturally — one of them says something like
+  "if you're coming from JavaScript, you might expect..." — make the contrast explicit.
+- End with the memory_hook spoken naturally as a closing thought from one of them.
+- If prerequisite_concepts is non-empty, open with a brief, one-sentence connection
+  to that prior concept before introducing this one.
+- No filler praise: no "Excellent!", "Great!", "Amazing!", "Absolutely!", "Perfect!".
+  Just natural acknowledgement and continuation.
+- Output only labeled lines: ALEX: ... / MAYA: ...
+- No blank lines between turns. No stage directions. No other speakers.
+
+BEAT STRUCTURE — follow this order:
+
+1. ALEX — Name the concept and open with WHY it matters to understand it well.
+   One or two sentences. If prerequisite_concepts is set, link to it first.
+
+2. MAYA — Add what makes this concept interesting or where people tend to get
+   confused. Draw from common_misconception — not as a wrong answer, but as the
+   thing that becomes clear once you really get it.
+
+3. ALEX — Introduce the analogy: "think of it like..." Build the mental picture
+   in two or three sentences using the provided good_analogy.
+
+4. MAYA — Extend the analogy or connect it to the first key fact. Make it
+   concrete for the listener — add a second angle that locks the image in.
+
+5. ALEX — State the precise rule or mechanism the listener must remember.
+   Pull from key_facts. Keep it crisp and definitive.
+
+6. MAYA — Translate that rule into a real scenario: "so in practice, this means..."
+   or "the moment this shows up in code is when...". Ground it so the listener
+   can picture it happening.
+
+7. ALEX — Add the second or third key fact, or the js_contrast if not yet used.
+   Connect to production_relevance — one sentence on where this matters in real work.
+
+8. MAYA — Close with the memory_hook as a natural takeaway. Something the listener
+   will remember when they encounter this in code.

tutor/prompts/narrate.txt

@@ -0,0 +1,34 @@
+You are ALEX, a clear and calm Java educator reading a tutorial aloud to a student
+who is following along on screen, scrolling through the document at the same pace.
+
+Document: {doc_title}
+Section {section_index} of {total_sections}: {heading}
+Target word count: approximately {word_budget} words
+
+Your job: read this section aloud, top to bottom, in natural spoken English.
+
+Rules:
+- Open with a single orienting sentence that names the section: "Section {section_index} covers..." or "This part is about...".
+- Follow the section content in order. Do not skip, reorder, or add content not in the source.
+- Translate every code example and symbol into spoken English:
+    List<String>       →  "a List of Strings"
+    @Override          →  "the Override annotation"
+    super()            →  "the super constructor call"
+    ==                 →  "double equals"
+    !=                 →  "not equal to"
+    .equals()          →  "dot equals"
+    int[]              →  "int array"
+    try-catch          →  "try-catch block"
+    instanceof         →  "instance of"
+    throws             →  "throws declaration"
+- Reference what the reader can see on screen: "the table here shows...", "in this code block...", "as the example above shows...".
+- Speak in second person: "you will notice...", "here you can see...", "as you read...".
+- Keep sentences short. One idea per sentence.
+- Do not quiz, test, or ask the student questions. Just narrate.
+- Output one ALEX: line per paragraph, table, code block, or logical group — not one giant line.
+  Aim for 4–10 ALEX: lines total.
+- Output only labeled lines in the format: ALEX: <spoken text>
+  No blank lines. No stage directions. No other speakers.
+
+Source section:
+{section_text}

tutor/prompts/qa.txt

@@ -0,0 +1,17 @@
+You are answering a student's question during a Java audio tutorial.
+The student just heard a dialogue about: {concept}.
+The student already knows JavaScript — calibrate your answer to their background:
+if the Java behavior is the same as JavaScript, say so briefly; if it differs,
+make that contrast the centre of your answer.
+
+Answer in 4–6 sentences. Rules:
+- Ground your answer in the provided source content. Quote it if helpful.
+- Do not re-explain what the audio already covered — add to it, correct a
+  misunderstanding, or go one level deeper.
+- If the concept connects to a real backend use case (Spring Boot, REST APIs,
+  database layers, microservices), mention it in one sentence.
+- If the question is outside the source material, say so in one sentence and give
+  a brief general answer, clearly labeled as outside the tutorial scope.
+- End with one short follow-up question that pushes their thinking one step further.
+- Cite the source section your answer draws from: (§ section name).
+- No "Great question!". No filler. Answer and move on.

tutor/prompts/summarize.txt

@@ -0,0 +1,9 @@
+Summarize the following section of a Java tutorial in exactly 4 sentences.
+
+Sentence 1 — Concept: state the core concept introduced and what the learner must understand about it.
+Sentence 2 — Key rule or trap: state the most important rule, OR the most common mistake a learner makes here (use the ⚠️ warnings or "common misconception" callouts in the text as your guide).
+Sentence 3 — JavaScript contrast: if the section draws a comparison to JavaScript, state what is the same and what is genuinely different in Java. If no JS contrast exists, state one concrete code-level detail (a method name, a keyword rule, an example outcome).
+Sentence 4 — Sequence: state what prior concept this builds on, and what later concept depends on understanding this correctly.
+
+Do not write "this section explains" — write as facts, not as a document description.
+Do not copy sentences verbatim from the source — restate in your own words.

tutor/prompts/visual.txt

@@ -0,0 +1,60 @@
+You are generating slide content for a Java audio tutorial visual.
+
+Given the unit metadata below, produce a JSON object with these exact fields:
+  hook_question    — one sharp question ALEX opens with (max 15 words)
+  key_points       — list of 3 to 5 bullet strings (max 12 words each, plain English)
+  code_snippet     — short Java code string if relevant, else null
+  diagram_type     — one of: class_diagram | flowchart | code_comparison | concept_map | none
+  diagram_spec     — see below
+  memory_hook      — the memory_hook field restated as a punchy sentence (max 10 words)
+
+DIAGRAM_SPEC VALUE RULES:
+
+For class_diagram, flowchart, or concept_map:
+  diagram_spec must be a JSON STRING containing valid Graphviz DOT code.
+  Do NOT make it a JSON object. It is a plain string.
+
+For code_comparison:
+  diagram_spec must be a JSON object with keys: wrong, right, label_wrong, label_right
+
+For none:
+  diagram_spec must be null
+
+COMPLETE OUTPUT EXAMPLE (concept_map):
+
+{
+  "hook_question": "Interface or abstract class — which fits?",
+  "key_points": [
+    "Interface defines a contract",
+    "Abstract class adds shared state",
+    "Use interface for multiple inheritance"
+  ],
+  "code_snippet": null,
+  "diagram_type": "concept_map",
+  "diagram_spec": "graph G {\n  layout=neato\n  graph [bgcolor=\"#0d1117\"]\n  node [style=\"filled,rounded\" fillcolor=\"#161b22\" color=\"#30363d\" fontcolor=\"#e6edf3\" fontsize=13 shape=box]\n  edge [color=\"#8b949e\" fontcolor=\"#8b949e\" fontsize=10]\n  Interface [label=\"Interface\" fontsize=16 color=\"#00b4d8\"]\n  Abstract [label=\"Abstract Class\"]\n  Interface -- Abstract [label=\"vs\"]\n}",
+  "memory_hook": "Interface = contract, abstract class = blueprint."
+}
+
+COMPLETE OUTPUT EXAMPLE (flowchart):
+
+{
+  "hook_question": "Does == compare value or reference?",
+  "key_points": [
+    "== compares object references",
+    ".equals() compares content",
+    "Always use .equals() for strings"
+  ],
+  "code_snippet": "s1.equals(s2)",
+  "diagram_type": "flowchart",
+  "diagram_spec": "digraph G {\n  rankdir=TB\n  graph [bgcolor=\"#0d1117\"]\n  node [style=filled fillcolor=\"#161b22\" color=\"#30363d\" fontcolor=\"#e6edf3\" fontsize=13]\n  edge [color=\"#8b949e\" fontcolor=\"#8b949e\" fontsize=11]\n  start [label=\"Compare strings\" shape=oval color=\"#00b4d8\" fillcolor=\"#1a1a2e\"]\n  decide [label=\"Same object?\" shape=diamond color=\"#e3b341\" fillcolor=\"#2a1a0d\"]\n  yes [label=\"== is true\" shape=box color=\"#3fb950\" fillcolor=\"#0d2a1a\"]\n  no [label=\"Use .equals()\" shape=box]\n  start -> decide\n  decide -> yes [label=\"yes\"]\n  decide -> no [label=\"no\"]\n}",
+  "memory_hook": "Strings need .equals(), not ==."
+}
+
+CRITICAL RULES for the DOT string:
+- It is a JSON string value — write it as a single string with \n for newlines
+- It MUST start with digraph or graph and contain { ... }
+- Statements separated by newlines (\n), never semicolons
+- Maximum 6 nodes
+- Node labels: plain text only, no unescaped quotes inside the string
+
+Output only the JSON object. No prose, no markdown fences before or after.