File size: 4,016 Bytes
2732a07
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
---
title: Singerkone Quiz
emoji: πŸ“š
colorFrom: yellow
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
---

# Singerkone Quiz App

Pick a book, pick page range, get an MCQ quiz from Gemini, earn stars in the Star Bank.

---

## DEPLOYMENT β€” DO THIS ONCE

### Step 1 β€” Create the Google Sheet
1. Go to Google Sheets, create a new sheet named **exactly**: `MicroTest_star_App`
2. (The app will auto-create a `QuizLog` worksheet on first write β€” you don't need to add columns manually.)

### Step 2 β€” Create a Google Service Account
This is what lets the app write to your Sheet without you logging in.

1. Go to https://console.cloud.google.com/
2. Create a new project (or use an existing one) β€” call it `singerkone-quiz`
3. Enable two APIs: **Google Sheets API** and **Google Drive API**
4. Go to "IAM & Admin" β†’ "Service Accounts" β†’ "Create Service Account"
5. Give it any name (e.g. `quiz-bot`), skip role assignment, click Done
6. Click on the new service account β†’ "Keys" tab β†’ "Add Key" β†’ "Create new key" β†’ JSON β†’ Download
7. You now have a JSON file. **Keep it safe.**
8. Open the JSON file β€” find the `client_email` (looks like `quiz-bot@singerkone-quiz.iam.gserviceaccount.com`)
9. **Share your Google Sheet** with that email address, give it Editor access

### Step 3 β€” Get a Gemini API key
1. Go to https://aistudio.google.com/apikey
2. Click "Create API Key" β†’ copy the key
3. Free tier: 1500 requests/day β€” far more than Singerkone will need

### Step 4 β€” Create the HF Space
1. Go to https://huggingface.co/new-space
2. Name: `singerkone-quiz` (or anything)
3. SDK: **Gradio**
4. Hardware: **CPU basic (free)**
5. Create

### Step 5 β€” Add secrets to the Space
1. In the Space, go to Settings β†’ Variables and secrets β†’ New secret
2. Add `GEMINI_API_KEY` = (paste the Gemini key)
3. Add `GOOGLE_SERVICE_ACCOUNT_JSON` = (paste the **entire contents** of the JSON file from Step 2)

### Step 6 β€” Upload files
Upload to the Space repo:
- `app.py`
- `requirements.txt`
- A folder called `books/` containing:
  - `books/class6/amader_prithibi.pdf`
  - `books/class6/<other_books>.pdf`
  - (Add `books/class5/`, `books/class7/` etc. later β€” same pattern)

**Naming convention:** lowercase filenames with underscores. The app shows them as Title Case in the UI.

### Step 7 β€” Test
Open the Space URL. Try a quiz with pages 5-7 of Amader Prithibi. If MCQs appear and Sheet updates, you're done.

---

## Adding more books later

Just upload new PDFs to the right folder. No code changes. The dropdown refreshes from the file system.

If you want to add a new class: create `books/class7/` (or whatever) and drop PDFs in.

---

## Cost expectations

Gemini 2.5 Flash-Lite: ~$0.0003 per quiz (5 pages Γ— 1 quiz).
At 100 quizzes/week from Singerkone: under β‚Ή3/month.
You will likely stay inside the free tier (1500 requests/day) indefinitely.

---

## Known limits and gotchas

- 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.
- Page rendering is on-demand. A 10-page quiz takes ~5–10 seconds end to end (rendering + Gemini call).
- The 1 GB Space limit fits ~70–100 textbooks at typical PDF sizes. You're nowhere near this.
- If a PDF has copy-disabled protection (like WBBSE textbooks), rendering still works β€” we render the visual page, not extract text.
- If Gemini returns malformed JSON, the quiz fails with a clear error message. Refresh and try again.
- Star formula: 100% β†’ 5 stars, 80% β†’ 4, 60% β†’ 3, 40% β†’ 2, 20% β†’ 1, below 20% β†’ 0. Change `STARS_FORMULA` in app.py to adjust.

---

## File layout in the Space

```
/
β”œβ”€β”€ app.py
β”œβ”€β”€ requirements.txt
β”œβ”€β”€ README.md (this file)
└── books/
    β”œβ”€β”€ class5/
    β”‚   └── *.pdf
    β”œβ”€β”€ class6/
    β”‚   β”œβ”€β”€ amader_prithibi.pdf
    β”‚   └── *.pdf
    └── class7/
        └── *.pdf
```