---
title: LibBee
emoji: 🐝
colorFrom: blue
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
---

# LibBee 4.1.1 — KU Library Assistant

FastAPI origin for the existing Cloudflare gateway and KU LibGuides chatbot.

## Configuration

Set real credentials in Space secrets. `.env.example` documents placeholders and optional settings. Keep `ORIGIN_TOKEN` equal to the Worker's `HF_ORIGIN_TOKEN`, and `CLOUDFLARE_ADMIN_TOKEN` equal to its `ADMIN_TOKEN`.

`OPENAI_API_KEY` enables GPT and semantic embeddings. `ANTHROPIC_API_KEY`, `PRIMO_API_KEY`, and `OPENALEX_API_KEY` are optional integration keys. Live hours/events need LibCal credentials; separate events credentials are optional. `ADMIN_PASSWORD` protects the admin dashboard.

The Docker runtime uses UID 1000 and port 7860. Set `RUNTIME_DIR` to a writable durable mount if configuration, metrics, feedback and signed embeddings should survive restarts. A folder named `/data` alone does not guarantee persistent storage.

## Startup and request behavior

- `/health/live` and `/config` can respond while knowledge initialization runs in the background.
- Keyword retrieval initializes locally first; semantic retrieval joins when a valid cache loads or embeddings finish. Semantic failure leaves local retrieval available.
- `/health/ready` returns 503 when retrieval is unavailable, maintenance is on, or the production origin token is missing. It distinguishes missing model credentials from a fully configured service.
- `/agent` and its diagnostic subpaths, `/search`, and `/feedback` require the origin token in production. Student browsers call the Worker; the Worker adds this token server-side.
- The 512 KiB default whole-body limit covers bounded Unicode histories and search contexts; request models still enforce individual field limits.
- Generated answer HTML is sanitized. Credentials stay out of student HTML, provider request URLs and operational query logs.
- Signed semantic caches are invalidated by KB content and indexing settings. Older cache schemas rebuild once; modified or unsigned caches are ignored.
- Admin logout revokes persisted sessions; write diagnostics are explicit POST actions. The Worker analytics token contract remains unchanged and needs verification against your Worker source.

## Validation

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

The supplied offline tests/harnesses document their mocks and skipped integration checks. They do not replace full dependency, browser, or live-provider testing. This review did not update the supplied dependency pins; validate compatible security updates and freeze the resolved dependency set in staging.

See `DEPLOYMENT_GUIDE.md` and the complete package's `AUDIT_REPORT.md` for rollout instructions and limitations. The supplied files do not include the actual Worker or D1 schema.