Spaces:
Sleeping
Sleeping
Upload README.md
Browse files
README.md
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
title: Singerkone Quiz
|
| 3 |
+
emoji: π
|
| 4 |
+
colorFrom: yellow
|
| 5 |
+
colorTo: blue
|
| 6 |
+
sdk: gradio
|
| 7 |
+
sdk_version: 5.49.1
|
| 8 |
+
app_file: app.py
|
| 9 |
+
pinned: false
|
| 10 |
+
---
|
| 11 |
+
|
| 12 |
+
# Singerkone Quiz App
|
| 13 |
+
|
| 14 |
+
Pick a book, pick page range, get an MCQ quiz from Gemini, earn stars in the Star Bank.
|
| 15 |
+
|
| 16 |
+
---
|
| 17 |
+
|
| 18 |
+
## DEPLOYMENT β DO THIS ONCE
|
| 19 |
+
|
| 20 |
+
### Step 1 β Create the Google Sheet
|
| 21 |
+
1. Go to Google Sheets, create a new sheet named **exactly**: `MicroTest_star_App`
|
| 22 |
+
2. (The app will auto-create a `QuizLog` worksheet on first write β you don't need to add columns manually.)
|
| 23 |
+
|
| 24 |
+
### Step 2 β Create a Google Service Account
|
| 25 |
+
This is what lets the app write to your Sheet without you logging in.
|
| 26 |
+
|
| 27 |
+
1. Go to https://console.cloud.google.com/
|
| 28 |
+
2. Create a new project (or use an existing one) β call it `singerkone-quiz`
|
| 29 |
+
3. Enable two APIs: **Google Sheets API** and **Google Drive API**
|
| 30 |
+
4. Go to "IAM & Admin" β "Service Accounts" β "Create Service Account"
|
| 31 |
+
5. Give it any name (e.g. `quiz-bot`), skip role assignment, click Done
|
| 32 |
+
6. Click on the new service account β "Keys" tab β "Add Key" β "Create new key" β JSON β Download
|
| 33 |
+
7. You now have a JSON file. **Keep it safe.**
|
| 34 |
+
8. Open the JSON file β find the `client_email` (looks like `quiz-bot@singerkone-quiz.iam.gserviceaccount.com`)
|
| 35 |
+
9. **Share your Google Sheet** with that email address, give it Editor access
|
| 36 |
+
|
| 37 |
+
### Step 3 β Get a Gemini API key
|
| 38 |
+
1. Go to https://aistudio.google.com/apikey
|
| 39 |
+
2. Click "Create API Key" β copy the key
|
| 40 |
+
3. Free tier: 1500 requests/day β far more than Singerkone will need
|
| 41 |
+
|
| 42 |
+
### Step 4 β Create the HF Space
|
| 43 |
+
1. Go to https://huggingface.co/new-space
|
| 44 |
+
2. Name: `singerkone-quiz` (or anything)
|
| 45 |
+
3. SDK: **Gradio**
|
| 46 |
+
4. Hardware: **CPU basic (free)**
|
| 47 |
+
5. Create
|
| 48 |
+
|
| 49 |
+
### Step 5 β Add secrets to the Space
|
| 50 |
+
1. In the Space, go to Settings β Variables and secrets β New secret
|
| 51 |
+
2. Add `GEMINI_API_KEY` = (paste the Gemini key)
|
| 52 |
+
3. Add `GOOGLE_SERVICE_ACCOUNT_JSON` = (paste the **entire contents** of the JSON file from Step 2)
|
| 53 |
+
|
| 54 |
+
### Step 6 β Upload files
|
| 55 |
+
Upload to the Space repo:
|
| 56 |
+
- `app.py`
|
| 57 |
+
- `requirements.txt`
|
| 58 |
+
- A folder called `books/` containing:
|
| 59 |
+
- `books/class6/amader_prithibi.pdf`
|
| 60 |
+
- `books/class6/<other_books>.pdf`
|
| 61 |
+
- (Add `books/class5/`, `books/class7/` etc. later β same pattern)
|
| 62 |
+
|
| 63 |
+
**Naming convention:** lowercase filenames with underscores. The app shows them as Title Case in the UI.
|
| 64 |
+
|
| 65 |
+
### Step 7 β Test
|
| 66 |
+
Open the Space URL. Try a quiz with pages 5-7 of Amader Prithibi. If MCQs appear and Sheet updates, you're done.
|
| 67 |
+
|
| 68 |
+
---
|
| 69 |
+
|
| 70 |
+
## Adding more books later
|
| 71 |
+
|
| 72 |
+
Just upload new PDFs to the right folder. No code changes. The dropdown refreshes from the file system.
|
| 73 |
+
|
| 74 |
+
If you want to add a new class: create `books/class7/` (or whatever) and drop PDFs in.
|
| 75 |
+
|
| 76 |
+
---
|
| 77 |
+
|
| 78 |
+
## Cost expectations
|
| 79 |
+
|
| 80 |
+
Gemini 2.5 Flash-Lite: ~$0.0003 per quiz (5 pages Γ 1 quiz).
|
| 81 |
+
At 100 quizzes/week from Singerkone: under βΉ3/month.
|
| 82 |
+
You will likely stay inside the free tier (1500 requests/day) indefinitely.
|
| 83 |
+
|
| 84 |
+
---
|
| 85 |
+
|
| 86 |
+
## Known limits and gotchas
|
| 87 |
+
|
| 88 |
+
- HF Space free tier sleeps after 48 hours of inactivity. First kid to use it after a long gap waits ~30 seconds for cold start. After that, fast for everyone.
|
| 89 |
+
- Page rendering is on-demand. A 10-page quiz takes ~5β10 seconds end to end (rendering + Gemini call).
|
| 90 |
+
- The 1 GB Space limit fits ~70β100 textbooks at typical PDF sizes. You're nowhere near this.
|
| 91 |
+
- If a PDF has copy-disabled protection (like WBBSE textbooks), rendering still works β we render the visual page, not extract text.
|
| 92 |
+
- If Gemini returns malformed JSON, the quiz fails with a clear error message. Refresh and try again.
|
| 93 |
+
- Star formula: 100% β 5 stars, 80% β 4, 60% β 3, 40% β 2, 20% β 1, below 20% β 0. Change `STARS_FORMULA` in app.py to adjust.
|
| 94 |
+
|
| 95 |
+
---
|
| 96 |
+
|
| 97 |
+
## File layout in the Space
|
| 98 |
+
|
| 99 |
+
```
|
| 100 |
+
/
|
| 101 |
+
βββ app.py
|
| 102 |
+
βββ requirements.txt
|
| 103 |
+
βββ README.md (this file)
|
| 104 |
+
βββ books/
|
| 105 |
+
βββ class5/
|
| 106 |
+
β βββ *.pdf
|
| 107 |
+
βββ class6/
|
| 108 |
+
β βββ amader_prithibi.pdf
|
| 109 |
+
β βββ *.pdf
|
| 110 |
+
βββ class7/
|
| 111 |
+
βββ *.pdf
|
| 112 |
+
```
|