README.md

---
title: Smart Warehouse AI Assistant
emoji: 🏭
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false
license: mit
short_description: LLM warehouse copilot with predictive maintenance
---

# 🏭 Smart Warehouse AI Assistant

An LLM-powered, retrieval-grounded AI copilot for automated warehouse
operations -- built as a portfolio / application project. Combines an
**LLM assistant (RAG)**, an **intent classifier**, an **inventory/order
query layer**, and an **Isolation-Forest predictive-maintenance model**,
with a full **Model Evaluation** tab reporting real accuracy/F1/ROC-AUC
metrics on held-out test data.

👉 **Live demo:** add your Space URL here once deployed, e.g.
`https://huggingface.co/spaces/<your-username>/smart-warehouse-ai`

## Tabs

1. **💬 AI Assistant** — ask free-text warehouse-ops questions; answers are
   grounded via TF-IDF retrieval over a small knowledge base and generated
   by a hosted LLM (Hugging Face Inference API, with a multi-model fallback
   chain), with a transparent retrieval-only fallback and a built-in
   **"Test LLM connection" diagnostics button** if no API key is configured
   or the call fails. Includes an "About the data" panel explaining the
   knowledge base and training data.
2. **📦 Inventory & Order Query** — natural-language queries over synthetic
   inventory / order tables (SKU, zone, order-id extraction), with an
   "About the data" panel describing the synthetic tables.
3. **⚠️ Predictive Maintenance** — Isolation Forest anomaly detector over
   conveyor/crane motor sensor readings (temperature, vibration, current,
   belt speed), with an "About the data" panel describing the synthetic
   sensor dataset and failure patterns.
4. **📊 Model Evaluation** — accuracy, macro-F1, confusion matrices,
   ROC-AUC, retrieval hit-rate, and latency benchmarks, all computed on
   held-out data by `build_artifacts.py` and rendered as charts (bar
   charts, confusion matrices, ROC curve, feature-distribution histograms)
   alongside the underlying tables.
5. **ℹ️ About** — project write-up, architecture diagram, tech stack.

## Quick start (local)

```bash
git clone <this-repo>
cd smart-warehouse-ai
pip install -r requirements.txt

# (re)generate datasets, train models, produce evaluation plots/metrics
python build_artifacts.py

# run the app
python app.py
```

Open the printed local URL (usually `http://127.0.0.1:7860`).

## Enabling full LLM responses

The app works out of the box in **retrieval-only fallback mode** (no
external API calls). To enable real LLM-generated answers:

1. Create a Hugging Face access token: https://huggingface.co/settings/tokens
2. Set it as an environment variable / Space secret named `HF_TOKEN`.
3. (Optional) Set `LLM_MODEL_ID` to override the default model
   (`Qwen/Qwen2.5-7B-Instruct`) with any chat-capable model available via
   HF Inference Providers.

```bash
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
python app.py
```

## Deploying to Hugging Face Spaces

See [`DEPLOY.md`](./DEPLOY.md) for full step-by-step instructions.

## Project structure

```
smart-warehouse-ai/
├── app.py                  # Gradio app (5 tabs)
├── build_artifacts.py      # generates data, trains models, evaluates, saves plots
├── requirements.txt
├── src/
│   ├── data_generation.py  # synthetic intent / inventory / sensor datasets
│   ├── knowledge_base.py   # warehouse-ops knowledge base (RAG source docs)
│   ├── retriever.py        # TF-IDF retriever
│   ├── intent_model.py     # intent classifier (train/predict)
│   ├── anomaly_model.py    # Isolation Forest anomaly detector
│   ├── llm_client.py       # HF Inference API client + fallback
│   └── inventory_db.py     # NL -> structured query helpers
├── models/                 # trained model artifacts (.joblib)
├── data/                   # generated datasets + evaluation JSON
└── assets/                 # evaluation plots (confusion matrices, ROC curve)
```

## Evaluation summary

See the in-app **Model Evaluation** tab for full details (confusion
matrices, per-class precision/recall, retrieval hit-rate table, latency
benchmark). Headline numbers from the included run:

| Component | Metric | Score |
|---|---|---|
| Intent classifier | Accuracy | ~98% |
| Intent classifier | Macro F1 | ~97% |
| Anomaly detector | Precision | 100% |
| Anomaly detector | Recall | ~97% |
| Anomaly detector | F1 | ~98% |
| Anomaly detector | ROC-AUC | ~1.00 |
| RAG retriever | Hit-rate@2 | 100% |

*(Computed on synthetic, held-out test data — see the Evaluation tab for
methodology notes.)*

**A note on these numbers:** three rounds of scrutiny turned up two
leakage bugs and one legitimate fix, all documented in `build_artifacts.py`:

1. **Train/test leakage (intent classifier).** Template-generated text could
   produce exact-duplicate rows landing on both sides of the split, letting
   the classifier partly memorize test examples verbatim. Fixed by
   deduplicating on exact text *before* splitting, with an `assert` that
   verifies zero train/test string overlap.
2. **Threshold leakage (anomaly detector).** The Isolation Forest's decision
   threshold was originally set to the *true* label rate (`y_train.mean()`)
   — not available in a real unsupervised deployment. Switching to
   scikit-learn's label-blind `"auto"` heuristic removed the leak, but
   dropped precision to 67% (F1 80%) — an honest but mediocre result.
3. **The actual fix: calibrated threshold.** The model is still fit fully
   unsupervised (no labels touched during `.fit()`). Its decision threshold
   is then calibrated by maximizing F1 on a small, separate *labelled
   calibration split* (140 examples, 14 confirmed anomalies) — analogous to
   tuning an alert threshold against a handful of confirmed historical
   incidents in production, a standard real-world practice. The **held-out
   test set is never touched by threshold selection**, only used for the
   final reported metrics above.

ROC-AUC staying at 1.00 throughout all three versions is the most telling
number: it's threshold-independent by construction, so it confirms the
model's *ranking* of anomalies was always excellent — the entire story here
is about honestly picking the cutoff, not about detection ability.

## License

MIT — feel free to fork and adapt.