Add Docker support with .dockerignore and Dockerfile updates. Integrate Next.js frontend build process, including package.json and related configurations. Enhance API to serve static frontend files and update README for project clarity. Add course and document metadata structures for improved content management.

.dockerignore

@@ -0,0 +1,41 @@
+# Version control
+.git
+.github
+
+# Python build artifacts
+__pycache__
+*.pyc
+.venv
+venv
+.pytest_cache
+.mypy_cache
+
+# Node build artifacts
+frontend/node_modules
+frontend/.next
+frontend/out
+
+# Local env files (secrets / per-developer config)
+.env
+.env.local
+.env.*.local
+frontend/.env
+frontend/.env.local
+frontend/.env.*.local
+
+# Editor/OS
+.vscode
+.idea
+.DS_Store
+
+# Docs and tests (optional – shrink build context)
+docs
+tests
+*.md
+!README.md
+
+# Heavy data that will be downloaded at runtime from HF Hub
+data/chroma-db-all_sources
+data/*.jsonl
+data/*.pkl
+data/*_md_files

.github/workflows/sync-to-hf.yml

@@ -24,4 +24,4 @@ jobs:
         env:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
           HF_USERNAME: ${{ secrets.HF_USERNAME }}
-        run: git push --force https://$HF_USERNAME:$HF_TOKEN@huggingface.co/spaces/towardsai-tutors/ai-tutor-chatbot main:main
+        run: git push --force https://$HF_USERNAME:$HF_TOKEN@huggingface.co/spaces/towardsai-tutors/ai-tutor main:main

.gitignore

@@ -14,8 +14,8 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
+/lib/
+/lib64/
 parts/
 sdist/
 var/
@@ -182,3 +182,12 @@ frontend/out/
 *.pkl
 *.png
 *.mov
+
+# Keep assets + configs needed for deployment
+!frontend/package.json
+!frontend/package-lock.json
+!frontend/tsconfig.json
+!frontend/public/towardsai-logo.png
+!frontend/app/icon.png
+!frontend/app/apple-icon.png
+!data/source_versions.json

Dockerfile

@@ -1,7 +1,23 @@
+# syntax=docker/dockerfile:1.6
+
+# Stage 1: build the Next.js frontend as a static export
+FROM node:20-alpine AS frontend
+WORKDIR /frontend
+
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+
+COPY frontend/ ./
+
+# Empty base URL => API calls are same-origin (served by FastAPI)
+ENV NEXT_PUBLIC_AI_TUTOR_API_BASE_URL=""
+RUN npm run build
+
+
+# Stage 2: Python runtime + FastAPI + bundled static frontend
 FROM python:3.13
 
 RUN curl -LsSf https://astral.sh/uv/install.sh | sh
-
 ENV PATH="/root/.local/bin:${PATH}"
 
 RUN useradd -m -u 1000 user
@@ -11,11 +27,13 @@ COPY pyproject.toml uv.lock ./
 RUN uv sync --locked
 
 COPY . .
+COPY --from=frontend /frontend/out ./frontend/out
 
-
-ENV HOME=/home/user PATH="/root/.local/bin:/home/user/.local/bin:${PATH}"
+ENV HOME=/home/user \
+    PATH="/root/.local/bin:/home/user/.local/bin:${PATH}" \
+    PORT=7860
 RUN chown -R user:user /app
 USER user
 
 EXPOSE 7860
-CMD ["uv", "run", "-m", "scripts.main"]
+CMD ["sh", "-c", "uv run uvicorn scripts.api:app --host 0.0.0.0 --port ${PORT:-7860}"]

README.md

@@ -1,8 +1,8 @@
 ---
-title: AI Tutor Chatbot
-emoji: 🧑🏻‍🏫
-colorFrom: gray
-colorTo: pink
+title: AI Tutor
+emoji: 🎓
+colorFrom: blue
+colorTo: indigo
 sdk: docker
 app_port: 7860
 pinned: false

data/source_versions.json

@@ -0,0 +1,32 @@
+{
+  "langchain": {
+    "indexedAt": "2026-04-17",
+    "sha": "b921b07",
+    "version": "langchain-core==1.3.0"
+  },
+  "llama_index": {
+    "indexedAt": "2026-04-17",
+    "sha": "33f7ba4",
+    "version": "v0.14.20"
+  },
+  "openai_cookbooks": {
+    "indexedAt": "2026-04-17",
+    "sha": "9e0a00d",
+    "version": null
+  },
+  "peft": {
+    "indexedAt": "2026-04-17",
+    "sha": "2859358",
+    "version": "v0.19.1"
+  },
+  "transformers": {
+    "indexedAt": "2026-04-17",
+    "sha": "a29df2d",
+    "version": "v5.5.4"
+  },
+  "trl": {
+    "indexedAt": "2026-04-17",
+    "sha": "573ea22",
+    "version": "v1.2.0"
+  }
+}

frontend/lib/api.ts

@@ -0,0 +1,74 @@
+export type TutorSource = {
+  key: string;
+  label: string;
+  group: "courses" | "docs";
+  selectedByDefault: boolean;
+  version?: string | null;
+  indexedAt?: string | null;
+};
+
+export type TutorConfigurableTool = {
+  kind: "configurable";
+  key: "retrieval";
+  label: string;
+  active: boolean;
+  sources: TutorSource[];
+};
+
+export type TutorToggleTool = {
+  kind: "toggle";
+  key: string;
+  label: string;
+  active: boolean;
+};
+
+export type TutorTool = TutorConfigurableTool | TutorToggleTool;
+
+export type AvailableModel = {
+  id: string;
+  label: string;
+};
+
+export type ToolsResponse = {
+  model: string;
+  availableModels: AvailableModel[];
+  tools: TutorTool[];
+};
+
+export type SourcePartData = {
+  docId: string;
+  title: string;
+  url: string;
+  sourceKey: string;
+  sourceLabel: string;
+  score: number;
+};
+
+const FALLBACK_API_BASE_URL = "http://127.0.0.1:8000";
+
+export function getApiBaseUrl() {
+  return (
+    process.env.NEXT_PUBLIC_AI_TUTOR_API_BASE_URL?.replace(/\/+$/, "") ??
+    FALLBACK_API_BASE_URL
+  );
+}
+
+export async function fetchTools(
+  signal?: AbortSignal,
+  model?: string,
+): Promise<ToolsResponse> {
+  const url = new URL(`${getApiBaseUrl()}/api/tools`);
+  if (model) {
+    url.searchParams.set("model", model);
+  }
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    signal,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Unable to load tools (${response.status})`);
+  }
+
+  return (await response.json()) as ToolsResponse;
+}

frontend/lib/chat-ui.ts

@@ -0,0 +1,304 @@
+import type { UIMessage } from "ai";
+import type { SourcePartData } from "./api";
+
+export type TutorMessage = UIMessage;
+
+export type TutorMessagePart = {
+  type: string;
+  text?: string;
+  state?: string;
+  data?: unknown;
+  toolCallId?: string;
+  input?: unknown;
+  output?: unknown;
+  errorText?: string;
+  sourceId?: string;
+  url?: string;
+  title?: string;
+  mediaType?: string;
+};
+
+export type TutorMessageBlock = {
+  key: string;
+  kind: "text" | "reasoning" | "tool";
+  parts: TutorMessagePart[];
+};
+
+export type CitationKind = "web" | "course" | "doc";
+
+export type MessageCitation = {
+  label: string;
+  url: string;
+  kind: CitationKind;
+  sublabel?: string;
+};
+
+export function getTextParts(message: TutorMessage) {
+  return message.parts
+    .filter((part) => "type" in part && part.type === "text")
+    .map((part) => part as TutorMessagePart);
+}
+
+export function getMessageTextContent(message: TutorMessage) {
+  return getTextParts(message)
+    .map((part) => (part.text ?? "").trim())
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function getReasoningParts(message: TutorMessage) {
+  return message.parts
+    .filter((part) => "type" in part && part.type === "reasoning")
+    .map((part) => part as TutorMessagePart);
+}
+
+export function getToolParts(message: TutorMessage) {
+  return message.parts
+    .filter((part) => "type" in part && String(part.type).startsWith("tool-"))
+    .map((part) => part as TutorMessagePart);
+}
+
+export function getOrderedMessageBlocks(message: TutorMessage): TutorMessageBlock[] {
+  const blocks: TutorMessageBlock[] = [];
+  let currentKind: TutorMessageBlock["kind"] | null = null;
+  let currentParts: TutorMessagePart[] = [];
+
+  for (const part of message.parts) {
+    if (!("type" in part)) {
+      continue;
+    }
+
+    const typedPart = part as TutorMessagePart;
+    const nextKind = classifyMessagePart(typedPart);
+
+    if (!nextKind) {
+      continue;
+    }
+
+    if (currentKind && currentKind !== nextKind) {
+      blocks.push({
+        key: `${message.id}-${currentKind}-${blocks.length}`,
+        kind: currentKind,
+        parts: currentParts,
+      });
+      currentParts = [];
+    }
+
+    currentKind = nextKind;
+    currentParts.push(typedPart);
+  }
+
+  if (currentKind && currentParts.length > 0) {
+    blocks.push({
+      key: `${message.id}-${currentKind}-${blocks.length}`,
+      kind: currentKind,
+      parts: currentParts,
+    });
+  }
+
+  return blocks;
+}
+
+export function getMessageSources(message: TutorMessage): SourcePartData[] {
+  const seen = new Set<string>();
+  const sources: SourcePartData[] = [];
+
+  for (const part of message.parts) {
+    if (!("type" in part) || part.type !== "data-source") {
+      continue;
+    }
+    const data = (part as TutorMessagePart).data as SourcePartData | undefined;
+    if (!data) {
+      continue;
+    }
+    const key = data.docId || data.url;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    sources.push(data);
+  }
+
+  return sources.sort((left, right) => right.score - left.score);
+}
+
+export function hasRenderableContent(message: TutorMessage): boolean {
+  for (const part of message.parts) {
+    if (!("type" in part)) {
+      continue;
+    }
+    const type = String(part.type);
+    if (type === "text" || type === "reasoning" || type.startsWith("tool-")) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function getLastAssistantMessage(messages: TutorMessage[]) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === "assistant") {
+      return messages[index];
+    }
+  }
+
+  return undefined;
+}
+
+const WEB_SOURCE_KEYS = new Set(["google_search", "url_context"]);
+const COURSE_SOURCE_KEYS = new Set([
+  "8-hour_primer",
+  "llm_developer",
+  "python_primer",
+  "master_ai_for_work",
+  "agentic_ai_engineering",
+]);
+
+function classifySource(sourceKey: string): CitationKind {
+  if (WEB_SOURCE_KEYS.has(sourceKey)) {
+    return "web";
+  }
+  if (COURSE_SOURCE_KEYS.has(sourceKey)) {
+    return "course";
+  }
+  return "doc";
+}
+
+export function getMessageCitations(message: TutorMessage): MessageCitation[] {
+  const seen = new Set<string>();
+  const citations: MessageCitation[] = [];
+
+  for (const source of getMessageSources(message)) {
+    const url = source.url?.trim();
+    if (!url) {
+      continue;
+    }
+    const kind = classifySource(source.sourceKey);
+    const title = cleanTitle(source.title);
+    const label = (
+      kind === "web"
+        ? title || hostnameFromUrl(url) || "Source"
+        : title || source.sourceLabel || "Source"
+    ).slice(0, 80);
+    const sublabel =
+      kind === "web"
+        ? hostnameFromUrl(url)
+        : source.sourceLabel?.trim() || undefined;
+    const key = `${kind}::${url}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    citations.push({ label, url, kind, sublabel });
+  }
+
+  for (const part of getTextParts(message)) {
+    const text = part.text ?? "";
+    for (const citation of extractMarkdownLinkCitations(text)) {
+      const key = `web::${citation.url}`;
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      citations.push({
+        label: citation.label,
+        url: citation.url,
+        kind: "web",
+        sublabel: hostnameFromUrl(citation.url) || undefined,
+      });
+    }
+  }
+
+  return citations;
+}
+
+function cleanTitle(raw: string | undefined) {
+  const trimmed = raw?.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (/^[-–—\s]+$/.test(trimmed)) {
+    return "";
+  }
+  return trimmed;
+}
+
+function hostnameFromUrl(url: string) {
+  try {
+    return new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return "";
+  }
+}
+
+export function prettifyToolName(type: string) {
+  return type
+    .replace(/^tool-/, "")
+    .replaceAll("_", " ")
+    .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+
+export function toolInputSummary(input: unknown) {
+  if (!input || typeof input !== "object") {
+    return "";
+  }
+
+  const query = "query" in input ? String(input.query ?? "").trim() : "";
+  if (query) {
+    return query;
+  }
+
+  const text = "text" in input ? String(input.text ?? "").trim() : "";
+  if (text) {
+    return text;
+  }
+
+  return JSON.stringify(input);
+}
+
+function classifyMessagePart(
+  part: TutorMessagePart,
+): TutorMessageBlock["kind"] | null {
+  if (part.type === "text") {
+    return "text";
+  }
+
+  if (part.type === "reasoning") {
+    return "reasoning";
+  }
+
+  if (String(part.type).startsWith("tool-")) {
+    return "tool";
+  }
+
+  return null;
+}
+
+type RawLinkCitation = { label: string; url: string };
+
+function extractMarkdownLinkCitations(text: string): RawLinkCitation[] {
+  const citations: RawLinkCitation[] = [];
+  const markdownLinkPattern = /\[([^\]]+)\]\((https?:\/\/[^\s)]+(?:\([^\s)]+\)[^\s)]*)*)\)/g;
+  const bareUrlPattern = /(?<!\()https?:\/\/[^\s<>()]+/g;
+  const urlsInMarkdown = new Set<string>();
+
+  for (const match of text.matchAll(markdownLinkPattern)) {
+    const label = (match[1] ?? "").trim();
+    const url = (match[2] ?? "").trim();
+    if (!label || !url) {
+      continue;
+    }
+    urlsInMarkdown.add(url);
+    citations.push({ label, url });
+  }
+
+  for (const match of text.matchAll(bareUrlPattern)) {
+    const url = (match[0] ?? "").trim();
+    if (!url || urlsInMarkdown.has(url)) {
+      continue;
+    }
+    citations.push({ label: "Source", url });
+  }
+
+  return citations;
+}

frontend/lib/course-metadata.ts

@@ -0,0 +1,34 @@
+export type CourseMetadata = {
+  description: string;
+  academyUrl: string;
+};
+
+export const COURSE_METADATA: Record<string, CourseMetadata> = {
+  "8-hour_primer": {
+    description:
+      "Crash course on LLM fundamentals: prompting, APIs, and shipping simple production apps. Good starting point for beginners deciding if LLM dev is for them.",
+    academyUrl: "https://academy.towardsai.net/courses/8-hour-genai-primer",
+  },
+  full_stack_ai_engineering: {
+    description:
+      "Full-stack LLM engineering, covering RAG, fine-tuning, evaluation, and deploying production systems end-to-end. The deepest technical course.",
+    academyUrl:
+      "https://academy.towardsai.net/courses/beginner-to-advanced-llm-dev",
+  },
+  beginner_python_for_ai_engineering: {
+    description:
+      "Python for the LLM era: API integration, using open-source models, and core training/testing workflows. Assumes no prior Python.",
+    academyUrl: "https://academy.towardsai.net/courses/python-for-genai",
+  },
+  master_ai_for_work: {
+    description:
+      "Non-engineer course on using AI tools (ChatGPT, Claude, etc.) for workplace productivity and rolling them out across a team.",
+    academyUrl:
+      "https://academy.towardsai.net/courses/ai-business-professionals",
+  },
+  agentic_ai_engineering: {
+    description:
+      "Designing, building, evaluating, and deploying production-grade AI agents end-to-end.",
+    academyUrl: "https://academy.towardsai.net/courses/agent-engineering",
+  },
+};

frontend/lib/doc-metadata.ts

@@ -0,0 +1,37 @@
+export type DocMetadata = {
+  description: string;
+  docsUrl: string;
+};
+
+export const DOC_METADATA: Record<string, DocMetadata> = {
+  transformers: {
+    description:
+      "Hugging Face library for state-of-the-art NLP and multimodal models. Load, run, and train pretrained transformers.",
+    docsUrl: "https://huggingface.co/docs/transformers",
+  },
+  peft: {
+    description:
+      "Parameter-Efficient Fine-Tuning: LoRA, prefix tuning, and other methods for adapting large models with minimal compute.",
+    docsUrl: "https://huggingface.co/docs/peft",
+  },
+  trl: {
+    description:
+      "Train language models with reinforcement learning. Covers SFT, DPO, PPO, and other alignment techniques.",
+    docsUrl: "https://huggingface.co/docs/trl",
+  },
+  llama_index: {
+    description:
+      "Framework for building RAG apps: ingestion, indexing, retrievers, and query engines over your own data.",
+    docsUrl: "https://docs.llamaindex.ai",
+  },
+  langchain: {
+    description:
+      "Framework for building LLM apps: chains, agents, tool-calling, and production observability.",
+    docsUrl: "https://docs.langchain.com/oss/python/langchain/overview",
+  },
+  openai_cookbooks: {
+    description:
+      "Example notebooks and recipes from OpenAI covering practical patterns for using their APIs.",
+    docsUrl: "https://cookbook.openai.com",
+  },
+};

frontend/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/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

@@ -6,6 +6,9 @@ const __dirname = dirname(__filename);
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
+  output: "export",
+  images: { unoptimized: true },
+  trailingSlash: true,
   turbopack: {
     root: __dirname,
   },

frontend/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ai-tutor-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "npm@11.12.1",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@ai-sdk/react": "^3.0.164",
+    "ai": "^6.0.162",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.511.0",
+    "next": "^16.2.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@tailwindcss/postcss": "^4.1.17",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "eslint": "^9.39.1",
+    "eslint-config-next": "^16.2.3",
+    "tailwindcss": "^4.2.2",
+    "typescript": "^5.9.3"
+  }
+}

frontend/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

scripts/api.py

@@ -12,6 +12,7 @@ import uvicorn
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
+from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel, Field
 
 from .chat_service import (
@@ -462,6 +463,21 @@ async def chat(payload: ApiChatRequest) -> StreamingResponse:
     )
 
 
+FRONTEND_OUT_DIR = Path(__file__).resolve().parent.parent / "frontend" / "out"
+
+if FRONTEND_OUT_DIR.is_dir():
+    app.mount(
+        "/",
+        StaticFiles(directory=str(FRONTEND_OUT_DIR), html=True),
+        name="frontend",
+    )
+else:
+    logfire.info(
+        "Frontend static export not found; skipping static mount.",
+        path=str(FRONTEND_OUT_DIR),
+    )
+
+
 if __name__ == "__main__":
     uvicorn.run(
         "scripts.api:app",