microtestfrombook / README.md
Rajarshi255's picture
Upload README.md
2732a07 verified
|
Raw History Blame Contribute Delete
4.02 kB
---
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
```