README.md

---
library_name: peft
base_model: aubmindlab/bert-base-arabertv2
tags:
  - text-classification
  - sentiment-analysis
  - arabic
  - lora
  - peft
  - mlflow
language:
  - ar
license: mit
pipeline_tag: text-classification
---

# arabic-sentiment-lora-deploy

**Deploy bundle for the [`arabic-sentiment-mlops`](https://github.com/psjprajna/arabic-sentiment-mlops)
LoRA sentiment classifier.** Not a standalone model card — this repo
holds the *artifacts* that the FastAPI serving container fetches at
build time. The model card lives on the [running Space](https://huggingface.co/spaces/PrajnaShetty/arabic-sentiment-lora).

**Live demo:** https://prajnashetty-arabic-sentiment-lora.hf.space — try
`GET /health` and `POST /predict` (Arabic text in; positive / negative /
neutral + confidence out).

## What's in this repo

| Path                                                                  | Size    | Purpose                                                                                                            |
|-----------------------------------------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------|
| `models/arabert-lora-v1/`                                             | 2.8 MB  | LoRA adapter weights + tokenizer + labels. Used as the filesystem fallback if registry resolution fails in-container. |
| `mlflow.db`                                                           | 892 KB  | SQLite-backed MLflow registry. Holds the `arabert-lora` v1 registered model + its run lineage.                      |
| `mlruns/1/models/m-f9cac40424504a5a91d9449f38f5bd7c/`                  | 523 MB  | MLflow 3.x logged-model artefacts — the pyfunc bundle (`MLmodel`, `python_model.pkl`, nested LoRA weights).         |

Total: **27 files, ~525 MB**. LFS-tracked binaries handled by HF Hub
automatically.

## How it's consumed

The container's Dockerfile (cache-warm stage) fetches the whole repo
via `huggingface_hub.snapshot_download`:

```python
from huggingface_hub import snapshot_download

snapshot_download(
    "PrajnaShetty/arabic-sentiment-lora-deploy",
    repo_type="model",
    local_dir="/opt/deploy",
)
```

The runtime stage `COPY`s `/opt/deploy` into `/app/`, applies a
build-time SQL rewrite over six columns in `mlflow.db` (the absolute
build-host paths get retargeted to `/app/…`), and ships a torch
compatibility shim that maps MPS-tagged tensor storage to CPU at
deserialize time (the LoRA was logged on Apple Silicon; the runtime
torch wheel is Linux CPU-only).

See [`Dockerfile`](https://github.com/psjprajna/arabic-sentiment-mlops/blob/main/Dockerfile)
and [ADR-0008](https://github.com/psjprajna/arabic-sentiment-mlops/blob/main/.claude/docs/adrs/0008-hf-hub-pull-on-build.md)
in the source repo for the full mechanics.

## Model card

The model itself is an [AraBERT v2](https://huggingface.co/aubmindlab/bert-base-arabertv2)
classifier fine-tuned with LoRA on the [HARD dataset](https://github.com/elnagara/HARD-Arabic-Dataset)
for 3-class sentiment (positive / negative / neutral). Macro F1 on the
held-out test split: **0.838** (positive 0.91, negative 0.85, neutral
0.76). Dialect breakdown (per Phase 5 in the source repo): **0.80
macro F1 on Gulf** vs **0.85 on MSA** — a ~5-point gap the repo
documents rather than hides.

Hardware constraints: trained on Apple Silicon MPS (~80 min wall);
served on CPU at ~600 ms per `/predict` call on HF Spaces' free tier
(2 vCPU / 16 GB RAM).

## Loading the LoRA outside the Space

If you want to use just the LoRA adapter without the FastAPI container:

```python
from peft import PeftModel
from transformers import AutoTokenizer, AutoModelForSequenceClassification
from huggingface_hub import snapshot_download

bundle = snapshot_download(
    "PrajnaShetty/arabic-sentiment-lora-deploy",
    repo_type="model",
    allow_patterns="models/arabert-lora-v1/*",
)
base = AutoModelForSequenceClassification.from_pretrained(
    "aubmindlab/bert-base-arabertv2", num_labels=3
)
model = PeftModel.from_pretrained(base, f"{bundle}/models/arabert-lora-v1")
tokenizer = AutoTokenizer.from_pretrained(f"{bundle}/models/arabert-lora-v1")
```

## Source

- **App code + Dockerfile + ADRs:** https://github.com/psjprajna/arabic-sentiment-mlops
- **Running Space:** https://huggingface.co/spaces/PrajnaShetty/arabic-sentiment-lora
- **Live API:** https://prajnashetty-arabic-sentiment-lora.hf.space

## License

MIT. The base model ([`aubmindlab/bert-base-arabertv2`](https://huggingface.co/aubmindlab/bert-base-arabertv2))
and the [HARD dataset](https://github.com/elnagara/HARD-Arabic-Dataset)
are under their own licenses; please check there if you intend to use
this bundle outside personal / academic contexts.