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.

An API 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; counts.free remains the lower-level occupancy count for compatibility.

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.