Omni Session Metrics¶

EmiliaVision's Omni Session Metrics module calculates 24 service quality metrics per dining session, combining video annotations, POS data, and real-time AI suggestions into a unified quality profile.

Architecture¶

flowchart TD
    A["Shift Map Storage<br/>shift_map_storage"] --> B["Metrics Engine<br/>metrics.py"]
    C["POS Sessions Storage<br/>pos_sessions_storage"] --> B
    D["EchoBase Events<br/>metadata.tables[].echobase_events"] --> B
    B --> E["Enriched Shift<br/>version N+1"]
    E --> F["ClickHouse<br/>shift_map_storage"]

The enrichment CLI reads the latest shift version, calculates metrics for every session, and inserts a new version with session.metrics populated. A SHA-256 fingerprint prevents unnecessary writes when metrics haven't changed.

Metric Catalog¶

All metrics live at metadata.tables[].sessions[].metrics in the shift_map_storage JSON metadata.

ID	Field	Type	Source	Details
M-1	`manager_touch_count`	int	Annotations	Annotation Metrics
M-2	`time_to_first_pos_order_seconds`	int \| null	Annotations + POS	POS Metrics
M-3	`time_from_session_start_to_drink_arrival_seconds`	int \| null	Annotations	Annotation Metrics
M-4	`waiter_touch_count`	int	Annotations	Annotation Metrics
M-5	`hand_raise_count`	int	Annotations	Annotation Metrics
M-6	`table_cleaned_time_seconds`	int \| null	Annotations	Annotation Metrics
M-7	`food_delivery_from_first_pos_item_seconds`	int \| null	Annotations + POS	POS Metrics
M-8	`first_waiter_contact_time_seconds`	int \| null	Annotations	Annotation Metrics
M-9	`drink_delivery_from_first_pos_item_seconds`	int \| null	Annotations + POS	POS Metrics
M-10	`drink_delivery_from_first_drink_order_seconds`	int \| null	Annotations + POS	POS Metrics
M-11	`food_delivery_from_first_main_dish_order_seconds`	int \| null	Annotations + POS	POS Metrics
M-12	`drink_delivery_from_order_taken_seconds`	int \| null	Annotations	Annotation Metrics
M-13	`food_delivery_from_order_taken_seconds`	int \| null	Annotations	Annotation Metrics
M-14	`bill_payment_to_end_session_seconds`	int \| null	Annotations	Annotation Metrics
M-15	`drink_item_count`	int	POS	POS Metrics
M-16	`main_dish_item_count`	int	POS	POS Metrics
M-17	`dessert_item_count`	int	POS	POS Metrics
M-18	`pos_ticket_subtotal`	float \| null	POS	POS Metrics
M-19	`pos_ticket_avg`	float \| null	POS	POS Metrics
M-20	`pos_drink_ticket_total`	float \| null	POS	POS Metrics
M-21	`pos_dessert_ticket_total`	float \| null	POS	POS Metrics
M-22	`pos_server_name_open`	str \| null	POS	POS Metrics
M-23	`pos_server_name_close`	str \| null	POS	POS Metrics
M-24	`pos_top_seller`	str \| null	POS	POS Metrics
—	`drink_suggestion_count`	int	EchoBase Events	Compliance
—	`drink_suggestion_compliance_pct`	float \| null	EchoBase Events	Compliance
—	`dessert_suggestion_count`	int	EchoBase Events	Compliance
—	`dessert_suggestion_compliance_pct`	float \| null	EchoBase Events	Compliance
—	`delayed_food_items`	list[str]	POS + Metrics	SLA Detection
—	`delayed_drink_items`	list[str]	POS + Metrics	SLA Detection

Metadata Fields¶

Every enriched session also includes:

Field	Type	Description
`omni_metrics_version`	str	Version of the Omni Metrics module that calculated these metrics
`fingerprint`	str	8-char SHA-256 hash of all metrics + version — used to skip re-writes
`calculated_at`	str	ISO 8601 timestamp of when metrics were calculated

Null Convention¶

Duration metrics return null when their prerequisite annotations are missing:

Metrics gated on start-session: M-2, M-3, M-8
Metrics gated on end-session: M-6, M-14
Metrics gated on order-taken: M-12, M-13
Metrics gated on confirmed POS + video_start_utc: M-2, M-7, M-9, M-10, M-11

A null metric is not an error — it means the required data was not available for that session.

Count metrics (M-1, M-4, M-5, M-15, M-16, M-17) default to 0, never null.