README.md

---
title: Math Tutor Response Annotation Demo
sdk: docker
app_port: 7860
pinned: false
---

# Math Tutor Response Annotation Demo

This folder is a self-contained Potato annotation demo for:

`annotated_data/math_annotator_train&test_sets_simple_2q_train_2q_test.xlsx`

It follows the same broad structure as Kseniia's Hugging Face Space: a Potato
`config.yaml`, prepared CSV data with an HTML display field, and Docker files
for Hugging Face Spaces.

## Files

- `config.yaml`: Potato task configuration and the 10 tutor-evaluation dimensions.
- `layouts/task_layout.html`: Potato-generated annotation form layout for the 10 dimensions.
- `scripts/prepare_potato_data.py`: Converts the Excel workbook into Potato CSV/JSON.
- `scripts/check_data.py`: Validates generated CSV/JSON files.
- `my-annotation-task/data/math_annotator_demo_all_with_id_text2show.csv`: Combined train/test demo data.
- `my-annotation-task/data/math_annotator_training_set_with_id_text2show.csv`: Training split only.
- `my-annotation-task/data/math_annotator_testing_set_with_id_text2show.csv`: Testing split only.
- `my-annotation-task/data/training_questions.json`: Known-label training items generated from the train sheet.
- `my-annotation-task/data/gold_standards.json`: Known-label gold items generated from the test sheet.
- `Dockerfile`, `requirements.txt`, `hf_start.py`: Hugging Face Spaces runtime.

## Regenerate Data

From the repository root:

```bash
python3 math_potato_annotation_demo/scripts/prepare_potato_data.py
python3 math_potato_annotation_demo/scripts/check_data.py
```

Expected generated counts:

- 14 train items
- 14 test items
- 28 combined demo items

## Run Locally

```bash
cd math_potato_annotation_demo
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python hf_start.py
```

Then open:

`http://localhost:7860`

## Deploy to Hugging Face Spaces

1. Create a new Hugging Face Space with SDK type `Docker`.
2. Upload or push the contents of this folder to the Space repository.
3. Let the Space build from `Dockerfile`.
4. For persistent annotation backups, set an `HF_TOKEN` Space secret and enable a
   backup/export workflow before collecting real annotations.

## Notes

- The first demo uses `math_annotator_demo_all_with_id_text2show.csv`, so both
  train and test examples are visible in one annotation queue.
- `training_questions.json` and `gold_standards.json` are generated and ready
  for a later qualification/QC pass, but the blocks in `config.yaml` are kept
  commented for the first UI demo to reduce startup risk.
- The UI itself is Potato's built-in UI. The custom part here is only CSS/JS in
  `custom_footer_html` to show one dimension at a time, similar to the screenshot.