docs/CONTRACT.md

Birdie data contract

This file is the merge contract between the two backend repos. Anything that produces or consumes seat data must use the models below (they live in birdie/models.py). Map your code onto the public functions listed per module; private helpers (leading underscore) are free to change.

Rules:

• birdie/ never imports Gradio. UI code lives only in app.py and birdie/ui/.
• Every timestamp is a timezone-aware datetime in Doha time (UTC+3, birdie.clock.DOHA_TZ).
• Everything time-based takes a clock (RealClock in the app, FakeClock in tests). Nothing sleeps in tests.
• Timers and thresholds come from birdie.config.TIMERS (demo or production, behind DEMO_MODE).
• Seat polygons are normalised (x, y) corners in 0..1, so they work at any camera resolution.
• The app does not persist source frames. Hosted Space logging and retention must be checked separately. The app stores seat states and aggregate counts.

Models (birdie/models.py)

Model	Fields
Venue	venue_id: str, name: str, area: str, type: VenueType (cafe, library, cowork, study_room), lat: float, lon: float, zones: list[str], source: VenueSource (live, recorded, simulated), optional floor_plan and display metadata
Seat	seat_id: str, venue_id: str, zone: str, optional table_id, optional customer-map coordinates, seat_polygon and workspace_polygon (normalised camera regions), has_outlet, has_window
StudyTable	table_id, table_type (shared, private, single_person_desk), capacity, seat_ids, normalised table_polygon, is_shareable, is_available_for_studying
SeatSnapshot	venue_id, seat_id, zone, has_outlet, state: SeatState (UNKNOWN, FREE, OCCUPIED, HELD, REVIEW_REQUIRED, UNAVAILABLE), timestamps, detector evidence, grace-period countdown, review and override flags
SeatEvent	ts: datetime, venue_id, seat_id, old_state: SeatState | None, new_state: SeatState
Query	area: str | None, party_size: int, needs_outlet: bool, quiet: bool, zone: str | None, venue_type: VenueType | None, arrival_minutes: int
VenueConfig	venue, seats, tables, unmapped_seat_ids, private mirror-exclusion regions, legacy camera_table_regions fallback, and optional recording_sha256 tying calibration to one clip

With an explicit tables layout, each configured seat must link to exactly one table and appear in that table's seat_ids. Known IDs awaiting calibration live in unmapped_seat_ids; they are excluded from capacity and availability. Camera coordinates stay private and are not returned by the public venue API.

The customer API groups detailed backend states into three availability statuses: free, taken (OCCUPIED or UNAVAILABLE), and held (HELD or REVIEW_REQUIRED). UNKNOWN is returned as checking, a camera-evidence indicator rather than an availability state. counts.free, counts.taken, counts.held_or_review, and counts.checking partition configured seats; legacy detailed state counters and the raw state/seat_state fields remain available for diagnostics. A seat is a verified study space only when its state is FREE, its configured chair is detected above the detector confidence threshold, and its assigned workspace is clear. A missing chair, uncertain/shared item, missing polygon, unknown seat state, or disabled table is never counted as usable. Shared tables are evaluated seat by seat. Private or non-shareable tables are one group space and require every seat to be verified free. A belongings timeout only raises staff review; it never frees the blocked workspace. counts.usable_study_spaces is the customer-facing total.

Zone ids used by the demo venues: quiet, open, group, family, women, terrace, indoor (labels in birdie.venues.ZONE_LABELS).

Storage (birdie/storage.py)

SQLite at data/birdie.db (gitignored). Repository(path); use Repository(":memory:") in tests.

Function	Purpose
add_seat_event(event, synthetic=False), add_seat_events(events, synthetic=False)	Append to the seat event log. synthetic=True marks back-filled history for simulated venues
seat_events(venue_id=None, since=None, until=None, include_synthetic=True) -> list[SeatEvent]	Read the event log in time order
record_occupancy(venue_id, ts, free, occupied, held), occupancy_buckets(venue_id, since=None)	Live occupancy in 15-minute buckets
add_alert(...), alerts(venue_id=None, unresolved_only=False), resolve_alerts(venue_id, seat_id, kind=None)	Staff alerts
save_seat_snapshots(snapshots), seat_snapshots(venue_id)	Persist current state and unattended timer timestamps across process restarts

Venues (birdie/venues.py)

load_all() -> dict[str, VenueConfig], load_venue(venue_id), save_venue(config), zone_label(zone).

Vision (birdie/vision/)

Function	Purpose
detector.detect(frame, threshold=0.4) -> list[{label, score, box}]	RT-DETR r18 (PekingU/rtdetr_r18vd). Keeps COCO classes chair, person, backpack, handbag, suitcase, laptop, cup, bottle, book, cell phone. box = [x1, y1, x2, y2] in pixels of the frame passed in. Resizes to long side <= 640 internally
detector.resize_long_side(frame, 640) -> PIL.Image, detector.load()	Helpers. _infer is the pure (frame in, detections out) function wrapped with @spaces.GPU when spaces is importable
seats.assign_detections(detections, seats, (w, h), min_overlap=0.2, table_regions=None) -> {seat_id: [det]}	Assign person/item evidence to configured seat/workspace regions; ambiguous shared-table items remain unknown
seats.observe_evidence(assigned)	Confidence-aware PERSON, ITEMS, EMPTY, or conservative UNKNOWN evidence
seats.workspace_evidence(detections, seats, (w, h))	Verify a visible chair and clear/blocked/uncertain desk workspace for each calibrated seat
state.SeatStateMachine(venue_id, seat_id, clock, k=3, hold_seconds=...)	Smooths evidence; belongings become HELD, then REVIEW_REQUIRED after the real-time grace period
state.VenueTracker(venue_id, seats, clock, on_event)	.process({seat_id: Observation}) -> [SeatEvent] (missing seats = UNKNOWN), .tick() (hold timers and stale-feed expiry), .snapshots(), .counts(), .force(states), .set_seats(seats)
render.annotate(frame, detections)	RGB frame with detector boxes only; no static seat regions and no blurring
render.to_data_uri(frame)	In-memory JPEG data URL (frames never touch disk)
clip.iter_clip_frames(path, fps=1)	Sample a recorded clip at 1 fps, in memory
demo.replay_recording(svc, venue_id, path, stop)	Repeatedly process a configured clip and invalidate seat states on failure

Forecast (birdie/forecast/)

Function	Purpose
calendar.is_weekend(dt) (Friday + Saturday), day_type(dt) (weekday/friday/saturday), is_friday_prayer_quiet(dt), is_ramadan(dt), is_exam_season(dt), is_terrace_season(dt), slot_of(dt), features(dt)	Qatar calendar. RAMADAN_RANGES, EXAM_RANGES are editable
synthetic.profile(venue_type, ts), synthetic.generate_history(venue, n_seats, end, weeks=4) -> [{ts, occupied, free, total, synthetic}]	Synthetic history, always labelled synthetic
model.BaselineForecaster(venue_type).fit(history).predict_ratio(ts)	Default forecaster (occupancy ratio 0..1)
model.ChronosForecaster().predict(contexts, steps), model.load_chronos()	Optional amazon/chronos-bolt-small; raises ForecasterUnavailable / returns None if it can't load
model.ForecastEngine(configs, clock, repo).ratio_at(venue_id, ts)	What the app uses (BIRDIE_USE_CHRONOS=1 to try Chronos)

Decision (birdie/decision.py)

Functions take a LiveData object: anything with now(), venues(), venue(id), seats(id), snapshots(id), and forecast_ratio(id, ts). BirdieService implements it.

Function	Purpose
availability_at(data, venue_id, arrival_minutes) -> Availability	expected_free, low, high, live_free, forecast_free, live_weight; .summary()
blend_availability(...)	The pure blending rule (live weight 0.5 ** (arrival / 20 min))
focus_score(data, venue_id, arrival_minutes) -> FocusScore	score 0..100 and parts (free 40, noise 25, outlets 20, trend 15)
recommend(data, query, top=3) -> [Recommendation]	Filters by the Query, ranks by focus score; each has reasons

Simulator (birdie/simulator.py)

Simulator(configs, trackers, ratio_at, clock): .step() feeds observations to each simulated venue's VenueTracker.process (the camera's code path); .backfill(repo, venue_id, hours=24) writes a synthetic event log.

Analytics (birdie/analytics.py)

venue_dashboard(repo, venue_id, seat_ids, now, hours=24, observed_since=None) -> Dashboard with occupancy_by_hour, peak_hours, held_minutes_total, held_minutes_by_seat. Building blocks: seat_intervals, occupancy_by_hour, held_minutes.

Service (birdie/service.py)

BirdieService(repo=None, clock=None, venues=None, timers=TIMERS, detector=None) is the one object the UI talks to: process_frame(venue_id, frame) associates detections and updates seat state; snapshots(venue_id), zone_counts(venue_id), upsert_seat(seat), delete_seat(venue_id, seat_id), study_availability(venue_id), set_table_available_for_studying(...), availability_at(venue_id, minutes), forecast (ForecastEngine), simulator, tick(), start() (back-fill + 2 s scheduler), stop().

GET /api/venues/{venue_id} returns table-level and seat-level usable_for_studying, workspace_clear, and availability_reason. Staff may disable/re-enable a seat or table through the bearer-token protected maintenance endpoints. Venue geometry changes are stored in venues/<venue_id>.json and require a fresh camera sample before availability returns.

Assistant (birdie/assistant/, stub)

answer(data, question) -> AssistantAnswer = parse_query(question) -> Query (Fanar, JSON) -> recommend() in Python -> phrase_reply(...) (Fanar, user's language). No tool calling.

Mapping a second repo onto this contract

1. Convert your seat and venue objects to the models above (Model.model_validate(dict)).
2. Anything that observes seats should end in VenueTracker.process({seat_id: Observation}), so smoothing, hold timers and SeatEvents stay identical.
3. Anything that reads availability should go through LiveData + birdie.decision.