Upload folder using huggingface_hub

app.py

@@ -84,17 +84,29 @@ def _payload(turn_id, voice_on, status, detail, new_steps, seq_start):
     })
 
 
+def _track_board(board_ops, step_board):
+    """Mirror what the lesson drew so the next turn knows the board state."""
+    for op in step_board or []:
+        if op.get("op") == "clear":
+            board_ops = []
+        else:
+            board_ops.append(op)
+    return board_ops[-60:]
+
+
 def run_turn(audio_path, typed_text, snapshot, chat, convo, profile,
-             pace, web_on, voice_on):
+             notes, board_ops, pace, web_on, voice_on):
     """Bridges ENGINE.run_turn events into streaming Gradio updates."""
     chat = list(chat or [])
     convo = list(convo or [])
     profile = dict(profile or {})
+    notes = notes or ""
+    board_ops = list(board_ops or [])
     turn_id = uuid.uuid4().hex[:10]
 
     has_input = bool(audio_path or (typed_text or "").strip() or snapshot)
     if not has_input:
-        yield (gr.update(), chat, convo, profile, profile,
+        yield (gr.update(), chat, convo, profile, profile, notes, board_ops,
                gr.update(), gr.update())
         return
 
@@ -106,8 +118,8 @@ def run_turn(audio_path, typed_text, snapshot, chat, convo, profile,
 
     def render(status="thinking", detail="", new_steps=(), seq=0):
         return (_payload(turn_id, voice_on, status, detail, list(new_steps), seq),
-                chat, convo, profile, profile, gr.update(value=None),
-                gr.update(value=""))
+                chat, convo, profile, profile, notes, board_ops,
+                gr.update(value=None), gr.update(value=""))
 
     yield render(detail="Thinking…")
 
@@ -116,7 +128,7 @@ def run_turn(audio_path, typed_text, snapshot, chat, convo, profile,
     print(f"[tutori] turn {turn_id}: starting engine", flush=True)
     try:
         for ev in ENGINE.run_turn(audio_path, typed_text, snapshot, convo, profile,
-                                  pace, web_on, voice_on):
+                                  notes, board_ops, pace, web_on, voice_on):
             kind = ev.get("type")
             if seq == 0 and kind != "step":
                 print(f"[tutori] turn {turn_id}: event {kind}", flush=True)
@@ -126,9 +138,14 @@ def run_turn(audio_path, typed_text, snapshot, chat, convo, profile,
                 question_for_context = ev["text"]
                 chat[-2]["content"] = f"🎙️ {ev['text']}"
                 yield render("thinking", "Heard you!", (), seq)
+            elif kind == "research":
+                fresh = ev.get("notes", "")
+                if fresh:
+                    notes = (notes + "\n" + fresh)[-4000:]
             elif kind == "step":
                 step = ev["step"]
                 says.append(step.get("say", ""))
+                board_ops = _track_board(board_ops, step.get("board"))
                 chat[-1]["content"] = "✏️ " + " ".join(s for s in says if s)
                 yield render("teaching", f"Teaching — step {seq + 1}", [step], seq)
                 seq += 1
@@ -156,12 +173,12 @@ def run_turn(audio_path, typed_text, snapshot, chat, convo, profile,
     final_text = " ".join(s for s in says if s).strip() or chat[-1]["content"]
     chat[-1]["content"] = "✏️ " + final_text
     convo.append({"role": "user", "content": question_for_context})
-    convo.append({"role": "assistant", "content": final_text[:900]})
+    convo.append({"role": "assistant", "content": final_text[:1200]})
     yield render("done", "", (), seq)
 
 
 def reset_session():
-    return [], [], "", gr.update(value=None)
+    return [], [], "", [], gr.update(value=None)
 
 
 def forget_me():
@@ -180,6 +197,8 @@ with gr.Blocks(
 
     profile_state = gr.BrowserState(EMPTY_PROFILE, storage_key="tutori_profile_v1")
     convo_state = gr.State([])
+    notes_state = gr.State("")     # web research carried across the session
+    board_state = gr.State([])     # ops currently on the board (server mirror)
 
     payload_box = gr.Textbox(visible=False, elem_id="tutori-payload")
     snap_box = gr.Textbox(visible=False)
@@ -256,17 +275,17 @@ with gr.Blocks(
     # `snap_box`. (gr.State arrives as null in js; pass it through untouched.)
     def _snap_js(fn_name):
         return (
-            "(audio, text, snap, chat, convo, profile, pace, web, voice) => "
+            "(audio, text, snap, chat, convo, profile, notes, board, pace, web, voice) => "
             f"[audio, text, (window.{fn_name} ? window.{fn_name}() : ''), "
-            "chat, convo, profile, pace, web, voice]"
+            "chat, convo, profile, notes, board, pace, web, voice]"
         )
 
     turn_io = dict(
         fn=run_turn,
         inputs=[mic, text_in, snap_box, chatbot, convo_state, profile_state,
-                pace, web_on, voice_on],
+                notes_state, board_state, pace, web_on, voice_on],
         outputs=[payload_box, chatbot, convo_state, profile_state, profile_view,
-                 mic, text_in],
+                 notes_state, board_state, mic, text_in],
         show_progress="hidden",
     )
 
@@ -284,7 +303,8 @@ with gr.Blocks(
     skip_btn.click(fn=None, inputs=None, outputs=None,
                    js="() => window.tutoriStop()")
     new_btn.click(
-        reset_session, None, [chatbot, convo_state, text_in, mic],
+        reset_session, None,
+        [chatbot, convo_state, text_in, board_state, mic],
         js="() => { window.tutoriClearAll && window.tutoriClearAll(); return []; }",
     )
     forget_btn.click(forget_me, None, [profile_state, profile_view])

engine.py

@@ -125,18 +125,34 @@ Respond with ONE JSON object and NOTHING else (no markdown fences, no prose outs
 }}
 
 Rules for "say" (spoken by a TTS voice):
-- Natural, friendly spoken language. 1-2 short sentences, at most 28 words per step.
+- Natural, friendly spoken language. 1-3 sentences, 15 to 35 words per step.
 - Never use markdown, symbols, URLs or formulas as symbols: say "x squared", "pi", "H two O".
-- Sound like a human tutor: occasional "Alright", "Now here's the neat part", direct address.
+- Sound like a human tutor mid-conversation: vary your openings, address the learner directly.
 
 Rules for "steps":
-- 3 to 5 steps. Together they form one mini whiteboard lesson answering the learner.
-- Each step has 1 to 4 board ops that draw exactly what that step says.
-- Step 1 usually starts with {{"op":"clear"}} then a short title.
-- Build the diagram cumulatively across steps; later steps add arrows, labels, highlights.
-- Prefer pictures over text: boxes + arrows for relationships and processes, axes + curve
-  for anything quantitative, dots + labels for points of interest. Use color meaningfully.
-- The last step often asks one short check-in question matched to the learner's pace.
+- 3 to 5 steps forming one mini whiteboard lesson that directly answers the learner.
+- Each step has 1 to 4 board ops that draw exactly what that step says, as you say it.
+- THE DRAWING MUST BE SPECIFIC TO THIS TOPIC. Draw the idea's REAL structure — actual
+  names, values, shapes and relationships — never a generic input/process/output chain
+  and never the same layout you drew last time. Examples of being specific:
+    * recursion -> the actual call tree with real arguments at each node
+    * binary search -> a row of small boxes with the real sorted numbers, dots and
+      underlines marking lo, mid, hi as they move
+    * supply and demand -> axes with the two labeled curves crossing at a dot
+    * photosynthesis -> a leaf (ellipse) with labeled arrows in (sun, water, CO2) and out (O2, sugar)
+- Build ONE diagram cumulatively: later steps ADD arrows, labels, dots, highlights to
+  what is already drawn. {{"op":"clear"}} is allowed ONLY as the first op of step 1, and
+  ONLY when BOARD NOW shows a different topic. For a follow-up on the same topic: no
+  clear, no new title — extend and annotate the existing drawing.
+- Never place two elements at overlapping coordinates; check BOARD NOW for occupied space.
+- Use color with meaning (e.g. red = the thing to watch, green = result, gray = notes).
+- The last step usually asks one short check-in question matched to the learner's pace.
+
+Conversation behavior:
+- The chat history is the lesson so far. On follow-ups: skip greetings and recaps,
+  answer the actual question, go deeper or give a new angle — never re-teach what the
+  learner already confirmed they understood.
+- If the learner answered your check-in question, react to THEIR answer first.
 
 {board_reference}
 
@@ -147,7 +163,8 @@ confused them, preferred pace). Keep it under 90 words total.
 
 LEARNER PACE SETTING: {pace}
 CURRENT LEARNER PROFILE: {profile}
-TODAY: {today}{web_block}"""
+BOARD NOW (ops already drawn, oldest first): {board_now}
+TODAY: {today}{notes_block}{web_block}"""
 
 PACE_DESCRIPTIONS = {
     1: "Total beginner — tiny steps, everyday analogies, zero jargon, frequent reassurance.",
@@ -161,7 +178,8 @@ SEARCH_SYSTEM = """You are the research planner for a tutor agent. Today is {tod
 Decide whether a quick web search would materially improve a whiteboard lesson on the
 learner's request. Conceptual/timeless topics (math, physics, programming basics,
 history before this year) need NO search. Current events, prices, versions, schedules,
-records, or anything after your training data DOES need one.
+records, niche/new algorithms or papers, or anything after your training data DOES
+need one. If the EXISTING NOTES below already cover the question, do NOT search again.
 Answer with ONE JSON object only:
 {{"search": false}}  or  {{"search": true, "queries": ["...", "..."]}}  (max 2 queries)"""
 
@@ -389,6 +407,13 @@ def synthesize(text):
             audio = audio.mean(axis=1)
         peak = float(np.max(np.abs(audio))) or 1.0
         audio = audio / max(peak, 1.0) * 0.92
+        # trim leading/trailing silence — Higgs pads generations with dead
+        # air, which reads as awkward pauses between lesson steps
+        voiced = np.where(np.abs(audio) > 0.012)[0]
+        if voiced.size:
+            start = max(0, int(voiced[0]) - int(0.04 * sr))
+            end = min(len(audio), int(voiced[-1]) + int(0.14 * sr))
+            audio = audio[start:end]
         buf = io.BytesIO()
         sf.write(buf, audio, sr, format="WAV", subtype="PCM_16")
         b64 = base64.b64encode(buf.getvalue()).decode("ascii")
@@ -402,11 +427,14 @@ def synthesize(text):
 # web research (DuckDuckGo, no key needed)
 # --------------------------------------------------------------------------
 
-def decide_search(question, profile):
+def decide_search(question, profile, notes):
     today = datetime.date.today().isoformat()
+    notes_hint = f"\nEXISTING NOTES (from earlier this session): {notes[:500]}" if notes else ""
     msgs = [
         {"role": "system", "content": SEARCH_SYSTEM.format(today=today)},
-        {"role": "user", "content": f"Learner request: {question}\nLearner profile: {json.dumps(profile)[:400]}"},
+        {"role": "user",
+         "content": f"Learner request: {question}\n"
+                    f"Learner profile: {json.dumps(profile)[:400]}{notes_hint}"},
     ]
     try:
         raw = llm_generate(msgs, max_new_tokens=96, temperature=0.0)
@@ -418,8 +446,24 @@ def decide_search(question, profile):
     return []
 
 
+def _fetch_page(url, limit=1500):
+    """Pull readable text from a page — snippets alone are too shallow to
+    teach from (e.g. a newly published algorithm)."""
+    try:
+        import requests
+        r = requests.get(url, timeout=4,
+                         headers={"User-Agent": "Mozilla/5.0 (TutoriBot/1.0)"})
+        txt = re.sub(r"<(script|style|nav|header|footer)[\s\S]*?</\1>", " ", r.text)
+        txt = re.sub(r"<[^>]+>", " ", txt)
+        txt = re.sub(r"&[a-z#0-9]+;", " ", txt)
+        txt = re.sub(r"\s+", " ", txt).strip()
+        return txt[:limit]
+    except Exception:
+        return ""
+
+
 def web_research(queries):
-    snippets = []
+    snippets, page_text, first_url = [], "", None
     try:
         from ddgs import DDGS
         with DDGS() as ddg:
@@ -428,35 +472,51 @@ def web_research(queries):
                     for r in ddg.text(q, max_results=4):
                         title = r.get("title", "")
                         body = r.get("body", "")
+                        href = r.get("href", "")
+                        if first_url is None and href:
+                            first_url = href
                         if body:
                             snippets.append(f"- {title}: {body}")
                 except Exception:
                     continue
     except Exception as e:
         print(f"[tutori] web research failed: {e}")
-    return "\n".join(snippets[:10])
+    if first_url:
+        page_text = _fetch_page(first_url)
+    out = "\n".join(snippets[:8])
+    if page_text:
+        out += f"\n\nFROM {first_url}:\n{page_text}"
+    return out[:3000]
 
 
 # --------------------------------------------------------------------------
 # the agent turn
 # --------------------------------------------------------------------------
 
-def _build_messages(question, history, profile, pace, web_context, board_image):
+def _build_messages(question, history, profile, pace, web_context, board_image,
+                    notes="", board_now=None):
     today = datetime.date.today().isoformat()
     web_block = (
         f"\n\nWEB CONTEXT (gathered just now — fold relevant facts into the lesson):\n{web_context}"
         if web_context else ""
     )
+    notes_block = (
+        f"\nRESEARCH NOTES (gathered earlier this session, still relevant):\n{notes[:2200]}"
+        if notes else ""
+    )
     system = LESSON_SYSTEM.format(
         board_reference=BOARD_REFERENCE,
         pace=PACE_DESCRIPTIONS.get(int(pace), PACE_DESCRIPTIONS[3]),
         profile=json.dumps(profile or {}, ensure_ascii=False)[:700],
+        board_now=(json.dumps(board_now, ensure_ascii=False)[:900]
+                   if board_now else "(empty board)"),
         today=today,
+        notes_block=notes_block,
         web_block=web_block,
     )
     msgs = [{"role": "system", "content": system}]
-    for m in (history or [])[-8:]:
-        msgs.append({"role": m["role"], "content": str(m["content"])[:600]})
+    for m in (history or [])[-12:]:
+        msgs.append({"role": m["role"], "content": str(m["content"])[:800]})
     if board_image is not None:
         import tempfile
         tmp = tempfile.NamedTemporaryFile(suffix=".png", delete=False)
@@ -489,7 +549,7 @@ def _decode_board_image(data_url):
 # whole turn must fit in under 60s or logged-out users are rejected outright.
 @spaces.GPU(duration=59)
 def run_turn(audio_path, typed_text, board_snapshot, history, profile,
-             pace, web_on, voice_on):
+             notes, board_now, pace, web_on, voice_on):
     """One full agent turn. Yields event dicts (see module docstring)."""
     t0 = time.time()
     print("[tutori] GPU turn body entered", flush=True)
@@ -513,17 +573,22 @@ def run_turn(audio_path, typed_text, board_snapshot, history, profile,
         web_context = ""
         if web_on:
             yield {"type": "status", "status": "thinking", "detail": "Deciding what context I need…"}
-            queries = decide_search(question, profile)
+            queries = decide_search(question, profile, notes)
             if queries:
                 yield {"type": "status", "status": "searching",
                        "detail": "Researching: " + " · ".join(queries)}
                 web_context = web_research(queries)
+                if web_context:
+                    # carried into later turns so follow-ups can dig deeper
+                    # without searching again
+                    yield {"type": "research", "notes": web_context}
 
         # ---- 3. teach: stream lesson steps, voicing each one ----------
         yield {"type": "status", "status": "teaching", "detail": "Preparing your whiteboard lesson…"}
-        msgs = _build_messages(question, history, profile, pace, web_context, board_image)
+        msgs = _build_messages(question, history, profile, pace, web_context,
+                               board_image, notes=notes or "", board_now=board_now)
         print(f"[tutori] lesson generation starting ({time.time()-t0:.1f}s in)", flush=True)
-        streamer, gen_thread = llm_stream(msgs, max_new_tokens=1000, temperature=0.6)
+        streamer, gen_thread = llm_stream(msgs, max_new_tokens=1000, temperature=0.75)
 
         parser = LessonStreamParser()
         n_steps = 0

mock_engine.py

@@ -56,7 +56,7 @@ def _demo_lesson(topic):
 
 
 def run_turn(audio_path, typed_text, board_snapshot, history, profile,
-             pace, web_on, voice_on):
+             notes, board_now, pace, web_on, voice_on):
     question = (typed_text or "").strip()
     if audio_path:
         yield {"type": "status", "status": "thinking", "detail": "Listening… (mock)"}
@@ -66,10 +66,11 @@ def run_turn(audio_path, typed_text, board_snapshot, history, profile,
     if not question:
         question = "Tell me about what's on the board" if board_snapshot else "Teach me something fun"
 
-    if web_on:
+    if web_on and not notes:
         yield {"type": "status", "status": "searching",
                "detail": f"Researching: {question[:60]} (mock)"}
         time.sleep(0.7)
+        yield {"type": "research", "notes": f"- (mock) background notes about {question[:50]}"}
 
     yield {"type": "status", "status": "teaching", "detail": "Preparing your whiteboard lesson… (mock)"}
     time.sleep(0.6)

static/board.js

@@ -358,11 +358,15 @@
 
     if (step.audio && S.voiceOn) {
       try {
-        const buf = await actx().decodeAudioData(b64ToBuf(step.audio));
-        dur = buf.duration;
-        src = actx().createBufferSource();
-        src.buffer = buf;
-        src.connect(actx().destination);
+        // audio was pre-decoded the moment the step arrived (see enqueue)
+        const buf = step._bufP ? await step._bufP
+                               : await actx().decodeAudioData(b64ToBuf(step.audio));
+        if (buf) {
+          dur = buf.duration;
+          src = actx().createBufferSource();
+          src.buffer = buf;
+          src.connect(actx().destination);
+        }
       } catch (e) { src = null; }
     }
 
@@ -448,9 +452,16 @@
     if (p.status_detail !== undefined) setStatus(p.status_detail, p.status);
     for (const s of (p.steps || [])) {        // incremental: each step carries its index
       const idx = (s.i !== undefined) ? s.i : S.enqueued;
-      if (idx >= S.enqueued) { S.queue.push(s); S.enqueued = idx + 1; }
+      if (idx >= S.enqueued) {
+        if (s.audio && S.voiceOn) {           // decode now, while earlier steps play
+          try { s._bufP = actx().decodeAudioData(b64ToBuf(s.audio)).catch(() => null); }
+          catch (e) { s._bufP = null; }
+        }
+        S.queue.push(s);
+        S.enqueued = idx + 1;
+      }
     }
-    if (S.queue.length) setTimeout(pump, 80);
+    if (S.queue.length) setTimeout(pump, 30);
     if (p.status === "done" || p.status === "error") {
       setTimeout(() => setStatus("", "idle"), p.status === "error" ? 6000 : 1500);
     }