Upload folder using huggingface_hub

README.md

@@ -18,9 +18,89 @@ This Space is only the front desk. It serves the page and signs a short-lived
 LiveKit ticket after a passcode check. It never touches audio and never talks to
 the Pi: the browser and the Pi each dial out to a LiveKit server and meet in a room.
 
+### What runs where
+
+```mermaid
+flowchart TB
+    subgraph B["Browser — laptop or phone, anywhere"]
+        PAGE["Nova page<br/>orb · state · transcript · LLM switch · chime"]
+    end
+
+    subgraph HF["This Space — Hugging Face, Docker"]
+        DESK["POST /api/session<br/>passcode → scrypt check → signed ticket"]
+    end
+
+    subgraph SFU["LiveKit server — self-hosted SFU"]
+        ROOM["room nova-xxxx<br/>relays encrypted audio + data · no AI"]
+    end
+
+    subgraph PI["Raspberry Pi 5 + Hailo NPU — one nova-hailo process"]
+        direction TB
+        WORKER["LiveKit Agents worker<br/>registered as nova-&lt;hostname&gt;"]
+        WAKE["wake word on the caller's audio<br/>openWakeWord · nova_pro_v3"]
+        SESS["AgentSession<br/>Silero VAD · endpointing · interruptions"]
+        STT["Parakeet STT (CPU)"]
+        PIPE["NovaPipeline<br/>router · tools · search · research<br/>LLM: Groq ⇄ Qwen2 on Hailo · Piper TTS"]
+        LAN["/v1/realtime — LAN door<br/>in-car Qt HMI"]
+        LEASE["SessionLease — one conversation at a time"]
+        WORKER --> WAKE --> SESS --> STT --> PIPE
+        LAN --> PIPE
+        LEASE -.- WORKER
+        LEASE -.- LAN
+    end
+
+    PAGE -- "① passcode" --> DESK
+    DESK -- "② url + ticket (10 min)" --> PAGE
+    PAGE <-- "③ WebRTC audio + data" --> ROOM
+    WORKER -. "outbound WSS, always on<br/>(no inbound port on the Pi)" .-> ROOM
+    ROOM -- "④ dispatch to nova-&lt;hostname&gt;" --> WORKER
+    PIPE -- "⑤ Nova's voice (PCM → Opus)" --> ROOM
 ```
-browser ─ passcode ─► this Space ─► ticket (10 min, 1 room, dispatch nova-<pi>)
-   └──── WebRTC ────► LiveKit server ◄──── outbound, always on ──── Pi (all models local)
+
+### Wake word and follow-up
+
+Same contract as the in-car HMI: nothing is transcribed while idle.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle: Nova joins the room
+    Idle --> Listening: "Hey Nova" or tap the orb · chime
+    Listening --> Thinking: you stop talking
+    Thinking --> Speaking: first audio
+    Speaking --> Listening: answer done · follow-up window restarts
+    Speaking --> Listening: you interrupt
+    Listening --> Idle: 5 s of silence (livekit.followup_s)
+```
+
+### One conversation, step by step
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as You (browser)
+    participant S as This Space
+    participant R as LiveKit SFU
+    participant W as Pi worker
+    participant N as NovaPipeline
+
+    Note over W: at boot: registers as nova-<hostname>
+    U->>S: POST /api/session {passcode}
+    S-->>U: url + ticket (1 room, dispatch nova-<hostname>)
+    U->>R: join room, publish mic
+    R->>W: dispatch job
+    W->>W: take SessionLease, or reply "Nova is in use"
+    W->>R: join as agent
+    W-->>U: nova.state idle
+    U->>R: "Hey Nova"
+    R->>W: mic audio (16 kHz copy to the wake word)
+    W-->>U: nova.state listening → chime
+    U->>R: "what's the weather in Chennai?"
+    W->>W: VAD + endpointing → Parakeet → text
+    W->>N: run_text_turn(text)
+    N-->>W: Piper PCM, clause by clause
+    W->>R: Nova's voice + transcript
+    R-->>U: Nova speaks
+    Note over U,W: 5 s of silence → nova.state idle
 ```
 
 ## Setting up a Pi

static/nova.css

@@ -55,3 +55,4 @@ button:focus-visible, input:focus-visible { outline: 2px solid var(--cyan); outl
 .controls { display: flex; align-items: center; gap: var(--u); padding-top: calc(2 * var(--u)); padding-bottom: env(safe-area-inset-bottom, 0px); }
 .metrics { flex: 1; text-align: center; font: 12px "SF Mono", "JetBrains Mono", monospace; color: var(--text-lo); }
 #mute[aria-pressed="true"] { color: var(--yellow); border-color: var(--yellow); }
+#orb { cursor: pointer; }

static/nova.js

@@ -11,7 +11,10 @@
 
   let room = null;
   let agent = null;
-  let chimed = false;
+  // Two sources of state: the Pi's wake gate (idle until "Hey Nova") and
+  // LiveKit's agent state (listening / thinking / speaking).
+  let gate = "idle";
+  let lkState = "listening";
   let llmMode = null;
   let joinTimer = null;
   let analyser = null;
@@ -48,7 +51,17 @@
   }
   function onControl(msg) {
     switch (msg.type) {
-      case "nova.settings": showLlm(msg); break;
+      case "nova.settings":
+        showLlm(msg);
+        if (msg.wake_state) { gate = msg.wake_state; render(); }
+        break;
+      case "nova.state":
+        // idle -> listening is a wake: "Hey Nova", a tap, or (no wake word
+        // configured) the session itself becoming ready. Chime on that edge.
+        if (msg.state === "listening" && gate !== "listening") chime.play().catch(() => {});
+        gate = msg.state;
+        render();
+        break;
       case "nova.llm_status":
         if (msg.status === "loading") { $("llm").disabled = true; $("llm").textContent = "Switching…"; }
         if (msg.status === "error") { say($("live-msg"), `Model switch failed: ${msg.error}`, true); send({ type: "nova.settings.get" }); }
@@ -109,12 +122,15 @@
   }
   function agentState(s) {
     if (!s) return;
-    if (s === "listening" && !chimed) {
-      // Joining is the wake event online: one chime when Nova is first ready.
-      chimed = true;
-      chime.play().catch(() => {});
-    }
-    setState(s === "initializing" ? "connecting" : s);
+    lkState = s;
+    render();
+  }
+  function render() {
+    if (!agent || lkState === "initializing") return setState("connecting");
+    const busy = lkState === "thinking" || lkState === "speaking";
+    // A closed gate shows Idle unless Nova is still talking (e.g. research).
+    setState(gate === "idle" && !busy ? "idle" : lkState);
+    say($("live-msg"), gate === "idle" && !busy ? "Say “Hey Nova” — or tap the orb." : "");
   }
 
   async function connect(passcode) {
@@ -193,7 +209,7 @@
   function hangUp(message = "", bad = false) {
     clearTimeout(joinTimer);
     const r = room;
-    room = null; agent = null; chimed = false; analyser = null;
+    room = null; agent = null; gate = "idle"; lkState = "listening"; analyser = null;
     if (r) r.disconnect();
     document.querySelectorAll("body > audio").forEach((a) => a.remove());
     $("transcript").replaceChildren();
@@ -215,6 +231,8 @@
     connect($("passcode").value);
   });
   $("hangup").addEventListener("click", () => hangUp());
+  // Tap to talk: the same wake event as "Hey Nova", like the HMI's PTT.
+  $("orb").addEventListener("click", () => { if (agent && gate === "idle") send({ type: "nova.wake" }); });
   $("mute").addEventListener("click", async () => {
     if (!room) return;
     const muted = $("mute").getAttribute("aria-pressed") === "true";