Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/elzackarias/Hackaton3B-Reto1/llms.txt

Use this file to discover all available pages before exploring further.

backend/contracts.py centralizes every inter-module data type used across the Anaquel Inteligente 3B pipeline — from YOLOv8 detections (M2) through inventory tracking (M3), predictions (M6), heatmaps (M7), and narrative generation (M8). frontend/src/types/index.ts mirrors the key types in TypeScript so the React dashboard stays in sync with the backend contracts without a shared code-gen step.

​
Python Dataclasses (contracts.py)

​
EventType

An Enum that identifies the direction of a stock movement. Used as the event_type field on DetectionEvent.
​
RETIRO
string
Value: "retiro". A product was removed from the shelf by a customer.
​
DEVOLUCION
string
Value: "devolucion". A product was returned to the shelf.
from enum import Enum

class EventType(Enum):
    RETIRO     = "retiro"
    DEVOLUCION = "devolucion"

​
DetectionEvent

Contract C2 — produced by the Detection Engine (M2) and consumed by the Inventory Engine (M3). Carries the raw vision data for a single stock-movement event detected by YOLOv8.
​
event_id
str
required
UUID string uniquely identifying this detection event.
​
event_type
EventType
required
EventType.RETIRO or EventType.DEVOLUCION.
​
sku_id
str
required
Machine-readable product identifier, e.g. "nachos_naturasol".
​
sku_name
str
required
Human-readable product name, e.g. "Nachos Con Sal Naturasol 200gr".
​
slot_id
int
required
Shelf slot number where the detection occurred.
​
confidence
float
required
YOLOv8 detection confidence in the range [0.0, 1.0].
​
timestamp
datetime
required
Python datetime object representing when the event was detected.
​
bbox
tuple[int, int, int, int]
required
Bounding box in pixel coordinates: (x1, y1, x2, y2).
​
count_before
int
required
Detected item count in the slot before the event.
​
count_after
int
required
Detected item count in the slot after the event.

​
SlotDetection

Contract C3 (internal to M2) — represents a single slot’s detection result within a DetectionResult. Carries enriched context including a stock-level classification.
​
sku_id
str
required
Machine-readable product identifier.
​
sku_name
str
required
Human-readable product name.
​
slot_id
int
required
Shelf slot number.
​
bbox
tuple[int, int, int, int]
required
Bounding box: (x1, y1, x2, y2).
​
confidence
float
required
Detection confidence in [0.0, 1.0].
​
count
int
required
Number of product units detected in the slot.
​
stock_level
str
required
Categorical stock status: "ok" | "warning" | "critical".

​
DetectionResult

Contract C3 — the complete output of one inference pass by the Detection Engine (M2). Aggregates all SlotDetection objects produced from a single camera frame.
​
timestamp
float
required
Unix timestamp (seconds since epoch) when the frame was processed.
​
counts
dict[str, int]
required
Mapping of sku_id → detected count across all slots in the frame.
​
detections
list[SlotDetection]
required
List of per-slot detection results. Defaults to an empty list.

​
AnnotatedFrame

Contract C3 (internal to M2) — pairs a raw video frame with its detection results. Used internally by the camera pipeline and video overlay (VideoOverlay) to render bounding-box annotations before encoding the frame for broadcast. This type is not transmitted over the WebSocket or REST API — it exists only within the M2 camera-processing thread.
​
frame
numpy.ndarray
required
Raw BGR image array as returned by OpenCV. Not JSON-serializable; used only in-process.
​
timestamp
float
required
Unix timestamp (seconds since epoch) when the frame was captured.
​
detections
list[SlotDetection]
required
The SlotDetection results associated with this frame.

​
ProductStock

Contract C5 — the authoritative stock state for a single SKU as maintained by the Inventory Engine (M3). Broadcast on every inventory_update and alert WebSocket event.
​
sku_id
str
required
Machine-readable product identifier.
​
sku_name
str
required
Human-readable product name.
​
slot_id
int
required
Shelf slot number.
​
stock_initial
int
required
Stock count at session start (used to compute fill rate).
​
stock_current
int
required
Current stock count.
​
stock_min_threshold
float
required
Fractional alert threshold. An alert fires when stock_current / stock_initial drops below this value (e.g. 0.2 = 20%).
​
is_alert
bool
required
True if the SKU is currently at or below the alert threshold.
​
last_event
datetime | None
required
Datetime of the most recent event affecting this SKU, or None if no event has occurred.

​
InventoryState

Contract C5 — a snapshot of the full shelf inventory at a given point in time, returned by GET /api/inventory.
​
last_updated
datetime
required
Datetime when the inventory state was last modified.
​
products
list[ProductStock]
required
List of ProductStock objects for every registered SKU.

​
InventoryEvent

Contract C5 — the processed, inventory-level record of a stock movement. Produced by InventoryEngine.process_event() from a DetectionEvent and emitted on inventory_update and detection_event WebSocket events.
InventoryEvent is distinct from DetectionEvent. DetectionEvent carries raw vision data (bbox, count_before, count_after), while InventoryEvent carries inventory-level data (stock_before, stock_after) in terms that the dashboard and engines consume.
​
event_id
str
required
UUID string uniquely identifying this inventory event.
​
event_type
str
required
"retiro" or "devolucion" as a plain string (not the EventType enum).
​
sku_id
str
required
Machine-readable product identifier.
​
sku_name
str
required
Human-readable product name.
​
slot_id
int
required
Shelf slot number.
​
stock_before
int
required
Inventory stock count before this event was applied.
​
stock_after
int
required
Inventory stock count after this event was applied.
​
confidence
float
required
Detection confidence forwarded from the originating DetectionEvent.
​
timestamp
datetime
required
Datetime when the event was processed.

​
SKUHistory

Contract C6 — aggregated removal history for a single SKU, passed from the Inventory Engine (M3) to the Prediction Engine (M6) to compute depletion rates.
​
sku_id
str
required
Machine-readable product identifier.
​
sku_name
str
required
Human-readable product name.
​
stock_current
int
required
Current stock count at the time this history snapshot was taken.
​
stock_initial
int
required
Initial stock count (used to compute remaining capacity).
​
events
list[datetime]
required
Ordered list of datetime timestamps for every removal event recorded for this SKU. The Prediction Engine requires at least 2 entries to calculate a rate.

​
StockPrediction

Contract C6 — depletion forecast produced by the Prediction Engine (M6) from a SKUHistory. Broadcast on the prediction_update WebSocket event and served by GET /api/predictions.
​
sku_id
str
required
Machine-readable product identifier.
​
sku_name
str
required
Human-readable product name.
​
stock_current
int
required
Stock count at prediction time.
​
rate_per_hour
float
required
Exponentially weighted moving average of removal rate in units per hour (alpha=0.3).
​
estimated_depletion
datetime | None
required
Predicted datetime when stock reaches zero, or None if the rate is zero or indeterminate.
​
minutes_remaining
float | None
required
Minutes until predicted depletion, or None.
​
trend
str
required
Acceleration of demand: "acelerando" | "estable" | "desacelerando".
​
confidence
str
required
Prediction confidence based on sample size: "alta" | "media" | "baja".

​
InteractionEvent

Contract C4 — represents a physical interaction with a shelf slot, used by the Heatmap Engine (M7) to build activity maps. Currently emitted with region=(0, 0, 0, 0) pending full M2 bounding-box integration.
​
slot_id
int
required
Shelf slot where the interaction occurred.
​
sku_id
str
required
Product involved in the interaction.
​
region
tuple[int, int, int, int]
required
Pixel region of the interaction: (x1, y1, x2, y2).
​
timestamp
datetime
required
Datetime of the interaction.
​
interaction_type
str
required
"hand_detected" | "product_moved".

​
NarrativeMessage

Contract C7 — a human-readable Spanish message produced by the Narrative Engine (M8) and delivered to the frontend via the narrative WebSocket event. Subject to a 30-second cooldown per SKU/message-type pair.
​
message_id
str
required
UUID string uniquely identifying this message.
​
severity
str
required
"info" | "warning" | "critical".
​
text
str
required
Human-readable Spanish message, e.g. "⚠️ Nachos Con Sal Naturasol 200gr está al 50% de su capacidad.".
​
sku_id
str | None
required
Related SKU, or None for store-wide messages.
​
timestamp
datetime
required
Datetime when the message was generated.
​
icon
str
required
Emoji icon matching the severity level, e.g. "⚠️", "🚨", "ℹ️".

​
TypeScript Interfaces (frontend/src/types/index.ts)

The frontend mirrors the key backend contracts as TypeScript interfaces. Note that datetime fields become string (ISO 8601) and some interfaces include additional frontend-only fields (e.g. source_id, alert_level) used by the dashboard’s multi-camera adapter layer. 
// ── Products & Inventory ──────────────────────────────────────

export interface ProductStock {
  sku_id: string;
  sku_name: string;
  stock_current: number;
  stock_initial: number;
  last_event: string | null;
  alert_active: boolean;
  alert_level: "normal" | "low" | "critical";
  source_id: string;
}

export interface InventoryState {
  timestamp: string;
  products: ProductStock[];
  total_events: number;
  source_id: string;
}

// ── Detection Events ──────────────────────────────────────────

export interface DetectionEvent {
  event_id: string;
  sku_id: string;
  sku_name: string;
  action: "removed" | "returned";
  stock_before: number;
  stock_after: number;
  timestamp: string;
  source_id: string;
}

// ── Predictions ───────────────────────────────────────────────

export interface StockPrediction {
  sku_id: string;
  sku_name: string;
  stock_current: number;
  rate_per_hour: number;
  estimated_depletion: string | null;
  minutes_remaining: number | null;
  trend: "acelerando" | "estable" | "desacelerando";
  confidence: "alta" | "media" | "baja";
  source_id: string;
}

// ── Narratives ────────────────────────────────────────────────

export interface NarrativeMessage {
  message_id: string;
  severity: "info" | "warning" | "critical";
  text: string;
  sku_id: string | null;
  timestamp: string;
  icon: string;
  source_id: string;
}
The useSocket hook in frontend/src/hooks/useSocket.ts includes an adaptProduct() function that maps backend ProductStock fields (e.g. is_alert) to their frontend equivalents (e.g. alert_active, alert_level) at the WebSocket boundary. This keeps both sides of the contract independent without a shared code-gen step.

​
Contract Map

The table below shows which contract is consumed by which engine module.
ContractDataclass(es)ProducerConsumer(s)
C2DetectionEvent, EventTypeM2M3
C3SlotDetection, DetectionResult, AnnotatedFrameM2M2 (internal)
C4InteractionEventM3M7
C5ProductStock, InventoryState, InventoryEventM3M4, WebSocket, REST
C6SKUHistory, StockPredictionM3M6
C7NarrativeMessageM8M4, WebSocket

Build docs developers (and LLMs) love

Get started for freeTalk to us