README.md

metadata

title: Educational Assistant
emoji: 🌖
colorFrom: purple
colorTo: green
sdk: docker
app_port: 7860
pinned: false

Quick start (clone for your own course)

1. Duplicate this Space on Hugging Face.
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.
   • APP_PASSWORD — strongly recommended if the Space is public/protected; default is password.
3. Optional overrides:
   • APP_USERNAME — defaults to student.
   • 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.
5. Share the root URL with your students — they land on the chat UI.

Local development

Requires Python 3.13, Node 20+, and uv.

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

# 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)

docker build -t iamearthdev .
docker run --rm -p 7860:7860 --env-file .env iamearthdev

Customizing personas

Edit 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, …