---
title: Hierarchical Longformer ESG Classification
emoji: 📊
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
---

# Hierarchical Longformer — ESG Classification API

FastAPI backend for live inference on hierarchical ESG text classification, deployed on Hugging Face Spaces.

---

## Initial Setup (From Scratch)

### 1. Create a Hugging Face Account & Token

1. Go to [huggingface.co](https://huggingface.co) and sign up.
2. Go to **Settings → Access Tokens → New Token**.
3. Create a token with **Write** access, copy it.

### 2. Install the HF CLI & Login

On your training server (or any machine with the model files):

```bash
pip install huggingface_hub
huggingface-cli login
# Paste your token when prompted
# Type Y to save as git credential
```

If git credential helper is not set, run:

```bash
git config --global credential.helper store
```

### 3. Upload the Trained Model to HF Hub

This creates a private repository on HF Hub and uploads the model checkpoint and tokenizer:

```bash
python3 -c "
from huggingface_hub import HfApi
api = HfApi()

# Create a private repo (only needs to be done once)
api.create_repo('sweebano/hierarchical-longformer', private=True)

# Upload the model checkpoint
api.upload_file(
    path_or_fileobj='/projects/raah9348/longformer/code/Longformer_Hierarchical_Model/hierarchical_model.pt',
    path_in_repo='hierarchical_model.pt',
    repo_id='sweebano/hierarchical-longformer',
)

# Upload the tokenizer folder
api.upload_folder(
    folder_path='/projects/raah9348/longformer/code/Longformer_Hierarchical_Model/hierarchical_model_tokenizer',
    path_in_repo='hierarchical_model_tokenizer',
    repo_id='sweebano/hierarchical-longformer',
)

print('Done!')
"
```

### 4. Create a Hugging Face Space

1. Go to [huggingface.co/new-space](https://huggingface.co/new-space).
2. Fill in:
   - **Owner:** sweebano
   - **Name:** `longformer_classifier`
   - **SDK:** Docker
   - **Docker template:** Blank
   - **Hardware:** Free (CPU)
   - **Visibility:** Public
3. Click **Create Space**.

### 5. Push the Backend Code to the Space

From your local machine:

```bash
cd /path/to/hf_backend
git init
git remote add origin https://huggingface.co/spaces/sweebano/longformer_classifier
git add app.py Dockerfile requirements.txt README.md
git commit -m "Add application files"
git push --force origin main
```

When prompted:
- **Username:** `sweebano`
- **Password:** your HF access token (not your HF password)

### 6. Add the HF Token as a Space Secret

Since the model repository is private, the Space needs your token to download it:

1. Go to your Space page → **Settings** → **Variables and secrets**.
2. Click **New secret**.
3. Name: `HF_TOKEN`, Value: your HF access token.
4. Save. The Space will automatically restart.

### 7. Wait for Build

The Space will automatically build the Docker image and start the FastAPI server. First build takes ~5–10 minutes (installs dependencies and downloads the Longformer base model). Watch the build logs on the Space's **App** tab.

Once you see `✓ Model loaded successfully` and `Uvicorn running on http://0.0.0.0:7860`, the API is live.

---

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET`  | `/`      | Status, model info, device, label names |
| `GET`  | `/health`| Health check (`model_loaded: true/false`) |
| `POST` | `/predict`| Classify input text |

### Example Request

```bash
curl -X POST https://sweebano-longformer-classifier.hf.space/predict \
  -H "Content-Type: application/json" \
  -d '{"text": "The fund excludes companies involved in tobacco, weapons, and fossil fuels."}'
```

### Example Response

```json
{
  "pred_label": "Exc",
  "deciding_head": "family",
  "probabilities": {
    "Exc": 0.8932,
    "Imp": 0.0215,
    "Imp Act": 0.0081,
    "Opp": 0.0193,
    "Opp Act": 0.0067,
    "Men": 0.0124,
    "None": 0.0388
  },
  "head_predictions": {
    "binary": {"ESG": 0.9612, "None": 0.0388},
    "family": {"Exc": 0.8745, "Imp": 0.0322, "Opp": 0.0521, "Men": 0.0412},
    "imp_action": {"Imp": 0.7267, "Imp Act": 0.2733},
    "opp_action": {"Opp": 0.7423, "Opp Act": 0.2577}
  }
}
```

---

## Frontend Integration

From any frontend, call the API using `fetch`:

```javascript
const API_URL = "https://sweebano-longformer-classifier.hf.space";

async function predict() {
  const text = document.getElementById("input-text").value;
  const resultDiv = document.getElementById("result");
  resultDiv.textContent = "Predicting...";

  try {
    const res = await fetch(`${API_URL}/predict`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text }),
    });
    const data = await res.json();
    resultDiv.textContent = `Prediction: ${data.pred_label}`;
  } catch (err) {
    resultDiv.textContent = `Error: ${err.message}`;
  }
}
```

CORS is enabled for all origins, so this works from any domain (localhost, Vercel, GitHub Pages, etc.).

**Note:** CPU inference takes ~15–30 seconds per request. Show a loading spinner so users know it's working.

---

## Updating the Inference Code

After making changes to `app.py`, `Dockerfile`, or `requirements.txt`:

```bash
cd /path/to/hf_backend
git add -A
git commit -m "Describe your changes"
git push origin main
```

The Space auto-rebuilds on every push (~2–3 minutes).

---

## Updating the Model (After Retraining)

From your training server:

```bash
python3 -c "
from huggingface_hub import HfApi
api = HfApi()
api.upload_file(
    path_or_fileobj='/projects/raah9348/longformer/code/Longformer_Hierarchical_Model/hierarchical_model.pt',
    path_in_repo='hierarchical_model.pt',
    repo_id='sweebano/hierarchical-longformer',
)
print('Model updated!')
"
```

Then go to your Space page → **Settings** → **Factory reboot** to reload the new weights.

If the tokenizer also changed (e.g., new special tokens), upload it too:

```bash
python3 -c "
from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(
    folder_path='/projects/raah9348/longformer/code/Longformer_Hierarchical_Model/hierarchical_model_tokenizer',
    path_in_repo='hierarchical_model_tokenizer',
    repo_id='sweebano/hierarchical-longformer',
)
print('Tokenizer updated!')
"
```

---

## Keeping the Space Awake (Free Tier)

The free CPU tier sleeps after 48 hours of inactivity. To prevent this:

1. Go to [cron-job.org](https://cron-job.org) and create a free account.
2. Create a new cron job:
   - **URL:** `https://sweebano-longformer-classifier.hf.space/health`
   - **Schedule:** Every 30 minutes
3. This pings the health endpoint regularly, preventing the Space from sleeping.

---

## File Structure

```
hf_backend/
├── app.py            # FastAPI application (model loading, /predict endpoint)
├── Dockerfile        # Docker build instructions for HF Spaces
├── requirements.txt  # Python dependencies
└── README.md         # This file
```