docs/DEPLOYMENT.md

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:

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:

# 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):

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

ls /Users/dayalgupta/Desktop/Meta-R2/lifestack_model/
# Should print: "No such file or directory" OR "Empty directory"

If it has files, remove them:

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:

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:

# 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):

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:

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

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:

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)

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