Opening hours
- HKUL daily JSONplus the maintained Chi Wah schedule
- Fetch and cachefour dates, ETag revalidation
- Status calculationopen, closing, closed or unknown
AILT9019 Group 44 · The University of Hong Kong
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.
01 · Problem and users
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.
02 · How it works
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.
The Python service in app/ is a local reference implementation of the same behaviour.
It is not part of the online request path.
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.
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.
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
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.
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.
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
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.
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.
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
| Check | Result | How 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. |
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.
{"kind":"insufficient","label":"Conflicting Reports","score":null,"sample_count":4}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.
status.code = "unknown", is_open = nullmode: unpublished or stale-cacheTranscription runs on a fixed monthly allowance. When it is used up the endpoint refuses the clip instead of queueing work, and typing still works.
429 {"detail":"Monthly voice allowance ... used up."}, reproduced
with the counter set to the limitWhen 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.
provider_notice names the rejection; the state and retry window
are stored in D1Case 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
07 · Run it
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.
The repository holds the reference implementation, the Worker deployment, the tests and the source registry used by this page.
The README covers the full setup, configuration and deployment notes.
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.
| Name | Where | Purpose |
|---|---|---|
AI_API_KEY | Secret | Chat provider key. |
AI_BASE_URL, AI_MODEL | Variable | OpenAI-compatible endpoint and model id. |
FREE_AI_QUOTA | Variable | Monthly allowance for server-funded chat calls. |
CURRENT_CROWD_WINDOW_MINUTES | Variable | Window for a current crowd estimate. |
MIN_CURRENT_CROWD_REPORTS | Variable | Reports required before a current estimate is shown. |
HKUL_CACHE_MAX_AGE_HOURS | Variable | Maximum age of a cached official schedule. |