deploy: sync GitHub main 07450c9

Deploys 07450c98611aacaa07df903a778fada118aa3c7f.

Co-authored-by: Codex <noreply@openai.com>

AGENTS.md

@@ -79,6 +79,9 @@ tests/                  pytest suite (mirrors module names: test_<module>.py)
 | `data.py` | `ProjectIndex`: loads the snapshot + embedding index, `_embed_query()` via llama.cpp, cosine search. |
 | `llama_embedding.py` | `LlamaCppEmbedder` — EmbeddingGemma GGUF through llama-cpp-python (the Llama Champion path). |
 | `dashboard.py` / `dashboard_storage.py` / `dashboard_search.py` | Atlas payload (t-SNE / KMeans / nearest links), BM25 search, and the refresh **lease + heartbeat + atomic `latest.json` swap**. |
+| `dashboard_repository.py` | `DashboardRepository`: read-only queries (overview, clusters, quests, leaderboard, search, recent) over one snapshot of `(dashboard_payload, search_index)`; no locks, no globals, plain dicts. |
+| `dashboard_chat_contracts.py` | Atlas-chat tool specs (8 tools), `parse_native_tool_call()` for MiniCPM5's native `<function><param>` format, and the chat degradation ladder (`resolve_chat_tool_call` / `data_intent_call`). |
+| `dashboard_chat.py` | `DashboardChatEngine.turn_stream()`: native two-pass loop on the **base** model with `enable_thinking` — reasoning streams as `thinking` events (split from content at `</think>`, which is NOT a special token), then tool pick (tools= injected) → repository execution → `tool_result` + `map_action` events **before** prose → grounded answer from a compact line-format digest (no history in pass 2: echo bait). 4096-token budget per generation; empty results skip pass 2 for a templated sentence. |
 | `quest_analysis.py` / `quest_taxonomy.py` / `quest_cache.py` | MiniCPM quest LoRA → strict quest JSON; the taxonomy; per-project cache keyed on prompt/taxonomy/model/adapter hashes. |
 | `scoring.py` | Deterministic idea rubric (the model only triggers + verbalizes it). |
 | `wood_map.py` / `png_export.py` | PCA projection + Pillow render of the shareable page PNG. |
@@ -97,6 +100,7 @@ First-party FastAPI routes power the visible app; `@app.api()` endpoints stay av
 | `POST /api/agent-turn` | The advisor turn — **NDJSON stream**; this is the `@spaces.GPU` boundary |
 | `POST /api/transcribe` | Voice note → transcript (NeMo, see ASR gotcha) |
 | `GET /api/dashboard` · `GET /api/dashboard/search` | Atlas payload · BM25 search |
+| `POST /api/dashboard/chat` | Atlas chat turn — **NDJSON stream** (base MiniCPM5-1B, native tool calling, two-pass) |
 | `POST/GET /api/dashboard/refresh` | Start / poll one background refresh job |
 | `GET /api/bootstrap` · `GET /api/runtime` · `GET /api/prize-ledger` · `GET /api/tool-contracts` | Frontend bootstrap, runtime status, prize ledger, tool schema |
 | `GET /api/demo-bundle.zip` · `GET /api/lora-training-kit.zip` · `POST /api/artifact.png` · `POST /api/field-notes` · `POST /api/chapter` | Exports |
@@ -124,6 +128,13 @@ First-party FastAPI routes power the visible app; `@app.api()` endpoints stay av
    weights. Don't add module-top heavy imports that break CPU-only test collection.
 8. **ASR backend.** `asr_runtime.py` requires NVIDIA NeMo ASR for `nvidia/nemotron-speech-streaming-en-0.6b`; missing
    NeMo is a hard runtime error, locally and on the deployed Space. `status()` reports the configured Nemotron backend.
+9. **The atlas chat shares the advisor's model — never load a second MiniCPM.** `create_chat_runner(engine.planner)`
+   borrows the loaded PeftModel and runs chat generations inside `base_model_context()` (PEFT `disable_adapter()`), so
+   the chat speaks with BASE weights. Adapter toggling mutates shared model state, so **every** generation (advisor and
+   chat) goes through `_stream_minicpm_generation`, which holds the module-level `generation_lock()` for the full
+   streamer-worker lifetime. Gotcha 1 still binds the advisor; the chat's two-pass model-written answers are a
+   deliberate, separately guarded exception (verified cards always render from the real tool result, and empty results
+   skip the model entirely).
 
 ---
 

README.md

@@ -68,6 +68,10 @@ export the session evidence.
   text, and declared app-file source.
 - Filter by cluster or quest, then inspect the selected project's summary, Space link, tags, quest matches, and evidence
   hints.
+- Chat with the atlas: the "Ask the atlas" drawer answers questions like "who completed the most quests" or "what
+  clusters exist" through the BASE MiniCPM5-1B model's native tool calling, with thinking enabled — the reasoning
+  trace streams live into a collapsible block. Verified tool results render as cards and can filter or highlight the
+  map directly; the model's prose is grounded on a compact digest of the same result.
 - Refresh the atlas from the Space backend; validated artifacts are written to the mounted cache directory and swapped
   into the live app atomically.
 - Open the advisor workspace for idea comparison, gap exploration, score seals, profile-aware plans, voice input, and
@@ -212,6 +216,7 @@ credentials.
 | --- | --- |
 | `GET /api/dashboard` | Atlas points, links, clusters, quest report, provenance, and refresh status. |
 | `GET /api/dashboard/search?q=...` | BM25 search over project, cluster, quest, README, and app-file text. |
+| `POST /api/dashboard/chat` | Atlas chat turn (NDJSON stream): base-model tool call, verified result + map action, grounded answer. |
 | `POST /api/dashboard/refresh` | Starts one background refresh job. |
 | `GET /api/dashboard/refresh` | Reports refresh stage, result, and status. |
 | `POST /api/transcribe` | Transcribes uploaded voice notes with NVIDIA NeMo and Nemotron ASR. |

app.py

@@ -44,8 +44,10 @@ from hackathon_advisor.data import (
     ProjectIndex,
     normalize_project_tags,
 )
+from hackathon_advisor.dashboard_chat import DashboardChatEngine
+from hackathon_advisor.dashboard_repository import DashboardRepository
 from hackathon_advisor.demo_rehearsal import build_demo_rehearsal
-from hackathon_advisor.model_runtime import create_tool_planner
+from hackathon_advisor.model_runtime import create_chat_runner, create_tool_planner
 from hackathon_advisor.profiling import (
     TurnProfiler,
     configure_logging,
@@ -136,7 +138,22 @@ engine = AdvisorEngine(index, create_tool_planner(device=gpu_device()))
 voice_transcriber = create_asr_transcriber()
 app = Server()
 
+
+def _current_dashboard_repository() -> DashboardRepository:
+    """Snapshot the swapped globals under the lock, build the repository outside it."""
+    with _runtime_lock:
+        payload = dashboard_payload
+        search_index = dashboard_search_index
+    return DashboardRepository(payload, search_index)
+
+
+# The atlas chat shares the advisor's model (BASE weights via adapter-off generations);
+# create_chat_runner never loads a second copy. The planner reference survives refresh
+# swaps because _replace_runtime_from_files reuses engine.planner.
+chat_engine = DashboardChatEngine(create_chat_runner(engine.planner), _current_dashboard_repository)
+
 _cpu_engine: AdvisorEngine | None = None
+_cpu_chat_engine: DashboardChatEngine | None = None
 _refresh_state: dict[str, Any] = {
     "status": "idle",
     "run_id": "",
@@ -166,11 +183,28 @@ def _cpu_engine_instance() -> AdvisorEngine:
     return _cpu_engine
 
 
+def _cpu_chat_engine_instance() -> DashboardChatEngine:
+    """CPU-pinned atlas chat used for the explicit CPU override and the ZeroGPU-quota
+    fallback. Shares the CPU advisor engine's model, mirroring _cpu_engine_instance()."""
+    global _cpu_chat_engine
+    if _cpu_chat_engine is None:
+        _cpu_chat_engine = DashboardChatEngine(
+            create_chat_runner(_cpu_engine_instance().planner),
+            _current_dashboard_repository,
+        )
+    return _cpu_chat_engine
+
+
 @gpu_task
 def _engine_turn_stream_gpu(message: str, session: dict[str, Any]) -> Iterator[dict[str, Any]]:
     yield from engine.turn_stream(message, session)
 
 
+@gpu_task
+def _chat_turn_stream_gpu(message: str, history: list[dict[str, Any]]) -> Iterator[dict[str, Any]]:
+    yield from chat_engine.turn_stream(message, history)
+
+
 @gpu_task
 def _transcribe_voice(audio_path: str) -> dict[str, Any]:
     return voice_transcriber.transcribe(Path(audio_path)).to_dict()
@@ -883,6 +917,70 @@ def _profiled_turn_events(
         yield event
 
 
+def _history_from_json(history_json: str = "[]") -> list[dict[str, Any]]:
+    try:
+        history = json.loads(history_json or "[]")
+    except json.JSONDecodeError:
+        return []
+    return history if isinstance(history, list) else []
+
+
+def _primary_chat_stream(message: str, history: list[dict[str, Any]]) -> Iterator[dict[str, Any]]:
+    if zero_gpu_enabled():
+        yield from _chat_turn_stream_gpu(message, history)
+    else:
+        yield from chat_engine.turn_stream(message, history)
+
+
+def _chat_turn_events(
+    message: str,
+    history_json: str = "[]",
+    compute: str = "gpu",
+) -> Iterator[str]:
+    profiler = TurnProfiler(
+        message_index=next_message_index(),
+        compute=compute,
+        backend=str(getattr(chat_engine.runner, "backend", "")),
+        message_chars=len(message),
+    )
+    profiler.log_start()
+    try:
+        for event in _profiled_chat_events(message, history_json, compute):
+            profiler.observe(event)
+            yield _json_event(event)
+        profiler.device = _active_device(compute)
+        profiler.log_summary()
+    except Exception as error:  # noqa: BLE001 - log timing/resources even when a turn fails
+        profiler.device = _active_device(compute)
+        profiler.log_summary(error)
+        raise
+
+
+def _profiled_chat_events(
+    message: str,
+    history_json: str,
+    compute: str,
+) -> Iterator[dict[str, Any]]:
+    history = _history_from_json(history_json)
+    if compute != "cpu":
+        produced = False
+        try:
+            for event in _primary_chat_stream(message, history):
+                produced = True
+                yield event
+            return
+        except Exception as error:  # noqa: BLE001 - fall back to local on a clean quota failure
+            if produced or not is_gpu_quota_error(error):
+                raise
+            yield {
+                "type": "fallback",
+                "to": "cpu",
+                "reason": "ZeroGPU quota reached — running this turn locally (slower).",
+            }
+
+    yield from _cpu_chat_engine_instance().turn_stream(message, history)
+
+
 @app.get("/", response_class=HTMLResponse)
 def home() -> FileResponse:
     return FileResponse(STATIC_DIR / "index.html")
@@ -1137,6 +1235,22 @@ def agent_turn_stream(payload: dict[str, Any] | None = Body(default=None)) -> St
     return StreamingResponse(stream(), media_type="application/x-ndjson")
 
 
+@app.post("/api/dashboard/chat")
+def dashboard_chat_stream(payload: dict[str, Any] | None = Body(default=None)) -> StreamingResponse:
+    payload = payload or {}
+    message = str(payload.get("message") or "").strip()
+    if not message:
+        raise HTTPException(status_code=400, detail="Chat message is required.")
+    history_json = str(payload.get("history_json") or "[]")
+    compute = _normalize_compute(payload.get("compute"))
+
+    def stream() -> Iterator[str]:
+        for event in _chat_turn_events(message, history_json, compute):
+            yield f"{event}\n"
+
+    return StreamingResponse(stream(), media_type="application/x-ndjson")
+
+
 def _normalize_compute(value: Any) -> str:
     # Acceleration is automatic; "cpu" is the only manual override (not surfaced in the UI).
     return "cpu" if str(value or "").strip().lower() == "cpu" else "gpu"
@@ -1288,6 +1402,11 @@ def agent_turn(message: str, session_json: str = "{}", compute: str = "gpu") ->
     yield from _agent_turn_events(message, session_json, _normalize_compute(compute))
 
 
+@app.api(name="dashboard_chat", concurrency_limit=4, stream_every=0.04)
+def dashboard_chat(message: str, history_json: str = "[]", compute: str = "gpu") -> Iterator[str]:
+    yield from _chat_turn_events(message, history_json, _normalize_compute(compute))
+
+
 _start_scheduled_refresh_loop()
 
 

hackathon_advisor/dashboard_chat.py

@@ -0,0 +1,643 @@
+"""The atlas chat engine: a two-pass, tool-grounded conversation over the idea map.
+
+Flow per turn (the native MiniCPM5 tool protocol, run on the BASE model):
+
+1. *Pass 1* — the model sees the chat history plus the tool schemas (injected by the
+   chat template via ``tools=``) and either calls one tool or answers plain prose.
+2. The call is validated and degraded through the chat-specific ladder
+   (``resolve_chat_tool_call``), then executed against a fresh
+   :class:`~hackathon_advisor.dashboard_repository.DashboardRepository` snapshot.
+3. The full verified result streams to the UI *first* (``tool_result`` + optional
+   ``map_action``) so cards and the map always carry the real numbers.
+4. *Pass 2* — a compact digest (urls/ids/scores stripped, so the model cannot
+   misquote what it never saw) goes back as a ``role:"tool"`` message and the model
+   writes a short grounded answer at temperature 0 with NO tools injected.
+   Empty results skip pass 2 entirely: a 1B narrating absent data is where it
+   hallucinates, so those turns get a deterministic templated sentence instead.
+
+The engine is UI- and app-agnostic: it depends only on a ChatRunner and a
+repository factory, and every yielded event is a JSON-serializable dict.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+import re
+from typing import Any
+
+from hackathon_advisor._text import clean
+from hackathon_advisor.aliases import normalize_text
+from hackathon_advisor.dashboard_chat_contracts import (
+    ChatToolResolution,
+    chat_tool_schemas,
+    data_intent_call,
+    resolve_chat_tool_call,
+    smalltalk_intent,
+    strip_function_blocks,
+)
+from hackathon_advisor.dashboard_repository import DashboardRepository
+from hackathon_advisor.model_runtime import ChatRunner
+from hackathon_advisor.tool_contracts import ToolCall
+
+# One generous budget for every chat generation: with thinking enabled the model
+# reasons inside <think>...</think> before the tool call / answer, and the trace
+# alone can run long. The model stops at EOS well before the cap on normal turns.
+MAX_CHAT_GENERATION_TOKENS = 4096
+MAX_HISTORY_MESSAGES = 12  # six user/assistant turns
+MAX_ANSWER_HISTORY_MESSAGES = 4  # two turns of context for the prose passes
+MAX_HISTORY_MESSAGE_CHARS = 600
+
+CHAT_PLANNING_PROMPT = (
+    "You are the Atlas Guide for the Build Small hackathon idea map. "
+    "You cannot see the atlas directly: the ONLY way to answer a question about projects, "
+    "clusters, quests, teams, or recent activity is to call one of the provided tools, which "
+    "read the live atlas. For any such question respond with exactly one tool call and no "
+    'other text, for example: <function name="search_projects"><param name="query">voice'
+    "</param></function>. Reply in plain prose only for greetings or questions about yourself."
+)
+
+CHAT_ANSWER_PROMPT = (
+    "You are the Atlas Guide for the Build Small hackathon idea map. "
+    "Write a short conversational answer to the user's question using ONLY the facts in the "
+    "tool response. Quote counts and names exactly as given. Do not invent projects, numbers, "
+    "or links. Do not enumerate every item: summarize, naming at most three examples. "
+    "Two to four sentences, no lists, no markdown."
+)
+
+CHAT_SMALLTALK_PROMPT = (
+    "You are the Atlas Guide for the Build Small hackathon idea map. "
+    "Reply briefly and warmly. You have NO project data in this conversation: never state "
+    "project names, counts, likes, or rankings, and do not defend earlier numbers — if asked "
+    "about data, say you should look it up and suggest asking what everyone is building, "
+    "which projects completed the most quests, or what clusters exist. One or two sentences."
+)
+
+# Keys stripped from the model-facing digest. The UI renders links and ids from the
+# verified payload; the model only needs labels, titles, and counts.
+_DIGEST_DROPPED_KEYS = frozenset({"url", "id", "score", "host", "quest_ids"})
+
+# A trailing fragment of "<function" left by a max_new_tokens cut mid-marker.
+_PARTIAL_TAG_RE = re.compile(r"<[a-z]{0,8}$")
+
+THINK_END_MARKER = "</think>"
+
+
+class _ThinkSplitter:
+    """Incrementally split a thinking-mode stream into (kind, text) chunks.
+
+    With ``enable_thinking`` the chat template ends the prompt with ``<think>\\n``,
+    so the generation is reasoning text up to ``</think>`` followed by the real
+    content. The marker can arrive split across stream pieces, so a small tail
+    buffer is kept until it can no longer be a marker prefix. When the runner does
+    not think (rules backend) every piece passes straight through as answer text."""
+
+    def __init__(self, active: bool) -> None:
+        self._thinking = bool(active)
+        self._buffer = ""
+
+    def feed(self, piece: str) -> list[tuple[str, str]]:
+        if not self._thinking:
+            return [("answer", piece)] if piece else []
+        self._buffer += piece
+        marker = self._buffer.find(THINK_END_MARKER)
+        if marker >= 0:
+            thought = self._buffer[:marker]
+            rest = self._buffer[marker + len(THINK_END_MARKER) :].lstrip("\n")
+            self._buffer = ""
+            self._thinking = False
+            chunks: list[tuple[str, str]] = []
+            if thought:
+                chunks.append(("thinking", thought))
+            if rest:
+                chunks.append(("answer", rest))
+            return chunks
+        keep = _marker_prefix_length(self._buffer)
+        flush, self._buffer = (
+            self._buffer[: len(self._buffer) - keep],
+            self._buffer[len(self._buffer) - keep :],
+        )
+        return [("thinking", flush)] if flush else []
+
+    def finish(self) -> list[tuple[str, str]]:
+        """Flush the tail when the stream ends mid-thought (max_new_tokens cut)."""
+        if self._thinking and self._buffer:
+            tail, self._buffer = self._buffer, ""
+            return [("thinking", tail)]
+        return []
+
+
+def _marker_prefix_length(text: str) -> int:
+    for length in range(min(len(text), len(THINK_END_MARKER) - 1), 0, -1):
+        if THINK_END_MARKER.startswith(text[-length:]):
+            return length
+    return 0
+
+
+class DashboardChatEngine:
+    def __init__(
+        self,
+        runner: ChatRunner,
+        repository_factory: Callable[[], DashboardRepository],
+    ) -> None:
+        self.runner = runner
+        self.repository_factory = repository_factory
+
+    def turn_stream(
+        self,
+        message: str,
+        history: list[dict[str, Any]] | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        history = _normalize_history(history)
+        normalized, corrections = normalize_text(message)
+        yield {
+            "type": "start",
+            "normalized_text": normalized,
+            "corrections": [correction.to_dict() for correction in corrections],
+        }
+        repository = self.repository_factory()
+
+        yield {"type": "stage", "stage": "planning", "label": "Reading the atlas"}
+        resolution, raw_output = yield from self._pick_tool(normalized, history)
+        if resolution.status == "none":
+            # Accuracy backstop: when the model answers in prose (declining its tools),
+            # route any substantive question to a tool — a matched intent first, BM25
+            # search otherwise. Only greetings/meta/short follow-ups may stay on the
+            # ungrounded small-talk path; this is a data surface, and letting a question
+            # like "how many voice apps" through is how invented facts reach the user.
+            intent = data_intent_call(normalized)
+            if intent is None and not smalltalk_intent(normalized):
+                intent = ToolCall("search_projects", {"query": normalized})
+            if intent is not None:
+                resolution = ChatToolResolution(
+                    status="defaulted",
+                    call=intent,
+                    errors=("model answered without a tool; routed by intent",),
+                )
+        yield {
+            "type": "tool_call",
+            "name": resolution.call.name if resolution.call else "",
+            "arguments": resolution.call.arguments if resolution.call else {},
+            "status": resolution.status,
+            "errors": list(resolution.errors),
+        }
+
+        if resolution.status == "none":
+            response = yield from self._smalltalk(normalized, history, raw_output)
+            yield self._done(normalized, history, response, tool="", data={}, map_action=None)
+            return
+
+        call = resolution.call
+        assert call is not None
+        yield {
+            "type": "stage",
+            "stage": "running_tool",
+            "tool": call.name,
+            "label": f"Calling {call.name}",
+        }
+        # _execute may swap the tool (show_project falls back to search when no
+        # project matches), so the executed name drives rendering from here on.
+        tool_name, data, map_action, empty_reason = self._execute(call, repository)
+        yield {"type": "tool_result", "tool": tool_name, "data": data, "map_action": map_action}
+
+        if empty_reason:
+            response = _templated_sentence(call, data, empty_reason)
+            yield {"type": "answer_skipped", "reason": empty_reason, "text": response}
+        else:
+            yield {"type": "stage", "stage": "writing", "label": "Writing the answer"}
+            executed = ToolCall(tool_name, call.arguments)
+            response = yield from self._grounded_answer(normalized, history, executed, data)
+            if not response:
+                response = _templated_sentence(call, data, "empty_answer")
+                yield {"type": "answer_skipped", "reason": "empty_answer", "text": response}
+
+        yield self._done(
+            normalized, history, response, tool=tool_name, data=data, map_action=map_action
+        )
+
+    def _pick_tool(
+        self,
+        message: str,
+        history: list[dict[str, Any]],
+    ) -> Iterator[dict[str, Any]]:
+        messages = [
+            {"role": "system", "content": CHAT_PLANNING_PROMPT},
+            *history,
+            {"role": "user", "content": message},
+        ]
+        splitter = _ThinkSplitter(getattr(self.runner, "supports_thinking", False))
+        answer_pieces: list[str] = []
+        for count, piece in self.runner.stream(
+            messages,
+            tools=chat_tool_schemas(),
+            max_new_tokens=MAX_CHAT_GENERATION_TOKENS,
+            enable_thinking=True,
+        ):
+            for kind, text in splitter.feed(piece):
+                if kind == "thinking":
+                    yield {"type": "thinking", "pass": 1, "text": text}
+                else:
+                    answer_pieces.append(text)
+            yield {
+                "type": "model_progress",
+                "pass": 1,
+                "tokens": count,
+                "max_tokens": MAX_CHAT_GENERATION_TOKENS,
+            }
+        for _kind, text in splitter.finish():
+            yield {"type": "thinking", "pass": 1, "text": text}
+        # Only the post-thinking text may be parsed: the reasoning trace legitimately
+        # talks about <function ...> syntax without being a call.
+        raw_output = "".join(answer_pieces).strip()
+        return resolve_chat_tool_call(raw_output, fallback_query=message), raw_output
+
+    def _smalltalk(
+        self,
+        message: str,
+        history: list[dict[str, Any]],
+        raw_output: str,
+    ) -> Iterator[dict[str, Any]]:
+        """Dedicated no-tools generation: the pass-1 output is tuned for tool
+        selection, not for a satisfying greeting, so chit-chat gets its own pass."""
+        yield {"type": "stage", "stage": "writing", "label": "Writing the answer"}
+        messages = [
+            {"role": "system", "content": CHAT_SMALLTALK_PROMPT},
+            *_answer_history(history),
+            {"role": "user", "content": message},
+        ]
+        response = yield from self._stream_prose(messages, MAX_CHAT_GENERATION_TOKENS)
+        if not response:
+            response = strip_function_blocks(raw_output) or (
+                "Hello! Ask me what everyone is building, which projects completed the most "
+                "quests, or what clusters exist."
+            )
+            yield {"type": "answer_skipped", "reason": "empty_answer", "text": response}
+        return response
+
+    def _grounded_answer(
+        self,
+        message: str,
+        history: list[dict[str, Any]],
+        call: ToolCall,
+        data: dict[str, Any],
+    ) -> Iterator[dict[str, Any]]:
+        digest = render_digest(_digest_for_model(call.name, data))
+        # NO history here: every fact the answer needs is in the digest, and a greedy
+        # 1B echoes similar-sounding lines from prior turns over the digest in front
+        # of it. Conversation context only matters for pass-1's tool choice.
+        messages = [
+            {"role": "system", "content": CHAT_ANSWER_PROMPT},
+            {"role": "user", "content": message},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [{"name": call.name, "arguments": call.arguments}],
+            },
+            {"role": "tool", "content": digest},
+        ]
+        return (yield from self._stream_prose(messages, MAX_CHAT_GENERATION_TOKENS))
+
+    def _stream_prose(
+        self,
+        messages: list[dict[str, Any]],
+        max_new_tokens: int,
+    ) -> Iterator[dict[str, Any]]:
+        """Stream a no-tools generation as thinking + token events; returns the prose.
+
+        The reasoning trace streams as ``thinking`` events; only the post-think text
+        becomes the answer. If a stray ``<function`` shows up in the answer the stream
+        stops early; the ``done`` response carries the stripped text, which the UI
+        treats as authoritative."""
+        splitter = _ThinkSplitter(getattr(self.runner, "supports_thinking", False))
+        pieces: list[str] = []
+        stream = self.runner.stream(messages, max_new_tokens=max_new_tokens, enable_thinking=True)
+        stray_function = False
+        try:
+            for count, piece in stream:
+                for kind, text in splitter.feed(piece):
+                    if kind == "thinking":
+                        yield {"type": "thinking", "pass": 2, "text": text}
+                        continue
+                    pieces.append(text)
+                    if "<function" in "".join(pieces[-4:]):
+                        stray_function = True
+                        break
+                    yield {"type": "token", "text": text}
+                if stray_function:
+                    break
+                yield {
+                    "type": "model_progress",
+                    "pass": 2,
+                    "tokens": count,
+                    "max_tokens": max_new_tokens,
+                }
+        finally:
+            close = getattr(stream, "close", None)
+            if close is not None:
+                close()
+        for _kind, text in splitter.finish():
+            yield {"type": "thinking", "pass": 2, "text": text}
+        text = "".join(pieces)
+        marker = text.find("<function")
+        if marker >= 0:
+            text = text[:marker]
+        # A generation cut at max_new_tokens can end mid-marker ("<fun"); drop any
+        # trailing partial tag so it never reaches the authoritative response.
+        text = _PARTIAL_TAG_RE.sub("", text)
+        return clean(strip_function_blocks(text))
+
+    def _execute(
+        self,
+        call: ToolCall,
+        repository: DashboardRepository,
+    ) -> tuple[str, dict[str, Any], dict[str, Any] | None, str]:
+        """Run one validated tool; returns (executed tool, data, map action, empty reason)."""
+        name = call.name
+        if name == "atlas_overview":
+            data = repository.overview()
+            return name, data, {"type": "clear_filters"}, ""
+        if name == "list_clusters":
+            data = repository.list_clusters()
+            return name, data, None, "" if data["clusters"] else "no_clusters"
+        if name == "show_cluster":
+            label = clean(call.arguments.get("label"))
+            detail = repository.cluster_detail(label)
+            if detail is None:
+                return name, {"requested_label": label}, None, "unknown_cluster"
+            return name, detail, {"type": "filter_cluster", "label": detail["label"]}, ""
+        if name == "list_quests":
+            data = repository.list_quests()
+            if data["status"] != "analyzed":
+                return name, data, None, "quests_not_analyzed"
+            return name, data, None, ""
+        if name == "show_quest":
+            quest = clean(call.arguments.get("quest"))
+            detail = repository.quest_detail(quest)
+            if detail is None:
+                return name, {"requested_quest": quest}, None, "unknown_quest"
+            if detail["status"] != "analyzed":
+                return name, detail, None, "quests_not_analyzed"
+            map_action = {"type": "filter_quest", "quest": detail["id"]}
+            if detail["project_count"] == 0:
+                return name, detail, map_action, "quest_no_projects"
+            return name, detail, map_action, ""
+        if name == "show_project":
+            requested = clean(call.arguments.get("project"))
+            detail = repository.project_detail(requested)
+            if detail is None:
+                # Half-remembered names still get useful cards: fall back to search.
+                return self._search(repository, requested)
+            return name, detail, {"type": "highlight_projects", "ids": [detail["id"]]}, ""
+        if name == "top_projects_by_quests":
+            data = repository.top_by_quests()
+            if data["status"] != "analyzed":
+                return name, data, None, "quests_not_analyzed"
+            if not data["rows"]:
+                return name, data, None, "no_leaderboard_rows"
+            ids = [row["id"] for row in data["rows"]]
+            return name, data, {"type": "highlight_projects", "ids": ids}, ""
+        if name == "search_projects":
+            return self._search(repository, clean(call.arguments.get("query")))
+        if name == "recent_activity":
+            data = repository.recent_activity()
+            if not data["projects"]:
+                return name, data, None, "no_projects"
+            ids = [project["id"] for project in data["projects"]]
+            return name, data, {"type": "highlight_projects", "ids": ids}, ""
+        # Unreachable for validated calls; degrade to a safe overview.
+        return "atlas_overview", repository.overview(), None, ""
+
+    def _search(
+        self,
+        repository: DashboardRepository,
+        query: str,
+    ) -> tuple[str, dict[str, Any], dict[str, Any] | None, str]:
+        data = repository.search(query)
+        if not data["results"]:
+            return "search_projects", data, None, "no_search_results"
+        ids = [result["id"] for result in data["results"]]
+        return (
+            "search_projects",
+            data,
+            {"type": "highlight_projects", "ids": ids, "query": query},
+            "",
+        )
+
+    def _done(
+        self,
+        message: str,
+        history: list[dict[str, Any]],
+        response: str,
+        *,
+        tool: str,
+        data: dict[str, Any],
+        map_action: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        new_history = [
+            *history,
+            {"role": "user", "content": message},
+            {"role": "assistant", "content": response},
+        ]
+        return {
+            "type": "done",
+            "response": response,
+            "tool": tool,
+            "data": data,
+            "map_action": map_action,
+            "history": _normalize_history(new_history),
+        }
+
+
+def _normalize_history(history: Any) -> list[dict[str, Any]]:
+    """Keep only well-formed prior prose turns, clipped, deduplicated, and capped.
+
+    Tool digests are deliberately dropped from history: stale counts must never
+    leak into a later answer — every turn re-reads a fresh repository snapshot.
+    Repeated assistant sentences are collapsed too: a greedy 1B that sees the
+    same line twice in history will echo it a third time regardless of the
+    digest in front of it."""
+    if not isinstance(history, list):
+        return []
+    cleaned: list[dict[str, Any]] = []
+    for item in history:
+        if not isinstance(item, dict):
+            continue
+        role = str(item.get("role") or "")
+        content = clean(item.get("content"))
+        if role not in ("user", "assistant") or not content:
+            continue
+        cleaned.append({"role": role, "content": content[:MAX_HISTORY_MESSAGE_CHARS]})
+    return _dedupe_assistant_echoes(cleaned)[-MAX_HISTORY_MESSAGES:]
+
+
+def _dedupe_assistant_echoes(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Collapse consecutive identical assistant answers, keeping the NEWEST turn.
+
+    Walks backwards so the latest user/assistant pair always survives; the older
+    repeats (and the user turns that elicited them) are dropped."""
+    deduped_reversed: list[dict[str, Any]] = []
+    previous_assistant = None
+    skip_next_user = False
+    for item in reversed(messages):
+        if item["role"] == "assistant":
+            if item["content"] == previous_assistant:
+                skip_next_user = True
+                continue
+            previous_assistant = item["content"]
+            deduped_reversed.append(item)
+        else:
+            if skip_next_user:
+                skip_next_user = False
+                continue
+            deduped_reversed.append(item)
+    return list(reversed(deduped_reversed))
+
+
+def _answer_history(history: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """The short tail of history given to answer generations.
+
+    Facts come from the digest, not from history; the prose passes only need
+    enough context for follow-ups, and a longer tail mostly adds echo bait."""
+    return history[-MAX_ANSWER_HISTORY_MESSAGES:]
+
+
+def _digest_for_model(tool: str, data: dict[str, Any]) -> Any:
+    """Compact the verified payload into what the model may safely restate.
+
+    Beyond stripping urls/ids/scores, long listings are trimmed per tool: a 1B asked
+    to repeat ten labels starts blending them, so it only sees the few it may name.
+    The UI renders the FULL verified payload independently."""
+    trimmed: dict[str, Any] = dict(data)
+    if tool == "atlas_overview":
+        # Self-describing keys, most-liked first: with three lists in one digest a 1B
+        # answering "what's the coolest project" otherwise grabs the wrong column.
+        trimmed = {
+            "most_liked_projects": data.get("most_liked"),
+            "project_count": data.get("project_count"),
+            "cluster_count": data.get("cluster_count"),
+            "largest_clusters": data.get("top_clusters"),
+            "most_completed_quests": data.get("top_quests"),
+            "quest_status": data.get("quest_status"),
+        }
+    if tool == "list_clusters":
+        # Ten compound labels is past what a 1B can restate without blending them;
+        # it gets the count and the largest cluster, the cards carry the full list.
+        clusters = data.get("clusters") or []
+        trimmed = {
+            "cluster_count": data.get("cluster_count"),
+            "largest_cluster": clusters[0] if clusters else None,
+            "note": "the full cluster list is already shown to the user as cards",
+        }
+    if tool == "list_quests":
+        quests = data.get("quests") or []
+        trimmed = {
+            "status": data.get("status"),
+            "quest_count": len(quests),
+            "most_completed_quest": quests[0] if quests else None,
+            "note": "the full quest list is already shown to the user as cards",
+        }
+    if tool == "show_cluster":
+        trimmed["examples"] = (data.get("examples") or [])[:3]
+    if tool == "show_quest":
+        trimmed["examples"] = (data.get("examples") or [])[:3]
+    if tool == "search_projects":
+        # BM25 "total" counts any term overlap; quoting it as "N projects about X"
+        # would mislead, so the model only sees the close matches themselves.
+        trimmed.pop("total", None)
+    return _strip_digest_keys(trimmed)
+
+
+def _strip_digest_keys(data: Any) -> Any:
+    if isinstance(data, dict):
+        return {
+            key: _strip_digest_keys(value)
+            for key, value in data.items()
+            if key not in _DIGEST_DROPPED_KEYS
+        }
+    if isinstance(data, list):
+        return [_strip_digest_keys(item) for item in data]
+    return data
+
+
+def render_digest(data: Any, indent: int = 0) -> str:
+    """Render the digest as plain ``key: value`` lines instead of JSON.
+
+    A 1B model copying labels out of nested JSON starts blending adjacent strings;
+    one fact per line keeps its quotes literal."""
+    return "\n".join(_digest_lines(data, indent))
+
+
+def _digest_lines(value: Any, indent: int) -> list[str]:
+    pad = "  " * indent
+    if isinstance(value, dict):
+        lines: list[str] = []
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                lines.append(f"{pad}{key}:")
+                lines.extend(_digest_lines(item, indent + 1))
+            else:
+                lines.append(f"{pad}{key}: {_digest_value(item)}")
+        return lines
+    if isinstance(value, list):
+        lines = []
+        for item in value:
+            if isinstance(item, dict):
+                flat = ", ".join(
+                    f"{key}: {_digest_value(entry)}"
+                    for key, entry in item.items()
+                    if not isinstance(entry, (dict, list))
+                )
+                lines.append(f"{pad}- {flat}")
+            else:
+                lines.append(f"{pad}- {_digest_value(item)}")
+        return lines
+    return [f"{pad}{_digest_value(value)}"]
+
+
+def _digest_value(value: Any) -> Any:
+    # Quote strings so compound labels like "Dream / Oracle" keep hard copy
+    # boundaries — a greedy 1B blends adjacent unquoted multi-word labels.
+    if isinstance(value, str):
+        return f'"{value}"'
+    return value
+
+
+def _templated_sentence(call: ToolCall, data: dict[str, Any], reason: str) -> str:
+    """Deterministic sentences for the turns where the model must not improvise."""
+    if reason == "quests_not_analyzed":
+        return (
+            "Quest analysis has not run for this snapshot yet, so quest coverage is empty. "
+            "Refresh the map to classify the field, or ask about clusters and projects instead."
+        )
+    if reason == "unknown_cluster":
+        requested = clean(data.get("requested_label")) or "that name"
+        return (
+            f"I could not find a cluster matching {requested} in the current snapshot. "
+            "Ask me to list the clusters to see the live labels."
+        )
+    if reason == "unknown_quest":
+        requested = clean(data.get("requested_quest")) or "that name"
+        return (
+            f"I could not match {requested} to a hackathon quest. "
+            "Ask me to list the quests to see the official names."
+        )
+    if reason == "quest_no_projects":
+        label = clean(data.get("label"))
+        if label:
+            return f"No project in the current snapshot has completed {label} yet."
+        return "No project in the current snapshot has completed that quest yet."
+    if reason == "no_leaderboard_rows":
+        return (
+            "Quest analysis ran, but no project in the current snapshot has completed a "
+            "quest yet — the leaderboard is empty."
+        )
+    if reason == "no_search_results":
+        query = clean(data.get("query")) or "that"
+        return (
+            f"The atlas has no match for {query}. "
+            "That can be good news for originality — try a broader term to double-check."
+        )
+    if reason == "no_clusters" or reason == "no_projects":
+        return "The current snapshot has no data for that yet. Try refreshing the map."
+    if reason == "empty_answer":
+        return "The verified results are on the cards below."
+    return "The verified results are on the cards below."

hackathon_advisor/dashboard_chat_contracts.py

@@ -0,0 +1,299 @@
+"""Tool contracts for the atlas chat: native MiniCPM5 format, chat-specific fallback.
+
+The dashboard chat drives the BASE MiniCPM5-1B model through its native
+tool-calling protocol: tool JSON schemas go in via ``apply_chat_template(...,
+tools=...)`` and the model answers either with plain prose (no tool needed) or
+with one XML call of the form::
+
+    <function name="tool_name"><param name="arg">value</param></function>
+
+That argument encoding (``<param>`` children, CDATA for special characters)
+differs from the advisor's JSON-body format in ``tool_contracts.py``, so it gets
+its own parser here. Validation reuses ``validate_tool_call`` against the chat
+tool specs. The degradation ladder is chat-specific: prose with no function call
+is a deliberate "no tool" outcome, while a malformed call degrades through a
+keyword intent router and finally to a BM25 search of the raw message — never to
+the advisor's ``search_projects``/``find_whitespace`` defaults, which assume the
+advisor's idea-board context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import Any, Literal
+from xml.etree import ElementTree
+
+from hackathon_advisor.tool_contracts import (
+    ToolCall,
+    ToolContractError,
+    ToolField,
+    ToolSpec,
+    validate_tool_call,
+)
+
+CHAT_TOOL_SPECS: dict[str, ToolSpec] = {
+    "atlas_overview": ToolSpec(
+        name="atlas_overview",
+        description="Summarize the whole field: project totals, biggest clusters, quest coverage.",
+        fields={},
+    ),
+    "list_clusters": ToolSpec(
+        name="list_clusters",
+        description="List the project clusters (themes) with sizes and keywords.",
+        fields={},
+    ),
+    "show_cluster": ToolSpec(
+        name="show_cluster",
+        description="Inspect one cluster by its label and show example projects.",
+        fields={
+            "label": ToolField("string", "Cluster label, such as Voice / Chatbot.", required=True)
+        },
+    ),
+    "list_quests": ToolSpec(
+        name="list_quests",
+        description="List the hackathon quests with how many projects completed each.",
+        fields={},
+    ),
+    "show_quest": ToolSpec(
+        name="show_quest",
+        description="Inspect one quest: its description, coverage, and example projects.",
+        fields={
+            "quest": ToolField(
+                "string", "Quest name, such as Off the Grid or Tiny Titan.", required=True
+            )
+        },
+    ),
+    "show_project": ToolSpec(
+        name="show_project",
+        description="Read one project's README and main app file by project name.",
+        fields={"project": ToolField("string", "Project name, id, or slug.", required=True)},
+    ),
+    "top_projects_by_quests": ToolSpec(
+        name="top_projects_by_quests",
+        description="Rank projects by how many quests they completed (the quest leaderboard).",
+        fields={},
+    ),
+    "search_projects": ToolSpec(
+        name="search_projects",
+        description="Full-text search across all projects on the map.",
+        fields={
+            "query": ToolField("string", "Topic, model, or idea to search for.", required=True)
+        },
+    ),
+    "recent_activity": ToolSpec(
+        name="recent_activity",
+        description="Show the most recently updated projects.",
+        fields={},
+    ),
+}
+
+
+@dataclass(frozen=True)
+class ChatToolResolution:
+    """Outcome of reading one pass-1 model output.
+
+    ``none`` means the model deliberately answered without a tool (chit-chat);
+    ``call`` is None only in that case.
+    """
+
+    status: Literal["valid", "defaulted", "none"]
+    call: ToolCall | None
+    errors: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "call": self.call.to_dict() if self.call else None,
+            "errors": list(self.errors),
+        }
+
+
+def chat_tool_schemas() -> list[dict[str, Any]]:
+    return [spec.to_schema() for spec in CHAT_TOOL_SPECS.values()]
+
+
+_FUNCTION_BLOCK_RE = re.compile(r"<function\b.*?</function>", re.DOTALL)
+_FUNCTION_OPEN_RE = re.compile(r"<function\b")
+
+
+def parse_native_tool_call(text: str) -> ToolCall:
+    """Extract and parse the first native-format function call in ``text``.
+
+    The native template lets the model wrap a call in prose, so surrounding text
+    is ignored; only the ``<function ...>...</function>`` block is parsed.
+    """
+    block = _FUNCTION_BLOCK_RE.search(text or "")
+    if block is None:
+        raise ToolContractError("no <function> call found in model output")
+    try:
+        node = ElementTree.fromstring(block.group(0))
+    except ElementTree.ParseError as error:
+        raise ToolContractError(f"invalid native tool call XML: {error}") from error
+    name = str(node.attrib.get("name") or "").strip()
+    if not name:
+        raise ToolContractError("function call is missing a name")
+    arguments: dict[str, Any] = {}
+    for child in node:
+        if child.tag != "param":
+            raise ToolContractError(f"unexpected element <{child.tag}> in function call")
+        param_name = str(child.attrib.get("name") or "").strip()
+        if not param_name:
+            raise ToolContractError("param is missing a name")
+        arguments[param_name] = _element_text(child).strip()
+    return ToolCall(name=name, arguments=arguments)
+
+
+def resolve_chat_tool_call(model_output: str, fallback_query: str = "") -> ChatToolResolution:
+    """Validate one pass-1 output, or degrade: intent router, then BM25 search."""
+    text = str(model_output or "")
+    if _FUNCTION_OPEN_RE.search(text) is None:
+        return ChatToolResolution(status="none", call=None, errors=())
+
+    errors: list[str] = []
+    try:
+        call = validate_tool_call(parse_native_tool_call(text), specs=CHAT_TOOL_SPECS)
+        return ChatToolResolution(status="valid", call=call, errors=())
+    except ToolContractError as error:
+        errors.append(str(error))
+
+    call = heuristic_chat_call(fallback_query)
+    return ChatToolResolution(status="defaulted", call=call, errors=tuple(errors))
+
+
+def data_intent_call(message: str) -> ToolCall | None:
+    """Map a message with a CLEAR data intent to a tool call; None means no clear intent.
+
+    Used as the accuracy backstop when the model answers a data-shaped question in plain
+    prose: an explicit intent routes to the matching tool, anything else (greetings,
+    meta questions) stays conversational."""
+    lower = " ".join(str(message or "").casefold().split())
+    cleaned = " ".join(str(message or "").split())
+    detail_intent = _mentions(
+        lower, ("what is in", "what's in", "inside", "show me the", "tell me about", "about the")
+    )
+    if _mentions(
+        lower, ("leaderboard", "most quest", "who completed", "top project", "top team", "winning")
+    ):
+        return ToolCall("top_projects_by_quests", {})
+    if _mentions(lower, ("cluster", "theme", "group", "region")):
+        if detail_intent:
+            # cluster_detail() fuzzy-resolves a label embedded in the question.
+            return ToolCall("show_cluster", {"label": cleaned})
+        return ToolCall("list_clusters", {})
+    if _mentions(lower, ("quest", "badge", "challenge")):
+        if detail_intent:
+            return ToolCall("show_quest", {"quest": cleaned})
+        return ToolCall("list_quests", {})
+    if _mentions(lower, ("recent", "latest", "newest", "just updated", "activity")):
+        return ToolCall("recent_activity", {})
+    if _mentions(
+        lower,
+        (
+            "overview",
+            "everyone building",
+            "everyone doing",
+            "whole field",
+            "summary of the",
+            "most liked",
+            "most popular",
+            "coolest",
+            "best project",
+            "favorite project",
+        ),
+    ):
+        return ToolCall("atlas_overview", {})
+    if (
+        _mentions(
+            lower,
+            ("readme", "app file", "source code", "how does", "how is", "what does", "built with"),
+        )
+        or detail_intent
+    ):
+        # project_detail() spots a title embedded in the question; the engine falls
+        # back to BM25 search when no project matches.
+        return ToolCall("show_project", {"project": cleaned})
+    if _mentions(
+        lower,
+        (
+            "find ",
+            "search",
+            "looking for",
+            "projects about",
+            "projects on",
+            "show me",
+            "anything about",
+            "who is building",
+            "how many",
+            "number of",
+            "count of",
+            "is there a",
+            "are there any",
+        ),
+    ):
+        return ToolCall("search_projects", {"query": " ".join(str(message).split())})
+    return None
+
+
+_SMALLTALK_PATTERNS = (
+    "hi",
+    "hello",
+    "hey",
+    "yo",
+    "thanks",
+    "thank you",
+    "ok",
+    "okay",
+    "cool",
+    "nice",
+    "bye",
+    "goodbye",
+    "why",
+    "really",
+    "are you sure",
+    "who are you",
+    "what are you",
+    "what can you do",
+    "how do you work",
+    "help",
+)
+
+
+def smalltalk_intent(message: str) -> bool:
+    """True only for greetings, meta questions, and short follow-ups.
+
+    The chat is a data-exploration surface, so the safe default for anything
+    substantive is a tool (BM25 search) — letting an unmatched question fall
+    through to ungrounded small talk is how the model ends up inventing facts."""
+    lower = " ".join(str(message or "").casefold().split()).rstrip(".!?")
+    if not lower:
+        return True
+    # Pattern-table only: an unknown two-word phrase like "knitting helpers" is a
+    # search, and an unmatched search honestly answers "no match" — never invents.
+    return any(
+        lower == pattern or lower.startswith(f"{pattern} ") for pattern in _SMALLTALK_PATTERNS
+    )
+
+
+def heuristic_chat_call(message: str) -> ToolCall:
+    """Keyword intent router used when the model's tool call cannot be salvaged."""
+    intent = data_intent_call(message)
+    if intent is not None:
+        return intent
+    cleaned = " ".join(str(message or "").split())
+    if cleaned:
+        return ToolCall("search_projects", {"query": cleaned})
+    return ToolCall("atlas_overview", {})
+
+
+def strip_function_blocks(text: str) -> str:
+    """Remove any stray function-call XML a pass-2 generation might emit."""
+    return _FUNCTION_BLOCK_RE.sub("", str(text or "")).strip()
+
+
+def _mentions(lower_text: str, phrases: tuple[str, ...]) -> bool:
+    return any(phrase in lower_text for phrase in phrases)
+
+
+def _element_text(node: ElementTree.Element) -> str:
+    return "".join(node.itertext())

hackathon_advisor/dashboard_repository.py

@@ -0,0 +1,337 @@
+"""Read-only query layer over one immutable dashboard snapshot.
+
+The atlas chat feature (and any future consumer) asks questions like "what is
+everyone building", "which projects completed the most quests", or "what does the
+Voice cluster contain". Those queries belong in one place — not in tool prompts,
+not in route handlers — so this module wraps a single dashboard snapshot
+(``dashboard_payload`` + its ``DashboardSearchIndex``) behind typed query methods
+that return plain JSON-ready dicts.
+
+A repository instance never touches module globals, locks, or models: the caller
+captures a consistent snapshot (app.py does so under ``_runtime_lock``, the same
+pattern as ``/api/dashboard/search``) and constructs the repository outside the
+lock. Quest data may be absent (``quest_report.status == "not_analyzed"``); every
+method degrades to empty-but-well-formed results in that case.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from difflib import SequenceMatcher
+from typing import Any
+
+from hackathon_advisor._text import clean, list_of_dicts
+from hackathon_advisor.dashboard_search import DashboardSearchIndex
+from hackathon_advisor.data import (
+    normalize_project_tags,
+    public_project_summary,
+    public_project_title,
+)
+from hackathon_advisor.quest_taxonomy import (
+    build_app_segment,
+    build_readme_segment,
+    canonical_quest_id,
+    quest_label,
+    quest_profiles,
+)
+
+CLUSTER_LABEL_MATCH_THRESHOLD = 0.6
+DEFAULT_LEADERBOARD_LIMIT = 8
+DEFAULT_SEARCH_LIMIT = 8
+DEFAULT_RECENT_LIMIT = 6
+DEFAULT_EXAMPLE_LIMIT = 6
+README_EXCERPT_CHARS = 1500
+APP_EXCERPT_CHARS = 1900
+
+
+class DashboardRepository:
+    """Pure queries over one dashboard snapshot; safe to use without locks."""
+
+    def __init__(
+        self, dashboard_payload: Mapping[str, Any], search_index: DashboardSearchIndex
+    ) -> None:
+        self._payload = dashboard_payload
+        self._search_index = search_index
+        self._points = list_of_dicts(dashboard_payload.get("points"))
+        self._clusters = list_of_dicts(dashboard_payload.get("clusters"))
+        quest_report = dashboard_payload.get("quest_report")
+        self._quest_report = quest_report if isinstance(quest_report, Mapping) else {}
+        self._cluster_label_by_id = {
+            str(cluster.get("id") or ""): clean(cluster.get("label")) for cluster in self._clusters
+        }
+        # Full Project objects (incl. readme_body / app_file_source, which the public
+        # dashboard points strip) ride along inside the search index's documents.
+        self._project_by_id = {
+            document.project.id: document.project for document in search_index.documents
+        }
+        self._point_by_id = {str(point.get("id") or ""): point for point in self._points}
+
+    def quests_analyzed(self) -> bool:
+        return str(self._quest_report.get("status") or "") == "analyzed"
+
+    def overview(self) -> dict[str, Any]:
+        """Field-wide counts plus the brightest clusters, quests, and projects."""
+        top_quests = [
+            {"id": quest["id"], "label": quest["label"], "project_count": quest["project_count"]}
+            for quest in self._quests_by_coverage()[:3]
+            if quest["project_count"] > 0
+        ]
+        most_liked = sorted(
+            self._points,
+            key=lambda point: (int(point.get("likes") or 0), clean(point.get("title")).casefold()),
+            reverse=True,
+        )[:3]
+        return {
+            "project_count": int(self._payload.get("project_count") or len(self._points)),
+            "cluster_count": len(self._clusters),
+            "generated_at": str(self._payload.get("generated_at") or ""),
+            "quest_status": str(self._quest_report.get("status") or "not_analyzed"),
+            "top_clusters": [
+                {
+                    "label": clean(cluster.get("label")),
+                    "project_count": int(cluster.get("project_count") or 0),
+                }
+                for cluster in self._clusters[:3]
+            ],
+            "top_quests": top_quests,
+            "most_liked": [self._project_row(point) for point in most_liked],
+        }
+
+    def list_clusters(self) -> dict[str, Any]:
+        return {
+            "cluster_count": len(self._clusters),
+            "clusters": [
+                {
+                    "label": clean(cluster.get("label")),
+                    "project_count": int(cluster.get("project_count") or 0),
+                    "keywords": [clean(keyword) for keyword in (cluster.get("keywords") or [])[:4]],
+                }
+                for cluster in self._clusters
+            ],
+        }
+
+    def cluster_detail(self, label: str) -> dict[str, Any] | None:
+        """Resolve a cluster by (fuzzy) label or id; cluster ids are unstable across refreshes."""
+        cluster = self._resolve_cluster(label)
+        if cluster is None:
+            return None
+        examples = list_of_dicts(cluster.get("representative_projects"))[:DEFAULT_EXAMPLE_LIMIT]
+        return {
+            "label": clean(cluster.get("label")),
+            "project_count": int(cluster.get("project_count") or 0),
+            "keywords": [clean(keyword) for keyword in (cluster.get("keywords") or [])[:5]],
+            "examples": [self._project_row(example) for example in examples],
+        }
+
+    def list_quests(self) -> dict[str, Any]:
+        return {
+            "status": str(self._quest_report.get("status") or "not_analyzed"),
+            "quests": self._quests_by_coverage(),
+        }
+
+    def quest_detail(self, quest: str) -> dict[str, Any] | None:
+        try:
+            quest_id = canonical_quest_id(quest)
+        except ValueError:
+            quest_id = self._find_quest_in_text(quest)
+            if quest_id is None:
+                return None
+        report_entry = next(
+            (
+                entry
+                for entry in list_of_dicts(self._quest_report.get("quests"))
+                if str(entry.get("id") or "") == quest_id
+            ),
+            {},
+        )
+        profile = next(
+            (profile for profile in quest_profiles() if profile["id"] == quest_id),
+            {"id": quest_id, "label": quest_id, "description": ""},
+        )
+        matched = [point for point in self._points if quest_id in (point.get("quest_ids") or [])]
+        examples = list_of_dicts(report_entry.get("examples"))[:DEFAULT_EXAMPLE_LIMIT] or [
+            self._project_row(point) for point in matched[:DEFAULT_EXAMPLE_LIMIT]
+        ]
+        return {
+            "id": quest_id,
+            "label": profile["label"],
+            "description": profile["description"],
+            "status": str(self._quest_report.get("status") or "not_analyzed"),
+            "project_count": int(report_entry.get("project_count") or len(matched)),
+            "examples": [self._project_row(example) for example in examples],
+        }
+
+    def top_by_quests(self, limit: int = DEFAULT_LEADERBOARD_LIMIT) -> dict[str, Any]:
+        """Per-project quest leaderboard (projects ARE the teams: no author field exists)."""
+        rows = [
+            {
+                **self._project_row(point),
+                "quest_count": len(point.get("quest_ids") or []),
+                "quest_ids": [str(quest) for quest in point.get("quest_ids") or []],
+            }
+            for point in self._points
+            if point.get("quest_ids")
+        ]
+        rows.sort(
+            key=lambda row: (row["quest_count"], row["likes"], row["title"].casefold()),
+            reverse=True,
+        )
+        return {
+            "status": str(self._quest_report.get("status") or "not_analyzed"),
+            "rows": rows[: max(1, int(limit))],
+            "projects_with_quests": len(rows),
+        }
+
+    def search(self, query: str, limit: int = DEFAULT_SEARCH_LIMIT) -> dict[str, Any]:
+        payload = self._search_index.search(clean(query), limit=max(1, int(limit)))
+        return {
+            "query": payload["query"],
+            "total": int(payload["total"]),
+            "results": [
+                {
+                    "id": str(result.get("project_id") or ""),
+                    "title": clean(result.get("title")),
+                    "summary": clean(result.get("summary")),
+                    "url": str(result.get("url") or ""),
+                    "score": float(result.get("score") or 0.0),
+                }
+                for result in payload["results"]
+            ],
+        }
+
+    def recent_activity(self, limit: int = DEFAULT_RECENT_LIMIT) -> dict[str, Any]:
+        ordered = sorted(
+            self._points,
+            key=lambda point: str(point.get("last_modified") or ""),
+            reverse=True,
+        )[: max(1, int(limit))]
+        return {
+            "projects": [
+                {
+                    **self._project_row(point),
+                    "last_modified": str(point.get("last_modified") or ""),
+                    "cluster_label": self._cluster_label_by_id.get(
+                        str(point.get("cluster_id") or ""), ""
+                    ),
+                }
+                for point in ordered
+            ],
+        }
+
+    def _quests_by_coverage(self) -> list[dict[str, Any]]:
+        entries = [
+            {
+                "id": str(entry.get("id") or ""),
+                "label": clean(entry.get("label")) or str(entry.get("id") or ""),
+                "description": clean(entry.get("description")),
+                "project_count": int(entry.get("project_count") or 0),
+            }
+            for entry in list_of_dicts(self._quest_report.get("quests"))
+        ]
+        return sorted(
+            entries, key=lambda entry: (-entry["project_count"], entry["label"].casefold())
+        )
+
+    def project_detail(self, name: str) -> dict[str, Any] | None:
+        """One project's card plus its README and main-app-file excerpts.
+
+        The excerpts reuse the quest classifier's prompt view (build_readme_segment /
+        build_app_segment) — the same budgeted slices MiniCPM already reads well."""
+        project = self._resolve_project(name)
+        if project is None:
+            return None
+        point = self._point_by_id.get(project.id, {})
+        app_excerpt = _clip_excerpt(
+            build_app_segment(project.app_file_source, project.app_file_embedding_text),
+            APP_EXCERPT_CHARS,
+        )
+        return {
+            "id": project.id,
+            "title": public_project_title(project.title),
+            "summary": public_project_summary(project.summary),
+            "url": project.url,
+            "likes": project.likes,
+            "sdk": project.sdk,
+            "models": list(project.models)[:4],
+            "tags": list(normalize_project_tags(project.tags))[:6],
+            "last_modified": project.last_modified,
+            "cluster_label": self._cluster_label_by_id.get(str(point.get("cluster_id") or ""), ""),
+            "quests": [quest_label(str(quest)) for quest in point.get("quest_ids") or []],
+            "readme_excerpt": _clip_excerpt(
+                build_readme_segment(project.readme_body), README_EXCERPT_CHARS
+            ),
+            "app_file": project.app_file,
+            "app_excerpt": app_excerpt,
+        }
+
+    def _resolve_project(self, name: str) -> Any | None:
+        """Match a project by id, slug, or title — exact first, then embedded in a
+        longer question ("tell me about Jawbreaker"), longest title winning."""
+        wanted = clean(name).casefold()
+        if not wanted:
+            return None
+        for project in self._project_by_id.values():
+            slug = project.id.rsplit("/", 1)[-1]
+            if wanted in (project.id.casefold(), slug.casefold()):
+                return project
+            if public_project_title(project.title).casefold() == wanted:
+                return project
+        best, best_length = None, 0
+        for project in self._project_by_id.values():
+            title = public_project_title(project.title).casefold()
+            slug = project.id.rsplit("/", 1)[-1].casefold()
+            for candidate in (title, slug):
+                if len(candidate) > 3 and candidate in wanted and len(candidate) > best_length:
+                    best, best_length = project, len(candidate)
+        return best
+
+    def _find_quest_in_text(self, text: str) -> str | None:
+        """Spot a quest id or label embedded in a longer question."""
+        wanted = clean(text).casefold()
+        if not wanted:
+            return None
+        for profile in quest_profiles():
+            if profile["id"].casefold() in wanted or profile["label"].casefold() in wanted:
+                return profile["id"]
+        return None
+
+    def _resolve_cluster(self, label: str) -> Mapping[str, Any] | None:
+        wanted = clean(label).casefold()
+        if not wanted:
+            return None
+        for cluster in self._clusters:
+            if str(cluster.get("id") or "").casefold() == wanted:
+                return cluster
+        for cluster in self._clusters:
+            if clean(cluster.get("label")).casefold() == wanted:
+                return cluster
+        for cluster in self._clusters:
+            cluster_label = clean(cluster.get("label")).casefold()
+            if wanted in cluster_label or cluster_label in wanted:
+                return cluster
+        for cluster in self._clusters:
+            keywords = {clean(keyword).casefold() for keyword in cluster.get("keywords") or []}
+            if any(token in keywords for token in wanted.split()):
+                return cluster
+        best, best_score = None, 0.0
+        for cluster in self._clusters:
+            score = SequenceMatcher(None, wanted, clean(cluster.get("label")).casefold()).ratio()
+            if score > best_score:
+                best, best_score = cluster, score
+        return best if best_score >= CLUSTER_LABEL_MATCH_THRESHOLD else None
+
+    def _project_row(self, point: Mapping[str, Any]) -> dict[str, Any]:
+        return {
+            "id": str(point.get("id") or ""),
+            "title": clean(point.get("title")) or str(point.get("id") or ""),
+            "url": str(point.get("url") or ""),
+            "likes": int(point.get("likes") or 0),
+        }
+
+
+def _clip_excerpt(text: str, limit: int) -> str:
+    # Newlines stay (app files read as code); only the length is bounded.
+    cleaned = str(text or "").strip()
+    if len(cleaned) <= limit:
+        return cleaned
+    return cleaned[:limit].rstrip() + " ..."

hackathon_advisor/model_runtime.py

@@ -24,6 +24,17 @@ MAX_TOOL_CALL_TOKENS = 180
 MINICPM_DEMO_TEMPERATURE = 0.9
 MINICPM_DEMO_TOP_P = 0.95
 
+# One lock for every MiniCPM generation in this process. The atlas chat borrows the
+# advisor's loaded model and toggles its LoRA off via PeftModel.disable_adapter(),
+# which mutates shared model state — so adapter toggling and generate() must never
+# interleave across threads. The lock is held for the FULL lifetime of the streaming
+# worker thread (acquired before it starts, released after it joins).
+_GENERATION_LOCK = threading.Lock()
+
+
+def generation_lock() -> threading.Lock:
+    return _GENERATION_LOCK
+
 
 class ToolPlanner(Protocol):
     backend: str
@@ -157,6 +168,7 @@ class MiniCPMTransformersPlanner:
         self._tokenizer = None
         self._model = None
         self._inference_mode = None
+        self._load_lock = threading.Lock()
 
     def plan(self, message: str, state: dict[str, Any]) -> ToolResolution:
         resolution: ToolResolution | None = None
@@ -179,6 +191,15 @@ class MiniCPMTransformersPlanner:
     def _ensure_loaded(self) -> None:
         if self._model is not None and self._tokenizer is not None:
             return
+        # Double-checked: the advisor and the atlas chat share this planner, so two
+        # cold-start requests could otherwise both run the full from_pretrained load
+        # (a ~2x transient memory spike). _GENERATION_LOCK starts too late to help.
+        with self._load_lock:
+            if self._model is not None and self._tokenizer is not None:
+                return
+            self._load()
+
+    def _load(self) -> None:
         try:
             import torch
             from transformers import AutoModelForCausalLM, AutoTokenizer
@@ -235,44 +256,31 @@ class MiniCPMTransformersPlanner:
         )
 
     def _stream_tool_call(self, prompt: str) -> Iterator[tuple[int, str]]:
-        from transformers import TextIteratorStreamer
-
         assert self._tokenizer is not None
         assert self._model is not None
         inputs = self._prepare_inputs(prompt)
-        streamer = TextIteratorStreamer(
-            self._tokenizer, skip_prompt=True, skip_special_tokens=True
-        )
-        generation_kwargs = _minicpm_generation_kwargs(
+        yield from _stream_minicpm_generation(
+            self._model,
+            self._tokenizer,
             inputs,
             max_new_tokens=MAX_TOOL_CALL_TOKENS,
             temperature=0.0,
-            streamer=streamer,
+            inference_mode=self._inference_mode,
         )
-        errors: list[BaseException] = []
-
-        def _run() -> None:
-            context = self._inference_mode() if self._inference_mode is not None else nullcontext()
-            try:
-                with context:
-                    self._model.generate(**generation_kwargs)
-            except BaseException as error:  # surfaced after the streamer drains
-                errors.append(error)
-                # generate() never reached its end sentinel, so wake the consumer instead of
-                # letting it block forever, then re-raise from the main thread below.
-                streamer.end()
-
-        worker = threading.Thread(target=_run, daemon=True)
-        worker.start()
-        tokens = 0
-        for piece in streamer:
-            if not piece:
-                continue
-            tokens += 1
-            yield tokens, piece
-        worker.join()
-        if errors:
-            raise errors[0]
+
+    def ensure_loaded(self) -> None:
+        """Public lazy-load trigger so a borrower (the atlas chat) can share the model."""
+        self._ensure_loaded()
+
+    def base_model_context(self):
+        """Context manager that exposes the BASE weights of the loaded model.
+
+        With a LoRA adapter attached this is PeftModel.disable_adapter(); without one
+        the model already is the base, so a nullcontext suffices. Callers must hold
+        generation_lock() around the entered context (see _stream_minicpm_generation)."""
+        if self.adapter_id and self._model is not None and hasattr(self._model, "disable_adapter"):
+            return self._model.disable_adapter()
+        return nullcontext()
 
 
 def _device_available(device: str, torch: Any) -> bool:
@@ -359,6 +367,30 @@ def _minicpm_chat_inputs(
     return inputs
 
 
+def _minicpm_chat_inputs_with_tools(
+    tokenizer: Any,
+    messages: list[dict[str, Any]],
+    *,
+    tools: list[dict[str, Any]],
+    enable_thinking: bool,
+    device: Any,
+) -> Any:
+    """Chat inputs with the native tools= injection (atlas chat pass 1).
+
+    Kept separate from _minicpm_chat_inputs so the advisor's exact template call —
+    asserted verbatim in tests — stays untouched."""
+    prompt_text = tokenizer.apply_chat_template(
+        messages,
+        tools=tools,
+        tokenize=False,
+        add_generation_prompt=True,
+        enable_thinking=enable_thinking,
+    )
+    inputs = tokenizer([prompt_text], return_tensors="pt").to(device)
+    _strip_unused_generation_inputs(inputs)
+    return inputs
+
+
 def _minicpm_generation_kwargs(
     inputs: dict[str, Any],
     *,
@@ -380,6 +412,188 @@ def _minicpm_generation_kwargs(
     return generation_kwargs
 
 
+def _stream_minicpm_generation(
+    model: Any,
+    tokenizer: Any,
+    inputs: dict[str, Any],
+    *,
+    max_new_tokens: int,
+    temperature: float = 0.0,
+    inference_mode: Any | None = None,
+    model_context: Any | None = None,
+) -> Iterator[tuple[int, str]]:
+    """Stream one MiniCPM generation as (token_count, text_piece) tuples.
+
+    Shared by the advisor tool-call pass and both atlas-chat passes. generate() runs in
+    a daemon thread feeding a TextIteratorStreamer; the process-wide generation lock is
+    held from before the worker starts until after it joins, so an adapter toggle
+    (``model_context`` — e.g. PeftModel.disable_adapter()) can never interleave with a
+    concurrent adapter-on generation. The ``finally`` also covers a consumer that
+    abandons the generator mid-stream."""
+    from transformers import TextIteratorStreamer
+
+    streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True)
+    generation_kwargs = _minicpm_generation_kwargs(
+        inputs,
+        max_new_tokens=max_new_tokens,
+        temperature=temperature,
+        streamer=streamer,
+    )
+    errors: list[BaseException] = []
+
+    def _run() -> None:
+        context = inference_mode() if inference_mode is not None else nullcontext()
+        weights = model_context() if model_context is not None else nullcontext()
+        try:
+            with weights, context:
+                model.generate(**generation_kwargs)
+        except BaseException as error:  # surfaced after the streamer drains
+            errors.append(error)
+            # generate() never reached its end sentinel, so wake the consumer instead of
+            # letting it block forever, then re-raise from the main thread below.
+            streamer.end()
+
+    worker = threading.Thread(target=_run, daemon=True)
+    with _GENERATION_LOCK:
+        worker.start()
+        try:
+            tokens = 0
+            for piece in streamer:
+                if not piece:
+                    continue
+                tokens += 1
+                yield tokens, piece
+        finally:
+            worker.join()
+    if errors:
+        raise errors[0]
+
+
+class ChatRunner(Protocol):
+    """Streams atlas-chat generations over the (shared) base model."""
+
+    backend: str
+    model_id: str
+
+    supports_thinking: bool
+
+    def stream(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        max_new_tokens: int,
+        enable_thinking: bool = False,
+    ) -> Iterator[tuple[int, str]]:
+        ...
+
+
+class MiniCPMChatRunner:
+    """Atlas-chat generations on the advisor's MiniCPM instance with the LoRA disabled.
+
+    Borrows the advisor planner's model and tokenizer (never loads its own copy) and
+    runs every generation under base_model_context() + the shared generation lock, so
+    the chat speaks with the BASE MiniCPM5-1B voice while the advisor keeps its adapter."""
+
+    backend = "minicpm-transformers"
+    # With enable_thinking the template ends the prompt with "<think>\n", so the
+    # stream is reasoning text up to "</think>" followed by the actual content.
+    supports_thinking = True
+
+    def __init__(self, planner: MiniCPMTransformersPlanner) -> None:
+        self._planner = planner
+
+    @property
+    def model_id(self) -> str:
+        return self._planner.model_id
+
+    def stream(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        max_new_tokens: int,
+        enable_thinking: bool = False,
+    ) -> Iterator[tuple[int, str]]:
+        planner = self._planner
+        planner.ensure_loaded()
+        assert planner._model is not None and planner._tokenizer is not None
+        device = next(planner._model.parameters()).device
+        if tools:
+            inputs = _minicpm_chat_inputs_with_tools(
+                planner._tokenizer,
+                messages,
+                tools=tools,
+                enable_thinking=enable_thinking,
+                device=device,
+            )
+        else:
+            inputs = _minicpm_chat_inputs(
+                planner._tokenizer,
+                messages,
+                enable_thinking=enable_thinking,
+                device=device,
+            )
+        yield from _stream_minicpm_generation(
+            planner._model,
+            planner._tokenizer,
+            inputs,
+            max_new_tokens=max_new_tokens,
+            temperature=0.0,
+            inference_mode=planner._inference_mode,
+            model_context=planner.base_model_context,
+        )
+
+
+class RuleBasedChatRunner:
+    """Deterministic ChatRunner for the rules backend (tests, weight-free UI work).
+
+    Pass 1 (tools given) emits a native-format call chosen by the keyword intent
+    router; pass 2 emits a fixed grounded sentence — the UI's verified cards carry
+    the actual data either way."""
+
+    backend = "rules"
+    model_id = "deterministic-chat-router"
+    supports_thinking = False
+
+    def stream(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        max_new_tokens: int,
+        enable_thinking: bool = False,
+    ) -> Iterator[tuple[int, str]]:
+        from xml.sax.saxutils import escape
+
+        from hackathon_advisor.dashboard_chat_contracts import heuristic_chat_call
+
+        if tools:
+            message = _last_user_content(messages)
+            call = heuristic_chat_call(message)
+            params = "".join(
+                f'<param name="{name}">{escape(str(value))}</param>'
+                for name, value in call.arguments.items()
+            )
+            yield 1, f'<function name="{call.name}">{params}</function>'
+            return
+        yield 1, "Here is what the atlas snapshot shows; the cards below are the verified data."
+
+
+def _last_user_content(messages: list[dict[str, Any]]) -> str:
+    for message in reversed(messages):
+        if message.get("role") == "user":
+            return str(message.get("content") or "")
+    return ""
+
+
+def create_chat_runner(planner: ToolPlanner) -> ChatRunner:
+    """Build the atlas ChatRunner for an advisor planner; never loads a second model."""
+    if isinstance(planner, MiniCPMTransformersPlanner):
+        return MiniCPMChatRunner(planner)
+    return RuleBasedChatRunner()
+
+
 def create_tool_planner(device: str = "auto") -> ToolPlanner:
     backend = os.environ.get("ADVISOR_MODEL_BACKEND", "").strip().lower() or DEFAULT_BACKEND
     if backend == "rules":

static/app.js

@@ -477,6 +477,7 @@ function renderDashboard(data) {
   renderAtlasDetail(currentAtlasPoint(data));
   renderAtlasReport(data);
   renderAtlasSearch();
+  renderChatActionChip(); // keep the chat's applied-filter chip in sync with manual clicks
   if (atlasStatusEl) atlasStatusEl.textContent = atlasSearchQuery ? atlasSearchStatusCopy() : atlasProvenanceCopy(data);
 }
 
@@ -2130,3 +2131,626 @@ function shortDate(value) {
   if (!value) return "unknown";
   return String(value).replace("T", " ").replace(/\+00:00$/, "Z").slice(0, 16);
 }
+
+/* ---------------------------------------------------------------------------
+ * Atlas chat drawer — conversational access to the live dashboard.
+ *
+ * Streams POST /api/dashboard/chat (NDJSON). Verified tool results render as
+ * cards and drive the map through map_action BEFORE the model prose arrives;
+ * the prose is labeled "Model summary" and the done.response is authoritative.
+ * ------------------------------------------------------------------------- */
+
+const openAtlasChatButton = document.querySelector("#open-atlas-chat");
+const atlasChatEl = document.querySelector("#atlas-chat");
+const atlasChatScrimEl = document.querySelector("#atlas-chat-scrim");
+const atlasChatLogEl = document.querySelector("#atlas-chat-log");
+const atlasChatFormEl = document.querySelector("#atlas-chat-form");
+const atlasChatInputEl = document.querySelector("#atlas-chat-input");
+const atlasChatSendEl = document.querySelector("#atlas-chat-send");
+const atlasChatCloseEl = document.querySelector("#atlas-chat-close");
+const atlasChatClearEl = document.querySelector("#atlas-chat-clear");
+const atlasChatSuggestionsEl = document.querySelector("#atlas-chat-suggestions");
+const atlasChatActionEl = document.querySelector("#atlas-chat-action");
+
+const ATLAS_CHAT_STORAGE_KEY = "hackathon-advisor-atlas-chat-v1";
+const ATLAS_CHAT_MAX_MESSAGES = 30;
+const ATLAS_CHAT_SUGGESTIONS = [
+  "What is everyone building?",
+  "Who completed the most quests?",
+  "What clusters exist?",
+  "What changed recently?",
+];
+
+let atlasChatMessages = loadAtlasChatMessages();
+let atlasChatBusy = false;
+let atlasChatLastFocus = null;
+let chatMapActionApplied = false;
+
+openAtlasChatButton?.addEventListener("click", () => openAtlasChat());
+atlasChatCloseEl?.addEventListener("click", () => closeAtlasChat());
+atlasChatScrimEl?.addEventListener("click", () => closeAtlasChat());
+atlasChatClearEl?.addEventListener("click", () => {
+  if (atlasChatBusy) return; // an in-flight stream still mutates the live message
+  atlasChatMessages = [];
+  persistAtlasChatMessages();
+  renderAtlasChatLog();
+});
+atlasChatFormEl?.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  const message = String(atlasChatInputEl?.value || "").trim();
+  if (!message || atlasChatBusy) return;
+  atlasChatInputEl.value = "";
+  await runAtlasChatTurn(message);
+});
+// Non-modal dialog (aria-modal=false): no Tab trap — the map stays reachable.
+atlasChatEl?.addEventListener("keydown", (event) => {
+  if (event.key === "Escape") {
+    event.stopPropagation();
+    closeAtlasChat();
+  }
+});
+
+function openAtlasChat() {
+  if (!atlasChatEl) return;
+  atlasChatLastFocus = document.activeElement;
+  atlasChatEl.hidden = false;
+  if (atlasChatScrimEl) atlasChatScrimEl.hidden = false;
+  window.requestAnimationFrame(() => atlasChatEl.classList.add("open"));
+  renderAtlasChatLog();
+  window.setTimeout(() => atlasChatInputEl?.focus(), 60);
+}
+
+function closeAtlasChat() {
+  if (!atlasChatEl || atlasChatEl.hidden) return;
+  atlasChatEl.classList.remove("open");
+  if (atlasChatScrimEl) atlasChatScrimEl.hidden = true;
+  window.setTimeout(() => {
+    atlasChatEl.hidden = true;
+  }, 290);
+  if (atlasChatLastFocus?.focus) atlasChatLastFocus.focus();
+}
+
+function loadAtlasChatMessages() {
+  try {
+    const stored = JSON.parse(window.localStorage.getItem(ATLAS_CHAT_STORAGE_KEY) || "[]");
+    return Array.isArray(stored) ? stored.slice(-ATLAS_CHAT_MAX_MESSAGES) : [];
+  } catch {
+    return [];
+  }
+}
+
+function persistAtlasChatMessages() {
+  try {
+    window.localStorage.setItem(
+      ATLAS_CHAT_STORAGE_KEY,
+      JSON.stringify(atlasChatMessages.slice(-ATLAS_CHAT_MAX_MESSAGES)),
+    );
+  } catch {
+    /* storage may be unavailable; chat still works in-memory */
+  }
+}
+
+function atlasChatServerHistory() {
+  return atlasChatMessages
+    .filter((message) => message.text)
+    .map((message) => ({
+      role: message.role === "user" ? "user" : "assistant",
+      content: message.text,
+    }));
+}
+
+async function runAtlasChatTurn(message) {
+  if (atlasChatBusy) return;
+  atlasChatBusy = true;
+  if (atlasChatSendEl) atlasChatSendEl.disabled = true;
+  const historyJson = JSON.stringify(atlasChatServerHistory());
+  atlasChatMessages.push({ role: "user", text: message });
+  const guide = {
+    role: "guide",
+    text: "",
+    thinking: "",
+    tool: "",
+    data: null,
+    mapAction: null,
+    skipped: "",
+  };
+  atlasChatMessages.push(guide);
+  renderAtlasChatLog();
+  const live = atlasChatLogEl?.lastElementChild;
+  const typingEl = live?.querySelector(".atlas-chat-typing");
+  const proseEl = live?.querySelector(".atlas-chat-prose");
+  const thinkEl = live?.querySelector(".atlas-chat-think");
+  const thinkTextEl = live?.querySelector(".atlas-chat-think-text");
+
+  try {
+    const response = await fetch("/api/dashboard/chat", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ message, history_json: historyJson }),
+    });
+    if (!response.ok) throw new Error(`atlas chat failed with ${response.status}`);
+    if (!response.body) throw new Error("atlas chat stream was empty");
+
+    for await (const raw of readNdjson(response.body)) {
+      const event = JSON.parse(raw);
+      handleAtlasChatEvent(event, guide, { live, typingEl, proseEl, thinkEl, thinkTextEl });
+    }
+  } catch (error) {
+    console.error("Atlas chat turn failed.", error);
+    guide.text = guide.text || `The atlas guide could not answer: ${error.message}`;
+    guide.skipped = guide.skipped || "error";
+  } finally {
+    atlasChatBusy = false;
+    if (atlasChatSendEl) atlasChatSendEl.disabled = false;
+    persistAtlasChatMessages();
+    renderAtlasChatLog();
+    atlasChatInputEl?.focus();
+  }
+}
+
+function handleAtlasChatEvent(event, guide, nodes) {
+  switch (event.type) {
+    case "stage":
+      if (nodes.typingEl) nodes.typingEl.textContent = event.label || "Thinking.";
+      break;
+    case "thinking":
+      guide.thinking += event.text || "";
+      if (nodes.thinkEl) {
+        nodes.thinkEl.hidden = false;
+        nodes.thinkEl.open = true;
+      }
+      if (nodes.thinkTextEl) nodes.thinkTextEl.textContent = guide.thinking;
+      if (nodes.typingEl) nodes.typingEl.textContent = "Thinking.";
+      scrollAtlasChatLog();
+      break;
+    case "tool_call":
+      guide.tool = event.name || "";
+      if (nodes.typingEl && event.name) {
+        nodes.typingEl.textContent = `Checking ${event.name.replaceAll("_", " ")}.`;
+      }
+      break;
+    case "tool_result":
+      guide.data = event.data || null;
+      guide.tool = event.tool || guide.tool;
+      guide.mapAction = event.map_action || null;
+      if (guide.mapAction) applyChatMapAction(guide.mapAction);
+      if (nodes.live) {
+        const cards = nodes.live.querySelector(".atlas-chat-cards");
+        if (cards) cards.replaceChildren(...atlasChatCards(guide.tool, guide.data));
+      }
+      break;
+    case "token":
+      guide.text += event.text || "";
+      if (nodes.proseEl) {
+        nodes.proseEl.hidden = false;
+        nodes.proseEl.textContent = guide.text;
+      }
+      if (nodes.typingEl) nodes.typingEl.hidden = true;
+      if (nodes.thinkEl) nodes.thinkEl.open = false; // fold the trace once the answer starts
+      scrollAtlasChatLog();
+      break;
+    case "answer_skipped":
+      guide.text = event.text || "";
+      guide.skipped = event.reason || "skipped";
+      break;
+    case "fallback":
+      guide.fallback = event.reason || "Running locally.";
+      break;
+    case "done":
+      guide.text = event.response || guide.text;
+      guide.tool = event.tool || guide.tool;
+      if (guide.tool && event.data && Object.keys(event.data).length && !guide.data) {
+        guide.data = event.data;
+      }
+      announceAtlasChat(guide.text);
+      break;
+    default:
+      break;
+  }
+}
+
+function renderAtlasChatLog() {
+  if (!atlasChatLogEl) return;
+  atlasChatLogEl.replaceChildren();
+  for (const message of atlasChatMessages) {
+    atlasChatLogEl.append(
+      message.role === "user" ? atlasChatUserNode(message) : atlasChatGuideNode(message),
+    );
+  }
+  renderAtlasChatSuggestions();
+  renderChatActionChip();
+  scrollAtlasChatLog();
+}
+
+function atlasChatUserNode(message) {
+  const node = document.createElement("div");
+  node.className = "atlas-chat-msg user";
+  node.textContent = message.text;
+  return node;
+}
+
+function atlasChatGuideNode(message) {
+  const node = document.createElement("div");
+  node.className = "atlas-chat-msg guide";
+
+  const hasCards = Boolean(message.tool && message.data && Object.keys(message.data).length);
+  if (hasCards) {
+    const dataLabel = document.createElement("span");
+    dataLabel.className = "atlas-chat-label";
+    dataLabel.textContent = "Data";
+    node.append(dataLabel);
+  }
+  const cards = document.createElement("div");
+  cards.className = "atlas-chat-cards";
+  cards.append(...atlasChatCards(message.tool, message.data));
+  node.append(cards);
+
+  // The model's reasoning trace: streams open, folds once the answer starts.
+  const think = document.createElement("details");
+  think.className = "atlas-chat-think";
+  const summary = document.createElement("summary");
+  summary.textContent = "Thinking";
+  const thinkText = document.createElement("div");
+  thinkText.className = "atlas-chat-think-text";
+  thinkText.textContent = message.thinking || "";
+  think.append(summary, thinkText);
+  think.hidden = !message.thinking;
+  node.append(think);
+
+  const proseLabel = document.createElement("span");
+  proseLabel.className = "atlas-chat-label";
+  proseLabel.textContent = message.skipped ? "Atlas note" : "Model summary";
+  const prose = document.createElement("p");
+  prose.className = `atlas-chat-prose ${message.skipped ? "skipped" : ""}`;
+  prose.textContent = message.text;
+  prose.hidden = !message.text;
+  proseLabel.hidden = !message.text;
+
+  if (!message.text && atlasChatBusy && message === atlasChatMessages.at(-1)) {
+    const typing = document.createElement("span");
+    typing.className = "atlas-chat-typing";
+    typing.textContent = "Reading the atlas.";
+    node.append(typing);
+  }
+  node.append(proseLabel, prose);
+
+  if (message.fallback) {
+    const fallback = document.createElement("span");
+    fallback.className = "atlas-chat-fallback";
+    fallback.textContent = message.fallback;
+    node.append(fallback);
+  }
+  if (message.skipped === "quests_not_analyzed") {
+    node.append(atlasChatRefreshCard());
+  }
+  return node;
+}
+
+function atlasChatRefreshCard() {
+  const card = document.createElement("div");
+  card.className = "atlas-chat-empty";
+  const copy = document.createElement("span");
+  copy.textContent = "Quest coverage appears after a map refresh classifies the field.";
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "btn btn-ghost";
+  button.textContent = "Refresh map";
+  button.addEventListener("click", () => startDashboardRefresh());
+  card.append(copy, button);
+  return card;
+}
+
+function atlasChatCards(tool, data) {
+  if (!data) return [];
+  switch (tool) {
+    case "atlas_overview":
+      return overviewCards(data);
+    case "list_clusters":
+      return clusterListCards(data);
+    case "show_cluster":
+      return clusterDetailCards(data);
+    case "show_project":
+      return projectReadmeCards(data);
+    case "list_quests":
+      return questListCards(data);
+    case "show_quest":
+      return questDetailCards(data);
+    case "top_projects_by_quests":
+      return leaderboardCards(data);
+    case "search_projects":
+      return searchCards(data);
+    case "recent_activity":
+      return recentCards(data);
+    default:
+      return [];
+  }
+}
+
+function overviewCards(data) {
+  const statline = document.createElement("div");
+  statline.className = "atlas-chat-statline";
+  statline.innerHTML = `
+    <span><strong>${Number(data.project_count || 0)}</strong> projects</span>
+    <span><strong>${Number(data.cluster_count || 0)}</strong> clusters</span>
+    <span><strong>${escapeHtml(String(data.quest_status || ""))}</strong> quests</span>
+  `;
+  const chips = document.createElement("div");
+  chips.className = "atlas-chat-chips";
+  for (const cluster of data.top_clusters || []) {
+    chips.append(
+      chatChipButton(`${cluster.label} · ${cluster.project_count}`, () =>
+        applyChatMapAction({ type: "filter_cluster", label: cluster.label }),
+      ),
+    );
+  }
+  const nodes = [statline, chips];
+  for (const project of data.most_liked || []) {
+    nodes.push(projectCard(project, `${project.likes} likes`));
+  }
+  return nodes;
+}
+
+function clusterListCards(data) {
+  const chips = document.createElement("div");
+  chips.className = "atlas-chat-chips";
+  for (const cluster of data.clusters || []) {
+    chips.append(
+      chatChipButton(`${cluster.label} · ${cluster.project_count}`, () =>
+        applyChatMapAction({ type: "filter_cluster", label: cluster.label }),
+      ),
+    );
+  }
+  return [chips];
+}
+
+function clusterDetailCards(data) {
+  const nodes = [];
+  if (data.keywords?.length) {
+    const chips = document.createElement("div");
+    chips.className = "atlas-chat-chips";
+    for (const keyword of data.keywords) {
+      const chip = document.createElement("span");
+      chip.textContent = keyword;
+      chips.append(chip);
+    }
+    nodes.push(chips);
+  }
+  for (const project of data.examples || []) {
+    nodes.push(projectCard(project, `${project.likes} likes`));
+  }
+  return nodes;
+}
+
+function projectReadmeCards(data) {
+  const nodes = [];
+  const metaParts = [
+    data.likes ? `${data.likes} likes` : "",
+    data.sdk || "",
+    data.cluster_label || "",
+  ].filter(Boolean);
+  nodes.push(projectCard(data, [data.summary, metaParts.join(" · ")].filter(Boolean).join(" — ")));
+
+  const chips = document.createElement("div");
+  chips.className = "atlas-chat-chips";
+  for (const label of [...(data.quests || []), ...(data.tags || [])].slice(0, 8)) {
+    const chip = document.createElement("span");
+    chip.textContent = label;
+    chips.append(chip);
+  }
+  if (chips.childElementCount) nodes.push(chips);
+
+  if (data.readme_excerpt) {
+    const readme = document.createElement("div");
+    readme.className = "atlas-chat-card";
+    readme.innerHTML = `<span class="atlas-chat-label">README</span>`;
+    const body = document.createElement("p");
+    body.className = "atlas-chat-excerpt";
+    body.textContent = data.readme_excerpt;
+    readme.append(body);
+    nodes.push(readme);
+  }
+  if (data.app_excerpt) {
+    const app = document.createElement("div");
+    app.className = "atlas-chat-card";
+    app.innerHTML = `<span class="atlas-chat-label">${escapeHtml(data.app_file || "app file")}</span>`;
+    const code = document.createElement("pre");
+    code.className = "atlas-chat-code";
+    code.textContent = data.app_excerpt;
+    app.append(code);
+    nodes.push(app);
+  }
+  return nodes;
+}
+
+function questListCards(data) {
+  const quests = (data.quests || []).filter((quest) => Number(quest.project_count || 0) > 0);
+  const max = Math.max(1, ...quests.map((quest) => Number(quest.project_count || 0)));
+  return quests.slice(0, 8).map((quest) => barCard(quest.label, quest.project_count, max));
+}
+
+function questDetailCards(data) {
+  const nodes = [];
+  const card = document.createElement("div");
+  card.className = "atlas-chat-card";
+  card.innerHTML = `
+    <strong>${escapeHtml(data.label || data.id || "")}</strong>
+    <span class="atlas-chat-card-meta">${escapeHtml(data.description || "")}</span>
+    <span class="atlas-chat-card-meta">${Number(data.project_count || 0)} projects</span>
+  `;
+  nodes.push(card);
+  for (const project of data.examples || []) {
+    nodes.push(projectCard(project, ""));
+  }
+  return nodes;
+}
+
+function leaderboardCards(data) {
+  const rows = data.rows || [];
+  const max = Math.max(1, ...rows.map((row) => Number(row.quest_count || 0)));
+  return rows.map((row) =>
+    barCard(row.title, row.quest_count, max, row.url, `${row.quest_count} quests · ${row.likes} likes`),
+  );
+}
+
+function searchCards(data) {
+  return (data.results || []).map((result) =>
+    projectCard(result, result.summary || "Matched project"),
+  );
+}
+
+function recentCards(data) {
+  return (data.projects || []).map((project) =>
+    projectCard(project, `${shortDate(project.last_modified)}${project.cluster_label ? ` · ${project.cluster_label}` : ""}`),
+  );
+}
+
+function projectCard(project, meta) {
+  const card = document.createElement("div");
+  card.className = "atlas-chat-card";
+  const title = escapeHtml(project.title || project.id || "Untitled project");
+  const body = `
+    <strong>${title}</strong>
+    ${meta ? `<span class="atlas-chat-card-meta">${escapeHtml(meta)}</span>` : ""}
+  `;
+  const url = safeChatUrl(project.url);
+  card.innerHTML = url
+    ? `<a href="${escapeHtml(url)}" target="_blank" rel="noreferrer noopener">${body}</a>`
+    : body;
+  return card;
+}
+
+function barCard(label, count, max, url = "", meta = "") {
+  const card = document.createElement("div");
+  card.className = "atlas-chat-card";
+  const width = Math.max(8, Math.min(100, (Number(count || 0) / max) * 100)).toFixed(0);
+  const title = escapeHtml(label || "");
+  const safeUrl = safeChatUrl(url);
+  const heading = safeUrl
+    ? `<a href="${escapeHtml(safeUrl)}" target="_blank" rel="noreferrer noopener"><strong>${title}</strong></a>`
+    : `<strong>${title}</strong>`;
+  card.innerHTML = `
+    ${heading}
+    <span class="atlas-search-score" aria-hidden="true"><i style="width: ${width}%"></i></span>
+    <span class="atlas-chat-card-meta">${escapeHtml(meta || `${count} projects`)}</span>
+  `;
+  return card;
+}
+
+function safeChatUrl(url) {
+  // Card hrefs come from crawled metadata; only plain web links are clickable.
+  const value = String(url || "");
+  return /^https?:\/\//i.test(value) ? value : "";
+}
+
+function chatChipButton(label, onClick) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.textContent = label;
+  button.addEventListener("click", onClick);
+  return button;
+}
+
+function renderAtlasChatSuggestions() {
+  if (!atlasChatSuggestionsEl) return;
+  atlasChatSuggestionsEl.replaceChildren();
+  if (atlasChatMessages.length) return;
+  for (const suggestion of ATLAS_CHAT_SUGGESTIONS) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.textContent = suggestion;
+    button.addEventListener("click", () => runAtlasChatTurn(suggestion));
+    atlasChatSuggestionsEl.append(button);
+  }
+}
+
+/* --- chat -> map cooperation ---------------------------------------------- */
+
+function applyChatMapAction(action) {
+  if (!action || !dashboardData) return;
+  switch (action.type) {
+    case "clear_filters":
+      selectedClusterId = "";
+      selectedQuestId = "";
+      atlasSearchResultIds = new Set();
+      break;
+    case "filter_cluster": {
+      // Cluster ids are unstable across refreshes; resolve the label live.
+      const wanted = String(action.label || "").toLowerCase();
+      const cluster = (dashboardData.clusters || []).find(
+        (entry) => String(entry.label || "").toLowerCase() === wanted,
+      );
+      if (cluster) selectedClusterId = cluster.id;
+      break;
+    }
+    case "filter_quest":
+      selectedQuestId = String(action.quest || "");
+      break;
+    case "highlight_projects": {
+      const ids = (action.ids || []).filter(Boolean);
+      atlasSearchResultIds = new Set(ids);
+      if (ids.length) selectedProjectId = ids[0];
+      break;
+    }
+    default:
+      return;
+  }
+  chatMapActionApplied = true;
+  renderDashboard(dashboardData);
+}
+
+function clearChatMapAction() {
+  // "Clear" rather than snapshot-rollback: a rollback would silently revert any
+  // manual cluster/quest clicks the user made after the chat action.
+  if (!dashboardData) return;
+  selectedClusterId = "";
+  selectedQuestId = "";
+  atlasSearchResultIds = new Set();
+  chatMapActionApplied = false;
+  renderDashboard(dashboardData);
+}
+
+function renderChatActionChip() {
+  if (!atlasChatActionEl) return;
+  // Describe the LIVE filter state so a manual sidebar click can never desync the chip.
+  const description = liveMapStateCopy();
+  if (!chatMapActionApplied || !description) {
+    atlasChatActionEl.hidden = true;
+    atlasChatActionEl.replaceChildren();
+    return;
+  }
+  atlasChatActionEl.hidden = false;
+  atlasChatActionEl.replaceChildren();
+  const copy = document.createElement("span");
+  copy.innerHTML = `Map: <strong>${escapeHtml(description)}</strong>`;
+  const clear = document.createElement("button");
+  clear.type = "button";
+  clear.className = "atlas-chat-undo";
+  clear.textContent = "Clear";
+  clear.addEventListener("click", clearChatMapAction);
+  atlasChatActionEl.append(copy, clear);
+}
+
+function liveMapStateCopy() {
+  if (!dashboardData) return "";
+  const parts = [];
+  if (selectedClusterId) {
+    const cluster = (dashboardData.clusters || []).find((entry) => entry.id === selectedClusterId);
+    if (cluster) parts.push(`cluster ${cluster.label}`);
+  }
+  if (selectedQuestId) parts.push(`quest ${selectedQuestId}`);
+  if (atlasSearchResultIds.size && !atlasSearchQuery) {
+    parts.push(`${atlasSearchResultIds.size} highlighted`);
+  }
+  return parts.join(" · ");
+}
+
+function scrollAtlasChatLog() {
+  if (atlasChatLogEl) atlasChatLogEl.scrollTop = atlasChatLogEl.scrollHeight;
+}
+
+function announceAtlasChat(text) {
+  // One announcement per finished answer; live-updating the whole log would make
+  // screen readers re-read every streamed token.
+  const status = document.querySelector("#atlas-chat-status");
+  if (status) status.textContent = text || "";
+}

static/index.html

@@ -40,6 +40,10 @@
       <symbol id="icon-x" viewBox="0 0 24 24">
         <path d="M6 6l12 12M18 6L6 18" />
       </symbol>
+      <symbol id="icon-chat" viewBox="0 0 24 24">
+        <path d="M4 5h16v11H9l-5 4z" />
+        <path d="M8 9h8M8 12h5" />
+      </symbol>
       <symbol id="icon-check" viewBox="0 0 24 24">
         <path d="M5 12l4 4 10-11" />
       </symbol>
@@ -80,6 +84,17 @@
               <svg class="icon"><use href="#icon-reset"></use></svg>
               Refresh map
             </button>
+            <button
+              id="open-atlas-chat"
+              class="btn btn-ghost"
+              type="button"
+              title="Chat with the atlas guide"
+              aria-haspopup="dialog"
+              aria-controls="atlas-chat"
+            >
+              <svg class="icon"><use href="#icon-chat"></use></svg>
+              Ask the atlas
+            </button>
             <button id="open-advisor" class="btn btn-ink" type="button" title="Open the idea advisor">
               <svg class="icon"><use href="#icon-quill"></use></svg>
               Open advisor
@@ -121,6 +136,46 @@
             </section>
           </aside>
         </section>
+
+        <div id="atlas-chat-scrim" class="atlas-chat-scrim" hidden></div>
+        <aside
+          id="atlas-chat"
+          class="atlas-chat-drawer"
+          role="dialog"
+          aria-modal="false"
+          aria-label="Atlas guide chat"
+          hidden
+        >
+          <header class="atlas-chat-header">
+            <div class="atlas-chat-title">
+              <p class="atlas-kicker">Atlas guide</p>
+              <h2>Ask the field</h2>
+            </div>
+            <div class="atlas-chat-header-actions">
+              <button id="atlas-chat-clear" class="atlas-chat-iconbtn" type="button" title="Clear conversation">
+                <svg class="icon"><use href="#icon-reset"></use></svg>
+              </button>
+              <button id="atlas-chat-close" class="atlas-chat-iconbtn" type="button" title="Close chat" aria-label="Close chat">
+                <svg class="icon"><use href="#icon-x"></use></svg>
+              </button>
+            </div>
+          </header>
+          <div id="atlas-chat-action" class="atlas-chat-action" hidden></div>
+          <div id="atlas-chat-log" class="atlas-chat-log"></div>
+          <div id="atlas-chat-status" class="sr-only" role="status" aria-live="polite"></div>
+          <div id="atlas-chat-suggestions" class="atlas-chat-suggestions"></div>
+          <form id="atlas-chat-form" class="atlas-chat-composer">
+            <label class="sr-only" for="atlas-chat-input">Ask about the atlas</label>
+            <input
+              id="atlas-chat-input"
+              type="text"
+              autocomplete="off"
+              spellcheck="false"
+              placeholder="Ask what everyone is building..."
+            />
+            <button id="atlas-chat-send" class="btn btn-ink" type="submit">Ask</button>
+          </form>
+        </aside>
       </section>
     </main>
 

static/styles.css

@@ -2073,3 +2073,409 @@ textarea:disabled {
   background: rgba(154, 43, 34, 0.1);
   color: var(--oxblood);
 }
+
+/* Atlas chat drawer (the "Ask the atlas" guide) */
+.atlas-chat-scrim {
+  position: absolute;
+  inset: 0;
+  z-index: 5;
+  display: none; /* desktop chat is non-modal: the map stays interactive */
+  background: rgba(39, 26, 14, 0.34);
+}
+
+.atlas-chat-drawer {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 6;
+  display: flex;
+  flex-direction: column;
+  width: min(400px, 92%);
+  color: var(--ink);
+  background:
+    linear-gradient(180deg, var(--paper-3), var(--paper) 22%, var(--paper) 82%, var(--paper-2)),
+    var(--paper);
+  border-left: 1px solid var(--edge);
+  box-shadow: -26px 0 54px -18px rgba(0, 0, 0, 0.5);
+  transform: translateX(103%);
+  transition: transform 0.28s ease;
+}
+
+.atlas-chat-drawer.open {
+  transform: translateX(0);
+}
+
+.atlas-chat-drawer[hidden] {
+  display: none;
+}
+
+.atlas-chat-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 18px 18px 12px;
+  border-bottom: 1px solid var(--rule);
+}
+
+.atlas-chat-title h2 {
+  margin: 0;
+  font-family: var(--serif);
+  font-size: 1.18rem;
+  line-height: 1.1;
+}
+
+.atlas-chat-header-actions {
+  display: flex;
+  gap: 6px;
+}
+
+.atlas-chat-iconbtn {
+  display: grid;
+  place-items: center;
+  width: 30px;
+  height: 30px;
+  padding: 0;
+  color: var(--ink-soft);
+  background: rgba(255, 247, 224, 0.4);
+  border: 1px solid var(--rule-soft);
+  border-radius: 7px;
+  cursor: pointer;
+}
+
+.atlas-chat-iconbtn:hover {
+  color: var(--oxblood);
+  border-color: rgba(154, 43, 34, 0.4);
+}
+
+.atlas-chat-iconbtn .icon {
+  width: 14px;
+  height: 14px;
+}
+
+.atlas-chat-action {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 10px 16px 0;
+  padding: 7px 10px;
+  color: var(--ink-soft);
+  background: rgba(176, 125, 18, 0.1);
+  border: 1px solid rgba(176, 125, 18, 0.35);
+  border-radius: 999px;
+  font-family: var(--label);
+  font-size: 0.68rem;
+  font-weight: 760;
+}
+
+.atlas-chat-action strong {
+  color: var(--ink);
+}
+
+.atlas-chat-action .atlas-chat-undo {
+  margin-left: auto;
+  padding: 2px 8px;
+  color: var(--oxblood);
+  background: none;
+  border: 1px solid rgba(154, 43, 34, 0.35);
+  border-radius: 999px;
+  font: inherit;
+  cursor: pointer;
+}
+
+.atlas-chat-log {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 12px;
+  min-height: 0;
+  padding: 14px 16px;
+  overflow-y: auto;
+  scrollbar-width: thin;
+}
+
+.atlas-chat-msg {
+  display: grid;
+  gap: 7px;
+  max-width: 94%;
+}
+
+.atlas-chat-msg.user {
+  justify-self: end;
+  padding: 8px 12px;
+  color: var(--paper-3);
+  background: var(--ink);
+  border-radius: 12px 12px 3px 12px;
+  font-family: var(--serif);
+  font-size: 0.86rem;
+  line-height: 1.4;
+}
+
+.atlas-chat-msg.guide {
+  justify-self: start;
+  width: 100%;
+}
+
+.atlas-chat-label {
+  color: var(--ink-faint);
+  font-family: var(--label);
+  font-size: 0.6rem;
+  font-weight: 850;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.atlas-chat-prose {
+  padding: 9px 12px;
+  background: rgba(255, 247, 224, 0.5);
+  border: 1px solid var(--rule-soft);
+  border-left: 3px solid var(--gold);
+  border-radius: 3px 12px 12px 12px;
+  font-family: var(--serif);
+  font-size: 0.86rem;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+
+.atlas-chat-prose.skipped {
+  border-left-color: var(--leaf);
+}
+
+.atlas-chat-typing {
+  color: var(--ink-faint);
+  font-family: var(--label);
+  font-size: 0.7rem;
+  font-weight: 760;
+  animation: breathe 1.6s ease-in-out infinite;
+}
+
+.atlas-chat-think {
+  padding: 6px 10px;
+  background: rgba(73, 49, 22, 0.05);
+  border: 1px dashed var(--rule-soft);
+  border-radius: 7px;
+}
+
+.atlas-chat-think[hidden] {
+  display: none;
+}
+
+.atlas-chat-think summary {
+  color: var(--ink-faint);
+  cursor: pointer;
+  font-family: var(--label);
+  font-size: 0.62rem;
+  font-weight: 850;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.atlas-chat-think-text {
+  margin-top: 6px;
+  max-height: 220px;
+  overflow-y: auto;
+  color: var(--ink-soft);
+  font-family: var(--serif);
+  font-size: 0.76rem;
+  font-style: italic;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  scrollbar-width: thin;
+}
+
+.atlas-chat-cards {
+  display: grid;
+  gap: 7px;
+}
+
+.atlas-chat-card {
+  display: grid;
+  gap: 5px;
+  padding: 9px 11px;
+  background: rgba(255, 247, 224, 0.38);
+  border: 1px solid var(--rule-soft);
+  border-left: 3px solid var(--leaf);
+  border-radius: 7px;
+}
+
+.atlas-chat-card strong {
+  font-family: var(--serif);
+  font-size: 0.84rem;
+  line-height: 1.2;
+}
+
+.atlas-chat-card a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.atlas-chat-card a:hover strong {
+  color: var(--oxblood);
+}
+
+.atlas-chat-card-meta {
+  color: var(--ink-faint);
+  font-family: var(--label);
+  font-size: 0.66rem;
+  font-weight: 760;
+  line-height: 1.35;
+}
+
+.atlas-chat-excerpt {
+  margin: 0;
+  max-height: 180px;
+  overflow-y: auto;
+  color: var(--ink-soft);
+  font-family: var(--serif);
+  font-size: 0.78rem;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+  scrollbar-width: thin;
+}
+
+.atlas-chat-code {
+  margin: 0;
+  max-height: 200px;
+  overflow: auto;
+  padding: 7px 9px;
+  color: var(--ink-soft);
+  background: rgba(73, 49, 22, 0.07);
+  border-radius: 6px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.66rem;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  scrollbar-width: thin;
+}
+
+.atlas-chat-statline {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  padding: 8px 11px;
+  background: rgba(73, 49, 22, 0.06);
+  border: 1px solid var(--rule-soft);
+  border-radius: 7px;
+}
+
+.atlas-chat-statline span {
+  color: var(--ink-soft);
+  font-family: var(--label);
+  font-size: 0.68rem;
+  font-weight: 800;
+}
+
+.atlas-chat-statline strong {
+  color: var(--ink);
+  font-family: var(--serif);
+  font-size: 0.9rem;
+}
+
+.atlas-chat-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.atlas-chat-chips button,
+.atlas-chat-chips span {
+  padding: 4px 8px;
+  color: var(--ink-soft);
+  background: rgba(73, 49, 22, 0.08);
+  border: 1px solid var(--rule-soft);
+  border-radius: 999px;
+  font-family: var(--label);
+  font-size: 0.66rem;
+  font-weight: 800;
+}
+
+.atlas-chat-chips button {
+  cursor: pointer;
+}
+
+.atlas-chat-chips button:hover {
+  color: var(--leaf);
+  border-color: rgba(47, 107, 65, 0.4);
+}
+
+.atlas-chat-empty {
+  display: grid;
+  gap: 8px;
+  padding: 10px 12px;
+  background: rgba(176, 125, 18, 0.08);
+  border: 1px dashed rgba(176, 125, 18, 0.45);
+  border-radius: 7px;
+  color: var(--ink-soft);
+  font-family: var(--label);
+  font-size: 0.7rem;
+  font-weight: 700;
+}
+
+.atlas-chat-suggestions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 0 16px 10px;
+}
+
+.atlas-chat-suggestions button {
+  padding: 5px 10px;
+  color: var(--ink-soft);
+  background: rgba(255, 247, 224, 0.45);
+  border: 1px solid var(--rule-soft);
+  border-radius: 999px;
+  font-family: var(--label);
+  font-size: 0.68rem;
+  font-weight: 760;
+  cursor: pointer;
+}
+
+.atlas-chat-suggestions button:hover {
+  color: var(--oxblood);
+  border-color: rgba(154, 43, 34, 0.4);
+}
+
+.atlas-chat-composer {
+  display: flex;
+  gap: 8px;
+  padding: 12px 16px 16px;
+  border-top: 1px solid var(--rule);
+}
+
+.atlas-chat-composer input {
+  flex: 1;
+  min-width: 0;
+  padding: 9px 12px;
+  color: var(--ink);
+  background: rgba(255, 247, 224, 0.6);
+  border: 1px solid var(--edge);
+  border-radius: 8px;
+  font-family: var(--serif);
+  font-size: 0.86rem;
+}
+
+.atlas-chat-composer input:focus {
+  outline: 2px solid var(--gold-glow);
+  border-color: var(--gold);
+}
+
+.atlas-chat-fallback {
+  color: var(--oxblood);
+  font-family: var(--label);
+  font-size: 0.66rem;
+  font-weight: 760;
+}
+
+@media (max-width: 760px) {
+  .atlas-chat-drawer {
+    width: 100%;
+    border-left: none;
+  }
+
+  .atlas-chat-scrim:not([hidden]) {
+    display: block;
+  }
+}

tests/test_app.py

@@ -4,6 +4,9 @@ import time
 from io import BytesIO
 from zipfile import ZipFile
 
+import pytest
+from fastapi import HTTPException
+
 import app as app_module
 from app import (
     agent_turn_stream,
@@ -12,6 +15,7 @@ from app import (
     chapter_api,
     chapter_artifact,
     dashboard,
+    dashboard_chat_stream,
     dashboard_search,
     dashboard_refresh_start,
     dashboard_refresh_status,
@@ -583,6 +587,120 @@ def test_agent_turn_stream_runs_on_cpu_compute() -> None:
     assert lines[-1]["state"]["ideas"]
 
 
+def _run_dashboard_chat(payload: dict) -> list[dict]:
+    response = dashboard_chat_stream(payload)
+    assert response.media_type == "application/x-ndjson"
+    body = asyncio.run(_read_streaming_response(response))
+    return [json.loads(line) for line in body.splitlines()]
+
+
+def test_dashboard_chat_stream_exports_ndjson_events() -> None:
+    lines = _run_dashboard_chat({"message": "what clusters exist on the map?"})
+    types = [line["type"] for line in lines]
+
+    assert types[0] == "start"
+    assert types[-1] == "done"
+    tool_call = next(line for line in lines if line["type"] == "tool_call")
+    assert tool_call["status"] == "valid"
+    assert tool_call["name"] == "list_clusters"
+    tool_result = next(line for line in lines if line["type"] == "tool_result")
+    assert tool_result["data"]["clusters"]
+    assert types.index("tool_result") < types.index("token")
+    done = lines[-1]
+    assert done["response"]
+    assert done["history"][-1]["role"] == "assistant"
+
+
+def test_dashboard_chat_stream_skips_answer_for_unanalyzed_quests() -> None:
+    lines = _run_dashboard_chat({"message": "who completed the most quests?"})
+    types = [line["type"] for line in lines]
+
+    tool_call = next(line for line in lines if line["type"] == "tool_call")
+    assert tool_call["name"] == "top_projects_by_quests"
+    skipped = next(line for line in lines if line["type"] == "answer_skipped")
+    assert skipped["reason"] == "quests_not_analyzed"
+    assert "token" not in types
+    assert lines[-1]["response"] == skipped["text"]
+
+
+def test_dashboard_chat_stream_emits_map_action_for_overview() -> None:
+    lines = _run_dashboard_chat({"message": "what is everyone building right now?"})
+
+    tool_result = next(line for line in lines if line["type"] == "tool_result")
+    assert tool_result["tool"] == "atlas_overview"
+    assert tool_result["map_action"] == {"type": "clear_filters"}
+    assert tool_result["data"]["project_count"] == len(index.projects)
+
+
+def test_dashboard_chat_stream_round_trips_history() -> None:
+    first = _run_dashboard_chat({"message": "what clusters exist?"})
+    history = first[-1]["history"]
+    assert history[-2]["content"] == "what clusters exist?"
+
+    second = _run_dashboard_chat(
+        {"message": "what changed recently?", "history_json": json.dumps(history)}
+    )
+
+    # The rules backend answers every turn with the same fixed sentence, and repeated
+    # assistant lines are deliberately deduplicated — so assert the round trip keeps
+    # the latest turn rather than a fixed length.
+    final_history = second[-1]["history"]
+    assert {"role": "user", "content": "what changed recently?"} in final_history
+    assert final_history[-1]["role"] == "assistant"
+
+
+def test_dashboard_chat_stream_runs_on_cpu_compute() -> None:
+    lines = _run_dashboard_chat({"message": "what clusters exist?", "compute": "cpu"})
+
+    assert lines[0]["type"] == "start"
+    assert lines[-1]["type"] == "done"
+
+
+def test_dashboard_chat_stream_requires_message() -> None:
+    with pytest.raises(HTTPException) as error:
+        dashboard_chat_stream({"message": "   "})
+
+    assert error.value.status_code == 400
+
+
+class _QuotaError(Exception):
+    pass
+
+
+def test_dashboard_chat_falls_back_to_cpu_on_pre_stream_quota_error(monkeypatch) -> None:
+    def quota_stream(message, history):
+        raise _QuotaError("gpu quota exceeded")
+        yield  # pragma: no cover - makes this a generator
+
+    monkeypatch.setattr(app_module, "_primary_chat_stream", quota_stream)
+    monkeypatch.setattr(app_module, "is_gpu_quota_error", lambda error: isinstance(error, _QuotaError))
+
+    events = list(app_module._profiled_chat_events("what clusters exist?", "[]", "gpu"))
+
+    types = [event["type"] for event in events]
+    assert types[0] == "fallback"
+    assert types.count("start") == 1
+    assert types.count("done") == 1
+
+
+def test_dashboard_chat_does_not_restart_after_mid_stream_failure(monkeypatch) -> None:
+    def mid_stream_failure(message, history):
+        yield {"type": "start", "normalized_text": message, "corrections": []}
+        raise _QuotaError("gpu quota exceeded")
+
+    monkeypatch.setattr(app_module, "_primary_chat_stream", mid_stream_failure)
+    monkeypatch.setattr(app_module, "is_gpu_quota_error", lambda error: isinstance(error, _QuotaError))
+
+    events = []
+    with pytest.raises(_QuotaError):
+        for event in app_module._profiled_chat_events("what clusters exist?", "[]", "gpu"):
+            events.append(event)
+
+    # A mid-stream failure must re-raise, never silently restart on CPU and emit
+    # a second start/done into the same NDJSON stream.
+    assert [event["type"] for event in events] == ["start"]
+
+
 def test_transcribe_audio_endpoint_saves_audio(monkeypatch) -> None:
     captured = {}
 

tests/test_dashboard_chat.py

@@ -0,0 +1,487 @@
+from hackathon_advisor.dashboard_chat import DashboardChatEngine
+from tests.test_dashboard_repository import analyzed_repository, not_analyzed_repository
+
+
+class ScriptedRunner:
+    """ChatRunner double that replays prepared model outputs and records calls."""
+
+    backend = "scripted"
+    model_id = "scripted-test-model"
+    supports_thinking = False
+
+    def __init__(self, outputs: list[object]) -> None:
+        self.outputs = list(outputs)
+        self.calls: list[dict] = []
+
+    def stream(self, messages, *, tools=None, max_new_tokens, enable_thinking=False):
+        self.calls.append(
+            {
+                "messages": messages,
+                "tools": tools,
+                "max_new_tokens": max_new_tokens,
+                "enable_thinking": enable_thinking,
+            }
+        )
+        output = self.outputs.pop(0)
+        pieces = output if isinstance(output, list) else [output]
+        for count, piece in enumerate(pieces, start=1):
+            yield count, piece
+
+
+class ThinkingScriptedRunner(ScriptedRunner):
+    """ScriptedRunner whose outputs start inside a <think> block (native thinking)."""
+
+    supports_thinking = True
+
+
+def run_turn(runner, repository, message, history=None):
+    engine = DashboardChatEngine(runner, lambda: repository)
+    return list(engine.turn_stream(message, history))
+
+
+def events_of(events, event_type):
+    return [event for event in events if event["type"] == event_type]
+
+
+def test_tool_turn_streams_verified_data_before_prose() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="top_projects_by_quests"></function>',
+            "Project 9 leads with two quests.",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "who completed the most quests?")
+
+    tool_call = events_of(events, "tool_call")[0]
+    assert tool_call["status"] == "valid"
+    assert tool_call["name"] == "top_projects_by_quests"
+
+    tool_result = events_of(events, "tool_result")[0]
+    assert tool_result["data"]["rows"][0]["id"] == "build-small-hackathon/project-9"
+    assert tool_result["map_action"]["type"] == "highlight_projects"
+
+    types = [event["type"] for event in events]
+    assert types.index("tool_result") < types.index("token")
+
+    done = events_of(events, "done")[0]
+    assert done["response"] == "Project 9 leads with two quests."
+    assert done["tool"] == "top_projects_by_quests"
+    assert done["history"][-2:] == [
+        {"role": "user", "content": "who completed the most quests?"},
+        {"role": "assistant", "content": "Project 9 leads with two quests."},
+    ]
+
+
+def test_model_digest_strips_urls_and_ids() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="top_projects_by_quests"></function>',
+            "Project 9 leads.",
+        ]
+    )
+
+    run_turn(runner, analyzed_repository(), "quest leaderboard")
+
+    answer_call = runner.calls[1]
+    assert answer_call["tools"] is None
+    digest = answer_call["messages"][-1]["content"]
+    assert "url" not in digest
+    assert "huggingface.co" not in digest
+    assert 'title: "Project 9"' in digest
+    assert "quest_count: 2" in digest
+
+
+def test_model_digest_trims_long_listings_and_bm25_total() -> None:
+    repository = analyzed_repository()
+    runner = ScriptedRunner(
+        ['<function name="search_projects"><param name="query">project</param></function>', "Found a few."]
+    )
+    run_turn(runner, repository, "find project planners")
+    search_digest = runner.calls[1]["messages"][-1]["content"]
+    assert "total:" not in search_digest
+
+    runner = ScriptedRunner(['<function name="list_clusters"></function>', "A few clusters."])
+    run_turn(runner, repository, "what clusters exist")
+    cluster_digest = runner.calls[1]["messages"][-1]["content"]
+    # Only the largest cluster is restatable; the full list lives on the UI cards.
+    assert cluster_digest.count("label:") == 1
+    assert f"cluster_count: {repository.list_clusters()['cluster_count']}" in cluster_digest
+
+
+def test_not_analyzed_quests_skip_the_answer_pass() -> None:
+    runner = ScriptedRunner(['<function name="top_projects_by_quests"></function>'])
+
+    events = run_turn(runner, not_analyzed_repository(), "who completed the most quests?")
+
+    skipped = events_of(events, "answer_skipped")[0]
+    assert skipped["reason"] == "quests_not_analyzed"
+    assert events_of(events, "token") == []
+    assert len(runner.calls) == 1  # pass 2 never ran
+    assert events_of(events, "done")[0]["response"] == skipped["text"]
+
+
+def test_empty_search_skips_the_answer_pass() -> None:
+    runner = ScriptedRunner(
+        ['<function name="search_projects"><param name="query">zzzz qqqq</param></function>']
+    )
+
+    events = run_turn(runner, analyzed_repository(), "find zzzz qqqq")
+
+    skipped = events_of(events, "answer_skipped")[0]
+    assert skipped["reason"] == "no_search_results"
+    assert "zzzz qqqq" in skipped["text"]
+    assert len(runner.calls) == 1
+
+
+def test_unknown_cluster_uses_templated_sentence() -> None:
+    runner = ScriptedRunner(
+        ['<function name="show_cluster"><param name="label">flying castles</param></function>']
+    )
+
+    events = run_turn(runner, analyzed_repository(), "show me the flying castles cluster")
+
+    skipped = events_of(events, "answer_skipped")[0]
+    assert skipped["reason"] == "unknown_cluster"
+    assert "flying castles" in skipped["text"]
+    assert events_of(events, "tool_result")[0]["map_action"] is None
+
+
+def test_show_cluster_emits_filter_map_action() -> None:
+    repository = analyzed_repository()
+    label = repository.list_clusters()["clusters"][0]["label"]
+    runner = ScriptedRunner(
+        [
+            f'<function name="show_cluster"><param name="label">{label}</param></function>',
+            "That cluster groups the local-first planners.",
+        ]
+    )
+
+    events = run_turn(runner, repository, f"what is in {label}?")
+
+    map_action = events_of(events, "tool_result")[0]["map_action"]
+    assert map_action == {"type": "filter_cluster", "label": label}
+
+
+def test_show_cluster_map_action_carries_canonical_label_for_fuzzy_input() -> None:
+    """The UI resolves filter_cluster by exact label match, so the engine must
+    forward the repository's canonical label, never the user's fuzzy input."""
+    repository = analyzed_repository()
+    canonical = repository.list_clusters()["clusters"][0]["label"]
+    fuzzy = canonical.split()[0].lower()
+    assert fuzzy != canonical
+    runner = ScriptedRunner(
+        [
+            f'<function name="show_cluster"><param name="label">{fuzzy}</param></function>',
+            "Here is that cluster.",
+        ]
+    )
+
+    events = run_turn(runner, repository, f"what is in the {fuzzy} cluster?")
+
+    map_action = events_of(events, "tool_result")[0]["map_action"]
+    assert map_action == {"type": "filter_cluster", "label": canonical}
+
+
+def test_plain_prose_routes_to_dedicated_smalltalk_pass() -> None:
+    runner = ScriptedRunner(
+        [
+            "Hello! Happy to help.",
+            "Hi! Ask me what everyone is building.",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "hello there")
+
+    assert events_of(events, "tool_call")[0]["status"] == "none"
+    assert events_of(events, "tool_result") == []
+    done = events_of(events, "done")[0]
+    assert done["tool"] == ""
+    assert done["response"] == "Hi! Ask me what everyone is building."
+    assert runner.calls[1]["tools"] is None
+
+
+def test_unmatched_data_question_defaults_to_search_not_smalltalk() -> None:
+    """Regression: 'how many voice apps' once slipped into ungrounded small talk."""
+    runner = ScriptedRunner(
+        [
+            "I'm not sure, but I can provide more information if you'd like.",
+            "The closest matches are shown on the cards.",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "how many voice apps")
+
+    tool_call = events_of(events, "tool_call")[0]
+    assert tool_call["status"] == "defaulted"
+    assert tool_call["name"] == "search_projects"
+    assert tool_call["arguments"]["query"] == "how many voice apps"
+
+
+def test_short_followup_stays_on_smalltalk_path() -> None:
+    runner = ScriptedRunner(
+        [
+            "Because it scored well.",
+            "I should look that up rather than guess - ask me about the quest leaderboard!",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "are you sure?")
+
+    assert events_of(events, "tool_call")[0]["status"] == "none"
+    assert events_of(events, "tool_result") == []
+
+
+def test_show_project_streams_readme_and_highlights_the_dot() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="show_project"><param name="project">Project 4</param></function>',
+            "Project 4 is an offline planner; its app file loads gradio.",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "how does Project 4 work?")
+
+    tool_result = events_of(events, "tool_result")[0]
+    assert tool_result["tool"] == "show_project"
+    assert "README evidence for project 4" in tool_result["data"]["readme_excerpt"]
+    assert tool_result["map_action"] == {
+        "type": "highlight_projects",
+        "ids": ["build-small-hackathon/project-4"],
+    }
+    digest = runner.calls[1]["messages"][-1]["content"]
+    assert "README evidence for project 4" in digest
+    assert "import gradio" in digest
+    assert events_of(events, "done")[0]["tool"] == "show_project"
+
+
+def test_show_project_falls_back_to_search_for_unknown_names() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="show_project"><param name="project">offline planner thing</param></function>',
+            "The closest matches are on the cards.",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "tell me about the offline planner thing")
+
+    tool_result = events_of(events, "tool_result")[0]
+    assert tool_result["tool"] == "search_projects"
+    assert tool_result["data"]["results"]
+    assert events_of(events, "done")[0]["tool"] == "search_projects"
+
+
+def test_prose_answer_to_data_question_is_routed_by_intent() -> None:
+    runner = ScriptedRunner(
+        [
+            "I do not have access to quest completion data.",
+            "Project 9 leads with two quests.",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "who completed the most quests?")
+
+    tool_call = events_of(events, "tool_call")[0]
+    assert tool_call["status"] == "defaulted"
+    assert tool_call["name"] == "top_projects_by_quests"
+    assert events_of(events, "tool_result")[0]["data"]["rows"]
+    assert events_of(events, "done")[0]["response"] == "Project 9 leads with two quests."
+
+
+def test_malformed_call_degrades_through_intent_router() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="nonexistent_tool"></function>',
+            "Project 9 leads the quest board.",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "who completed the most quests")
+
+    tool_call = events_of(events, "tool_call")[0]
+    assert tool_call["status"] == "defaulted"
+    assert tool_call["name"] == "top_projects_by_quests"
+    assert tool_call["errors"]
+
+
+def test_stray_function_block_is_cut_from_the_answer() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="atlas_overview"></function>',
+            ["The field has ten projects. ", '<function name="x">', "</function> extra"],
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "overview please")
+
+    done = events_of(events, "done")[0]
+    assert done["response"] == "The field has ten projects."
+    for token in events_of(events, "token"):
+        assert "<function" not in token["text"]
+
+
+def test_thinking_trace_streams_separately_from_the_tool_call() -> None:
+    runner = ThinkingScriptedRunner(
+        [
+            [
+                "The user wants the leaderboard. I could emit ",
+                '<function name="x"> here but the right tool is top_projects_by_quests.',
+                "</th",
+                'ink>\n\n<function name="top_projects_by_quests"></function>',
+            ],
+            ["Let me restate the digest.</think>\n\nProject 9 leads with two quests."],
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "who completed the most quests?")
+
+    thinking_pass1 = [e for e in events if e["type"] == "thinking" and e["pass"] == 1]
+    assert "".join(e["text"] for e in thinking_pass1).startswith("The user wants the leaderboard")
+    # <function inside the REASONING must not be mistaken for the call itself.
+    tool_call = events_of(events, "tool_call")[0]
+    assert tool_call["status"] == "valid"
+    assert tool_call["name"] == "top_projects_by_quests"
+
+    thinking_pass2 = [e for e in events if e["type"] == "thinking" and e["pass"] == 2]
+    assert "".join(e["text"] for e in thinking_pass2) == "Let me restate the digest."
+    done = events_of(events, "done")[0]
+    assert done["response"] == "Project 9 leads with two quests."
+    for token in events_of(events, "token"):
+        assert "</think>" not in token["text"]
+    # Thinking never leaks into the durable history.
+    assert all("Let me restate" not in entry["content"] for entry in done["history"])
+
+
+def test_thinking_marker_split_across_pieces_is_handled() -> None:
+    runner = ThinkingScriptedRunner(
+        [
+            ["step one ", "step two</t", "hink>", '\n\n<function name="list_quests"></function>'],
+            ["ok</think>\n\nThe quests are on the cards."],
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "list the quests")
+
+    thinking = "".join(e["text"] for e in events if e["type"] == "thinking" and e["pass"] == 1)
+    assert thinking == "step one step two"
+    assert events_of(events, "tool_call")[0]["name"] == "list_quests"
+
+
+def test_truncated_thinking_degrades_gracefully() -> None:
+    """A 4096-token cut inside <think> leaves no answer text; the turn must still
+    resolve (intent backstop on pass 1, templated sentence on pass 2)."""
+    runner = ThinkingScriptedRunner(
+        [
+            ["I am still reasoning about which tool to"],  # no </think>, no call
+            ["and the digest says</think>\n\nProject 9 leads."],
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "who completed the most quests?")
+
+    tool_call = events_of(events, "tool_call")[0]
+    assert tool_call["status"] == "defaulted"
+    assert tool_call["name"] == "top_projects_by_quests"
+    assert events_of(events, "done")[0]["response"] == "Project 9 leads."
+
+
+def test_chat_generations_use_thinking_and_4096_budget() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="atlas_overview"></function>',
+            "Ten projects in view.",
+        ]
+    )
+
+    events = run_turn(runner, analyzed_repository(), "overview")
+
+    for call in runner.calls:
+        assert call["enable_thinking"] is True
+        assert call["max_new_tokens"] >= 4096
+    for progress in events_of(events, "model_progress"):
+        assert progress["max_tokens"] >= 4096
+
+
+def test_history_drops_repeated_assistant_answers() -> None:
+    """Regression: a greedy 1B echoes any sentence that appears twice in history."""
+    runner = ScriptedRunner(
+        [
+            '<function name="atlas_overview"></function>',
+            "Ten projects in view.",
+        ]
+    )
+    looping_history = [
+        {"role": "user", "content": "why"},
+        {"role": "assistant", "content": "I should look that up."},
+        {"role": "user", "content": "are you sure?"},
+        {"role": "assistant", "content": "I should look that up."},
+        {"role": "user", "content": "really?"},
+        {"role": "assistant", "content": "I should look that up."},
+    ]
+
+    run_turn(runner, analyzed_repository(), "overview", looping_history)
+
+    pass1_messages = runner.calls[0]["messages"]
+    repeated = [m for m in pass1_messages if m.get("content") == "I should look that up."]
+    assert len(repeated) == 1
+
+
+def test_grounded_answer_pass_sees_no_history() -> None:
+    """Echoes regression: with history in the prompt, a greedy 1B repeats prior
+    answers instead of reading the digest. Facts come from the digest alone."""
+    runner = ScriptedRunner(
+        [
+            '<function name="atlas_overview"></function>',
+            "Ten projects in view.",
+        ]
+    )
+    long_history = []
+    for index in range(6):
+        long_history.append({"role": "user", "content": f"question {index}"})
+        long_history.append({"role": "assistant", "content": f"answer {index}"})
+
+    run_turn(runner, analyzed_repository(), "overview", long_history)
+
+    answer_messages = runner.calls[1]["messages"]
+    roles = [m["role"] for m in answer_messages]
+    assert roles == ["system", "user", "assistant", "tool"]
+
+
+def test_overview_digest_leads_with_most_liked_projects() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="atlas_overview"></function>',
+            "Project 9 is the most liked.",
+        ]
+    )
+
+    run_turn(runner, analyzed_repository(), "what is the coolest project?")
+
+    digest = runner.calls[1]["messages"][-1]["content"]
+    assert digest.startswith("most_liked_projects:")
+    assert "most_completed_quests:" in digest
+
+
+def test_history_is_normalized_and_capped() -> None:
+    runner = ScriptedRunner(
+        [
+            '<function name="atlas_overview"></function>',
+            "Ten projects in view.",
+        ]
+    )
+    junk_history = [
+        {"role": "user", "content": "old question"},
+        {"role": "assistant", "content": "old answer"},
+        {"role": "tool", "content": "should be dropped"},
+        "not even a dict",
+        {"role": "user", "content": ""},
+    ]
+
+    events = run_turn(runner, analyzed_repository(), "overview", junk_history)
+
+    pass1_messages = runner.calls[0]["messages"]
+    roles = [message["role"] for message in pass1_messages]
+    assert roles == ["system", "user", "assistant", "user"]
+    done = events_of(events, "done")[0]
+    assert all(entry["role"] in ("user", "assistant") for entry in done["history"])
+    assert len(done["history"]) <= 12

tests/test_dashboard_chat_contracts.py

@@ -0,0 +1,179 @@
+import pytest
+
+from hackathon_advisor.dashboard_chat_contracts import (
+    CHAT_TOOL_SPECS,
+    chat_tool_schemas,
+    heuristic_chat_call,
+    parse_native_tool_call,
+    resolve_chat_tool_call,
+    strip_function_blocks,
+)
+from hackathon_advisor.tool_contracts import ToolContractError
+
+
+def test_chat_tool_schemas_are_openai_style() -> None:
+    schemas = chat_tool_schemas()
+
+    assert len(schemas) == len(CHAT_TOOL_SPECS) == 9
+    for schema in schemas:
+        assert schema["type"] == "function"
+        assert schema["function"]["parameters"]["type"] == "object"
+
+
+def test_parse_native_tool_call_reads_params() -> None:
+    call = parse_native_tool_call(
+        '<function name="search_projects"><param name="query">voice agents</param></function>'
+    )
+
+    assert call.name == "search_projects"
+    assert call.arguments == {"query": "voice agents"}
+
+
+def test_parse_native_tool_call_handles_cdata_and_surrounding_prose() -> None:
+    call = parse_native_tool_call(
+        'Let me look that up.\n<function name="show_cluster">'
+        "<param name=\"label\"><![CDATA[Voice / Chatbot & ASR]]></param></function> Done."
+    )
+
+    assert call.name == "show_cluster"
+    assert call.arguments == {"label": "Voice / Chatbot & ASR"}
+
+
+def test_parse_native_tool_call_without_params() -> None:
+    call = parse_native_tool_call('<function name="list_quests"></function>')
+
+    assert call.name == "list_quests"
+    assert call.arguments == {}
+
+
+def test_parse_native_tool_call_rejects_garbage() -> None:
+    with pytest.raises(ToolContractError):
+        parse_native_tool_call('<function name="x"><param name="q">unclosed</function>')
+    with pytest.raises(ToolContractError):
+        parse_native_tool_call("just prose, no call")
+    with pytest.raises(ToolContractError):
+        parse_native_tool_call('<function><param name="q">missing name</param></function>')
+
+
+def test_resolve_marks_plain_prose_as_none() -> None:
+    resolution = resolve_chat_tool_call("Hello! Ask me about the atlas.", fallback_query="hello")
+
+    assert resolution.status == "none"
+    assert resolution.call is None
+    assert resolution.errors == ()
+
+
+def test_resolve_accepts_valid_call() -> None:
+    resolution = resolve_chat_tool_call(
+        '<function name="show_quest"><param name="quest">Tiny Titan</param></function>',
+        fallback_query="tiny titan",
+    )
+
+    assert resolution.status == "valid"
+    assert resolution.call is not None
+    assert resolution.call.name == "show_quest"
+
+
+def test_resolve_defaults_unknown_tool_through_intent_router() -> None:
+    resolution = resolve_chat_tool_call(
+        '<function name="made_up_tool"></function>',
+        fallback_query="who completed the most quests?",
+    )
+
+    assert resolution.status == "defaulted"
+    assert resolution.call is not None
+    assert resolution.call.name == "top_projects_by_quests"
+    assert resolution.errors
+
+
+def test_resolve_defaults_malformed_xml_to_search() -> None:
+    resolution = resolve_chat_tool_call(
+        '<function name="search_projects"><param name="query">a < b</param></function>',
+        fallback_query="projects about voice",
+    )
+
+    assert resolution.status == "defaulted"
+    assert resolution.call is not None
+    assert resolution.call.name == "search_projects"
+    assert resolution.call.arguments["query"] == "projects about voice"
+
+
+def test_resolve_rejects_missing_required_argument() -> None:
+    resolution = resolve_chat_tool_call(
+        '<function name="show_cluster"></function>',
+        fallback_query="show me the voice cluster",
+    )
+
+    assert resolution.status == "defaulted"
+    assert resolution.errors
+
+
+def test_heuristic_chat_call_routes_intents() -> None:
+    assert heuristic_chat_call("who completed the most quests").name == "top_projects_by_quests"
+    assert heuristic_chat_call("what clusters exist").name == "list_clusters"
+    assert heuristic_chat_call("list the quests please").name == "list_quests"
+    assert heuristic_chat_call("what changed recently").name == "recent_activity"
+    assert heuristic_chat_call("what is everyone building").name == "atlas_overview"
+    assert heuristic_chat_call("knitting helpers").name == "search_projects"
+    assert heuristic_chat_call("").name == "atlas_overview"
+
+
+def test_data_intent_call_separates_detail_from_listing() -> None:
+    from hackathon_advisor.dashboard_chat_contracts import data_intent_call
+
+    detail = data_intent_call("what is in the Dream / Oracle cluster?")
+    assert detail is not None and detail.name == "show_cluster"
+    assert "Dream / Oracle" in detail.arguments["label"]
+
+    quest_detail = data_intent_call("tell me about the Tiny Titan quest")
+    assert quest_detail is not None and quest_detail.name == "show_quest"
+
+    assert data_intent_call("what clusters exist").name == "list_clusters"
+    assert data_intent_call("find projects about voice").name == "search_projects"
+    assert data_intent_call("how many voice apps").name == "search_projects"
+    assert data_intent_call("what is the coolest project?").name == "atlas_overview"
+    assert data_intent_call("which project is most liked").name == "atlas_overview"
+    assert data_intent_call("hello there") is None
+    assert data_intent_call("thanks!") is None
+
+
+def test_data_intent_call_routes_project_reading() -> None:
+    from hackathon_advisor.dashboard_chat_contracts import data_intent_call
+
+    readme = data_intent_call("read the readme of Jawbreaker")
+    assert readme is not None and readme.name == "show_project"
+
+    how = data_intent_call("how does Jawbreaker work?")
+    assert how is not None and how.name == "show_project"
+
+    about = data_intent_call("tell me about Jawbreaker")
+    assert about is not None and about.name == "show_project"
+    assert about.arguments["project"] == "tell me about Jawbreaker"
+
+    # cluster/quest detail intents keep their own tools
+    assert data_intent_call("tell me about the Tiny Titan quest").name == "show_quest"
+    assert data_intent_call("what is in the Dream / Oracle cluster?").name == "show_cluster"
+
+
+def test_smalltalk_intent_only_matches_greetings_and_followups() -> None:
+    from hackathon_advisor.dashboard_chat_contracts import smalltalk_intent
+
+    assert smalltalk_intent("hello!")
+    assert smalltalk_intent("hey there")
+    assert smalltalk_intent("thanks")
+    assert smalltalk_intent("why")
+    assert smalltalk_intent("are you sure?")
+    assert smalltalk_intent("who are you")
+    assert smalltalk_intent("")
+
+    assert not smalltalk_intent("how many voice apps")
+    assert not smalltalk_intent("what is the coolest project?")
+    assert not smalltalk_intent("voice agents for elderly care")
+    assert not smalltalk_intent("knitting helpers")
+
+
+def test_strip_function_blocks_removes_stray_calls() -> None:
+    text = 'Here you go. <function name="x"><param name="q">v</param></function> The map shows it.'
+
+    assert strip_function_blocks(text) == "Here you go.  The map shows it.".strip()
+    assert strip_function_blocks("plain prose") == "plain prose"

tests/test_dashboard_repository.py

@@ -0,0 +1,247 @@
+from hackathon_advisor.dashboard import build_dashboard_payload
+from hackathon_advisor.dashboard_repository import DashboardRepository
+from hackathon_advisor.dashboard_search import DashboardSearchIndex
+from hackathon_advisor.data import Project, ProjectIndex, build_index_payload
+
+
+def test_overview_reports_counts_clusters_and_quests() -> None:
+    repository = analyzed_repository()
+
+    overview = repository.overview()
+
+    assert overview["project_count"] == 10
+    assert overview["cluster_count"] >= 1
+    assert overview["quest_status"] == "analyzed"
+    assert overview["top_clusters"][0]["project_count"] >= 1
+    assert overview["top_quests"][0]["project_count"] >= 1
+    assert overview["most_liked"][0]["title"] == "Project 9"
+
+
+def test_overview_handles_not_analyzed_quests() -> None:
+    repository = not_analyzed_repository()
+
+    overview = repository.overview()
+
+    assert overview["quest_status"] == "not_analyzed"
+    assert overview["top_quests"] == []
+
+
+def test_list_clusters_returns_labels_not_ids() -> None:
+    repository = analyzed_repository()
+
+    listing = repository.list_clusters()
+
+    assert listing["cluster_count"] == len(listing["clusters"])
+    for cluster in listing["clusters"]:
+        assert cluster["label"]
+        assert not cluster["label"].startswith("cluster-")
+        assert cluster["project_count"] >= 1
+
+
+def test_cluster_detail_resolves_fuzzy_label_and_id() -> None:
+    repository = analyzed_repository()
+    first = repository.list_clusters()["clusters"][0]
+
+    by_label = repository.cluster_detail(first["label"])
+    by_lower = repository.cluster_detail(first["label"].lower())
+    by_id = repository.cluster_detail("cluster-1")
+
+    assert by_label is not None and by_label["label"] == first["label"]
+    assert by_lower is not None and by_lower["label"] == first["label"]
+    assert by_id is not None
+    assert by_label["examples"]
+    assert by_label["examples"][0]["id"].startswith("build-small-hackathon/")
+
+
+def test_cluster_detail_returns_none_for_unknown_label() -> None:
+    repository = analyzed_repository()
+
+    assert repository.cluster_detail("totally unrelated nonsense xyz") is None
+    assert repository.cluster_detail("") is None
+
+
+def test_list_quests_sorted_by_coverage() -> None:
+    repository = analyzed_repository()
+
+    listing = repository.list_quests()
+
+    counts = [quest["project_count"] for quest in listing["quests"]]
+    assert listing["status"] == "analyzed"
+    assert counts == sorted(counts, reverse=True)
+    assert counts[0] >= 1
+
+
+def test_quest_detail_resolves_aliases() -> None:
+    repository = analyzed_repository()
+
+    detail = repository.quest_detail("local first")
+
+    assert detail is not None
+    assert detail["id"] == "Off the Grid"
+    assert detail["project_count"] >= 1
+    assert detail["examples"]
+
+
+def test_quest_detail_rejects_unknown_quest() -> None:
+    repository = analyzed_repository()
+
+    assert repository.quest_detail("not a quest at all") is None
+
+
+def test_quest_detail_spots_label_inside_a_question() -> None:
+    repository = analyzed_repository()
+
+    detail = repository.quest_detail("tell me about the Tiny Titan quest")
+
+    assert detail is not None
+    assert detail["id"] == "Tiny Titan"
+
+
+def test_top_by_quests_ranks_projects_by_quest_count() -> None:
+    repository = analyzed_repository()
+
+    leaderboard = repository.top_by_quests(limit=5)
+
+    assert leaderboard["status"] == "analyzed"
+    assert leaderboard["rows"]
+    counts = [row["quest_count"] for row in leaderboard["rows"]]
+    assert counts == sorted(counts, reverse=True)
+    assert leaderboard["rows"][0]["quest_count"] == 2
+    assert leaderboard["rows"][0]["id"] == "build-small-hackathon/project-9"
+
+
+def test_top_by_quests_empty_when_not_analyzed() -> None:
+    repository = not_analyzed_repository()
+
+    leaderboard = repository.top_by_quests()
+
+    assert leaderboard["status"] == "not_analyzed"
+    assert leaderboard["rows"] == []
+    assert leaderboard["projects_with_quests"] == 0
+
+
+def test_search_delegates_to_bm25_index() -> None:
+    repository = analyzed_repository()
+
+    result = repository.search("project 4 summary", limit=3)
+
+    assert result["total"] >= 1
+    assert result["results"][0]["id"] == "build-small-hackathon/project-4"
+    assert result["results"][0]["url"]
+
+
+def test_project_detail_returns_readme_and_app_excerpts() -> None:
+    repository = analyzed_repository()
+
+    by_title = repository.project_detail("Project 4")
+    by_slug = repository.project_detail("project-4")
+    embedded = repository.project_detail("how does Project 4 work?")
+
+    assert by_title is not None
+    assert by_title["id"] == "build-small-hackathon/project-4"
+    assert "README evidence for project 4" in by_title["readme_excerpt"]
+    assert "import gradio" in by_title["app_excerpt"]
+    assert by_title["app_file"] == "app.py"
+    assert by_title["cluster_label"]
+    assert by_slug is not None and by_slug["id"] == by_title["id"]
+    assert embedded is not None and embedded["id"] == by_title["id"]
+
+
+def test_project_detail_returns_none_for_unknown_project() -> None:
+    repository = analyzed_repository()
+
+    assert repository.project_detail("totally unknown thing") is None
+    assert repository.project_detail("") is None
+
+
+def test_repository_survives_a_sparse_payload() -> None:
+    """The docstring promises empty-but-well-formed results on degraded snapshots."""
+    project_index = fake_project_index()
+    full_payload = build_dashboard_payload(project_index, generated_at="2026-06-08T00:00:00+00:00")
+    search_index = DashboardSearchIndex(project_index.projects, full_payload)
+    repository = DashboardRepository({}, search_index)
+
+    assert repository.overview()["project_count"] == 0
+    assert repository.list_clusters()["clusters"] == []
+    assert repository.list_quests()["quests"] == []
+    assert repository.top_by_quests()["rows"] == []
+    assert repository.recent_activity()["projects"] == []
+    assert repository.cluster_detail("anything") is None
+    assert repository.quest_detail("Off the Grid") is not None
+    assert repository.search("planner")["results"]
+
+
+def test_recent_activity_sorts_by_last_modified() -> None:
+    repository = analyzed_repository()
+
+    recent = repository.recent_activity(limit=3)
+
+    assert [project["id"] for project in recent["projects"]] == [
+        "build-small-hackathon/project-9",
+        "build-small-hackathon/project-8",
+        "build-small-hackathon/project-7",
+    ]
+    assert recent["projects"][0]["cluster_label"]
+
+
+def analyzed_repository() -> DashboardRepository:
+    project_index = fake_project_index()
+    quest_matches = {project.id: [] for project in project_index.projects}
+    quest_matches["build-small-hackathon/project-9"] = [
+        {"quest": "Off the Grid", "confidence": 0.9, "evidence": "loads weights locally", "source": "readme"},
+        {"quest": "Tiny Titan", "confidence": 0.8, "evidence": "MiniCPM5-1B model", "source": "app_file"},
+    ]
+    quest_matches["build-small-hackathon/project-4"] = [
+        {"quest": "Off the Grid", "confidence": 0.7, "evidence": "local llama.cpp runtime", "source": "readme"},
+    ]
+    payload = build_dashboard_payload(
+        project_index,
+        quest_matches=quest_matches,
+        quest_source="test-quest-run",
+        generated_at="2026-06-08T00:00:00+00:00",
+    )
+    return DashboardRepository(payload, DashboardSearchIndex(project_index.projects, payload))
+
+
+def not_analyzed_repository() -> DashboardRepository:
+    project_index = fake_project_index()
+    payload = build_dashboard_payload(project_index, generated_at="2026-06-08T00:00:00+00:00")
+    return DashboardRepository(payload, DashboardSearchIndex(project_index.projects, payload))
+
+
+def fake_project_index() -> ProjectIndex:
+    projects = [
+        Project(
+            id=f"build-small-hackathon/project-{index}",
+            title=f"Project {index}",
+            summary=f"Offline project planner {index}",
+            tags=("gradio", "local-first"),
+            models=("tiny-model",),
+            datasets=(),
+            likes=index,
+            sdk="gradio",
+            license="mit",
+            created_at="2026-06-01T00:00:00+00:00",
+            last_modified=f"2026-06-{index + 1:02d}T00:00:00+00:00",
+            host=f"https://project-{index}.hf.space",
+            url=f"https://huggingface.co/spaces/build-small-hackathon/project-{index}",
+            app_file="app.py",
+            app_file_embedding_text=f"local inference gradio small model artifact project {index}",
+            app_file_source=f'import gradio as gr\n\ndemo = gr.Interface(fn=str)  # project {index}\ndemo.launch()',
+            readme_body=f"README evidence for project {index}",
+        )
+        for index in range(10)
+    ]
+    embeddings = []
+    for index in range(10):
+        vector = [0.0] * 10
+        vector[index] = 1.0
+        embeddings.append(vector)
+    generated_at = "2026-06-08T00:00:00+00:00"
+    source = "https://example.test/spaces"
+    return ProjectIndex(
+        projects=projects,
+        generated_at=generated_at,
+        source=source,
+        index_payload=build_index_payload(projects, generated_at, source, embeddings),
+    )

tests/test_model_runtime.py

@@ -1,11 +1,19 @@
+import sys
+import types
+
 import pytest
 
+from hackathon_advisor.dashboard_chat_contracts import parse_native_tool_call
 from hackathon_advisor.model_runtime import (
     DEFAULT_ADAPTER_ID,
     DEFAULT_ADAPTER_REVISION,
+    MiniCPMChatRunner,
     MiniCPMTransformersPlanner,
+    RuleBasedChatRunner,
     RuleBasedPlanner,
+    create_chat_runner,
     create_tool_planner,
+    generation_lock,
     render_context,
     runtime_status,
     system_prompt,
@@ -13,6 +21,7 @@ from hackathon_advisor.model_runtime import (
     _minicpm_generation_kwargs,
     _load_minicpm_causal_lm,
     _minicpm_chat_inputs,
+    _minicpm_chat_inputs_with_tools,
     _normalize_xml_tool_output,
     _resolve_torch_device,
     _strip_unused_generation_inputs,
@@ -75,6 +84,276 @@ class FakeMiniCPMModel:
         return self
 
 
+class FakeToolsTokenizer(FakeTokenizer):
+    """FakeTokenizer that also records the native tools= template path."""
+
+    def apply_chat_template(
+        self, messages, *, tokenize, add_generation_prompt, enable_thinking, tools=None
+    ):
+        self.template_call = {
+            "messages": messages,
+            "tokenize": tokenize,
+            "add_generation_prompt": add_generation_prompt,
+            "enable_thinking": enable_thinking,
+        }
+        if tools is not None:
+            self.template_call["tools"] = tools
+        return "rendered prompt"
+
+
+class FakeStreamer:
+    """Stands in for transformers.TextIteratorStreamer in the worker-thread flow."""
+
+    def __init__(self, tokenizer, *, skip_prompt, skip_special_tokens) -> None:
+        import queue
+
+        self._queue: queue.Queue = queue.Queue()
+
+    def put(self, piece) -> None:
+        self._queue.put(piece)
+
+    def end(self) -> None:
+        self._queue.put(None)
+
+    def __iter__(self):
+        while True:
+            piece = self._queue.get()
+            if piece is None:
+                return
+            yield piece
+
+
+class FakeParameter:
+    device = "cpu"
+
+
+class FakeAdapterContext:
+    def __init__(self, log: list[str]) -> None:
+        self._log = log
+
+    def __enter__(self):
+        self._log.append("adapter_disabled")
+        return self
+
+    def __exit__(self, *exc_info):
+        self._log.append("adapter_restored")
+        return False
+
+
+class FakeChatModel:
+    def __init__(self, pieces: tuple[str, ...], adapter_log: list[str] | None = None) -> None:
+        self.pieces = pieces
+        self.adapter_log = adapter_log
+        self.generate_calls: list[dict] = []
+        self.lock_was_held: list[bool] = []
+
+    def parameters(self):
+        return iter([FakeParameter()])
+
+    def generate(self, **kwargs) -> None:
+        self.lock_was_held.append(generation_lock().locked())
+        self.generate_calls.append(kwargs)
+        streamer = kwargs["streamer"]
+        for piece in self.pieces:
+            streamer.put(piece)
+        streamer.end()
+
+
+class FakeAdapterChatModel(FakeChatModel):
+    def disable_adapter(self):
+        assert self.adapter_log is not None
+        return FakeAdapterContext(self.adapter_log)
+
+
+@pytest.fixture
+def fake_transformers(monkeypatch: pytest.MonkeyPatch):
+    module = types.SimpleNamespace(TextIteratorStreamer=FakeStreamer)
+    monkeypatch.setitem(sys.modules, "transformers", module)
+    return module
+
+
+def chat_runner_with(model: FakeChatModel) -> MiniCPMChatRunner:
+    planner = MiniCPMTransformersPlanner(
+        "openbmb/MiniCPM5-1B",
+        adapter_id="build-small-hackathon/some-lora" if hasattr(model, "disable_adapter") else "",
+    )
+    planner._model = model
+    planner._tokenizer = FakeToolsTokenizer()
+    return MiniCPMChatRunner(planner)
+
+
+def test_chat_inputs_with_tools_passes_native_tools() -> None:
+    tokenizer = FakeToolsTokenizer()
+    tools = [{"type": "function", "function": {"name": "list_quests"}}]
+
+    inputs = _minicpm_chat_inputs_with_tools(
+        tokenizer,
+        [{"role": "user", "content": "hello"}],
+        tools=tools,
+        enable_thinking=False,
+        device="cpu",
+    )
+
+    assert tokenizer.template_call["tools"] == tools
+    assert tokenizer.template_call["enable_thinking"] is False
+    assert inputs == {"input_ids": [1], "attention_mask": [1], "device": "cpu"}
+
+
+def test_chat_runner_streams_under_lock_with_adapter_disabled(fake_transformers) -> None:
+    adapter_log: list[str] = []
+    model = FakeAdapterChatModel(("<function ", 'name="list_quests">', "</function>"), adapter_log)
+    runner = chat_runner_with(model)
+
+    pieces = list(
+        runner.stream(
+            [{"role": "user", "content": "what quests exist"}],
+            tools=[{"type": "function", "function": {"name": "list_quests"}}],
+            max_new_tokens=96,
+        )
+    )
+
+    assert [piece for _count, piece in pieces] == [
+        "<function ",
+        'name="list_quests">',
+        "</function>",
+    ]
+    assert [count for count, _piece in pieces] == [1, 2, 3]
+    assert adapter_log == ["adapter_disabled", "adapter_restored"]
+    assert model.lock_was_held == [True]
+    assert generation_lock().locked() is False
+    assert model.generate_calls[0]["max_new_tokens"] == 96
+    assert model.generate_calls[0]["do_sample"] is False
+    template_call = runner._planner._tokenizer.template_call
+    assert "tools" in template_call
+
+
+def test_chat_runner_forwards_enable_thinking_to_the_template(fake_transformers) -> None:
+    model = FakeChatModel(("thoughts</think>\n\nanswer",))
+    runner = chat_runner_with(model)
+
+    list(
+        runner.stream(
+            [{"role": "user", "content": "hi"}],
+            tools=[{"type": "function"}],
+            max_new_tokens=4096,
+            enable_thinking=True,
+        )
+    )
+
+    template_call = runner._planner._tokenizer.template_call
+    assert template_call["enable_thinking"] is True
+    assert model.generate_calls[0]["max_new_tokens"] == 4096
+    assert MiniCPMChatRunner.supports_thinking is True
+    assert RuleBasedChatRunner.supports_thinking is False
+
+
+def test_chat_runner_answer_pass_omits_tools_and_adapter_toggle(fake_transformers) -> None:
+    model = FakeChatModel(("The map ", "shows ten projects."))
+    runner = chat_runner_with(model)
+
+    pieces = list(
+        runner.stream(
+            [
+                {"role": "user", "content": "what is everyone building"},
+                {"role": "assistant", "content": "", "tool_calls": []},
+                {"role": "tool", "content": "{}"},
+            ],
+            max_new_tokens=200,
+        )
+    )
+
+    assert "".join(piece for _count, piece in pieces) == "The map shows ten projects."
+    assert model.lock_was_held == [True]
+    template_call = runner._planner._tokenizer.template_call
+    assert "tools" not in template_call
+
+
+def test_chat_runner_surfaces_generation_errors(fake_transformers) -> None:
+    class ExplodingModel(FakeChatModel):
+        def generate(self, **kwargs) -> None:
+            kwargs["streamer"].end()
+            raise RuntimeError("boom")
+
+    runner = chat_runner_with(ExplodingModel(()))
+
+    with pytest.raises(RuntimeError, match="boom"):
+        list(runner.stream([{"role": "user", "content": "hi"}], max_new_tokens=10))
+    assert generation_lock().locked() is False
+
+
+def test_early_close_releases_generation_lock(fake_transformers) -> None:
+    model = FakeChatModel(("tok1 ", "tok2 ", "tok3 ", "tok4 ", "tok5"))
+    runner = chat_runner_with(model)
+    stream = runner.stream([{"role": "user", "content": "hi"}], max_new_tokens=32)
+
+    next(stream)  # consume one piece then abandon mid-stream
+    stream.close()
+
+    assert generation_lock().locked() is False
+
+
+def test_rule_chat_runner_escapes_xml_special_characters() -> None:
+    runner = RuleBasedChatRunner()
+
+    output = "".join(
+        piece
+        for _count, piece in runner.stream(
+            [{"role": "user", "content": "find projects about A & B <robots>"}],
+            tools=[{"type": "function"}],
+            max_new_tokens=96,
+        )
+    )
+
+    call = parse_native_tool_call(output)
+    assert call.name == "search_projects"
+    assert call.arguments["query"] == "find projects about A & B <robots>"
+
+
+def test_rule_chat_runner_routes_tools_pass_through_intents() -> None:
+    runner = RuleBasedChatRunner()
+
+    output = "".join(
+        piece
+        for _count, piece in runner.stream(
+            [{"role": "user", "content": "who completed the most quests"}],
+            tools=[{"type": "function"}],
+            max_new_tokens=96,
+        )
+    )
+
+    call = parse_native_tool_call(output)
+    assert call.name == "top_projects_by_quests"
+
+
+def test_rule_chat_runner_answer_pass_is_deterministic() -> None:
+    runner = RuleBasedChatRunner()
+
+    output = "".join(
+        piece
+        for _count, piece in runner.stream(
+            [{"role": "user", "content": "hi"}, {"role": "tool", "content": "{}"}],
+            max_new_tokens=200,
+        )
+    )
+
+    assert "verified data" in output
+
+
+def test_create_chat_runner_matches_advisor_backend() -> None:
+    minicpm = MiniCPMTransformersPlanner("openbmb/MiniCPM5-1B")
+
+    assert isinstance(create_chat_runner(minicpm), MiniCPMChatRunner)
+    assert isinstance(create_chat_runner(RuleBasedPlanner()), RuleBasedChatRunner)
+
+
+def test_base_model_context_is_null_without_adapter() -> None:
+    planner = MiniCPMTransformersPlanner("openbmb/MiniCPM5-1B", adapter_id="")
+    planner._model = FakeChatModel(())
+
+    with planner.base_model_context():
+        pass  # no adapter -> nullcontext, nothing to toggle
+
+
 def test_rule_planner_emits_valid_search_call() -> None:
     planner = RuleBasedPlanner()