API_DOCUMENTATION.md

Energy ML API Documentation

Overview

This API provides machine learning predictions for industrial energy management with three separate endpoints for different models.

Base URL

https://your-space-name.hf.space

Endpoints

1. Energy Prediction - Random Forest

Endpoint: /api/predict (Tab 0)
Method: POST
Description: Predicts daily average energy consumption using Random Forest

Request Body

[
  {
    "data": "2025-01-01",
    "boosting": 0.0,
    "cor": "incolor",
    "espessura": 8.0,
    "extracao_forno": 750.0,
    "porcentagem_caco": 15.0,
    "extracao_boosting": 1.5
  }
]

Response

[
  {
    "data": "01-01-2025",
    "predicted_energy": 5.234,
    "note": "Add boosting energy separately to get final consumption"
  }
]

2. Energy Prediction - XGBoost

Endpoint: /api/predict (Tab 1)
Method: POST
Description: Predicts daily average energy consumption using XGBoost (best model)

Request Body

[
  {
    "data": "2025-01-01",
    "boosting": 0.0,
    "cor": "incolor",
    "espessura": 8.0,
    "extracao_forno": 750.0,
    "porcentagem_caco": 15.0,
    "extracao_boosting": 1.5
  }
]

Response

[
  {
    "data": "01-01-2025",
    "predicted_energy": 5.187,
    "note": "Add boosting energy separately to get final consumption"
  }
]

3. Threshold Detection

Endpoint: /api/predict (Tab 2)
Method: POST
Description: Predicts probability of exceeding 8300 and 9000 consumption thresholds

Request Body

{
  "data": "2025-01-01",
  "cor": "incolor",
  "espessura": 8.0,
  "ext_boosting": 1.5,
  "extracao_forno": 750.0,
  "porcentagem_caco": 15.0,
  "prod_e": 1,
  "prod_l": 0,
  "autoclave": 1
}

Response

{
  "predictions": {
    "prediction_1": [
      {
        "datetime": "2025-01-01",
        "threshold": 8300,
        "probabilidade_de_estouro": 0.1234,
        "estouro_previsto": 0
      }
    ],
    "prediction_2": [
      {
        "datetime": "2025-01-01",
        "threshold": 9000,
        "probabilidade_de_estouro": 0.0567,
        "estouro_previsto": 0
      }
    ]
  }
}

Input Parameters

Energy Prediction Models

Parameter	Type	Required	Description
data	string	Yes	Date in YYYY-MM-DD format
boosting	float	Yes	Always set to 0.0 (compatibility)
cor	string	Yes	Glass color: "incolor", "verde", "cinza", "bronze"
espessura	float	Yes	Glass thickness (mm)
extracao_forno	float	Yes	Furnace extraction rate
porcentagem_caco	float	Yes	Glass cullet percentage (%)
extracao_boosting	float	Yes	External boosting parameter

Threshold Detection Model

Parameter	Type	Required	Description
data	string	Yes	Date in YYYY-MM-DD format
cor	string	Yes	Glass color: "incolor", "verde", "cinza", "bronze"
espessura	float	Yes	Glass thickness (mm)
ext_boosting	float	Yes	External boosting parameter
extracao_forno	float	Yes	Furnace extraction rate
porcentagem_caco	float	Yes	Glass cullet percentage (%)
prod_e	int	Yes	Production E (0 or 1)
prod_l	int	Yes	Production L (0 or 1)
autoclave	int	Yes	Autoclave usage (0 or 1)

Usage Examples

Python

import requests
import json

# Energy Prediction (XGBoost)
url = "https://your-space-name.hf.space/api/predict"
headers = {"Content-Type": "application/json"}

data = [
    {
        "data": "2025-01-01",
        "boosting": 0.0,
        "cor": "verde",
        "espessura": 10.0,
        "extracao_forno": 849.0,
        "porcentagem_caco": 45.0,
        "extracao_boosting": 54.0
    }
]

response = requests.post(url, json=data, headers=headers)
prediction = response.json()
print(f"Predicted energy: {prediction[0]['predicted_energy']} MWh")

cURL

# Threshold Detection
curl -X POST https://your-space-name.hf.space/api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "data": "2025-01-01",
    "cor": "incolor",
    "espessura": 8.0,
    "ext_boosting": 1.5,
    "extracao_forno": 750.0,
    "porcentagem_caco": 15.0,
    "prod_e": 1,
    "prod_l": 0,
    "autoclave": 1
  }'

Model Performance

• Random Forest Energy: R² = 0.50, MAE = 0.24 MWh
• XGBoost Energy: R² = 0.53, MAE = 0.24 MWh (recommended)
• Threshold Detection: 98.9% accuracy (8300), 100% accuracy (9000)

Notes

• Energy models predict base consumption - add actual boosting energy separately
• No temporal features - models work for any date/time period
• Real-time prediction - sub-second response times
• Batch processing - energy models accept arrays of inputs
• Threshold models output probabilities (0-1) and binary predictions (>0.5)

Error Handling

• Invalid JSON: Returns error message
• Missing parameters: Uses default values where possible
• Model errors: Returns error description with context