First commit

.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+results/
+
+__huggingface_repos__.json

.python-version

@@ -0,0 +1 @@
+3.12

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.11-slim
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN uv pip install --system --no-cache -r requirements.txt
+
+COPY main.py .
+COPY results ./results
+
+EXPOSE 8000
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -0,0 +1,110 @@
+# Sentiment API
+
+Fine-tune **DistilBERT** on the SST-2 dataset and serve it as a REST API with FastAPI.
+
+## Overview
+
+| | |
+|---|---|
+| **Model** | `distilbert-base-uncased` fine-tuned on SST-2 |
+| **Task** | Binary sentiment classification (POSITIVE / NEGATIVE) |
+| **Dataset** | [GLUE SST-2](https://huggingface.co/datasets/glue) — Stanford Movie Reviews |
+| **Serving** | FastAPI + Uvicorn |
+| **Packaging** | Docker |
+| **Deps** | [uv](https://github.com/astral-sh/uv) |
+
+## Project structure
+
+```
+.
+├── main.py          # FastAPI inference server
+├── train.py         # Training script (fine-tunes DistilBERT, saves to results/)
+├── Dockerfile       # Production container
+├── pyproject.toml   # Project metadata and dependencies
+├── requirements.txt # Pinned requirements for Docker
+└── results/         # Training output — gitignored
+    └── best_model/  # Saved model loaded by the API
+```
+
+## Quickstart
+
+### 1. Install dependencies
+
+```bash
+uv sync
+```
+
+### 2. Train the model
+
+```bash
+uv run python train.py
+```
+
+This downloads `distilbert-base-uncased` and the SST-2 dataset from HuggingFace, fine-tunes the model, and saves the best checkpoint to `results/best_model/`.
+
+### 3. Run the API
+
+```bash
+uv run python -m uvicorn main:app --reload
+```
+
+> **Note (Windows):** `fastapi dev` / `uvicorn` trampolines are broken in some uv versions on Windows. Use `python -m uvicorn` instead.
+
+The API is available at `http://localhost:8000`. Interactive docs at `http://localhost:8000/docs`.
+
+## API endpoints
+
+### `GET /`
+Health check.
+```json
+{"status": "ok", "model": "./results/best_model"}
+```
+
+### `POST /predict`
+Single text prediction.
+
+**Request:**
+```json
+{"text": "This movie was absolutely fantastic!"}
+```
+
+**Response:**
+```json
+{
+  "text": "This movie was absolutely fantastic!",
+  "label": "POSITIVE",
+  "score": 0.9987,
+  "latency_ms": 12.4
+}
+```
+
+### `POST /predict/batch`
+Batch prediction (up to 32 texts).
+
+**Request:**
+```json
+{"texts": ["Great film!", "Terrible waste of time."]}
+```
+
+**Response:**
+```json
+{
+  "results": [
+    {"text": "Great film!", "label": "POSITIVE", "score": 0.9981, "latency_ms": 6.1},
+    {"text": "Terrible waste of time.", "label": "NEGATIVE", "score": 0.9973, "latency_ms": 6.1}
+  ],
+  "total_latency_ms": 12.3
+}
+```
+
+## Docker
+
+```bash
+# Build
+docker build -t ml-api .
+
+# Run
+docker run -p 8000:8000 ml-api
+```
+
+The Dockerfile installs dependencies via uv and serves the API on port 8000.

main.py

@@ -0,0 +1,107 @@
+import time
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+from transformers import pipeline
+
+MODEL_PATH = "./results/best_model"
+
+ml: dict = {}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print(f"Loading model from {MODEL_PATH} ...")
+    ml["pipe"] = pipeline(
+        "text-classification",
+        model=MODEL_PATH,
+        tokenizer=MODEL_PATH,
+        truncation=True,
+        max_length=128,
+    )
+    print("Model is ready")
+    yield
+    ml.clear()
+
+
+app = FastAPI(
+    title="Sentiment API",
+    description="DistilBERT fine-tuned on SST-2 — binary sentiment classification",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+
+class PredictRequest(BaseModel):
+    text: str = Field(
+        ...,
+        min_length=1,
+        max_length=512,
+        example="This movie was absolutely fantastic!",
+    )
+
+
+class PredictResponse(BaseModel):
+    text: str
+    label: str  # "POSITIVE" | "NEGATIVE"
+    score: float  # confidence 0–1
+    latency_ms: float
+
+
+class BatchRequest(BaseModel):
+    texts: list[str] = Field(
+        ...,
+        min_length=1,
+        max_length=32,
+        example=["Great film!", "Terrible waste of time."],
+    )
+
+
+class BatchResponse(BaseModel):
+    results: list[PredictResponse]
+    total_latency_ms: float
+
+
+@app.get("/", tags=["health"])
+def health():
+    return {"status": "ok", "model": MODEL_PATH}
+
+
+@app.post("/predict", response_model=PredictResponse, tags=["inference"])
+def predict(req: PredictRequest):
+    if "pipe" not in ml:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    t0 = time.perf_counter()
+    result = ml["pipe"](req.text)[0]
+    latency = (time.perf_counter() - t0) * 1000
+
+    return PredictResponse(
+        text=req.text,
+        label=result["label"],
+        score=round(result["score"], 4),
+        latency_ms=round(latency, 2),
+    )
+
+
+@app.post("/predict/batch", response_model=BatchResponse, tags=["inference"])
+def predict_batch(req: BatchRequest):
+    if "pipe" not in ml:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    t0 = time.perf_counter()
+    raw = ml["pipe"](req.texts)
+    total_latency = (time.perf_counter() - t0) * 1000
+
+    results = [
+        PredictResponse(
+            text=text,
+            label=r["label"],
+            score=round(r["score"], 4),
+            latency_ms=round(total_latency / len(req.texts), 2),
+        )
+        for text, r in zip(req.texts, raw)
+    ]
+
+    return BatchResponse(results=results, total_latency_ms=round(total_latency, 2))

pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "hf-training"
+version = "0.1.0"
+description = "Fine-tune DistilBERT on SST-2 sentiment classification"
+requires-python = ">=3.10"
+dependencies = [
+    "torch>=2.2.0",
+    "transformers>=4.40.0",
+    "datasets>=2.19.0",
+    "evaluate>=0.4.1",
+    "accelerate>=0.29.0",
+    "scikit-learn>=1.4.0",
+    "fastapi>=0.111.0",
+    "uvicorn[standard]>=0.29.0",
+]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=6.29.0",
+]

requirements.txt

@@ -0,0 +1,62 @@
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.12.1
+certifi==2026.2.25
+click==8.3.1
+colorama==0.4.6
+dnspython==2.8.0
+email-validator==2.3.0
+fastapi==0.135.1
+fastapi-cli==0.0.24
+fastapi-cloud-cli==0.14.0
+fastar==0.8.0
+filelock==3.25.0
+fsspec==2026.2.0
+h11==0.16.0
+hf-xet==1.3.2
+httpcore==1.0.9
+httptools==0.7.1
+httpx==0.28.1
+huggingface-hub==1.6.0
+idna==3.11
+jinja2==3.1.6
+joblib==1.5.3
+markdown-it-py==4.0.0
+markupsafe==3.0.3
+mdurl==0.1.2
+mpmath==1.3.0
+networkx==3.6.1
+numpy==2.4.2
+packaging==26.0
+pydantic==2.12.5
+pydantic-core==2.41.5
+pydantic-extra-types==2.11.0
+pydantic-settings==2.13.1
+pygments==2.19.2
+python-dotenv==1.2.2
+python-multipart==0.0.22
+pyyaml==6.0.3
+regex==2026.2.28
+rich==14.3.3
+rich-toolkit==0.19.7
+rignore==0.7.6
+safetensors==0.7.0
+scikit-learn==1.8.0
+scipy==1.17.1
+sentry-sdk==2.54.0
+setuptools==82.0.0
+shellingham==1.5.4
+starlette==0.52.1
+sympy==1.14.0
+threadpoolctl==3.6.0
+tokenizers==0.22.2
+torch==2.10.0
+tqdm==4.67.3
+transformers==5.3.0
+typer==0.24.1
+typing-extensions==4.15.0
+typing-inspection==0.4.2
+urllib3==2.6.3
+uvicorn==0.41.0
+watchfiles==1.1.1
+websockets==16.0

train.py

@@ -0,0 +1,121 @@
+import time
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+from transformers import pipeline
+
+# ── Config ────────────────────────────────────────────────────────────────────
+
+MODEL_PATH = "./results/best_model"  # produced by train.py
+
+
+# ── Lifespan (load model once on startup) ─────────────────────────────────────
+
+ml: dict = {}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print(f"Loading model from {MODEL_PATH} ...")
+    ml["pipe"] = pipeline(
+        "text-classification",
+        model=MODEL_PATH,
+        tokenizer=MODEL_PATH,
+        truncation=True,
+        max_length=128,
+    )
+    print("Model ready ✅")
+    yield
+    ml.clear()
+
+
+# ── App ───────────────────────────────────────────────────────────────────────
+
+app = FastAPI(
+    title="Sentiment API",
+    description="DistilBERT fine-tuned on SST-2 — binary sentiment classification",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+
+# ── Schemas ───────────────────────────────────────────────────────────────────
+
+
+class PredictRequest(BaseModel):
+    text: str = Field(
+        ...,
+        min_length=1,
+        max_length=512,
+        example="This movie was absolutely fantastic!",
+    )
+
+
+class PredictResponse(BaseModel):
+    text: str
+    label: str  # "POSITIVE" | "NEGATIVE"
+    score: float  # confidence 0–1
+    latency_ms: float
+
+
+class BatchRequest(BaseModel):
+    texts: list[str] = Field(
+        ...,
+        min_length=1,
+        max_length=32,
+        example=["Great film!", "Terrible waste of time."],
+    )
+
+
+class BatchResponse(BaseModel):
+    results: list[PredictResponse]
+    total_latency_ms: float
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+
+@app.get("/", tags=["health"])
+def health():
+    return {"status": "ok", "model": MODEL_PATH}
+
+
+@app.post("/predict", response_model=PredictResponse, tags=["inference"])
+def predict(req: PredictRequest):
+    if "pipe" not in ml:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    t0 = time.perf_counter()
+    result = ml["pipe"](req.text)[0]
+    latency = (time.perf_counter() - t0) * 1000
+
+    return PredictResponse(
+        text=req.text,
+        label=result["label"],
+        score=round(result["score"], 4),
+        latency_ms=round(latency, 2),
+    )
+
+
+@app.post("/predict/batch", response_model=BatchResponse, tags=["inference"])
+def predict_batch(req: BatchRequest):
+    if "pipe" not in ml:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    t0 = time.perf_counter()
+    raw = ml["pipe"](req.texts)
+    total_latency = (time.perf_counter() - t0) * 1000
+
+    results = [
+        PredictResponse(
+            text=text,
+            label=r["label"],
+            score=round(r["score"], 4),
+            latency_ms=round(total_latency / len(req.texts), 2),
+        )
+        for text, r in zip(req.texts, raw)
+    ]
+
+    return BatchResponse(results=results, total_latency_ms=round(total_latency, 2))