Omni Session Metrics¶

EmiliaVision's Omni Session Metrics module calculates 37 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 v1<br/>pos_sessions_storage"] --> B
    D["POS Sessions v2<br/>pos_sessions_v2_storage"] --> B
    E["EchoBase Events<br/>metadata.tables[].echobase_events"] --> B
    B --> F["Enriched Shift<br/>version N+1"]
    F --> G["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.

POS v1 and POS v2 Inputs¶

The metrics engine supports both POS generations:

• Legacy POS v1 uses session.pos_correlation.pos_session_id to read echobasematrix_{env}_pos_sessions_storage.
• POS Sessions v2 uses session.pos_correlation.pos_uuid to read the latest non-deleted row for pos_session_uuid from echobasematrix_{env}_pos_sessions_v2_storage.

POS v2 separates metadata.items (final financial state for totals, revenue, and item counts) from metadata.order_events (raw operational evidence, including non-order events). The backend selects positive orders using the canonical eligibility policy.

Category-dependent metrics read POS v2 final item categories and may apply them to operational order-event items at read time. If POS v2 item categories are backfilled or corrected, run enrichment again so affected sessions receive new metric fingerprints and updated shift versions.

Service Timing Contract¶

The existing duration fields remain nullable integer seconds. The new service_timing_evidence object accompanies them:

An interval contains finite non-negative start_offset_seconds and end_offset_seconds, relative to the original shift video, preserving fractions. It is null when the metric is unavailable or contradictory. An order contains offset_seconds, event_ids (source references, possibly empty), items (name, nullable category, nullable quantity, nullable line price), and nullable total. A total is available only when all included line prices are known. This operational total is not the final bill total.

Player validates the version/types, renders the supplied values and markers, and seeks to the supplied offsets. It must not select operational events, resolve category conflicts, reconstruct anchors from rounded durations, or substitute manual/generic timing formulas. Raw POS panels can still display financial context without treating it as timing evidence. SLA delay labels use the same canonical category anchor and order items.

Release and bounded reenrichment¶

This contract needs no DDL: it is additive JSON in the existing Shift Map metadata. Deploying code does not update an archived session or report.

1. Review the backend change, run producer and consumer contract tests, and publish the metrics image from the reviewed revision. Verify the actual published image, not just local source or a successful build job.
2. Inventory the permitted shifts, dates, and locations privately. Dry-run by --video-task-id, then write and reread a pilot only with operator approval. Continue in resumable batches over that closed inventory; preserve source annotations/POS rows and append new Shift Map versions normally.
3. Review all three infra/k8s/metrics/ image pins and deploy explicitly using the documented Kubernetes context. The existing jobs have no date filter: changing the metrics version changes every processed fingerprint and can reenrich all selected history even without --force. Do not apply the new pins before approving that scope or an appropriately bounded job policy.
4. Validate Player, Reports, Workspace, and SLA on the same reenriched sessions before declaring operational completion. Reader-specific compatibility work and immutable report publication are separate steps, not automatic effects of a metrics image release.
5. Rollback may restore a previous reviewed image pin. It does not erase appended data versions or authorize overwriting report snapshots.

Metric Catalog¶

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

Metadata Fields¶

Every enriched session also includes:

Null Convention¶

Duration metrics return null when their prerequisite annotations are missing:

• Metrics gated on start-session: M-2, M-3, M-8, M-25, M-27
• Metrics gated on end-session: M-6, M-14
• Metrics gated on bill-dropped + bill-payment: M-26
• 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.