Hugging Face's logo

Spaces:
LeedsLibraries
/
Luminaria
Sleeping

App Files Community
Luminaria
File size: 3,030 Bytes
af24c4f
 
 
 
 
 
4b81334
af24c4f
 
 
4b81334
 
 
6be14c8
 
6230227
6be14c8
6230227
6be14c8
 
5bd66e6
 
 
 
4b81334
 
 
 
 
 
 
 
 
6be14c8
4b81334
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
---
title: IamEarthDev
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 `deepseek-ai/DeepSeek-V4-Flash`.
   - *(optional)* `LLM_PROVIDER` — defaults to Hugging Face auto-routing; set this only if you want to force a provider such as `deepinfra`.
   - *(optional)* `LLM_MAX_TOKENS` — defaults to `8192`.
   - *(optional)* `LLM_FINAL_ANSWER_MAX_TOKENS` — defaults to `8192`.
   - *(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, …
```