Add Next.js frontend with chat functionality, including components for chat messages, source panels, and markdown rendering. Update README with setup instructions and enhance .gitignore for frontend build artifacts.

.gitignore

@@ -164,6 +164,11 @@ cython_debug/
 .vscode/
 data/chroma-db**/
 evaluation_data/chroma-db**/
+node_modules/
+.next/
+frontend/node_modules/
+frontend/.next/
+frontend/out/
 
 .huggingface
 
@@ -176,4 +181,4 @@ evaluation_data/chroma-db**/
 *.mdx
 *.pkl
 *.png
-*.mov
+*.mov

README.md

@@ -40,6 +40,53 @@ The Gradio demo is deployed on Hugging Face Spaces at: [AI Tutor Chatbot on Hugg
 
    Starts the Gradio AI Tutor interface.
 
+### Next.js Frontend — Quick Start
+
+The repo now also includes a separate Next.js frontend in [frontend](./frontend) that talks to the FastAPI backend instead of the Gradio transport.
+
+1. Start the Python API:
+
+   ```bash
+   uv run -m scripts.api
+   ```
+
+   If `8000` is already taken, bind another port instead:
+
+   ```bash
+   AI_TUTOR_API_PORT=8001 uv run -m scripts.api
+   ```
+
+2. In a second terminal, install the frontend dependencies:
+
+   ```bash
+   cd frontend
+   npm install
+   ```
+
+3. Configure the frontend API target:
+
+   ```bash
+   cp .env.example .env.local
+   ```
+
+   The default points at `http://127.0.0.1:8000`, which matches the local FastAPI app.
+   If you override the backend port, update `NEXT_PUBLIC_AI_TUTOR_API_BASE_URL` to match.
+
+4. Run the frontend:
+
+   ```bash
+   npm run dev
+   ```
+
+5. Open [http://localhost:3000](http://localhost:3000).
+
+This frontend consumes:
+
+- `GET /api/sources`
+- `POST /api/chat`
+
+and renders sources, tool activity, and reasoning as separate UI elements rather than a single markdown block.
+
 ### Gradio API
 
 The chat endpoint is exposed as `chat`, so the API flow is:

frontend/.env.example

@@ -0,0 +1 @@
+NEXT_PUBLIC_AI_TUTOR_API_BASE_URL=http://127.0.0.1:8000

frontend/.env.local

@@ -0,0 +1 @@
+NEXT_PUBLIC_AI_TUTOR_API_BASE_URL=http://127.0.0.1:8000

frontend/app/globals.css

@@ -0,0 +1,417 @@
+@import "tailwindcss";
+
+:root {
+  --font-sans:
+    ui-sans-serif,
+    -apple-system,
+    BlinkMacSystemFont,
+    "SF Pro Text",
+    "SF Pro Display",
+    "Segoe UI",
+    system-ui,
+    sans-serif;
+  --font-display: var(--font-sans);
+  --paper: #f7fbfe;
+  --paper-strong: #ffffff;
+  --ink: #12213d;
+  --muted: #5f7393;
+  --panel: rgba(247, 251, 254, 0.8);
+  --panel-strong: rgba(255, 255, 255, 0.92);
+  --line: rgba(11, 136, 238, 0.08);
+  --line-strong: rgba(11, 136, 238, 0.18);
+  --accent: #0b88ee;
+  --accent-soft: rgba(11, 136, 238, 0.14);
+  --accent-faint: rgba(193, 235, 255, 0.42);
+  --success: #122acc;
+  --shadow: 0 24px 80px rgba(18, 42, 204, 0.12);
+  --surface: rgba(255, 255, 255, 0.78);
+  --surface-strong: rgba(255, 255, 255, 0.92);
+  --surface-soft: rgba(255, 255, 255, 0.55);
+  --surface-subtle: rgba(255, 255, 255, 0.35);
+  --surface-hover: rgba(255, 255, 255, 0.9);
+  --app-bg:
+    radial-gradient(circle at top left, rgba(193, 235, 255, 0.42), transparent 26%),
+    radial-gradient(circle at top right, rgba(11, 136, 238, 0.18), transparent 24%),
+    linear-gradient(180deg, #eef7ff 0%, #f7fbfe 46%, #ffffff 100%);
+  --grid-dot: rgba(15, 23, 32, 0.018);
+  --scroll-track: rgba(15, 23, 32, 0.18);
+  --grain-dot: rgba(15, 23, 32, 0.9);
+  --grain-blend: multiply;
+  --grain-opacity: 0.08;
+  --code-border: rgba(15, 23, 32, 0.08);
+  --code-bg: rgba(255, 255, 255, 0.72);
+  --pre-bg: rgba(15, 23, 32, 0.96);
+  --pre-color: #f7f2ea;
+  --hr-color: rgba(15, 23, 32, 0.1);
+  --table-header-bg: rgba(15, 23, 32, 0.04);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --paper: #0e1626;
+    --paper-strong: #13203a;
+    --ink: #e8edf5;
+    --muted: #94a5c2;
+    --panel: rgba(17, 28, 50, 0.74);
+    --panel-strong: rgba(25, 40, 72, 0.9);
+    --line: rgba(120, 180, 255, 0.1);
+    --line-strong: rgba(120, 180, 255, 0.24);
+    --accent: #4fa6f5;
+    --accent-soft: rgba(79, 166, 245, 0.2);
+    --accent-faint: rgba(79, 166, 245, 0.16);
+    --success: #6a8cff;
+    --shadow: 0 24px 80px rgba(0, 0, 0, 0.55);
+    --surface: rgba(30, 46, 78, 0.6);
+    --surface-strong: rgba(36, 54, 90, 0.88);
+    --surface-soft: rgba(30, 46, 78, 0.4);
+    --surface-subtle: rgba(30, 46, 78, 0.26);
+    --surface-hover: rgba(42, 62, 100, 0.72);
+    --app-bg:
+      radial-gradient(circle at top left, rgba(79, 166, 245, 0.18), transparent 28%),
+      radial-gradient(circle at top right, rgba(99, 102, 241, 0.22), transparent 26%),
+      linear-gradient(180deg, #070c18 0%, #0a1224 46%, #0d172e 100%);
+    --grid-dot: rgba(255, 255, 255, 0.028);
+    --scroll-track: rgba(255, 255, 255, 0.16);
+    --grain-dot: rgba(255, 255, 255, 0.5);
+    --grain-blend: screen;
+    --grain-opacity: 0.05;
+    --code-border: rgba(255, 255, 255, 0.12);
+    --code-bg: rgba(255, 255, 255, 0.06);
+    --pre-bg: rgba(0, 0, 0, 0.5);
+    --pre-color: #f7f2ea;
+    --hr-color: rgba(255, 255, 255, 0.12);
+    --table-header-bg: rgba(255, 255, 255, 0.05);
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  height: 100%;
+  color: var(--ink);
+  background: var(--app-bg);
+}
+
+body {
+  min-height: 100vh;
+  margin: 0;
+  font-family: var(--font-sans), sans-serif;
+  line-height: 1.5;
+  letter-spacing: -0.012em;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  font-feature-settings: "ss01" 1, "ss03" 1, "cv11" 1;
+  color: var(--ink);
+  background-image:
+    linear-gradient(var(--grid-dot) 1px, transparent 1px),
+    linear-gradient(90deg, var(--grid-dot) 1px, transparent 1px);
+  background-size: 32px 32px;
+  overflow-x: hidden;
+}
+
+@media (min-width: 1024px) {
+  body {
+    height: 100vh;
+    overflow: hidden;
+  }
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+button,
+input,
+textarea {
+  font: inherit;
+}
+
+::selection {
+  background: rgba(11, 136, 238, 0.18);
+}
+
+.glass-panel {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  box-shadow: var(--shadow);
+  backdrop-filter: blur(24px);
+}
+
+.panel-strong {
+  background: var(--panel-strong);
+  border: 1px solid var(--line-strong);
+}
+
+.display-font {
+  font-family: var(--font-display), sans-serif;
+  font-weight: 620;
+  letter-spacing: -0.045em;
+}
+
+.grain-mask::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  opacity: var(--grain-opacity);
+  background-image:
+    radial-gradient(circle at 1px 1px, var(--grain-dot) 1px, transparent 0);
+  background-size: 14px 14px;
+  mix-blend-mode: var(--grain-blend);
+}
+
+.scrollbar-thin {
+  scrollbar-width: thin;
+  scrollbar-color: var(--scroll-track) transparent;
+}
+
+.scrollbar-thin::-webkit-scrollbar {
+  width: 10px;
+}
+
+.scrollbar-thin::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.scrollbar-thin::-webkit-scrollbar-thumb {
+  background: var(--scroll-track);
+  border-radius: 999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+
+@keyframes rise-in {
+  from {
+    opacity: 0;
+    transform: translateY(14px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes pulse-border {
+  0%,
+  100% {
+    box-shadow: inset 0 0 0 1px rgba(11, 136, 238, 0.12);
+  }
+
+  50% {
+    box-shadow: inset 0 0 0 1px rgba(11, 136, 238, 0.34);
+  }
+}
+
+@keyframes processing-sheen {
+  0% {
+    transform: translateX(-120%);
+  }
+
+  100% {
+    transform: translateX(160%);
+  }
+}
+
+@keyframes processing-orb {
+  0%,
+  100% {
+    transform: translate(0, -50%) scale(0.95);
+    opacity: 0.2;
+  }
+
+  50% {
+    transform: translate(calc(100% + 5.75rem), -50%) scale(1.08);
+    opacity: 0.42;
+  }
+}
+
+@keyframes processing-pulse {
+  0%,
+  100% {
+    transform: scale(0.9);
+    opacity: 0.55;
+  }
+
+  50% {
+    transform: scale(1.2);
+    opacity: 1;
+  }
+}
+
+.animate-rise-in {
+  animation: rise-in 240ms ease-out both;
+}
+
+.animate-pulse-border {
+  animation: pulse-border 1.8s ease-in-out infinite;
+}
+
+.processing-button__sheen {
+  background:
+    linear-gradient(
+      115deg,
+      transparent 18%,
+      rgba(255, 255, 255, 0.14) 38%,
+      rgba(255, 255, 255, 0.78) 50%,
+      rgba(255, 255, 255, 0.16) 62%,
+      transparent 82%
+    );
+  animation: processing-sheen 1.65s linear infinite;
+}
+
+.processing-button__orb {
+  background:
+    radial-gradient(circle, rgba(255, 255, 255, 0.95) 0%, rgba(255, 255, 255, 0) 72%);
+  filter: blur(2px);
+  animation: processing-orb 2.2s ease-in-out infinite;
+}
+
+.processing-button__pulse {
+  background: currentColor;
+  box-shadow: 0 0 0 0 rgba(11, 136, 238, 0.18);
+  animation: processing-pulse 1.2s ease-in-out infinite;
+}
+
+.activity-sheen {
+  background: linear-gradient(
+    115deg,
+    transparent 18%,
+    rgba(11, 136, 238, 0.1) 40%,
+    rgba(11, 136, 238, 0.24) 50%,
+    rgba(11, 136, 238, 0.1) 60%,
+    transparent 82%
+  );
+  animation: processing-sheen 1.9s linear infinite;
+}
+
+.markdown-block {
+  color: inherit;
+}
+
+.markdown-block > :first-child {
+  margin-top: 0;
+}
+
+.markdown-block > :last-child {
+  margin-bottom: 0;
+}
+
+.markdown-block p,
+.markdown-block ul,
+.markdown-block ol,
+.markdown-block pre,
+.markdown-block blockquote,
+.markdown-block table {
+  margin: 0.85rem 0;
+}
+
+.markdown-block h1,
+.markdown-block h2,
+.markdown-block h3,
+.markdown-block h4 {
+  margin: 1.1rem 0 0.55rem;
+  font-family: var(--font-display), sans-serif;
+  font-weight: 620;
+  letter-spacing: -0.035em;
+  line-height: 1.04;
+  color: var(--ink);
+}
+
+.markdown-block h1 {
+  font-size: 1.62rem;
+}
+
+.markdown-block h2 {
+  font-size: 1.3rem;
+}
+
+.markdown-block h3 {
+  font-size: 1.06rem;
+}
+
+.markdown-block ul,
+.markdown-block ol {
+  padding-left: 1.35rem;
+}
+
+.markdown-block li + li {
+  margin-top: 0.35rem;
+}
+
+.markdown-block code {
+  border: 1px solid var(--code-border);
+  border-radius: 0.5rem;
+  background: var(--code-bg);
+  padding: 0.08rem 0.4rem;
+  font-size: 0.92em;
+}
+
+.markdown-block pre {
+  overflow-x: auto;
+  border: 1px solid var(--code-border);
+  border-radius: 1rem;
+  background: var(--pre-bg);
+  padding: 0.9rem 1rem;
+  color: var(--pre-color);
+}
+
+.markdown-block pre code {
+  border: 0;
+  background: transparent;
+  padding: 0;
+  color: inherit;
+}
+
+.markdown-block blockquote {
+  border-left: 3px solid rgba(11, 136, 238, 0.32);
+  padding-left: 0.9rem;
+  color: var(--muted);
+}
+
+.markdown-block a {
+  color: var(--accent);
+  text-decoration: underline;
+  text-decoration-color: rgba(11, 136, 238, 0.28);
+  text-underline-offset: 0.14em;
+}
+
+.markdown-block hr {
+  border: 0;
+  border-top: 1px solid var(--hr-color);
+  margin: 1rem 0;
+}
+
+.markdown-block table {
+  width: 100%;
+  border-collapse: collapse;
+  overflow: hidden;
+  border-radius: 0.9rem;
+  border: 1px solid var(--code-border);
+}
+
+.markdown-block th,
+.markdown-block td {
+  border-bottom: 1px solid var(--code-border);
+  padding: 0.65rem 0.75rem;
+  text-align: left;
+}
+
+.markdown-block th {
+  background: var(--table-header-bg);
+}
+
+.markdown-block-muted {
+  color: var(--muted);
+}
+
+.markdown-block-muted h1,
+.markdown-block-muted h2,
+.markdown-block-muted h3,
+.markdown-block-muted h4 {
+  color: var(--ink);
+}

frontend/app/layout.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "AI Tutor Agent",
+  description:
+    "A modern chat workspace for the AI Tutor retrieval app, powered by FastAPI and LangGraph.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body suppressHydrationWarning>{children}</body>
+    </html>
+  );
+}

frontend/app/page.tsx

@@ -0,0 +1,5 @@
+import { ChatShell } from "@/components/chat-shell";
+
+export default function Home() {
+  return <ChatShell />;
+}

frontend/components/chat-message.tsx

@@ -0,0 +1,586 @@
+"use client";
+
+import clsx from "clsx";
+import {
+  BookOpen,
+  Check,
+  ChevronDown,
+  Copy,
+  ExternalLink,
+  Globe,
+  GraduationCap,
+  LibraryBig,
+  Pencil,
+  RefreshCw,
+  SearchCheck,
+  Sparkles,
+  Wrench,
+} from "lucide-react";
+import type { ComponentType, SVGProps } from "react";
+import {
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import { MarkdownBlock } from "@/components/markdown-block";
+import type {
+  TutorMessage,
+  TutorMessageBlock,
+  MessageCitation,
+  TutorMessagePart,
+} from "@/lib/chat-ui";
+import {
+  getMessageCitations,
+  getOrderedMessageBlocks,
+  prettifyToolName,
+  toolInputSummary,
+} from "@/lib/chat-ui";
+
+type ChatMessageProps = {
+  message: TutorMessage;
+  editDraft?: string;
+  isEditing?: boolean;
+  isStreaming?: boolean;
+  onAssistantCopy?: (message: TutorMessage) => void;
+  onAssistantRedo?: (messageId: string) => void;
+  onEditCancel?: () => void;
+  onEditChange?: (value: string) => void;
+  onEditSave?: (messageId: string) => void;
+  onUserEdit?: (messageId: string) => void;
+  actionDisabled?: boolean;
+  copied?: boolean;
+  showAssistantActions?: boolean;
+};
+
+export function ChatMessage({
+  message,
+  editDraft = "",
+  isEditing = false,
+  isStreaming = false,
+  onAssistantCopy,
+  onAssistantRedo,
+  onEditCancel,
+  onEditChange,
+  onEditSave,
+  onUserEdit,
+  actionDisabled = false,
+  copied = false,
+  showAssistantActions = true,
+}: ChatMessageProps) {
+  const isAssistant = message.role === "assistant";
+  const contentBlocks = getOrderedMessageBlocks(message);
+  const citations = isAssistant && !isStreaming ? getMessageCitations(message) : [];
+  const editTextareaRef = useRef<HTMLTextAreaElement>(null);
+
+  useEffect(() => {
+    if (!isEditing || isAssistant) {
+      return;
+    }
+
+    const textarea = editTextareaRef.current;
+    if (!textarea) {
+      return;
+    }
+
+    textarea.focus();
+    const length = textarea.value.length;
+    textarea.setSelectionRange(length, length);
+  }, [isAssistant, isEditing]);
+
+  useEffect(() => {
+    if (!isEditing || isAssistant) {
+      return;
+    }
+
+    const textarea = editTextareaRef.current;
+    if (!textarea) {
+      return;
+    }
+
+    textarea.style.height = "0px";
+    textarea.style.height = `${Math.min(textarea.scrollHeight, 240)}px`;
+  }, [editDraft, isAssistant, isEditing]);
+
+  return (
+    <div
+      data-message-id={message.id}
+      data-role={message.role}
+      className={clsx(
+        "animate-rise-in flex flex-col",
+        isAssistant ? "w-full items-start" : "items-end",
+      )}
+    >
+      <article
+        className={clsx(
+          "rounded-[1.8rem] border px-4 py-3 text-left shadow-[0_20px_50px_rgba(18,42,204,0.08)] transition outline-none sm:px-5",
+          isAssistant
+            ? "w-full border-[var(--line)] bg-[var(--surface)]"
+            : "ml-auto border-[var(--accent)] bg-[linear-gradient(135deg,rgba(11,136,238,0.16),rgba(193,235,255,0.35))]",
+        )}
+      >
+        {isEditing && !isAssistant ? (
+          <InlineEditor
+            disabled={actionDisabled}
+            textareaRef={editTextareaRef}
+            value={editDraft}
+            onCancel={onEditCancel}
+            onChange={onEditChange}
+            onSave={() => onEditSave?.(message.id)}
+          />
+        ) : (
+          <div className="space-y-3">
+            {contentBlocks.map((block, index) => {
+              const isLastBlock = index === contentBlocks.length - 1;
+              const isActive =
+                isStreaming && isLastBlock && block.kind !== "text";
+              return (
+                <ContentBlock
+                  key={block.key}
+                  block={block}
+                  isActive={isActive}
+                />
+              );
+            })}
+            {citations.length > 0 ? <CitationRow citations={citations} /> : null}
+          </div>
+        )}
+      </article>
+
+      {isAssistant && showAssistantActions ? (
+        <div className="mt-1.5 flex items-center gap-1.5 pl-2">
+          <MessageActionButton
+            label="Redo"
+            onClick={() => onAssistantRedo?.(message.id)}
+            disabled={actionDisabled}
+          >
+            <RefreshCw className="h-3.5 w-3.5" />
+          </MessageActionButton>
+          <MessageActionButton
+            label={copied ? "Copied" : "Copy"}
+            onClick={() => onAssistantCopy?.(message)}
+          >
+            {copied ? (
+              <Check className="h-3.5 w-3.5" />
+            ) : (
+              <Copy className="h-3.5 w-3.5" />
+            )}
+          </MessageActionButton>
+        </div>
+      ) : !isAssistant ? (
+        !isEditing ? (
+          <div className="mt-1.5 flex items-center gap-1 pr-3">
+            <MessageActionButton
+              label="Edit"
+              onClick={() => onUserEdit?.(message.id)}
+              disabled={actionDisabled}
+            >
+              <Pencil className="h-3.5 w-3.5" />
+            </MessageActionButton>
+          </div>
+        ) : null
+      ) : null}
+    </div>
+  );
+}
+
+function InlineEditor({
+  disabled,
+  onCancel,
+  onChange,
+  onSave,
+  textareaRef,
+  value,
+}: {
+  disabled: boolean;
+  onCancel?: () => void;
+  onChange?: (value: string) => void;
+  onSave?: () => void;
+  textareaRef: RefObject<HTMLTextAreaElement | null>;
+  value: string;
+}) {
+  const trimmed = value.trim();
+
+  return (
+    <div className="space-y-3">
+      <textarea
+        ref={textareaRef}
+        rows={1}
+        value={value}
+        onChange={(event) => onChange?.(event.target.value)}
+        onKeyDown={(event) => {
+          if ((event.metaKey || event.ctrlKey) && event.key === "Enter") {
+            event.preventDefault();
+            if (!disabled && trimmed) {
+              onSave?.();
+            }
+            return;
+          }
+
+          if (event.key === "Escape") {
+            event.preventDefault();
+            onCancel?.();
+          }
+        }}
+        className="max-h-60 min-h-20 w-full resize-none overflow-y-auto rounded-[1.15rem] border border-[var(--accent)]/20 bg-[var(--surface-subtle)] px-3 py-3 text-[15px] leading-7 text-[var(--ink)] outline-none placeholder:text-[var(--muted)]"
+      />
+      <div className="flex items-center justify-end gap-2">
+        <button
+          type="button"
+          onClick={onCancel}
+          disabled={disabled}
+          className="rounded-full border border-[var(--accent)]/20 bg-[var(--surface-soft)] px-3 py-1.5 text-sm font-medium text-[var(--ink)] transition enabled:hover:border-[var(--accent)] enabled:hover:text-[var(--accent)] disabled:cursor-not-allowed disabled:opacity-40"
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          onClick={onSave}
+          disabled={disabled || !trimmed}
+          className="rounded-full bg-[var(--accent)] px-3 py-1.5 text-sm font-semibold text-white transition hover:brightness-110 disabled:cursor-not-allowed disabled:opacity-40"
+        >
+          Save
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function MessageActionButton({
+  children,
+  label,
+  onClick,
+  disabled = false,
+}: {
+  children: ReactNode;
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={label}
+      title={label}
+      className="inline-flex h-7 w-7 items-center justify-center rounded-full border border-[var(--line)] bg-[var(--surface)] text-[var(--muted)] shadow-[0_8px_24px_rgba(18,42,204,0.06)] transition enabled:hover:border-[var(--accent)] enabled:hover:text-[var(--accent)] disabled:cursor-not-allowed disabled:opacity-40"
+    >
+      {children}
+    </button>
+  );
+}
+
+function ContentBlock({
+  block,
+  isActive = false,
+}: {
+  block: TutorMessageBlock;
+  isActive?: boolean;
+}) {
+  if (block.kind === "reasoning") {
+    return <ReasoningBlock parts={block.parts} isActive={isActive} />;
+  }
+
+  if (block.kind === "tool") {
+    return <ToolActivityBlock parts={block.parts} isActive={isActive} />;
+  }
+
+  return <TextBlock parts={block.parts} />;
+}
+
+function ReasoningBlock({
+  parts,
+  isActive = false,
+}: {
+  parts: TutorMessagePart[];
+  isActive?: boolean;
+}) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <section className="relative overflow-hidden rounded-[1.35rem] border border-[var(--line)] bg-[var(--paper)]/80 px-4 py-3">
+      {isActive ? (
+        <span
+          aria-hidden="true"
+          className="activity-sheen pointer-events-none absolute inset-x-0 top-0 h-[2.75rem]"
+        />
+      ) : null}
+      <button
+        type="button"
+        onClick={(event) => {
+          event.stopPropagation();
+          setIsOpen((current) => !current);
+        }}
+        className="relative z-[1] flex w-full items-center justify-between gap-2 text-left text-[13px] font-semibold tracking-[-0.012em] text-[var(--ink)]"
+        aria-expanded={isOpen}
+      >
+        <span className="inline-flex items-center gap-2 text-[var(--accent)]">
+          <Sparkles
+            className={clsx(
+              "h-4 w-4 text-[var(--accent)]",
+              isActive && "animate-pulse",
+            )}
+          />
+          <span className="text-[var(--ink)]">
+            {isActive ? "Thinking" : "Reasoning trace"}
+          </span>
+          {isActive ? (
+            <span
+              aria-hidden="true"
+              className="processing-button__pulse ml-0.5 h-1.5 w-1.5 rounded-full"
+            />
+          ) : null}
+        </span>
+        <ChevronDown
+          className={clsx(
+            "h-4 w-4 text-[var(--muted)] transition-transform",
+            isOpen && "rotate-180",
+          )}
+        />
+      </button>
+      {isOpen ? (
+        <div className="relative z-[1] mt-3 space-y-3 text-[14px] leading-[1.65] text-[var(--muted)]">
+          {parts.map((part, index) => (
+            <MarkdownBlock
+              key={`reasoning-${index}`}
+              className="markdown-block-muted"
+            >
+              {part.text ?? ""}
+            </MarkdownBlock>
+          ))}
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+function ToolActivityBlock({
+  parts,
+  isActive = false,
+}: {
+  parts: TutorMessagePart[];
+  isActive?: boolean;
+}) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const sourceCount = getToolPartSourceCount(parts);
+  const sourceCountLabel =
+    sourceCount > 0
+      ? `${sourceCount} source${sourceCount === 1 ? "" : "s"}`
+      : "";
+
+  return (
+    <section className="relative overflow-hidden rounded-[1.35rem] border border-[var(--line)] bg-[var(--surface)] px-4 py-3">
+      {isActive ? (
+        <span
+          aria-hidden="true"
+          className="activity-sheen pointer-events-none absolute inset-x-0 top-0 h-[2.75rem]"
+        />
+      ) : null}
+      <button
+        type="button"
+        onClick={(event) => {
+          event.stopPropagation();
+          setIsOpen((current) => !current);
+        }}
+        className="relative z-[1] flex w-full items-center justify-between gap-3 text-left"
+        aria-expanded={isOpen}
+      >
+        <div className="inline-flex items-center gap-2 text-[13px] font-semibold tracking-[-0.012em] text-[var(--ink)]">
+          <Wrench
+            className={clsx(
+              "h-4 w-4 text-[var(--accent)]",
+              isActive && "animate-pulse",
+            )}
+          />
+          <span>{isActive ? "Running tools" : "Tool activity"}</span>
+          {isActive ? (
+            <span
+              aria-hidden="true"
+              className="processing-button__pulse ml-0.5 h-1.5 w-1.5 rounded-full text-[var(--accent)]"
+            />
+          ) : null}
+        </div>
+        <div className="flex items-center gap-3">
+          {sourceCountLabel ? (
+            <span className="rounded-full bg-[var(--surface)] px-2.5 py-1 text-[10px] font-semibold uppercase tracking-[0.1em] text-[var(--muted)]">
+              {sourceCountLabel}
+            </span>
+          ) : null}
+          <ChevronDown
+            className={clsx(
+              "h-4 w-4 text-[var(--muted)] transition-transform",
+              isOpen && "rotate-180",
+            )}
+          />
+        </div>
+      </button>
+      {isOpen ? (
+        <div className="relative z-[1] mt-3 space-y-3">
+          {parts.map((part, index) => (
+            <ToolCard key={`tool-${index}`} part={part} />
+          ))}
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+function TextBlock({ parts }: { parts: TutorMessagePart[] }) {
+  return (
+    <div className="space-y-3 text-[15px] leading-[1.72] tracking-[-0.012em] text-[var(--ink)]">
+      {parts.map((part, index) => (
+        <MarkdownBlock
+          key={`text-${index}`}
+          className="text-[15px] leading-[1.72] tracking-[-0.012em] text-[var(--ink)]"
+        >
+          {part.text ?? ""}
+        </MarkdownBlock>
+      ))}
+    </div>
+  );
+}
+
+function ToolCard({ part }: { part: TutorMessagePart }) {
+  const summary = toolInputSummary(part.input);
+  const output =
+    part.output && typeof part.output === "object"
+      ? (part.output as { text?: string; matches?: unknown[] })
+      : undefined;
+  const matchCount = Array.isArray(output?.matches) ? output.matches.length : 0;
+  const resultSummary = describeToolResult(output?.text, matchCount);
+
+  return (
+    <div className="rounded-[1.25rem] border border-[var(--line)] bg-[var(--surface)] px-4 py-3 shadow-[0_10px_30px_rgba(18,42,204,0.05)]">
+      <div className="flex items-center justify-between gap-3">
+        <div>
+          <p className="text-[10px] font-semibold uppercase tracking-[0.11em] text-[var(--muted)]">
+            Tool call
+          </p>
+          <p className="mt-1 text-[13px] font-semibold tracking-[-0.012em] text-[var(--ink)]">
+            {prettifyToolName(part.type)}
+          </p>
+        </div>
+        <span className="rounded-full bg-[var(--surface)] px-2 py-1 text-[10px] font-medium uppercase tracking-[0.1em] text-[var(--muted)]">
+          {formatToolState(part.state)}
+        </span>
+      </div>
+
+      {summary ? (
+        <div className="mt-3 rounded-[1rem] border border-[var(--line)] bg-[var(--paper)]/65 px-3 py-3">
+          <div className="inline-flex items-center gap-2 text-[10px] font-semibold uppercase tracking-[0.11em] text-[var(--muted)]">
+            <SearchCheck className="h-3.5 w-3.5 text-[var(--accent)]" />
+            Tool input
+          </div>
+          <p className="mt-2 text-[13px] leading-[1.65] text-[var(--ink)]">{summary}</p>
+        </div>
+      ) : null}
+
+      {resultSummary ? (
+        <div className="mt-3 rounded-[1rem] border border-[var(--line)] bg-[rgba(11,136,238,0.08)] px-3 py-3">
+          <p className="text-[10px] font-semibold uppercase tracking-[0.11em] text-[var(--muted)]">
+            Tool result
+          </p>
+          <p className="mt-2 text-[13px] leading-[1.65] text-[var(--ink)]">
+            {resultSummary}
+          </p>
+        </div>
+      ) : null}
+
+      {part.errorText ? (
+        <p className="mt-3 text-xs leading-5 text-red-700">{part.errorText}</p>
+      ) : null}
+    </div>
+  );
+}
+
+function formatToolState(state?: string) {
+  if (!state) {
+    return "running";
+  }
+
+  return state.replaceAll("-", " ");
+}
+
+function describeToolResult(outputText?: string, matchCount = 0) {
+  if (matchCount > 0) {
+    return `${matchCount} source match${matchCount === 1 ? "" : "es"} captured for the final answer.`;
+  }
+
+  if ((outputText ?? "").trim()) {
+    return "Tool completed.";
+  }
+
+  return "";
+}
+
+function getToolPartSourceCount(parts: TutorMessagePart[]) {
+  const seen = new Set<string>();
+
+  for (const part of parts) {
+    const output =
+      part.output && typeof part.output === "object"
+        ? (part.output as { matches?: unknown[] })
+        : undefined;
+
+    for (const match of Array.isArray(output?.matches) ? output.matches : []) {
+      if (!match || typeof match !== "object") {
+        continue;
+      }
+
+      const source = match as { docId?: string; url?: string };
+      const key = source.docId || source.url;
+      if (!key) {
+        continue;
+      }
+      seen.add(key);
+    }
+  }
+
+  return seen.size;
+}
+
+const CITATION_KIND_META: Record<
+  MessageCitation["kind"],
+  { icon: ComponentType<SVGProps<SVGSVGElement>>; label: string }
+> = {
+  web: { icon: Globe, label: "Web" },
+  course: { icon: GraduationCap, label: "Course" },
+  doc: { icon: BookOpen, label: "Docs" },
+};
+
+function CitationRow({ citations }: { citations: MessageCitation[] }) {
+  return (
+    <section className="mt-2 space-y-2 border-t border-[var(--line)] pt-3">
+      <div className="inline-flex items-center gap-1.5 text-[10px] font-semibold uppercase tracking-[0.12em] text-[var(--muted)]">
+        <LibraryBig className="h-3.5 w-3.5 text-[var(--accent)]" />
+        <span>Sources</span>
+        <span className="rounded-full bg-[var(--accent-faint)] px-1.5 py-0.5 text-[10px] font-semibold text-[var(--accent)]">
+          {citations.length}
+        </span>
+      </div>
+      <div className="flex flex-wrap gap-2">
+        {citations.map((citation, index) => {
+          const meta = CITATION_KIND_META[citation.kind];
+          const Icon = meta.icon;
+          return (
+            <a
+              key={`${citation.kind}-${citation.url}-${index}`}
+              href={citation.url}
+              target="_blank"
+              rel="noreferrer"
+              title={`${meta.label}${citation.sublabel ? ` — ${citation.sublabel}` : ""}`}
+              className="group inline-flex max-w-full items-center gap-1.5 rounded-full border border-[var(--line-strong)] bg-[var(--accent-faint)] px-2.5 py-1.5 text-xs font-medium text-[var(--accent)] transition hover:border-[var(--accent)] hover:bg-[var(--surface-strong)]"
+            >
+              <Icon className="h-3.5 w-3.5 shrink-0" />
+              <span className="truncate">{citation.label}</span>
+              <ExternalLink className="h-3 w-3 shrink-0 opacity-60 transition group-hover:opacity-100" />
+            </a>
+          );
+        })}
+      </div>
+    </section>
+  );
+}

frontend/components/chat-shell.tsx

@@ -0,0 +1,515 @@
+"use client";
+
+import clsx from "clsx";
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { Send, Square, WandSparkles } from "lucide-react";
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useTransition,
+} from "react";
+import { ChatMessage } from "@/components/chat-message";
+import { SourceSidebar } from "@/components/source-sidebar";
+import { fetchTools, getApiBaseUrl, type TutorTool } from "@/lib/api";
+import {
+  getMessageTextContent,
+  hasRenderableContent,
+  type TutorMessage,
+} from "@/lib/chat-ui";
+
+type ThreadDataPart = {
+  type: "data-thread";
+  data: {
+    threadId: string;
+  };
+};
+
+export function ChatShell() {
+  const [transport] = useState(
+    () => new DefaultChatTransport({ api: `${getApiBaseUrl()}/api/chat` }),
+  );
+  const [tools, setTools] = useState<TutorTool[]>([]);
+  const [selectedSourceKeys, setSelectedSourceKeys] = useState<string[]>([]);
+  const [sourceError, setSourceError] = useState<string | null>(null);
+  const [input, setInput] = useState("");
+  const [threadId, setThreadId] = useState("");
+  const [copiedMessageId, setCopiedMessageId] = useState<string | null>(null);
+  const [editingMessageId, setEditingMessageId] = useState<string | null>(null);
+  const [editingText, setEditingText] = useState("");
+  const [, startTransition] = useTransition();
+  const threadViewportRef = useRef<HTMLDivElement>(null);
+  const composerInputRef = useRef<HTMLTextAreaElement>(null);
+  const pendingScrollRef = useRef(false);
+  const [spacerHeight, setSpacerHeight] = useState(0);
+
+  const {
+    messages,
+    sendMessage,
+    regenerate,
+    stop,
+    status,
+    error,
+    clearError,
+  } = useChat({
+    transport,
+    onData: (part) => {
+      if (part.type === "data-thread") {
+        const nextThreadId = (part as ThreadDataPart).data.threadId;
+        if (nextThreadId) {
+          startTransition(() => setThreadId(nextThreadId));
+        }
+      }
+    },
+    experimental_throttle: 50,
+  });
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    async function loadTools() {
+      try {
+        const { tools: loadedTools } = await fetchTools(controller.signal);
+        setTools(loadedTools);
+        const retrieval = loadedTools.find(
+          (tool) => tool.kind === "configurable",
+        );
+        if (retrieval) {
+          setSelectedSourceKeys(
+            retrieval.sources
+              .filter((source) => source.selectedByDefault)
+              .map((source) => source.key),
+          );
+        }
+        setSourceError(null);
+      } catch (loadError) {
+        if (controller.signal.aborted) {
+          return;
+        }
+        setSourceError(
+          loadError instanceof Error
+            ? loadError.message
+            : "Unable to load tool registry.",
+        );
+      }
+    }
+
+    void loadTools();
+    return () => controller.abort();
+  }, []);
+
+  const isStreaming = status === "submitted" || status === "streaming";
+  const isReady = status === "ready";
+  const typedMessages = messages as TutorMessage[];
+  const latestMessage = typedMessages[typedMessages.length - 1];
+  const streamingAssistantId =
+    isStreaming && latestMessage?.role === "assistant"
+      ? latestMessage.id
+      : null;
+  const visibleMessages = typedMessages.filter((message) => {
+    if (message.id !== streamingAssistantId) {
+      return true;
+    }
+    return hasRenderableContent(message);
+  });
+  const chatColumnClass =
+    "mx-auto w-full max-w-[1040px] px-3 sm:px-5 lg:px-8 xl:px-10";
+
+  useEffect(() => {
+    const viewport = threadViewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    const userElements = viewport.querySelectorAll<HTMLElement>(
+      '[data-role="user"]',
+    );
+    const lastUserEl = userElements[userElements.length - 1];
+
+    let needed = 0;
+    if (lastUserEl && (isStreaming || pendingScrollRef.current)) {
+      const container = lastUserEl.parentElement;
+      const children = container
+        ? (Array.from(container.children) as HTMLElement[])
+        : [];
+      const lastNonSpacer = children
+        .filter((child) => child.dataset.spacer !== "true")
+        .pop();
+      if (lastNonSpacer) {
+        const spaceFromLastUserTop =
+          lastNonSpacer.getBoundingClientRect().bottom -
+          lastUserEl.getBoundingClientRect().top;
+        needed = Math.max(
+          0,
+          viewport.clientHeight - 24 - spaceFromLastUserTop,
+        );
+      }
+    }
+
+    setSpacerHeight(needed);
+  }, [messages, isStreaming]);
+
+  useLayoutEffect(() => {
+    if (!pendingScrollRef.current) {
+      return;
+    }
+    const viewport = threadViewportRef.current;
+    if (!viewport) {
+      return;
+    }
+    pendingScrollRef.current = false;
+
+    const users = viewport.querySelectorAll<HTMLElement>(
+      '[data-role="user"]',
+    );
+    const lastUserEl = users[users.length - 1];
+    if (!lastUserEl) {
+      return;
+    }
+
+    const delta =
+      lastUserEl.getBoundingClientRect().top -
+      viewport.getBoundingClientRect().top;
+    viewport.scrollTo({
+      top: Math.max(0, viewport.scrollTop + delta - 24),
+      behavior: "instant",
+    });
+  }, [spacerHeight]);
+
+  useEffect(() => {
+    const textarea = composerInputRef.current;
+    if (!textarea) {
+      return;
+    }
+
+    textarea.style.height = "0px";
+    textarea.style.height = `${Math.min(textarea.scrollHeight, 176)}px`;
+  }, [input]);
+
+  async function handleSubmit() {
+    const trimmed = input.trim();
+    if (!trimmed || isStreaming) {
+      return;
+    }
+
+    clearError();
+    setCopiedMessageId(null);
+    setEditingMessageId(null);
+    setEditingText("");
+    setInput("");
+    pendingScrollRef.current = true;
+    await sendMessage(
+      { text: trimmed },
+      {
+        body: {
+          sourceKeys: selectedSourceKeys,
+          includeReasoning: true,
+          threadId,
+        },
+      },
+    );
+  }
+
+  async function handleRedo(messageId?: string) {
+    clearError();
+    setCopiedMessageId(null);
+    await regenerate({
+      messageId,
+      body: {
+        sourceKeys: selectedSourceKeys,
+        includeReasoning: true,
+        threadId,
+      },
+    });
+  }
+
+  function handleEdit(messageId: string) {
+    const messageIndex = messages.findIndex((message) => message.id === messageId);
+    if (messageIndex === -1) {
+      return;
+    }
+
+    const message = messages[messageIndex] as TutorMessage;
+    const draft = getMessageTextContent(message);
+
+    clearError();
+    setCopiedMessageId(null);
+    setEditingMessageId(messageId);
+    setEditingText(draft);
+  }
+
+  async function handleCopy(message: TutorMessage) {
+    const text = getMessageTextContent(message);
+    if (!text) {
+      return;
+    }
+
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopiedMessageId(message.id);
+      window.setTimeout(() => {
+        setCopiedMessageId((current) =>
+          current === message.id ? null : current,
+        );
+      }, 1400);
+    } catch {
+      setCopiedMessageId(null);
+    }
+  }
+
+  function handleEditCancel() {
+    setEditingMessageId(null);
+    setEditingText("");
+  }
+
+  async function handleEditSave(messageId: string) {
+    const trimmed = editingText.trim();
+    if (!trimmed || isStreaming) {
+      return;
+    }
+
+    clearError();
+    setCopiedMessageId(null);
+    setEditingMessageId(null);
+    setEditingText("");
+    pendingScrollRef.current = true;
+    await sendMessage(
+      { text: trimmed, messageId },
+      {
+        body: {
+          sourceKeys: selectedSourceKeys,
+          includeReasoning: true,
+          threadId,
+        },
+      },
+    );
+  }
+
+  function toggleSource(sourceKey: string) {
+    setSelectedSourceKeys((current) =>
+      current.includes(sourceKey)
+        ? current.filter((key) => key !== sourceKey)
+        : [...current, sourceKey],
+    );
+  }
+
+  return (
+    <main className="min-h-screen p-2 lg:h-screen lg:overflow-hidden">
+      <div className="flex min-h-[calc(100vh-1rem)] w-full flex-col gap-2 lg:h-[calc(100vh-1rem)] lg:min-h-0 lg:grid lg:grid-cols-[248px_minmax(0,1fr)]">
+        <SourceSidebar
+          selectedSourceKeys={selectedSourceKeys}
+          sourceError={sourceError}
+          tools={tools}
+          onToggleSource={toggleSource}
+        />
+
+        <section className="glass-panel flex min-h-0 flex-col overflow-hidden rounded-[1.5rem] p-2 sm:p-2.5 lg:max-h-[calc(100vh-1rem)] lg:min-h-[calc(100vh-1rem)]">
+          <div
+            ref={threadViewportRef}
+            className="scrollbar-thin min-h-0 flex-1 overflow-y-auto"
+          >
+            {typedMessages.length === 0 ? (
+              <div className={clsx(chatColumnClass, "flex min-h-full")}>
+                <EmptyConversation
+                  onSelect={(prompt) => {
+                    setInput(prompt);
+                    composerInputRef.current?.focus();
+                  }}
+                />
+              </div>
+            ) : (
+              <div className={clsx(chatColumnClass, "flex flex-col gap-3 pt-4 pb-3")}>
+                {visibleMessages.map((message) => (
+                  <ChatMessage
+                    key={message.id}
+                    message={message}
+                    actionDisabled={isStreaming}
+                    copied={copiedMessageId === message.id}
+                    editDraft={editingMessageId === message.id ? editingText : ""}
+                    isEditing={editingMessageId === message.id}
+                    isStreaming={message.id === streamingAssistantId}
+                    onAssistantCopy={handleCopy}
+                    onAssistantRedo={(messageId) => void handleRedo(messageId)}
+                    onEditCancel={handleEditCancel}
+                    onEditChange={setEditingText}
+                    onEditSave={(messageId) => void handleEditSave(messageId)}
+                    onUserEdit={handleEdit}
+                    showAssistantActions={message.id !== streamingAssistantId}
+                  />
+                ))}
+                <div
+                  aria-hidden
+                  data-spacer="true"
+                  className="shrink-0"
+                  style={{ height: spacerHeight }}
+                />
+              </div>
+            )}
+          </div>
+
+          <footer className="sticky bottom-0 z-10 mt-2">
+            <div className={chatColumnClass}>
+              <div className="rounded-[1.1rem] border border-[var(--line)] bg-[var(--panel-strong)] px-2.5 py-2 shadow-[0_10px_30px_rgba(18,42,204,0.08)] backdrop-blur-xl">
+                <textarea
+                  ref={composerInputRef}
+                  rows={1}
+                  value={input}
+                  onChange={(event) => setInput(event.target.value)}
+                  onKeyDown={(event) => {
+                    if (
+                      event.key === "Enter" &&
+                      !event.shiftKey &&
+                      !event.altKey &&
+                      !event.ctrlKey &&
+                      !event.metaKey &&
+                      !event.nativeEvent.isComposing
+                    ) {
+                      event.preventDefault();
+                      void handleSubmit();
+                    }
+                  }}
+                  placeholder="Ask about RAG, LangGraph, PEFT, or any of your selected sources…"
+                  className="max-h-44 min-h-10 w-full resize-none overflow-y-auto bg-transparent px-0.5 py-2 text-[15px] leading-[1.6] tracking-[-0.012em] text-[var(--ink)] outline-none placeholder:text-[var(--muted)]"
+                />
+
+                <div className="mt-1.5 flex items-center justify-end gap-2">
+                  <ComposerActionButton
+                    disabled={!isStreaming && (!input.trim() || !isReady)}
+                    isStreaming={isStreaming}
+                    onClick={
+                      isStreaming ? () => stop() : () => void handleSubmit()
+                    }
+                  />
+                </div>
+              </div>
+
+              {error ? (
+                <p className="mt-2 rounded-[0.9rem] border border-red-300/70 bg-red-50 px-3 py-2 text-sm text-red-800">
+                  {error.message}
+                </p>
+              ) : null}
+            </div>
+          </footer>
+        </section>
+
+      </div>
+    </main>
+  );
+}
+
+function ComposerActionButton({
+  disabled,
+  isStreaming,
+  onClick,
+}: {
+  disabled: boolean;
+  isStreaming: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={isStreaming ? "Stop generating" : "Send message"}
+      title={isStreaming ? "Stop generating" : "Send message"}
+      className={clsx(
+        "relative inline-flex h-10 min-w-[8.75rem] items-center justify-center overflow-hidden rounded-full px-4 text-sm font-semibold transition disabled:cursor-not-allowed disabled:opacity-50",
+        isStreaming
+          ? "border border-[var(--line-strong)] bg-[rgba(11,136,238,0.12)] text-[var(--accent)] shadow-[0_12px_30px_rgba(11,136,238,0.14)] hover:border-[var(--accent)] hover:bg-[rgba(11,136,238,0.15)]"
+          : "bg-[var(--accent)] text-white hover:brightness-110",
+      )}
+    >
+      {isStreaming ? (
+        <>
+          <span
+            aria-hidden="true"
+            className="processing-button__sheen absolute inset-0 rounded-full"
+          />
+          <span
+            aria-hidden="true"
+            className="processing-button__orb absolute left-2 top-1/2 h-6 w-6 -translate-y-1/2 rounded-full"
+          />
+          <span className="relative z-10 inline-flex items-center gap-2.5">
+            <span
+              aria-hidden="true"
+              className="processing-button__pulse h-2.5 w-2.5 rounded-full"
+            />
+            <span>Streaming</span>
+            <span className="inline-flex h-6 w-6 items-center justify-center rounded-full bg-white/92 text-[var(--accent)] shadow-[0_6px_16px_rgba(11,136,238,0.18)]">
+              <Square className="h-3 w-3 fill-current" />
+            </span>
+          </span>
+        </>
+      ) : (
+        <span className="relative z-10 inline-flex items-center gap-2">
+          <Send className="h-4 w-4" />
+          <span>Send</span>
+        </span>
+      )}
+    </button>
+  );
+}
+
+const SUGGESTIONS: ReadonlyArray<{ title: string; prompt: string }> = [
+  {
+    title: "RAG vs fine-tuning",
+    prompt:
+      "When should I use retrieval-augmented generation instead of fine-tuning a model?",
+  },
+  {
+    title: "LoRA with PEFT",
+    prompt:
+      "Walk me through fine-tuning a model with LoRA using the PEFT library.",
+  },
+  {
+    title: "Build a LangGraph agent",
+    prompt:
+      "How do I build a tool-calling agent with LangGraph, step by step?",
+  },
+  {
+    title: "Evaluate a RAG pipeline",
+    prompt:
+      "What are practical ways to evaluate the quality of a RAG pipeline?",
+  },
+];
+
+function EmptyConversation({
+  onSelect,
+}: {
+  onSelect: (prompt: string) => void;
+}) {
+  return (
+    <div className="flex min-h-full flex-1 flex-col items-center justify-center px-4 py-10 text-center">
+      <div className="inline-flex h-11 w-11 items-center justify-center rounded-2xl bg-[var(--accent-faint)] text-[var(--accent)]">
+        <WandSparkles className="h-5 w-5" />
+      </div>
+      <h2 className="display-font mt-4 text-[1.95rem] leading-[1] text-[var(--ink)] sm:text-[2.2rem]">
+        Ask your AI tutor
+      </h2>
+      <p className="mt-2 max-w-md text-[13.5px] leading-[1.6] text-[var(--muted)]">
+        Answers are grounded in the sources you selected on the left. Try one of
+        these to start:
+      </p>
+      <div className="mt-6 grid w-full max-w-[640px] grid-cols-1 gap-2 sm:grid-cols-2">
+        {SUGGESTIONS.map((suggestion) => (
+          <button
+            key={suggestion.title}
+            type="button"
+            onClick={() => onSelect(suggestion.prompt)}
+            className="group flex flex-col items-start gap-1 rounded-[0.95rem] border border-[var(--line)] bg-[var(--surface)] px-3.5 py-3 text-left transition hover:-translate-y-0.5 hover:border-[var(--accent)] hover:bg-[var(--surface-strong)] hover:shadow-[0_8px_20px_rgba(11,136,238,0.08)]"
+          >
+            <span className="text-[12.5px] font-semibold tracking-[-0.01em] text-[var(--ink)]">
+              {suggestion.title}
+            </span>
+            <span className="text-[12px] leading-[1.45] text-[var(--muted)]">
+              {suggestion.prompt}
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}

frontend/components/markdown-block.tsx

@@ -0,0 +1,31 @@
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+type MarkdownBlockProps = {
+  children: string;
+  className?: string;
+};
+
+export function MarkdownBlock({
+  children,
+  className = "",
+}: MarkdownBlockProps) {
+  return (
+    <div className={`markdown-block ${className}`.trim()}>
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}
+        components={{
+          a: ({ ...props }) => (
+            <a
+              {...props}
+              target="_blank"
+              rel="noreferrer"
+            />
+          ),
+        }}
+      >
+        {children}
+      </ReactMarkdown>
+    </div>
+  );
+}

frontend/components/source-panel.tsx

@@ -0,0 +1,158 @@
+"use client";
+
+import clsx from "clsx";
+import {
+  ChevronLeft,
+  ChevronRight,
+  ExternalLink,
+  LibraryBig,
+  SearchCode,
+} from "lucide-react";
+import type { SourcePartData } from "@/lib/api";
+import type { TutorMessage } from "@/lib/chat-ui";
+import { getMessageSources } from "@/lib/chat-ui";
+
+type SourcePanelProps = {
+  isCollapsed: boolean;
+  message: TutorMessage | undefined;
+  onToggleCollapse: () => void;
+};
+
+export function SourcePanel({
+  isCollapsed,
+  message,
+  onToggleCollapse,
+}: SourcePanelProps) {
+  const sources = message ? getMessageSources(message) : [];
+
+  return (
+    <div className="relative min-h-0">
+      <button
+        type="button"
+        onClick={onToggleCollapse}
+        aria-label={isCollapsed ? "Expand sources panel" : "Collapse sources panel"}
+        aria-pressed={isCollapsed}
+        className="absolute left-0 top-5 z-20 hidden h-10 w-10 -translate-x-1/2 items-center justify-center rounded-full border border-[var(--line-strong)] bg-[rgba(247,251,254,0.96)] text-[var(--accent)] shadow-[0_14px_34px_rgba(18,42,204,0.12)] backdrop-blur-xl transition hover:border-[var(--accent)] hover:text-[var(--ink)] lg:flex"
+      >
+        {isCollapsed ? (
+          <ChevronLeft className="h-4 w-4" />
+        ) : (
+          <ChevronRight className="h-4 w-4" />
+        )}
+      </button>
+
+      <aside
+        className={clsx(
+          "glass-panel overflow-hidden rounded-[1.5rem] p-3 transition-[padding] duration-300 lg:flex lg:min-h-0 lg:max-h-[calc(100vh-1rem)] lg:min-h-[calc(100vh-1rem)] lg:rounded-r-none lg:flex-col",
+          isCollapsed && "lg:items-center lg:px-2 lg:py-3",
+        )}
+      >
+        <div
+          className={clsx(
+            "hidden h-full flex-col items-center gap-3 lg:flex",
+            !isCollapsed && "lg:hidden",
+          )}
+        >
+          <div className="flex h-10 w-10 items-center justify-center rounded-2xl bg-[var(--accent-faint)] text-[var(--accent)]">
+            <LibraryBig className="h-[18px] w-[18px]" />
+          </div>
+          {message ? (
+            <span className="rounded-full bg-white/70 px-2 py-1 text-[10px] font-semibold tracking-[0.02em] text-[var(--accent)]">
+              {sources.length}
+            </span>
+          ) : null}
+          <span className="[writing-mode:vertical-rl] text-[10px] font-semibold uppercase tracking-[0.16em] text-[var(--muted)]">
+            Sources
+          </span>
+        </div>
+
+        <div className={clsx("lg:flex lg:min-h-0 lg:flex-1 lg:flex-col", isCollapsed && "lg:hidden")}>
+          <div className="flex items-center gap-2 text-[13px] font-semibold tracking-[-0.012em] text-[var(--ink)]">
+            <LibraryBig className="h-4 w-4 text-[var(--accent)]" />
+            Sources
+          </div>
+
+          {!message ? (
+            <EmptyState
+              title="No answer selected"
+              body="Send a question or click any assistant answer to inspect the sources and relevance scores behind it."
+            />
+          ) : sources.length === 0 ? (
+            <EmptyState
+              title="No sources attached yet"
+              body="This assistant turn has not emitted source data yet. During streaming, the cards will populate here automatically."
+            />
+          ) : (
+            <div className="mt-3 space-y-2 lg:flex lg:min-h-0 lg:flex-1 lg:flex-col">
+              <div className="rounded-[1.1rem] border border-[var(--line)] bg-white/60 p-3">
+                <p className="text-[10px] font-semibold uppercase tracking-[0.12em] text-[var(--muted)]">
+                  Current answer
+                </p>
+                <p className="mt-1.5 text-[13px] leading-[1.45] tracking-[-0.01em] text-[var(--ink)]">
+                  {sources.length} supporting reference{sources.length === 1 ? "" : "s"}
+                </p>
+              </div>
+
+              <div className="scrollbar-thin min-w-0 space-y-2 pr-2 lg:min-h-0 lg:flex-1 lg:overflow-y-auto">
+                {sources.map((source) => (
+                  <SourceCard key={source.docId || source.url} source={source} />
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+      </aside>
+    </div>
+  );
+}
+
+function EmptyState({ title, body }: { title: string; body: string }) {
+  return (
+    <div className="mt-3 rounded-[1.1rem] border border-dashed border-[var(--line-strong)] bg-white/45 p-3">
+      <div className="flex items-center gap-2 text-[13px] font-semibold tracking-[-0.012em] text-[var(--ink)]">
+        <SearchCode className="h-4 w-4 text-[var(--accent)]" />
+        {title}
+      </div>
+      <p className="mt-1.5 text-[13px] leading-[1.55] text-[var(--muted)]">{body}</p>
+    </div>
+  );
+}
+
+function SourceCard({ source }: { source: SourcePartData }) {
+  const percentage = Math.max(0, Math.min(100, Math.round(source.score * 100)));
+
+  return (
+    <article className="animate-rise-in min-w-0 rounded-[1.1rem] border border-[var(--line)] bg-white/70 p-3 shadow-[0_18px_50px_rgba(18,42,204,0.08)]">
+      <div className="flex items-start justify-between gap-4">
+        <div className="min-w-0">
+          <p className="text-[10px] font-semibold uppercase tracking-[0.12em] text-[var(--muted)]">
+            {source.sourceLabel}
+          </p>
+          <h3 className="mt-1.5 line-clamp-3 text-[15px] font-semibold leading-[1.35] tracking-[-0.02em] text-[var(--ink)]">
+            {source.title}
+          </h3>
+        </div>
+        <span className="rounded-full bg-[var(--accent-faint)] px-2.5 py-1 text-[11px] font-semibold tracking-[-0.01em] text-[var(--accent)]">
+          {percentage}%
+        </span>
+      </div>
+
+      <div className="mt-2 h-2 overflow-hidden rounded-full bg-[var(--accent-faint)]">
+        <div
+          className="h-full rounded-full bg-[var(--accent)] transition-[width] duration-500"
+          style={{ width: `${percentage}%` }}
+        />
+      </div>
+
+      <a
+        href={source.url}
+        target="_blank"
+        rel="noreferrer"
+        className="mt-3 inline-flex items-center gap-2 text-[13px] font-medium tracking-[-0.01em] text-[var(--accent)] transition hover:text-[var(--ink)]"
+      >
+        Open source
+        <ExternalLink className="h-4 w-4" />
+      </a>
+    </article>
+  );
+}

frontend/components/source-sidebar.tsx

@@ -0,0 +1,254 @@
+"use client";
+
+import clsx from "clsx";
+import {
+  BookOpen,
+  ChevronDown,
+  Globe,
+  GraduationCap,
+  Library,
+  Link as LinkIcon,
+  Wrench,
+} from "lucide-react";
+import { useState, type ComponentType, type SVGProps } from "react";
+import type { TutorSource, TutorTool } from "@/lib/api";
+
+type SourceSidebarProps = {
+  selectedSourceKeys: string[];
+  sourceError: string | null;
+  tools: TutorTool[];
+  onToggleSource: (sourceKey: string) => void;
+};
+
+type ToggleToolMeta = {
+  icon: ComponentType<SVGProps<SVGSVGElement>>;
+};
+
+const TOGGLE_TOOL_META: Record<string, ToggleToolMeta> = {
+  web_search: { icon: Globe },
+  url_context: { icon: LinkIcon },
+};
+
+export function SourceSidebar({
+  selectedSourceKeys,
+  sourceError,
+  tools,
+  onToggleSource,
+}: SourceSidebarProps) {
+  const retrievalTool = tools.find(
+    (tool): tool is Extract<TutorTool, { kind: "configurable" }> =>
+      tool.kind === "configurable",
+  );
+  const toggleTools = tools.filter(
+    (tool): tool is Extract<TutorTool, { kind: "toggle" }> =>
+      tool.kind === "toggle",
+  );
+  const activeCount =
+    (retrievalTool && selectedSourceKeys.length > 0 ? 1 : 0) +
+    toggleTools.filter((tool) => tool.active).length;
+  const totalCount = (retrievalTool ? 1 : 0) + toggleTools.length;
+
+  return (
+    <aside className="glass-panel relative overflow-hidden rounded-[1.5rem] p-2.5 lg:flex lg:min-h-0 lg:max-h-[calc(100vh-1rem)] lg:min-h-[calc(100vh-1rem)] lg:flex-col">
+      <div className="grain-mask absolute inset-0" />
+      <div className="relative flex flex-col gap-2.5 lg:min-h-0 lg:flex-1">
+        <div className="space-y-0.5 px-1 pt-0.5">
+          <h1 className="text-[1.3rem] font-semibold leading-tight tracking-[-0.03em] text-[var(--ink)]">
+            AI Tutor
+          </h1>
+          <p className="text-[11.5px] leading-[1.45] text-[var(--muted)]">
+            Pick the tools that guide the agent.
+          </p>
+        </div>
+
+        <div className="flex items-center justify-between border-t border-[var(--line)] px-1 pt-2">
+          <div className="flex items-center gap-1.5">
+            <Wrench className="h-3.5 w-3.5 text-[var(--accent)]" />
+            <span className="text-[10.5px] font-semibold uppercase tracking-[0.12em] text-[var(--muted)]">
+              Tools
+            </span>
+          </div>
+          <span className="rounded-full bg-[var(--accent-faint)] px-2 py-0.5 text-[10.5px] font-semibold tracking-[-0.01em] text-[var(--accent)]">
+            {activeCount}/{totalCount}
+          </span>
+        </div>
+
+        <div className="scrollbar-thin space-y-2 pr-0.5 lg:min-h-0 lg:flex-1 lg:overflow-y-auto">
+          {retrievalTool ? (
+            <RetrievalTool
+              tool={retrievalTool}
+              selectedSourceKeys={selectedSourceKeys}
+              onToggleSource={onToggleSource}
+            />
+          ) : null}
+          {toggleTools.map((tool) => (
+            <ToggleToolRow key={tool.key} tool={tool} />
+          ))}
+        </div>
+
+        {sourceError ? (
+          <p className="rounded-[0.75rem] border border-amber-300/60 bg-amber-50 px-2.5 py-1.5 text-[12px] text-amber-800">
+            {sourceError}
+          </p>
+        ) : null}
+      </div>
+    </aside>
+  );
+}
+
+function RetrievalTool({
+  tool,
+  selectedSourceKeys,
+  onToggleSource,
+}: {
+  tool: Extract<TutorTool, { kind: "configurable" }>;
+  selectedSourceKeys: string[];
+  onToggleSource: (sourceKey: string) => void;
+}) {
+  const [isOpen, setIsOpen] = useState(true);
+  const courseSources = tool.sources.filter((source) => source.group === "courses");
+  const docSources = tool.sources.filter((source) => source.group === "docs");
+
+  return (
+    <section className="space-y-1">
+      <button
+        type="button"
+        onClick={() => setIsOpen((current) => !current)}
+        aria-expanded={isOpen}
+        className="flex w-full items-center gap-2 rounded-[0.75rem] px-2 py-1.5 text-left transition hover:bg-[var(--surface-soft)]"
+      >
+        <Library className="h-3.5 w-3.5 shrink-0 text-[var(--accent)]" />
+        <span className="min-w-0 flex-1 truncate text-[12.5px] font-semibold tracking-[-0.01em] text-[var(--ink)]">
+          {tool.label}
+        </span>
+        <ChevronDown
+          className={clsx(
+            "h-3.5 w-3.5 shrink-0 text-[var(--muted)] transition-transform",
+            isOpen && "rotate-180",
+          )}
+        />
+      </button>
+
+      {isOpen ? (
+        <div className="ml-[11px] space-y-2.5 border-l border-[var(--line-strong)] pl-3">
+          {courseSources.length > 0 ? (
+            <SourceGroup
+              label="Courses"
+              icon={GraduationCap}
+              sources={courseSources}
+              selectedSourceKeys={selectedSourceKeys}
+              onToggleSource={onToggleSource}
+            />
+          ) : null}
+          {docSources.length > 0 ? (
+            <SourceGroup
+              label="Open-source docs"
+              icon={BookOpen}
+              sources={docSources}
+              selectedSourceKeys={selectedSourceKeys}
+              onToggleSource={onToggleSource}
+            />
+          ) : null}
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+function SourceGroup({
+  label,
+  icon: Icon,
+  sources,
+  selectedSourceKeys,
+  onToggleSource,
+}: {
+  label: string;
+  icon: ComponentType<SVGProps<SVGSVGElement>>;
+  sources: TutorSource[];
+  selectedSourceKeys: string[];
+  onToggleSource: (sourceKey: string) => void;
+}) {
+  return (
+    <div className="space-y-1">
+      <div className="flex items-center gap-1.5 px-1">
+        <Icon className="h-3 w-3 text-[var(--muted)]/70" />
+        <h2 className="text-[10px] font-medium tracking-[0.02em] text-[var(--muted)]/80">
+          {label}
+        </h2>
+      </div>
+
+      <div className="space-y-1">
+        {sources.map((source) => {
+          const selected = selectedSourceKeys.includes(source.key);
+          const isCourse = source.group === "courses";
+          return (
+            <button
+              key={source.key}
+              type="button"
+              onClick={() => onToggleSource(source.key)}
+              className={clsx(
+                "flex w-full items-center gap-2 rounded-[0.75rem] border px-2 py-1.5 text-left transition",
+                selected
+                  ? isCourse
+                    ? "border-[var(--accent)] bg-[var(--accent)] text-white shadow-[0_4px_12px_rgba(11,136,238,0.18)]"
+                    : "border-[var(--accent)] bg-[var(--accent-soft)] text-[var(--ink)]"
+                  : "border-[var(--line)] bg-[var(--surface-soft)] text-[var(--ink)] hover:border-[var(--line-strong)] hover:bg-[var(--surface-hover)]",
+              )}
+            >
+              <span
+                className={clsx(
+                  "flex h-4 w-4 shrink-0 items-center justify-center rounded-full border text-[9px] font-bold",
+                  selected
+                    ? isCourse
+                      ? "border-white/70 bg-white text-[var(--accent)]"
+                      : "border-[var(--accent)] bg-[var(--accent)] text-white"
+                    : "border-[var(--line-strong)] text-transparent",
+                )}
+              >
+                ✓
+              </span>
+              <span className="min-w-0 truncate text-[12.5px] font-medium tracking-[-0.01em]">
+                {formatSourceLabel(source.label)}
+              </span>
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function ToggleToolRow({
+  tool,
+}: {
+  tool: Extract<TutorTool, { kind: "toggle" }>;
+}) {
+  const meta = TOGGLE_TOOL_META[tool.key];
+  const Icon = meta?.icon ?? Globe;
+  return (
+    <div
+      className="flex items-center gap-2 rounded-[0.9rem] border border-[var(--line)] bg-[var(--surface-subtle)] px-2 py-2"
+      title={tool.active ? "Always on for this model" : "Unavailable"}
+    >
+      <Icon className="h-3.5 w-3.5 shrink-0 text-[var(--accent)]" />
+      <span className="min-w-0 flex-1 truncate text-[12.5px] font-medium tracking-[-0.01em] text-[var(--ink)]">
+        {tool.label}
+      </span>
+      <span
+        aria-label={tool.active ? "on" : "off"}
+        className={clsx(
+          "inline-flex items-center rounded-full px-1.5 py-0.5 text-[9.5px] font-semibold uppercase tracking-[0.1em]",
+          tool.active
+            ? "bg-[var(--accent-faint)] text-[var(--accent)]"
+            : "bg-[var(--muted)]/15 text-[var(--muted)]",
+        )}
+      >
+        {tool.active ? "on" : "off"}
+      </span>
+    </div>
+  );
+}
+
+function formatSourceLabel(label: string) {
+  return label.replace(/\s+Docs$/, "");
+}

frontend/eslint.config.mjs

@@ -0,0 +1,6 @@
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTypescript from "eslint-config-next/typescript";
+
+const eslintConfig = [...nextVitals, ...nextTypescript];
+
+export default eslintConfig;

frontend/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

frontend/next.config.mjs

@@ -0,0 +1,14 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  turbopack: {
+    root: __dirname,
+  },
+};
+
+export default nextConfig;

frontend/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

scripts/api.py

@@ -2,19 +2,28 @@ from __future__ import annotations
 
 import json
 import os
-from typing import Any
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator
 from uuid import uuid4
 
+import logfire
 import uvicorn
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel, Field
 
-from .chat_service import message_content_to_text, stream_chat
+from .chat_service import (
+    get_retriever,
+    is_google_genai_model,
+    message_content_to_text,
+    stream_chat,
+)
 from .chat_types import ChatEvent, ChatRequest, ChatTurn
 from .setup import (
+    AVAILABLE_SOURCES,
     AVAILABLE_SOURCES_UI,
+    COURSE_SOURCE_KEYS,
     DEFAULT_MODEL_NAME,
     DEFAULT_SELECTED_SOURCE_KEYS,
     DEFAULT_SELECTED_SOURCES_UI,
@@ -42,7 +51,40 @@ def parse_cors_origins() -> list[str]:
     return [origin.strip() for origin in raw.split(",") if origin.strip()] or ["*"]
 
 
-app = FastAPI(title="AI Tutor API")
+def parse_bind_port() -> int:
+    raw = os.getenv("AI_TUTOR_API_PORT") or os.getenv("PORT") or "8000"
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise ValueError(f"Invalid API port: {raw!r}") from exc
+
+
+def parse_bind_host() -> str:
+    return (os.getenv("AI_TUTOR_API_HOST") or os.getenv("HOST") or "0.0.0.0").strip()
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+    """Warm up the Chroma retriever before serving any requests.
+
+    LangGraph's ToolNode runs sync tools in a threadpool, and parallel
+    `retrieve_tutor_context` calls can race into `PersistentClient(...)`
+    at the same time on the first turn. That race occasionally surfaces
+    `Could not connect to tenant default_tenant`. Touching the retriever
+    at startup forces single-threaded tenant init.
+    """
+    if os.environ.get("COHERE_API_KEY"):
+        try:
+            get_retriever()
+        except Exception as exc:  # pragma: no cover - diagnostic logging only
+            logfire.warn(
+                "Retriever warm-up failed; first retrieval call may retry.",
+                error=str(exc),
+            )
+    yield
+
+
+app = FastAPI(title="AI Tutor API", lifespan=lifespan)
 app.add_middleware(
     CORSMiddleware,
     allow_origins=parse_cors_origins(),
@@ -94,7 +136,13 @@ def build_chat_request(payload: ApiChatRequest) -> ChatRequest:
     if not query:
         raise HTTPException(status_code=422, detail="query is required")
 
-    source_keys = tuple(payload.sourceKeys or DEFAULT_SELECTED_SOURCE_KEYS)
+    allowed_source_keys = set(AVAILABLE_SOURCES)
+    requested_source_keys = payload.sourceKeys or list(DEFAULT_SELECTED_SOURCE_KEYS)
+    source_keys = tuple(
+        dict.fromkeys(
+            key for key in requested_source_keys if key in allowed_source_keys
+        )
+    ) or DEFAULT_SELECTED_SOURCE_KEYS
     return ChatRequest(
         query=query,
         history=history,
@@ -109,10 +157,18 @@ class UIMessageStreamEncoder:
     def __init__(self) -> None:
         self.message_id = ""
         self.text_block_id = ""
-        self.reasoning_block_ids: dict[str, str] = {}
+        self.active_reasoning_id = ""
         self.source_matches_by_call_id: dict[str, list[dict[str, Any]]] = {}
         self.closed = False
 
+    def close_reasoning_block(self) -> list[dict[str, Any]]:
+        if not self.active_reasoning_id:
+            return []
+
+        parts = [{"type": "reasoning-end", "id": self.active_reasoning_id}]
+        self.active_reasoning_id = ""
+        return parts
+
     def encode(self, event: ChatEvent) -> list[dict[str, Any]]:
         parts: list[dict[str, Any]] = []
 
@@ -127,11 +183,13 @@ class UIMessageStreamEncoder:
 
         if event.type == "message_started":
             self.message_id = str(event.data.get("message_id", uuid4().hex))
+            self.active_reasoning_id = ""
             parts.append({"type": "start", "messageId": self.message_id})
             parts.append({"type": "start-step"})
             return parts
 
         if event.type == "text_delta":
+            parts.extend(self.close_reasoning_block())
             if not self.text_block_id:
                 self.text_block_id = f"text_{self.message_id or uuid4().hex}"
                 parts.append({"type": "text-start", "id": self.text_block_id})
@@ -145,22 +203,20 @@ class UIMessageStreamEncoder:
             return parts
 
         if event.type == "reasoning_delta":
-            step = str(event.data.get("step", "")) or "default"
-            reasoning_id = self.reasoning_block_ids.get(step)
-            if reasoning_id is None:
-                reasoning_id = f"reasoning_{step}_{uuid4().hex[:8]}"
-                self.reasoning_block_ids[step] = reasoning_id
-                parts.append({"type": "reasoning-start", "id": reasoning_id})
+            if not self.active_reasoning_id:
+                self.active_reasoning_id = f"reasoning_{uuid4().hex[:8]}"
+                parts.append({"type": "reasoning-start", "id": self.active_reasoning_id})
             parts.append(
                 {
                     "type": "reasoning-delta",
-                    "id": reasoning_id,
+                    "id": self.active_reasoning_id,
                     "delta": str(event.data.get("text", "")),
                 }
             )
             return parts
 
         if event.type == "tool_call_started":
+            parts.extend(self.close_reasoning_block())
             call_id = str(event.data.get("call_id", uuid4().hex))
             tool_name = str(event.data.get("tool_name", "tool"))
             parts.append(
@@ -223,6 +279,7 @@ class UIMessageStreamEncoder:
             return parts
 
         if event.type == "tool_call_completed":
+            parts.extend(self.close_reasoning_block())
             call_id = str(event.data.get("call_id", uuid4().hex))
             output = {
                 "text": str(event.data.get("output_text", "")),
@@ -238,6 +295,7 @@ class UIMessageStreamEncoder:
             return parts
 
         if event.type == "message_completed":
+            parts.extend(self.close_reasoning_block())
             answer = str(event.data.get("answer", "")).strip()
             if answer and not self.text_block_id:
                 self.text_block_id = f"text_{self.message_id or uuid4().hex}"
@@ -248,11 +306,9 @@ class UIMessageStreamEncoder:
                         "id": self.text_block_id,
                         "delta": answer,
                     }
-                )
+            )
             if self.text_block_id:
                 parts.append({"type": "text-end", "id": self.text_block_id})
-            for reasoning_id in self.reasoning_block_ids.values():
-                parts.append({"type": "reasoning-end", "id": reasoning_id})
             parts.append({"type": "finish-step"})
             parts.append({"type": "finish"})
             self.closed = True
@@ -263,10 +319,9 @@ class UIMessageStreamEncoder:
     def finish_error(self, error_text: str) -> list[dict[str, Any]]:
         parts: list[dict[str, Any]] = [{"type": "error", "errorText": error_text}]
         if not self.closed:
+            parts.extend(self.close_reasoning_block())
             if self.text_block_id:
                 parts.append({"type": "text-end", "id": self.text_block_id})
-            for reasoning_id in self.reasoning_block_ids.values():
-                parts.append({"type": "reasoning-end", "id": reasoning_id})
             if self.message_id:
                 parts.append({"type": "finish-step"})
                 parts.append({"type": "finish"})
@@ -279,19 +334,55 @@ def healthcheck() -> dict[str, str]:
     return {"status": "ok"}
 
 
-@app.get("/api/sources")
-def list_sources() -> dict[str, Any]:
+def _source_entries() -> list[dict[str, Any]]:
     defaults = set(DEFAULT_SELECTED_SOURCES_UI)
-    return {
-        "sources": [
+    entries: list[dict[str, Any]] = []
+    for label in AVAILABLE_SOURCES_UI:
+        key = SOURCE_UI_TO_KEY[label]
+        entries.append(
             {
                 "label": label,
-                "key": SOURCE_UI_TO_KEY[label],
+                "key": key,
+                "group": "courses" if key in COURSE_SOURCE_KEYS else "docs",
                 "selectedByDefault": label in defaults,
             }
-            for label in AVAILABLE_SOURCES_UI
-        ]
+        )
+    return entries
+
+
+def _tool_catalog(model_name: str) -> list[dict[str, Any]]:
+    retrieval_tool: dict[str, Any] = {
+        "key": "retrieval",
+        "label": "Retrieval",
+        "kind": "configurable",
+        "active": True,
+        "sources": _source_entries(),
     }
+    tools: list[dict[str, Any]] = [retrieval_tool]
+    if is_google_genai_model(model_name):
+        tools.append(
+            {
+                "key": "web_search",
+                "label": "Web search",
+                "kind": "toggle",
+                "active": True,
+            }
+        )
+        tools.append(
+            {
+                "key": "url_context",
+                "label": "URL reading",
+                "kind": "toggle",
+                "active": True,
+            }
+        )
+    return tools
+
+
+@app.get("/api/tools")
+def list_tools(model: str | None = None) -> dict[str, Any]:
+    model_name = (model or DEFAULT_MODEL_NAME).strip() or DEFAULT_MODEL_NAME
+    return {"model": model_name, "tools": _tool_catalog(model_name)}
 
 
 @app.post("/api/chat")
@@ -327,4 +418,9 @@ async def chat(payload: ApiChatRequest) -> StreamingResponse:
 
 
 if __name__ == "__main__":
-    uvicorn.run("scripts.api:app", host="0.0.0.0", port=8000, reload=False)
+    uvicorn.run(
+        "scripts.api:app",
+        host=parse_bind_host(),
+        port=parse_bind_port(),
+        reload=False,
+    )

scripts/chat_service.py

@@ -9,6 +9,7 @@ from uuid import uuid4
 
 import logfire
 from langchain.agents import create_agent
+from langchain.agents.middleware import AgentMiddleware
 from langchain.tools import ToolRuntime, tool
 from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage, HumanMessage
 from langchain_openai import ChatOpenAI
@@ -53,7 +54,21 @@ def get_retriever() -> LocalChromaRetriever:
     )
 
 
-@tool
+RETRIEVE_TUTOR_CONTEXT_SCHEMA = {
+    "title": "retrieve_tutor_context",
+    "description": "Retrieve relevant course and documentation context for an AI tutor question.",
+    "type": "object",
+    "properties": {
+        "query": {
+            "type": "string",
+            "description": "The question or topic to search for in the course and documentation corpus.",
+        },
+    },
+    "required": ["query"],
+}
+
+
+@tool(args_schema=RETRIEVE_TUTOR_CONTEXT_SCHEMA)
 def retrieve_tutor_context(query: str, runtime: ToolRuntime[AppContext]) -> str:
     """Retrieve relevant course and documentation context for an AI tutor question."""
     results = get_retriever().search(
@@ -202,6 +217,9 @@ def sync_thread_with_history(
         state.values.get("messages", [])
     )
 
+    if checkpoint_history == history:
+        return thread_id
+
     if not checkpoint_history:
         restored_messages = history_to_langgraph_messages(history)
         if restored_messages:
@@ -210,12 +228,6 @@ def sync_thread_with_history(
             )
         return thread_id
 
-    if not history:
-        return thread_id
-
-    if checkpoint_history == history:
-        return thread_id
-
     branched_thread_id = new_thread_id()
     restored_messages = history_to_langgraph_messages(history)
     if restored_messages:
@@ -336,18 +348,113 @@ def build_chat_model(model_name: str, include_thoughts: bool = False):
     )
 
 
+class GeminiServerSideToolsMiddleware(AgentMiddleware):
+    """Enable server-side tool invocation for Gemini 3 tool combinations.
+
+    Combining built-in tools (e.g. `google_search`, `url_context`) with
+    user-defined function declarations requires
+    `include_server_side_tool_invocations=True` on Gemini's `ToolConfig`.
+    We inject it via `model_settings` so it flows through LangChain's
+    `bind_tools(..., tool_config=...)` path.
+    """
+
+    def _inject(self, request):
+        existing = request.model_settings.get("tool_config") or {}
+        if isinstance(existing, dict):
+            next_tool_config: Any = {
+                **existing,
+                "include_server_side_tool_invocations": True,
+            }
+        else:
+            next_tool_config = existing
+        new_settings = {**request.model_settings, "tool_config": next_tool_config}
+        return request.override(model_settings=new_settings)
+
+    def wrap_model_call(self, request, handler):
+        return handler(self._inject(request))
+
+    async def awrap_model_call(self, request, handler):
+        return await handler(self._inject(request))
+
+
 @lru_cache(maxsize=8)
 def build_agent(model_name: str, include_thoughts: bool = False):
     model = build_chat_model(model_name, include_thoughts=include_thoughts)
+    tools: list[Any] = [retrieve_tutor_context]
+    middleware: list[AgentMiddleware] = []
+    if is_google_genai_model(model_name):
+        tools.append({"google_search": {}})
+        tools.append({"url_context": {}})
+        middleware.append(GeminiServerSideToolsMiddleware())
     return create_agent(
         model=model,
-        tools=[retrieve_tutor_context],
+        tools=tools,
         system_prompt=system_message_openai_agent,
         context_schema=AppContext,
         checkpointer=CHECKPOINTER,
+        middleware=middleware,
     )
 
 
+def extract_web_search_queries(response_metadata: Any) -> list[str]:
+    """Pull the queries Gemini ran against google_search from grounding metadata."""
+    if not isinstance(response_metadata, dict):
+        return []
+    grounding = response_metadata.get("grounding_metadata") or {}
+    queries = grounding.get("web_search_queries") or []
+    return [str(q).strip() for q in queries if isinstance(q, str) and str(q).strip()]
+
+
+def extract_grounding_source_matches(
+    response_metadata: Any,
+    matches_by_doc_id: dict[str, SourceMatch],
+) -> list[SourceMatch]:
+    """Turn Gemini grounding metadata into source matches (deduped by URI)."""
+    if not isinstance(response_metadata, dict):
+        return []
+    grounding = response_metadata.get("grounding_metadata") or {}
+    chunks = grounding.get("grounding_chunks") or []
+    if not chunks:
+        return []
+
+    confidence_by_index: dict[int, float] = {}
+    for support in grounding.get("grounding_supports") or []:
+        indices = support.get("grounding_chunk_indices") or []
+        scores = support.get("confidence_scores") or []
+        for idx, score in zip(indices, scores):
+            if not isinstance(idx, int):
+                continue
+            numeric = float(score) if isinstance(score, (int, float)) else 0.0
+            if numeric > confidence_by_index.get(idx, 0.0):
+                confidence_by_index[idx] = numeric
+
+    updated: list[SourceMatch] = []
+    for idx, chunk in enumerate(chunks):
+        web = (chunk or {}).get("web") or {}
+        uri = str(web.get("uri") or "").strip()
+        if not uri:
+            continue
+        title = str(web.get("title") or uri).strip()
+        doc_id = f"google_search::{uri}"
+        if doc_id in matches_by_doc_id:
+            continue
+        score = confidence_by_index.get(idx, 1.0)
+        source_match = SourceMatch(
+            doc_id=doc_id,
+            title=title,
+            url=uri,
+            source_key="google_search",
+            source_label="Web",
+            score=score,
+        )
+        matches_by_doc_id[doc_id] = source_match
+        updated.append(source_match)
+    return updated
+
+
+GOOGLE_SEARCH_TOOL_NAME = "google_search"
+
+
 async def stream_chat(request: ChatRequest) -> AsyncIterator[ChatEvent]:
     normalized_history = normalize_history(request.history)
     matches_by_doc_id: dict[str, SourceMatch] = {}
@@ -358,6 +465,9 @@ async def stream_chat(request: ChatRequest) -> AsyncIterator[ChatEvent]:
     include_reasoning = bool(request.include_reasoning) and is_google_genai_model(
         request.model_name
     )
+    google_search_call_id = ""
+    google_search_queries: list[str] = []
+    google_search_match_count = 0
 
     logfire.info("Running query", query=request.query)
     agent = build_agent(request.model_name, include_thoughts=include_reasoning)
@@ -427,6 +537,46 @@ async def stream_chat(request: ChatRequest) -> AsyncIterator[ChatEvent]:
                         "text": text_delta,
                     },
                 )
+
+            token_metadata = getattr(token, "response_metadata", None)
+            new_queries = [
+                q
+                for q in extract_web_search_queries(token_metadata)
+                if q not in google_search_queries
+            ]
+            new_grounding = extract_grounding_source_matches(
+                token_metadata,
+                matches_by_doc_id,
+            )
+            if (new_queries or new_grounding) and not google_search_call_id:
+                google_search_call_id = uuid4().hex
+                yield ChatEvent(
+                    "tool_call_started",
+                    {
+                        "message_id": message_id,
+                        "call_id": google_search_call_id,
+                        "tool_name": GOOGLE_SEARCH_TOOL_NAME,
+                        "args": {"query": "; ".join(new_queries) if new_queries else ""},
+                        "args_text": "; ".join(new_queries),
+                    },
+                )
+            if new_queries:
+                google_search_queries.extend(new_queries)
+            for source_match in new_grounding:
+                google_search_match_count += 1
+                yield ChatEvent(
+                    "source_match",
+                    {
+                        "message_id": message_id,
+                        "doc_id": source_match.doc_id,
+                        "title": source_match.title,
+                        "url": source_match.url,
+                        "source_key": source_match.source_key,
+                        "source_label": source_match.source_label,
+                        "score": source_match.score,
+                        "call_id": google_search_call_id,
+                    },
+                )
             continue
 
         if chunk["type"] != "updates":
@@ -478,10 +628,72 @@ async def stream_chat(request: ChatRequest) -> AsyncIterator[ChatEvent]:
 
             if step != "model" or getattr(message, "type", None) != "ai":
                 continue
+
+            message_metadata = getattr(message, "response_metadata", None)
+            new_queries = [
+                q
+                for q in extract_web_search_queries(message_metadata)
+                if q not in google_search_queries
+            ]
+            new_grounding = extract_grounding_source_matches(
+                message_metadata,
+                matches_by_doc_id,
+            )
+            if (new_queries or new_grounding) and not google_search_call_id:
+                google_search_call_id = uuid4().hex
+                yield ChatEvent(
+                    "tool_call_started",
+                    {
+                        "message_id": message_id,
+                        "call_id": google_search_call_id,
+                        "tool_name": GOOGLE_SEARCH_TOOL_NAME,
+                        "args": {"query": "; ".join(new_queries) if new_queries else ""},
+                        "args_text": "; ".join(new_queries),
+                    },
+                )
+            if new_queries:
+                google_search_queries.extend(new_queries)
+            for source_match in new_grounding:
+                google_search_match_count += 1
+                yield ChatEvent(
+                    "source_match",
+                    {
+                        "message_id": message_id,
+                        "doc_id": source_match.doc_id,
+                        "title": source_match.title,
+                        "url": source_match.url,
+                        "source_key": source_match.source_key,
+                        "source_label": source_match.source_label,
+                        "score": source_match.score,
+                        "call_id": google_search_call_id,
+                    },
+                )
+
             if getattr(message, "tool_calls", None):
                 continue
             completed_answer = message_content_to_text(message.content)
 
+    if google_search_call_id:
+        joined_queries = "; ".join(google_search_queries)
+        if google_search_match_count == 0:
+            output_text = "Google search ran but returned no grounding results."
+        else:
+            plural = "" if google_search_match_count == 1 else "s"
+            output_text = (
+                f"Google search returned {google_search_match_count} web result{plural}."
+            )
+        yield ChatEvent(
+            "tool_call_completed",
+            {
+                "message_id": message_id,
+                "call_id": google_search_call_id,
+                "tool_name": GOOGLE_SEARCH_TOOL_NAME,
+                "args": {"query": joined_queries},
+                "args_text": joined_queries,
+                "output_text": output_text,
+            },
+        )
+
     answer = "".join(answer_chunks).strip() or completed_answer.strip()
     yield ChatEvent(
         "message_completed",

scripts/prompts.py

@@ -1,17 +1,73 @@
 system_message_openai_agent = """You are an AI teacher for applied AI, LLM, RAG, and Python topics.
 
-Your job is to answer student questions clearly and accurately. Use the retrieval tool when the question depends on the course or documentation corpus. Do not use retrieval when it is unnecessary.
-
-Rules:
-- Call `retrieve_tutor_context` for questions that require facts from the course or documentation corpus.
-- Do not call `retrieve_tutor_context` for greetings, small talk, general conversation, or questions about your own role/capabilities in this app.
-- For questions about what you can do, answer directly from your role in this app without retrieval.
-- When you do use retrieval, base factual claims about the corpus on the retrieved results.
-- If the retrieval results are weak or missing, say that the answer is not well covered by the current knowledge base.
-- Synthesize retrieved material into a clear teaching answer. Do not copy tool output verbatim unless a code block should be preserved.
-- Prefer a few solid paragraphs over shallow bullet spam.
-- If retrieved content includes code, include complete runnable code blocks when that is useful.
-- End with a short invitation for the student to ask a follow-up question.
-
-The retrieval tool returns JSON with matched passages and source metadata. Use that evidence faithfully when retrieval is needed.
+Your job is to answer student questions clearly and accurately. You have
+three tools available:
+
+- `retrieve_tutor_context` — retrieval over the course and documentation
+  corpus. Use this for anything that depends on course content.
+- `google_search` (Gemini built-in, when available) — live web search for
+  current events, recent library releases, or facts outside the corpus.
+- `url_context` (Gemini built-in, when available) — read a specific URL
+  in depth when the user provides one or when a search result needs to be
+  inspected closely.
+
+## When to use the retrieval tool
+
+USE retrieval for:
+- Questions about course content, concepts, code examples, or documentation.
+- Factual questions where you need to ground the answer in the corpus.
+
+DO NOT use retrieval for:
+- Greetings or small talk.
+- Questions about your own role or capabilities in this app (answer directly).
+- Questions you can answer fully from general knowledge with no corpus dependency.
+
+## When to use web search / URL reading
+
+USE `google_search` for:
+- Questions about recent events, releases, or API changes that may post-date
+  the corpus.
+- Facts the corpus likely does not cover (product pricing, news, etc.).
+
+USE `url_context` for:
+- Any URL the user pastes in their question.
+- A search result you need to read in detail to answer accurately.
+
+Prefer `retrieve_tutor_context` first when the question is clearly about
+course material. Combine tools when it helps (e.g. retrieve corpus context,
+then search the web for the latest update).
+
+## How to call the retrieval tool
+
+You have two strategies. Pick one per turn:
+
+1. PARALLEL CALLS (preferred for broad or multi-part questions):
+   If the question covers multiple sub-topics, asks for a comparison, or is
+   broad enough that one query will miss context, issue 2-4 parallel calls
+   with DIFFERENT queries. Each query should target a distinct angle,
+   sub-topic, or phrasing. Do not issue near-duplicate queries.
+
+   Example: "Compare RAG and fine-tuning for domain adaptation"
+   → parallel queries: "RAG for domain adaptation", "fine-tuning for domain
+     adaptation", "RAG vs fine-tuning tradeoffs".
+
+2. SEQUENTIAL FOLLOW-UP (for narrow questions or when first results are weak):
+   Start with one focused query. If the results are off-topic, too sparse,
+   or miss a key aspect of the question, call the tool again with a
+   refined query (different keywords, more specific, or targeting the gap).
+   Stop after at most 2 sequential calls.
+
+## Answering rules
+
+- Ground factual claims about the corpus in the retrieved results.
+- If retrieval results are weak or missing, say the topic is not well
+  covered by the current knowledge base rather than guessing.
+- Synthesize retrieved material into a clear teaching explanation. Do not
+  paste tool output verbatim, except for code blocks that should be
+  preserved as-is.
+- Prefer a few solid paragraphs over shallow bullet lists.
+- Include complete, runnable code blocks when code is relevant.
+- End with a short invitation for a follow-up question.
+
+The retrieval tool returns JSON with matched passages and source metadata.
 """

scripts/setup.py

@@ -14,7 +14,7 @@ except Exception:
 VECTOR_DB_DIR = "data/chroma-db-all_sources"
 VECTOR_COLLECTION_NAME = "chroma-db-all_sources"
 DOCUMENT_DICT_PATH = f"{VECTOR_DB_DIR}/document_dict_all_sources.pkl"
-DEFAULT_MODEL_NAME = "google-genai:gemini-flash-latest"
+DEFAULT_MODEL_NAME = "google-genai:gemini-3-flash-preview"
 
 AVAILABLE_SOURCES_UI = [
     "Transformers Docs",
@@ -23,7 +23,6 @@ AVAILABLE_SOURCES_UI = [
     "LlamaIndex Docs",
     "LangChain Docs",
     "OpenAI Cookbooks",
-    "Towards AI Blog",
     "8 Hour Primer",
     "Advanced LLM Developer",
     "Python Primer",
@@ -37,7 +36,6 @@ DEFAULT_SELECTED_SOURCES_UI = [
     "Advanced LLM Developer",
     "8 Hour Primer",
     "Python Primer",
-    "Towards AI Blog",
     "Transformers Docs",
     "PEFT Docs",
     "TRL Docs",
@@ -53,7 +51,6 @@ AVAILABLE_SOURCES = [
     "llama_index",
     "langchain",
     "openai_cookbooks",
-    "tai_blog",
     "8-hour_primer",
     "llm_developer",
     "python_primer",
@@ -68,7 +65,6 @@ SOURCE_UI_TO_KEY = {
     "LlamaIndex Docs": "llama_index",
     "LangChain Docs": "langchain",
     "OpenAI Cookbooks": "openai_cookbooks",
-    "Towards AI Blog": "tai_blog",
     "8 Hour Primer": "8-hour_primer",
     "Advanced LLM Developer": "llm_developer",
     "Python Primer": "python_primer",
@@ -76,6 +72,16 @@ SOURCE_UI_TO_KEY = {
     "Agentic AI Engineering": "agentic_ai_engineering",
 }
 
+COURSE_SOURCE_KEYS = frozenset(
+    {
+        "8-hour_primer",
+        "llm_developer",
+        "python_primer",
+        "master_ai_for_work",
+        "agentic_ai_engineering",
+    }
+)
+
 SOURCE_KEY_TO_LABEL = {value: key for key, value in SOURCE_UI_TO_KEY.items()}
 DEFAULT_SELECTED_SOURCE_KEYS = tuple(
     SOURCE_UI_TO_KEY[label] for label in DEFAULT_SELECTED_SOURCES_UI
@@ -110,6 +116,7 @@ mongo_db = (
 __all__ = [
     "AVAILABLE_SOURCES",
     "AVAILABLE_SOURCES_UI",
+    "COURSE_SOURCE_KEYS",
     "DEFAULT_SELECTED_SOURCE_KEYS",
     "DEFAULT_SELECTED_SOURCES_UI",
     "CONCURRENCY_COUNT",

tests/test_api.py

@@ -26,15 +26,39 @@ class ApiTestCase(unittest.TestCase):
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.json(), {"status": "ok"})
 
-    def test_list_sources(self) -> None:
+    def test_list_tools(self) -> None:
         with TestClient(app) as client:
-            response = client.get("/api/sources")
+            response = client.get("/api/tools")
 
         self.assertEqual(response.status_code, 200)
         body = response.json()
-        self.assertIn("sources", body)
-        self.assertTrue(body["sources"])
-        self.assertTrue(any(item["selectedByDefault"] for item in body["sources"]))
+        self.assertIn("tools", body)
+        tools = body["tools"]
+        retrieval = next(tool for tool in tools if tool["key"] == "retrieval")
+        self.assertEqual(retrieval["kind"], "configurable")
+        self.assertTrue(retrieval["sources"])
+        self.assertTrue(
+            any(source["selectedByDefault"] for source in retrieval["sources"])
+        )
+        self.assertTrue(
+            all(source["group"] in {"courses", "docs"} for source in retrieval["sources"])
+        )
+        # Gemini is the default model, so web search + url reading are present.
+        tool_keys = {tool["key"] for tool in tools}
+        self.assertIn("web_search", tool_keys)
+        self.assertIn("url_context", tool_keys)
+
+    def test_list_tools_for_non_gemini_model(self) -> None:
+        with TestClient(app) as client:
+            response = client.get(
+                "/api/tools", params={"model": "anthropic:claude-sonnet-4-6"}
+            )
+
+        self.assertEqual(response.status_code, 200)
+        tool_keys = {tool["key"] for tool in response.json()["tools"]}
+        self.assertIn("retrieval", tool_keys)
+        self.assertNotIn("web_search", tool_keys)
+        self.assertNotIn("url_context", tool_keys)
 
     def test_chat_stream_returns_ai_sdk_parts(self) -> None:
         async def fake_stream_chat(request):
@@ -156,6 +180,52 @@ class ApiTestCase(unittest.TestCase):
         self.assertEqual(parts[0]["type"], "error")
         self.assertEqual(parts[0]["errorText"], "backend failed")
 
+    def test_chat_stream_restarts_reasoning_after_tool_activity(self) -> None:
+        async def fake_stream_chat(_request):
+            yield ChatEvent("message_started", {"message_id": "message_1"})
+            yield ChatEvent("reasoning_delta", {"message_id": "message_1", "text": "First thought"})
+            yield ChatEvent(
+                "tool_call_started",
+                {
+                    "message_id": "message_1",
+                    "call_id": "call_1",
+                    "tool_name": "retrieve_tutor_context",
+                    "args": {"query": "What is RAG?"},
+                    "args_text": "What is RAG?",
+                },
+            )
+            yield ChatEvent(
+                "tool_call_completed",
+                {
+                    "message_id": "message_1",
+                    "call_id": "call_1",
+                    "output_text": "payload",
+                },
+            )
+            yield ChatEvent("reasoning_delta", {"message_id": "message_1", "text": "Second thought"})
+            yield ChatEvent("text_delta", {"message_id": "message_1", "text": "Final answer"})
+            yield ChatEvent(
+                "message_completed",
+                {
+                    "message_id": "message_1",
+                    "answer": "Final answer",
+                },
+            )
+
+        with patch("scripts.api.stream_chat", fake_stream_chat):
+            with TestClient(app) as client:
+                with client.stream("POST", "/api/chat", json={"query": "Hello"}) as response:
+                    body = "".join(response.iter_text())
+
+        self.assertEqual(response.status_code, 200)
+        payloads = parse_sse_payloads(body)
+        parts = [json.loads(item) for item in payloads[:-1]]
+        part_types = [part["type"] for part in parts]
+
+        self.assertEqual(part_types.count("reasoning-start"), 2)
+        self.assertEqual(part_types.count("reasoning-end"), 2)
+        self.assertLess(part_types.index("tool-input-start"), part_types.index("text-start"))
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_chat_service.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import types
+import unittest
+from unittest.mock import patch
+
+from langchain_core.messages import AIMessage, HumanMessage
+
+from scripts.chat_service import sync_thread_with_history
+from scripts.chat_types import ChatTurn
+
+
+class FakeAgent:
+    def __init__(self, messages):
+        self._messages = list(messages)
+        self.updated_states: list[tuple[dict[str, object], dict[str, object]]] = []
+
+    def get_state(self, _config):
+        return types.SimpleNamespace(values={"messages": list(self._messages)})
+
+    def update_state(self, config, payload):
+        self.updated_states.append((config, payload))
+
+
+class ChatServiceTestCase(unittest.TestCase):
+    def test_shorter_history_branches_to_fresh_thread(self) -> None:
+        agent = FakeAgent(
+            [
+                HumanMessage(content="How do I create an agent?"),
+                AIMessage(content="Use a model and tools."),
+            ]
+        )
+
+        with patch("scripts.chat_service.new_thread_id", return_value="thread_regen"):
+            active_thread_id = sync_thread_with_history(agent, "thread_0", ())
+
+        self.assertEqual(active_thread_id, "thread_regen")
+        self.assertEqual(agent.updated_states, [])
+
+    def test_edited_history_restores_messages_into_branched_thread(self) -> None:
+        agent = FakeAgent(
+            [
+                HumanMessage(content="How do I create an agent?"),
+                AIMessage(content="Use a model and tools."),
+            ]
+        )
+        edited_history = (
+            ChatTurn(role="user", content="How do I create a RAG agent?"),
+            ChatTurn(role="assistant", content="Use retrieval and a model."),
+        )
+
+        with patch("scripts.chat_service.new_thread_id", return_value="thread_edit"):
+            active_thread_id = sync_thread_with_history(
+                agent,
+                "thread_0",
+                edited_history,
+            )
+
+        self.assertEqual(active_thread_id, "thread_edit")
+        self.assertEqual(len(agent.updated_states), 1)
+        config, payload = agent.updated_states[0]
+        self.assertEqual(config, {"configurable": {"thread_id": "thread_edit"}})
+        restored_messages = payload["messages"]
+        self.assertEqual(len(restored_messages), 2)
+        self.assertEqual(restored_messages[0].content, "How do I create a RAG agent?")
+        self.assertEqual(restored_messages[1].content, "Use retrieval and a model.")
+
+
+if __name__ == "__main__":
+    unittest.main()