feat: add default env vars

.env.example

@@ -2,12 +2,13 @@
 # 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
+# ---- Optional overrides ----
+# Defaults to "<SPACE_ID>-corpus" on Hugging Face Spaces, or "iam-earth-dev-corpus" locally.
+# DATASET_ID=your-username/iam-earth-dev-corpus
+
+# Default admin passcode is "password"; override this for real deployments.
+# ADMIN_PASSCODE=change-me
 
-# ---- 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
 
@@ -15,10 +16,7 @@ EMBED_MODEL=BAAI/bge-small-en-v1.5
 # 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
+BACKEND_INTERNAL_URL=http://127.0.0.1:8000
 FRONTEND_PORT=7860

Dockerfile

@@ -52,6 +52,7 @@ ENV HF_HOME=/app/.cache \
     LANCEDB_PATH=/app/.lancedb \
     TMP_UPLOAD_DIR=/app/.tmp_uploads \
     BACKEND_PORT=8000 \
+    BACKEND_INTERNAL_URL=http://127.0.0.1:8000 \
     FRONTEND_PORT=7860 \
     NEXT_TELEMETRY_DISABLED=1 \
     PYTHONUNBUFFERED=1

README.md

@@ -11,11 +11,11 @@ pinned: false
 ## 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`.
+2. In your Space → **Settings → Variables and secrets**, add:
+   - `HF_TOKEN` — required; use a token with write access so the app can create/sync the dataset.
+3. Optional overrides:
+   - `DATASET_ID` — defaults to `<SPACE_ID>-corpus` on Spaces and is created automatically when needed.
+   - `ADMIN_PASSCODE` — defaults to `password`; set this for real deployments.
    - *(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.
@@ -26,7 +26,7 @@ pinned: false
 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
+cp .env.example .env   # fill in HF_TOKEN; other values have defaults
 
 # Backend
 cd backend && uv sync && uv run uvicorn main:app --port 8000 --reload

backend/auth.py

@@ -5,12 +5,12 @@ 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", "")
+from config import ADMIN_PASSCODE
+
 COOKIE_NAME = "admin_session"
 
 

backend/config.py

@@ -0,0 +1,58 @@
+"""Runtime configuration defaults.
+
+Only HF_TOKEN is intentionally left without a default because chat, embeddings,
+and dataset writes need a Hugging Face token in deployed Spaces.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).parent.parent
+
+
+def _default_dataset_id() -> str:
+    space_id = os.environ.get("SPACE_ID") or os.environ.get("HF_SPACE_ID")
+    if space_id and "/" in space_id:
+        return f"{space_id}-corpus"
+    return "iam-earth-dev-corpus"
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.lower() in {"1", "true", "yes", "on"}
+
+
+HF_TOKEN = os.environ.get("HF_TOKEN")
+DATASET_ID = os.environ.get("DATASET_ID") or _default_dataset_id()
+ADMIN_PASSCODE = os.environ.get("ADMIN_PASSCODE", "password")
+
+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")
+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 = _env_bool("SHOW_LLM_REASONING", False)
+
+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"))
+
+BACKEND_PORT = os.environ.get("BACKEND_PORT", "8000")
+FRONTEND_PORT = os.environ.get("FRONTEND_PORT", "7860")
+BACKEND_INTERNAL_URL = os.environ.get("BACKEND_INTERNAL_URL", f"http://127.0.0.1:{BACKEND_PORT}")
+
+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")))
+LANCEDB_PATH = str(LANCEDB_DIR)
+

backend/hf_sync.py

@@ -13,7 +13,6 @@ from __future__ import annotations
 
 import json
 import logging
-import os
 from pathlib import Path
 import shutil
 from tempfile import TemporaryDirectory
@@ -22,10 +21,10 @@ from typing import List
 from huggingface_hub import HfApi, hf_hub_download
 from huggingface_hub.utils import EntryNotFoundError, RepositoryNotFoundError
 
+from config import DATASET_ID, HF_TOKEN
+
 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/"

backend/main.py

@@ -27,6 +27,7 @@ from pydantic import BaseModel, Field
 
 # Local (imported AFTER load_dotenv so their module-level env reads are correct)
 import auth
+import config
 import hf_sync
 import personas_store
 from rag import RagEngine
@@ -34,23 +35,17 @@ 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"))
+TMP_UPLOAD_DIR = config.TMP_UPLOAD_DIR
+LANCEDB_DIR = config.LANCEDB_DIR
+LLM_MODEL = config.LLM_MODEL
+LLM_MODEL_LOWER = config.LLM_MODEL_LOWER
+EMBED_MODEL = config.EMBED_MODEL
+HF_TOKEN = config.HF_TOKEN
+LLM_EXTRA_BODY_JSON = config.LLM_EXTRA_BODY_JSON
+LLM_FINAL_ANSWER_EXTRA_BODY_JSON = config.LLM_FINAL_ANSWER_EXTRA_BODY_JSON
+SHOW_LLM_REASONING = config.SHOW_LLM_REASONING
+LLM_MAX_TOKENS = config.LLM_MAX_TOKENS
+LLM_FINAL_ANSWER_MAX_TOKENS = config.LLM_FINAL_ANSWER_MAX_TOKENS
 
 # Globals populated in lifespan.
 rag: Optional[RagEngine] = None
@@ -231,6 +226,10 @@ async def health() -> dict:
     return {
         "ok": True,
         "model": LLM_MODEL,
+        "embed_model": EMBED_MODEL,
+        "dataset_id": config.DATASET_ID,
+        "admin_passcode_defaulted": config.ADMIN_PASSCODE == "password" and "ADMIN_PASSCODE" not in os.environ,
+        "hf_token_configured": bool(HF_TOKEN),
         "chat_extra_body": CHAT_EXTRA_BODY,
         "final_answer_extra_body": FINAL_ANSWER_EXTRA_BODY,
         "show_reasoning": SHOW_LLM_REASONING,

backend/personas_store.py

@@ -10,11 +10,12 @@ from __future__ import annotations
 
 import json
 import logging
-import os
 from pathlib import Path
 from threading import Lock
 from typing import List
 
+from config import DATASET_ID, HF_TOKEN
+
 logger = logging.getLogger(__name__)
 
 _BUNDLED = Path(__file__).parent / "personas.json"
@@ -36,18 +37,16 @@ def load() -> None:
     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:
+    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_id=DATASET_ID,
                 repo_type="dataset",
                 filename=_DATASET_FILENAME,
-                token=hf_token,
+                token=HF_TOKEN,
             )
             data = json.loads(Path(local).read_text("utf-8"))
             with _lock:
@@ -83,17 +82,15 @@ def save(new_personas: List[dict]) -> List[dict]:
         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:
+    if HF_TOKEN and DATASET_ID:
         try:
             from huggingface_hub import HfApi
 
-            api = HfApi(token=hf_token)
+            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_id=DATASET_ID,
                 repo_type="dataset",
                 commit_message="Update personas",
             )

backend/rag.py

@@ -9,7 +9,6 @@ Designed for HF Spaces Free CPU Basic:
 from __future__ import annotations
 
 import logging
-import os
 from pathlib import Path
 from threading import Lock
 from typing import Iterable, List, Optional
@@ -20,15 +19,12 @@ 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 config import EMBED_MODEL, HF_TOKEN, LANCEDB_PATH
 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"

frontend/app/api/chat/route.ts

@@ -1,25 +1,45 @@
 import { type NextRequest, NextResponse } from "next/server";
+import { backendUrl } from "@/lib/backend-url";
 
 export const dynamic = "force-dynamic";
 export const runtime = "nodejs";
 
+const BACKEND_RETRY_ATTEMPTS = 20;
+const BACKEND_RETRY_DELAY_MS = 500;
+
+function delay(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 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 {
+  const backend = backendUrl();
+  const body = await request.text();
+
+  let response: Response | undefined;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      response = await fetch(`${backend}/chat`, {
+        method: "POST",
+        body,
+        headers: {
+          "content-type": request.headers.get("content-type") ?? "application/json",
+        },
+      });
+      break;
+    } catch {
+      if (attempt >= BACKEND_RETRY_ATTEMPTS) {
+        return NextResponse.json(
+          { detail: `Could not reach the backend chat service at ${backend}.` },
+          { status: 502 }
+        );
+      }
+      await delay(BACKEND_RETRY_DELAY_MS);
+    }
+  }
+
+  if (!response) {
     return NextResponse.json(
-      { detail: "Could not reach the backend chat service." },
+      { detail: `Could not reach the backend chat service at ${backend}.` },
       { status: 502 }
     );
   }

frontend/app/api/upload/route.ts

@@ -1,4 +1,5 @@
 import { type NextRequest, NextResponse } from "next/server";
+import { backendUrl } from "@/lib/backend-url";
 
 // 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
@@ -7,8 +8,7 @@ import { type NextRequest, NextResponse } from "next/server";
 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 backend = backendUrl();
 
   const formData = await request.formData();
   const cookie = request.headers.get("cookie") ?? "";

frontend/lib/backend-url.ts

@@ -0,0 +1,5 @@
+export function backendUrl() {
+  const port = process.env.BACKEND_PORT ?? "8000";
+  return (process.env.BACKEND_INTERNAL_URL ?? `http://127.0.0.1:${port}`).replace(/\/$/, "");
+}
+

frontend/next.config.js

@@ -9,7 +9,8 @@ const nextConfig = {
     serverActions: { bodySizeLimit: "100mb" },
   },
   async rewrites() {
-    const backend = process.env.BACKEND_INTERNAL_URL || "http://127.0.0.1:8000";
+    const backend =
+      process.env.BACKEND_INTERNAL_URL || `http://127.0.0.1:${process.env.BACKEND_PORT || "8000"}`;
     return [
       {
         source: "/api/:path*",

start.sh

@@ -5,6 +5,8 @@ set -euo pipefail
 
 BACKEND_PORT="${BACKEND_PORT:-8000}"
 FRONTEND_PORT="${FRONTEND_PORT:-7860}"
+BACKEND_INTERNAL_URL="${BACKEND_INTERNAL_URL:-http://127.0.0.1:${BACKEND_PORT}}"
+export BACKEND_PORT FRONTEND_PORT BACKEND_INTERNAL_URL
 
 cleanup() {
     echo "[start.sh] caught signal, shutting down…"
@@ -20,6 +22,24 @@ cd /app/backend
 uv run uvicorn main:app --host 127.0.0.1 --port "$BACKEND_PORT" --workers 1 &
 BACKEND_PID=$!
 
+echo "[start.sh] waiting for FastAPI health check at $BACKEND_INTERNAL_URL/health"
+for _ in $(seq 1 120); do
+    if curl -fsS "$BACKEND_INTERNAL_URL/health" >/dev/null 2>&1; then
+        echo "[start.sh] FastAPI is ready"
+        break
+    fi
+    if ! kill -0 "$BACKEND_PID" 2>/dev/null; then
+        wait "$BACKEND_PID" || true
+        echo "[start.sh] FastAPI exited before becoming ready"
+        cleanup
+    fi
+    sleep 1
+done
+if ! curl -fsS "$BACKEND_INTERNAL_URL/health" >/dev/null 2>&1; then
+    echo "[start.sh] FastAPI did not become ready in time"
+    cleanup
+fi
+
 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 &