README.md

metadata

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

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.