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