---
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`](https://docs.astral.sh/uv/).

```bash
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)

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

## Customizing personas

Edit [`frontend/lib/personas.ts`](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, …
```