Spaces:
Sleeping
Sleeping
| 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, … | |
| ``` | |