README.md

metadata

title: Tutorial Builder
emoji: 📘
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

Tutorial Builder (reusable across topics)

One Streamlit app that turns teacher-provided material into an interactive student tutorial. It replaces the need for a separate topicXquestions.qmd file or a separate Hugging Face Space per topic: every tutorial is just a JSON file in tutorials/, and the app discovers them automatically.

Adding a new topic requires no code changes — save a new JSON file (from Teacher mode, or by hand) and it shows up in Student mode.

Run locally

pip install -r requirements.txt
streamlit run app.py

Pick Student or Teacher in the sidebar.

Modes

• Teacher mode — set the title, topic number/name, paste or upload readings, and add questions with suggested answers. Save to the tutorials/ folder (and, if configured, to a Hugging Face Dataset so it survives restarts) or download the JSON. You can also load an existing tutorial (or upload a JSON) to edit it. No coding required.
• Student mode — choose a tutorial, read the intro and readings, answer each question, optionally Get AI feedback (hints, not answers), reveal the suggested answer to self-check, and download all your answers (with any AI feedback) as Markdown.

Optional features (set as Hugging Face Space Secrets)

Both are optional — the app runs without them, just with those features off.

Secret	Purpose
GROQ_API_KEY (plus optional GROQ_API_KEY_FALLBACK_1/2)	Enables the Get AI feedback button. Keys are tried in order if one is rate-limited.
HF_TOKEN (write-scoped) + HF_DATASET_REPO (e.g. your-username/ec3014-tutorials)	Persistence. Teacher saves are committed to that Dataset and pulled back on startup, so tutorials survive Space restarts.

Without HF_TOKEN/HF_DATASET_REPO, saves are written to the local tutorials/ folder only (ephemeral on Spaces) — the Download JSON button remains the durable fallback.

Data format

One JSON file per tutorial in tutorials/. Schema:

{
  "topic_number": "2",
  "topic_name": "Classical Theory of Money",
  "title": "Topic 2 Questions",
  "intro": "markdown shown above the questions",
  "readings": "markdown list of readings",
  "questions": [
    {
      "title": "Utility Maximization",
      "prompt": "markdown question text, with $LaTeX$ and $$display$$ math",
      "suggested_answer": "markdown indicative answer"
    }
  ]
}

LaTeX math is supported anywhere Markdown is rendered ($inline$, $$display$$). See tutorials/topic3-keyness-theory-of-money.json for a worked example (converted from topic3questions.qmd; the original .qmd files in the repo are left untouched).

Deploy

Deploy this single folder as one Hugging Face Space (Streamlit SDK). All topics are served from it — no per-topic Space needed.