DEPLOY.md

# Deploying to Hugging Face Spaces

## A note on hardware / ZeroGPU

This app is **CPU-only by design** — all local ML (intent classifier,
anomaly detector, TF-IDF retrieval) runs on scikit-learn, and the LLM
call goes to the remote HF Inference API rather than running locally.

If your account only offers the **ZeroGPU** hardware tier (some free/new
accounts can't select CPU-basic for new Spaces), that's fine: `app.py`
includes a small `@spaces.GPU`-decorated health-check function purely so
the platform's ZeroGPU compatibility check passes at startup. It's never
called on the actual request path, so it adds no latency or GPU cost —
you can safely select ZeroGPU hardware when creating the Space.

Two ways to deploy: the web UI (easiest, no git needed) or the CLI/git route.

## Option A — Web UI upload (fastest)

1. Go to https://huggingface.co/new-space
2. Fill in:
   - **Space name:** e.g. `daifuku-warehouse-ai`
   - **License:** MIT (or your choice)
   - **Select the Space SDK:** **Gradio**
   - **Space hardware:** CPU basic (free tier is enough for this app)
   - Visibility: **Public** (so you can share the link with Daifuku)
3. Click **Create Space**.
4. On the new Space page, click **Files → Add file → Upload files**, and
   upload the *entire project folder contents* (keep the folder structure:
   `app.py`, `requirements.txt`, `README.md`, `src/`, `models/`, `data/`,
   `assets/`). Drag-and-drop the whole folder works in most browsers.
5. Wait for the Space to build (check the **Logs** tab if it fails — almost
   always a missing/incompatible package version).
6. Once it shows "Running", your demo is live at:
   `https://huggingface.co/spaces/<your-username>/daifuku-warehouse-ai`

## Option B — git (recommended if you'll keep iterating)

```bash
# 1. Install the CLI and log in (needs a token with "write" scope)
pip install huggingface_hub
huggingface-cli login

# 2. Create the Space (or create it via the web UI first, then just clone it)
huggingface-cli repo create daifuku-warehouse-ai --type space --space_sdk gradio

# 3. Clone it, copy in the project files, and push
git clone https://huggingface.co/spaces/<your-username>/daifuku-warehouse-ai
cd daifuku-warehouse-ai
cp -r /path/to/this/project/* .
git add .
git commit -m "Initial commit: Smart Warehouse AI Assistant"
git push
```

The Space will automatically build from `requirements.txt` and launch
`app.py` (as declared in the README's YAML front matter: `sdk: gradio`,
`app_file: app.py`).

## Enabling the LLM (recommended before sharing with Daifuku)

By default the Space runs in **retrieval-only fallback mode** — it still
works, but answers are extractive rather than LLM-generated. To turn on
real LLM responses:

1. Create an access token at https://huggingface.co/settings/tokens
   (a "Read" token is sufficient for Inference API calls).
2. In your Space, go to **Settings → Variables and secrets → New secret**.
   - Name: `HF_TOKEN`
   - Value: your token
3. (Optional) Add another secret/variable `LLM_MODEL_ID` if you want a
   different hosted model than the default `Qwen/Qwen2.5-7B-Instruct`
   (any chat-capable model available via HF Inference Providers works).
4. Restart the Space (**Settings → Factory reboot**, or just wait — it
   picks up new secrets on the next restart).

**Note on the API endpoint:** `src/llm_client.py` explicitly passes
`provider="auto"` to `InferenceClient`, and `requirements.txt` pins a
recent `huggingface_hub` version. Both matter:
- Older client versions / omitting the provider can silently route calls
  through the now-deprecated `api-inference.huggingface.co` domain, which
  fails with a DNS resolution error rather than a clear auth error.
- Hardcoding a specific provider (e.g. `"hf-inference"`) can fail with
  *"Model not supported by provider ..."* for models that are actually
  hosted via a different backend (Together, Fireworks, Novita, SambaNova,
  etc.) under HF's Inference Providers system. `provider="auto"` lets HF's
  router pick whichever backend actually serves each candidate model.

If you ever see errors in the "Test LLM connection" diagnostics, they'll
show you exactly which of the above it is per candidate model.

## Re-training / updating the models

The Space **loads pre-built artifacts** from `models/` and `data/` — it
does not retrain on startup, so boot time stays fast. If you change
`src/data_generation.py`, `src/intent_model.py`, or `src/anomaly_model.py`,
regenerate everything locally before pushing:

```bash
python build_artifacts.py
git add models/ data/ assets/
git commit -m "Retrain models"
git push
```

## Sharing with Daifuku

Once it's live, share the Space URL directly:

```
https://huggingface.co/spaces/<your-username>/daifuku-warehouse-ai
```

Consider also linking the **Model Evaluation** tab specifically in your
application/cover letter, since it's the clearest evidence of rigorous,
reproducible ML work rather than just a UI demo.