Spaces:
Running on Zero
Running on Zero
Upload 3 files
Browse files- README.md +56 -5
- app.py +35 -2
- requirements.txt +3 -0
README.md
CHANGED
|
@@ -1,13 +1,64 @@
|
|
| 1 |
---
|
| 2 |
title: Homework Hero
|
| 3 |
-
emoji:
|
| 4 |
-
colorFrom:
|
| 5 |
-
colorTo:
|
| 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 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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(
|
|
|
|
| 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
|