README.md

metadata

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

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:

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:

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

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

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

{
  "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:

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:

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:

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:

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