README.md

metadata

title: My Challenge
emoji: 🔋
colorFrom: purple
colorTo: green
sdk: gradio
sdk_version: 5.50.0
pinned: false

🏆 Gradio Challenge Template

A ready-to-deploy template for hosting science challenges with Gradio.

Participants can register, submit results, and track their position on a live leaderboard.

---

Features

• The platform for participants to learn about the challenge, register, submit their results and track their position on the leaderboard.
• HuggingFace dataset backend — registrations and submissions are stored as two dataset configs (registrations, submissions)
• Duplicate guard — prevents the same e-mail from registering twice
• Single config file — change challenge name, description, dataset path, and scoring direction in config.py

---

File Structure

.
├── app.py              # Entry point, assembles all tabs
├── config.py           # ← Edit this to configure your challenge
├── utils.py            # HuggingFace load / push data helpers
├── tabs                # About tab
    ├── about.py        # About (details about the challenges)
    ├── registration.py # Registration tab
    ├── submission.py   # Submission tab
    ├── leaderboard.py  # Leaderboard tab
├── requirements.txt    # the app requirements
├── .gitignore
├── README.md
└── .env                # Your HF token to run the app locally — never commit this

---

Quickstart — Run Locally

1. Clone the repo

git clone https://github.com/EmmaScharfmann/challenge-template.git
cd challenge-template

2. Create a virtual environment and install dependencies

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Set up your HuggingFace token

Create a .env file at the root of the project:

# .env
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Where to get a token: you need a Hugging Face account. Then, go to huggingface.co/settings/tokens and create a token with write access.

⚠️ Never commit .env to git. Add it to .gitignore:

.env

4. Configure the challenge

Open about.py and edit the values at the top:

CHALLENGE_NAME = "My Challenge"
CHALLENGE_DESCRIPTION = "..."          # Markdown supported
HF_DATASET_PATH = "your-org/your-challenge-dataset"
LEADERBOARD_SCORE_COLUMN = "score"
LEADERBOARD_HIGHER_IS_BETTER = True

5. Create the HuggingFace dataset

The dataset must exist before the app can push to it. Create an empty dataset repo on huggingface.co/new-dataset matching the path you set in about.py. The two configs (registrations, submissions) are created automatically on first write.

6. Launch

python app.py

The app will be available at http://localhost:7860.

---

Deploy on HuggingFace Spaces

1. Create a new Space

Go to huggingface.co/new-space and choose:

• SDK: Gradio
• Visibility: Public or Private

2. Push your code

git remote add space https://huggingface.co/spaces/your-org/your-space
git push space main

Or connect your GitHub repo directly from the Space settings page.

3. Add your HF token as a Secret

In your Space, go to Settings → Variables and Secrets → New Secret and add:

Name	Value
HF_TOKEN	hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Secrets are injected as environment variables at runtime. The datasets library will pick up HF_TOKEN automatically — no code change needed compared to local.

Why a secret and not a variable? Variables are visible to anyone who views the Space settings. Secrets are encrypted and only exposed to the running container.

---

Dataset Schema

Two configs are pushed to your HuggingFace dataset:

registrations

Column	Type	Description
timestamp	string	ISO 8601 UTC
name	string	Participant's full name
email	string	Used as unique identifier
affiliation	string	University / company
team_name	string	Used to link submissions

submissions

Column	Type	Description
timestamp	string	ISO 8601 UTC
team_name	string	Must match a registered team
method	string	Short description of the approach
score	float	The metric value
file_name	string	Optional uploaded file path

---

Custom challenge

This is a simple challenge template. Feel free to adapt this template to your need and to contribute to this repo.

License

MIT