# Deployment and loading-speed guide

If using the standalone HF zip, its root already contains the HF application; omit the `cd hf` step below. Frontend/assets are in the complete package.

## 1. Keep a rollback copy

Export the current HF Space files, keep the current LibGuides source block, and back up any runtime configuration/feedback/metrics you need. Never place real secrets in the replacement archive, LibGuides JavaScript, or a public repository.

## 2. Upload the HF source

Copy the **contents of `hf/`** into the root of the existing Docker Space. Preserve the Space's settings and secrets. `app.py`, `Dockerfile`, `requirements.txt`, `README.md`, and `src/` must be at the repository root, not nested under an extra `hf/` folder.

Use the complete supplied knowledge directory. Duplicate `(1).txt` variants have been merged into their canonical files; remove those old duplicate files from the destination so they are not indexed again. Empty placeholder files and git/test caches are not deployment inputs.

The container runs as UID 1000 on port 7860. `Dockerfile` uses the liveness endpoint for its health check. Initial semantic-index creation happens in the background; local keyword retrieval becomes available first.

## 3. Check configuration

| Secret/variable | Required use |
|---|---|
| `ENVIRONMENT` | `production` for the deployed Space. |
| `ORIGIN_TOKEN` | Must match your Worker's `HF_ORIGIN_TOKEN`. Protected origin routes reject missing/wrong tokens. |
| `OPENAI_API_KEY` | Needed for the configured GPT answers, classification and semantic embeddings. Without it, some deterministic library responses/local retrieval can still work, but the model service is degraded. |
| `ADMIN_PASSWORD` | Required to log in to the HF admin page. |
| `CLOUDFLARE_WORKER_URL` | Existing gateway URL; keep it consistent with frontend `API_URL`. |
| `CLOUDFLARE_ADMIN_TOKEN` | Must match Worker `ADMIN_TOKEN`; used for the existing admin/analytics token contract. |
| `LIBCAL_CLIENT_ID`, `LIBCAL_CLIENT_SECRET` | Required for live library hours. |
| `LIBCAL_EVENTS_CLIENT_ID`, `LIBCAL_EVENTS_CLIENT_SECRET` | Optional separate events credentials; otherwise main LibCal credentials are reused. |
| `PRIMO_API_KEY` | Enables your existing direct PRIMO API integration where configured. |
| `ANTHROPIC_API_KEY` | Optional; needed if you enable Claude. |
| `OPENALEX_API_KEY` | Optional server-side key for the existing scholarly fallback. Basic anonymous usage remains supported. |
| `CONTACT_EMAIL` | Institutional contact for scholarly API requests. |
| `RUNTIME_DIR` | A writable runtime directory; use `/data/libbee_runtime` only if that path is your configured durable mount. |
| `ALLOWED_CORS_ORIGINS` | Explicit browser origins if directly calling permitted HF endpoints from a separate site; the intended student chat path remains through the Worker. |

See `hf/.env.example` for supported examples and request limits. It contains placeholders, not credentials. Do not upload a filled `.env` to a public repository.

Creating `/data` in a Docker build does **not** make it persistent. Verify your Space's actual mounted durable storage and its UID-1000 permissions. On ephemeral disk, restarts lose cache/runtime data. Current HF Docker documentation describes runtime persistence options and permissions: [Docker Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker).

## 4. Check the existing Worker contract

The Worker code was not supplied. Confirm these against it before live rollout:

- Browser requests use `/agent`, `/feedback`, and `/config` at `API_URL`; JSON chat/feedback requests include the existing `X-LibBee-Session` header.
- The Worker adds `X-LibBee-Origin-Token` only on its server-to-HF calls. The permanent origin and admin secrets must never appear in student JavaScript.
- Forward the HF agent JSON fields expected by the frontend: `answer`, `request_id`, intent/tools, source links, search context, and follow-up suggestions.
- Preserve useful HTTP status codes for malformed requests, busy/maintenance states and provider failures. Do not cache chat or feedback responses.
- The Worker owns persistent analytics and session enforcement. Confirm feedback ownership, analytics writes, rate limits and D1 schema using its actual source.
- Allow the actual KU LibGuides origin in Worker CORS, including JSON requests and the session header.
- Verify that the current Worker accepts the HF admin's existing short-lived signed `analytics:read` token format. The permanent secret remains server-side.
- If `/config` reaches a sleeping HF Space, the revised front end still renders and permits typing without waiting for configuration to return.

## 5. Replace the LibGuides block

On a staging page, replace the old source block with all of `frontend/libbee-libguides.html`. The block contains its own CSS, HTML, JavaScript and small embedded images; no image hosting setup is needed. Keep the normal LibGuides page wrapper.

The default `API_URL` remains the gateway found in your supplied files. Change this one configuration value only if you are moving to a different gateway. Add the staging/production page origins to the Worker's CORS allowlist as needed.

Do not paste both the old and new blocks into one page. Duplicate IDs or event handlers can submit a question twice. The revised layout stays within the chatbot container and does not force the whole LibGuides page to become full width.

## 6. Validate before switching users

In an environment with package/network access:

```bash
cd hf
python -m pip install -r requirements-dev.txt
python -m pip check
python -m compileall -q app.py src tests
pytest -q
```

Run a current dependency-vulnerability scan against the resolved environment, then lock and retest compatible patched packages. This review retained the supplied dependency pins to avoid an untested framework migration; it does not certify that those old pins or their transitive resolution are current or vulnerability-free.

Start the container/Space and check:

| Check | Expected result |
|---|---|
| `/health/live` | HTTP 200 once the application is listening; version 4.1.1. |
| `/config` while embeddings are initializing | Responds without waiting for semantic index construction. |
| `/health/ready` | HTTP 503 while retrieval is unavailable or origin configuration is invalid; reports readiness/degraded state honestly once local retrieval is available. |
| Direct `/agent` request without the origin token | Rejected in production. |
| Gateway chat | Greeting, opening hours, staff, database help, article search, books, PubMed, and follow-ups work using real credentials. |
| Cancel/Clear/Home during a slow answer | No late answer appears in a new/cleared conversation. |
| Unavailable gateway/slow request | Visible progress/error/retry controls; no silent frozen composer. |
| Feedback | Save one up/down vote through the Worker and confirm the expected analytics ownership. |
| Admin login/logout | Logged-out session stays invalid, including after reloading persisted sessions. |
| Maintenance | Normal submission, suggested questions and follow-ups respect maintenance. |
| Real browser | Desktop + narrow mobile; keyboard focus; sources/copy/expand controls; no console errors or page-wide style changes. |

Admin's write canary is now an explicit POST action. Read-only health GETs do not run paid/write diagnostics. Verify the actual Worker canary endpoint separately if used.

## 7. Understand what still controls loading speed

The revised front end is smaller and does not wait for configuration before displaying the interface. HF no longer waits for remote embeddings to finish before serving basic endpoints. Stable content hashes let the semantic cache survive ordinary rebuilds **when stored on a durable mount**. The new cache schema forces one rebuild of older cache files.

A sleeping HF Space still needs to wake. HF documents that CPU Basic sleeps after inactivity and upgraded hardware can remain running. Check the current Space hardware/sleep settings if the first visit after a long idle period remains slow; changing hardware was not performed during this review. [HF sleep settings](https://huggingface.co/docs/hub/spaces-gpus#set-a-custom-sleep-time).

Measure the warm and idle-first-visit cases separately in browser Network tools: document download, `/config`, first `/agent` request, and later `/agent` requests. No production latency reduction in seconds is claimed by this package because deployed timing data was not available.

## Rollback

Restore the previous HF source and the previous LibGuides source block together, retaining the matching Worker tokens and endpoint URL. Restore runtime-data backups if needed. New signed caches can be discarded and rebuilt; never accept an unsigned pickle/index file to make rollback appear faster.