README.md

metadata

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)

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.

export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
python app.py

Deploying to Hugging Face Spaces

See 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.