Spaces:
Runtime error
Runtime error
| title: Worcestershire Libraries Live Assistant | |
| colorFrom: green | |
| colorTo: blue | |
| sdk: gradio | |
| sdk_version: 6.17.3 | |
| app_file: app.py | |
| pinned: true | |
| license: mit | |
| short_description: Live, source-cited answers about your local library | |
| tags: | |
| - track:backyard | |
| - sponsor:openbmb | |
| - achievement:offgrid | |
| - achievement:offbrand | |
| - achievement:llama | |
| - achievement:fieldnotes | |
| # Team Members | |
| Julian Elliott ( GameTheory ) | |
| # Worcestershire Libraries - Live Assistant | |
| A small-model (**≤ 32B**) agent that answers real questions about Worcestershire | |
| Libraries from official data **at every granularity** - service pages → every | |
| page of the Hive's site → catalogue items → the individual copies on a branch's | |
| shelf - mined live at question time wherever the source allows it. | |
| > Built for the [Build Small Hackathon](https://huggingface.co/build-small-hackathon) | |
| > · **Backyard AI** track. The "someone I know" is **Jack, a library resources | |
| > manager in Worcester**, whose recurring complaint is that *the library never | |
| > shouts loudly enough about everything it offers*. This is the megaphone. | |
| Primary Video Demo: [Youtube](https://youtu.be/0JoOqYBQv_4) | |
| Primary Video Demo: [Screen Studio](https://preview.screen.studio/share/Td6VxRdL?state=uploading) | |
| Backup Video Demo: [Arcade Demo](https://app.arcade.software/share/p5cZQyn7OZUXmR6Kqxbk) | |
| ## What it does | |
| Ask in plain English and it routes your question to a live tool, reads what comes | |
| back from the council's own systems, and explains it: | |
| | You ask… | It mines… | Source | | |
| |---|---|---| | |
| | “How do I **get** Wolf Hall?” | the item's **copy-level holdings** - which branch has it on the shelf *now*, free reservation, or the eBook on BorrowBox tonight | `wcc.ent.sirsidynix.net.uk` | | |
| | “Do you have Harry Potter audiobooks?” | the **SirsiDynix catalogue** (books, eBooks, audio, DVDs) | `wcc.ent.sirsidynix.net.uk` | | |
| | “What can I do at The Hive?” | **every page of the Hive's site** - archives & archaeology, 800+ study spaces, room hire, open 8:30am–10pm daily | `thehiveworcester.org` | | |
| | “When does the mobile library visit Abberley?” | the **mobile-library timetable** (154 villages) | `worcestershire.gov.uk` | | |
| | “What's on this week?” | **events & activities** | `worcestershire.gov.uk` | | |
| | “How do I print from my phone?” | **Print Your Way** steps & prices | `worcestershire.gov.uk` | | |
| Every reply carries a **“checked live just now” footer** with the tool used and a | |
| link back to the official page. | |
| Each answer is designed around a customer journey - what the person is trying | |
| to do and the next action the reply must hand them. See **[JOURNEYS.md](JOURNEYS.md)**. | |
| As a trusted hub within the local community, libraries often act as the public face for many wider council functions. They work with tight budgets and a mix of old systems, all while offering a huge range of services; everything from baby activity sessions to business support. | |
| This simple library chatbot helps cut through this complexity by giving people one clear, modern way to get information. Instead of fighting through outdated interfaces, residents can ask questions in plain language and receive quick, accurate answers that reflect everything the library provides. | |
| Because this low-cost tool can be built to run as a website, add-on or app, it becomes an easy, always-available point of contact. Each response can be tailored to automatically highlight related services using analytics-driven prompts, helping surface both well-used resources and lesser-known parts of the library offer. The result, a lightweight, affordable upgrade that improves access, boosts discovery, and supports libraries without requiring major system changes. | |
| ## The honest small-model fit | |
| The model never invents library facts. The intelligence lives in the **live | |
| retrieval**; a 7-8B model is more than enough to *route* the question and *phrase* | |
| the answer. That's a genuine fit with the brief - not a 32B model pretending to | |
| know a catalogue it was never trained on. | |
| - **Model:** `meta-llama/Llama-3.1-8B-Instruct` by default, with an in-app | |
| selector for OpenBMB MiniCPM 3 4B and Qwen 2.5 7B (set `MODEL_ID` to swap up | |
| to any ≤32B model). | |
| - **Graceful degradation:** with no `HF_TOKEN`, the app still works in *no-LLM | |
| mode* - deterministic keyword routing + the raw live data. The demo never | |
| breaks. | |
| ## The Hive, with provenance | |
| I originally excluded thehiveworcester.org because parts of it run stale. The | |
| re-think: **include it page-by-page, but tag every fact with its source** - | |
| because the Hive's site is the *only* place much of Worcester's extended offer | |
| is described (Explore the Past archives & archaeology, Europe's first joint | |
| university+public library, 800+ study spaces, room hire, the BIPC, the Youth | |
| Hub). The rules that keep answers trustworthy: | |
| - every Hive fact carries its **source page + crawl date** (`hive_kb.json`, | |
| rebuilt by `build_hive_kb.py`) | |
| - where Hive and council pages conflict (hours, prices, membership), the | |
| **council page wins** - and the answer says which source it used | |
| - the Hive's own events page is static, so **live events always come from the | |
| council site** | |
| ## Architecture | |
| ``` | |
| question ──▶ route() (LLM JSON router, keyword fallback) | |
| │ | |
| ▼ | |
| library_sources.py ──▶ the granularity ladder | |
| │ service • 87 council service pages (library_kb.json) | |
| │ page • 57 Hive pages, exact offer (hive_kb.json) | |
| │ item • search_catalogue() (live Atom feed) | |
| │ copy • where_to_get() (live holdings: | |
| │ shelf @ branch → reserve → BorrowBox tonight) | |
| │ plus • mobile_library() · library_events() | |
| │ • find_library() · hive_info() · printing_help() | |
| ▼ | |
| synthesize() ──▶ warm, grounded answer + named-source footer | |
| ``` | |
| `library_sources.py` has **zero** Gradio/LLM dependencies and is independently | |
| testable against the live sites: `python library_sources.py`. | |
| ## Run locally | |
| ```bash | |
| pip install -r requirements.txt gradio | |
| export HF_TOKEN=hf_xxx # optional - omit for no-LLM / offgrid mode | |
| export TRACE_DATASET=you/wpl-traces # optional - persist usage analytics (see below) | |
| python app.py # http://localhost:7860 | |
| # refresh the knowledge bases + graph any time: | |
| python build_kb.py # council pages -> library_kb.json | |
| python build_hive_kb.py # every Hive page -> hive_kb.json | |
| python graph_build.py # both KBs -> library_graph.json | |
| ``` | |
| ### No-LLM / Offgrid mode (`achievement:offgrid`) | |
| Run **without** `HF_TOKEN` and the assistant works entirely on its own - no | |
| external AI API call is made. A deterministic keyword router (400+ patterns) | |
| handles every question and returns the raw live data directly. This is the | |
| `achievement:offgrid` mode: the library data still comes from the council's | |
| own public website, but the intelligence layer requires no third-party model | |
| service whatsoever. | |
| ```bash | |
| python app.py # no HF_TOKEN → keyword-only, zero AI API calls | |
| ``` | |
| The UI flags this mode clearly and all tools remain fully functional. | |
| ### Usage analytics (optional) | |
| The Space's container is wiped on every reboot, so the local `traces.jsonl` | |
| never accumulates. Set **`TRACE_DATASET`** (e.g. `you/wpl-traces`) with a | |
| write-scoped `HF_TOKEN` and every turn is persisted to a **private** Hugging | |
| Face Dataset - one small file per turn, written on a background worker so it | |
| adds no latency and can never break an answer. Unset, it's a silent no-op. | |
| That gives a queryable record of real behaviour to iterate on: questions that | |
| fall through to the help text (`route.tool == "none"` - a coverage gap), turns | |
| where the LLM router failed over to keyword matching (`route.router == | |
| "keyword"`), and flaky live sources (a step with `ok == false`). Questions are | |
| user input, so the dataset is created private. | |
| ## License | |
| MIT - © Julian Elliott ( GameTheory ) | |