sultan-hassan commited on
Commit
b8f7be2
·
verified ·
1 Parent(s): 6872877

Upload 3 files

Browse files
Files changed (3) hide show
  1. README.md +56 -5
  2. app.py +35 -2
  3. requirements.txt +3 -0
README.md CHANGED
@@ -1,13 +1,64 @@
1
  ---
2
  title: Homework Hero
3
- emoji: 🏃
4
- colorFrom: purple
5
- colorTo: gray
6
  sdk: gradio
7
  sdk_version: 6.30.0
8
- python_version: '3.12'
9
  app_file: app.py
10
  pinned: false
 
 
11
  ---
12
 
13
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
  title: Homework Hero
3
+ emoji: 🦸
4
+ colorFrom: indigo
5
+ colorTo: yellow
6
  sdk: gradio
7
  sdk_version: 6.30.0
 
8
  app_file: app.py
9
  pinned: false
10
+ license: apache-2.0
11
+ short_description: One homework question at a time, for kids with ADHD
12
  ---
13
 
14
+ # Homework Hero
15
+
16
+ Hold a worksheet up to the camera and Homework Hero turns it into a game with one question at a time. Built for kids with ADHD, who often freeze when they see a full page of problems.
17
+
18
+ Gemma 4 reads the worksheet, checks answers, and gives hints that never reveal the answer. A gentle time bar, a progress path, "save for later," and a movement break every 3 questions keep kids moving. Hints and cheers can be in English, Spanish, Amharic, or French. No accounts, and no photos are saved.
19
+
20
+ ## How it connects to Gemma 4
21
+
22
+ The app tries these in order and moves to the next one if a step fails:
23
+
24
+ 1. **Hugging Face Inference Providers** (`google/gemma-4-31B-it`), when the `HF_TOKEN` secret is set. Free accounts get a small monthly credit; when it runs out, the app moves on.
25
+ 2. **Ollama** on your own computer (`gemma4:e4b`), when it's running.
26
+ 3. **Demo mode** with `sample_worksheet.png`, so the screens always work.
27
+
28
+ ## Deploy on Hugging Face Spaces
29
+
30
+ 1. Create a new Space with the Gradio SDK and upload these files.
31
+ 2. Create a token at huggingface.co/settings/tokens with "Make calls to Inference Providers" turned on.
32
+ 3. In the Space, open Settings, then Variables and secrets, and add a secret named `HF_TOKEN` with that token.
33
+
34
+ ## Run on your laptop
35
+
36
+ ```
37
+ pip install -r requirements.txt
38
+ ollama pull gemma4:e4b # optional, for offline use
39
+ python app.py
40
+ ```
41
+
42
+ Open http://127.0.0.1:7860. To use the Hugging Face API locally, run `HF_TOKEN=your_token python app.py`.
43
+
44
+ ## Settings
45
+
46
+ | Variable | Default | What it does |
47
+ |---|---|---|
48
+ | `HF_TOKEN` | not set | Turns on the Hugging Face API |
49
+ | `HF_MODEL` | `google/gemma-4-31B-it` | Which Gemma 4 model to call on Hugging Face |
50
+ | `HERO_MODEL` | `gemma4:e4b` | Which Ollama model to use |
51
+ | `OLLAMA_URL` | `http://localhost:11434` | Where Ollama is running |
52
+ | `HERO_DEMO` | `0` | Set to `1` to skip Gemma and use the sample worksheet |
53
+
54
+ ## Next steps
55
+
56
+ - Voice answers using Gemma 4's audio input
57
+ - Read each question aloud
58
+ - A parent view with the session summary
59
+
60
+ Homework Hero supports focus and routines. It is not a medical tool or treatment for ADHD.
61
+
62
+ ## License
63
+
64
+ Apache 2.0
app.py CHANGED
@@ -40,6 +40,34 @@ SAMPLE = os.path.join(HERE, "sample_worksheet.png")
40
 
41
  LANGUAGES = ["English", "Spanish", "Amharic", "French"]
42
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
43
  BREAKS = [
44
  ("Jumping jacks!", "Stand up and do 5 jumping jacks."),
45
  ("Stretch like a cat", "Reach up high, then touch your toes. Do it 3 times."),
@@ -424,7 +452,12 @@ HEAD = (
424
 
425
  THEME = gr.themes.Soft(primary_hue="indigo", radius_size="lg")
426
 
427
- with gr.Blocks(title="Homework Hero") as demo:
 
 
 
 
 
428
  state = gr.State({})
429
 
430
  gr.HTML('<div class="hh-title"><h1>Homework Hero</h1>'
@@ -481,4 +514,4 @@ if __name__ == "__main__":
481
  names = {"hf": f"Hugging Face ({HF_MODEL})", "ollama": f"Ollama ({MODEL})"}
482
  found = available_backends()
483
  print("Homework Hero backends:", ", ".join(names[b] for b in found) or "demo mode only")
484
- demo.launch(theme=THEME, css=CSS, head=HEAD)
 
40
 
41
  LANGUAGES = ["English", "Spanish", "Amharic", "French"]
42
 
43
+
44
+ def make_sample_worksheet(path: str):
45
+ """Draw the demo worksheet so the app works even if the PNG wasn't uploaded."""
46
+ from PIL import ImageDraw, ImageFont
47
+ try:
48
+ big, small = ImageFont.load_default(size=52), ImageFont.load_default(size=38)
49
+ except TypeError: # very old Pillow
50
+ big = small = ImageFont.load_default()
51
+ img = Image.new("RGB", (1240, 1600), "white")
52
+ d = ImageDraw.Draw(img)
53
+ d.text((80, 70), "Math Practice - Week 6", font=big, fill="black")
54
+ d.text((80, 160), "Name: ________________ Date: ________", font=small, fill="black")
55
+ d.text((80, 240), "Solve each problem. Show your work.", font=small, fill="black")
56
+ probs = ["7 + 5 =", "14 - 6 =", "3 x 4 =", "9 + 8 =", "20 - 7 =", "6 x 2 =", "15 + 6 =", "18 / 3 ="]
57
+ for i, p in enumerate(probs):
58
+ d.text((80 + (i % 2) * 560, 340 + (i // 2) * 190), f"{i + 1}. {p} ______", font=small, fill="black")
59
+ d.text((80, 1130), "9. Maya has 12 stickers. She gives 4 to her", font=small, fill="black")
60
+ d.text((80, 1185), " brother. How many stickers does she have left?", font=small, fill="black")
61
+ d.text((80, 1350), '10. Write the word that means the opposite of "hot".', font=small, fill="black")
62
+ img.save(path)
63
+
64
+
65
+ if not os.path.exists(SAMPLE):
66
+ try:
67
+ make_sample_worksheet(SAMPLE)
68
+ except Exception as ex:
69
+ print("Couldn't create the sample worksheet:", ex)
70
+
71
  BREAKS = [
72
  ("Jumping jacks!", "Stand up and do 5 jumping jacks."),
73
  ("Stretch like a cat", "Reach up high, then touch your toes. Do it 3 times."),
 
452
 
453
  THEME = gr.themes.Soft(primary_hue="indigo", radius_size="lg")
454
 
455
+ # Gradio 6 takes theme/css/head in launch(); Gradio 5 takes them in Blocks().
456
+ import inspect
457
+ NEW_GRADIO = "css" in inspect.signature(gr.Blocks.launch).parameters
458
+ STYLE = dict(theme=THEME, css=CSS, head=HEAD)
459
+
460
+ with gr.Blocks(title="Homework Hero", **({} if NEW_GRADIO else STYLE)) as demo:
461
  state = gr.State({})
462
 
463
  gr.HTML('<div class="hh-title"><h1>Homework Hero</h1>'
 
514
  names = {"hf": f"Hugging Face ({HF_MODEL})", "ollama": f"Ollama ({MODEL})"}
515
  found = available_backends()
516
  print("Homework Hero backends:", ", ".join(names[b] for b in found) or "demo mode only")
517
+ demo.launch(**(STYLE if NEW_GRADIO else {}))
requirements.txt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ gradio>=6.0
2
+ requests
3
+ pillow