| --- |
| title: LibBee |
| emoji: 🐝 |
| colorFrom: blue |
| colorTo: yellow |
| sdk: docker |
| app_file: app.py |
| pinned: false |
| --- |
| |
| # 🐝 LibBee — KU Library AI Assistant |
|
|
| An open-source, institution-aware AI library assistant for Khalifa University Library, Abu Dhabi, UAE. |
|
|
| Built with FastAPI, hybrid FAISS + BM25 RAG, and live LibCal integration. |
|
|
| **Live interface:** https://ku-library.github.io/LibBee |
| **GitHub:** https://github.com/ku-library/LibBee |
|
|
| --- |
|
|
| ## Architecture |
|
|
| - **Backend:** FastAPI + Python 3.9 (this Space) |
| - **Frontend:** GitHub Pages (single-file HTML/JS) |
| - **RAG:** FAISS dense + BM25 sparse + RRF fusion |
| - **Live data:** LibCal API via Cloudflare Worker proxy |
| - **Analytics:** Cloudflare D1 |
|
|
| ## Secrets required |
|
|
| Set these in the Space **Settings → Variables and Secrets**: |
|
|
| | Secret | Description | |
| |---|---| |
| | `OPENAI_API_KEY` | Required for classification and answering | |
| | `ANTHROPIC_API_KEY` | Optional — enables Claude Haiku toggle | |
| | `PRIMO_API_KEY` | Required for PRIMO discovery search | |
| | `ADMIN_PASSWORD` | Required for /admin dashboard | |
| | `CLOUDFLARE_WORKER_URL` | Required for live hours/events and analytics | |
| | `SESSION_SECRET` | Required for admin session | |
|
|
| ## Version |
|
|
| **v3.7** — Navigation-first agentic AI. See GitHub for changelog. |
|
|
| ## Architecture (v3.8) |
|
|
| The pipeline is split by stage under `src/agentcore/` - each module's docstring |
| explains its role: |
|
|
| | Module | Role | |
| |---|---| |
| | `models.py` | Pydantic I/O contracts | |
| | `constants.py` | Regexes, URLs, prompts (no logic) | |
| | `utils.py` | Shared helpers, LLM factory, query/URL builders | |
| | `classify.py` | Rule pre-classifier + LLM intent classifier | |
| | `libcal.py` | Live hours/events via Cloudflare Worker proxy | |
| | `scholarly.py` | OpenAlex, Semantic Scholar, Crossref, Unpaywall clients | |
| | `rendering.py` | HTML fragments (badges, trace blocks, AI-tools footer) | |
| | `intents_library.py` | library_info handlers | |
| | `intents_search.py` | search_academic / search_medical machinery | |
| | `intents_general.py` | general / social handlers | |
| | `orchestrator.py` | Injection gate, routing pipeline, analytics logging | |
|
|
| `src/api/agent.py` is a thin router. Tests: `pytest tests/ -q` (20 tests, no |
| API keys required). |
|
|
| ## Environment variables (new in v3.8) |
|
|
| | Variable | Purpose | |
| |---|---| |
| | `CLOUDFLARE_WORKER_TOKEN` | Bearer token for the Worker analytics surface; must equal the Worker's `ANALYTICS_TOKEN` secret | |
| | `CONTACT_EMAIL` | Polite-pool contact sent to OpenAlex / Unpaywall / Crossref (default `library@ku.ac.ae`) | |
|
|
| ## Privacy |
|
|
| Before any query reaches metrics or the D1 analytics store it passes |
| `_redact_for_analytics`: e-mail addresses and digit runs of 6+ are masked and |
| text is truncated to 200 characters. Answer excerpts logged for the daily |
| relevance agent get the same treatment. The Worker applies the identical |
| redaction server-side as defence in depth. |
|
|
