Rashmil888/TX_FAT_Reports

Transformer FAT API — Setup Guide

FastAPI backend for the 3-winding transformer FAT workflow. Designed to run on Hugging Face Spaces (Docker SDK) — free tier.

Project Structure

transformer-fat-api/
├── Dockerfile
├── requirements.txt
└── app/
    ├── main.py              ← FastAPI app + CORS
    ├── routes/
    │   ├── detect.py        ← POST /api/detect        (Step 0 — LLM param detection)
    │   ├── config.py        ← GET/POST /api/config     (save/load batch_config.json)
    │   ├── extract.py       ← POST /api/extract        (Step 1 — PDF extraction)
    │   ├── normalise.py     ← POST /api/normalise      (Step 2 — PowerFactory params)
    │   └── download.py      ← GET  /api/download       (Excel file download)
    └── scripts/
        ├── tx_fat_utils.py      ← shared extraction engine
        ├── tx_fat_extract.py    ← Step 1 script
        └── tx_fat_normalise.py  ← Step 2 script

Step 1 — Create a Hugging Face account

Go to https://huggingface.co and sign up for a free account. You do NOT need to pay for anything — the free tier is sufficient.

Step 2 — Create a new Space

1. 1.Go to https://huggingface.co/spaces
2. 2.Click "Create new Space"
3. 3.Fill in:
4. 4.Space name: transformer-fat-api (or any name you like)
5. 5.License: MIT
6. 6.SDK: Select Docker
7. 7.Visibility: Private (recommended — keeps your API internal)
8. 8.Click "Create Space"

You will land on a page with an empty Space and a git repository URL like: https://huggingface.co/spaces/YOUR_USERNAME/transformer-fat-api

Step 3 — Get a HuggingFace access token (for LLM inference)

This token lets your backend call HF's hosted models for Step 0 auto-detection.

1. 1.Go to https://huggingface.co/settings/tokens
2. 2.Click "New token"
3. 3.Name it transformer-fat-api, Role: Read
4. 4.Copy the token — it starts with hf_...

Step 4 — Add the token as a Space secret

1. 1.In your Space, go to Settings → Variables and Secrets
2. 2.Click "New Secret"
3. 3.Name: HF_TOKEN
4. 4.Value: paste your hf_... token
5. 5.Click Save

This injects the token as an environment variable at runtime without exposing it in your code or git history.

Step 5 — Push the code to your Space

HF Spaces uses git. Clone your Space, copy the files in, and push.

# Install git-lfs if you haven't already
git lfs install

# Clone your Space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/transformer-fat-api
cd transformer-fat-api

# Copy all project files into the cloned repo
# (copy the contents of this transformer-fat-api folder here)
cp -r /path/to/transformer-fat-api/* .

# Commit and push
git add .
git commit -m "Initial deployment"
git push

After pushing, go back to your Space page. You will see a "Building" badge in the top right — the Docker image is being built. This takes 2–4 minutes the first time. Once it says "Running", your API is live.

Step 6 — Test the health endpoint

Your API URL will be: https://YOUR_USERNAME-transformer-fat-api.hf.space

Test it:

curl https://YOUR_USERNAME-transformer-fat-api.hf.space/api/health
# Expected: {"status":"ok","service":"transformer-fat-api"}

You can also open the auto-generated docs: https://YOUR_USERNAME-transformer-fat-api.hf.space/docs

Step 7 — Update the CORS origin in main.py

Once you deploy your React frontend to Vercel, add its URL to the CORS list in app/main.py:

allow_origins=[
    "http://localhost:5173",
    "https://your-app-name.vercel.app",   # ← add your Vercel URL here
],

Then commit and push the change — the Space rebuilds automatically.

API Reference

All endpoints are documented interactively at /docs (Swagger UI).

Session model

The React frontend generates a UUID on first load and stores it in localStorage. This ID is passed with every API call to keep session files isolated under /tmp/{session_id}/.

Important: /tmp is ephemeral — files are lost if the Space restarts. The frontend should:

1. 1.Download the Excel file immediately after Step 2 completes.
2. 2.Save batch_config.json to localStorage so Step 0 can be skipped for the next batch from the same manufacturer.

Uploading 50 PDFs — chunked upload

Do not upload all 50 PDFs in a single request. The React frontend should upload them in batches of 10 with a progress bar:

// pseudocode
for (let i = 0; i < files.length; i += 10) {
  const batch = files.slice(i, i + 10);
  const form = new FormData();
  batch.forEach(f => form.append("files", f));
  await fetch(`${API}/api/extract/${sessionId}/upload`, {
    method: "POST", body: form
  });
  setProgress(Math.round((i + 10) / files.length * 100));
}

Keeping the Space warm (optional)

The free tier sleeps after 48 hours of inactivity (30-second cold start on next request). To keep it warm, add a simple ping from your frontend:

// ping every 30 minutes while the app is open
setInterval(() => fetch(`${API}/api/health`), 30 * 60 * 1000);

Or upgrade the Space to a paid CPU instance ($5/month) for always-on hosting.

Local development

# Install dependencies
pip install -r requirements.txt

# Run locally (port 8000)
uvicorn app.main:app --reload --port 8000

# API docs at: http://localhost:8000/docs

Set HF_TOKEN in your environment for local LLM testing:

export HF_TOKEN=hf_your_token_here
uvicorn app.main:app --reload --port 8000