AILT9019 Group 44 · The University of Hong Kong

Find a study spot that is actually open.

HKU publishes opening hours one date at a time. This project turns the official schedule into one answer: which of sixteen study spaces is open now, how long it stays open, and how busy it is reported to be.

Dashboard showing three recommended study spaces: Main Library open for two more hours, Chi Wah Learning Commons Level 1 open for ten hours, and Library 24 open around the clock.
The deployed app ranking open spaces by status, campus, remaining hours and crowd reports.
  • 16study spaces in the catalogue
  • 4dates checked on every refresh
  • 5opening states, including Unknown
  • 3reports needed for a current estimate

01 · Problem and users

One question, answered by five different pages.

HKU students choose between libraries, learning commons, 24-hour rooms and specialist collections across four campuses. Deciding where to go needs three facts at once: whether the place is open, how long until it closes, and whether it is already busy. Each fact lives somewhere else.

The Libraries publish a per-date schedule used by their own hours page. Chi Wah Learning Commons publishes separately through ITS. Crowd levels are not published at all. None of these sources answers which of the sixteen places is worth walking to in the next ten minutes.

Who this is for

  • Students between classes who need a seat within a short walk.
  • Late-night studiers who need to know whether a 24-hour room is open.
  • Students during revision periods, when floor-level crowding changes hourly.

02 · How it works

From official hours to one ranked answer.

Opening status, crowd estimates and ranking are computed in code. A language model is used only to phrase a chat answer from records the app has already retrieved.

Online path Browser Cloudflare WorkerAPI, page and scheduled refresh D1reports, hours cache, usage The Worker also calls HKUL, Cloudflare Workers AI and DeepSeek.

Opening hours

  1. HKUL daily JSONplus the maintained Chi Wah schedule
  2. Fetch and cachefour dates, ETag revalidation
  3. Status calculationopen, closing, closed or unknown

Crowd reports

  1. Anonymous reports1–5 rating, hashed token
  2. Validation and storagecooldown, daily limit, D1
  3. Crowd estimatecurrent, typical or conflicting

Ranking

  1. Status, crowd and venue facts16 catalogued spaces
  2. Scoringweighted score with reasons
  3. API and pageJSON, cards, details

Assistant

  1. Question and recordsvenue data, public documents
  2. Retrieval and guardrailsrefuses seat, booking, Wi-Fi
  3. Local answer or DeepSeekmodel only rephrases
  4. Answer with sourcescited venue links

Voice input

  1. Recordup to 20 seconds
  2. TranscribeCloudflare Workers AI Whisper
  3. Editable textadded to the question box
  4. Sendthe user submits the question

The Python service in app/ is a local reference implementation of the same behaviour. It is not part of the online request path.

1

Fetch four dates

Yesterday, today, tomorrow and the day after are fetched with ETag revalidation. If the source fails, a cache younger than 48 hours is used; anything older becomes Unknown.

2

Resolve a status

Weekly intervals, overnight ranges and per-date exceptions are merged in Hong Kong time. The result is one of five states plus the next transition, so “closes in 40 minutes” is derived from the schedule.

3

Estimate, then rank

Crowd evidence is combined with opening status, campus, space size and remaining hours. The score and its reasons are returned by the API, so the ordering can be checked.

03 · What we built

What the team wrote, and what it runs on.

Built by the team

  • The catalogue of 16 study spaces with access notes and source links.
  • The schedule parser and Hong Kong status engine, including overnight ranges and date exceptions.
  • The HKUL ingestion layer: four-date window, ETag cache, staleness limits and Unknown states.
  • The crowd estimator: validation, hashed tokens, cooldown, sample thresholds and a conflict state.
  • The recommendation score and its reasons.
  • Keyword retrieval over curated public documents, with guardrails for seat counts, bookings and Wi-Fi.
  • Voice capture in the browser and the transcription endpoint that feeds the question box.
  • The dashboard, the JSON API and the Cloudflare deployment.

External services

  • HKUL daily hours JSON — the same endpoint the Libraries’ hours page uses.
  • HKU ITS Chi Wah page — the source for the two maintained Chi Wah schedules.
  • Cloudflare Workers and D1 — hosting, the API and storage.
  • Cloudflare Workers AI — Whisper transcription for voice input.
  • DeepSeek chat API — OpenAI-compatible; used to phrase chat answers when configured.
  • FastAPI, Uvicorn, Jinja2, httpx — the local reference implementation.

What is specific to HKU study spaces

Field-level mapping

The official file exposes one field per library. Fung Ping Shan and Fine Arts inherit the Main Library field, while the Education Library has its own. The mapping used for each venue is visible in the API response.

Campus-aware ranking

Main Campus, Centennial Campus, Sassoon Road and the Prince Philip Dental Hospital carry different weights, so a central option wins a near tie without hiding the far ones.

Unknown instead of closed

An unpublished date, a missing field, a malformed value or an expired cache all produce Unknown. A student standing outside a library is never told it is closed when the app simply could not verify.

04 · Demo

Demonstration and captured evidence.

Both recordings are from the finished project. The screenshots and the API response below were captured on 18 November 2026 from app.hku-lib.xyz.

Desktop dashboard with three recommendation cards: Main Library open for two more hours, Chi Wah Learning Commons open for ten hours, and Library 24 open around the clock, each with crowd and source rows.
Recommended spaces on the deployed app, with the time remaining, the crowd estimate and the official source for each.
Mobile layout at 390 pixels wide: header, then the recommendation list stacked in one column.
The same list at 390 px.
Chat panel answering the question “Is the Main Library open now?” with the opening status, the closing time and a link to the official HKU Libraries page.
The assistant answering from live records and linking the official schedule.
Technical example

A request for one venue returns its computed status, the crowd estimate and the recommendation score with reasons. Here the Main Library is open until 22:00, the crowd figure is a synthetic starter estimate, and the ranking rewards an open, large, central space.

Captured 18 Nov 2026 curl https://app.hku-lib.xyz/api/venues/main-library
{
  "id": "main-library",
  "status": {
    "code": "open", "label": "Open Now", "is_open": true,
    "next_transition": "2026-11-18T22:00:00+08:00", "transition_label": "Closes"
  },
  "crowd": {
    "kind": "typical", "label": "Starter estimate",
    "score": 1.7, "sample_count": 6, "is_demo": true
  },
  "recommendation": {
    "score": 119.77,
    "reasons": ["Open now", "Main Campus", "Very large general-purpose space", "Lower crowd estimate"]
  }
}

05 · Evaluation

What we ran.

Test and verification results
CheckResultHow it was produced
Python test suite 60 passed pytest -q on Windows with Python 3.13.1, 18 November 2026. One deprecation warning from the test client library.
Frontend display rules Passed node tests/test_frontend_display.cjs renders the card and detail functions in a stubbed DOM and checks the closed-venue, pinned and crowd rules.
Functional API checks 22 of 22 on both runtimes The same script against the Python reference and the deployed Worker: health, 16 venues, source metadata, export, validation errors, the three-report estimate, guardrail refusal, quota and source catalogue.
Parity between implementations 10 of 10 identical Python and Worker JSON compared field by field after removing timestamps and ETags: /api/health, /api/venues, /api/export, /api/sources and four venue details.
Public read-only checks 17 of 17 Health, the full venue list, source health, export, a 404 for an unknown venue, the seat-count refusal, quota shape and security headers, against the deployed Worker.
Voice input Transcript inserted Headless Chromium with a synthetic microphone: press the mic, speak, stop; the transcript appears in the question box within two seconds.
Persistence across restart Estimate kept Three reports produced a current estimate of 2.0/5; after restarting the Worker the same estimate was returned from D1.

Failure and boundary cases

Case A · conflicting reports

Four reports that disagree

Four reports of 1, 1, 5 and 5 are not averaged into 3.0. The estimator detects the spread and refuses to publish a number.

Expected
No score, label “Conflicting Reports”
Actual
{"kind":"insufficient","label":"Conflicting Reports","score":null,"sample_count":4}
Case B · boundary

Unpublished hours are not “closed”

If HKUL has not published a date, the daily endpoint returns 404. The ingestion layer converts that into Unknown with a note instead of reporting the space as closed.

Expected
status.code = "unknown", is_open = null
Actual
Covered by the test suite and shown in the source panel as mode: unpublished or stale-cache
Case C · allowance

Voice input reaches its monthly cap

Transcription runs on a fixed monthly allowance. When it is used up the endpoint refuses the clip instead of queueing work, and typing still works.

Expected
HTTP 429 and a message asking the user to type
Actual
429 {"detail":"Monthly voice allowance ... used up."}, reproduced with the counter set to the limit
Case D · provider

The chat provider rejects the key

When the configured key is rejected, the gateway answers 401. The product keeps answering from local records, names the cause and stops retrying for ten minutes, so chat does not fail on every message.

Expected
No invented answer, visible reason, no repeated failing calls
Actual
provider_notice names the rejection; the state and retry window are stored in D1

Case A was reproduced on a local Worker with an isolated database; submitting synthetic reports to the public deployment would leave misleading crowd evidence for real visitors.

06 · Limitations

What this project does not establish.

Data and evidence

  • Crowd figures are estimates. No crowd report has reached the three needed for a current estimate, so pages show a labelled Starter estimate built from a synthetic historical pattern.
  • No seat counts or live occupancy. The app does not know how many seats are free, and refuses questions that ask.
  • Hours depend on HKUL. If the official file is wrong or unpublished, the app shows what the source says or Unknown. Chi Wah schedules are maintained by hand.
  • No field study. We collected no observations from students in the spaces, so crowd accuracy and usability are untested.

Product and AI

  • The assistant is grounded by prompt. Answers are checked for cited venues; sentence-level grounding is not verified.
  • The chat model has a monthly cap. When the allowance or the key is unavailable, chat answers from local records and says why.
  • Abuse controls are partial. Browser tokens can be replaced and per-IP limits are best effort.
  • No account is required. A report stores a 1–5 rating, an optional note and a hashed random token. Audio is transcribed and not stored.
AI use. The team used AI tools for coding assistance, drafting and review. Test results on this page come from the runs listed above.

07 · Run it

Run the reference implementation locally.

Python 3.11 or newer. The core flow needs no API key and no HKU login.

git clone https://github.com/AILT9019-Group-44/ailt9019-project-group-44.git
cd ailt9019-project-group-44
python -m venv .venv
.venv/Scripts/python -m pip install -r requirements-dev.txt
.venv/Scripts/python -m pytest -q
.venv/Scripts/python -m uvicorn app.main:app --port 8000

Then open http://127.0.0.1:8000. On macOS or Linux use .venv/bin/python.

Repository

The repository holds the reference implementation, the Worker deployment, the tests and the source registry used by this page.

View the repository on GitHub

The README covers the full setup, configuration and deployment notes.

Cloudflare Worker deployment and configuration

Requires Node 20 or newer and a Cloudflare account with Workers and D1.

cd deploy/app
node build.mjs
npx wrangler d1 create hku-study-spot
npx wrangler d1 execute hku-study-spot --remote --file=./migrations/0001_init.sql
npx wrangler secret put AI_API_KEY
npx wrangler deploy

The AI secret is optional. Without it the chat answers from local records.

NameWherePurpose
AI_API_KEYSecretChat provider key.
AI_BASE_URL, AI_MODELVariableOpenAI-compatible endpoint and model id.
FREE_AI_QUOTAVariableMonthly allowance for server-funded chat calls.
CURRENT_CROWD_WINDOW_MINUTESVariableWindow for a current crowd estimate.
MIN_CURRENT_CROWD_REPORTSVariableReports required before a current estimate is shown.
HKUL_CACHE_MAX_AGE_HOURSVariableMaximum age of a cached official schedule.