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.

Three intelligence endpoints correspond to modules M6, M7, and M8 of the Anaquel Inteligente 3B pipeline. M6 predicts when each product will run out of stock using exponential smoothing over the removal event history. M7 aggregates slot interactions into a time-windowed activity heatmap. M8 surfaces auto-generated human-readable narrative messages in Spanish that describe events, trends, and alerts as they occur.

​
GET /api/predictions

Returns a StockPrediction object for every tracked SKU. Predictions are generated by PredictionEngine (M6) using exponential smoothing (alpha=0.3) over the timestamps of recorded removal events. A minimum of 2 removal events per SKU is required before a meaningful depletion estimate can be computed; products with fewer events return null for estimated_depletion and minutes_remaining. 
curl http://localhost:8000/api/predictions

​
StockPrediction Object

​
sku_id
string
Unique SKU identifier.
​
sku_name
string
Human-readable product name.
​
stock_current
integer
Units currently on the shelf at the time of prediction.
​
rate_per_hour
float
Smoothed removal rate in units per hour, derived from the inter-event timestamps using exponential smoothing.
​
estimated_depletion
string | null
ISO 8601 datetime when the product is predicted to reach zero stock, or null if insufficient event data exists (fewer than 2 retiro events).
​
minutes_remaining
float | null
Minutes from now until estimated depletion, or null if insufficient data.
​
trend
string
Direction of the removal rate over recent events:
  • "acelerando" — removal pace is increasing (stock depleting faster)
  • "estable" — removal pace is roughly constant
  • "desacelerando" — removal pace is decreasing
​
confidence
string
Reliability of the prediction based on the number of data points:
  • "alta" — high confidence (sufficient event history)
  • "media" — medium confidence
  • "baja" — low confidence (minimal event history)
Example response: 
[
  {
    "sku_id": "nachos_naturasol",
    "sku_name": "Nachos Con Sal Naturasol 200gr",
    "stock_current": 3,
    "rate_per_hour": 8.4,
    "estimated_depletion": "2024-11-15T10:59:30.000000",
    "minutes_remaining": 21.4,
    "trend": "acelerando",
    "confidence": "alta"
  },
  {
    "sku_id": "agua_burst",
    "sku_name": "Agua Natural Burst 1500ml",
    "stock_current": 8,
    "rate_per_hour": 0.0,
    "estimated_depletion": null,
    "minutes_remaining": null,
    "trend": "estable",
    "confidence": "baja"
  }
]
Predictions are recomputed on every request from the current event history. Use POST /api/events or POST /api/mock/event to generate removal events and observe the predictions evolve in real time.

​
GET /api/heatmap

Returns a structured heatmap of shelf slot activity within a configurable time window. Activity is recorded by HeatmapEngine (M7) each time any InventoryEvent is processed. The response contains a slots array ordered by descending intensity (the most active slot has intensity = 1.0), the window duration, and a timestamp.
​
window
integer
default:"300"
Time window in seconds over which to aggregate slot interactions. Minimum 10, maximum 3600 (1 hour).
curl "http://localhost:8000/api/heatmap?window=600"

​
Heatmap Response Fields

​
slots
array
Array of slot objects sorted by intensity descending. Each object contains:
  • slot_id (integer) — physical shelf slot number
  • sku_id (string) — SKU occupying that slot
  • activity_count (integer) — number of interactions recorded within the window
  • intensity (float) — normalized activity score; the busiest slot has 1.0, others are proportional
​
window_seconds
integer
The time window used to filter interactions, as passed in the window query parameter.
​
last_updated
string
ISO 8601 datetime when the heatmap was computed.
Example response: 
{
  "slots": [
    { "slot_id": 4, "sku_id": "nachos_naturasol", "activity_count": 7, "intensity": 1.0 },
    { "slot_id": 6, "sku_id": "sisi_cola",        "activity_count": 3, "intensity": 0.43 },
    { "slot_id": 3, "sku_id": "burst_energy",     "activity_count": 1, "intensity": 0.14 }
  ],
  "window_seconds": 600,
  "last_updated": "2024-11-15T10:55:00.123456"
}
Combine heatmap data with GET /api/analytics products array to correlate slot activity with product velocity. High-activity slots with low fill_rate values are the best restock candidates.

​
GET /api/narratives

Returns the most recent NarrativeMessage records generated by NarrativeEngine (M8) in reverse chronological order. Narratives are produced automatically in Spanish whenever significant events occur: product removals, returns, alert threshold crossings, and stock depletion predictions. A 30-second cooldown per SKU prevents message flooding.
​
limit
integer
default:"10"
Maximum number of narrative messages to return. Minimum 1, maximum 100.
curl "http://localhost:8000/api/narratives?limit=5"

​
NarrativeMessage Object

​
message_id
string
12-character lowercase hex string uniquely identifying this narrative message (first 12 hex digits of a UUID v4).
​
severity
string
Severity level of the message:
  • "info" — informational (e.g., a product was returned to the shelf)
  • "warning" — requires attention (e.g., stock is running low)
  • "critical" — immediate action needed (e.g., stock has crossed the alert threshold)
​
text
string
Human-readable narrative in Spanish describing the event or condition.
​
sku_id
string | null
SKU identifier of the product this message relates to, or null for system-wide messages.
​
timestamp
string
ISO 8601 datetime when this narrative was generated.
​
icon
string
Emoji icon associated with the message severity or event type.
Example response: 
[
  {
    "message_id": "d4f2a9017c3e",
    "severity": "critical",
    "text": "⚠️ ¡ALERTA! Nachos Con Sal Naturasol 200gr alcanzó el umbral crítico (25%). Reponer urgente.",
    "sku_id": "nachos_naturasol",
    "timestamp": "2024-11-15T10:50:22.100000",
    "icon": "⚠️"
  },
  {
    "message_id": "e5a3b0128d4f",
    "severity": "info",
    "text": "📦 Refresco Cola Sin Azucar Sisi 355ml retirado del anaquel. Stock actual: 6 unidades",
    "sku_id": "sisi_cola",
    "timestamp": "2024-11-15T10:49:55.880000",
    "icon": "📦"
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us