--- 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/.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 ```