GITHUB_SETUP.md

# 🚀 GitHub + Hugging Face Setup Guide

Follow these steps **exactly** to push TeamForge to GitHub and deploy to Hugging Face Spaces.

---

## PART 1 — Push to GitHub

### Step 1: Create a GitHub account (if you don't have one)
Go to https://github.com → Sign Up → free account

---

### Step 2: Create a new repository on GitHub

1. Click the **+** button (top right) → **New repository**
2. Fill in:
   - **Repository name:** `teamforge`
   - **Description:** `OpenEnv Benchmark for Autonomous Software Engineering Agents`
   - **Visibility:** Public ✅ (required for hackathon)
   - **Do NOT** tick "Add README" (we have our own)
3. Click **Create repository**
4. Copy the URL shown — it looks like:
   ```
   https://github.com/YOUR_USERNAME/teamforge.git
   ```

---

### Step 3: Install Git (if not installed)

**Check if installed:**
```bash
git --version
```

**If not installed:**
- Windows: Download from https://git-scm.com → install → restart VS Code
- Mac: Run `xcode-select --install` in terminal

---

### Step 4: Open VS Code terminal in your teamforge folder

1. Open VS Code
2. File → Open Folder → select the `teamforge` folder (extracted from zip)
3. Press `` Ctrl + ` `` to open terminal

---

### Step 5: Run these commands ONE BY ONE

```bash
# 1. Tell Git who you are (use your GitHub email)
git config --global user.email "your@email.com"
git config --global user.name "Your Name"

# 2. Initialize git in the folder
git init

# 3. Add all files
git add .

# 4. First commit
git commit -m "feat: TeamForge OpenEnv benchmark - initial submission"

# 5. Set main branch
git branch -M main

# 6. Connect to GitHub (paste YOUR repo URL here)
git remote add origin https://github.com/YOUR_USERNAME/teamforge.git

# 7. Push to GitHub
git push -u origin main
```

**If it asks for username/password:**
- Username: your GitHub username
- Password: use a GitHub Personal Access Token (NOT your password)
  - Go to GitHub → Settings → Developer settings → Personal access tokens → Generate new token
  - Select `repo` scope → Generate → Copy the token → paste as password

---

### Step 6: Verify

Go to `https://github.com/YOUR_USERNAME/teamforge` — you should see all your files there.

---

## PART 2 — Deploy to Hugging Face Spaces

### Step 1: Create Hugging Face account
Go to https://huggingface.co → Sign Up → free account

---

### Step 2: Create a new Space

1. Go to https://huggingface.co/spaces
2. Click **Create new Space**
3. Fill in:
   - **Space name:** `teamforge`
   - **License:** MIT
   - **SDK:** Gradio ✅
   - **Hardware:** CPU basic (free)
4. Click **Create Space**

---

### Step 3: Add your API key as a Secret

1. In your Space → **Settings** tab → **Repository secrets**
2. Add these three secrets:
   ```
   Name: HF_TOKEN
   Value: your_groq_api_key_here
   
   Name: API_BASE_URL
   Value: https://api.groq.com/openai/v1
   
   Name: MODEL_NAME
   Value: llama3-8b-8192
   ```
   > ⚠️ Regenerate your Groq key first at console.groq.com — the old one was shared publicly

---

### Step 4: Push code to the Space

```bash
# In your VS Code terminal (inside teamforge folder)

# Add HuggingFace Space as a remote
git remote add hf https://huggingface.co/spaces/YOUR_HF_USERNAME/teamforge

# Push to HuggingFace
git push hf main
```

**If it asks for credentials:**
- Username: your HuggingFace username
- Password: your HuggingFace Access Token
  - Go to HuggingFace → Settings → Access Tokens → New token → Write access → Copy

---

### Step 5: Verify deployment

1. Go to `https://huggingface.co/spaces/YOUR_HF_USERNAME/teamforge`
2. Wait 2–3 minutes for it to build
3. You should see the Gradio interface

---

## PART 3 — Submit to Hackathon

When submitting, provide:

| Field | Value |
|---|---|
| **GitHub URL** | `https://github.com/YOUR_USERNAME/teamforge` |
| **HF Space URL** | `https://huggingface.co/spaces/YOUR_USERNAME/teamforge` |
| **Inference script** | `inference.py` (in root) |
| **API_BASE_URL** | `https://api.groq.com/openai/v1` |
| **MODEL_NAME** | `llama3-8b-8192` |
| **HF_TOKEN** | your Groq API key |

---

## PART 4 — Test Before Submitting

Run these to confirm everything works:

```bash
# 1. Tests pass
pytest tests/test_environment.py -v

# 2. Demo runs
python demo.py

# 3. Log format is correct
set HF_TOKEN=gsk_...         # Windows
export HF_TOKEN=gsk_...      # Mac/Linux
python inference.py --task easy_bugfix_chunk_list

# Expected output:
# [START] task=easy_bugfix_chunk_list env=teamforge model=llama3-8b-8192
# [STEP] step=1 action=plan_step reward=0.02 done=false error=null
# ...
# [END] success=true steps=8 score=0.97 rewards=...
```

---

## Common Errors & Fixes

| Error | Fix |
|---|---|
| `git: command not found` | Install Git from git-scm.com, restart VS Code |
| `remote: Repository not found` | Check the GitHub URL — must match your username exactly |
| `Authentication failed` | Use Personal Access Token, not your password |
| `pip install` fails | Add `--break-system-packages` or use `pip3` |
| `python: command not found` | Use `python3` or `py` instead |
| HF Space shows error | Check Secrets are set correctly in Space settings |

---

## Quick Reference — All Commands

```bash
# Push to GitHub
git init
git add .
git commit -m "feat: TeamForge OpenEnv benchmark"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/teamforge.git
git push -u origin main

# Push to HuggingFace
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/teamforge
git push hf main

# After making changes, update both:
git add .
git commit -m "fix: description of change"
git push origin main
git push hf main
```