Rajarshi255 commited on
Commit
2732a07
Β·
verified Β·
1 Parent(s): 29776fe

Upload README.md

Browse files
Files changed (1) hide show
  1. README.md +112 -0
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
+ ```