Spaces:
Sleeping
Sleeping
| 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 | |
| ``` | |