🧠 LLM Context Management and Dynamic System Prompts

# ── All imports ───────────────────────────────────────────────────────
# ── Standard Library ──────────────────────────────────────────────────
import os
import json
import re
import re as _re
import time
import time as _time
import warnings
from datetime import datetime
warnings.filterwarnings('ignore')
import threading
from IPython.display import display, Javascript

# ── Notebook Display ──────────────────────────────────────────────────
# Tools for rendering interactive UI elements inside Jupyter
from IPython.display import display, HTML, clear_output
import ipywidgets as widgets

# ── LLM Backend ───────────────────────────────────────────────────────
# llama_cpp loads and runs our local language model
from llama_cpp import Llama

# ── Custom Utilities (utils.py) ───────────────────────────────────────
# All heavy logic is abstracted here to keep the notebook clean and readable
from utils import (
    build_system_message, build_course_prompt,   # Prompt construction
    count_tokens, estimated_wait,                 # Token management
    summarize_full_text, extract_key_entities,    # Compression strategies
    compress_semantic, detect_profile_changes,    # Context optimization
    ChatAssistant,                                # Core chat engine
    visualize_context_window,                     # Visual diagnostics
    retrieve, rag_chat,                           # RAG pipeline
    bubble, token_pill,                           # UI components
)

print('✅ Imports done.')

# ── Model Configuration ────────────────────────────────────────────────
# We use a quantized (Q4_K_M) version of Llama 3.2 1B to reduce memory
# usage while keeping reasonable performance on a shared server.

model_filename = 'Llama-3.2-1B-Instruct-Q4_K_M.gguf'
model_path     = f'/home/jovyan/shared/{model_filename}'

# n_ctx: how many tokens the model can "see" at once (its short-term memory)
# 4096 tokens ≈ ~3,000 words — enough for a full tutoring conversation
n_ctx     = 4096

# n_threads: number of CPU cores used for inference
# 4 is a safe default for a shared JupyterHub environment
n_threads = 4

print(f'Model    : {model_filename}')
print(f'Path     : {model_path}')
print(f'Context  : {n_ctx} tokens')
print(f'Threads  : {n_threads}')

# ── Verify the model file exists before loading ────────────────────────
# Loading a missing model causes a cryptic error deep in llama_cpp.
# We catch it early here and give a clear, actionable message instead.

if os.path.exists(model_path):
    size_gb = os.path.getsize(model_path) / (1024**3)
    print(f'✅ Found  {model_filename}  ({size_gb:.2f} GB)')
else:
    print('❌ Model not found — ask your teacher to check the shared folder.')
    raise FileNotFoundError(f'Model not found at {model_path}')

# ── Load model into memory ─────────────────────────────────────────────
# This is the most time-consuming step — the model file is read from disk
# and loaded into RAM. It only happens once per kernel session.

print('⏳ Loading model…  (this may take 1-2 minutes)\n')

model = Llama(
    model_path = model_path,
    n_ctx      = n_ctx,
    n_threads  = n_threads,
    verbose    = False,  # suppress llama_cpp's internal logs (very noisy)
)

# Clear the noisy llama_cpp output and replace with a clean summary
clear_output(wait=True)
print('=' * 50)
print('✅ Model loaded and ready!')
print('=' * 50)
print(f'  Model   : {model_filename}')
print(f'  Context : {n_ctx} tokens')
print(f'  Threads : {n_threads}')

# Part 1 — Interactive widget: students experience how the messages list works as the model's only memory


display(HTML('<style>.jp-OutputArea-output { overflow: visible !important; max-height: none !important; }</style>'))

display(HTML("""
<style>
@keyframes fadeOut {
  from { opacity:1; transform:translateY(0);   max-height:120px; margin:5px 0; }
  to   { opacity:0; transform:translateY(-6px); max-height:0;    margin:0;     }
}
@keyframes fadeIn {
  from { opacity:0; transform:translateY(8px); }
  to   { opacity:1; transform:translateY(0);   }
}
@keyframes shake {
  0%,100%{transform:translateX(0)}
  20%{transform:translateX(-8px)} 40%{transform:translateX(8px)}
  60%{transform:translateX(-5px)} 80%{transform:translateX(5px)}
}
.bubble-wrap  { animation: fadeIn 0.35s ease both; }
.bubble-dying { animation: fadeOut 0.5s ease forwards; overflow:hidden; }
.amnesiac     { animation: shake 0.5s ease; }
.token-pill {
  display:inline-block; background:#313244; border-radius:20px;
  padding:2px 10px; font-size:0.76em; color:#a6adc8; margin-left:8px;
}
.token-pill.warn { background:#f9e2af22; color:#f9e2af; }
.token-pill.crit { background:#f38ba822; color:#f38ba8; }
</style>
"""))

# ── Progress bar (shown while the model is generating) ────────────────
def show_progress(output_widget, estimated_seconds):
    """
    Display an animated progress bar while the model is thinking.
    Uses estimated_wait() from utils.py to set the duration.
    """
    bar = widgets.IntProgress(
        value=0, min=0, max=100,
        bar_style='info',
        layout=widgets.Layout(width='100%', height='12px'),
    )
    label = widgets.HTML(
        f'<span style="color:#a6adc8;font-size:0.82em">'
        f'🧠 Model is thinking… (~{estimated_seconds:.0f}s)</span>'
    )
    with output_widget:
        clear_output(wait=True)
        display(widgets.VBox([label, bar],
                layout=widgets.Layout(padding='10px 0')))

    steps = 30  # number of increments — more steps = smoother animation
    for i in range(steps + 1):
        bar.value = int(i / steps * 100)
        time.sleep(estimated_seconds / steps)

# ── Shared state ──────────────────────────────────────────────────────
# Dicts instead of plain variables so nested functions can mutate them
state        = {"index": 0}   # which challenge is currently active
student_name = {"v": ""}      # saved so Challenge 2 can personalise its message
_c1_history  = {"msgs": []}   # full messages list from Challenge 1, reused in Challenge 2

# ── System prompt ─────────────────────────────────────────────────────
# Intentionally strict about name recall so the contrast between
# Challenge 1 (remembers) and Challenge 2 (forgets) is unmistakable
SYSTEM_PROMPT = (
    "You are an AI tutor. A student is talking to you. "
    "The student's name and background will appear in their first message. "
    "IMPORTANT: When the student introduces themselves, acknowledge them by name in your reply. "
    "When asked who the student is, state their name and background exactly as they told you. "
    "For example: 'The student I am talking to is Zoey, a Data 100 student learning machine learning.' "
    "Never say you don't know the student's name if they have already introduced themselves. "
    "Keep replies to 1-2 sentences."
)

# ── Widgets ───────────────────────────────────────────────────────────
banner_out  = widgets.Output()
preview_out = widgets.Output()
output_area = widgets.Output()

c1_name = widgets.Text(placeholder="e.g. your name",
                       layout=widgets.Layout(width="280px"))
c1_like = widgets.Text(placeholder="e.g. Data 8 student, just starting with the datascience library",
                       layout=widgets.Layout(width="480px"))
c1_form = widgets.VBox([
    widgets.HTML('<div style="color:#a6adc8;font-size:0.84em;margin:10px 0 4px 0">'
                 '👤 Your name:</div>'),
    c1_name,
    widgets.HTML('<div style="color:#a6adc8;font-size:0.84em;margin:8px 0 4px 0">'
                 '📚 Something about yourself (course, background, what you\'re learning):</div>'),
    c1_like,
], layout=widgets.Layout(display="none", padding="0 0 10px 0"))

send_btn = widgets.Button(description="▶ Send", button_style="primary",
                          layout=widgets.Layout(width="110px", margin="10px 6px 0 0"))
next_btn = widgets.Button(description="Next →", button_style="info",
                          layout=widgets.Layout(width="110px", margin="10px 0 0 0"))

# ── Challenge definitions ─────────────────────────────────────────────
CHALLENGES = [
    {
        "id": "c1", "label": "Challenge 1 of 2",
        "title": "The AI remembers — because YOU gave it the memory",
        "color": "#89b4fa", "icon": "🧠",
        "instruction": "Enter your name and something about yourself, then hit <strong>Send</strong>.",
        "hint": "Every message in the list is part of the AI's memory. It can see all of them.",
        "form": "c1",
    },
    {
        "id": "c2", "label": "Challenge 2 of 2",
        "title": "Watch your memory disappear.",
        "color": "#f38ba8", "icon": "💀",
        "instruction": "Watch the messages vanish — then hit <strong>Send</strong> to confirm the AI forgot everything.",
        "hint": "The AI only sees what's in the list right now. No list = no memory.",
        "form": None,
    },
]

# ── Banner & layout ───────────────────────────────────────────────────
def load_challenge(idx):
    c = CHALLENGES[idx]
    with banner_out:
        clear_output(wait=True)
        display(HTML(f"""
        <div style="background:#1e1e2e;border:2px solid {c['color']};
                    border-radius:12px;padding:16px 20px;margin:10px 0">
          <div style="display:flex;align-items:center;gap:10px;margin-bottom:8px">
            <span style="font-size:1.6em">{c['icon']}</span>
            <div>
              <div style="color:{c['color']};font-weight:bold;font-size:0.85em">{c['label']}</div>
              <div style="color:#cdd6f4;font-weight:bold;font-size:1em">{c['title']}</div>
            </div>
          </div>
          <div style="color:#cdd6f4;font-size:0.9em;margin-bottom:6px">{c['instruction']}</div>
          <div style="color:#a6adc8;font-size:0.8em">💡 {c['hint']}</div>
        </div>"""))

    c1_form.layout.display = "" if c["form"] == "c1" else "none"

    if c["id"] == "c1":
        refresh_c1_preview()
    else:
        saved = _c1_history.get("msgs")
        render_preview(saved if saved else [], label="📨 This was your memory from Challenge 1…")

    next_btn.disabled    = (idx == len(CHALLENGES) - 1)
    next_btn.description = "✅ Done" if idx == len(CHALLENGES) - 1 else "Next →"
    with output_area:
        clear_output()

# ── Preview panel ─────────────────────────────────────────────────────
def render_preview(messages, label=None):
    label = label or f'📨 Messages the model will receive {token_pill(messages, model)}'
    bubs  = "".join(bubble(m["role"], m["content"]) for m in messages)
    with preview_out:
        clear_output(wait=True)
        display(HTML(
            f'<div style="background:#1e1e2e;border-radius:10px;padding:14px">'
            f'<div style="color:#585b70;font-size:0.78em;margin-bottom:6px">{label}</div>'
            f'{bubs}</div>'))

def refresh_c1_preview(*_):
    name = c1_name.value.strip() or "you"
    like = c1_like.value.strip() or "…"
    msgs = [
        {"role": "system",    "content": SYSTEM_PROMPT},
        {"role": "user",      "content": f"Hi! My name is {name}. {like}."},
        {"role": "assistant", "content": "( AI will reply here after Turn 1 )"},
        {"role": "user",      "content": "What is my name, and what is my background?"},
    ]
    render_preview(msgs)

c1_name.observe(refresh_c1_preview, names="value")
c1_like.observe(refresh_c1_preview, names="value")

# ── Amnesia animation (Challenge 2) ───────────────────────────────────
def play_amnesia_then_send():
    full_msgs = _c1_history.get("msgs", [])
    if not full_msgs:
        with output_area:
            clear_output()
            display(HTML('<p style="color:#f38ba8">⚠️ Please complete Challenge 1 first!</p>'))
        return

    for i in range(len(full_msgs) - 1):
        surviving = [
            bubble(m["role"], m["content"],
                   extra_class="bubble-dying" if j == i else "")
            for j, m in enumerate(full_msgs)
        ]
        with preview_out:
            clear_output(wait=True)
            display(HTML(
                '<div style="background:#1e1e2e;border-radius:10px;padding:14px">'
                '<div style="color:#f38ba8;font-size:0.78em;margin-bottom:6px">'
                '🗑️ Erasing memory…</div>'
                + "".join(surviving) + "</div>"))
        time.sleep(0.6)

    lone = [{"role": "user", "content": "What is the name of the student you are talking to, and what is their background?"}]
    with preview_out:
        clear_output(wait=True)
        display(HTML(
            '<div style="background:#1e1e2e;border-radius:10px;padding:14px">'
            f'<div style="color:#f38ba8;font-size:0.78em;margin-bottom:6px">'
            f'📨 All that remains {token_pill(lone, model)}</div>'
            + bubble(lone[0]["role"], lone[0]["content"]) + "</div>"))

    # Show progress bar while model generates
    wait = estimated_wait(count_tokens(lone, model))
    show_progress(output_area, wait)

    resp  = model.create_chat_completion(messages=lone, max_tokens=60, temperature=0.7)
    reply = resp["choices"][0]["message"]["content"].strip()
    name  = student_name["v"] or "you"

    with output_area:
        clear_output(wait=True)
        display(HTML(f"""
        <div class="amnesiac" style="background:#1e1e2e;border-radius:10px;
                    padding:14px;margin-top:8px">
          <div style="color:#585b70;font-size:0.78em;margin-bottom:8px">🤖 Model reply</div>
          {bubble("assistant", reply)}
          <div style="background:#f38ba822;border:2px solid #f38ba8;border-radius:10px;
               padding:12px 16px;margin-top:12px;text-align:center">
            <div style="font-size:1.4em;margin-bottom:4px">🫥</div>
            <div style="color:#f38ba8;font-weight:bold">Complete amnesia.</div>
            <div style="color:#a6adc8;font-size:0.82em;margin-top:6px;line-height:1.7">
              The model received <strong style="color:#f38ba8">1 message</strong> — no history, no name, nothing.<br>
              It has no idea who <strong style="color:#cdd6f4">{name}</strong> is.<br><br>
              <strong style="color:#cdd6f4">This is what Zoe's first broken prototype felt like.</strong><br>
              <span style="color:#a6adc8">The fix? Pass the full messages list every time. That's what Part 2 builds.</span>
            </div>
          </div>
        </div>"""))

# ── Send handler ──────────────────────────────────────────────────────
def on_send(btn):
    c = CHALLENGES[state["index"]]
    send_btn.disabled    = True
    send_btn.description = "⏳ …"

    if c["id"] == "c2":
        with output_area:
            clear_output()
        play_amnesia_then_send()

    else:  # Challenge 1
        name = c1_name.value.strip()
        like = c1_like.value.strip()
        if not name or not like:
            with output_area:
                clear_output()
                display(HTML('<p style="color:#f38ba8">⚠️ Enter your name and something about yourself first!</p>'))
            send_btn.disabled    = False
            send_btn.description = "▶ Send"
            return
        student_name["v"] = name

        # Turn 1: student introduces themselves
        turn1 = [
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user",   "content": f"Hi! My name is {name}. {like}."},
        ]
        wait = estimated_wait(count_tokens(turn1, model))
        show_progress(output_area, wait)
        resp1    = model.create_chat_completion(messages=turn1, max_tokens=60, temperature=0.7)
        ai_reply = resp1["choices"][0]["message"]["content"].strip()

        # Turn 2: ask if the model remembers — the key demonstration
        turn2 = turn1 + [
            {"role": "assistant", "content": ai_reply},
            {"role": "user",      "content": "What is the name of the student you are talking to, and what is their background?"},
        ]
        _c1_history["msgs"] = turn2  # save for Challenge 2 to reuse

        wait = estimated_wait(count_tokens(turn2, model))
        show_progress(output_area, wait)
        resp2 = model.create_chat_completion(messages=turn2, max_tokens=80, temperature=0.7)
        final = resp2["choices"][0]["message"]["content"].strip()

        bubs = "".join(bubble(m["role"], m["content"]) for m in turn2)
        with output_area:
            clear_output(wait=True)
            display(HTML(f"""
            <div style="background:#1e1e2e;border-radius:10px;padding:14px;margin-top:8px">
              <div style="color:#585b70;font-size:0.78em;margin-bottom:8px">
                📨 What the model received {token_pill(turn2, model)}</div>
              {bubs}
              <div style="border-top:1px solid #313244;margin:10px 0"></div>
              <div style="color:#585b70;font-size:0.78em;margin-bottom:6px">🤖 Model reply</div>
              {bubble("assistant", final)}
              <div style="background:#89b4fa22;border:1px solid #89b4fa44;border-radius:8px;
                   padding:10px 14px;margin-top:10px;font-size:0.82em;color:#a6adc8">
                ✅ The AI knows your name because <strong style="color:#cdd6f4">you gave it the memory</strong>.
                Hit <strong style="color:#89b4fa">Next →</strong> to see what happens when that memory disappears.
              </div>
            </div>"""))

    send_btn.disabled    = False
    send_btn.description = "▶ Send"

def on_next(btn):
    nxt = state["index"] + 1
    if nxt < len(CHALLENGES):
        state["index"] = nxt
        load_challenge(nxt)

send_btn.on_click(on_send)
next_btn.on_click(on_next)

# ── Initial render ────────────────────────────────────────────────────
display(widgets.HTML("""
<div style="background:#1e1e2e;padding:16px 20px;border-radius:12px;margin-bottom:4px">
  <h3 style="color:#cdd6f4;margin:0 0 6px 0">🧠 Part 1: The messages List is the AI's Entire Memory</h3>
  <p style="color:#a6adc8;margin:0;font-size:0.88em">
    Two challenges. Each one lets you <em>feel</em> how AI memory works — and breaks.
  </p>
</div>
"""))
load_challenge(0)
display(banner_out, c1_form, preview_out,
        widgets.HBox([send_btn, next_btn]), output_area)

# Demo: same question sent to Data 8 and Data 100 prompts side-by-side to show how system prompts change behaviour

# ── Data 8 vs Data 100 System Prompt Builder ─────────────────────────
question = "How do I read a CSV file?"

COURSE_COLORS = {
    "Data 8":   {"border": "#a6e3a1", "label": "#a6e3a1", "keyword": "datascience", "kw_color": "#a6e3a1"},
    "Data 100": {"border": "#89b4fa", "label": "#89b4fa", "keyword": "pandas",      "kw_color": "#89b4fa"},
}

def highlight(text, keyword, color):
    return text.replace(
        keyword,
        f'<span style="color:{color};font-weight:bold;background:#1e1e2e;'
        f'padding:1px 5px;border-radius:3px">{keyword}</span>'
    )

output_area = widgets.Output()

# ── Progress indicator (no sleep — just shows message instantly) ──────
def show_progress(estimated_seconds):
    bar = widgets.IntProgress(
        value=0, min=0, max=100,
        bar_style='info',
        layout=widgets.Layout(width='100%', height='12px'),
    )
    label = widgets.HTML(
        f'<span style="color:#a6adc8;font-size:0.82em">'
        f'🧠 Querying both courses… (~{estimated_seconds:.0f}s)</span>'
    )
    with output_area:
        clear_output(wait=True)
        display(widgets.VBox([label, bar],
                layout=widgets.Layout(padding='10px 0')))

   
    def _animate():
        steps = 30
        for i in range(steps + 1):
            bar.value = int(i / steps * 100)
            time.sleep(estimated_seconds / steps)

    threading.Thread(target=_animate, daemon=True).start()

# ── Run comparison ────────────────────────────────────────────────────
def run_comparison(_=None):
    run_btn.disabled    = True
    run_btn.description = "⏳ Running..."

    sample_msgs = [
        {"role": "system", "content": build_course_prompt("Data 8")},
        {"role": "user",   "content": question},
    ]
    wait = estimated_wait(count_tokens(sample_msgs, model)) * 2 * 2
    show_progress(wait)

    results = {}
    prompts = {}
    for course, cfg in COURSE_COLORS.items():
        prompts[course] = build_course_prompt(course)
        resp = model.create_chat_completion(
            messages=[
                {"role": "system", "content": prompts[course]},
                {"role": "user",   "content": question},
            ],
            max_tokens=150,
            temperature=0.7,
        )
        results[course] = resp["choices"][0]["message"]["content"].strip()

    with output_area:
        clear_output()
        html_parts = ['<div style="display:flex;gap:14px;margin-top:10px">']
        for course, cfg in COURSE_COLORS.items():
            reply_html = highlight(results[course], cfg["keyword"], cfg["kw_color"])
            reply_html = reply_html.replace(
                "Table.read_table",
                f'<span style="color:{cfg["kw_color"]};font-weight:bold">Table.read_table</span>'
            ).replace(
                "pd.read_csv",
                f'<span style="color:{cfg["kw_color"]};font-weight:bold">pd.read_csv</span>'
            )

            html_parts.append(f"""
            <div style="flex:1;background:#1e1e2e;border:2px solid {cfg['border']};
                        border-radius:10px;padding:14px">

              <div style="color:{cfg['label']};font-weight:bold;font-size:1em;margin-bottom:10px">
                🎓 {course}
              </div>

              <!-- System prompt section -->
              <div style="color:#a6adc8;font-size:0.75em;font-weight:bold;
                          text-transform:uppercase;letter-spacing:0.05em;margin-bottom:4px">
                ⚙️ System Prompt
              </div>
              <div style="background:#181825;border:1px solid {cfg['border']}44;
                          border-radius:6px;padding:8px 10px;
                          color:#a6adc8;font-size:0.78em;line-height:1.6;
                          max-height:90px;overflow-y:auto;
                          white-space:pre-wrap;margin-bottom:10px">{prompts[course]}</div>

              <!-- Arrow -->
              <div style="text-align:center;color:#7c7f93;font-size:1.2em;margin-bottom:8px">↓</div>

              <!-- AI response section -->
              <div style="color:#a6adc8;font-size:0.75em;font-weight:bold;
                          text-transform:uppercase;letter-spacing:0.05em;margin-bottom:4px">
                🤖 AI Response
              </div>
              <div style="background:#313244;padding:10px;border-radius:6px;
                          color:#cdd6f4;font-size:0.87em;line-height:1.6;
                          white-space:pre-wrap">{reply_html}</div>

            </div>""")

        html_parts.append('</div>')
        html_parts.append("""
        <div style="margin-top:12px;background:#313244;padding:10px 14px;border-radius:8px;
                    font-size:0.85em;color:#a6adc8">
          ✨ <strong style="color:#fab387">Key observation:</strong>
          Same model, same question — only the system prompt changed.<br>
          The highlighted library name shows exactly where the behaviour diverged.
        </div>""")
        display(HTML("".join(html_parts)))

    run_btn.disabled    = False
    run_btn.description = "▶ Run Again"

run_btn = widgets.Button(
    description="▶ Run Comparison",
    button_style="primary",
    layout=widgets.Layout(width="160px", margin="0 0 10px 0")
)
run_btn.on_click(run_comparison)

display(widgets.HTML("""
<div style="background:#1e1e2e;padding:14px 18px;border-radius:10px;margin-bottom:10px">
  <h4 style="color:#cdd6f4;margin:0 0 6px 0">🎓 Data 8 vs Data 100 — Side-by-Side</h4>
  <p style="color:#a6adc8;margin:0;font-size:0.88em">
    Question: <em>"How do I read a CSV file?"</em><br>
    Notice how the <strong style="color:#fab387">system prompt</strong> changes the library the AI recommends.
  </p>
</div>
"""), run_btn, output_area)

# Part 2 — Token counter: shows how system prompts and history multiply token usage and wait time

# ── Token Counter Demonstration ──────────────────────────────────────
simple_question  = "How do I read a CSV file in Python?"
data100_prompt   = build_course_prompt("Data 100")

msgs_simple = [
    {"role": "user", "content": simple_question}
]
msgs_with_prompt = [
    {"role": "system", "content": data100_prompt},
    {"role": "user",   "content": simple_question},
]
msgs_with_history = [
    {"role": "system", "content": data100_prompt},
    {"role": "user",      "content": "Hi! I'm Zoe, a student from Taiwan studying AI at UC Berkeley."},
    {"role": "assistant", "content": "Welcome Zoe! That's exciting. What are you working on?"},
    {"role": "user",      "content": "I'm learning about context management in LLMs for a class project."},
    {"role": "assistant", "content": "Great topic! Context management is key for building real AI apps."},
    {"role": "user",      "content": "I'm also learning pandas and scikit-learn for the data side."},
    {"role": "assistant", "content": "Nice combo. Are you using Jupyter or a local environment?"},
    {"role": "user",      "content": simple_question},
]

t1 = count_tokens(msgs_simple)
t2 = count_tokens(msgs_with_prompt)
t3 = count_tokens(msgs_with_history)

SPEED = 25  # conservative tokens/sec estimate for llama-cpp on a shared CPU

rows = [
    ("Simple question only",     t1),
    ("+ System prompt",          t2),
    ("+ 6-turn history preview", t3),
]

html = ['<div style="background:#1e1e2e;border-radius:10px;padding:16px 20px;margin-top:8px">']
html.append('<h4 style="color:#cdd6f4;margin:0 0 12px 0">🪙 Token Count & Estimated Wait Time</h4>')
html.append('<table style="width:100%;border-collapse:collapse;font-size:0.88em">')
html.append('''<tr style="background:#2a2a3d;border-bottom:1px solid #45475a">
  <th style="text-align:left;padding:6px 10px;color:#cdd6f4">Scenario</th>
  <th style="text-align:right;padding:6px 10px;color:#cdd6f4">Tokens</th>
  <th style="text-align:right;padding:6px 10px;color:#cdd6f4">% of 4096</th>
  <th style="text-align:right;padding:6px 10px;color:#cdd6f4">Est. wait (@25 tok/s)</th>
</tr>''')

bar_colors = ["#a6e3a1", "#89b4fa", "#f38ba8"]
for (label, t), color in zip(rows, bar_colors):
    pct   = t / 4096 * 100
    wait  = estimated_wait(t, SPEED)
    bar_w = max(4, int(pct * 1.5))
    html.append(f'''<tr style="background:#1e1e2e;border-bottom:1px solid #313244">
  <td style="padding:8px 10px;color:#cdd6f4">{label}</td>
  <td style="text-align:right;padding:8px 10px;color:{color};font-weight:bold">{t}</td>
  <td style="text-align:right;padding:8px 10px">
    <span style="display:inline-block;width:{bar_w}px;height:10px;
                 background:{color};border-radius:3px;vertical-align:middle"></span>
    <span style="color:#cdd6f4;margin-left:6px">{pct:.1f}%</span>
  </td>
  <td style="text-align:right;padding:8px 10px;color:#cdd6f4">~{wait:.1f} s</td>
</tr>''')

html.append('</table>')
html.append(f'''<div style="margin-top:12px;padding:10px 14px;background:#313244;border-radius:8px;
                            font-size:0.85em;line-height:1.8">
  💡 <strong style="color:#fab387">Cost us time:</strong>
  <span style="color:#cdd6f4"> Adding a system prompt multiplies token count by ~{t2/t1:.0f}×.</span><br>
  <span style="color:#cdd6f4">Adding 6 turns of history multiplies it by ~{t3/t1:.0f}× vs. the bare question.</span><br>
  <span style="color:#cdd6f4">With 25 full turns (Zoe\'s story below), expect </span>
  <strong style="color:#f38ba8">1,000 + tokens</strong>
  <span style="color:#cdd6f4"> and ~{1000/SPEED:.0f}+ seconds of wait time on this local 1B model.</span><br>
  👉 <strong style="color:#cdd6f4">This is exactly why history compression (Part 3) matters.</strong>
</div>
</div>''')

display(HTML("".join(html)))

# Part 3 — Dataset: Zoe's 25-turn conversation, used to show how the assistant infers a student profile over time

# ── DATASET: Zoe's Storyline History (25 turns) ──────────────────────
ZOE_HISTORY = [
    {"role": "user",      "content": "Hi! I'm Zoe. I'm from Taiwan and I'm studying at UC Berkeley."},
    {"role": "assistant", "content": "Welcome Zoe! Great to meet you. What are you studying?"},
    {"role": "user",      "content": "I'm focusing on AI and machine learning. It's my first semester here."},
    {"role": "assistant", "content": "That's exciting! Berkeley has a great CS program. What draws you to AI?"},
    {"role": "user",      "content": "I want to understand how language models work — especially memory and context."},
    {"role": "assistant", "content": "Context management is a fascinating area. Are you working on a project?"},
    {"role": "user",      "content": "Yes, I'm building a teaching notebook about LLM context management for a class."},
    {"role": "assistant", "content": "That sounds like a great project. What tools are you using?"},
    {"role": "user",      "content": "Python, Jupyter, and llama-cpp-python with a local Llama model."},
    {"role": "assistant", "content": "Nice setup! Running locally avoids API costs. How's the performance?"},
    {"role": "user",      "content": "It's a bit slow — the 1B model takes a few seconds per response."},
    {"role": "assistant", "content": "That's expected. Reducing token count helps. Have you tried history compression?"},
    {"role": "user",      "content": "Not yet. That's actually one of the topics I want to teach in the notebook."},
    {"role": "assistant", "content": "Perfect timing then. Summarization and entity extraction are two common approaches."},
    {"role": "user",      "content": "I also want to show students the difference between Data 8 and Data 100 workflows."},
    {"role": "assistant", "content": "Good idea. The datascience vs pandas distinction is a classic Berkeley contrast."},
    {"role": "user",      "content": "Exactly! I think system prompts are the key to making that demo work."},
    {"role": "assistant", "content": "Right — change one field in the profile, the whole prompt regenerates."},
    {"role": "user",      "content": "I'm also learning about token budgets. Every token = more wait time locally."},
    {"role": "assistant", "content": "That's a great insight to teach. Students often ignore token costs until they feel it."},
    {"role": "user",      "content": "My background is more stats than CS, so I'm still getting comfortable with Python."},
    {"role": "assistant", "content": "Stats is a great foundation. pandas and numpy will feel natural to you."},
    {"role": "user",      "content": "I also want a fun mode where the AI speaks in a playful, encouraging tone."},
    {"role": "assistant", "content": "Easy — just add that as a style option in the system prompt."},
    {"role": "user",      "content": "Cool, I think that will make the notebook more fun. Thanks for helping me plan this!"},
]

def display_dataset_professional(history):
    """Render the conversation history as a styled HTML table."""
    # Use count_tokens from utils.py — no need to reimplement here
    total_tok = count_tokens(history)

    rows = ""
    for m in history:
        is_user    = m["role"] == "user"
        role_color = "#1a5fb4" if is_user else "#26a269"
        label      = m["role"].upper()
        rows += f"""
        <tr style="border-bottom:1px solid #eee">
          <td style="padding:12px 14px; vertical-align:top; width:110px;
                     font-weight:700; color:{role_color}; font-size:0.88em; text-align:left;">{label}</td>
          <td style="padding:12px 14px; color:#000000; line-height:1.6; font-size:0.9em; text-align:left;">{m['content']}</td>
        </tr>"""

    html = f"""
    <div style="font-family: sans-serif; margin:10px 0">
      <div style="background:#1e2d40; border:1px solid #3b5268; border-radius:10px 10px 0 0;
                  padding:12px 16px; position:relative;">
        <div style="color:#f0f6ff; font-weight:700; font-size:1em; text-align:center;">
          📖 Full Conversation History — Zoe
        </div>
        <div style="position:absolute; right:16px; top:14px; font-size:0.75em; color:#7ea8c9; display:flex; gap:10px;">
          <span>{len(history)} turns</span>
          <span style="color:#3b5268">|</span>
          <span style="color:#38bdf8; font-weight:700">{total_tok} tokens</span>
        </div>
      </div>

      <div style="max-height:300px; overflow-y:auto;
                  border:1px solid #3b5268; border-top:none;
                  border-radius:0 0 10px 10px; background:#ffffff">
        <table style="width:100%; border-collapse:collapse; table-layout:fixed;">
          <thead>
            <tr style="background:#f8f9fa; border-bottom:2px solid #dee2e6; position:sticky; top:0; z-index:10;">
              <th style="padding:10px 14px; width:110px; text-align:center;
                         color:#444444; font-size:0.75em; text-transform:uppercase;
                         letter-spacing:0.1em; font-weight:bold;">Role</th>
              <th style="padding:10px 14px; text-align:center;
                         color:#444444; font-size:0.75em; text-transform:uppercase;
                         letter-spacing:0.1em; font-weight:bold;">Message</th>
            </tr>
          </thead>
          <tbody>{rows}</tbody>
        </table>
      </div>
    </div>"""

    display(HTML(html))

display_dataset_professional(ZOE_HISTORY)

# Demo: full 25-turn history injected into context to generate a personalized learning roadmap for Zoe
import threading

# ── Setup ─────────────────────────────────────────────────────────────
simple_question = "Based on my background and what I'm working on, what should I focus on to get better at AI?"

msgs_full_zoe = [
    {
        "role": "system",
        "content": (
            "You are a specialized AI mentor for Data Science students at UC Berkeley. "
            "The user is Zoe. You MUST tailor your advice to her specific background: "
            "Taiwanese, Statistics background, UC Berkeley student, building an LLM context notebook. "
            "FORMAT REQUIREMENT: Provide 5 specific focus areas. Each point must start with a "
            "BOLD KEYWORD followed by a very brief one-sentence explanation. "
            "Example format: '**Keyword**: Brief explanation.' "
            "Do NOT give generic advice. Keep the bolded parts strictly to the keywords."
        )
    },
    *ZOE_HISTORY,
    {"role": "user", "content": simple_question},
]

# ── Bold fix: replace **text** with proper <b>text</b> ───────────────
def render_bold(text):
    text = re.sub(r'\*\*(.+?)\*\*', r'<strong style="color:#f0f6ff">\1</strong>', text)
    text = text.replace("\n", "<br>")
    return text

# ── Widgets ───────────────────────────────────────────────────────────
progress_out = widgets.Output()
result_out   = widgets.Output()

run_btn = widgets.Button(
    description="▶ Generate Roadmap",
    button_style="success",
    layout=widgets.Layout(width="200px", margin="10px 0")
)

# ── Input panel ───────────────────────────────────────────────────────
display(HTML(f"""
<div style="font-family:'IBM Plex Mono','Fira Code',monospace;
            background:#0d1420;border:1px solid #3b5268;
            border-radius:12px;padding:18px 20px;margin:10px 0;color:#e2e8f0">

  <div style="font-size:0.63em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.15em;margin-bottom:8px">Input Context</div>
  <h3 style="color:#f0f6ff;margin:0 0 14px;font-size:1.0em">🔍 Student Profile</h3>

  <div style="display:flex;flex-direction:column;gap:6px;
              font-size:0.8em;color:#94b8d4;line-height:1.7;margin-bottom:14px">
    <div><span style="color:#7a9bb5">Name / Origin  </span> Zoe (Taiwan)</div>
    <div><span style="color:#7a9bb5">Affiliation    </span> UC Berkeley — Statistics background</div>
    <div><span style="color:#7a9bb5">Current project</span> LLM Context Management Notebook</div>
  </div>

  <div style="background:#0f2336;border:1px solid #38bdf855;border-radius:8px;
              padding:10px 14px;margin-bottom:14px;font-size:0.78em;color:#7dd3fc;
              display:flex;align-items:flex-start;gap:8px">
    <span style="font-size:1.1em;margin-top:1px">💬</span>
    <span>
      The roadmap below is generated from <strong style="color:#38bdf8">Zoe's full 25-turn conversation history</strong>
      injected into the model's context — not a generic profile. Every recommendation is grounded
      in what she actually said across the entire session.
    </span>
  </div>

  <div style="background:#020408;border:1px solid #38bdf844;border-left:3px solid #38bdf8;
              border-radius:0 8px 8px 0;padding:12px 14px;font-size:0.82em;
              color:#cbd5e1;line-height:1.6;font-style:italic">
    "{simple_question}"
  </div>

</div>
"""))

display(run_btn, progress_out, result_out)

# ── Button handler ────────────────────────────────────────────────────
def on_run(_):
    run_btn.disabled    = True
    run_btn.description = "⏳ Running..."

    # Clear previous results
    with progress_out:
        clear_output()
    with result_out:
        clear_output()

    # Show progress bar in background thread
    wait = 50
    bar = widgets.IntProgress(
        value=0, min=0, max=100,
        bar_style='info',
        layout=widgets.Layout(width='100%', height='12px'),
    )
    label = widgets.HTML(
        f'<span style="color:#a6adc8;font-size:0.82em">'
        f'🧠 Generating personalized roadmap from conversation history... (~{wait}s)</span>'
    )
    with progress_out:
        display(widgets.VBox([label, bar], layout=widgets.Layout(padding='10px 0')))

    def _animate():
        steps = 30
        for i in range(steps + 1):
            bar.value = int(i / steps * 100)
            time.sleep(wait / steps)

    threading.Thread(target=_animate, daemon=True).start()

    # Inference
    try:
        resp = model.create_chat_completion(
            messages=msgs_full_zoe,
            max_tokens=250,
            temperature=0.4,
        )
        final_reply = resp["choices"][0]["message"]["content"].strip()
    except Exception as e:
        final_reply = f"Error: {e}"

    with progress_out:
        clear_output()

    with result_out:
        display(HTML(f"""
        <div style="font-family:'IBM Plex Mono','Fira Code',monospace;
                    background:#0d1420;border:2px solid #34d399;
                    border-radius:12px;padding:18px 20px;margin-top:10px;color:#e2e8f0">

          <div style="font-size:0.63em;color:#34d399;text-transform:uppercase;
                      letter-spacing:0.15em;margin-bottom:8px">Output</div>
          <h3 style="color:#f0f6ff;margin:0 0 14px;font-size:1.0em">🎯 Personalized AI Learning Roadmap</h3>

          <div style="background:#0d2b1a;border:1px solid #34d39944;border-radius:6px;
                      padding:8px 12px;margin-bottom:12px;font-size:0.75em;color:#6ee7b7;
                      display:flex;align-items:center;gap:6px">
            <span>📜</span>
            <span>Based on <strong style="color:#34d399">25 turns of conversation history</strong>
            — this roadmap reflects Zoe's actual questions, struggles, and progress during the session.</span>
          </div>

          <div style="background:#020408;border:1px solid #34d39922;border-radius:8px;
                      padding:14px 16px;font-size:0.82em;color:#cbd5e1;line-height:1.9">
            {render_bold(final_reply)}
          </div>

          <div style="margin-top:12px;font-size:0.72em;color:#7a9bb5;font-style:italic">
            Focus areas are prioritized based on Zoe's statistical background and local LLM development context.
          </div>

        </div>
        """))

    run_btn.disabled    = False
    run_btn.description = "▶ Run Again"

run_btn.on_click(on_run)

# Truncation Strategy Comparison: BEFORE/AFTER + what AI actually receives + token bar chart

# ═══════════════════════════════════════════════════════════
#  Truncation Strategy Comparison
#  Three strategies, three completely different AFTER states:
#
#  🪟 Sliding Window      → last N raw messages only (hard cutoff)
#  🔍 Entity Extraction   → ALL history → 1 structured facts block
#  🗜️ Summary Compression → ALL history → 1 natural-language summary
#
#  Visualizes per strategy:
#    1. BEFORE/AFTER bubbles  (❌ deleted · 🗜️ compressed · ✅ kept)
#    2. Exact context the AI receives (rendered verbatim)
#    3. Token bar + summary chart across all three
#
#  PREREQUISITE: model loaded (Step 0) + ZOE_HISTORY from Part 2b
# ═══════════════════════════════════════════════════════════

from IPython.display import display, HTML
import re

DEMO_HISTORY = ZOE_HISTORY

# ── Strategy 1: Sliding Window ───────────────────────────────
# Keeps only the last N messages. Everything before is deleted.
# The AI has NO knowledge of anything said before the cutoff.
def strategy_sliding_window(history, n=4):
    kept    = history[-n:]
    deleted = history[:-n]
    note    = f"Hard cutoff: only the last {n} messages survive. {len(deleted)} messages permanently deleted."
    # deleted msgs → state "dropped" (gone forever, no recovery)
    return kept, [], deleted, note

# ── Strategy 2: Entity Extraction ────────────────────────────
# Scans the ENTIRE history, pulls out structured facts.
# ALL original messages are replaced by 1 system message.
# No "keep last N" — the whole point is to compress everything.
def strategy_entity_extraction(history):
    all_text = " ".join(m["content"] for m in history)

    facts = {"Name": "Zoe"}
    m_origin  = re.search(r'from (\w+)', all_text, re.I)
    m_school  = re.search(r'studying (?:at )?(.+?)[.,]', all_text, re.I)
    m_project = re.search(r'building (?:a )?(.+?)[.,]', all_text, re.I)
    topics    = list(set(re.findall(r'learning (\w+)', all_text, re.I)))

    if m_origin:  facts["Origin"]  = m_origin.group(1)
    if m_school:  facts["School"]  = m_school.group(1)
    if m_project: facts["Project"] = m_project.group(1)
    if topics:    facts["Topics"]  = ", ".join(topics)

    summary_lines = "\n".join(f"  • {k}: {v}" for k, v in facts.items())
    summary = f"[ENTITY MEMORY — extracted from {len(history)} messages]\n{summary_lines}"

    kept       = [{"role": "system", "content": summary}]
    compressed = history   # ALL original messages → compressed into the 1 system msg
    note       = f"Scanned all {len(history)} messages → extracted {len(facts)} facts → replaced with 1 system message. The AI sees only structured facts, no conversation."
    return kept, compressed, [], note

# ── Strategy 3: Summary Compression ──────────────────────────
# Rewrites the ENTIRE history as natural-language prose.
# ALL original messages are replaced by 1 summary message.
# Feels more human than entity extraction — narrative is preserved.
def strategy_summary_compression(history):
    topics = set()
    for m in history:
        c = m["content"].lower()
        if "taiwan"   in c: topics.add("comes from Taiwan")
        if "berkeley" in c: topics.add("is studying at UC Berkeley")
        if "notebook" in c: topics.add("is building a teaching notebook about LLMs")
        if "llama"    in c: topics.add("is using llama-cpp-python for local inference")
        if "token"    in c: topics.add("is learning about token budgets and context windows")
        if "pandas"   in c: topics.add("has a stats background and is learning pandas")
        if "rag"      in c: topics.add("is exploring RAG for memory management")

    prose = (
        f"[SUMMARY — rewrote {len(history)} messages as natural language]\n"
        f"  Zoe is a student who " + ", ".join(topics) + ".\n"
        f"  This summary replaces the full conversation history to save tokens.\n"
        f"  The most recent context is captured here — no raw messages are kept."
    )

    kept       = [{"role": "assistant", "content": prose}]
    compressed = history   # ALL original messages → compressed into the 1 summary
    note       = f"Rewrote all {len(history)} messages as 1 natural-language summary. The AI reads prose, not raw dialogue — closest to how a human would recall a conversation."
    return kept, compressed, [], note

# ── Strategy registry ─────────────────────────────────────────
STRATEGIES = {
    "🪟 Sliding Window": {
        "fn":    strategy_sliding_window,
        "color": "#89b4fa",   # 🔵 technical term
        "explanation": (
            "<strong style='color:#f38ba8'>What the AI loses:</strong> "
            "every message before the cutoff — deleted forever, no summary, no facts.<br>"
            "<strong style='color:#a6e3a1'>What the AI keeps:</strong> "
            "the last 4 raw messages, exactly as written.<br>"
            "<strong style='color:#89b4fa'>The AI's memory:</strong> "
            "a short slice of recent chat — it has no idea who Zoe is."
        ),
    },
    "🔍 Entity Extraction": {
        "fn":    strategy_entity_extraction,
        "color": "#a6e3a1",   # 🟢 solution
        "explanation": (
            "<strong style='color:#f38ba8'>What the AI loses:</strong> "
            "all conversational flow — no back-and-forth, just extracted data.<br>"
            "<strong style='color:#a6e3a1'>What the AI keeps:</strong> "
            "structured facts (name, school, project, topics) in 1 system message.<br>"
            "<strong style='color:#89b4fa'>The AI's memory:</strong> "
            "like reading a student's file instead of their actual conversation."
        ),
    },
    "🗜️ Summary Compression": {
        "fn":    strategy_summary_compression,
        "color": "#fab387",   # 🟠 strategy / emphasis
        "explanation": (
            "<strong style='color:#f38ba8'>What the AI loses:</strong> "
            "exact wording and fine-grained details from older turns.<br>"
            "<strong style='color:#a6e3a1'>What the AI keeps:</strong> "
            "a natural-language retelling of the whole conversation in 1 message.<br>"
            "<strong style='color:#89b4fa'>The AI's memory:</strong> "
            "like a colleague catching you up — narrative intact, details softened."
        ),
    },
}

# ── Token counter ─────────────────────────────────────────────
def count_tokens_list(msgs):
    return sum(len(model.tokenize(m["content"].encode("utf-8"))) for m in msgs)

# ── Role colours ──────────────────────────────────────────────
ROLE_COLORS = {
    "user":      {"border": "#89b4fa", "label": "#89b4fa", "bg": "#89b4fa18"},
    "assistant": {"border": "#a6e3a1", "label": "#a6e3a1", "bg": "#a6e3a118"},
    "system":    {"border": "#f9e2af", "label": "#f9e2af", "bg": "#f9e2af18"},
}

def make_bubble(m, state="kept"):
    """
    state:
      'kept'       ✅  full opacity  — AI still sees this verbatim
      'dropped'    ❌  very faded    — permanently deleted (Sliding Window)
      'compressed' 🗜️  orange-tinted — turned into summary (Entity / Summary)
    """
    cfg = ROLE_COLORS.get(m["role"], {"border": "#7a9bb5", "label": "#7a9bb5", "bg": "#7a9bb518"})
    if state == "dropped":
        opacity, icon, border, bg = "0.18", "❌", cfg["border"] + "33", cfg["bg"]
    elif state == "compressed":
        opacity, icon, border, bg = "0.42", "🗜️", "#fab38799", "#fab38712"
    else:
        opacity, icon, border, bg = "1",    "✅", cfg["border"] + "88", cfg["bg"]

    return f"""
    <div style="margin-bottom:5px;opacity:{opacity}">
      <span style="color:{cfg['label']};font-size:0.68em;font-weight:bold">
        {icon} {m['role'].upper()}
      </span>
      <div style="background:{bg};border:1px solid {border};padding:5px 9px;
                  border-radius:5px;color:#cdd6f4;font-size:0.76em;
                  line-height:1.5;margin-top:2px;word-break:break-word">
        {m['content'][:90]}{"…" if len(m['content']) > 90 else ""}
      </div>
    </div>"""

def make_ai_context_box(kept, color):
    """
    Shows exactly what the AI receives — the full content of every message,
    especially the summary/facts block which is the whole point of compression.
    """
    rows = ""
    for m in kept:
        cfg = ROLE_COLORS.get(m["role"], {"border": "#7a9bb5", "label": "#7a9bb5", "bg": "#7a9bb518"})
        # Show full content — this IS what the AI reads
        rows += f"""
        <div style="margin-bottom:7px">
          <span style="color:{cfg['label']};font-size:0.68em;font-weight:bold">
            {m['role'].upper()}
          </span>
          <div style="background:{cfg['bg']};border:1px solid {cfg['border']}88;
                      padding:8px 11px;border-radius:5px;color:#cdd6f4;
                      font-size:0.76em;line-height:1.7;margin-top:2px;
                      white-space:pre-wrap;word-break:break-word">{m['content']}</div>
        </div>"""
    return f"""
    <div style="background:#0d0d1a;border:1px solid {color}55;border-radius:8px;
                padding:10px;max-height:340px;overflow-y:auto">
      {rows}
    </div>"""

def make_token_bar(result_tokens, original_tokens, color):
    pct     = result_tokens / original_tokens * 100
    savings = original_tokens - result_tokens
    return f"""
    <div style="margin-top:12px">
      <div style="display:flex;justify-content:space-between;
                  font-size:0.75em;color:#a6adc8;margin-bottom:4px">
        <span>Token usage after compression</span>
        <span>
          <strong style="color:{color}">{result_tokens}</strong>
          <span style="color:#585b70"> / {original_tokens} tokens · </span>
          <span style="color:#a6e3a1">saved {savings} ({100-pct:.0f}% reduction)</span>
        </span>
      </div>
      <div style="background:#313244;border-radius:4px;height:10px;overflow:hidden">
        <div style="width:{pct:.1f}%;background:{color};height:100%;border-radius:4px"></div>
      </div>
      <div style="display:flex;justify-content:space-between;
                  font-size:0.68em;color:#585b70;margin-top:3px">
        <span>0</span><span>{original_tokens} tokens (original)</span>
      </div>
    </div>"""

def render_strategy_panel(label, cfg, original, kept, compressed, deleted, note, original_tokens, result_tokens):
    compressed_set = set(m["content"] for m in compressed)
    deleted_set    = set(m["content"] for m in deleted)

    left_html = ""
    for m in original:
        if m["content"] in deleted_set:
            left_html += make_bubble(m, state="dropped")
        elif m["content"] in compressed_set:
            left_html += make_bubble(m, state="compressed")
        else:
            left_html += make_bubble(m, state="kept")

    color = cfg["color"]

    return f"""
    <div style="background:#1e1e2e;border:2px solid {color}55;border-radius:12px;
                padding:18px;margin-bottom:22px">

      <div style="color:{color};font-weight:bold;font-size:1.05em;margin-bottom:3px">{label}</div>
      <div style="color:#a6adc8;font-size:0.79em;margin-bottom:12px">{note}</div>

      <div style="background:{color}10;border-left:3px solid {color};border-radius:6px;
                  padding:10px 14px;margin-bottom:14px;color:#cdd6f4;
                  font-size:0.83em;line-height:1.9">
        {cfg['explanation']}
      </div>

      <div style="display:grid;grid-template-columns:1fr 1fr;gap:14px">

        <div>
          <div style="color:#585b70;font-size:0.70em;font-weight:bold;
                      text-transform:uppercase;letter-spacing:0.05em;margin-bottom:6px">
            BEFORE — {len(original)} messages
            <span style="font-weight:normal;margin-left:6px">
              ❌ deleted &nbsp;🗜️ compressed &nbsp;✅ kept
            </span>
          </div>
          <div style="background:#0d0d1a;border-radius:8px;padding:10px;
                      max-height:340px;overflow-y:auto">
            {left_html}
          </div>
        </div>

        <div>
          <div style="color:#585b70;font-size:0.70em;font-weight:bold;
                      text-transform:uppercase;letter-spacing:0.05em;margin-bottom:6px">
            WHAT THE AI ACTUALLY RECEIVES
            <span style="font-weight:normal;margin-left:6px">— its entire memory</span>
          </div>
          {make_ai_context_box(kept, color)}
        </div>

      </div>

      {make_token_bar(result_tokens, original_tokens, color)}
    </div>"""

def make_summary_chart(chart_data, original_tokens):
    rows = ""
    for label, d in chart_data.items():
        pct   = d["kept"] / original_tokens * 100
        color = d["color"]
        rows += f"""
        <div style="margin-bottom:12px">
          <div style="display:flex;justify-content:space-between;
                      font-size:0.80em;color:#cdd6f4;margin-bottom:4px">
            <span>{label}</span>
            <span>
              <strong style="color:{color}">{d['kept']} tokens</strong>
              <span style="color:#a6e3a1"> · saved {original_tokens - d['kept']} ({100-pct:.0f}%)</span>
            </span>
          </div>
          <div style="background:#313244;border-radius:4px;height:14px;overflow:hidden">
            <div style="width:{pct:.1f}%;background:{color};height:100%;border-radius:4px"></div>
          </div>
        </div>"""

    return f"""
    <div style="background:#1e1e2e;border:1px solid #45475a;border-radius:10px;
                padding:18px;margin-top:6px">
      <div style="color:#cdd6f4;font-weight:bold;font-size:0.95em;margin-bottom:4px">
        📊 Token Usage Comparison — All Three Strategies
      </div>
      <div style="color:#a6adc8;font-size:0.78em;margin-bottom:14px">
        Original history: <strong style="color:#f9e2af">{original_tokens} tokens</strong>
        &nbsp;·&nbsp; bars show what's left after each strategy
      </div>
      {rows}
      <div style="margin-top:14px;padding-top:12px;border-top:1px solid #313244;
                  font-size:0.82em;color:#a6adc8;line-height:1.8">
        <strong style="color:#cdd6f4">🧠 Key takeaway for Zoe's students:</strong><br>
        <span style="color:#89b4fa">■ Sliding Window</span>
          — fastest · lowest token cost · AI has no idea who Zoe is.<br>
        <span style="color:#a6e3a1">■ Entity Extraction</span>
          — AI knows the facts · but has never "heard" Zoe's voice.<br>
        <span style="color:#fab387">■ Summary Compression</span>
          — AI understands the narrative · costs one extra model call.<br>
        <strong>In production, tutoring assistants often combine all three.</strong>
      </div>
    </div>"""

# ── Main render ───────────────────────────────────────────────
original_tokens = count_tokens_list(DEMO_HISTORY)

header_html = f"""
<div style="background:#313244;border-left:4px solid #f9e2af;padding:12px 16px;
            border-radius:6px;margin-bottom:18px;font-size:0.88em">
  <strong style="color:#f9e2af">Zoe's full conversation history:</strong>
  <span style="color:#cdd6f4"> {len(DEMO_HISTORY)} messages · {original_tokens} tokens</span>
  <span style="color:#585b70"> · {original_tokens/4096*100:.1f}% of the 4096-token context window</span><br>
  <span style="color:#a6adc8;font-size:0.9em">
    Each strategy below shows a <em>completely different</em> picture of what the AI will receive. 👇
  </span>
</div>"""

panels_html = ""
chart_data  = {}

for label, cfg in STRATEGIES.items():
    kept, compressed, deleted, note = cfg["fn"](DEMO_HISTORY)
    t = count_tokens_list(kept)
    panels_html += render_strategy_panel(
        label, cfg, DEMO_HISTORY, kept, compressed, deleted, note, original_tokens, t
    )
    chart_data[label] = {"kept": t, "color": cfg["color"]}

display(HTML(header_html + panels_html + make_summary_chart(chart_data, original_tokens)))

# Conclusion: which compression strategy works best depending on model size


conclusion_html = """
<div style="font-family:'IBM Plex Mono','Fira Code',monospace;
            background:#0d1420;border:1px solid #1e293b;
            border-radius:12px;padding:20px 24px;margin-top:10px;color:#e2e8f0">

  <div style="font-size:0.63em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.15em;margin-bottom:8px">Conclusion</div>
  <h3 style="color:#f0f6ff;margin:0 0 16px;font-size:1.05em">
    Choosing a compression strategy depends on your model size
  </h3>

  <div style="display:flex;flex-direction:column;gap:10px;margin-bottom:20px">

    <div style="display:flex;gap:12px;align-items:flex-start;background:#0f1e10;
                border:1px solid #34d39933;border-radius:8px;padding:12px 14px">
      <span style="font-size:1.1em;margin-top:1px">✅</span>
      <div>
        <div style="color:#34d399;font-weight:700;font-size:0.85em;margin-bottom:3px">
          Summarization — works well on small models
        </div>
        <div style="color:#94a3b8;font-size:0.78em;line-height:1.6">
          Asks the model to do what it does best: generate free-form text.
          No strict format requirements means no format failures.
          The output may vary slightly each run, but it will always be usable.
        </div>
      </div>
    </div>

    <div style="display:flex;gap:12px;align-items:flex-start;background:#1f0e0e;
                border:1px solid #f8717133;border-radius:8px;padding:12px 14px">
      <span style="font-size:1.1em;margin-top:1px">❌</span>
      <div>
        <div style="color:#f87171;font-weight:700;font-size:0.85em;margin-bottom:3px">
          Entity Extraction — unreliable on small models
        </div>
        <div style="color:#94a3b8;font-size:0.78em;line-height:1.6">
          Requires strict schema compliance. The 1B model ignored the required fields,
          invented its own structure, and produced invalid JSON — even after adding
          explicit constraints. For structured output, use a larger model (7B+)
          or a model that supports JSON mode / function calling.
        </div>
      </div>
    </div>

    <div style="display:flex;gap:12px;align-items:flex-start;background:#150f1f;
                border:1px solid #a78bfa33;border-radius:8px;padding:12px 14px">
      <span style="font-size:1.1em;margin-top:1px">⚠️</span>
      <div>
        <div style="color:#a78bfa;font-weight:700;font-size:0.85em;margin-bottom:3px">
          Semantic Compression — limited benefit on small models
        </div>
        <div style="color:#94a3b8;font-size:0.78em;line-height:1.6">
          The intent is to preserve causal reasoning, not just surface content.
          In practice, the 1B model produced output nearly identical to Summarization.
          The distinction becomes meaningful at larger model sizes.
        </div>
      </div>
    </div>

  </div>

  <div style="background:#020408;border:1px solid #334155;border-radius:8px;
              padding:12px 16px;font-size:0.8em;color:#94a3b8;line-height:1.8">
    <span style="color:#f0f6ff;font-weight:700">Key takeaway: </span>
    Compression strategy choice is not just about what information you want to preserve —
    it also depends on what your model can reliably produce.
    When working with small local models, prefer strategies with
    <span style="color:#34d399">low output constraints</span> and
    <span style="color:#34d399">flexible formats</span>.
  </div>

</div>
"""

display(HTML(conclusion_html))

# Memory Conflict Detection Demo
# ═══════════════════════════════════════════════════════════
#
#  TRANSPARENCY NOTE — what is hard-coded vs real in this demo:
#
#  HARD-CODED (fixed, won't change each run):
#    - conflict_message       : the sentence Zoe says to trigger the conflict
#    - assistant.recent_history : pre-loaded conversation history (skips wait time)
#    - expert_question        : the follow-up question in Step 3
#    - expert_reply           : the expert-mode answer (written by us, not the model)
#
#  REAL MODEL OUTPUT (runs inference, may vary each run):
#    - assistant.chat(conflict_message) : Step 2 — model detects conflict + replies
#    - detect_profile_changes(...)      : called inside .chat(), model outputs JSON
#
#  Why hard-code some parts?
#  The 1B local model is slow (~25 tok/s). Pre-loading history and the expert reply
#  keeps the demo fast and predictable for teaching. The conflict detection in Step 2
#  is the real inference we want to showcase.
# ═══════════════════════════════════════════════════════════


# ── STEP 1: Initialize session ────────────────────────────────────────
# ⚠️ HARD-CODED: user profile, project profile, and pre-loaded history
# These are fixed so every student sees the same starting state.

assistant = ChatAssistant(
    user_profile={
        "name":             "Zoe",
        "language":         "English",
        "expertise":        "Python beginner",   # ← this is what will be contradicted
        "style_preferences": ["Simple and clear", "Include code examples"]
    },
    project_profile={
        "name":         "LLM Teaching Notebook",
        "description":  "Building a teaching notebook about LLM context management",
        "tools":        ["Python", "Jupyter", "llama-cpp-python"],
        "current_goal": "Teach context management concepts to students"
    },
    model=model,
    max_turns=4,
    chunk_size=2
)

# ⚠️ HARD-CODED: pre-loaded history — no model call, instant
# In a real session these would have been generated by the model.
assistant.recent_history = [
    {"role": "user",      "content": "How do I load a CSV file in Python?"},
    {"role": "assistant", "content": "Use pd.read_csv('filename.csv'). It returns a DataFrame."},
    {"role": "user",      "content": "What about checking for missing values?"},
    {"role": "assistant", "content": "Use df.isnull().sum() to count missing values per column."},
]
assistant.total_turns = 2

# ── Render Step 1 ─────────────────────────────────────────────────────
history_divs = "".join(f"""
<div style="display:flex;gap:12px;padding:8px 12px;border-bottom:1px solid #1e293b;
            background:{'#0d1420' if i%2==0 else '#0a1220'}">
  <span style="font-size:0.72em;font-weight:700;width:90px;flex-shrink:0;
               color:{'#38bdf8' if m['role']=='user' else '#34d399'}">{m['role'].upper()}</span>
  <span style="color:#cbd5e1;font-size:0.78em;line-height:1.6">{m['content']}</span>
</div>""" for i, m in enumerate(assistant.recent_history))

display(HTML(f"""
<div style="font-family:'IBM Plex Mono','Fira Code',monospace;
            background:#080c12;border-radius:12px;padding:18px 20px;color:#e2e8f0">

  <div style="font-size:0.63em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.15em;margin-bottom:4px">Part 6 — Step 1 of 3</div>
  <h3 style="color:#f0f6ff;margin:0 0 14px;font-size:1.0em">⚙️ Session Initialized</h3>

  <!-- hard-code banner -->
  <div style="background:#f9e2af18;border:1px solid #f9e2af44;border-left:3px solid #f9e2af;
              border-radius:0 8px 8px 0;padding:8px 14px;margin-bottom:14px;font-size:0.78em">
    <span style="color:#f9e2af;font-weight:700">⚠️ Hard-coded</span>
    <span style="color:#94b8d4"> — profile and history are fixed for this demo.
    No model call was made here.</span>
  </div>

  <div style="display:grid;grid-template-columns:1fr 1fr;gap:12px;margin-bottom:16px">
    <div style="background:#0d1420;border:1px solid #1e293b;border-radius:8px;padding:12px 14px">
      <div style="font-size:0.65em;color:#7ea8c9;text-transform:uppercase;
                  letter-spacing:0.1em;margin-bottom:8px">User Profile</div>
      <div style="font-size:0.78em;color:#94b8d4;line-height:1.8">
        <div><span style="color:#64748b">name      </span> Zoe</div>
        <div><span style="color:#64748b">expertise </span>
          <span style="color:#f87171">Python beginner</span>
          <span style="color:#64748b;font-size:0.85em"> ← will be contradicted in Step 2</span>
        </div>
        <div><span style="color:#64748b">style     </span> Simple, with code examples</div>
      </div>
    </div>
    <div style="background:#0d1420;border:1px solid #1e293b;border-radius:8px;padding:12px 14px">
      <div style="font-size:0.65em;color:#7ea8c9;text-transform:uppercase;
                  letter-spacing:0.1em;margin-bottom:8px">Project Profile</div>
      <div style="font-size:0.78em;color:#94b8d4;line-height:1.8">
        <div><span style="color:#64748b">name  </span> LLM Teaching Notebook</div>
        <div><span style="color:#64748b">tools </span> Python, Jupyter, llama-cpp-python</div>
      </div>
    </div>
  </div>

  <div style="background:#0d1420;border:1px solid #1e293b;border-radius:8px;overflow:hidden">
    <div style="padding:10px 14px;background:#0a1628;font-size:0.65em;color:#7ea8c9;
                text-transform:uppercase;letter-spacing:0.1em">
      💬 Pre-loaded history (2 turns)
      <span style="color:#f9e2af;font-weight:700"> — hard-coded, no model call</span>
    </div>
    {history_divs}
  </div>

  <div style="margin-top:12px;font-size:0.75em;color:#64748b;text-align:center">
    ⬇️ Run the next cell to trigger the conflict
  </div>
</div>
"""))


# ── STEP 2: Trigger conflict + detect ────────────────────────────────
# ⚠️ HARD-CODED: the message Zoe sends — fixed so the demo is predictable.
# ✅ REAL MODEL OUTPUT: assistant.chat() calls the model twice:
#     Call 1 — generate a reply to conflict_message
#     Call 2 — detect_profile_changes() asks the model to output JSON

conflict_message = "Actually, I've been working with Python professionally for 5 years."
# This sentence is chosen to reliably trigger the keyword fallback in detect_profile_changes()
# even if the model fails to return valid JSON ("years of experience" is in the keyword list).

display(HTML(f"""
<div style="font-family:'IBM Plex Mono','Fira Code',monospace;
            background:#080c12;border-radius:12px;padding:18px 20px;
            color:#e2e8f0;margin-top:10px">

  <div style="font-size:0.63em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.15em;margin-bottom:4px">Part 6 — Step 2 of 3</div>
  <h3 style="color:#f0f6ff;margin:0 0 10px;font-size:1.0em">⚠️ Conflict Triggered</h3>

  <!-- labels -->
  <div style="display:flex;gap:8px;margin-bottom:12px;flex-wrap:wrap">
    <span style="background:#f9e2af18;border:1px solid #f9e2af44;color:#f9e2af;
                 font-size:0.72em;padding:3px 10px;border-radius:20px">
      ⚠️ Hard-coded: conflict_message
    </span>
    <span style="background:#34d39918;border:1px solid #34d39944;color:#34d399;
                 font-size:0.72em;padding:3px 10px;border-radius:20px">
      ✅ Real model output: reply + conflict detection JSON
    </span>
  </div>

  <div style="background:#020408;border:1px solid #f8717144;border-left:3px solid #f87171;
              border-radius:0 8px 8px 0;padding:10px 14px;font-size:0.8em;color:#fca5a5;
              margin-bottom:4px">
    Zoe says: <em>"{conflict_message}"</em><br>
    <span style="color:#64748b;font-size:0.9em">
      Current profile says: <strong style="color:#f87171">Python beginner</strong>
    </span>
  </div>
  <div style="font-size:0.72em;color:#64748b;margin-bottom:12px;padding-left:4px">
    The model will now be called to: (1) reply to Zoe, (2) check if the profile needs updating.
  </div>
</div>
"""))

# ✅ REAL MODEL OUTPUT — two inference calls happen inside .chat()
reply = assistant.chat(conflict_message)

if assistant.conflicts_detected:
    last       = assistant.conflicts_detected[-1]
    resolution = last['resolution']
    change_lines = []
    if isinstance(resolution, dict):
        for section, fields in resolution.items():
            if isinstance(fields, dict):
                for k, v in fields.items():
                    change_lines.append(
                        f"<div>{k} &nbsp;→&nbsp; <span style='color:#34d399'>{v}</span></div>"
                    )
    resolution_html = "".join(change_lines) if change_lines else str(resolution)

    display(HTML(f"""
    <div style="font-family:'IBM Plex Mono','Fira Code',monospace;
                background:#0d1420;border:2px solid #34d399;
                border-radius:10px;padding:16px;margin-top:10px;color:#e2e8f0">
      <div style="color:#34d399;font-weight:700;font-size:0.85em;margin-bottom:10px">
        ✅ Memory Conflict Resolved
        <span style="color:#64748b;font-weight:normal;font-size:0.85em;margin-left:8px">
          — real model output
        </span>
      </div>
      <div style="font-size:0.78em;line-height:1.9;color:#94b8d4">
        <div><span style="color:#64748b">Detected at turn  </span> {last['turn']}</div>
        <div><span style="color:#64748b">Profile updated   </span></div>
        <div style="padding-left:16px;color:#e2e8f0">{resolution_html}</div>
        <div style="margin-top:6px">
          <span style="color:#64748b">AI now sees Zoe as  </span>
          <strong style="color:#34d399">{assistant.user_profile.get('expertise', 'N/A')}</strong>
        </div>
      </div>
    </div>
    """))
else:
    display(HTML("""
    <div style="font-family:'IBM Plex Mono','Fira Code',monospace;
                background:#0d1420;border:1px solid #f87171;border-radius:8px;
                padding:12px 16px;margin-top:10px;font-size:0.8em">
      <span style="color:#f87171">⚠️ No conflict detected this run.</span>
      <span style="color:#64748b"> The 1B model may have failed to return valid JSON.
      The keyword fallback also did not trigger — try running again.</span>
    </div>
    """))


# ── STEP 3: Expert mode response + token recap ───────────────────────
# ⚠️ HARD-CODED: expert_question and expert_reply
# Why hard-code the reply?
#   Running a third inference call would add ~30s wait for a teaching demo.
#   The reply below is written to show what an expert-mode response looks like —
#   concise, technical, no hand-holding. Compare it to a beginner response mentally:
#   a beginner answer would start with "pandas is a data analysis library that..."

expert_question = "Should I use polars instead of pandas for performance optimization?"

# ⚠️ HARD-CODED — written by us, not generated by the model this run
expert_reply = (
    "For datasets under ~500MB, pandas is fine. "
    "Polars is worth it when you need lazy evaluation, true parallelism, "
    "or are hitting pandas memory limits. "
    "Key difference: Polars uses Apache Arrow under the hood — "
    "faster groupby and joins, but less ecosystem support."
)

assistant.recent_history.append({"role": "user",      "content": expert_question})
assistant.recent_history.append({"role": "assistant", "content": expert_reply})
assistant.total_turns += 1

final_msgs = [{"role": "system", "content": assistant._build_system_message()}]
final_msgs += assistant.recent_history
t_final    = sum(len(model.tokenize(m["content"].encode("utf-8"))) for m in final_msgs)
SPEED      = 25

display(HTML(f"""
<div style="font-family:'IBM Plex Mono','Fira Code',monospace;
            background:#080c12;border-radius:12px;padding:18px 20px;
            color:#e2e8f0;margin-top:10px">

  <div style="font-size:0.63em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.15em;margin-bottom:4px">Part 6 — Step 3 of 3</div>
  <h3 style="color:#f0f6ff;margin:0 0 14px;font-size:1.0em">🎯 Behaviour Shift — Expert Mode</h3>

  <!-- labels -->
  <div style="display:flex;gap:8px;margin-bottom:12px;flex-wrap:wrap">
    <span style="background:#f9e2af18;border:1px solid #f9e2af44;color:#f9e2af;
                 font-size:0.72em;padding:3px 10px;border-radius:20px">
      ⚠️ Hard-coded: expert_question + expert_reply
    </span>
    <span style="background:#a78bfa18;border:1px solid #a78bfa44;color:#a78bfa;
                 font-size:0.72em;padding:3px 10px;border-radius:20px">
      ✅ Real: system prompt was updated by Step 2's conflict detection
    </span>
  </div>

  <!-- profile change notice -->
  <div style="background:#a78bfa18;border:1px solid #a78bfa44;border-left:3px solid #a78bfa;
              border-radius:0 8px 8px 0;padding:10px 14px;margin-bottom:14px;font-size:0.82em">
    <span style="color:#a78bfa;font-weight:700">✨ System prompt has changed.</span>
    <span style="color:#94b8d4"> The AI now treats Zoe as an </span>
    <span style="color:#34d399;font-weight:700">EXPERT</span>
    <span style="color:#94b8d4"> — this part IS real, updated by Step 2.</span>
  </div>

  <!-- expert exchange -->
  <div style="background:#0d1420;border:1px solid #a78bfa33;border-radius:8px;
              padding:14px;margin-bottom:14px">
    <div style="font-size:0.65em;color:#a78bfa;text-transform:uppercase;
                letter-spacing:0.1em;margin-bottom:10px">
      Simulated expert-mode exchange
      <span style="color:#f9e2af;font-weight:700"> — reply is hard-coded</span>
    </div>
    <div style="font-size:0.78em;color:#38bdf8;margin-bottom:4px">👤 Zoe</div>
    <div style="background:#020408;border-radius:6px;padding:8px 12px;
                color:#cbd5e1;font-size:0.78em;margin-bottom:10px;
                border:1px solid #38bdf822">{expert_question}</div>
    <div style="font-size:0.78em;color:#34d399;margin-bottom:4px">
      🤖 AI (expert mode)
      <span style="color:#f9e2af;font-size:0.85em"> — hard-coded example</span>
    </div>
    <div style="background:#020408;border-radius:6px;padding:8px 12px;
                color:#cbd5e1;font-size:0.78em;border:1px solid #34d39922">{expert_reply}</div>
    <div style="margin-top:10px;padding-top:10px;border-top:1px solid #1e293b;
                font-size:0.72em;color:#7ea8c9;font-style:italic">
      💡 Compare: a <strong>beginner</strong> response would start with
      "pandas is a data analysis library that helps you work with tabular data..."<br>
      This response skips all that — no definition, no hand-holding, straight to the trade-off.
      That shift happened because Step 2 updated the system prompt.
    </div>
  </div>

  <!-- token recap -->
  <div style="background:#0d1420;border:1px solid #fbbf2444;border-radius:8px;padding:14px">
    <div style="font-size:0.65em;color:#fbbf24;text-transform:uppercase;
                letter-spacing:0.1em;margin-bottom:10px">🪙 Token Cost Recap</div>
    <div style="font-size:0.78em;color:#94b8d4;line-height:1.9">
      <div>
        <span style="color:#64748b">Context tokens  </span>
        <strong style="color:#f87171">{t_final}</strong>
        <span style="color:#7ea8c9"> / 4096 ({t_final/4096*100:.1f}% full)</span>
      </div>
      <div>
        <span style="color:#64748b">Est. wait time  </span>
        <span style="color:#fbbf24">~{t_final/SPEED:.1f}s</span>
        <span style="color:#7ea8c9"> at 25 tok/s</span>
      </div>
      <div>
        <span style="color:#64748b">Profile update cost  </span>
        <span style="color:#94b8d4">~1 extra model call to detect the conflict</span>
        <span style="color:#64748b"> — a fixed overhead per turn, not per token</span>
      </div>
    </div>
    <div style="margin-top:10px;padding-top:10px;border-top:1px solid #1e293b;
                font-size:0.75em;color:#64748b;line-height:1.6">
      This is why Part 4 (History Compression) matters —
      on a local 1B model, every saved token = less wait time for students.
    </div>
  </div>

</div>
"""))

# ✅ REAL: show_state() reads from the live assistant object updated by Step 2
assistant.show_state()

# Production Architecture: how every notebook concept maps to a real backend system

part7_html = """
<div style="font-family:'IBM Plex Mono','Fira Code',monospace;
            background:#080c12;border-radius:12px;padding:20px;color:#e2e8f0;margin-bottom:12px">

  <div style="font-size:0.63em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.15em;margin-bottom:4px">Part 7</div>
  <h3 style="color:#f0f6ff;margin:0 0 6px;font-size:1.1em">
    🗺️ How Would This Actually Work in Production?
  </h3>
  <p style="color:#94b8d4;font-size:0.82em;margin:0 0 8px;line-height:1.7">
    The assistant works. Prof. Eric is ready to deploy it to all 300 students.
    But Zoe realises: everything in this notebook runs in a single Python process,
    in memory, for one user at a time.
  </p>
  <div style="background:#020408;border:1px solid #38bdf844;border-left:3px solid #38bdf8;
              border-radius:0 8px 8px 0;padding:10px 14px;font-size:0.82em;
              color:#94b8d4;font-style:italic;margin-bottom:20px;line-height:1.7">
    "What does this look like as a real system — one that can handle hundreds of students
    simultaneously, persist their profiles across sessions, and stay fast?"
  </div>

  <!-- ASCII diagram -->
  <div style="font-size:0.65em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.1em;margin-bottom:8px">📐 System Architecture</div>
  <pre style="background:#020408;border:1px solid #1e293b;border-radius:8px;
              padding:16px;color:#34d399;font-size:0.78em;line-height:1.9;
              overflow-x:auto">
  🧑‍💻 Student's Browser
         |
         v
  +--------------------+
  |   Classroom Door   |  ← Checks who you are and if you're allowed in (Auth)
  +--------+-----------+
           |
           v
  +--------------------+
  |  Safety Filter     |  ← Blocks prompt injection & PII (Llama Guard)
  +--------+-----------+
           |
           v
  +--------------------+
  |   TA / API Server  |  ← Receives the question, decides how to respond
  +--+-----------+-----+
     |           |
     v           v
  📒 Sticky note   📚 Notebook
     (Redis)       (PostgreSQL)
  Last 10 turns    Full learning history
  Fast, temporary  Slower, permanent
     |           |
     v           v
  +--------------------+
  |     AI Model       |  ← Receives full context, generates a reply
  +--------------------+
         |
         v
  📬 Answer streams back to the student
     (one token at a time)
  </pre>

  <!-- Component table -->
  <div style="font-size:0.65em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.1em;margin:18px 0 8px">📋 Notebook vs Real System</div>
  <div style="background:#0d1420;border:1px solid #1e293b;border-radius:8px;overflow:hidden">

    <div style="display:grid;grid-template-columns:1fr 1fr 1fr;
                background:#0a1628;border-bottom:2px solid #1e293b;padding:10px 14px">
      <span style="color:#7ea8c9;font-size:0.72em;text-transform:uppercase;letter-spacing:0.08em">In this notebook</span>
      <span style="color:#7ea8c9;font-size:0.72em;text-transform:uppercase;letter-spacing:0.08em">In a real system</span>
      <span style="color:#7ea8c9;font-size:0.72em;text-transform:uppercase;letter-spacing:0.08em">School analogy</span>
    </div>

    <div style="display:grid;grid-template-columns:1fr 1fr 1fr;
                padding:10px 14px;border-bottom:1px solid #1e293b;background:#0d1420">
      <span style="color:#38bdf8;font-family:monospace;font-size:0.85em">recent_history = []</span>
      <span style="color:#34d399;font-size:0.8em">Short-term cache (Redis)</span>
      <span style="color:#94b8d4;font-size:0.8em">Scratch paper during class — thrown away after</span>
    </div>

    <div style="display:grid;grid-template-columns:1fr 1fr 1fr;
                padding:10px 14px;border-bottom:1px solid #1e293b;background:#111827">
      <span style="color:#38bdf8;font-family:monospace;font-size:0.85em">summary = compress(...)</span>
      <span style="color:#34d399;font-size:0.8em">Long-term memory DB (PostgreSQL)</span>
      <span style="color:#94b8d4;font-size:0.8em">Your study notes before finals — kept forever</span>
    </div>

    <div style="display:grid;grid-template-columns:1fr 1fr 1fr;
                padding:10px 14px;border-bottom:1px solid #1e293b;background:#0d1420">
      <span style="color:#38bdf8;font-family:monospace;font-size:0.85em">retrieve() in RAG</span>
      <span style="color:#34d399;font-size:0.8em">Knowledge search (Vector DB)</span>
      <span style="color:#94b8d4;font-size:0.8em">Going to the library to look something up</span>
    </div>

    <div style="display:grid;grid-template-columns:1fr 1fr 1fr;
                padding:10px 14px;border-bottom:1px solid #1e293b;background:#111827">
      <span style="color:#38bdf8;font-family:monospace;font-size:0.85em">model.create_chat_completion()</span>
      <span style="color:#34d399;font-size:0.8em">AI model server (vLLM)</span>
      <span style="color:#94b8d4;font-size:0.8em">The professor who actually answers the question</span>
    </div>

    <div style="display:grid;grid-template-columns:1fr 1fr 1fr;
                padding:10px 14px;border-bottom:1px solid #1e293b;background:#0d1420">
      <span style="color:#38bdf8;font-family:monospace;font-size:0.85em">user_profile = {}</span>
      <span style="color:#34d399;font-size:0.8em">Student profile database</span>
      <span style="color:#94b8d4;font-size:0.8em">The school's student records system</span>
    </div>

    <div style="display:grid;grid-template-columns:1fr 1fr 1fr;
                padding:10px 14px;background:#111827">
      <span style="color:#38bdf8;font-family:monospace;font-size:0.85em">INJECTION_PATTERNS guard</span>
      <span style="color:#34d399;font-size:0.8em">Safety filter (Llama Guard)</span>
      <span style="color:#94b8d4;font-size:0.8em">The security guard at the school entrance</span>
    </div>

  </div>

  <!-- Key insight -->
  <div style="margin-top:14px;background:#0d1420;border:1px solid #fbbf2444;
              border-left:3px solid #fbbf24;border-radius:0 8px 8px 0;
              padding:12px 16px;font-size:0.82em;line-height:1.8">
    <strong style="color:#fbbf24">💡 Zoe's Takeaway:</strong><br>
    <span style="color:#cbd5e1">
      Every <code style="color:#38bdf8;background:#020408;padding:1px 5px;border-radius:3px">dict</code>
      and <code style="color:#38bdf8;background:#020408;padding:1px 5px;border-radius:3px">list</code>
      in this notebook becomes its own service in a real system.<br>
      <strong style="color:#f0f6ff">The concepts are identical</strong> —
      you just swap the simple tools for more powerful ones
      that can handle 300 students at once.
    </span>
  </div>

</div>
"""

flow_html = """
<div style="font-family:'IBM Plex Mono','Fira Code',monospace;
            background:#080c12;border-radius:12px;padding:20px;
            color:#e2e8f0;margin-top:10px">

  <div style="font-size:0.65em;color:#7ea8c9;text-transform:uppercase;
              letter-spacing:0.1em;margin-bottom:12px">⚡ Request Lifecycle — One Student Message</div>

  <!-- step 1 -->
  <div style="display:flex;align-items:stretch;gap:12px;margin-bottom:4px">
    <div style="display:flex;flex-direction:column;align-items:center;width:32px;flex-shrink:0">
      <div style="width:28px;height:28px;border-radius:50%;background:#f8717122;border:1px solid #f87171;
                  display:flex;align-items:center;justify-content:center;
                  font-size:0.7em;font-weight:700;color:#f87171">1</div>
      <div style="width:1px;background:#1e293b;flex:1;margin-top:4px"></div>
    </div>
    <div style="background:#0d1420;border:1px solid #f8717133;border-radius:8px;
                padding:10px 14px;flex:1;margin-bottom:4px">
      <div style="color:#f87171;font-size:0.78em;font-weight:700">🛡️ Safety Filter</div>
      <div style="color:#64748b;font-size:0.72em;margin-top:2px">blocks prompt injection & PII (Llama Guard)</div>
      <div style="color:#475569;font-size:0.68em;margin-top:4px">← covered in Part 2</div>
    </div>
  </div>

  <!-- step 2 -->
  <div style="display:flex;align-items:stretch;gap:12px;margin-bottom:4px">
    <div style="display:flex;flex-direction:column;align-items:center;width:32px;flex-shrink:0">
      <div style="width:28px;height:28px;border-radius:50%;background:#38bdf822;border:1px solid #38bdf8;
                  display:flex;align-items:center;justify-content:center;
                  font-size:0.7em;font-weight:700;color:#38bdf8">2</div>
      <div style="width:1px;background:#1e293b;flex:1;margin-top:4px"></div>
    </div>
    <div style="background:#0d1420;border:1px solid #38bdf833;border-radius:8px;
                padding:10px 14px;flex:1;margin-bottom:4px">
      <div style="color:#38bdf8;font-size:0.78em;font-weight:700">👤 Load Student Profile</div>
      <div style="color:#64748b;font-size:0.72em;margin-top:2px">name, expertise, style preferences</div>
      <div style="color:#475569;font-size:0.68em;margin-top:4px">← covered in Part 2</div>
    </div>
  </div>

  <!-- step 3 -->
  <div style="display:flex;align-items:stretch;gap:12px;margin-bottom:4px">
    <div style="display:flex;flex-direction:column;align-items:center;width:32px;flex-shrink:0">
      <div style="width:28px;height:28px;border-radius:50%;background:#a78bfa22;border:1px solid #a78bfa;
                  display:flex;align-items:center;justify-content:center;
                  font-size:0.7em;font-weight:700;color:#a78bfa">3</div>
      <div style="width:1px;background:#1e293b;flex:1;margin-top:4px"></div>
    </div>
    <div style="background:#0d1420;border:1px solid #a78bfa33;border-radius:8px;
                padding:10px 14px;flex:1;margin-bottom:4px">
      <div style="color:#a78bfa;font-size:0.78em;font-weight:700">📚 Retrieve RAG Docs</div>
      <div style="color:#64748b;font-size:0.72em;margin-top:2px">fetch relevant course materials</div>
      <div style="color:#475569;font-size:0.68em;margin-top:4px">← covered in Part 5</div>
    </div>
  </div>

  <!-- step 4 -->
  <div style="display:flex;align-items:stretch;gap:12px;margin-bottom:4px">
    <div style="display:flex;flex-direction:column;align-items:center;width:32px;flex-shrink:0">
      <div style="width:28px;height:28px;border-radius:50%;background:#34d39922;border:1px solid #34d399;
                  display:flex;align-items:center;justify-content:center;
                  font-size:0.7em;font-weight:700;color:#34d399">4</div>
      <div style="width:1px;background:#1e293b;flex:1;margin-top:4px"></div>
    </div>
    <div style="background:#0d1420;border:1px solid #34d39933;border-radius:8px;
                padding:10px 14px;flex:1;margin-bottom:4px">
      <div style="color:#34d399;font-size:0.78em;font-weight:700">🧩 Assemble Context Window</div>
      <div style="color:#64748b;font-size:0.72em;margin-top:2px">system prompt + history + RAG + new message</div>
      <div style="color:#475569;font-size:0.68em;margin-top:4px">← covered in Part 5 visualizer</div>
    </div>
  </div>

  <!-- step 5 -->
  <div style="display:flex;align-items:stretch;gap:12px;margin-bottom:4px">
    <div style="display:flex;flex-direction:column;align-items:center;width:32px;flex-shrink:0">
      <div style="width:28px;height:28px;border-radius:50%;background:#f9e2af22;border:1px solid #f9e2af;
                  display:flex;align-items:center;justify-content:center;
                  font-size:0.7em;font-weight:700;color:#f9e2af">5</div>
      <div style="width:1px;background:#1e293b;flex:1;margin-top:4px"></div>
    </div>
    <div style="background:#0d1420;border:1px solid #f9e2af33;border-radius:8px;
                padding:10px 14px;flex:1;margin-bottom:4px">
      <div style="color:#f9e2af;font-size:0.78em;font-weight:700">🤖 LLM Inference → Stream Reply</div>
      <div style="color:#64748b;font-size:0.72em;margin-top:2px">generate response token by token</div>
      <div style="color:#475569;font-size:0.68em;margin-top:4px">← production: vLLM + SSE</div>
    </div>
  </div>

  <!-- step 6 -->
  <div style="display:flex;align-items:stretch;gap:12px;margin-bottom:4px">
    <div style="display:flex;flex-direction:column;align-items:center;width:32px;flex-shrink:0">
      <div style="width:28px;height:28px;border-radius:50%;background:#fbbf2422;border:1px solid #fbbf24;
                  display:flex;align-items:center;justify-content:center;
                  font-size:0.7em;font-weight:700;color:#fbbf24">6</div>
      <div style="width:1px;background:#1e293b;flex:1;margin-top:4px"></div>
    </div>
    <div style="background:#0d1420;border:1px solid #fbbf2433;border-radius:8px;
                padding:10px 14px;flex:1;margin-bottom:4px">
      <div style="color:#fbbf24;font-size:0.78em;font-weight:700">🔄 Detect Profile Changes</div>
      <div style="color:#64748b;font-size:0.72em;margin-top:2px">update expertise if user contradicts profile</div>
      <div style="color:#475569;font-size:0.68em;margin-top:4px">← covered in Part 4</div>
    </div>
  </div>

  <!-- step 7 -->
  <div style="display:flex;align-items:stretch;gap:12px">
    <div style="display:flex;flex-direction:column;align-items:center;width:32px;flex-shrink:0">
      <div style="width:28px;height:28px;border-radius:50%;background:#94b8d422;border:1px solid #94b8d4;
                  display:flex;align-items:center;justify-content:center;
                  font-size:0.7em;font-weight:700;color:#94b8d4">7</div>
    </div>
    <div style="background:#0d1420;border:1px solid #94b8d433;border-radius:8px;
                padding:10px 14px;flex:1">
      <div style="color:#94b8d4;font-size:0.78em;font-weight:700">💾 Persist Turn + Update Profile</div>
      <div style="color:#64748b;font-size:0.72em;margin-top:2px">save to Redis (recent) + PostgreSQL (long-term)</div>
      <div style="color:#475569;font-size:0.68em;margin-top:4px">← production: Redis + PostgreSQL</div>
    </div>
  </div>

</div>
"""

display(HTML(part7_html))
display(HTML(flow_html))

# Quiz: LLM Context Engineering — Hangman Edition
# ══════════════════════════════════════════════════════════════
#  5 random questions. Wrong answer = one hangman stroke.
#  6 wrong answers = game over. Pure HTML/JS.
# ══════════════════════════════════════════════════════════════
import json
import random
from IPython.display import display, HTML

QUESTION_POOL = [
    {
        "q": "Why does the LLM forget what was said in previous turns?",
        "options": ["The model's memory fills up after each reply", "The model is stateless — it only sees what you pass in right now", "The API deletes history to save bandwidth", "The system prompt overwrites previous messages"],
        "answer": 1, "explanation": "LLMs are stateless. Every call starts fresh — the only 'memory' is the messages list you pass in.", "part": "Part 1",
    },
    {
        "q": "What is the correct way to give the model memory of previous turns?",
        "options": ["Maintain a messages list and pass the full history with every API call", "Set a session cookie with the conversation ID", "Call model.remember() before each new message", "Use a larger model with more parameters"],
        "answer": 0, "explanation": "You maintain a messages list and pass the full history with every API call. The model has no built-in memory.", "part": "Part 1",
    },
    {
        "q": "Zoe needs to handle 300 students with different skill levels. What is her solution?",
        "options": ["Write 300 hardcoded system prompts, one per student", "Ask each student to manually set their level in a settings menu", "Store student info in a profile dict and auto-generate the system prompt", "Train a separate model for each skill level"],
        "answer": 2, "explanation": "A profile dict is injected into a template to auto-generate a personalised system prompt dynamically.", "part": "Part 2",
    },
    {
        "q": "What happens to token usage as a conversation grows longer?",
        "options": ["Token usage stays constant — only the latest message is sent", "Token usage grows linearly — every turn re-sends the full history", "Token usage decreases as the model gets more efficient", "Token usage only grows when the system prompt changes"],
        "answer": 1, "explanation": "Because you pass the full messages list every call, token usage grows with every turn.", "part": "Part 2",
    },
    {
        "q": "What does the system prompt control that a user message cannot?",
        "options": ["The model's response length", "The persona, tone, and instructions that frame every reply", "Which GPU the model runs on", "The temperature and sampling parameters"],
        "answer": 1, "explanation": "The system prompt sets the AI's persona, tone, and standing instructions — it shapes every reply.", "part": "Part 2",
    },
    {
        "q": "The assistant is getting slower every day. What is the root cause?",
        "options": ["The model server is overloaded with concurrent users", "The system prompt has grown too long", "The full conversation history is re-sent every call, filling the context window", "RAG retrieval is adding too many documents"],
        "answer": 2, "explanation": "After 40+ turns, the context window is nearly full. Every call processes the entire history from scratch.", "part": "Part 4",
    },
    {
        "q": "Which compression strategy preserves the most semantic meaning from old turns?",
        "options": ["Sliding window — keep only the last N messages", "Hard truncation — drop the oldest messages one by one", "Keyword extraction — keep sentences with important words", "Semantic compression — ask the model to summarise old turns"],
        "answer": 3, "explanation": "Semantic compression asks the model to summarise older turns, preserving meaning while drastically cutting token count.", "part": "Part 4",
    },
    {
        "q": "What is the main risk of sliding window truncation?",
        "options": ["It uses too many tokens", "It loses early context — like the student's name and background", "It makes the model reply more slowly", "It breaks the messages list format"],
        "answer": 1, "explanation": "Sliding window discards the oldest messages — often the ones containing the student's profile and background.", "part": "Part 4",
    },
    {
        "q": "Which of these is an anti-pattern Zoe discovered when managing context?",
        "options": ["Passing the system prompt as the first message", "Dumping the full user profile inline into every user message", "Using RAG to retrieve course documents before each call", "Compressing history older than 10 turns"],
        "answer": 1, "explanation": "Dumping all user data inline into every user message bloats the context. Profile injection belongs in the system prompt.", "part": "Part 4c",
    },
    {
        "q": "What problem does RAG (Retrieval-Augmented Generation) solve?",
        "options": ["It makes the model faster by caching common answers", "It lets the model answer questions about info it was never trained on", "It replaces the system prompt with retrieved documents", "It automatically compresses conversation history"],
        "answer": 1, "explanation": "RAG retrieves relevant documents and injects them into the context before calling the model.", "part": "Part 5",
    },
    {
        "q": "In the RAG demo, how does retrieve() find relevant documents?",
        "options": ["It uses vector embeddings and cosine similarity", "It asks the model which documents are relevant", "It counts keyword overlap between the query and each document", "It fetches documents randomly and filters by date"],
        "answer": 2, "explanation": "The demo uses simple keyword overlap. In production you would use a vector DB for semantic similarity.", "part": "Part 5",
    },
    {
        "q": "What would you use instead of keyword overlap in a production RAG system?",
        "options": ["A SQL LIKE query over a PostgreSQL table", "Vector similarity search using embeddings (FAISS, Pinecone, pgvector)", "A BM25 inverted index with TF-IDF scoring", "A simple Python list comprehension with string matching"],
        "answer": 1, "explanation": "Production RAG uses vector embeddings — nearest-neighbour search finds semantically similar documents.", "part": "Part 5",
    },
    {
        "q": "A student says they are a beginner, then later claims 5 years of experience. What should happen?",
        "options": ["Ignore the new claim and keep the original profile", "Ask the student to confirm which statement is correct", "Detect the contradiction and auto-update the profile", "Start a brand new session with a blank profile"],
        "answer": 2, "explanation": "Conflict detection compares the new message against the stored profile and updates automatically.", "part": "Part 6",
    },
    {
        "q": "In the conflict detection demo, what triggers a profile update without a model call?",
        "options": ["Any message longer than 20 words", "Keywords like 'years of experience' or 'senior developer'", "A change in the student's writing style", "The model's confidence score dropping below 0.5"],
        "answer": 1, "explanation": "Keyword matching runs first — fast and cheap. The model call is only a fallback.", "part": "Part 6",
    },
    {
        "q": "In a production system, what replaces the in-memory messages list for short-term history?",
        "options": ["A PostgreSQL table with one row per message", "A Redis cache — fast, temporary storage for the last 10 turns", "A vector database like FAISS or Pinecone", "A local JSON file written to disk after each turn"],
        "answer": 1, "explanation": "Redis handles short-term, fast-access history. PostgreSQL stores full long-term history.", "part": "Part 7",
    },
    {
        "q": "In the production architecture, what is the role of PostgreSQL?",
        "options": ["Fast cache for the last 10 turns of conversation", "Vector similarity search for RAG retrieval", "Long-term persistent storage for full conversation history and profiles", "Load balancer for distributing requests across model servers"],
        "answer": 2, "explanation": "PostgreSQL is the permanent store — it keeps the full learning history across sessions.", "part": "Part 7",
    },
    {
        "q": "What does vLLM provide in a production deployment?",
        "options": ["A vector database for RAG retrieval", "An efficient model server that handles many concurrent requests", "A compression algorithm for conversation history", "A safety filter that blocks prompt injection"],
        "answer": 1, "explanation": "vLLM is a high-throughput model serving framework that handles batching and concurrent requests efficiently.", "part": "Part 7",
    },
    {
        "q": "Which notebook concept maps to a Safety Filter (Llama Guard) in production?",
        "options": ["The STOPWORDS set in the RAG retriever", "The INJECTION_PATTERNS guard in the system prompt", "The MAX_HISTORY limit in the compression logic", "The conflict detection keyword list"],
        "answer": 1, "explanation": "The INJECTION_PATTERNS guard blocks prompt injection attempts. In production, this becomes a dedicated safety model like Llama Guard.", "part": "Part 7",
    },
    {
        "q": "Why does the Final Demo use threading.Thread for model calls?",
        "options": ["To run multiple model calls simultaneously for faster responses", "To keep the UI live and responsive while the model is generating", "To avoid hitting API rate limits", "To save memory by running the model in a separate process"],
        "answer": 1, "explanation": "Without threading, the UI freezes for 60-90s while the model runs.", "part": "Final Demo",
    },
    {
        "q": "What is the key advantage of widgets.HTML over widgets.Output for the chat log?",
        "options": ["widgets.HTML supports more HTML tags than widgets.Output", "widgets.HTML renders faster because it uses less memory", "widgets.HTML can be updated from any thread and renders immediately", "widgets.HTML automatically scrolls to the bottom of the chat"],
        "answer": 2, "explanation": "widgets.Output blocks all UI updates until the Python function finishes. widgets.HTML.value can be set from a background thread and renders immediately.", "part": "Final Demo",
    },
]

NUM_QUESTIONS = 5
MAX_WRONG     = 6
pool_json     = json.dumps(QUESTION_POOL)

html = f"""
<style>
  .hm-wrap {{
    font-family: 'IBM Plex Mono', 'Fira Code', monospace;
    background: #080c12;
    border-radius: 14px;
    padding: 20px;
    max-width: 860px;
  }}
  .hm-header {{
    background: linear-gradient(135deg, #0a1628, #0d1f3c);
    border: 1px solid #1e3a5f;
    border-radius: 12px;
    padding: 16px 20px;
    margin-bottom: 16px;
    display: flex;
    justify-content: space-between;
    align-items: center;
  }}
  .hm-title {{ color: #f0f6ff; font-weight: 700; font-size: 1.05em; }}
  .hm-sub   {{ color: #475569; font-size: 0.72em; margin-top: 4px; }}

  .hm-body {{
    display: flex;
    gap: 20px;
    align-items: flex-start;
    margin-bottom: 16px;
  }}

  /* Hangman SVG panel */
  .hm-scaffold {{
    flex-shrink: 0;
    background: #0d1420;
    border: 1px solid #1e293b;
    border-radius: 12px;
    padding: 12px;
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 8px;
    width: 160px;
  }}
  .hm-lives {{
    font-size: 0.72em;
    color: #475569;
    text-align: center;
  }}
  .hm-lives span {{ color: #f87171; font-weight: 700; }}

  /* Question panel */
  .hm-qpanel {{
    flex: 1;
  }}
  .hm-progress {{
    font-size: 0.72em;
    color: #475569;
    margin-bottom: 10px;
    display: flex;
    justify-content: space-between;
  }}
  .hm-progress .correct-count {{ color: #34d399; font-weight: 700; }}
  .hm-progress .wrong-count   {{ color: #f87171; font-weight: 700; }}

  .q-block {{
    background: #0d1420;
    border: 1px solid #1e293b;
    border-radius: 12px;
    padding: 16px 18px;
  }}
  .q-meta {{ display: flex; align-items: center; gap: 8px; margin-bottom: 10px; }}
  .q-part {{
    background: #1e3a5f; color: #38bdf8; font-size: 0.62em; font-weight: 700;
    padding: 2px 9px; border-radius: 20px; text-transform: uppercase; letter-spacing: 0.05em;
  }}
  .q-num  {{ color: #475569; font-size: 0.68em; }}
  .q-text {{ color: #e2e8f0; font-size: 0.88em; font-weight: 600; line-height: 1.6; margin-bottom: 12px; }}

  .opt {{
    background: #111827; border: 1px solid #1e293b; border-radius: 8px;
    padding: 11px 14px; margin-bottom: 7px; cursor: pointer;
    display: flex; align-items: flex-start; gap: 10px;
    transition: border-color 0.15s, background 0.15s;
  }}
  .opt:hover {{ border-color: #38bdf8; background: #0f1f35; }}
  .opt-letter {{
    background: #1e293b; color: #64748b; font-size: 0.70em; font-weight: 700;
    width: 20px; height: 20px; border-radius: 50%;
    display: flex; align-items: center; justify-content: center; flex-shrink: 0; margin-top: 1px;
  }}
  .opt-text {{ color: #94a3b8; font-size: 0.82em; line-height: 1.5; }}

  .opt.correct {{ background: #052e16; border-color: #34d399; cursor: default; }}
  .opt.correct .opt-letter {{ background: #34d399; color: #052e16; }}
  .opt.correct .opt-text   {{ color: #a7f3d0; }}
  .opt.wrong   {{ background: #1c0a0a; border-color: #f87171; cursor: default; }}
  .opt.wrong .opt-letter   {{ background: #f87171; color: #1c0a0a; }}
  .opt.wrong .opt-text     {{ color: #fca5a5; }}
  .opt.locked  {{ cursor: default; }}
  .opt.locked:hover        {{ border-color: #1e293b; background: #111827; }}
  .opt.locked.correct:hover {{ border-color: #34d399; background: #052e16; }}
  .opt.dim     {{ opacity: 0.35; cursor: default; pointer-events: none; }}

  .feedback {{
    margin-top: 8px; padding: 10px 14px; border-radius: 0 8px 8px 0;
    font-size: 0.78em; line-height: 1.6; color: #cbd5e1; display: none;
  }}
  .feedback.show       {{ display: block; }}
  .feedback.correct-fb {{ background: #34d39910; border-left: 3px solid #34d399; }}
  .feedback.wrong-fb   {{ background: #f8717110; border-left: 3px solid #f87171; }}

  .next-btn {{
    margin-top: 12px; padding: 8px 20px; border-radius: 8px;
    background: #1e3a5f; border: 1px solid #38bdf8; color: #38bdf8;
    font-family: inherit; font-size: 0.82em; font-weight: 700;
    cursor: pointer; display: none; transition: background 0.15s;
  }}
  .next-btn:hover {{ background: #0f1f35; }}
  .next-btn.visible {{ display: inline-block; }}

  .final-screen {{
    background: #0d1420; border-radius: 12px; padding: 28px 24px;
    text-align: center; display: none;
  }}
  .final-screen.show {{ display: block; }}
  .final-big {{ font-size: 3.0em; font-weight: 700; line-height: 1; margin-bottom: 8px; }}
  .final-msg {{ font-size: 0.88em; margin-bottom: 16px; }}
  .retry-btn {{
    display: inline-block; padding: 10px 24px; border-radius: 8px;
    font-family: inherit; font-size: 0.85em; font-weight: 700;
    cursor: pointer; border: 1px solid; transition: opacity 0.15s;
  }}
  .retry-btn:hover {{ opacity: 0.75; }}

  /* Hangman SVG strokes */
  .hm-svg line, .hm-svg circle, .hm-svg path {{
    stroke-linecap: round;
    transition: opacity 0.3s;
  }}
  .hm-stroke {{ opacity: 0; }}
  .hm-stroke.drawn {{ opacity: 1; }}
</style>

<div class="hm-wrap">

  <div class="hm-header">
    <div>
      <div style="font-size:0.58em;color:#38bdf8;text-transform:uppercase;letter-spacing:0.15em;margin-bottom:3px">LLM Context Engineering</div>
      <div class="hm-title">🪢 Hangman Quiz</div>
      <div class="hm-sub">Wrong answer = one stroke. 6 strokes = game over.</div>
    </div>
    <div style="text-align:right;color:#475569;font-size:0.70em">
      <div>{NUM_QUESTIONS} questions</div>
      <div style="color:#38bdf8;font-weight:700">{MAX_WRONG} lives</div>
    </div>
  </div>

  <div class="hm-body">

    <!-- Hangman figure -->
    <div class="hm-scaffold">
      <svg class="hm-svg" width="120" height="140" viewBox="0 0 120 140">
        <!-- Gallows (always visible) -->
        <line x1="10" y1="135" x2="110" y2="135" stroke="#1e3a5f" stroke-width="3"/>
        <line x1="30"  y1="135" x2="30"  y2="10"  stroke="#1e3a5f" stroke-width="3"/>
        <line x1="30"  y1="10"  x2="75"  y2="10"  stroke="#1e3a5f" stroke-width="3"/>
        <line x1="75"  y1="10"  x2="75"  y2="28"  stroke="#1e3a5f" stroke-width="3"/>
        <!-- Stroke 1: head -->
        <circle class="hm-stroke" id="hm-s1" cx="75" cy="38" r="10" stroke="#f87171" stroke-width="2.5" fill="none"/>
        <!-- Stroke 2: body -->
        <line class="hm-stroke" id="hm-s2" x1="75" y1="48" x2="75" y2="90" stroke="#f87171" stroke-width="2.5"/>
        <!-- Stroke 3: left arm -->
        <line class="hm-stroke" id="hm-s3" x1="75" y1="60" x2="52" y2="78" stroke="#f87171" stroke-width="2.5"/>
        <!-- Stroke 4: right arm -->
        <line class="hm-stroke" id="hm-s4" x1="75" y1="60" x2="98" y2="78" stroke="#f87171" stroke-width="2.5"/>
        <!-- Stroke 5: left leg -->
        <line class="hm-stroke" id="hm-s5" x1="75" y1="90" x2="52" y2="115" stroke="#f87171" stroke-width="2.5"/>
        <!-- Stroke 6: right leg -->
        <line class="hm-stroke" id="hm-s6" x1="75" y1="90" x2="98" y2="115" stroke="#f87171" stroke-width="2.5"/>
      </svg>
      <div class="hm-lives">Lives left: <span id="lives-left">{MAX_WRONG}</span></div>
      <div id="wrong-pills" style="display:flex;flex-wrap:wrap;gap:3px;justify-content:center;margin-top:4px"></div>
    </div>

    <!-- Question panel -->
    <div class="hm-qpanel">
      <div class="hm-progress">
        <span>Question <span id="q-current">1</span> / {NUM_QUESTIONS}</span>
        <span><span class="correct-count" id="correct-count">0</span> correct &nbsp; <span class="wrong-count" id="wrong-count">0</span> wrong</span>
      </div>
      <div id="q-container"></div>
    </div>

  </div>

  <!-- Final screen (hidden until end) -->
  <div class="final-screen" id="final-screen"></div>

</div>

<script>
(function() {{

  var POOL      = {pool_json};
  var N         = {NUM_QUESTIONS};
  var MAX_WRONG = {MAX_WRONG};

  var wrongCount   = 0;
  var correctCount = 0;
  var qIndex       = 0;
  var questions    = [];
  var gameOver     = false;

  // ── DOM refs ────────────────────────────────────────────────
  var qContainer   = document.getElementById('q-container');
  var livesLeft    = document.getElementById('lives-left');
  var wrongPills   = document.getElementById('wrong-pills');
  var qCurrent     = document.getElementById('q-current');
  var correctEl    = document.getElementById('correct-count');
  var wrongEl      = document.getElementById('wrong-count');
  var finalScreen  = document.getElementById('final-screen');

  // ── Shuffle ─────────────────────────────────────────────────
  function shuffle(arr) {{
    var a = arr.slice();
    for (var i = a.length - 1; i > 0; i--) {{
      var j = Math.floor(Math.random() * (i + 1));
      var t = a[i]; a[i] = a[j]; a[j] = t;
    }}
    return a;
  }}

  // ── Draw hangman stroke ─────────────────────────────────────
  function drawStroke(n) {{
    var el = document.getElementById('hm-s' + n);
    if (el) el.classList.add('drawn');
  }}

  // ── Render one question ─────────────────────────────────────
  function renderQuestion(qi) {{
    var q = questions[qi];
    qCurrent.textContent = qi + 1;

    var opts = '';
    q.options.forEach(function(opt, oi) {{
      opts +=
        '<div class="opt" id="opt-' + oi + '" onclick="hmAnswer(' + oi + ')">' +
          '<div class="opt-letter">' + String.fromCharCode(65 + oi) + '</div>' +
          '<div class="opt-text">' + opt + '</div>' +
        '</div>';
    }});

    qContainer.innerHTML =
      '<div class="q-block">' +
        '<div class="q-meta">' +
          '<span class="q-part">' + q.part + '</span>' +
          '<span class="q-num">Q' + (qi + 1) + '</span>' +
        '</div>' +
        '<div class="q-text">' + q.q + '</div>' +
        opts +
        '<div class="feedback" id="fb"></div>' +
        '<button class="next-btn" id="next-btn" onclick="hmNext()">Next question →</button>' +
      '</div>';
  }}

  // ── Answer handler ───────────────────────────────────────────
  window.hmAnswer = function(oi) {{
    if (gameOver) return;
    var q       = questions[qIndex];
    var correct = q.answer;
    var isRight = (oi === correct);
    var fb      = document.getElementById('fb');
    var nextBtn = document.getElementById('next-btn');

    // Lock all options
    for (var j = 0; j < q.options.length; j++) {{
      var el = document.getElementById('opt-' + j);
      if (!el) continue;
      el.classList.add('locked');
      el.removeAttribute('onclick');
      if (j === correct)       el.classList.add('correct');
      else if (j === oi)       el.classList.add('wrong');
      else                     el.classList.add('dim');
    }}

    if (isRight) {{
      correctCount++;
      correctEl.textContent = correctCount;
      fb.className  = 'feedback show correct-fb';
      fb.innerHTML  = '✅ <strong style="color:#34d399">Correct!</strong> ' + q.explanation;
    }} else {{
      wrongCount++;
      wrongEl.textContent = wrongCount;
      drawStroke(wrongCount);
      livesLeft.textContent = MAX_WRONG - wrongCount;

      // Add wrong pill
      var pill = document.createElement('div');
      pill.style.cssText = 'background:#f8717120;border:1px solid #f87171;border-radius:4px;padding:1px 6px;font-size:0.65em;color:#f87171';
      pill.textContent = '✗';
      wrongPills.appendChild(pill);

      fb.className = 'feedback show wrong-fb';
      fb.innerHTML = '❌ <strong style="color:#f87171">Wrong.</strong> ' + q.explanation;

      if (wrongCount >= MAX_WRONG) {{
        gameOver = true;
        setTimeout(function() {{ showFinal(false); }}, 1200);
        return;
      }}
    }}

    // Show next button or finish
    if (qIndex >= N - 1) {{
      nextBtn.textContent = '🏁 See results';
      nextBtn.classList.add('visible');
    }} else {{
      nextBtn.classList.add('visible');
    }}
  }};

  // ── Next question ────────────────────────────────────────────
  window.hmNext = function() {{
    qIndex++;
    if (qIndex >= N) {{
      showFinal(true);
    }} else {{
      renderQuestion(qIndex);
    }}
  }};

  // ── Final screen ─────────────────────────────────────────────
  function showFinal(completed) {{
    document.querySelector('.hm-body').style.display = 'none';
    finalScreen.classList.add('show');

    var pct   = Math.round(correctCount / N * 100);
    var color, emoji, msg;

    if (!completed) {{
      color = '#f87171'; emoji = '💀'; msg = 'Game Over! The man has been hanged...';
    }} else if (correctCount === N) {{
      color = '#34d399'; emoji = '🎉'; msg = 'Perfect! Not a scratch on the man!';
    }} else if (correctCount >= Math.ceil(N * 0.7)) {{
      color = '#f9e2af'; emoji = '😅'; msg = 'Close call — but you survived!';
    }} else {{
      color = '#f87171'; emoji = '😬'; msg = 'Lucky escape. Review the notebook!';
    }}

    finalScreen.innerHTML =
      '<div class="final-big" style="color:' + color + '">' + emoji + '</div>' +
      '<div style="color:' + color + ';font-weight:700;font-size:1.1em;margin-bottom:6px">' + msg + '</div>' +
      '<div class="final-msg" style="color:#94b8d4">' +
        'Score: <strong style="color:' + color + '">' + correctCount + '/' + N + ' (' + pct + '%)</strong>' +
        ' &nbsp;·&nbsp; Wrong answers: <strong style="color:#f87171">' + wrongCount + '</strong>' +
      '</div>' +
      '<button class="retry-btn" style="background:' + color + '18;border-color:' + color + ';color:' + color + '" ' +
              'onclick="hmRestart()">🔄 Play Again</button>';
  }}

  // ── Restart ──────────────────────────────────────────────────
  window.hmRestart = function() {{
    // Reset state
    wrongCount = correctCount = qIndex = 0;
    gameOver   = false;

    // Reset hangman strokes
    for (var i = 1; i <= MAX_WRONG; i++) {{
      var el = document.getElementById('hm-s' + i);
      if (el) el.classList.remove('drawn');
    }}

    // Reset counters
    livesLeft.textContent = MAX_WRONG;
    wrongPills.innerHTML  = '';
    correctEl.textContent = '0';
    wrongEl.textContent   = '0';

    // Show game, hide final
    document.querySelector('.hm-body').style.display = 'flex';
    finalScreen.classList.remove('show');

    // New questions
    questions = shuffle(POOL).slice(0, N);
    renderQuestion(0);
  }};

  // ── Kick off ─────────────────────────────────────────────────
  questions = shuffle(POOL).slice(0, N);
  renderQuestion(0);

}})();
</script>
"""

display(HTML(html))