feat: completed initial dev

.dockerignore

@@ -0,0 +1,12 @@
+**/node_modules
+**/.next
+**/.venv
+**/__pycache__
+**/.lancedb
+**/.tmp_uploads
+**/.cache
+.git
+.env
+.env.local
+*.md
+!README.md

.env.example

@@ -0,0 +1,24 @@
+# ---- Hugging Face ----
+# A read+write token from https://huggingface.co/settings/tokens
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# The dataset repo that acts as your persistent "cloud drive" for PDFs.
+# Format: "username/dataset-name" — must already exist (create as a private dataset).
+DATASET_ID=your-username/iam-earth-dev-corpus
+
+# ---- LLM / Embeddings (Hugging Face Serverless Inference) ----
+# Any chat-completions-capable model on the HF Inference API.
+LLM_MODEL=Qwen/Qwen2.5-7B-Instruct
+EMBED_MODEL=BAAI/bge-small-en-v1.5
+
+# Leave reasoning hidden in the student UI. Set true only when debugging models
+# that expose a separate thinking/reasoning stream.
+SHOW_LLM_REASONING=false
+
+# ---- Admin auth ----
+# Educators set this as a Space secret; the admin dashboard requires it.
+ADMIN_PASSCODE=password
+
+# ---- Internal (defaults are fine for local dev; Docker sets these via Dockerfile ENV) ----
+BACKEND_PORT=8000
+FRONTEND_PORT=7860

.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+backend/.venv/
+.uv/
+
+# Node
+node_modules/
+frontend/.next/
+frontend/out/
+.next/
+
+# Runtime data (must NOT be committed — these are ephemeral on HF Spaces)
+.lancedb/
+.tmp_uploads/
+.cache/
+
+# Env
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,61 @@
+# syntax=docker/dockerfile:1.7
+# ---------- Stage 1: Build the Next.js frontend ----------
+FROM node:20-bookworm-slim AS frontend-build
+
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm install --no-audit --no-fund
+
+COPY frontend/ ./
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+# ---------- Stage 2: Runtime (Python 3.13 + Node 20) ----------
+FROM python:3.13-slim-bookworm AS runtime
+
+# Install Node 20 (needed to run `next start`) and minimal system libs
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl ca-certificates gnupg build-essential \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Install uv (fast Python package manager)
+RUN pip install --no-cache-dir uv
+
+# HF Spaces requires the working dir to be writable by an arbitrary uid.
+# We create /app and chmod it 777 so cache + lancedb dirs work at runtime.
+WORKDIR /app
+
+# ---- Backend ----
+COPY backend/pyproject.toml backend/uv.lock* ./backend/
+RUN cd backend && uv sync --no-dev --frozen 2>/dev/null || (cd backend && uv sync --no-dev)
+
+COPY backend/ ./backend/
+
+# ---- Frontend (built artifacts only) ----
+COPY --from=frontend-build /app/frontend/.next ./frontend/.next
+COPY --from=frontend-build /app/frontend/public ./frontend/public
+COPY --from=frontend-build /app/frontend/package.json ./frontend/package.json
+COPY --from=frontend-build /app/frontend/next.config.js ./frontend/next.config.js
+COPY --from=frontend-build /app/frontend/node_modules ./frontend/node_modules
+
+# ---- Entry script ----
+COPY start.sh /app/start.sh
+RUN chmod +x /app/start.sh
+
+# Cache + data dirs (HF Spaces runs as random uid; make them world-writable)
+RUN mkdir -p /app/.cache /app/.lancedb /app/.tmp_uploads \
+    && chmod -R 777 /app
+
+ENV HF_HOME=/app/.cache \
+    LANCEDB_PATH=/app/.lancedb \
+    TMP_UPLOAD_DIR=/app/.tmp_uploads \
+    BACKEND_PORT=8000 \
+    FRONTEND_PORT=7860 \
+    NEXT_TELEMETRY_DISABLED=1 \
+    PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+
+CMD ["/app/start.sh"]

README.md

@@ -4,7 +4,71 @@ emoji: 🌖
 colorFrom: purple
 colorTo: green
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Quick start (clone for your own course)
+
+1. **Duplicate this Space** on Hugging Face.
+2. **Create a private Dataset** on HF (e.g. `your-username/my-course-corpus`) — leave it empty.
+3. In your Space → **Settings → Variables and secrets**, add:
+   - `HF_TOKEN` — a token with **write** access to the dataset above.
+   - `DATASET_ID` — `your-username/my-course-corpus`
+   - `ADMIN_PASSCODE` — any string; this protects `/admin`.
+   - *(optional)* `LLM_MODEL` — defaults to `Qwen/Qwen2.5-7B-Instruct`.
+   - *(optional)* `EMBED_MODEL` — defaults to `BAAI/bge-small-en-v1.5`.
+4. Restart the Space. Open `/admin`, sign in with the passcode, drag in PDFs.
+5. Share the root URL with your students — they land on the chat UI.
+
+## Local development
+
+Requires Python 3.13, Node 20+, and [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+cp .env.example .env   # fill in HF_TOKEN, DATASET_ID, ADMIN_PASSCODE
+
+# Backend
+cd backend && uv sync && uv run uvicorn main:app --port 8000 --reload
+
+# Frontend (in another shell)
+cd frontend && npm install && npm run dev
+```
+
+Visit <http://localhost:7860>. Next.js proxies `/api/*` to `127.0.0.1:8000`.
+
+### Or with Docker (matches the HF Space environment exactly)
+
+```bash
+docker build -t iamearthdev .
+docker run --rm -p 7860:7860 --env-file .env iamearthdev
+```
+
+## Customizing personas
+
+Edit [`frontend/lib/personas.ts`](frontend/lib/personas.ts) — each persona is just an
+`id`, `name`, `description`, and a `prompt` that gets prepended to the system message.
+Rebuild the Space to deploy.
+
+## Repo layout
+
+```
+/
+├── Dockerfile          # multi-stage: Next build → Python+Node runtime
+├── start.sh            # launches FastAPI (:8000) and Next.js (:7860)
+├── .env.example
+├── backend/
+│   ├── pyproject.toml  # uv-managed deps
+│   ├── main.py         # FastAPI app, /chat streams NDJSON
+│   ├── rag.py          # PyMuPDF4LLM → LlamaIndex → LanceDB
+│   ├── hf_sync.py      # Dataset upload/download/list/delete
+│   └── auth.py         # passcode cookie middleware
+└── frontend/
+    ├── next.config.js  # /api/* → http://127.0.0.1:8000/*
+    ├── package.json
+    ├── app/
+    │   ├── page.tsx           # chat UI
+    │   ├── admin/page.tsx     # upload + file list
+    │   └── admin/login/page.tsx
+    └── components/            # chat-interface, persona-selector, file-uploader, …
+```

backend/auth.py

@@ -0,0 +1,51 @@
+"""Trivial passcode auth for the educator dashboard.
+
+The frontend stores the passcode in an httpOnly cookie set by /api/admin/login.
+Protected endpoints depend on `require_admin` to validate the cookie.
+"""
+from __future__ import annotations
+
+import os
+import secrets
+
+from fastapi import Cookie, HTTPException, status
+
+ADMIN_PASSCODE = os.environ.get("ADMIN_PASSCODE", "")
+COOKIE_NAME = "admin_session"
+
+
+def _expected_token() -> str:
+    """A deterministic-but-opaque token derived from the passcode.
+
+    Avoids storing the raw passcode in the cookie. We don't need full session
+    management here — the passcode itself is the credential.
+    """
+    if not ADMIN_PASSCODE:
+        return ""
+    # 32-char hex digest is plenty for a single-tenant educator template.
+    import hashlib
+
+    return hashlib.sha256(ADMIN_PASSCODE.encode("utf-8")).hexdigest()
+
+
+def verify_passcode(passcode: str) -> bool:
+    if not ADMIN_PASSCODE:
+        return False
+    return secrets.compare_digest(passcode, ADMIN_PASSCODE)
+
+
+def issue_token() -> str:
+    return _expected_token()
+
+
+def require_admin(admin_session: str | None = Cookie(default=None)) -> None:
+    if not ADMIN_PASSCODE:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="ADMIN_PASSCODE is not configured on the server.",
+        )
+    if not admin_session or not secrets.compare_digest(admin_session, _expected_token()):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Admin authentication required.",
+        )

backend/hf_embedding.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from huggingface_hub import InferenceClient
+from huggingface_hub.errors import HfHubHTTPError, InferenceTimeoutError
+from llama_index.core.base.embeddings.base import BaseEmbedding, Embedding
+from llama_index.core.bridge.pydantic import Field, PrivateAttr
+from llama_index.embeddings.huggingface_api.pooling import Pooling
+from llama_index.utils.huggingface import format_query, format_text
+
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MAX_CHARS = int(os.environ.get("HF_EMBED_MAX_CHARS", "3000"))
+DEFAULT_MIN_CHARS = int(os.environ.get("HF_EMBED_MIN_CHARS", "750"))
+DEFAULT_MAX_RETRIES = int(os.environ.get("HF_EMBED_RETRIES", "3"))
+DEFAULT_BACKOFF_SECONDS = float(os.environ.get("HF_EMBED_RETRY_BACKOFF", "1.0"))
+
+
+class SyncHuggingFaceInferenceEmbedding(BaseEmbedding):
+    """Sync-only embedding adapter for HF Inference API.
+
+    The upstream LlamaIndex HF wrapper uses AsyncInferenceClient internally even
+    for sync calls, which is brittle under uvicorn/asyncio. This adapter uses
+    only the regular InferenceClient, so indexing and retrieval can run safely
+    inside a worker thread.
+    """
+
+    pooling: Optional[Pooling] = Field(default=Pooling.CLS)
+    query_instruction: Optional[str] = Field(default=None)
+    text_instruction: Optional[str] = Field(default=None)
+    model_name: str = Field(default="BAAI/bge-small-en-v1.5")
+    token: Union[str, bool, None] = Field(default=None)
+    timeout: Optional[float] = Field(default=None)
+    headers: Optional[Dict[str, str]] = Field(default=None)
+    cookies: Optional[Dict[str, str]] = Field(default=None)
+    max_chars_per_request: int = Field(default=DEFAULT_MAX_CHARS, gt=0)
+    min_chars_per_request: int = Field(default=DEFAULT_MIN_CHARS, gt=0)
+    max_retries: int = Field(default=DEFAULT_MAX_RETRIES, ge=1)
+    retry_backoff_seconds: float = Field(default=DEFAULT_BACKOFF_SECONDS, ge=0.0)
+
+    _client: InferenceClient = PrivateAttr()
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = InferenceClient(
+            model=self.model_name,
+            token=self.token,
+            timeout=self.timeout,
+            headers=self.headers,
+            cookies=self.cookies,
+        )
+
+    @classmethod
+    def class_name(cls) -> str:
+        return "SyncHuggingFaceInferenceEmbedding"
+
+    @staticmethod
+    def _mean_pool_vectors(vectors: List[Embedding]) -> Embedding:
+        if not vectors:
+            raise ValueError("Cannot average an empty list of embeddings.")
+        if len(vectors) == 1:
+            return vectors[0]
+        return [sum(values) / len(values) for values in zip(*vectors)]
+
+    @staticmethod
+    def _split_text(text: str, max_chars: int) -> List[str]:
+        stripped = text.strip()
+        if len(stripped) <= max_chars:
+            return [stripped] if stripped else [" "]
+
+        paragraphs = [part.strip() for part in stripped.split("\n\n") if part.strip()]
+        if not paragraphs:
+            paragraphs = [stripped]
+
+        segments: List[str] = []
+        current = ""
+
+        for paragraph in paragraphs:
+            pieces = [paragraph[i : i + max_chars] for i in range(0, len(paragraph), max_chars)]
+            for piece in pieces:
+                candidate = piece if not current else f"{current}\n\n{piece}"
+                if len(candidate) <= max_chars:
+                    current = candidate
+                else:
+                    if current:
+                        segments.append(current)
+                    current = piece
+
+        if current:
+            segments.append(current)
+
+        return segments or [" "]
+
+    def _embed_request(self, text: str) -> Embedding:
+        embedding = self._client.feature_extraction(
+            text,
+            truncate=True,
+            truncation_direction="right",
+        )
+        if len(embedding.shape) == 1:
+            return embedding.tolist()
+
+        embedding = embedding.squeeze(axis=0)
+        if len(embedding.shape) == 1:
+            return embedding.tolist()
+
+        if self.pooling is None:
+            raise ValueError(
+                f"Pooling is required for {self.model_name} because it returned "
+                "a > 1-D value."
+            )
+
+        return self.pooling(embedding).tolist()
+
+    def _embed_with_retry(self, text: str) -> Embedding:
+        last_error: Exception | None = None
+
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                return self._embed_request(text)
+            except (HfHubHTTPError, InferenceTimeoutError) as exc:
+                last_error = exc
+                status_code = getattr(getattr(exc, "response", None), "status_code", None)
+                retryable = isinstance(exc, InferenceTimeoutError) or status_code in (429, 500, 502, 503, 504)
+                if not retryable or attempt == self.max_retries:
+                    break
+                delay = self.retry_backoff_seconds * (2 ** (attempt - 1))
+                logger.warning(
+                    "HF embedding request failed for %s (status=%s, attempt %d/%d). Retrying in %.1fs.",
+                    self.model_name,
+                    status_code,
+                    attempt,
+                    self.max_retries,
+                    delay,
+                )
+                time.sleep(delay)
+
+        if last_error is not None:
+            raise last_error
+        raise RuntimeError("Embedding request failed without an exception.")
+
+    def _embed_single(self, text: str, *, max_chars: Optional[int] = None) -> Embedding:
+        stripped = text.strip() or " "
+        current_max_chars = max_chars or self.max_chars_per_request
+        segments = self._split_text(stripped, current_max_chars)
+
+        if len(segments) > 1:
+            embeddings = [self._embed_single(segment, max_chars=current_max_chars) for segment in segments]
+            return self._mean_pool_vectors(embeddings)
+
+        try:
+            return self._embed_with_retry(segments[0])
+        except (HfHubHTTPError, InferenceTimeoutError) as exc:
+            if current_max_chars <= self.min_chars_per_request or len(stripped) <= self.min_chars_per_request:
+                raise exc
+
+            smaller_max_chars = max(self.min_chars_per_request, current_max_chars // 2)
+            if smaller_max_chars >= current_max_chars:
+                raise exc
+
+            logger.warning(
+                "HF embedding request for %s failed after retries. Falling back to smaller text segments (%d -> %d chars).",
+                self.model_name,
+                current_max_chars,
+                smaller_max_chars,
+            )
+            return self._embed_single(stripped, max_chars=smaller_max_chars)
+
+    def _get_query_embedding(self, query: str) -> Embedding:
+        return self._embed_single(
+            format_query(query, self.model_name, self.query_instruction)
+        )
+
+    async def _aget_query_embedding(self, query: str) -> Embedding:
+        return self._get_query_embedding(query)
+
+    def _get_text_embedding(self, text: str) -> Embedding:
+        return self._embed_single(
+            format_text(text, self.model_name, self.text_instruction)
+        )
+
+    async def _aget_text_embedding(self, text: str) -> Embedding:
+        return self._get_text_embedding(text)

backend/hf_sync.py

@@ -0,0 +1,261 @@
+"""Hugging Face Dataset acts as the persistent 'cloud drive' for uploaded PDFs.
+
+Layout inside the dataset repo:
+    pdfs/<filename>.pdf          <- raw PDFs (source of truth)
+    vector_cache/manifest.json   <- vector cache metadata
+    vector_cache/index/**        <- persisted LanceDB files
+
+Local disk on HF Spaces is ephemeral, so we try to restore the vector cache
+from the dataset first and only rebuild from PDFs when the cache is missing or
+stale.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+import shutil
+from tempfile import TemporaryDirectory
+from typing import List
+
+from huggingface_hub import HfApi, hf_hub_download
+from huggingface_hub.utils import EntryNotFoundError, RepositoryNotFoundError
+
+logger = logging.getLogger(__name__)
+
+HF_TOKEN = os.environ.get("HF_TOKEN")
+DATASET_ID = os.environ.get("DATASET_ID")
+PDF_PREFIX = "pdfs/"
+VECTOR_PREFIX = "vector_cache/"
+VECTOR_INDEX_PREFIX = f"{VECTOR_PREFIX}index/"
+VECTOR_MANIFEST_PATH = f"{VECTOR_PREFIX}manifest.json"
+VECTOR_CACHE_SCHEMA_VERSION = 1
+
+
+def is_configured() -> bool:
+    return bool(HF_TOKEN and DATASET_ID)
+
+
+def _vector_manifest(pdf_filenames: List[str], embed_model: str) -> dict:
+    return {
+        "schema_version": VECTOR_CACHE_SCHEMA_VERSION,
+        "embed_model": embed_model,
+        "pdf_files": sorted(pdf_filenames),
+    }
+
+
+def _api() -> HfApi:
+    if not HF_TOKEN or not DATASET_ID:
+        raise RuntimeError(
+            "HF_TOKEN and DATASET_ID must be set as environment variables / Space secrets."
+        )
+    return HfApi(token=HF_TOKEN)
+
+
+def _ensure_dataset_exists(api: HfApi) -> None:
+    try:
+        api.repo_info(repo_id=DATASET_ID, repo_type="dataset")
+    except RepositoryNotFoundError:
+        try:
+            api.create_repo(
+                repo_id=DATASET_ID,
+                repo_type="dataset",
+                private=True,
+                exist_ok=True,
+            )
+            logger.info("Created dataset repo %s", DATASET_ID)
+        except Exception as exc:  # noqa: BLE001
+            raise RuntimeError(
+                f"Dataset {DATASET_ID!r} does not exist and could not be created automatically. "
+                "Create it on Hugging Face or update DATASET_ID / HF_TOKEN permissions."
+            ) from exc
+
+
+def list_remote_pdfs() -> List[str]:
+    """Return PDF filenames (basename only) currently stored in the dataset."""
+    api = _api()
+    try:
+        files = api.list_repo_files(repo_id=DATASET_ID, repo_type="dataset")
+    except RepositoryNotFoundError:
+        return []
+    return [
+        f[len(PDF_PREFIX):]
+        for f in files
+        if f.startswith(PDF_PREFIX) and f.lower().endswith(".pdf")
+    ]
+
+
+def download_vector_store(
+    target_dir: Path,
+    expected_pdf_filenames: List[str],
+    embed_model: str,
+) -> bool:
+    """Restore the persisted LanceDB folder when its manifest matches the dataset PDFs."""
+    if not is_configured():
+        return False
+
+    api = _api()
+    try:
+        manifest_path = hf_hub_download(
+            repo_id=DATASET_ID,
+            repo_type="dataset",
+            filename=VECTOR_MANIFEST_PATH,
+            token=HF_TOKEN,
+        )
+    except (EntryNotFoundError, RepositoryNotFoundError):
+        logger.info("No vector cache manifest in dataset yet")
+        return False
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Could not download vector cache manifest: %s", exc)
+        return False
+
+    try:
+        manifest = json.loads(Path(manifest_path).read_text("utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Could not parse vector cache manifest: %s", exc)
+        return False
+
+    expected_manifest = _vector_manifest(expected_pdf_filenames, embed_model)
+    if manifest != expected_manifest:
+        logger.info("Vector cache manifest is stale; rebuilding from PDFs")
+        return False
+
+    try:
+        files = api.list_repo_files(repo_id=DATASET_ID, repo_type="dataset")
+    except RepositoryNotFoundError:
+        return False
+
+    vector_files = [f for f in files if f.startswith(VECTOR_INDEX_PREFIX)]
+    if not vector_files:
+        logger.info("Vector cache manifest exists but no cache files were found")
+        return False
+
+    shutil.rmtree(target_dir, ignore_errors=True)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    for repo_path in vector_files:
+        relative_path = repo_path[len(VECTOR_INDEX_PREFIX):]
+        if not relative_path:
+            continue
+        downloaded = hf_hub_download(
+            repo_id=DATASET_ID,
+            repo_type="dataset",
+            filename=repo_path,
+            token=HF_TOKEN,
+        )
+        destination = target_dir / relative_path
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(downloaded, destination)
+
+    logger.info("Vector cache restored from dataset (%d files)", len(vector_files))
+    return True
+
+
+def delete_vector_store() -> bool:
+    """Remove the persisted vector cache folder from the dataset."""
+    if not is_configured():
+        return False
+
+    api = _api()
+    try:
+        api.delete_folder(
+            path_in_repo=VECTOR_PREFIX.rstrip("/"),
+            repo_id=DATASET_ID,
+            repo_type="dataset",
+            commit_message="Delete vector cache",
+        )
+        logger.info("Vector cache deleted from HF Dataset")
+        return True
+    except (EntryNotFoundError, RepositoryNotFoundError):
+        return False
+
+
+def upload_vector_store(local_dir: Path, pdf_filenames: List[str], embed_model: str) -> bool:
+    """Persist the local LanceDB folder into the dataset along with a manifest."""
+    if not is_configured():
+        return False
+
+    api = _api()
+    _ensure_dataset_exists(api)
+
+    local_files = [p for p in local_dir.rglob("*") if p.is_file()]
+    if not pdf_filenames or not local_files:
+        delete_vector_store()
+        return bool(not pdf_filenames)
+
+    with TemporaryDirectory(prefix="iam-earth-vector-cache-") as tmp_dir:
+        stage_dir = Path(tmp_dir)
+        index_dir = stage_dir / "index"
+        shutil.copytree(local_dir, index_dir, dirs_exist_ok=True)
+        (stage_dir / "manifest.json").write_text(
+            json.dumps(_vector_manifest(pdf_filenames, embed_model), indent=2, ensure_ascii=False),
+            "utf-8",
+        )
+
+        api.upload_folder(
+            repo_id=DATASET_ID,
+            repo_type="dataset",
+            folder_path=stage_dir,
+            path_in_repo=VECTOR_PREFIX.rstrip("/"),
+            commit_message="Sync vector cache",
+            delete_patterns="**",
+            ignore_patterns=["**/.DS_Store"],
+        )
+
+    logger.info("Vector cache synced to HF Dataset")
+    return True
+
+
+def download_all_pdfs(target_dir: Path) -> List[Path]:
+    """Download every PDF in the dataset into target_dir. Returns local paths."""
+    target_dir.mkdir(parents=True, exist_ok=True)
+    paths: List[Path] = []
+    for name in list_remote_pdfs():
+        try:
+            local = hf_hub_download(
+                repo_id=DATASET_ID,
+                repo_type="dataset",
+                filename=f"{PDF_PREFIX}{name}",
+                local_dir=str(target_dir),
+                token=HF_TOKEN,
+            )
+            paths.append(Path(local))
+        except EntryNotFoundError:
+            continue
+    return paths
+
+
+def upload_pdf(local_path: Path, filename: str) -> None:
+    """Push a single PDF into the dataset under pdfs/<filename>."""
+    api = _api()
+    try:
+        _ensure_dataset_exists(api)
+        api.upload_file(
+            path_or_fileobj=str(local_path),
+            path_in_repo=f"{PDF_PREFIX}{filename}",
+            repo_id=DATASET_ID,
+            repo_type="dataset",
+            commit_message=f"Add {filename}",
+        )
+    except RuntimeError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise RuntimeError(
+            f"Failed to upload {filename} to dataset {DATASET_ID!r}: {exc}"
+        ) from exc
+
+
+def delete_pdf(filename: str) -> bool:
+    """Delete pdfs/<filename> from the dataset. Returns True if removed."""
+    api = _api()
+    try:
+        api.delete_file(
+            path_in_repo=f"{PDF_PREFIX}{filename}",
+            repo_id=DATASET_ID,
+            repo_type="dataset",
+            commit_message=f"Delete {filename}",
+        )
+        return True
+    except EntryNotFoundError:
+        return False

backend/main.py

@@ -0,0 +1,506 @@
+"""FastAPI entrypoint — runs internally on :8000, fronted by Next.js on :7860."""
+from __future__ import annotations
+
+# ── Load .env FIRST so all module-level os.environ.get() calls in local
+#    modules (auth, rag, hf_sync) pick up the values when they are imported.
+import asyncio
+import json
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+
+_env_file = Path(__file__).parent / ".env"
+if not _env_file.exists():
+    _env_file = Path(__file__).parent.parent / ".env"
+load_dotenv(_env_file)
+
+import logging
+import shutil
+import uuid
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, List, Literal, Optional
+
+from fastapi import Depends, FastAPI, File, Form, HTTPException, Response, UploadFile
+from fastapi.responses import StreamingResponse
+from huggingface_hub import AsyncInferenceClient
+from pydantic import BaseModel, Field
+
+# Local (imported AFTER load_dotenv so their module-level env reads are correct)
+import auth
+import hf_sync
+import personas_store
+from rag import RagEngine
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+logger = logging.getLogger("backend")
+
+_REPO_ROOT = Path(__file__).parent.parent
+TMP_UPLOAD_DIR = Path(os.environ.get("TMP_UPLOAD_DIR", str(_REPO_ROOT / ".tmp_uploads")))
+LANCEDB_DIR = Path(os.environ.get("LANCEDB_PATH", str(_REPO_ROOT / ".lancedb")))
+LLM_MODEL = os.environ.get("LLM_MODEL", "Qwen/Qwen2.5-7B-Instruct")
+LLM_MODEL_LOWER = LLM_MODEL.lower()
+EMBED_MODEL = os.environ.get("EMBED_MODEL", "BAAI/bge-small-en-v1.5")
+HF_TOKEN = os.environ.get("HF_TOKEN")
+LLM_EXTRA_BODY_JSON = os.environ.get("LLM_EXTRA_BODY_JSON", "").strip()
+LLM_FINAL_ANSWER_EXTRA_BODY_JSON = os.environ.get("LLM_FINAL_ANSWER_EXTRA_BODY_JSON", "").strip()
+SHOW_LLM_REASONING = os.environ.get("SHOW_LLM_REASONING", "").lower() in {"1", "true", "yes", "on"}
+LLM_MAX_TOKENS = int(
+    os.environ.get(
+        "LLM_MAX_TOKENS",
+        "2048" if "qwen/qwen3" in LLM_MODEL_LOWER or "qwen3" in LLM_MODEL_LOWER else "1024",
+    )
+)
+LLM_FINAL_ANSWER_MAX_TOKENS = int(os.environ.get("LLM_FINAL_ANSWER_MAX_TOKENS", "768"))
+
+# Globals populated in lifespan.
+rag: Optional[RagEngine] = None
+llm_client: Optional[AsyncInferenceClient] = None
+
+
+def _load_json_object_env(raw: str, env_name: str) -> Optional[dict[str, Any]]:
+    if not raw:
+        return None
+    try:
+        loaded = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        logger.warning("Ignoring invalid %s: %s", env_name, exc)
+        return None
+    if not isinstance(loaded, dict):
+        logger.warning("Ignoring %s because it is not a JSON object", env_name)
+        return None
+    return loaded
+
+
+def _is_qwen_thinking_model() -> bool:
+    return "qwen/qwen3" in LLM_MODEL_LOWER or "qwen3" in LLM_MODEL_LOWER
+
+
+def _non_thinking_extra_body() -> dict[str, Any]:
+    return {
+        "chat_template_kwargs": {"enable_thinking": False},
+        # Some HF router/provider combinations look for this at the top level.
+        "enable_thinking": False,
+    }
+
+
+def _chat_extra_body() -> Optional[dict[str, Any]]:
+    configured = _load_json_object_env(LLM_EXTRA_BODY_JSON, "LLM_EXTRA_BODY_JSON")
+    if configured is not None:
+        return configured
+
+    if _is_qwen_thinking_model():
+        return _non_thinking_extra_body()
+
+    return None
+
+
+def _final_answer_extra_body() -> Optional[dict[str, Any]]:
+    configured = _load_json_object_env(
+        LLM_FINAL_ANSWER_EXTRA_BODY_JSON,
+        "LLM_FINAL_ANSWER_EXTRA_BODY_JSON",
+    )
+    if configured is not None:
+        return configured
+
+    if _is_qwen_thinking_model():
+        return _non_thinking_extra_body()
+
+    return None
+
+
+CHAT_EXTRA_BODY = _chat_extra_body()
+FINAL_ANSWER_EXTRA_BODY = _final_answer_extra_body()
+
+
+def _sync_vector_cache_sync() -> bool:
+    if not hf_sync.is_configured():
+        return False
+    try:
+        return hf_sync.upload_vector_store(LANCEDB_DIR, hf_sync.list_remote_pdfs(), EMBED_MODEL)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Vector cache sync failed: %s", exc)
+        return False
+
+
+def _prepare_local_vector_cache_sync() -> tuple[bool, List[str]]:
+    """Restore the local LanceDB folder from the dataset when a valid cache exists."""
+    if not hf_sync.is_configured():
+        return False, []
+
+    remote_pdfs = hf_sync.list_remote_pdfs()
+    cache_restored = hf_sync.download_vector_store(LANCEDB_DIR, remote_pdfs, EMBED_MODEL)
+    if not cache_restored:
+        shutil.rmtree(LANCEDB_DIR, ignore_errors=True)
+    return cache_restored, remote_pdfs
+
+
+def _cold_start_index_sync() -> None:
+    if rag is None:
+        return
+
+    sync_dir = TMP_UPLOAD_DIR / "_sync"
+    sync_dir.mkdir(parents=True, exist_ok=True)
+    paths = hf_sync.download_all_pdfs(sync_dir)
+    if paths:
+        logger.info("Cold-start: indexing %d PDF(s) from dataset", len(paths))
+        added = rag.index_many((p, p.name) for p in paths)
+        logger.info("Cold-start: %d nodes indexed", added)
+        _sync_vector_cache_sync()
+    else:
+        logger.info("Cold-start: dataset has no PDFs yet")
+        _sync_vector_cache_sync()
+
+
+def _upload_and_index_sync(tmp_path: Path, safe_name: str) -> tuple[int, bool]:
+    if rag is None:
+        return 0, False
+
+    hf_sync.upload_pdf(tmp_path, safe_name)
+    nodes_added = rag.index_pdf(tmp_path, safe_name)
+    return nodes_added, _sync_vector_cache_sync()
+
+
+def _delete_and_sync_sync(filename: str) -> tuple[bool, int, bool]:
+    removed = hf_sync.delete_pdf(filename)
+    nodes_removed = rag.delete_by_filename(filename) if rag else 0
+    cache_synced = _sync_vector_cache_sync() if removed or nodes_removed > 0 else False
+    return removed, nodes_removed, cache_synced
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):  # noqa: ARG001
+    global rag, llm_client
+    TMP_UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
+
+    if not HF_TOKEN:
+        logger.warning("HF_TOKEN is not set — chat & embeddings will fail until configured.")
+
+    cache_restored = False
+    remote_pdfs: List[str] = []
+    if hf_sync.is_configured():
+        try:
+            cache_restored, remote_pdfs = await asyncio.to_thread(_prepare_local_vector_cache_sync)
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Vector cache restore failed: %s", exc)
+
+    rag = RagEngine()
+    llm_client = AsyncInferenceClient(model=LLM_MODEL, token=HF_TOKEN)
+
+    # Load personas (HF Dataset → local file → bundled defaults).
+    personas_store.load()
+
+    # Cold-start sync: pull all PDFs from the linked dataset and rebuild the index.
+    try:
+        if cache_restored:
+            logger.info("Cold-start: restored vector cache from dataset for %d PDF(s)", len(remote_pdfs))
+        elif hf_sync.is_configured():
+            await asyncio.to_thread(_cold_start_index_sync)
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("Cold-start sync failed: %s", exc)
+
+    yield
+
+
+app = FastAPI(title="IamEarthDev RAG", lifespan=lifespan)
+
+
+# ---------------- Models ----------------
+class ChatMessage(BaseModel):
+    role: Literal["system", "user", "assistant"]
+    content: str
+
+
+class ChatRequest(BaseModel):
+    messages: List[ChatMessage]
+    persona_prompt: str = Field(default="", description="Persona-specific system prompt")
+    temperature: float = Field(default=0.4, ge=0.0, le=1.5)
+    top_k: int = Field(default=4, ge=1, le=10)
+
+
+class LoginRequest(BaseModel):
+    passcode: str
+
+
+class DeleteRequest(BaseModel):
+    filename: str
+
+
+# ---------------- Health & files ----------------
+@app.get("/health")
+async def health() -> dict:
+    return {
+        "ok": True,
+        "model": LLM_MODEL,
+        "chat_extra_body": CHAT_EXTRA_BODY,
+        "final_answer_extra_body": FINAL_ANSWER_EXTRA_BODY,
+        "show_reasoning": SHOW_LLM_REASONING,
+    }
+
+
+@app.get("/files")
+async def list_files(_: None = Depends(auth.require_admin)) -> dict:
+    return {"files": hf_sync.list_remote_pdfs()}
+
+
+# ---------------- Admin auth ----------------
+@app.post("/admin/login")
+async def admin_login(body: LoginRequest, response: Response) -> dict:
+    if not auth.verify_passcode(body.passcode):
+        raise HTTPException(status_code=401, detail="Invalid passcode")
+    response.set_cookie(
+        key=auth.COOKIE_NAME,
+        value=auth.issue_token(),
+        httponly=True,
+        samesite="lax",
+        secure=False,  # HF Spaces serves over https at the edge; cookie still works.
+        max_age=60 * 60 * 12,
+        path="/",
+    )
+    return {"ok": True}
+
+
+@app.post("/admin/logout")
+async def admin_logout(response: Response) -> dict:
+    response.delete_cookie(auth.COOKIE_NAME, path="/")
+    return {"ok": True}
+
+
+@app.get("/admin/me")
+async def admin_me(_: None = Depends(auth.require_admin)) -> dict:
+    return {"authenticated": True}
+
+
+# ---------------- Personas ----------------
+class PersonaItem(BaseModel):
+    id: str
+    name: str
+    description: str
+    prompt: str
+
+
+@app.get("/personas")
+async def get_personas() -> dict:
+    """Public — students and the chat UI need this."""
+    return {"personas": personas_store.get_all()}
+
+
+@app.put("/personas")
+async def put_personas(
+    personas: List[PersonaItem],
+    _: None = Depends(auth.require_admin),
+) -> dict:
+    saved = personas_store.save([p.model_dump() for p in personas])
+    return {"personas": saved}
+
+
+@app.post("/personas/reset")
+async def reset_personas(_: None = Depends(auth.require_admin)) -> dict:
+    restored = personas_store.reset()
+    return {"personas": restored}
+
+
+# ---------------- Upload / Delete ----------------
+@app.post("/upload")
+async def upload(
+    file: UploadFile = File(...),
+    _: None = Depends(auth.require_admin),
+) -> dict:
+    if not file.filename or not file.filename.lower().endswith(".pdf"):
+        raise HTTPException(status_code=400, detail="Only .pdf files are accepted.")
+
+    safe_name = Path(file.filename).name  # strip any path components
+    tmp_path = TMP_UPLOAD_DIR / f"{uuid.uuid4().hex}_{safe_name}"
+    try:
+        with tmp_path.open("wb") as out:
+            shutil.copyfileobj(file.file, out)
+
+        try:
+            nodes_added, vector_cache_synced = await asyncio.to_thread(
+                _upload_and_index_sync, tmp_path, safe_name
+            )
+        except RuntimeError as exc:
+            raise HTTPException(status_code=502, detail=str(exc)) from exc
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Indexing failed for %s", safe_name)
+            raise HTTPException(
+                status_code=500,
+                detail=f"Uploaded {safe_name} to the dataset, but indexing failed: {exc}",
+            ) from exc
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+    return {
+        "ok": True,
+        "filename": safe_name,
+        "nodes_added": nodes_added,
+        "vector_cache_synced": vector_cache_synced,
+    }
+
+
+@app.post("/delete")
+async def delete(body: DeleteRequest, _: None = Depends(auth.require_admin)) -> dict:
+    safe_name = Path(body.filename).name
+    try:
+        removed, nodes_removed, vector_cache_synced = await asyncio.to_thread(
+            _delete_and_sync_sync, safe_name
+        )
+    except RuntimeError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+    if not removed and nodes_removed == 0:
+        raise HTTPException(status_code=404, detail=f"{safe_name} not found")
+    return {
+        "ok": True,
+        "filename": safe_name,
+        "nodes_removed": nodes_removed,
+        "vector_cache_synced": vector_cache_synced,
+    }
+
+
+# ---------------- Chat (streaming) ----------------
+SYSTEM_BASE = (
+    "You are a helpful course assistant for students. Use the selected persona "
+    "instructions to decide the tone, teaching style, level of directness, and "
+    "structure of your reply. Use the provided course material excerpts as your "
+    "primary source of truth. If the material does not contain the answer, say so "
+    "honestly. Always cite source filenames in square brackets when you use them."
+)
+
+
+def _build_messages(req: ChatRequest, context: str) -> List[dict]:
+    persona = req.persona_prompt.strip()
+    sys_parts = [SYSTEM_BASE]
+    if persona:
+        sys_parts.append(
+            "Selected persona instructions. Follow these for the response style; "
+            "only the grounding and citation rules above take priority:\n"
+            + persona
+        )
+    if context:
+        sys_parts.append(
+            "Course material excerpts (use these as your primary source of truth):\n\n"
+            + context
+        )
+    msgs: List[dict] = [{"role": "system", "content": "\n\n".join(sys_parts)}]
+    for m in req.messages:
+        if m.role == "system":
+            continue  # we control the system prompt server-side
+        msgs.append({"role": m.role, "content": m.content})
+    return msgs
+
+
+@app.post("/chat")
+async def chat(req: ChatRequest) -> StreamingResponse:
+    if rag is None or llm_client is None:
+        raise HTTPException(status_code=503, detail="Backend not ready.")
+    if not req.messages:
+        raise HTTPException(status_code=400, detail="messages must not be empty.")
+
+    last_user = next((m.content for m in reversed(req.messages) if m.role == "user"), "")
+    nodes = await asyncio.to_thread(rag.retrieve, last_user, req.top_k) if last_user else []
+    context = rag.format_context(nodes)
+    sources = sorted({n.node.metadata.get("source_filename", "unknown") for n in nodes})
+    messages = _build_messages(req, context)
+    final_answer_messages = [
+        *messages,
+        {
+            "role": "user",
+            "content": (
+                "You have already reasoned about this request. Now produce the "
+                "student-facing reply in the selected persona style, based on the "
+                "same course material excerpts. Do not repeat your thinking process. "
+                "Do not produce a thinking process, analysis section, or hidden reasoning. "
+                "Answer immediately and cite source filenames in square brackets."
+            ),
+        },
+    ]
+
+    async def stream() -> AsyncIterator[bytes]:
+        # Emit sources first as a single SSE-style event so the UI can render them.
+        yield (json.dumps({"type": "sources", "sources": sources}) + "\n").encode()
+        saw_content = False
+        saw_reasoning = False
+        finish_reason = None
+        try:
+            primary_stream = await llm_client.chat_completion(
+                messages=messages,
+                max_tokens=LLM_MAX_TOKENS,
+                temperature=req.temperature,
+                stream=True,
+                extra_body=CHAT_EXTRA_BODY,
+            )
+            async for chunk in primary_stream:
+                delta = ""
+                reasoning = ""
+                try:
+                    finish_reason = chunk.choices[0].finish_reason or finish_reason
+                    delta = chunk.choices[0].delta.content or ""
+                    reasoning = getattr(chunk.choices[0].delta, "reasoning", "") or ""
+                except (AttributeError, IndexError):
+                    pass
+                if delta:
+                    saw_content = True
+                    yield (json.dumps({"type": "delta", "text": delta}) + "\n").encode()
+                if reasoning:
+                    saw_reasoning = True
+                    if SHOW_LLM_REASONING:
+                        yield (json.dumps({"type": "reasoning", "text": reasoning}) + "\n").encode()
+                    elif not saw_content:
+                        logger.info(
+                            "Model emitted hidden reasoning before visible content; "
+                            "switching to final-answer pass early."
+                        )
+                        close_stream = getattr(primary_stream, "close", None)
+                        if callable(close_stream):
+                            close_stream()
+                        break
+
+            if not saw_content and saw_reasoning:
+                yield (
+                    json.dumps(
+                        {
+                            "type": "phase",
+                            "value": "finalizing",
+                            "message": "Thinking completed. Generating the final answer.",
+                        }
+                    )
+                    + "\n"
+                ).encode()
+                final_stream = await llm_client.chat_completion(
+                    messages=final_answer_messages,
+                    max_tokens=LLM_FINAL_ANSWER_MAX_TOKENS,
+                    temperature=req.temperature,
+                    stream=True,
+                    extra_body=FINAL_ANSWER_EXTRA_BODY,
+                )
+                async for chunk in final_stream:
+                    delta = ""
+                    try:
+                        delta = chunk.choices[0].delta.content or ""
+                    except (AttributeError, IndexError):
+                        pass
+                    if delta:
+                        saw_content = True
+                        yield (json.dumps({"type": "delta", "text": delta}) + "\n").encode()
+
+            if not saw_content and saw_reasoning:
+                detail = "The model finished its reasoning but did not emit a final answer."
+                if finish_reason == "length":
+                    detail += (
+                        " It likely exhausted the completion budget while thinking. "
+                        "Increase LLM_MAX_TOKENS if you want a longer first-pass reasoning budget."
+                    )
+                yield (json.dumps({"type": "error", "message": detail}) + "\n").encode()
+            yield (json.dumps({"type": "done"}) + "\n").encode()
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("LLM stream failed")
+            yield (json.dumps({"type": "error", "message": str(exc)}) + "\n").encode()
+
+    return StreamingResponse(
+        stream(),
+        media_type="application/x-ndjson",
+        headers={
+            "X-Accel-Buffering": "no",
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        },
+    )

backend/personas.json

@@ -0,0 +1,26 @@
+[
+  {
+    "id": "socratic",
+    "name": "Socratic Tutor",
+    "description": "Asks guiding questions instead of giving answers directly.",
+    "prompt": "Adopt the Socratic method. Rarely give a final answer outright; instead, ask one focused, open-ended question at a time that nudges the student toward the insight. Praise good reasoning, gently surface flawed assumptions."
+  },
+  {
+    "id": "strict_grader",
+    "name": "Strict Grader",
+    "description": "Rigorous, terse, and demanding of evidence.",
+    "prompt": "You are a strict grader. Be concise and uncompromising. Demand evidence from the course material for every claim. Point out logical gaps, missing citations, and imprecise terminology. Award no partial credit silently."
+  },
+  {
+    "id": "explainer",
+    "name": "Direct Explainer",
+    "description": "Plain, structured explanations with examples.",
+    "prompt": "Explain directly and clearly. Use short paragraphs, concrete examples, and analogies when helpful. End with a one-line summary. Never withhold the answer behind a question."
+  },
+  {
+    "id": "study_buddy",
+    "name": "Study Buddy",
+    "description": "Casual, encouraging, learns alongside the student.",
+    "prompt": "Speak as a friendly peer who is also studying this material. Be warm and encouraging, share confusion when it is genuine, and propose next steps the student could try together with you."
+  }
+]

backend/personas_store.py

@@ -0,0 +1,110 @@
+"""In-process persona store.
+
+Load priority on startup:
+  1. HF Dataset  (personas.json) — when HF_TOKEN + DATASET_ID are set
+  2. backend/personas.json       — bundled defaults / local edits
+
+Saves go to the local file and, when configured, to the HF Dataset.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from threading import Lock
+from typing import List
+
+logger = logging.getLogger(__name__)
+
+_BUNDLED = Path(__file__).parent / "personas.json"
+_DATASET_FILENAME = "personas.json"
+_lock = Lock()
+_personas: List[dict] = []
+
+
+def _read_bundled() -> List[dict]:
+    try:
+        return json.loads(_BUNDLED.read_text("utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Could not read bundled personas.json: %s", exc)
+        return []
+
+
+def load() -> None:
+    """Called once at startup. Tries HF Dataset first, falls back to local file."""
+    global _personas
+
+    # Try HF Dataset
+    hf_token = os.environ.get("HF_TOKEN")
+    dataset_id = os.environ.get("DATASET_ID")
+    if hf_token and dataset_id:
+        try:
+            from huggingface_hub import hf_hub_download
+            from huggingface_hub.utils import EntryNotFoundError
+
+            local = hf_hub_download(
+                repo_id=dataset_id,
+                repo_type="dataset",
+                filename=_DATASET_FILENAME,
+                token=hf_token,
+            )
+            data = json.loads(Path(local).read_text("utf-8"))
+            with _lock:
+                _personas = data
+            logger.info("Personas loaded from HF Dataset (%d items)", len(data))
+            return
+        except Exception as exc:  # noqa: BLE001
+            logger.info("No personas.json in dataset yet (%s), using bundled.", exc)
+
+    # Fall back to bundled file
+    data = _read_bundled()
+    with _lock:
+        _personas = data
+    logger.info("Personas loaded from bundled file (%d items)", len(data))
+
+
+def get_all() -> List[dict]:
+    with _lock:
+        return list(_personas)
+
+
+def save(new_personas: List[dict]) -> List[dict]:
+    """Persist a new list of personas. Returns the saved list."""
+    with _lock:
+        global _personas
+        _personas = new_personas
+
+    # Write local file
+    try:
+        _BUNDLED.write_text(json.dumps(new_personas, indent=2, ensure_ascii=False), "utf-8")
+        logger.info("Personas saved to local file")
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Could not write local personas.json: %s", exc)
+
+    # Sync to HF Dataset
+    hf_token = os.environ.get("HF_TOKEN")
+    dataset_id = os.environ.get("DATASET_ID")
+    if hf_token and dataset_id:
+        try:
+            from huggingface_hub import HfApi
+
+            api = HfApi(token=hf_token)
+            api.upload_file(
+                path_or_fileobj=json.dumps(new_personas, indent=2, ensure_ascii=False).encode(),
+                path_in_repo=_DATASET_FILENAME,
+                repo_id=dataset_id,
+                repo_type="dataset",
+                commit_message="Update personas",
+            )
+            logger.info("Personas synced to HF Dataset")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Could not sync personas to HF Dataset: %s", exc)
+
+    return new_personas
+
+
+def reset() -> List[dict]:
+    """Reset to the bundled defaults and persist."""
+    defaults = _read_bundled()
+    return save(defaults)

backend/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "iam-earth-dev-backend"
+version = "0.1.0"
+description = "FastAPI + LlamaIndex RAG backend for the IamEarthDev cloneable HF Space template"
+requires-python = ">=3.13,<3.14"
+dependencies = [
+  "fastapi>=0.115.0",
+  "uvicorn[standard]>=0.32.0",
+  "python-multipart>=0.0.12",
+  "pydantic>=2.9.0",
+  "python-dotenv>=1.0.1",
+  # RAG
+  "llama-index-core>=0.12.0",
+  "llama-index-vector-stores-lancedb>=0.3.0",
+  "llama-index-embeddings-huggingface-api>=0.3.0",
+  "lancedb>=0.16.0",
+  "pyarrow>=17.0.0",
+  "pandas>=2.2.0",
+  "pymupdf4llm>=0.0.17",
+  # HF
+  "huggingface-hub>=0.26.0",
+]
+
+[tool.uv]
+package = false

backend/rag.py

@@ -0,0 +1,174 @@
+"""RAG engine: PyMuPDF4LLM -> chunks -> HF-API embeddings -> LanceDB.
+
+Designed for HF Spaces Free CPU Basic:
+    * No local embedding/LLM weights are downloaded.
+    * LanceDB lives on ephemeral disk locally, but its files are mirrored into
+        the linked HF Dataset so cold starts can restore the vector cache instead
+        of rebuilding from PDFs every time.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from threading import Lock
+from typing import Iterable, List, Optional
+
+import pymupdf4llm
+from llama_index.core import Document, StorageContext, VectorStoreIndex, Settings
+from llama_index.core.node_parser import MarkdownNodeParser
+from llama_index.core.schema import MetadataMode, NodeWithScore, TextNode
+from llama_index.vector_stores.lancedb import LanceDBVectorStore
+
+from hf_embedding import SyncHuggingFaceInferenceEmbedding
+
+logger = logging.getLogger(__name__)
+
+_REPO_ROOT = Path(__file__).parent.parent
+LANCEDB_PATH = os.environ.get("LANCEDB_PATH", str(_REPO_ROOT / ".lancedb"))
+TABLE_NAME = "documents"
+EMBED_MODEL = os.environ.get("EMBED_MODEL", "BAAI/bge-small-en-v1.5")
+HF_TOKEN = os.environ.get("HF_TOKEN")
+
+# Filename is stored on every node so we can delete by source.
+FILENAME_KEY = "source_filename"
+
+
+class RagEngine:
+    """Thread-safe singleton wrapper around the LanceDB-backed index."""
+
+    def __init__(self) -> None:
+        self._lock = Lock()
+        self._index: Optional[VectorStoreIndex] = None
+        self._vector_store: Optional[LanceDBVectorStore] = None
+
+        if not HF_TOKEN:
+            logger.warning(
+                "HF_TOKEN is not set — embedding calls will fail. "
+                "Set it in .env before uploading or querying documents."
+            )
+            Settings.embed_model = None  # type: ignore[assignment]
+        else:
+            Settings.embed_model = SyncHuggingFaceInferenceEmbedding(
+                model_name=EMBED_MODEL,
+                token=HF_TOKEN,
+            )
+        Settings.llm = None  # We call the LLM ourselves in main.py for streaming.
+        Settings.node_parser = MarkdownNodeParser()
+
+        Path(LANCEDB_PATH).mkdir(parents=True, exist_ok=True)
+        self._vector_store = LanceDBVectorStore(
+            uri=LANCEDB_PATH,
+            table_name=TABLE_NAME,
+            mode="overwrite" if not self._table_exists() else "append",
+        )
+
+    # ---------- internals ----------
+    def _table_exists(self) -> bool:
+        import lancedb
+
+        try:
+            db = lancedb.connect(LANCEDB_PATH)
+            return TABLE_NAME in db.table_names()
+        except Exception:  # noqa: BLE001
+            return False
+
+    def _ensure_index(self) -> VectorStoreIndex:
+        if self._index is None:
+            storage = StorageContext.from_defaults(vector_store=self._vector_store)
+            if self._table_exists():
+                self._index = VectorStoreIndex.from_vector_store(
+                    vector_store=self._vector_store,
+                    storage_context=storage,
+                )
+            else:
+                self._index = VectorStoreIndex.from_documents(
+                    [], storage_context=storage
+                )
+        return self._index
+
+    @staticmethod
+    def _pdf_to_documents(pdf_path: Path, filename: str) -> List[Document]:
+        try:
+            md_text = pymupdf4llm.to_markdown(str(pdf_path))
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Failed to parse %s: %s", filename, exc)
+            return []
+        if not md_text.strip():
+            return []
+        return [
+            Document(
+                text=md_text,
+                metadata={FILENAME_KEY: filename},
+                excluded_llm_metadata_keys=[FILENAME_KEY],
+                excluded_embed_metadata_keys=[FILENAME_KEY],
+            )
+        ]
+
+    # ---------- public API ----------
+    def index_pdf(self, pdf_path: Path, filename: str) -> int:
+        """Parse a single PDF and insert its chunks. Returns # nodes added."""
+        with self._lock:
+            # First, drop any existing nodes for this filename (re-uploads).
+            self.delete_by_filename(filename, _locked=True)
+            docs = self._pdf_to_documents(pdf_path, filename)
+            if not docs:
+                return 0
+            index = self._ensure_index()
+            nodes = Settings.node_parser.get_nodes_from_documents(docs)
+            for n in nodes:
+                n.metadata[FILENAME_KEY] = filename
+            index.insert_nodes(nodes)
+            return len(nodes)
+
+    def index_many(self, items: Iterable[tuple[Path, str]]) -> int:
+        total = 0
+        for path, name in items:
+            total += self.index_pdf(path, name)
+        return total
+
+    def delete_by_filename(self, filename: str, *, _locked: bool = False) -> int:
+        """Remove all nodes with metadata.source_filename == filename."""
+        def _do() -> int:
+            import lancedb
+
+            if not self._table_exists():
+                return 0
+            db = lancedb.connect(LANCEDB_PATH)
+            tbl = db.open_table(TABLE_NAME)
+            # LanceDB stores metadata as a struct column called "metadata".
+            # Filter accesses nested fields with dot syntax.
+            try:
+                before = tbl.count_rows()
+                tbl.delete(f"metadata.{FILENAME_KEY} = '{filename}'")
+                removed = before - tbl.count_rows()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("delete_by_filename failed: %s", exc)
+                removed = 0
+            # Force the index to be rebuilt next query.
+            self._index = None
+            return removed
+
+        if _locked:
+            return _do()
+        with self._lock:
+            return _do()
+
+    def retrieve(self, query: str, top_k: int = 4) -> List[NodeWithScore]:
+        with self._lock:
+            if not self._table_exists():
+                return []
+            index = self._ensure_index()
+            retriever = index.as_retriever(similarity_top_k=top_k)
+            return retriever.retrieve(query)
+
+    @staticmethod
+    def format_context(nodes: List[NodeWithScore]) -> str:
+        if not nodes:
+            return ""
+        chunks = []
+        for i, n in enumerate(nodes, 1):
+            src = n.node.metadata.get(FILENAME_KEY, "unknown")
+            text = n.node.get_content(metadata_mode=MetadataMode.NONE).strip()
+            chunks.append(f"[{i}] (source: {src})\n{text}")
+        return "\n\n---\n\n".join(chunks)

frontend/.eslintrc.js

@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+module.exports = {
+  extends: ["next/core-web-vitals"],
+};

frontend/app/admin/login/page.tsx

@@ -0,0 +1,68 @@
+"use client";
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { Lock, Loader2 } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+
+export default function LoginPage() {
+  const router = useRouter();
+  const [passcode, setPasscode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true);
+    setError(null);
+    try {
+      const r = await fetch("/api/admin/login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ passcode }),
+      });
+      if (!r.ok) {
+        setError(r.status === 401 ? "Incorrect passcode." : await r.text());
+        return;
+      }
+      router.replace("/admin");
+    } catch (e) {
+      setError((e as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <main className="flex h-full items-center justify-center p-6">
+      <Card className="w-full max-w-sm">
+        <CardHeader className="items-center text-center">
+          <div className="mx-auto mb-2 rounded-full bg-muted p-3">
+            <Lock className="h-5 w-5" />
+          </div>
+          <CardTitle>Educator login</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <form onSubmit={submit} className="space-y-4">
+            <div className="space-y-2">
+              <Label htmlFor="passcode">Passcode</Label>
+              <Input
+                id="passcode"
+                type="password"
+                value={passcode}
+                onChange={(e) => setPasscode(e.target.value)}
+                autoFocus
+              />
+            </div>
+            {error && <p className="text-sm text-destructive">{error}</p>}
+            <Button type="submit" className="w-full" disabled={busy || !passcode}>
+              {busy ? <Loader2 className="h-4 w-4 animate-spin" /> : "Sign in"}
+            </Button>
+          </form>
+        </CardContent>
+      </Card>
+    </main>
+  );
+}

frontend/app/admin/page.tsx

@@ -0,0 +1,82 @@
+"use client";
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+import { Loader2, LogOut } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { FileUploader } from "@/components/file-uploader";
+import { FileList } from "@/components/file-list";
+import { PersonaEditor } from "@/components/persona-editor";
+
+export default function AdminPage() {
+  const router = useRouter();
+  const [checking, setChecking] = useState(true);
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  useEffect(() => {
+    (async () => {
+      const r = await fetch("/api/admin/me");
+      if (!r.ok) router.replace("/admin/login");
+      else setChecking(false);
+    })();
+  }, [router]);
+
+  async function logout() {
+    await fetch("/api/admin/logout", { method: "POST" });
+    router.replace("/admin/login");
+  }
+
+  if (checking) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+      </div>
+    );
+  }
+
+  return (
+    <main className="mx-auto max-w-3xl space-y-6 p-4 sm:p-6">
+      <header className="flex items-center justify-between">
+        <div>
+          <h1 className="text-xl font-semibold tracking-tight">Educator Dashboard</h1>
+          <p className="text-sm text-muted-foreground">
+            Upload PDFs to your linked Hugging Face Dataset.
+          </p>
+        </div>
+        <div className="flex items-center gap-2">
+          <Link
+            href="/"
+            className="text-sm text-muted-foreground underline-offset-4 hover:underline"
+          >
+            ← Chat
+          </Link>
+          <Button variant="ghost" size="sm" onClick={logout}>
+            <LogOut className="mr-1 h-4 w-4" /> Logout
+          </Button>
+        </div>
+      </header>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Upload PDFs</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <FileUploader onUploaded={() => setRefreshKey((k) => k + 1)} />
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardContent className="pt-6">
+          <FileList refreshKey={refreshKey} />
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardContent className="pt-6">
+          <PersonaEditor />
+        </CardContent>
+      </Card>
+    </main>
+  );
+}

frontend/app/api/chat/route.ts

@@ -0,0 +1,39 @@
+import { type NextRequest, NextResponse } from "next/server";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  const backend =
+    process.env.BACKEND_INTERNAL_URL ?? "http://127.0.0.1:8000";
+
+  let response: Response;
+  try {
+    response = await fetch(`${backend}/chat`, {
+      method: "POST",
+      body: request.body,
+      duplex: "half",
+      headers: {
+        "content-type": request.headers.get("content-type") ?? "application/json",
+      },
+    } as RequestInit & { duplex: "half" });
+  } catch {
+    return NextResponse.json(
+      { detail: "Could not reach the backend chat service." },
+      { status: 502 }
+    );
+  }
+
+  const headers = new Headers();
+  headers.set(
+    "content-type",
+    response.headers.get("content-type") ?? "application/x-ndjson"
+  );
+  headers.set("cache-control", "no-cache, no-transform");
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}

frontend/app/api/upload/route.ts

@@ -0,0 +1,37 @@
+import { type NextRequest, NextResponse } from "next/server";
+
+// This route handler replaces the rewrite proxy for /api/upload so that
+// large PDF files (>10 MB) are forwarded to FastAPI without Next.js buffering
+// the entire body before the 10 MB rewrite middleware limit kicks in.
+
+export const dynamic = "force-dynamic";
+
+export async function POST(request: NextRequest) {
+  const backend =
+    process.env.BACKEND_INTERNAL_URL ?? "http://127.0.0.1:8000";
+
+  const formData = await request.formData();
+  const cookie = request.headers.get("cookie") ?? "";
+
+  let response: Response;
+  try {
+    response = await fetch(`${backend}/upload`, {
+      method: "POST",
+      body: formData,
+      headers: { cookie },
+    });
+  } catch {
+    return NextResponse.json(
+      { detail: "Could not reach the backend upload service." },
+      { status: 502 }
+    );
+  }
+
+  const contentType = response.headers.get("content-type") ?? "text/plain; charset=utf-8";
+  const body = await response.text();
+
+  return new NextResponse(body, {
+    status: response.status,
+    headers: { "content-type": contentType },
+  });
+}

frontend/app/globals.css

@@ -0,0 +1,47 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222 47% 11%;
+    --card: 0 0% 100%;
+    --card-foreground: 222 47% 11%;
+    --primary: 222 47% 11%;
+    --primary-foreground: 210 40% 98%;
+    --muted: 210 40% 96%;
+    --muted-foreground: 215 16% 47%;
+    --accent: 210 40% 96%;
+    --accent-foreground: 222 47% 11%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214 32% 91%;
+    --input: 214 32% 91%;
+    --ring: 222 84% 4%;
+    --radius: 0.6rem;
+  }
+
+  .dark {
+    --background: 222 47% 6%;
+    --foreground: 210 40% 98%;
+    --card: 222 47% 8%;
+    --card-foreground: 210 40% 98%;
+    --primary: 210 40% 98%;
+    --primary-foreground: 222 47% 11%;
+    --muted: 217 33% 17%;
+    --muted-foreground: 215 20% 65%;
+    --accent: 217 33% 17%;
+    --accent-foreground: 210 40% 98%;
+    --destructive: 0 63% 31%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 217 33% 17%;
+    --input: 217 33% 17%;
+    --ring: 212 27% 84%;
+  }
+}
+
+@layer base {
+  * { @apply border-border; }
+  body { @apply bg-background text-foreground; }
+}

frontend/app/layout.tsx

@@ -0,0 +1,15 @@
+import "./globals.css";
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "IamEarthDev — Course Assistant",
+  description: "RAG chatbot for course materials, hosted on Hugging Face Spaces.",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className="h-full">
+      <body className="h-full antialiased">{children}</body>
+    </html>
+  );
+}

frontend/app/page.tsx

@@ -0,0 +1,26 @@
+import Link from "next/link";
+import { ChatInterface } from "@/components/chat-interface";
+
+export default function Page() {
+  return (
+    <main className="mx-auto flex h-full max-w-6xl flex-col gap-4 p-4 sm:p-6">
+      <header className="flex items-center justify-between">
+        <div>
+          <h1 className="text-xl font-semibold tracking-tight">Course Assistant</h1>
+          <p className="text-sm text-muted-foreground">
+            Ask questions grounded in the uploaded course materials.
+          </p>
+        </div>
+        <Link
+          href="/admin"
+          className="text-sm text-muted-foreground underline-offset-4 hover:underline"
+        >
+          Educator dashboard →
+        </Link>
+      </header>
+      <div className="min-h-0 flex-1">
+        <ChatInterface />
+      </div>
+    </main>
+  );
+}

frontend/components/chat-interface.tsx

@@ -0,0 +1,243 @@
+"use client";
+import { useState, useRef, useEffect } from "react";
+import { Send, Loader2, BookOpen } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Card, CardContent } from "@/components/ui/card";
+import { PersonaSelector } from "@/components/persona-selector";
+import { TemperatureSlider } from "@/components/temperature-slider";
+import { DEFAULT_PERSONAS, DEFAULT_PERSONA_ID, fetchPersonas, type Persona } from "@/lib/personas";
+
+type Msg = {
+  role: "user" | "assistant";
+  content: string;
+  reasoning?: string;
+  sources?: string[];
+  status?: string;
+};
+
+function latestThinkingPreview(reasoning: string) {
+  const text = reasoning.trim();
+  if (!text) return "";
+  return text.length > 420 ? `...${text.slice(-420)}` : text;
+}
+
+export function ChatInterface() {
+  const [personas, setPersonas] = useState<Persona[]>(DEFAULT_PERSONAS);
+  const [persona, setPersona] = useState<Persona>(
+    DEFAULT_PERSONAS.find((p) => p.id === DEFAULT_PERSONA_ID) ?? DEFAULT_PERSONAS[0]
+  );
+  const [temperature, setTemperature] = useState(0.4);
+  const [messages, setMessages] = useState<Msg[]>([]);
+  const [input, setInput] = useState("");
+  const [busy, setBusy] = useState(false);
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  // Load live personas on mount
+  useEffect(() => {
+    fetchPersonas().then((list) => {
+      setPersonas(list);
+      // Re-select same id if it still exists, otherwise pick default
+      setPersona((prev) => list.find((p) => p.id === prev.id) ?? list[0] ?? prev);
+    });
+  }, []);
+
+  useEffect(() => {
+    scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight });
+  }, [messages, busy]);
+
+  async function send() {
+    const text = input.trim();
+    if (!text || busy) return;
+    setInput("");
+    const next: Msg[] = [
+      ...messages,
+      { role: "user", content: text },
+      { role: "assistant", content: "" },
+    ];
+    setMessages(next);
+    setBusy(true);
+
+    try {
+      const resp = await fetch("/api/chat", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          messages: next
+            .slice(0, -1)
+            .map(({ role, content }) => ({ role, content })),
+          persona_prompt: persona.prompt,
+          temperature,
+        }),
+      });
+
+      if (!resp.ok) {
+        const message = (await resp.text()).trim() || `HTTP ${resp.status}`;
+        throw new Error(message);
+      }
+
+      if (!resp.body) throw new Error("No response stream");
+      const reader = resp.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = "";
+      let acc = "";
+      let reasoning = "";
+      let sources: string[] | undefined;
+      let status: string | undefined;
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const evt = JSON.parse(line);
+            if (evt.type === "delta") {
+              acc += evt.text;
+              status = undefined;
+            } else if (evt.type === "reasoning") {
+              reasoning += evt.text;
+            } else if (evt.type === "phase") {
+              status = evt.message || evt.value;
+            } else if (evt.type === "sources") {
+              sources = evt.sources;
+            } else if (evt.type === "error") {
+              acc += `\n\n*[error: ${evt.message}]*`;
+            }
+            setMessages((prev) => {
+              const copy = [...prev];
+              copy[copy.length - 1] = {
+                role: "assistant",
+                content: acc,
+                reasoning,
+                sources,
+                status,
+              };
+              return copy;
+            });
+          } catch {
+            // partial JSON, ignore
+          }
+        }
+      }
+    } catch (e) {
+      setMessages((prev) => {
+        const copy = [...prev];
+        copy[copy.length - 1] = {
+          role: "assistant",
+          content: `*Failed to reach the model: ${(e as Error).message}*`,
+        };
+        return copy;
+      });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="grid h-full grid-cols-1 gap-6 lg:grid-cols-[1fr_320px]">
+      <Card className="flex flex-col overflow-hidden">
+        <div ref={scrollRef} className="flex-1 space-y-4 overflow-y-auto p-6">
+          {messages.length === 0 && (
+            <div className="flex h-full flex-col items-center justify-center text-center text-muted-foreground">
+              <BookOpen className="mb-3 h-10 w-10 opacity-50" />
+              <p className="text-sm">
+                Ask a question about your course material to get started.
+              </p>
+            </div>
+          )}
+          {messages.map((m, i) => {
+            const isStreamingAssistant =
+              busy && i === messages.length - 1 && m.role === "assistant";
+            const thinkingPreview =
+              isStreamingAssistant && !m.content && m.reasoning
+                ? latestThinkingPreview(m.reasoning)
+                : "";
+
+            return (
+              <div
+                key={i}
+                className={`flex ${m.role === "user" ? "justify-end" : "justify-start"}`}
+              >
+              <div
+                className={`max-w-[85%] rounded-lg px-4 py-2.5 text-sm leading-relaxed ${
+                  m.role === "user"
+                    ? "bg-primary text-primary-foreground"
+                    : "bg-muted text-foreground"
+                }`}
+              >
+                <div className="whitespace-pre-wrap">
+                  {m.content ||
+                    thinkingPreview ||
+                    (isStreamingAssistant ? "Thinking…" : "")}
+                </div>
+                {thinkingPreview && (
+                  <div className="mt-2 text-xs italic opacity-70">
+                    Thinking stream
+                  </div>
+                )}
+                {m.reasoning && (
+                  <details className="mt-3 rounded-md border border-border/60 bg-background/60 p-3 text-xs text-muted-foreground">
+                    <summary className="cursor-pointer select-none font-medium text-foreground">
+                      Thinking
+                    </summary>
+                    <div className="mt-2 whitespace-pre-wrap leading-relaxed">
+                      {m.reasoning}
+                    </div>
+                  </details>
+                )}
+                {m.status && (
+                  <div className="mt-2 text-xs italic opacity-80">{m.status}</div>
+                )}
+                {m.sources && m.sources.length > 0 && (
+                  <div className="mt-2 border-t border-border/50 pt-2 text-xs opacity-80">
+                    <span className="font-medium">Sources: </span>
+                    {m.sources.join(", ")}
+                  </div>
+                )}
+              </div>
+            </div>
+            );
+          })}
+        </div>
+        <div className="border-t p-4">
+          <form
+            className="flex gap-2"
+            onSubmit={(e) => {
+              e.preventDefault();
+              send();
+            }}
+          >
+            <Input
+              placeholder="Ask about the course material…"
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              disabled={busy}
+            />
+            <Button type="submit" disabled={busy || !input.trim()} size="icon">
+              {busy ? (
+                <Loader2 className="h-4 w-4 animate-spin" />
+              ) : (
+                <Send className="h-4 w-4" />
+              )}
+            </Button>
+          </form>
+        </div>
+      </Card>
+
+      <Card>
+        <CardContent className="space-y-6 p-6">
+          <div className="space-y-2">
+            <div className="text-sm font-medium">Persona</div>
+            <PersonaSelector personas={personas} value={persona.id} onChange={setPersona} />
+            <p className="text-xs text-muted-foreground">{persona.description}</p>
+          </div>
+          <TemperatureSlider value={temperature} onChange={setTemperature} />
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

frontend/components/file-list.tsx

@@ -0,0 +1,85 @@
+"use client";
+import { useEffect, useState, useCallback } from "react";
+import { Trash2, FileText, RefreshCw } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+export function FileList({ refreshKey }: { refreshKey: number }) {
+  const [files, setFiles] = useState<string[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [deleting, setDeleting] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    setError(null);
+    try {
+      const r = await fetch("/api/files");
+      if (!r.ok) throw new Error(await r.text());
+      const data = await r.json();
+      setFiles(data.files ?? []);
+    } catch (e) {
+      setError((e as Error).message);
+    }
+  }, []);
+
+  useEffect(() => {
+    load();
+  }, [load, refreshKey]);
+
+  async function remove(name: string) {
+    if (!confirm(`Delete ${name}? This removes it from the dataset and the index.`))
+      return;
+    setDeleting(name);
+    try {
+      const r = await fetch("/api/delete", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ filename: name }),
+      });
+      if (!r.ok) throw new Error(await r.text());
+      await load();
+    } catch (e) {
+      setError((e as Error).message);
+    } finally {
+      setDeleting(null);
+    }
+  }
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center justify-between">
+        <h2 className="text-sm font-semibold">Course materials</h2>
+        <Button variant="ghost" size="sm" onClick={load}>
+          <RefreshCw className="mr-1 h-3.5 w-3.5" /> Refresh
+        </Button>
+      </div>
+      {error && <p className="text-sm text-destructive">{error}</p>}
+      {files === null ? (
+        <p className="text-sm text-muted-foreground">Loading…</p>
+      ) : files.length === 0 ? (
+        <p className="text-sm text-muted-foreground">No files uploaded yet.</p>
+      ) : (
+        <ul className="divide-y rounded-lg border">
+          {files.map((name) => (
+            <li
+              key={name}
+              className="flex items-center justify-between gap-3 px-4 py-2.5"
+            >
+              <div className="flex min-w-0 items-center gap-2">
+                <FileText className="h-4 w-4 shrink-0 text-muted-foreground" />
+                <span className="truncate text-sm">{name}</span>
+              </div>
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => remove(name)}
+                disabled={deleting === name}
+                className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+              >
+                <Trash2 className="h-4 w-4" />
+              </Button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

frontend/components/file-uploader.tsx

@@ -0,0 +1,87 @@
+"use client";
+import { useCallback, useState } from "react";
+import { useDropzone } from "react-dropzone";
+import { UploadCloud, Loader2 } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+export function FileUploader({ onUploaded }: { onUploaded: () => void }) {
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [progress, setProgress] = useState<string | null>(null);
+
+  const upload = useCallback(
+    async (files: File[]) => {
+      setError(null);
+      setBusy(true);
+      try {
+        for (let i = 0; i < files.length; i++) {
+          const f = files[i];
+          setProgress(`Uploading ${i + 1}/${files.length}: ${f.name}`);
+          const fd = new FormData();
+          fd.append("file", f);
+          const r = await fetch("/api/upload", { method: "POST", body: fd });
+          if (!r.ok) {
+            const contentType = r.headers.get("content-type") ?? "";
+            let message = "Upload failed";
+
+            if (contentType.includes("application/json")) {
+              const payload = (await r.json().catch(() => null)) as
+                | { detail?: string; error?: string }
+                | null;
+              message = payload?.detail ?? payload?.error ?? message;
+            } else {
+              message = (await r.text()).trim() || message;
+            }
+
+            throw new Error(`${f.name}: ${message}`);
+          }
+        }
+        onUploaded();
+      } catch (e) {
+        setError((e as Error).message);
+      } finally {
+        setBusy(false);
+        setProgress(null);
+      }
+    },
+    [onUploaded]
+  );
+
+  const { getRootProps, getInputProps, isDragActive } = useDropzone({
+    accept: { "application/pdf": [".pdf"] },
+    multiple: true,
+    disabled: busy,
+    onDrop: upload,
+  });
+
+  return (
+    <div className="space-y-2">
+      <div
+        {...getRootProps()}
+        className={cn(
+          "flex cursor-pointer flex-col items-center justify-center rounded-lg border-2 border-dashed p-10 text-center transition-colors",
+          isDragActive ? "border-primary bg-accent" : "border-border hover:bg-accent/50",
+          busy && "pointer-events-none opacity-60"
+        )}
+      >
+        <input {...getInputProps()} />
+        {busy ? (
+          <Loader2 className="mb-2 h-8 w-8 animate-spin text-muted-foreground" />
+        ) : (
+          <UploadCloud className="mb-2 h-8 w-8 text-muted-foreground" />
+        )}
+        <p className="text-sm font-medium">
+          {busy
+            ? progress ?? "Uploading…"
+            : isDragActive
+            ? "Drop the PDFs here"
+            : "Drag & drop PDFs here, or click to select"}
+        </p>
+        <p className="mt-1 text-xs text-muted-foreground">
+          Files are pushed to your linked Hugging Face Dataset and indexed automatically.
+        </p>
+      </div>
+      {error && <p className="text-sm text-destructive">{error}</p>}
+    </div>
+  );
+}

frontend/components/persona-editor.tsx

@@ -0,0 +1,297 @@
+"use client";
+import { useEffect, useState, useRef } from "react";
+import { Plus, Trash2, RotateCcw, Save, ChevronDown, ChevronUp, Pencil } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { type Persona } from "@/lib/personas";
+
+function uid() {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+// ── Confirm dialog ────────────────────────────────────────────────────────────
+function ConfirmDialog({
+  trigger,
+  title,
+  description,
+  confirmLabel = "Confirm",
+  destructive = false,
+  onConfirm,
+}: {
+  trigger: React.ReactNode;
+  title: string;
+  description: string;
+  confirmLabel?: string;
+  destructive?: boolean;
+  onConfirm: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger asChild>{trigger}</DialogTrigger>
+      <DialogContent className="max-w-sm">
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          <DialogDescription>{description}</DialogDescription>
+        </DialogHeader>
+        <DialogFooter className="gap-2">
+          <Button variant="outline" size="sm" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button
+            variant={destructive ? "destructive" : "default"}
+            size="sm"
+            onClick={() => {
+              setOpen(false);
+              onConfirm();
+            }}
+          >
+            {confirmLabel}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+// ── Per-persona card ──────────────────────────────────────────────────────────
+type SaveState = "idle" | "editing" | "saving" | "saved" | "error";
+
+function PersonaCard({
+  persona,
+  onSave,
+  onDelete,
+}: {
+  persona: Persona;
+  onSave: (p: Persona) => Promise<void>;
+  onDelete: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [draft, setDraft] = useState<Persona>(persona);
+  const [state, setState] = useState<SaveState>("idle");
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+
+  // Sync when parent updates (e.g. after reset)
+  const prevId = useRef(persona.id);
+  useEffect(() => {
+    if (persona.id !== prevId.current || state === "idle") {
+      setDraft(persona);
+      prevId.current = persona.id;
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [persona]);
+
+  const isDirty = JSON.stringify(draft) !== JSON.stringify(persona);
+
+  function change(field: keyof Persona, value: string) {
+    setDraft((d) => ({ ...d, [field]: value }));
+    setState("editing");
+  }
+
+  async function save() {
+    setState("saving");
+    setErrorMsg(null);
+    try {
+      await onSave(draft);
+      setState("saved");
+      setTimeout(() => setState("idle"), 2500);
+    } catch (e) {
+      setErrorMsg((e as Error).message);
+      setState("error");
+    }
+  }
+
+  return (
+    <div className="rounded-lg border bg-card">
+      {/* Header row */}
+      <div className="flex items-center gap-2 px-4 py-3">
+        <button
+          type="button"
+          className="flex flex-1 items-center justify-between text-left text-sm font-medium"
+          onClick={() => setOpen((o) => !o)}
+        >
+          <span className={draft.name ? "" : "italic text-muted-foreground"}>
+            {draft.name || "Unnamed"}
+          </span>
+          {open ? (
+            <ChevronUp className="h-4 w-4 shrink-0" />
+          ) : (
+            <ChevronDown className="h-4 w-4 shrink-0" />
+          )}
+        </button>
+
+        <ConfirmDialog
+          trigger={
+            <Button variant="ghost" size="icon" className="h-7 w-7 text-muted-foreground hover:text-destructive">
+              <Trash2 className="h-3.5 w-3.5" />
+            </Button>
+          }
+          title="Delete persona"
+          description={`Remove "${draft.name || "this persona"}" permanently? Students will no longer see it.`}
+          confirmLabel="Delete"
+          destructive
+          onConfirm={onDelete}
+        />
+      </div>
+
+      {/* Expandable fields */}
+      {open && (
+        <div className="space-y-3 border-t px-4 py-4">
+          <div className="space-y-1">
+            <Label>Name</Label>
+            <Input
+              value={draft.name}
+              onChange={(e) => change("name", e.target.value)}
+              placeholder="e.g. Socratic Tutor"
+            />
+          </div>
+          <div className="space-y-1">
+            <Label>Short description</Label>
+            <Input
+              value={draft.description}
+              onChange={(e) => change("description", e.target.value)}
+              placeholder="One sentence shown in the dropdown"
+            />
+          </div>
+          <div className="space-y-1">
+            <Label>System prompt</Label>
+            <textarea
+              className="min-h-[120px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              value={draft.prompt}
+              onChange={(e) => change("prompt", e.target.value)}
+              placeholder="Instructions appended to the system message…"
+            />
+          </div>
+
+          {errorMsg && <p className="text-xs text-destructive">{errorMsg}</p>}
+
+          <Button
+            size="sm"
+            className="w-full"
+            onClick={save}
+            disabled={!isDirty || state === "saving"}
+          >
+            <Save className="mr-1 h-3.5 w-3.5" />
+            {state === "saving"
+              ? "Saving…"
+              : state === "saved"
+                ? "Saved!"
+                : isDirty
+                  ? "Save changes"
+                  : "No changes"}
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── Main editor ───────────────────────────────────────────────────────────────
+export function PersonaEditor() {
+  const [personas, setPersonas] = useState<Persona[]>([]);
+
+  async function load() {
+    try {
+      const r = await fetch("/api/personas");
+      const d = await r.json();
+      setPersonas(d.personas ?? []);
+    } catch {}
+  }
+
+  useEffect(() => { load(); }, []);
+
+  // Save a single updated persona
+  async function saveOne(updated: Persona) {
+    const next = personas.map((p) => (p.id === updated.id ? updated : p));
+    const r = await fetch("/api/personas", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(next),
+    });
+    if (!r.ok) throw new Error(await r.text());
+    const data = await r.json();
+    setPersonas(data.personas);
+  }
+
+  function remove(id: string) {
+    const next = personas.filter((p) => p.id !== id);
+    fetch("/api/personas", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(next),
+    })
+      .then((r) => r.json())
+      .then((d) => setPersonas(d.personas ?? next))
+      .catch(() => setPersonas(next));
+  }
+
+  function addNew() {
+    setPersonas((prev) => [
+      ...prev,
+      { id: uid(), name: "", description: "", prompt: "" },
+    ]);
+  }
+
+  async function reset() {
+    const r = await fetch("/api/personas/reset", { method: "POST" });
+    if (!r.ok) throw new Error(await r.text());
+    const data = await r.json();
+    setPersonas(data.personas);
+  }
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center justify-between">
+        <h2 className="text-sm font-semibold">Personas</h2>
+        <ConfirmDialog
+          trigger={
+            <Button variant="ghost" size="sm" type="button">
+              <RotateCcw className="mr-1 h-3.5 w-3.5" /> Reset to defaults
+            </Button>
+          }
+          title="Reset personas?"
+          description="All custom personas will be replaced with the bundled defaults. This cannot be undone."
+          confirmLabel="Reset"
+          destructive
+          onConfirm={reset}
+        />
+      </div>
+      <p className="text-xs text-muted-foreground">
+        Each card saves individually. Changes are written to{" "}
+        <code className="rounded bg-muted px-1">personas.json</code> and synced
+        to your HF Dataset.
+      </p>
+
+      <div className="space-y-2">
+        {personas.map((p) => (
+          <PersonaCard
+            key={p.id}
+            persona={p}
+            onSave={saveOne}
+            onDelete={() => remove(p.id)}
+          />
+        ))}
+      </div>
+
+      <Button
+        variant="outline"
+        size="sm"
+        type="button"
+        className="w-full"
+        onClick={addNew}
+      >
+        <Plus className="mr-1 h-4 w-4" /> Add persona
+      </Button>
+    </div>
+  );
+}

frontend/components/persona-selector.tsx

@@ -0,0 +1,43 @@
+"use client";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { type Persona } from "@/lib/personas";
+
+export function PersonaSelector({
+  personas,
+  value,
+  onChange,
+}: {
+  personas: Persona[];
+  value: string;
+  onChange: (p: Persona) => void;
+}) {
+  return (
+    <Select
+      value={value}
+      onValueChange={(id) => {
+        const p = personas.find((x) => x.id === id);
+        if (p) onChange(p);
+      }}
+    >
+      <SelectTrigger className="w-full">
+        <SelectValue placeholder="Choose a persona" />
+      </SelectTrigger>
+      <SelectContent>
+        {personas.map((p) => (
+          <SelectItem key={p.id} value={p.id}>
+            <div className="flex flex-col">
+              <span className="font-medium">{p.name}</span>
+              <span className="text-xs text-muted-foreground">{p.description}</span>
+            </div>
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}

frontend/components/temperature-slider.tsx

@@ -0,0 +1,32 @@
+"use client";
+import { Slider } from "@/components/ui/slider";
+import { Label } from "@/components/ui/label";
+
+export function TemperatureSlider({
+  value,
+  onChange,
+}: {
+  value: number;
+  onChange: (n: number) => void;
+}) {
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center justify-between">
+        <Label>Creativity</Label>
+        <span className="text-sm tabular-nums text-muted-foreground">
+          {value.toFixed(2)}
+        </span>
+      </div>
+      <Slider
+        min={0}
+        max={1.2}
+        step={0.05}
+        value={[value]}
+        onValueChange={(v) => onChange(v[0] ?? 0)}
+      />
+      <p className="text-xs text-muted-foreground">
+        Lower = more focused on the source material. Higher = more creative.
+      </p>
+    </div>
+  );
+}

frontend/components/ui/button.tsx

@@ -0,0 +1,48 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-6",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Button.displayName = "Button";

frontend/components/ui/card.tsx

@@ -0,0 +1,65 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export const Card = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      "rounded-lg border bg-card text-card-foreground shadow-sm",
+      className
+    )}
+    {...props}
+  />
+));
+Card.displayName = "Card";
+
+export const CardHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn("flex flex-col gap-1.5 p-6", className)} {...props} />
+));
+CardHeader.displayName = "CardHeader";
+
+export const CardTitle = React.forwardRef<
+  HTMLHeadingElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h3
+    ref={ref}
+    className={cn("text-lg font-semibold leading-none tracking-tight", className)}
+    {...props}
+  />
+));
+CardTitle.displayName = "CardTitle";
+
+export const CardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p ref={ref} className={cn("text-sm text-muted-foreground", className)} {...props} />
+));
+CardDescription.displayName = "CardDescription";
+
+export const CardContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />
+));
+CardContent.displayName = "CardContent";
+
+export const CardFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex items-center p-6 pt-0", className)}
+    {...props}
+  />
+));
+CardFooter.displayName = "CardFooter";

frontend/components/ui/dialog.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import * as React from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { X } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+const Dialog = DialogPrimitive.Root;
+const DialogTrigger = DialogPrimitive.Trigger;
+const DialogPortal = DialogPrimitive.Portal;
+const DialogClose = DialogPrimitive.Close;
+
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      "fixed inset-0 z-50 bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className
+    )}
+    {...props}
+  />
+));
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
+
+const DialogContent = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+  <DialogPortal>
+    <DialogOverlay />
+    <DialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <DialogClose className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
+        <X className="h-4 w-4" />
+        <span className="sr-only">Close</span>
+      </DialogClose>
+    </DialogPrimitive.Content>
+  </DialogPortal>
+));
+DialogContent.displayName = DialogPrimitive.Content.displayName;
+
+const DialogHeader = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-col space-y-1.5 text-center sm:text-left", className)}
+    {...props}
+  />
+);
+DialogHeader.displayName = "DialogHeader";
+
+const DialogFooter = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2", className)}
+    {...props}
+  />
+);
+DialogFooter.displayName = "DialogFooter";
+
+const DialogTitle = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Title
+    ref={ref}
+    className={cn("text-lg font-semibold leading-none tracking-tight", className)}
+    {...props}
+  />
+));
+DialogTitle.displayName = DialogPrimitive.Title.displayName;
+
+const DialogDescription = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Description
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+));
+DialogDescription.displayName = DialogPrimitive.Description.displayName;
+
+export {
+  Dialog,
+  DialogPortal,
+  DialogOverlay,
+  DialogClose,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+};

frontend/components/ui/input.tsx

@@ -0,0 +1,19 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export type InputProps = React.InputHTMLAttributes<HTMLInputElement>;
+
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, ...props }, ref) => (
+    <input
+      type={type}
+      ref={ref}
+      className={cn(
+        "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+);
+Input.displayName = "Input";

frontend/components/ui/label.tsx

@@ -0,0 +1,19 @@
+"use client";
+import * as React from "react";
+import * as LabelPrimitive from "@radix-ui/react-label";
+import { cn } from "@/lib/utils";
+
+export const Label = React.forwardRef<
+  React.ElementRef<typeof LabelPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <LabelPrimitive.Root
+    ref={ref}
+    className={cn(
+      "text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
+      className
+    )}
+    {...props}
+  />
+));
+Label.displayName = "Label";

frontend/components/ui/select.tsx

@@ -0,0 +1,81 @@
+"use client";
+import * as React from "react";
+import * as SelectPrimitive from "@radix-ui/react-select";
+import { Check, ChevronDown } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+export const Select = SelectPrimitive.Root;
+export const SelectValue = SelectPrimitive.Value;
+export const SelectGroup = SelectPrimitive.Group;
+
+export const SelectTrigger = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>
+>(({ className, children, ...props }, ref) => (
+  <SelectPrimitive.Trigger
+    ref={ref}
+    className={cn(
+      "flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <SelectPrimitive.Icon asChild>
+      <ChevronDown className="h-4 w-4 opacity-50" />
+    </SelectPrimitive.Icon>
+  </SelectPrimitive.Trigger>
+));
+SelectTrigger.displayName = "SelectTrigger";
+
+export const SelectContent = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Content>
+>(({ className, children, position = "popper", ...props }, ref) => (
+  <SelectPrimitive.Portal>
+    <SelectPrimitive.Content
+      ref={ref}
+      position={position}
+      className={cn(
+        "relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md border bg-card text-card-foreground shadow-md",
+        position === "popper" &&
+          "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
+        className
+      )}
+      {...props}
+    >
+      <SelectPrimitive.Viewport
+        className={cn(
+          "p-1",
+          position === "popper" &&
+            "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)]"
+        )}
+      >
+        {children}
+      </SelectPrimitive.Viewport>
+    </SelectPrimitive.Content>
+  </SelectPrimitive.Portal>
+));
+SelectContent.displayName = "SelectContent";
+
+export const SelectItem = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Item>
+>(({ className, children, ...props }, ref) => (
+  <SelectPrimitive.Item
+    ref={ref}
+    className={cn(
+      "relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+      className
+    )}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <SelectPrimitive.ItemIndicator>
+        <Check className="h-4 w-4" />
+      </SelectPrimitive.ItemIndicator>
+    </span>
+    <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+  </SelectPrimitive.Item>
+));
+SelectItem.displayName = "SelectItem";

frontend/components/ui/slider.tsx

@@ -0,0 +1,24 @@
+"use client";
+import * as React from "react";
+import * as SliderPrimitive from "@radix-ui/react-slider";
+import { cn } from "@/lib/utils";
+
+export const Slider = React.forwardRef<
+  React.ElementRef<typeof SliderPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <SliderPrimitive.Root
+    ref={ref}
+    className={cn(
+      "relative flex w-full touch-none select-none items-center",
+      className
+    )}
+    {...props}
+  >
+    <SliderPrimitive.Track className="relative h-2 w-full grow overflow-hidden rounded-full bg-muted">
+      <SliderPrimitive.Range className="absolute h-full bg-primary" />
+    </SliderPrimitive.Track>
+    <SliderPrimitive.Thumb className="block h-5 w-5 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50" />
+  </SliderPrimitive.Root>
+));
+Slider.displayName = "Slider";

frontend/lib/personas.ts

@@ -0,0 +1,63 @@
+export type Persona = {
+  id: string;
+  name: string;
+  description: string;
+  prompt: string;
+};
+
+// Bundled fallback — shown before the API responds.
+// The canonical list lives on the server (backend/personas.json → HF Dataset).
+export const DEFAULT_PERSONAS: Persona[] = [
+  {
+    id: "socratic",
+    name: "Socratic Tutor",
+    description: "Asks guiding questions instead of giving answers directly.",
+    prompt:
+      "Adopt the Socratic method. Rarely give a final answer outright; instead, " +
+      "ask one focused, open-ended question at a time that nudges the student " +
+      "toward the insight. Praise good reasoning, gently surface flawed assumptions.",
+  },
+  {
+    id: "strict_grader",
+    name: "Strict Grader",
+    description: "Rigorous, terse, and demanding of evidence.",
+    prompt:
+      "You are a strict grader. Be concise and uncompromising. Demand evidence " +
+      "from the course material for every claim. Point out logical gaps, missing " +
+      "citations, and imprecise terminology. Award no partial credit silently.",
+  },
+  {
+    id: "explainer",
+    name: "Direct Explainer",
+    description: "Plain, structured explanations with examples.",
+    prompt:
+      "Explain directly and clearly. Use short paragraphs, concrete examples, " +
+      "and analogies when helpful. End with a one-line summary. Never withhold " +
+      "the answer behind a question.",
+  },
+  {
+    id: "study_buddy",
+    name: "Study Buddy",
+    description: "Casual, encouraging, learns alongside the student.",
+    prompt:
+      "Speak as a friendly peer who is also studying this material. Be warm and " +
+      "encouraging, share confusion when it's genuine, and propose next steps " +
+      "the student could try together with you.",
+  },
+];
+
+export const DEFAULT_PERSONA_ID = "explainer";
+
+/** Fetch the live persona list from the backend. Falls back to DEFAULT_PERSONAS. */
+export async function fetchPersonas(): Promise<Persona[]> {
+  try {
+    const r = await fetch("/api/personas");
+    if (!r.ok) throw new Error("non-ok");
+    const data = await r.json();
+    if (Array.isArray(data.personas) && data.personas.length > 0) return data.personas;
+  } catch {
+    // swallow — use bundled fallback
+  }
+  return DEFAULT_PERSONAS;
+}
+

frontend/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

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.js

@@ -0,0 +1,22 @@
+/** @type {import('next').NextConfig} */
+// All /api/* requests from the browser are transparently proxied to the
+// FastAPI process on 127.0.0.1:8000. Only port 7860 is exposed by the HF Space.
+const nextConfig = {
+  reactStrictMode: true,
+  output: "standalone" === process.env.NEXT_OUTPUT ? "standalone" : undefined,
+  // Allow large PDF uploads through the upload route handler
+  experimental: {
+    serverActions: { bodySizeLimit: "100mb" },
+  },
+  async rewrites() {
+    const backend = process.env.BACKEND_INTERNAL_URL || "http://127.0.0.1:8000";
+    return [
+      {
+        source: "/api/:path*",
+        destination: `${backend}/:path*`,
+      },
+    ];
+  },
+};
+
+module.exports = nextConfig;

frontend/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "iam-earth-dev-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 7860 -H 0.0.0.0",
+    "build": "next build",
+    "start": "next start -p 7860 -H 0.0.0.0",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-label": "^2.1.0",
+    "@radix-ui/react-select": "^2.1.2",
+    "@radix-ui/react-slider": "^1.2.1",
+    "@radix-ui/react-slot": "^1.1.0",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.460.0",
+    "next": "latest",
+    "react": "latest",
+    "react-dom": "latest",
+    "react-dropzone": "^14.3.5",
+    "tailwind-merge": "^2.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^9.14.0",
+    "eslint-config-next": "latest",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.14",
+    "tailwindcss-animate": "^1.0.7",
+    "typescript": "^5.6.3"
+  }
+}

frontend/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

frontend/tailwind.config.ts

@@ -0,0 +1,46 @@
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  darkMode: ["class"],
+  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
+  theme: {
+    container: { center: true, padding: "1.5rem" },
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        muted: {
+          DEFAULT: "hsl(var(--muted))",
+          foreground: "hsl(var(--muted-foreground))",
+        },
+        accent: {
+          DEFAULT: "hsl(var(--accent))",
+          foreground: "hsl(var(--accent-foreground))",
+        },
+        destructive: {
+          DEFAULT: "hsl(var(--destructive))",
+          foreground: "hsl(var(--destructive-foreground))",
+        },
+        card: {
+          DEFAULT: "hsl(var(--card))",
+          foreground: "hsl(var(--card-foreground))",
+        },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+    },
+  },
+  plugins: [require("tailwindcss-animate")],
+};
+
+export default config;

frontend/tsconfig.json

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

start.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Launch FastAPI (internal :8000) and Next.js (public :7860) together.
+# HF Spaces sends SIGTERM on shutdown; we trap it and forward to children.
+set -euo pipefail
+
+BACKEND_PORT="${BACKEND_PORT:-8000}"
+FRONTEND_PORT="${FRONTEND_PORT:-7860}"
+
+cleanup() {
+    echo "[start.sh] caught signal, shutting down…"
+    [[ -n "${BACKEND_PID:-}" ]] && kill -TERM "$BACKEND_PID" 2>/dev/null || true
+    [[ -n "${FRONTEND_PID:-}" ]] && kill -TERM "$FRONTEND_PID" 2>/dev/null || true
+    wait || true
+    exit 0
+}
+trap cleanup SIGINT SIGTERM
+
+echo "[start.sh] launching FastAPI on :$BACKEND_PORT"
+cd /app/backend
+uv run uvicorn main:app --host 127.0.0.1 --port "$BACKEND_PORT" --workers 1 &
+BACKEND_PID=$!
+
+echo "[start.sh] launching Next.js on :$FRONTEND_PORT"
+cd /app/frontend
+HOSTNAME=0.0.0.0 PORT="$FRONTEND_PORT" npx next start -p "$FRONTEND_PORT" -H 0.0.0.0 &
+FRONTEND_PID=$!
+
+# If either process dies, exit so HF restarts the Space.
+wait -n "$BACKEND_PID" "$FRONTEND_PID"
+EXIT_CODE=$?
+echo "[start.sh] a child exited (code=$EXIT_CODE), shutting down sibling"
+cleanup

test_stream.py

@@ -0,0 +1,6 @@
+import httpx
+import time
+
+for _ in range(3):
+    print("tick")
+    time.sleep(1)

test_uvicorn_log.py

@@ -0,0 +1,14 @@
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+import time
+
+app = FastAPI()
+
+def stream():
+    for i in range(3):
+        time.sleep(1)
+        yield f"chunk {i}\n"
+
+@app.get("/")
+def get_stream():
+    return StreamingResponse(stream())