README.md

---
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

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

### 2. Create a virtual environment and install dependencies

```bash
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:

```bash
# .env
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

> **Where to get a token:** you need a Hugging Face account. Then, go to [huggingface.co/settings/tokens](https://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:

```python
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](https://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

```bash
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](https://huggingface.co/new-space) and choose:

- **SDK:** Gradio
- **Visibility:** Public or Private

### 2. Push your code

```bash
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