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