README_HF.md

# How to Push Code to a New HuggingFace Space

## Prerequisites

- [Git](https://git-scm.com/) installed
- A [HuggingFace account](https://huggingface.co/join)
- A HuggingFace Access Token (create one at [Settings > Tokens](https://huggingface.co/settings/tokens) with **Write** permission)

---

## Steps

### 1. Create a New Space on HuggingFace

1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
2. Choose a **Space name** (e.g., `My_App`)
3. Select the **SDK** (Gradio, Streamlit, Docker, or Static)
4. Choose visibility (Public or Private)
5. Click **Create Space**

Your Space URL will be: `https://huggingface.co/spaces/<YOUR_USERNAME>/<SPACE_NAME>`

---

### 2. Clone the Empty Space Locally

```bash
git clone https://huggingface.co/spaces/<YOUR_USERNAME>/<SPACE_NAME>
cd <SPACE_NAME>
```

When prompted for credentials:
- **Username:** Your HuggingFace username
- **Password:** Your HuggingFace Access Token (NOT your account password)

---

### 3. Register Your Team
Create a `team.yml` file at the **root** of your Hugging Face Space folder with your team name and members. This is required for hackathon participation and helps organizers identify your team during evaluation.

```yaml
display_name: Your Team Name
members:
  - name: Alice Chen, email: "alice@example.com"
  - name: Bob Martin, email: "bob@example.com"
```

Create a `README.md` file at the **root** of your Hugging Face Space folder with a brief description of your app. This is required for Hugging Face Spaces and helps organizers understand your app during evaluation. Replace [Your Team Name] with your actual team name. Also note that the `app_file` field should match the name of your main application file (e.g., `app.py`).

```markdown
title: [Your Team Name]'s RAG App
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.1
python_version: '3.11'
app_file: app.py
pinned: false
license: apache-2.0
```

---

### 4. Add Codes

#### Pull the sample code Example-App-Hackathon-Gustave-Eiffel-2026 into the Space

To have a quick start, you can pull the sameple code Example-App-Hackathon-Gustave-Eiffel-2026 into your Space. You can do this by adding this repo as a second remote source and merging it into your Space:

```bash
# Inside your cloned Space folder:
cd <SPACE_NAME>

# Add the source repo as a second remote
git remote add source https://huggingface.co/spaces/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026
# or from GitHub:
# git remote add source https://github.com/<OWNER>/<REPO>.git

# Fetch all branches from the source
git fetch source

# Merge the source's main branch into your Space
git merge source/main --allow-unrelated-histories -m "Pull code from source repo"
```

#### Add your code into the Space

If you are working in a team, your teammate can simply copy/paste your code or files into the cloned Space folder.

---

#### Add a `.gitignore` to exclude unnecessary files:

Put the following content in a `.gitignore` file at the root of your Space to avoid pushing large or sensitive files:
```
.venv
__pycache__/
**/__pycache__/
*.sqlite3
chroma_db/
.env
```

---

### 5. Commit and Push

```bash
git add .
git commit -m "Initial commit"
git push origin main
git remote remove source (if you have added the sample code Example-App-Hackathon-Gustave-Eiffel-2026 as a second remote)
```
---


### 6. Deploy to Hugging Face Spaces

1. Once you have pushed the code, (IF NOT) Push this code to the Space repository.
2. Add `AZURE_API_KEY` as a Space Secret (Settings → Secrets). Azure API key is a key to call the LLM APIs. The organizers will provide you one at the date of the hackathon.
3. The Space automatically installs dependencies and starts the app.
4. The hackathon will be a competition on the RAG (Retrieval-Augmented Generation) application you built. You are encouraged to learn the basics of RAG.
---

## Troubleshooting reference

### Binary File Rejection

HuggingFace rejects pushes containing binary files (e.g., `.sqlite3`, `.pkl`, `.bin`).

**Fix:**

1. Add the binary files to `.gitignore`
2. Remove them from git tracking:
   ```bash
   git rm -r --cached path/to/binary/file
   ```
3. Squash history to purge them completely:
   ```bash
   git add -A
   git reset --soft $(git rev-list --max-parents=0 HEAD)
   git commit -m "Clean initial commit"
   git push hfspace main --force
   ```

### Authentication Failed

- HuggingFace does **not** accept account passwords for git. Use an **Access Token**.
- Make sure the token has **Write** permission.
- You can embed the token in the remote URL:
  ```bash
  git remote set-url hfspace https://<USERNAME>:<TOKEN>@huggingface.co/spaces/<USERNAME>/<SPACE_NAME>
  ```

### Wrong Branch Name

Some repos use `master` instead of `main`. Check with:

```bash
git branch
```

Push to whichever branch your Space expects (usually `main`).

---

## Security Reminder

- **Never** commit your HF token or API keys to the repo.
- If a token is accidentally exposed, revoke it immediately at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) and generate a new one.
- Use environment variables or HuggingFace Space **Secrets** (Settings > Variables and secrets) for sensitive values.