--- title: Lesson Agent emoji: ๐Ÿ“š colorFrom: blue colorTo: green sdk: gradio sdk_version: "6.16.0" app_file: app.py python_version: "3.12" pinned: false license: apache-2.0 tags: - track:backyard - track:wood - sponsor:openbmb - sponsor:openai - sponsor:nvidia - sponsor:modal - achievement:offgrid - achievement:welltuned - achievement:offbrand - achievement:llama - achievement:sharing - achievement:fieldnotes - build-small-hackathon - backyard-ai - modal - tiny-titan - best-agent - best-demo - openbmb - sharing-is-caring - off-the-grid - off-brand - field-notes - well-tuned - llama-champion --- # Lesson Agent **Backyard AI** Gradio Space for the [Build Small Hackathon](https://huggingface.co/build-small-hackathon). A local skill-based agent helps a teacher you know turn a **topic + grade level** into a downloadable **PowerPoint** โ€” powered by a small transformers model (`MiniCPM5-1B` by default), no cloud LLM API. See **[USAGE.md](USAGE.md)** for local run, Gradio SDK / ZeroGPU Space deployment, and Docker (later). **Demo video:** [https://www.youtube.com/watch?v=bwtOiZvJ-7k](https://www.youtube.com/watch?v=bwtOiZvJ-7k) **Blog post:** [Small Models, Bounded Jobs](https://huggingface.co/blog/build-small-hackathon/lessonagent-opennotebook) โ€” Hugging Face Build Small Hackathon write-up **X post:** [https://x.com/MSG_Encrypted/status/2066570320861921748](https://x.com/MSG_Encrypted/status/2066570320861921748) **Github:** [https://github.com/MSghais/small-model-hackathon/](https://github.com/MSghais/small-model-hackathon/) ## Prerequisites - [uv](https://docs.astral.sh/uv/) - Python 3.12 ## Quick start ```bash uv sync --all-packages cp .env.example .env # optional: edit model settings # Run Gradio locally uv run --package gradio-space python -m gradio_space.app ``` Open [http://localhost:7860](http://localhost:7860). - **Lesson slides** โ€” topic, grade, slide count โ†’ downloadable PowerPoint - **Research Agent** โ€” scrape/index sources into MemRAG, then ask questions offline with citations ### Studio UI (Off Brand track) The default landing page is a **custom AI Studio workspace** at `/` โ€” not default Gradio chrome. It uses **Gradio 6 Server mode** (`gradio.Server`): Material 3 layout, sidebar + workspace (Research โ†’ Slides โ†’ Language lessons), and `@server.api` endpoints wired to the same Python backends as Classic. - **`/`** โ€” Studio UI (ingest sources, generate slides, **Language lessons** multilingual coach) - **`/classic`** โ€” full Gradio Blocks app (TeacherVoice, EchoCoach pitch analysis, settings, Chat debug) See [apps/gradio-space/README.md](apps/gradio-space/README.md) for API names and a 2-minute judge demo script. ### Modal + Fine-tuning track (Well-Tuned) Cloud GPU **train โ†’ eval โ†’ gate โ†’ publish** for a skill-matrix of QLoRA adapters on `openbmb/MiniCPM5-1B` โ€” no local CUDA required. Each job in [`research/modal/experiments.yaml`](research/modal/experiments.yaml) (math, science, coding, reasoning, teaching, โ€ฆ) fine-tunes with [`research/finetune.py`](research/finetune.py), benchmarks with `slm-lm-eval`, gates on per-skill `goals`, and publishes passing adapters to the Hub. - **Modal (partner track)** โ€” `modal run` / warm GPU worker, Volume artifacts, optional [Modal Notebook](research/notebook/minicpm5-modal-finetune.ipynb) - **Well-Tuned badge** โ€” before/after lm-eval per skill + gated Hub publish (`MSGEncrypted/minicpm5-1b--lora`) Full runbook: [`research/modal/README.md`](research/modal/README.md) ยท agent loop: [`research/modal/SERVER.md`](research/modal/SERVER.md) ยท local research overview: [`research/USAGE.md`](research/USAGE.md) ```bash uv sync --group modal modal setup && modal secret create huggingface HF_TOKEN= modal run research/modal/server_app.py --ping # health check modal run research/modal/server_app.py --job math-lora --max-steps 20 --no-publish # cheap smoke modal run research/modal/server_app.py --pipeline # full sweep: baselines โ†’ train โ†’ eval โ†’ gate โ†’ publish ``` Pull a passing adapter into the Space: `modal volume get slm-finetune math-lora ./models/finetuned/minicpm5-1b-lora`, then set `ACTIVE_MODEL=minicpm5-1b-lesson-lora`. ### Llama track (Llama Champion + Off-the-Grid) The same OpenBMB **MiniCPM-V 4.6** model runs on **llama.cpp** via the [`minicpm-v-4.6-gguf`](models.yaml) preset โ€” GGUF weights from [`openbmb/MiniCPM-V-4.6-gguf`](https://huggingface.co/openbmb/MiniCPM-V-4.6-gguf) (~529 MB Q4_K_M). No cloud LLM API; inference stays fully local through [`libs/inference/src/inference/llama_cpp.py`](libs/inference/src/inference/llama_cpp.py). | Preset | Backend | Use case | | ------ | ------- | -------- | | `minicpm-v-4.6` | transformers | Full VLM (image/video) via Hugging Face | | `minicpm-v-4.6-gguf` | llama.cpp | **Llama Champion** badge; text on all tabs today | **Space (judges):** pin the GGUF preset โ€” no runtime switching for visitors. ```bash ACTIVE_MODEL=minicpm-v-4.6-gguf ALLOW_MODEL_SWITCH=false ``` **Local dev:** switch backends at runtime without restarting. ```bash ALLOW_MODEL_SWITCH=true ACTIVE_MODEL=minicpm-v-4.6 # transformers startup default # Settings or Chat โ†’ select minicpm-v-4.6-gguf for llama.cpp ``` Prefetch weights (optional): ```bash uv run python scripts/download_model.py --preset minicpm-v-4.6-gguf ``` See [USAGE.md](USAGE.md) (section *Switching models locally*) for Classic and Studio UI details. ## How it works 1. **Skill** โ€” `skills/education-pptx/SKILL.md` (Hermes / agentskills.io format) 2. **LLM** โ€” local model drafts a JSON slide outline 3. **Tool** โ€” `create_pptx` builds the file with `python-pptx` 4. **Trace** โ€” JSON log saved under `outputs/traces/` for the Sharing is Caring badge ```text apps/gradio-space/ # Gradio tabs (Lesson slides, Research Agent, Chat debug) libs/agent/ # Skill agent runner, tools, trace recorder libs/researchmind/ # Scraper, chunk/embed, MemRAG SQLite store, retrieval libs/inference/ # Transformers + llama.cpp backends skills/ # SKILL.md + references/ + scripts/ per task research/ # Fine-tune and agentic evals (optional) ``` ### ResearchMind (offline after ingest) 1. **Skills** โ€” `skills/scrape-web`, `scrape-pdf`, `extract-content`, `research-mind` 2. **Ingest** โ€” URL/PDF/DOCX or topic โ†’ (optional LLM URL suggest + confirm, or auto search) โ†’ chunk + embed โ†’ SQLite 3. **Q&A** โ€” local model + retrieved chunks with `[n]` citations (no network at chat time) 4. **Memory** โ€” persists under `RESEARCHMIND_DATA_DIR` (default `outputs/researchmind`) Optional research tooling (not required for the Space): see [research/USAGE.md](research/USAGE.md). ## Environment variables | Variable | Default | Description | | -------- | ------- | ----------- | | `ACTIVE_MODEL` | `minicpm5-1b` | Preset key from `models.yaml` (use `minicpm-v-4.6-gguf` for Llama track) | | `ALLOW_MODEL_SWITCH` | `false` | Set `true` locally to switch presets in Settings / Chat | | `AGENT_OUTPUTS_DIR` | `/tmp/agent_outputs` | Generated `.pptx` files | | `AGENT_TRACES_DIR` | `outputs/traces` | Agent trace JSON | | `SKILLS_DIR` | `./skills` | Skill definitions root | | `RESEARCHMIND_DATA_DIR` | `outputs/researchmind` | MemRAG DB and raw snapshots | | `RESEARCHMIND_EMBED_MODEL` | `all-MiniLM-L6-v2` | Sentence embedding model | | `RESEARCHMIND_AUTO_SEARCH` | `false` | Default auto DuckDuckGo ingest | See [`.env.example`](.env.example) and [`models.yaml`](models.yaml) for model presets. ## Hugging Face Space deployment 1. Create a Space under [build-small-hackathon](https://huggingface.co/build-small-hackathon) with **Gradio** SDK (Blank template). 2. Link this repository โ€” HF builds from root `app.py` + `requirements.txt` (README YAML above). 3. Hardware: **ZeroGPU** for burst GPU inference, or **GPU basic** for always-on GPU. 4. Set `ACTIVE_MODEL=minicpm5-1b` (or `minicpm-v-4.6-gguf` for [Llama track](#llama-track-llama-champion--off-the-grid)), `ALLOW_MODEL_SWITCH=false`, `RESEARCHMIND_DATA_DIR=/tmp/researchmind`. A root `Dockerfile` is kept for a later **Docker SDK** deploy (flip README to `sdk: docker`). See [USAGE.md](USAGE.md). ## Hackathon tracks & checklist | Track | What we ship | | ----- | ------------ | | **Backyard AI** (primary) | Lesson slide builder for a teacher you know โ€” topic + grade โ†’ downloadable `.pptx` | | **Off Brand** | Custom Studio UI at `/` (Gradio 6 Server mode, not default Gradio chrome) | | **Modal** (partner) | GPU `train โ†’ eval โ†’ gate โ†’ publish` on [Modal](https://modal.com) โ€” [`research/modal/`](research/modal/) | | **Well-Tuned** (finetuning) | Skill-matrix QLoRA adapters on MiniCPM5-1B, lm-eval gates, Hub publish | | **Llama Champion** | `minicpm-v-4.6-gguf` on llama.cpp โ€” same OpenBMB VLM family, local GGUF inference | - Space live under build-small-hackathon - Demo video: [YouTube](https://www.youtube.com/watch?v=bwtOiZvJ-7k) โ€” real user enters topic โ†’ download `.pptx` โ†’ show agent trace - Blog post: [Small Models, Bounded Jobs](https://huggingface.co/blog/build-small-hackathon/lessonagent-opennotebook) - Social post published: [X](https://x.com/MSG_Encrypted/status/2066570320861921748) - Submission by **June 15, 2026** ### Badge targets - **Best Agent** โ€” skill loop + `create_pptx` tool - **Tiny Titan** โ€” MiniCPM5 1B (โ‰ค4B) - **OpenBMB** โ€” `openbmb/MiniCPM5-1B` - **Sharing is Caring** โ€” upload traces with `scripts/upload_trace.py` - **Off-the-Grid** โ€” local inference only (no cloud LLM API) - **Llama Champion** โ€” llama.cpp backend with [`openbmb/MiniCPM-V-4.6-gguf`](https://huggingface.co/openbmb/MiniCPM-V-4.6-gguf); see [Llama track](#llama-track-llama-champion--off-the-grid) - **Well-Tuned** โ€” per-skill QLoRA adapters trained + gated + published via the [Modal + Fine-tuning track](#modal--fine-tuning-track-well-tuned) - **Modal** โ€” same pipeline; see [`research/modal/README.md`](research/modal/README.md) ## Agent trace upload ```bash uv run python scripts/upload_trace.py --repo-id YOUR_USER/build-small-agent-traces ``` ## Demo video script 1. Introduce the teacher and the problem (building a 5-slide lesson takes 30+ minutes). 2. Open **Lesson slides**, enter topic + grade, click **Generate**. 3. Show outline preview and download the `.pptx`. 4. Expand the agent trace JSON โ€” local model, no cloud API.