Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JaiderT/CoffeePrice/llms.txt

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

CoffePrice generates next-business-day FNC coffee price predictions using a machine-learning pipeline that runs outside the main Node.js server. Results are written to static files that the backend reads on demand — keeping prediction delivery fast and decoupled from ML execution. Every prediction comes with a price range, a directional trend signal, and a confidence score so producers can quickly judge whether to act on a prediction or wait.

​
What a Prediction Contains

Each prediction object exposes the following fields:
FieldTypeDescription
fechastring (ISO date)Target business day for the prediction (YYYY-MM-DD)
precioestimadonumberPoint estimate of the FNC price (COP/carga)
preciominimonumberLower bound of the expected range
preciomaximonumberUpper bound of the expected range
tendenciastringDirection signal: "sube", "baja", or "estable"
confianzanumber (0–100)Model confidence score (see calculation)
modelVersionstringAlways "fnc_hibrido" for production predictions
explicacionstringHuman-readable explanation generated by the pipeline
estrategiaAplicadastringWhich strategy drove this prediction (e.g. "naive", "ensemble")
holdoutMapenumberMAPE of the selected strategy on the holdout set
generatedAtstring (ISO)Timestamp when the pipeline produced this prediction

​
Model Strategy

The prediction pipeline is a hybrid ensemble that blends four strategies. Ensemble weights and holdout metrics come directly from ml-service-experimental/modelos/metricas_fnc_hibrido.json:

Naive (45.16%)

Carries the largest weight. Predicts that tomorrow’s price will equal today’s. Lowest holdout MAPE on the current dataset: 0.88% (MAE: 19,714 COP/carga).

Formula (35.77%)

A calibrated regression formula applied to recent FNC price history. Holdout MAPE: 1.21% (MAE: 26,986 COP/carga).

Prophet (9.87%)

Facebook Prophet time-series model. Performs well on training data (MAPE 1.45%) but has higher holdout MAPE (4.37%), so it carries the second-lowest weight.

XGBoost / Hybrid (9.20%)

Gradient-boosted tree model using engineered lag features. Best training MAPE (0.40%), but highest holdout MAPE (4.69%), indicating overfitting on short series; carries the lowest ensemble weight.
The current best strategy on holdout is naive with a MAPE of 0.88%. The pipeline automatically selects the strategy with the lowest holdout MAPE as estrategia_seleccionada and uses that selection to drive estrategiaAplicada in individual predictions. Ensemble metrics summary (holdout set, 361 records, 354 supervised):
StrategyHoldout MAPEHoldout MAE (COP)
naive0.88%19,714
formula1.21%26,986
ensemble1.52%33,784
prophet4.37%96,647
hybrid4.69%103,733

​
How Predictions Are Served

The backend reads predictions from flat files first; MongoDB is used only as a fallback.
1

Latest prediction file

The controller reads backend/datos/predicciones_fnc.json. If the file exists and passes schema validation (required fields: fecha_prediccion, precio_estimado, precio_minimo, precio_maximo, tendencia — all must be finite numbers and valid ISO dates), it is returned immediately.
2

Historical CSV

backend/datos/historial_predicciones_fnc.csv stores all previous daily predictions. The controller parses it, cross-references ml-service-experimental/datos/evaluacion_predicciones_fnc.csv for actual-price evaluations, and merges the result with the latest JSON.
3

MongoDB fallback

If neither file is readable (e.g. fresh deploy before the first pipeline run), the controller queries the prediccion collection filtered to modelVersion: "fnc_hibrido".

​
Prediction Endpoints Overview

All endpoints are public (no authentication required). For full request/response schemas see the API → Predictions reference.
EndpointDescription
GET /api/predicciones/ultimaLatest available prediction
GET /api/predicciones/resumenNext-business-day summary (identical to /ultima from the file)
GET /api/predicciones/rango?dias=7Last N days of predictions (valid values: 7, 15, 30)
GET /api/predicciones/dia?offset=1Prediction for day +N (valid values: 1, 7, 15, 30)
GET /api/predicciones/fecha?fecha=YYYY-MM-DDPrediction for a specific calendar date
GET /api/prediccionesAll available predictions sorted by date ascending

​
Confidence Calculation

The confidence score is derived from the holdout MAPE of the selected strategy: 
function calcularConfianzaDesdeFnc(prediccion) {
  const mape = Number(prediccion.holdout_mape);

  if (prediccion.precio_minimo === prediccion.precio_maximo) {
    return 92; // Point prediction — high certainty by definition
  }

  if (Number.isFinite(mape)) {
    return Math.max(45, Math.min(90, Math.round(92 - (mape * 10))));
  }

  return 65; // Default when MAPE is unavailable
}
In plain terms: confidence = 92 − (holdout_MAPE × 10), clamped to the range 45–90. With the current naive strategy at MAPE 0.88%, the resulting confidence is approximately 83.

​
Example Prediction Object

{
  "fecha": "2025-06-02",
  "precioestimado": 2265000,
  "preciominimo": 2240000,
  "preciomaximo": 2290000,
  "tendencia": "estable",
  "confianza": 83,
  "modelVersion": "fnc_hibrido",
  "estrategiaAplicada": "naive",
  "holdoutMape": 0.8784,
  "holdoutMae": 19714.29,
  "explicacion": "Se espera estabilidad en el precio del cafe para la proxima jornada.",
  "generatedAt": "2025-06-01T13:05:00.000Z",
  "fuente": "fnc_hibrido_json",
  "precioActualFnc": 2260000,
  "variacionPorcentual": 0.22
}
Predictions always target the next business day. The pipeline skips weekends — if today is Friday, the prediction covers the following Monday. The fecha field will reflect this skip automatically.
Admin-only write endpoints (POST, PUT, DELETE /api/predicciones) exist for manual overrides but should be used with caution. File-based predictions always take precedence over MongoDB records when files are present and valid.

Build docs developers (and LLMs) love

Get started for freeTalk to us