Spaces:

s-b3
/

LifeStack

Sleeping

Soham Banerjee

deploy: pure lifestack with partitioned wisdom pool

77da5ce 7 months ago

15.9 kB

# Meta-R2: Complete HuggingFace Deployment Guide (Option A)

> This guide walks you through every single step to deploy Meta-R2 to HuggingFace using the cleanest architecture:
> - **Your trained model (500MB)** → uploaded as a **HuggingFace Model Repository**
> - **Your code + environment** → deployed as a **HuggingFace Space** (Docker)
>
> The Space will auto-download the model from the Model Repo at startup. No Git LFS. No 500MB in your code repo.

---

## 🗺️ Architecture Overview

```
HuggingFace
├── YOUR-USERNAME/lifestack-agent      ← Model Repo (the 500MB weights)
│   ├── config.json
│   ├── tokenizer.json
│   ├── tokenizer_config.json
│   ├── special_tokens_map.json
│   └── model.safetensors  (or pytorch_model.bin)
│
└── YOUR-USERNAME/meta-r2  [SPACE]     ← Code Repo (Docker Space)
    ├── Dockerfile                       (already exists ✅)
    ├── requirements.txt                 (already exists ✅)
    ├── app_flask.py                     (entry point ✅)
    ├── core/ agent/ scripts/ ...        (all your code ✅)
    └── openenv.yaml                     (already exists ✅)
          ↓ at startup
    agent.py calls AutoModelForCausalLM.from_pretrained("YOUR-USERNAME/lifestack-agent")
    → HuggingFace downloads the model to the Space's /root/.cache/huggingface/
```

---

## ✅ Pre-Flight Checklist (Do These Before Anything Else)

Go through every item below before starting the upload steps.

### 1. Confirm Your Trained Model Files Exist

Unzip the 500MB file from Kaggle. Open the folder. You **must** see these files:

```
lifestack_model/
├── config.json              ← REQUIRED
├── tokenizer.json           ← REQUIRED
├── tokenizer_config.json    ← REQUIRED
├── special_tokens_map.json  ← REQUIRED (may be missing — check below)
└── model.safetensors        ← REQUIRED (the big file)
    OR
└── pytorch_model.bin        ← (alternative format, also fine)
```

> **If any of these are missing**, the model is an incomplete checkpoint. Re-download or re-run training with `save_model=True` at the end of `train_trl.py`.

### 2. Confirm `requirements.txt` Is Correct

Your `requirements.txt` already has:
- `openenv-core>=0.2.3` ✅ (latest version, confirmed)
- `pydantic>=2.7.0` ✅
- `transformers>=4.40.0` ✅ (needed to download model from Hub)
- `torch>=2.0.0` ✅

**No changes needed** to `requirements.txt`.

### 3. Confirm the `Dockerfile` Entry Point

Your `Dockerfile` already runs:
```dockerfile
CMD ["python", "app_flask.py"]
```
This is correct. `app_flask.py` is the web server.

**No changes needed** to the `Dockerfile`.

### 4. Make Sure `.env` is in `.gitignore`

Check your `.gitignore` — it already has:
```
.env
```
✅ Your `GROQ_API_KEY` will **never** be pushed to GitHub or HuggingFace by accident.

### 5. Make the One Required Code Change in `agent.py`

This is the only code edit required for Option A.

Open `/Users/dayalgupta/Desktop/Meta-R2/agent/agent.py` and find **lines 13–18**:

```python
# CURRENT CODE (lines 13-18):
self.api_key = os.getenv('GROQ_API_KEY')
self.local_model_path = local_model_path or os.getenv('LIFESTACK_MODEL_PATH')
# Fallback to current directory if default existence
if not self.local_model_path and os.path.exists("./lifestack_model"):
    self.local_model_path = "./lifestack_model"
```

**Change it to this** (replace `YOUR-USERNAME` with your actual HuggingFace username):

```python
# UPDATED CODE:
self.api_key = os.getenv('GROQ_API_KEY')
self.local_model_path = local_model_path or os.getenv('LIFESTACK_MODEL_PATH')
# 1. Check for local folder (Kaggle / local dev)
if not self.local_model_path and os.path.exists("./lifestack_model"):
    self.local_model_path = "./lifestack_model"
# 2. Fall back to HuggingFace Hub model repo (production / Space deployment)
if not self.local_model_path:
    self.local_model_path = "YOUR-USERNAME/lifestack-agent"
```

**Why this works:** `AutoModelForCausalLM.from_pretrained()` (which already exists on line 41) accepts either a local folder path OR a HuggingFace Hub repo ID like `"username/repo-name"`. No other code change is needed.

### 6. Verify `lifestack_model/` Is NOT in Your Code Repo
Your model (500MB) should NOT be in the `Meta-R2` GitHub repository. Confirm:
```bash
ls /Users/dayalgupta/Desktop/Meta-R2/lifestack_model/
# Should print: "No such file or directory" OR "Empty directory"
```
If it has files, remove them:
```bash
rm -rf /Users/dayalgupta/Desktop/Meta-R2/lifestack_model/*
```
The folder can stay (it's referenced in the code) but must be empty.
---
## 📦 PART 1: Upload the Model to HuggingFace Hub
### Step 1.1 — Create a HuggingFace Account
Go to **https://huggingface.co** → click **Sign Up** → create your account. Remember your username (e.g., `dayal-gupta`) — you will use it everywhere.
### Step 1.2 — Create a New Model Repository
1. Go to **https://huggingface.co/new** (or click the `+` button → "New Model")
2. Fill in:
   - **Owner:** your username
   - **Model name:** `lifestack-agent` (this becomes `YOUR-USERNAME/lifestack-agent`)
   - **License:** `MIT` (recommended for hackathons)
   - **Visibility:** `Public` (required for the Space to download it without auth)
3. Click **Create Model**
You now have an empty model repo at `https://huggingface.co/YOUR-USERNAME/lifestack-agent`.
### Step 1.3 — Install the HuggingFace CLI
On your Mac terminal:
```bash
pip install huggingface_hub
huggingface-cli login
```
When prompted, go to **https://huggingface.co/settings/tokens** → click **New token** → name it anything → **Role: Write** → copy the token → paste it into the terminal.
### Step 1.4 — Upload the Model Files
Navigate to where your unzipped model folder is (e.g., Desktop) and run:
```bash
# Replace the path with wherever your unzipped model folder is:
huggingface-cli upload YOUR-USERNAME/lifestack-agent /path/to/your/lifestack_model/ .
```
**Example (if you unzipped on Desktop):**
```bash
huggingface-cli upload dayal-gupta/lifestack-agent /Users/dayalgupta/Desktop/lifestack_model/ .
```
This uploads ALL files from the local folder to the root of the HF repo. The `.` at the end means "upload to the root of the repo."
**This will take 3–8 minutes** for a 500MB file on a normal connection. You'll see a progress bar.
### Step 1.5 — Verify the Upload
Go to `https://huggingface.co/YOUR-USERNAME/lifestack-agent` in your browser.
You should see all files listed: `config.json`, `tokenizer.json`, `model.safetensors`, etc.
Click on `config.json` and confirm it contains `"model_type"` — this confirms the model is valid and complete.
### Step 1.6 — Add a Model Card (Optional but Impressive for Judges)
Click the **"Model Card"** tab on your repo page → click the pencil icon to edit → paste this:
```markdown
---
language: en
license: mit
tags:
  - reinforcement-learning
  - life-simulation
  - grpo
  - llama
  - openenv
---

# LifeStack Agent — GRPO Fine-tuned

This model is the trained agent for [Meta-R2](https://huggingface.co/spaces/YOUR-USERNAME/meta-r2),
a reinforcement learning environment that simulates complex real-life decision-making scenarios.

Fine-tuned using GRPO (Group Relative Policy Optimization) via TRL on a custom reward function
spanning 23 life metrics across 6 domains: career, finances, relationships, physical health,
mental wellbeing, and time management.

## Usage
```python
from transformers import AutoModelForCausalLM, AutoTokenizer
model = AutoModelForCausalLM.from_pretrained("YOUR-USERNAME/lifestack-agent")
tokenizer = AutoTokenizer.from_pretrained("YOUR-USERNAME/lifestack-agent")
```
```
Click **Save**.
---
## 🚀 PART 2: Deploy the Project as a HuggingFace Space
### Step 2.1 — Create a New Space
1. Go to **https://huggingface.co/new-space**
2. Fill in:
   - **Owner:** your username
   - **Space name:** `meta-r2`
   - **License:** `MIT`
   - **SDK:** Select **"Docker"** ← very important, NOT Gradio or Streamlit
   - **Visibility:** `Public`
3. Click **Create Space**
You now have an empty Space at `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2`.
### Step 2.2 — Connect Your GitHub Repository to the Space
This is the cleanest method — HuggingFace will auto-sync from your GitHub repo.
1. In your Space, click the **Settings** tab (gear icon)
2. Scroll down to **"Repository"** section
3. Click **"Link to a GitHub repository"**
4. Authorize HuggingFace to access your GitHub
5. Select the repo: `oki-dokii/Meta-R2`
6. Set branch: `main`
7. Click **Save**
Now every `git push` to `main` will automatically redeploy the Space. 
**Alternative (manual push):** If you don't want to link GitHub, you can push directly to the HuggingFace Space repo:
```bash
cd /Users/dayalgupta/Desktop/Meta-R2

# Add HF Space as a second remote:
git remote add space https://huggingface.co/spaces/YOUR-USERNAME/meta-r2

# Push your code:
git push space main
```
### Step 2.3 — Add the `GROQ_API_KEY` Secret to the Space
Your app needs the Groq API key at runtime. **Never hardcode it.** HuggingFace Spaces have a Secrets system for this.
1. In your Space, click the **Settings** tab
2. Scroll down to **"Variables and secrets"**
3. Click **"New secret"**
4. Fill in:
   - **Name:** `GROQ_API_KEY`
   - **Value:** your actual Groq API key (get it from https://console.groq.com/keys)
5. Click **Save**
Your `agent.py` already reads this via `os.getenv('GROQ_API_KEY')` ✅ — no code change needed.
### Step 2.4 — Add `HF_TOKEN` Secret (Required to Download the Private Model)
If your model repo is **Public** (which we set in Step 1.2), you can **skip this step**.
If your model repo is **Private**, add another secret:
- **Name:** `HF_TOKEN`
- **Value:** your HuggingFace write token (same one from Step 1.3)
Then add this line at the top of `app_flask.py` (before any model-loading code):
```python
import os
from huggingface_hub import login
hf_token = os.getenv("HF_TOKEN")
if hf_token:
    login(token=hf_token)
```
### Step 2.5 — Trigger the First Build

After pushing your code (Step 2.2), the Space will automatically start building.

1. Go to your Space URL: `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2`
2. Click the **"App"** tab — you'll see a build log
3. The build will take **3–5 minutes** for the first time (Docker pulls base image, installs packages)
4. After build, it will show **"Running"** status — then the app will boot

**During the first boot**, the Space will call `AutoModelForCausalLM.from_pretrained("YOUR-USERNAME/lifestack-agent")` which will download the 500MB model. This takes about 60–90 seconds on HuggingFace infrastructure. **After the first boot, it is cached** and subsequent restarts are instant.

---

## 🔍 PART 3: Verify Everything is Working

### Step 3.1 — Check the Build Log

In your Space, click **"Logs"** tab. You should see:

```
✅ Step 1/7 : FROM python:3.11-slim
✅ Successfully built ...
✅ Successfully tagged ...
```

If you see a red error, check the troubleshooting section below.

### Step 3.2 — Check the App Boot Log

After the build, click the **"App"** tab. In the log output you should see:

```
📦 Loading local GRPO model from YOUR-USERNAME/lifestack-agent...
✅ Local model LOADED.
 * Running on http://0.0.0.0:7860
```

If you see `⚠️ Failed to load local model ... Falling back to Groq.` — the model download failed. Check that your HF model repo URL is correct in `agent.py` and the repo is public.

### Step 3.3 — Test the Live App

Go to `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2` and click through the demo:
1. The web UI (served by `app_flask.py`) should load
2. Start an episode — the agent should respond with life decisions
3. Check that rewards are non-zero and steps > 5 (confirms the Task system is working)

---

## 🛠️ Troubleshooting Common Issues

| Error | Cause | Fix |
|---|---|---|
| `ModuleNotFoundError: openenv` | Wrong package in requirements.txt | Confirm `openenv-core>=0.2.3` is in `requirements.txt` (not `openenv`) |
| `OSError: Can't load model` | Wrong repo ID in `agent.py` | Make sure it's `"YOUR-ACTUAL-USERNAME/lifestack-agent"` not literally `YOUR-USERNAME` |
| `Build failed: torch install timeout` | `torch>=2.0.0` is huge (2GB+) | Add `--extra-index-url https://download.pytorch.org/whl/cpu` to Dockerfile before pip install |
| `Port 7860 not responding` | `app_flask.py` binding to wrong interface | Confirm `app.run(host='0.0.0.0', port=7860)` at the bottom of `app_flask.py` |
| `GROQ_API_KEY not found` | Secret not set | Go to Space Settings → Variables and secrets → add `GROQ_API_KEY` |
| `Space keeps restarting` | Out of memory (free tier is 16GB RAM) | torch on CPU for 500MB model may OOM — see "Reducing Memory" note below |

### Reducing Memory Usage (If Space OOMs)

Free HuggingFace Spaces have 16GB RAM. Loading a 500MB model in float32 uses ~2GB RAM, which is fine. But if you face OOM, add this to `agent.py` line 41–44:

```python
self.local_model = AutoModelForCausalLM.from_pretrained(
    self.local_model_path,
    torch_dtype=torch.float16,    # ← half precision, halves memory
    low_cpu_mem_usage=True,       # ← stream-loads, avoids peak RAM spike
    device_map="cpu"              # ← explicitly CPU on free tier
)
```

---

## 📋 Final Pre-Submission Checklist

Before submitting to the hackathon, verify every item:

- [ ] `https://huggingface.co/YOUR-USERNAME/lifestack-agent` exists and has all model files
- [ ] `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2` shows **"Running"** status (green dot)
- [ ] The Space app loads in browser without errors
- [ ] The Space log shows `✅ Local model LOADED` (not "Falling back to Groq")
- [ ] An episode runs and produces steps > 5 (confirms Task system is working)
- [ ] `GROQ_API_KEY` secret is set in Space settings (as fallback)
- [ ] The model repo has a Model Card explaining what it is
- [ ] Your `README.md` in the code repo links to both: the Space URL and the Model URL
- [ ] `agent.py` has been updated with `"YOUR-USERNAME/lifestack-agent"` as the HF Hub fallback
- [ ] `lifestack_model/` folder in your local `Meta-R2/` repo is empty (model not in code repo)
- [ ] All Bugs 1, 2, 3 are fixed and committed (they are — we did this already ✅)

---

## 📎 Quick Reference — All URLs

Replace `YOUR-USERNAME` with your HuggingFace username everywhere:

| What | URL |
|---|---|
| HuggingFace profile | `https://huggingface.co/YOUR-USERNAME` |
| Model repo | `https://huggingface.co/YOUR-USERNAME/lifestack-agent` |
| Space (live demo) | `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2` |
| Space settings (secrets) | `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2/settings` |
| Space build logs | `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2` → Logs tab |
| HuggingFace API tokens | `https://huggingface.co/settings/tokens` |
| Groq API keys | `https://console.groq.com/keys` |

---

## ⚡ The Exact Commands to Run Right Now (In Order)

```bash
# 1. Install HF CLI
pip install huggingface_hub
# 2. Login (will prompt for token)
huggingface-cli login
# 3. Upload model (change the path to your unzipped model folder)
huggingface-cli upload YOUR-USERNAME/lifestack-agent /path/to/lifestack_model/ .
# 4. Make the agent.py code change (edit manually in VS Code, then):
cd /Users/dayalgupta/Desktop/Meta-R2
git add agent/agent.py
git commit -m "feat: add HuggingFace Hub model fallback for Option A deployment"
git push origin main
# 5. Push to HuggingFace Space (if not using GitHub auto-sync):
git remote add space https://huggingface.co/spaces/YOUR-USERNAME/meta-r2
git push space main
```

That's it. The Space will build and boot automatically.

	# Meta-R2: Complete HuggingFace Deployment Guide (Option A)

	> This guide walks you through every single step to deploy Meta-R2 to HuggingFace using the cleanest architecture:
	> - Your trained model (500MB) → uploaded as a HuggingFace Model Repository
	> - Your code + environment → deployed as a HuggingFace Space (Docker)
	>
	> The Space will auto-download the model from the Model Repo at startup. No Git LFS. No 500MB in your code repo.

	---

	## 🗺️ Architecture Overview

	```
	HuggingFace
	├── YOUR-USERNAME/lifestack-agent ← Model Repo (the 500MB weights)
	│ ├── config.json
	│ ├── tokenizer.json
	│ ├── tokenizer_config.json
	│ ├── special_tokens_map.json
	│ └── model.safetensors (or pytorch_model.bin)
	│
	└── YOUR-USERNAME/meta-r2 [SPACE] ← Code Repo (Docker Space)
	├── Dockerfile (already exists ✅)
	├── requirements.txt (already exists ✅)
	├── app_flask.py (entry point ✅)
	├── core/ agent/ scripts/ ... (all your code ✅)
	└── openenv.yaml (already exists ✅)
	↓ at startup
	agent.py calls AutoModelForCausalLM.from_pretrained("YOUR-USERNAME/lifestack-agent")
	→ HuggingFace downloads the model to the Space's /root/.cache/huggingface/
	```

	---

	## ✅ Pre-Flight Checklist (Do These Before Anything Else)

	Go through every item below before starting the upload steps.

	### 1. Confirm Your Trained Model Files Exist

	Unzip the 500MB file from Kaggle. Open the folder. You must see these files:

	```
	lifestack_model/
	├── config.json ← REQUIRED
	├── tokenizer.json ← REQUIRED
	├── tokenizer_config.json ← REQUIRED
	├── special_tokens_map.json ← REQUIRED (may be missing — check below)
	└── model.safetensors ← REQUIRED (the big file)
	OR
	└── pytorch_model.bin ← (alternative format, also fine)
	```

	> If any of these are missing, the model is an incomplete checkpoint. Re-download or re-run training with `save_model=True` at the end of `train_trl.py`.

	### 2. Confirm `requirements.txt` Is Correct

	Your `requirements.txt` already has:
	- `openenv-core>=0.2.3` ✅ (latest version, confirmed)
	- `pydantic>=2.7.0` ✅
	- `transformers>=4.40.0` ✅ (needed to download model from Hub)
	- `torch>=2.0.0` ✅

	No changes needed to `requirements.txt`.

	### 3. Confirm the `Dockerfile` Entry Point

	Your `Dockerfile` already runs:
	```dockerfile
	CMD ["python", "app_flask.py"]
	```
	This is correct. `app_flask.py` is the web server.

	No changes needed to the `Dockerfile`.

	### 4. Make Sure `.env` is in `.gitignore`

	Check your `.gitignore` — it already has:
	```
	.env
	```
	✅ Your `GROQ_API_KEY` will never be pushed to GitHub or HuggingFace by accident.

	### 5. Make the One Required Code Change in `agent.py`

	This is the only code edit required for Option A.

	Open `/Users/dayalgupta/Desktop/Meta-R2/agent/agent.py` and find lines 13–18:

	```python
	# CURRENT CODE (lines 13-18):
	self.api_key = os.getenv('GROQ_API_KEY')
	self.local_model_path = local_model_path or os.getenv('LIFESTACK_MODEL_PATH')

	# Fallback to current directory if default existence
	if not self.local_model_path and os.path.exists("./lifestack_model"):
	self.local_model_path = "./lifestack_model"
	```

	Change it to this (replace `YOUR-USERNAME` with your actual HuggingFace username):

	```python
	# UPDATED CODE:
	self.api_key = os.getenv('GROQ_API_KEY')
	self.local_model_path = local_model_path or os.getenv('LIFESTACK_MODEL_PATH')

	# 1. Check for local folder (Kaggle / local dev)
	if not self.local_model_path and os.path.exists("./lifestack_model"):
	self.local_model_path = "./lifestack_model"

	# 2. Fall back to HuggingFace Hub model repo (production / Space deployment)
	if not self.local_model_path:
	self.local_model_path = "YOUR-USERNAME/lifestack-agent"
	```

	Why this works: `AutoModelForCausalLM.from_pretrained()` (which already exists on line 41) accepts either a local folder path OR a HuggingFace Hub repo ID like `"username/repo-name"`. No other code change is needed.

	### 6. Verify `lifestack_model/` Is NOT in Your Code Repo

	Your model (500MB) should NOT be in the `Meta-R2` GitHub repository. Confirm:
	```bash
	ls /Users/dayalgupta/Desktop/Meta-R2/lifestack_model/
	# Should print: "No such file or directory" OR "Empty directory"
	```
	If it has files, remove them:
	```bash
	rm -rf /Users/dayalgupta/Desktop/Meta-R2/lifestack_model/*
	```
	The folder can stay (it's referenced in the code) but must be empty.

	---

	## 📦 PART 1: Upload the Model to HuggingFace Hub

	### Step 1.1 — Create a HuggingFace Account

	Go to https://huggingface.co → click Sign Up → create your account. Remember your username (e.g., `dayal-gupta`) — you will use it everywhere.

	### Step 1.2 — Create a New Model Repository

	1. Go to https://huggingface.co/new (or click the `+` button → "New Model")
	2. Fill in:
	- Owner: your username
	- Model name: `lifestack-agent` (this becomes `YOUR-USERNAME/lifestack-agent`)
	- License: `MIT` (recommended for hackathons)
	- Visibility: `Public` (required for the Space to download it without auth)
	3. Click Create Model

	You now have an empty model repo at `https://huggingface.co/YOUR-USERNAME/lifestack-agent`.

	### Step 1.3 — Install the HuggingFace CLI

	On your Mac terminal:
	```bash
	pip install huggingface_hub
	huggingface-cli login
	```

	When prompted, go to https://huggingface.co/settings/tokens → click New token → name it anything → Role: Write → copy the token → paste it into the terminal.

	### Step 1.4 — Upload the Model Files

	Navigate to where your unzipped model folder is (e.g., Desktop) and run:

	```bash
	# Replace the path with wherever your unzipped model folder is:
	huggingface-cli upload YOUR-USERNAME/lifestack-agent /path/to/your/lifestack_model/ .
	```

	Example (if you unzipped on Desktop):
	```bash
	huggingface-cli upload dayal-gupta/lifestack-agent /Users/dayalgupta/Desktop/lifestack_model/ .
	```

	This uploads ALL files from the local folder to the root of the HF repo. The `.` at the end means "upload to the root of the repo."

	This will take 3–8 minutes for a 500MB file on a normal connection. You'll see a progress bar.

	### Step 1.5 — Verify the Upload

	Go to `https://huggingface.co/YOUR-USERNAME/lifestack-agent` in your browser.

	You should see all files listed: `config.json`, `tokenizer.json`, `model.safetensors`, etc.

	Click on `config.json` and confirm it contains `"model_type"` — this confirms the model is valid and complete.

	### Step 1.6 — Add a Model Card (Optional but Impressive for Judges)

	Click the "Model Card" tab on your repo page → click the pencil icon to edit → paste this:

	```markdown
	---
	language: en
	license: mit
	tags:
	- reinforcement-learning
	- life-simulation
	- grpo
	- llama
	- openenv
	---

	# LifeStack Agent — GRPO Fine-tuned

	This model is the trained agent for [Meta-R2](https://huggingface.co/spaces/YOUR-USERNAME/meta-r2),
	a reinforcement learning environment that simulates complex real-life decision-making scenarios.

	Fine-tuned using GRPO (Group Relative Policy Optimization) via TRL on a custom reward function
	spanning 23 life metrics across 6 domains: career, finances, relationships, physical health,
	mental wellbeing, and time management.

	## Usage
	```python
	from transformers import AutoModelForCausalLM, AutoTokenizer
	model = AutoModelForCausalLM.from_pretrained("YOUR-USERNAME/lifestack-agent")
	tokenizer = AutoTokenizer.from_pretrained("YOUR-USERNAME/lifestack-agent")
	```
	```

	Click Save.

	---

	## 🚀 PART 2: Deploy the Project as a HuggingFace Space

	### Step 2.1 — Create a New Space

	1. Go to https://huggingface.co/new-space
	2. Fill in:
	- Owner: your username
	- Space name: `meta-r2`
	- License: `MIT`
	- SDK: Select "Docker" ← very important, NOT Gradio or Streamlit
	- Visibility: `Public`
	3. Click Create Space

	You now have an empty Space at `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2`.

	### Step 2.2 — Connect Your GitHub Repository to the Space

	This is the cleanest method — HuggingFace will auto-sync from your GitHub repo.

	1. In your Space, click the Settings tab (gear icon)
	2. Scroll down to "Repository" section
	3. Click "Link to a GitHub repository"
	4. Authorize HuggingFace to access your GitHub
	5. Select the repo: `oki-dokii/Meta-R2`
	6. Set branch: `main`
	7. Click Save

	Now every `git push` to `main` will automatically redeploy the Space.

	Alternative (manual push): If you don't want to link GitHub, you can push directly to the HuggingFace Space repo:

	```bash
	cd /Users/dayalgupta/Desktop/Meta-R2

	# Add HF Space as a second remote:
	git remote add space https://huggingface.co/spaces/YOUR-USERNAME/meta-r2

	# Push your code:
	git push space main
	```

	### Step 2.3 — Add the `GROQ_API_KEY` Secret to the Space

	Your app needs the Groq API key at runtime. Never hardcode it. HuggingFace Spaces have a Secrets system for this.

	1. In your Space, click the Settings tab
	2. Scroll down to "Variables and secrets"
	3. Click "New secret"
	4. Fill in:
	- Name: `GROQ_API_KEY`
	- Value: your actual Groq API key (get it from https://console.groq.com/keys)
	5. Click Save

	Your `agent.py` already reads this via `os.getenv('GROQ_API_KEY')` ✅ — no code change needed.

	### Step 2.4 — Add `HF_TOKEN` Secret (Required to Download the Private Model)

	If your model repo is Public (which we set in Step 1.2), you can skip this step.

	If your model repo is Private, add another secret:
	- Name: `HF_TOKEN`
	- Value: your HuggingFace write token (same one from Step 1.3)

	Then add this line at the top of `app_flask.py` (before any model-loading code):
	```python
	import os
	from huggingface_hub import login
	hf_token = os.getenv("HF_TOKEN")
	if hf_token:
	login(token=hf_token)
	```

	### Step 2.5 — Trigger the First Build

	After pushing your code (Step 2.2), the Space will automatically start building.

	1. Go to your Space URL: `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2`
	2. Click the "App" tab — you'll see a build log
	3. The build will take 3–5 minutes for the first time (Docker pulls base image, installs packages)
	4. After build, it will show "Running" status — then the app will boot

	During the first boot, the Space will call `AutoModelForCausalLM.from_pretrained("YOUR-USERNAME/lifestack-agent")` which will download the 500MB model. This takes about 60–90 seconds on HuggingFace infrastructure. After the first boot, it is cached and subsequent restarts are instant.

	---

	## 🔍 PART 3: Verify Everything is Working

	### Step 3.1 — Check the Build Log

	In your Space, click "Logs" tab. You should see:

	```
	✅ Step 1/7 : FROM python:3.11-slim
	✅ Successfully built ...
	✅ Successfully tagged ...
	```

	If you see a red error, check the troubleshooting section below.

	### Step 3.2 — Check the App Boot Log

	After the build, click the "App" tab. In the log output you should see:

	```
	📦 Loading local GRPO model from YOUR-USERNAME/lifestack-agent...
	✅ Local model LOADED.
	* Running on http://0.0.0.0:7860
	```

	If you see `⚠️ Failed to load local model ... Falling back to Groq.` — the model download failed. Check that your HF model repo URL is correct in `agent.py` and the repo is public.

	### Step 3.3 — Test the Live App

	Go to `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2` and click through the demo:
	1. The web UI (served by `app_flask.py`) should load
	2. Start an episode — the agent should respond with life decisions
	3. Check that rewards are non-zero and steps > 5 (confirms the Task system is working)

	---

	## 🛠️ Troubleshooting Common Issues

	\| Error \| Cause \| Fix \|
	\|---\|---\|---\|
	\| `ModuleNotFoundError: openenv` \| Wrong package in requirements.txt \| Confirm `openenv-core>=0.2.3` is in `requirements.txt` (not `openenv`) \|
	\| `OSError: Can't load model` \| Wrong repo ID in `agent.py` \| Make sure it's `"YOUR-ACTUAL-USERNAME/lifestack-agent"` not literally `YOUR-USERNAME` \|
	\| `Build failed: torch install timeout` \| `torch>=2.0.0` is huge (2GB+) \| Add `--extra-index-url https://download.pytorch.org/whl/cpu` to Dockerfile before pip install \|
	\| `Port 7860 not responding` \| `app_flask.py` binding to wrong interface \| Confirm `app.run(host='0.0.0.0', port=7860)` at the bottom of `app_flask.py` \|
	\| `GROQ_API_KEY not found` \| Secret not set \| Go to Space Settings → Variables and secrets → add `GROQ_API_KEY` \|
	\| `Space keeps restarting` \| Out of memory (free tier is 16GB RAM) \| torch on CPU for 500MB model may OOM — see "Reducing Memory" note below \|

	### Reducing Memory Usage (If Space OOMs)

	Free HuggingFace Spaces have 16GB RAM. Loading a 500MB model in float32 uses ~2GB RAM, which is fine. But if you face OOM, add this to `agent.py` line 41–44:

	```python
	self.local_model = AutoModelForCausalLM.from_pretrained(
	self.local_model_path,
	torch_dtype=torch.float16, # ← half precision, halves memory
	low_cpu_mem_usage=True, # ← stream-loads, avoids peak RAM spike
	device_map="cpu" # ← explicitly CPU on free tier
	)
	```

	---

	## 📋 Final Pre-Submission Checklist

	Before submitting to the hackathon, verify every item:

	- [ ] `https://huggingface.co/YOUR-USERNAME/lifestack-agent` exists and has all model files
	- [ ] `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2` shows "Running" status (green dot)
	- [ ] The Space app loads in browser without errors
	- [ ] The Space log shows `✅ Local model LOADED` (not "Falling back to Groq")
	- [ ] An episode runs and produces steps > 5 (confirms Task system is working)
	- [ ] `GROQ_API_KEY` secret is set in Space settings (as fallback)
	- [ ] The model repo has a Model Card explaining what it is
	- [ ] Your `README.md` in the code repo links to both: the Space URL and the Model URL
	- [ ] `agent.py` has been updated with `"YOUR-USERNAME/lifestack-agent"` as the HF Hub fallback
	- [ ] `lifestack_model/` folder in your local `Meta-R2/` repo is empty (model not in code repo)
	- [ ] All Bugs 1, 2, 3 are fixed and committed (they are — we did this already ✅)

	---

	## 📎 Quick Reference — All URLs

	Replace `YOUR-USERNAME` with your HuggingFace username everywhere:

	\| What \| URL \|
	\|---\|---\|
	\| HuggingFace profile \| `https://huggingface.co/YOUR-USERNAME` \|
	\| Model repo \| `https://huggingface.co/YOUR-USERNAME/lifestack-agent` \|
	\| Space (live demo) \| `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2` \|
	\| Space settings (secrets) \| `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2/settings` \|
	\| Space build logs \| `https://huggingface.co/spaces/YOUR-USERNAME/meta-r2` → Logs tab \|
	\| HuggingFace API tokens \| `https://huggingface.co/settings/tokens` \|
	\| Groq API keys \| `https://console.groq.com/keys` \|

	---

	## ⚡ The Exact Commands to Run Right Now (In Order)

	```bash
	# 1. Install HF CLI
	pip install huggingface_hub

	# 2. Login (will prompt for token)
	huggingface-cli login

	# 3. Upload model (change the path to your unzipped model folder)
	huggingface-cli upload YOUR-USERNAME/lifestack-agent /path/to/lifestack_model/ .

	# 4. Make the agent.py code change (edit manually in VS Code, then):
	cd /Users/dayalgupta/Desktop/Meta-R2
	git add agent/agent.py
	git commit -m "feat: add HuggingFace Hub model fallback for Option A deployment"
	git push origin main

	# 5. Push to HuggingFace Space (if not using GitHub auto-sync):
	git remote add space https://huggingface.co/spaces/YOUR-USERNAME/meta-r2
	git push space main
	```

	That's it. The Space will build and boot automatically.