README.md

---

title: Lesson Agent

emoji: 📚 colorFrom: blue colorTo: green sdk: docker app_port: 7860 pinned: false license: apache-2.0

Lesson Agent

Backyard AI Gradio Space for the 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 for local run, Docker smoke test, and HF Space deployment.

Prerequisites

• uv
• Python 3.12

Quick start

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.

• Lesson slides — topic, grade, slide count → downloadable PowerPoint
• Research Agent — scrape/index sources into MemRAG, then ask questions offline with citations

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

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, ensemble experiments, 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.

Environment variables

Variable	Default	Description
ACTIVE_MODEL	minicpm5-1b	Preset key from models.yaml
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 and models.yaml for model presets.

Hugging Face Space deployment

1. Create a Space under build-small-hackathon with Docker SDK.
2. Link this repository (root Dockerfile + root README.md YAML above).
3. Hardware: GPU basic recommended for transformers (minicpm5-1b).
4. Optional secrets: ACTIVE_MODEL, N_GPU_LAYERS (if using GGUF preset).

docker build -t hackathon-space .
docker run --rm -p 7860:7860 -e ACTIVE_MODEL=minicpm5-1b hackathon-space

Hackathon checklist

• Track: Backyard AI — lesson slide builder for a teacher you know
• Space live under build-small-hackathon
• Demo video: real user enters topic → download .pptx → show agent trace
• Social post published
• 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)
• Well-Tuned — optional fine-tuned preset in models.yaml (Phase 2)

Agent trace upload

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.