sweebano/longformer_classifier

1---2title: Hierarchical Longformer ESG Classification3emoji: 📊4colorFrom: green5colorTo: blue6sdk: docker7app_port: 78608---9 10# Hierarchical Longformer — ESG Classification API11 12FastAPI backend for live inference on hierarchical ESG text classification, deployed on Hugging Face Spaces.13 14---15 16## Initial Setup (From Scratch)17 18### 1. Create a Hugging Face Account & Token19 201. Go to [huggingface.co](https://huggingface.co) and sign up.212. Go to **Settings → Access Tokens → New Token**.223. Create a token with **Write** access, copy it.23 24### 2. Install the HF CLI & Login25 26On your training server (or any machine with the model files):27 28```bash29pip install huggingface_hub30huggingface-cli login31# Paste your token when prompted32# Type Y to save as git credential33```34 35If git credential helper is not set, run:36 37```bash38git config --global credential.helper store39```40 41### 3. Upload the Trained Model to HF Hub42 43This creates a private repository on HF Hub and uploads the model checkpoint and tokenizer:44 45```bash46python3 -c "47from huggingface_hub import HfApi48api = HfApi()49 50# Create a private repo (only needs to be done once)51api.create_repo('sweebano/hierarchical-longformer', private=True)52 53# Upload the model checkpoint54api.upload_file(55    path_or_fileobj='/projects/raah9348/longformer/code/Longformer_Hierarchical_Model/hierarchical_model.pt',56    path_in_repo='hierarchical_model.pt',57    repo_id='sweebano/hierarchical-longformer',58)59 60# Upload the tokenizer folder61api.upload_folder(62    folder_path='/projects/raah9348/longformer/code/Longformer_Hierarchical_Model/hierarchical_model_tokenizer',63    path_in_repo='hierarchical_model_tokenizer',64    repo_id='sweebano/hierarchical-longformer',65)66 67print('Done!')68"69```70 71### 4. Create a Hugging Face Space72 731. Go to [huggingface.co/new-space](https://huggingface.co/new-space).742. Fill in:75   - **Owner:** sweebano76   - **Name:** `longformer_classifier`77   - **SDK:** Docker78   - **Docker template:** Blank79   - **Hardware:** Free (CPU)80   - **Visibility:** Public813. Click **Create Space**.82 83### 5. Push the Backend Code to the Space84 85From your local machine:86 87```bash88cd /path/to/hf_backend89git init90git remote add origin https://huggingface.co/spaces/sweebano/longformer_classifier91git add app.py Dockerfile requirements.txt README.md92git commit -m "Add application files"93git push --force origin main94```95 96When prompted:97- **Username:** `sweebano`98- **Password:** your HF access token (not your HF password)99 100### 6. Add the HF Token as a Space Secret101 102Since the model repository is private, the Space needs your token to download it:103 1041. Go to your Space page → **Settings** → **Variables and secrets**.1052. Click **New secret**.1063. Name: `HF_TOKEN`, Value: your HF access token.1074. Save. The Space will automatically restart.108 109### 7. Wait for Build110 111The 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.112 113Once you see `✓ Model loaded successfully` and `Uvicorn running on http://0.0.0.0:7860`, the API is live.114 115---116 117## API Endpoints118 119| Method | Endpoint | Description |120|--------|----------|-------------|121| `GET`  | `/`      | Status, model info, device, label names |122| `GET`  | `/health`| Health check (`model_loaded: true/false`) |123| `POST` | `/predict`| Classify input text |124 125### Example Request126 127```bash128curl -X POST https://sweebano-longformer-classifier.hf.space/predict \129  -H "Content-Type: application/json" \130  -d '{"text": "The fund excludes companies involved in tobacco, weapons, and fossil fuels."}'131```132 133### Example Response134 135```json136{137  "pred_label": "Exc",138  "deciding_head": "family",139  "probabilities": {140    "Exc": 0.8932,141    "Imp": 0.0215,142    "Imp Act": 0.0081,143    "Opp": 0.0193,144    "Opp Act": 0.0067,145    "Men": 0.0124,146    "None": 0.0388147  },148  "head_predictions": {149    "binary": {"ESG": 0.9612, "None": 0.0388},150    "family": {"Exc": 0.8745, "Imp": 0.0322, "Opp": 0.0521, "Men": 0.0412},151    "imp_action": {"Imp": 0.7267, "Imp Act": 0.2733},152    "opp_action": {"Opp": 0.7423, "Opp Act": 0.2577}153  }154}155```156 157---158 159## Frontend Integration160 161From any frontend, call the API using `fetch`:162 163```javascript164const API_URL = "https://sweebano-longformer-classifier.hf.space";165 166async function predict() {167  const text = document.getElementById("input-text").value;168  const resultDiv = document.getElementById("result");169  resultDiv.textContent = "Predicting...";170 171  try {172    const res = await fetch(`${API_URL}/predict`, {173      method: "POST",174      headers: { "Content-Type": "application/json" },175      body: JSON.stringify({ text }),176    });177    const data = await res.json();178    resultDiv.textContent = `Prediction: ${data.pred_label}`;179  } catch (err) {180    resultDiv.textContent = `Error: ${err.message}`;181  }182}183```184 185CORS is enabled for all origins, so this works from any domain (localhost, Vercel, GitHub Pages, etc.).186 187**Note:** CPU inference takes ~15–30 seconds per request. Show a loading spinner so users know it's working.188 189---190 191## Updating the Inference Code192 193After making changes to `app.py`, `Dockerfile`, or `requirements.txt`:194 195```bash196cd /path/to/hf_backend197git add -A198git commit -m "Describe your changes"199git push origin main200```201 202The Space auto-rebuilds on every push (~2–3 minutes).203 204---205 206## Updating the Model (After Retraining)207 208From your training server:209 210```bash211python3 -c "212from huggingface_hub import HfApi213api = HfApi()214api.upload_file(215    path_or_fileobj='/projects/raah9348/longformer/code/Longformer_Hierarchical_Model/hierarchical_model.pt',216    path_in_repo='hierarchical_model.pt',217    repo_id='sweebano/hierarchical-longformer',218)219print('Model updated!')220"221```222 223Then go to your Space page → **Settings** → **Factory reboot** to reload the new weights.224 225If the tokenizer also changed (e.g., new special tokens), upload it too:226 227```bash228python3 -c "229from huggingface_hub import HfApi230api = HfApi()231api.upload_folder(232    folder_path='/projects/raah9348/longformer/code/Longformer_Hierarchical_Model/hierarchical_model_tokenizer',233    path_in_repo='hierarchical_model_tokenizer',234    repo_id='sweebano/hierarchical-longformer',235)236print('Tokenizer updated!')237"238```239 240---241 242## Keeping the Space Awake (Free Tier)243 244The free CPU tier sleeps after 48 hours of inactivity. To prevent this:245 2461. Go to [cron-job.org](https://cron-job.org) and create a free account.2472. Create a new cron job:248   - **URL:** `https://sweebano-longformer-classifier.hf.space/health`249   - **Schedule:** Every 30 minutes2503. This pings the health endpoint regularly, preventing the Space from sleeping.251 252---253 254## File Structure255 256```257hf_backend/258├── app.py            # FastAPI application (model loading, /predict endpoint)259├── Dockerfile        # Docker build instructions for HF Spaces260├── requirements.txt  # Python dependencies261└── README.md         # This file262```263