Initial deployment: Chronos-2 Excel Forecasting API

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.env
+.venv/
+*.log
+.cache/

Dockerfile

@@ -0,0 +1,42 @@
+# Dockerfile optimizado para HuggingFace Spaces
+FROM python:3.11-slim
+
+# Variables de entorno
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PORT=7860
+
+# Directorio de trabajo
+WORKDIR /app
+
+# Instalar dependencias del sistema
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copiar requirements
+COPY requirements.txt .
+
+# Instalar dependencias Python
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copiar código de la aplicación
+COPY app/ ./app/
+
+# Crear usuario no-root
+RUN useradd -m -u 1000 user && \
+    chown -R user:user /app
+USER user
+
+# Exponer puerto (HF Spaces usa 7860 por defecto)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Comando de inicio
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

INSTRUCTIONS.md

@@ -0,0 +1,35 @@
+# Instrucciones de Despliegue
+
+## Archivos listos para subir a HuggingFace Spaces
+
+Este directorio contiene todos los archivos necesarios para desplegar en HF Spaces.
+
+### Pasos:
+
+1. **Crear Space en HuggingFace**:
+   - Ve a: https://huggingface.co/new-space
+   - SDK: **Docker**
+   - Hardware: CPU basic (gratis)
+
+2. **Configurar HF_TOKEN**:
+   - Settings → Variables and secrets
+   - Nombre: `HF_TOKEN`
+   - Valor: tu token de HuggingFace
+   - Marcar como Secret
+
+3. **Subir archivos**:
+   ```bash
+   git clone https://huggingface.co/spaces/TU-USUARIO/TU-SPACE
+   cd TU-SPACE
+   cp -r ../hf_space_ready/* .
+   git add .
+   git commit -m "Initial deployment"
+   git push
+   ```
+
+4. **Verificar**:
+   ```bash
+   curl https://TU-USUARIO-TU-SPACE.hf.space/health
+   ```
+
+¡Listo! 🚀

README.md

@@ -1,10 +1,195 @@
 ---
-title: Chronos2 Excel Forecasting Api
-emoji: 💻
+title: Chronos2 Excel Forecasting API
+emoji: 📊
 colorFrom: blue
-colorTo: pink
+colorTo: green
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 📊 Chronos2 Excel Forecasting API
+
+API de pronósticos con IA para Microsoft Excel usando [Amazon Chronos-2](https://huggingface.co/amazon/chronos-t5-large).
+
+🔗 **Úsalo directamente desde Excel** con nuestro Office Add-in
+
+## 🚀 Características
+
+- ✅ **Pronósticos univariados**: Series temporales simples
+- ✅ **Detección de anomalías**: Identifica valores atípicos automáticamente
+- ✅ **Backtesting**: Valida la precisión de tus modelos
+- ✅ **API REST con FastAPI**: Fácil integración
+- ✅ **Documentación interactiva**: Swagger UI incluido
+
+## 📖 Documentación
+
+Accede a la documentación interactiva:
+- **Swagger UI**: `/docs`
+- **ReDoc**: `/redoc`
+- **Health Check**: `/health`
+
+## 🧪 Prueba Rápida
+
+### Pronóstico Simple
+
+```bash
+curl -X POST https://YOUR-USERNAME-chronos2-excel-forecasting-api.hf.space/forecast_univariate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "series": {"values": [100, 102, 105, 103, 108, 112, 115]},
+    "prediction_length": 3,
+    "freq": "D"
+  }'
+```
+
+**Respuesta esperada:**
+```json
+{
+  "timestamps": ["t+1", "t+2", "t+3"],
+  "median": [117.5, 119.2, 121.0],
+  "quantiles": {
+    "0.1": [112.3, 113.8, 115.5],
+    "0.5": [117.5, 119.2, 121.0],
+    "0.9": [122.7, 124.6, 126.5]
+  }
+}
+```
+
+### Detección de Anomalías
+
+```bash
+curl -X POST https://YOUR-USERNAME-chronos2-excel-forecasting-api.hf.space/detect_anomalies \
+  -H "Content-Type: application/json" \
+  -d '{
+    "context": {"values": [100, 102, 105, 103, 108]},
+    "recent_observed": [107, 200, 106],
+    "prediction_length": 3
+  }'
+```
+
+### Backtesting
+
+```bash
+curl -X POST https://YOUR-USERNAME-chronos2-excel-forecasting-api.hf.space/backtest_simple \
+  -H "Content-Type: application/json" \
+  -d '{
+    "series": {"values": [100, 102, 105, 103, 108, 112, 115, 118, 120, 122, 125, 128]},
+    "prediction_length": 7,
+    "test_length": 4
+  }'
+```
+
+## 🔗 Endpoints Disponibles
+
+| Endpoint | Método | Descripción |
+|----------|--------|-------------|
+| `/` | GET | Información de la API |
+| `/health` | GET | Health check del servicio |
+| `/docs` | GET | Documentación Swagger |
+| `/forecast_univariate` | POST | Pronóstico de serie simple |
+| `/detect_anomalies` | POST | Detectar valores atípicos |
+| `/backtest_simple` | POST | Validar precisión del modelo |
+| `/simple_forecast` | POST | Pronóstico rápido (testing) |
+
+## 💻 Uso con Excel
+
+Este API funciona perfectamente con nuestro **Office Add-in para Excel**:
+
+1. Descarga el Add-in desde [GitHub](https://github.com/tu-usuario/chronos2-server)
+2. Configura la URL de este Space en el Add-in
+3. ¡Realiza pronósticos directamente desde tus hojas de cálculo!
+
+### Ejemplo en Excel
+
+```javascript
+// En el Excel Add-in, configura:
+const API_BASE_URL = 'https://YOUR-USERNAME-chronos2-excel-forecasting-api.hf.space';
+```
+
+## 🛠️ Tecnologías
+
+- **Modelo**: [Amazon Chronos-2 T5-Large](https://huggingface.co/amazon/chronos-t5-large)
+- **Framework**: [FastAPI](https://fastapi.tiangolo.com/)
+- **Inference**: [Hugging Face Inference API](https://huggingface.co/docs/api-inference)
+- **Deployment**: Hugging Face Spaces (Docker)
+
+## 📊 Casos de Uso
+
+- 📈 **Ventas**: Predice demanda futura de productos
+- 💰 **Finanzas**: Proyecta ingresos y gastos
+- 📦 **Inventario**: Optimiza stock y reposición
+- 🌡️ **Sensores**: Anticipa valores de sensores IoT
+- 🏪 **Retail**: Planifica recursos y personal
+
+## ⚙️ Configuración
+
+### Variables de Entorno
+
+Para desplegar tu propia instancia, configura:
+
+- `HF_TOKEN`: Tu token de Hugging Face (requerido)
+- `CHRONOS_MODEL_ID`: ID del modelo (default: `amazon/chronos-t5-large`)
+- `PORT`: Puerto del servidor (default: `7860`)
+
+### Crear tu propio Space
+
+1. Fork este repositorio
+2. Crea un nuevo Space en Hugging Face
+3. Selecciona **Docker** como SDK
+4. Conecta tu repositorio
+5. Configura `HF_TOKEN` en los Secrets del Space
+6. ¡Listo!
+
+## 🔒 Seguridad
+
+- ✅ CORS configurado para orígenes permitidos
+- ✅ Validación de entrada con Pydantic
+- ✅ Rate limiting en HuggingFace Inference API
+- ✅ Timeouts configurados para evitar bloqueos
+
+## 📚 Recursos
+
+- [Documentación de Chronos-2](https://huggingface.co/amazon/chronos-t5-large)
+- [API de HuggingFace Inference](https://huggingface.co/docs/api-inference)
+- [FastAPI Docs](https://fastapi.tiangolo.com/)
+- [Tutorial de Office Add-ins](https://docs.microsoft.com/en-us/office/dev/add-ins/)
+
+## 🐛 Solución de Problemas
+
+### "Model is loading"
+
+La primera request puede tardar 30-60 segundos mientras el modelo se carga. Reintenta después.
+
+### "HF_TOKEN not configured"
+
+Asegúrate de configurar `HF_TOKEN` en los Secrets de tu Space.
+
+### Errores de timeout
+
+El modelo puede estar frío. Espera unos segundos y reintenta.
+
+## 📝 Licencia
+
+MIT License - Ver [LICENSE](LICENSE) para más detalles.
+
+## 🤝 Contribuir
+
+¿Quieres mejorar este proyecto?
+
+1. Fork el repositorio
+2. Crea una branch para tu feature (`git checkout -b feature/amazing`)
+3. Commit tus cambios (`git commit -m 'Add amazing feature'`)
+4. Push a la branch (`git push origin feature/amazing`)
+5. Abre un Pull Request
+
+## 📧 Contacto
+
+¿Preguntas o sugerencias? Abre un [issue en GitHub](https://github.com/tu-usuario/chronos2-server/issues).
+
+---
+
+**Desarrollado con ❤️ usando [Chronos-2](https://huggingface.co/amazon/chronos-t5-large) y [FastAPI](https://fastapi.tiangolo.com/)**
+
+🌟 Si te gusta este proyecto, ¡dale una estrella en [GitHub](https://github.com/tu-usuario/chronos2-server)!

app/main.py

@@ -0,0 +1,395 @@
+import os
+from typing import List, Dict, Optional
+import json
+
+import numpy as np
+import pandas as pd
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+from huggingface_hub import InferenceClient
+
+
+# =========================
+# Configuración
+# =========================
+
+HF_TOKEN = os.getenv("HF_TOKEN")
+MODEL_ID = os.getenv("CHRONOS_MODEL_ID", "amazon/chronos-t5-large")
+
+app = FastAPI(
+    title="Chronos-2 Forecasting API (HF Inference)",
+    description=(
+        "API de pronósticos usando Chronos-2 via Hugging Face Inference API. "
+        "Compatible con Excel Add-in."
+    ),
+    version="1.0.0",
+)
+
+# Configurar CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # En producción, especificar dominios permitidos
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Cliente de HF Inference
+if not HF_TOKEN:
+    print("⚠️  WARNING: HF_TOKEN no configurado. La API puede no funcionar correctamente.")
+    print("   Configura HF_TOKEN en las variables de entorno del Space.")
+    client = None
+else:
+    client = InferenceClient(token=HF_TOKEN)
+
+
+# =========================
+# Modelos Pydantic
+# =========================
+
+class UnivariateSeries(BaseModel):
+    values: List[float]
+
+
+class ForecastUnivariateRequest(BaseModel):
+    series: UnivariateSeries
+    prediction_length: int = Field(7, description="Número de pasos a predecir")
+    quantile_levels: Optional[List[float]] = Field(
+        default=[0.1, 0.5, 0.9],
+        description="Cuantiles para intervalos de confianza"
+    )
+    freq: str = Field("D", description="Frecuencia temporal (D, W, M, etc.)")
+
+
+class ForecastUnivariateResponse(BaseModel):
+    timestamps: List[str]
+    median: List[float]
+    quantiles: Dict[str, List[float]]
+
+
+class AnomalyDetectionRequest(BaseModel):
+    context: UnivariateSeries
+    recent_observed: List[float]
+    prediction_length: int = 7
+    quantile_low: float = 0.05
+    quantile_high: float = 0.95
+
+
+class AnomalyPoint(BaseModel):
+    index: int
+    value: float
+    predicted_median: float
+    lower: float
+    upper: float
+    is_anomaly: bool
+
+
+class AnomalyDetectionResponse(BaseModel):
+    anomalies: List[AnomalyPoint]
+
+
+class BacktestRequest(BaseModel):
+    series: UnivariateSeries
+    prediction_length: int = 7
+    test_length: int = 28
+
+
+class BacktestMetrics(BaseModel):
+    mae: float
+    mape: float
+    rmse: float
+
+
+class BacktestResponse(BaseModel):
+    metrics: BacktestMetrics
+    forecast_median: List[float]
+    forecast_timestamps: List[str]
+    actuals: List[float]
+
+
+# =========================
+# Función auxiliar para llamar a HF Inference
+# =========================
+
+def call_chronos_inference(series: List[float], prediction_length: int) -> Dict:
+    """
+    Llama a la API de Hugging Face Inference para Chronos.
+    Retorna un diccionario con las predicciones.
+    """
+    if client is None:
+        raise HTTPException(
+            status_code=503,
+            detail="HF_TOKEN no configurado. Contacta al administrador del servicio."
+        )
+    
+    try:
+        # Intentar usando el endpoint específico de time series
+        import requests
+        
+        url = f"https://api-inference.huggingface.co/models/{MODEL_ID}"
+        headers = {"Authorization": f"Bearer {HF_TOKEN}"}
+        
+        payload = {
+            "inputs": series,
+            "parameters": {
+                "prediction_length": prediction_length,
+                "num_samples": 100  # Para obtener cuantiles
+            }
+        }
+        
+        response = requests.post(url, headers=headers, json=payload, timeout=60)
+        
+        if response.status_code == 503:
+            raise HTTPException(
+                status_code=503,
+                detail="El modelo está cargando. Por favor, intenta de nuevo en 30-60 segundos."
+            )
+        elif response.status_code != 200:
+            raise HTTPException(
+                status_code=response.status_code,
+                detail=f"Error de la API de HuggingFace: {response.text}"
+            )
+        
+        result = response.json()
+        return result
+        
+    except requests.exceptions.Timeout:
+        raise HTTPException(
+            status_code=504,
+            detail="Timeout al comunicarse con HuggingFace API. El modelo puede estar cargando."
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Error inesperado: {str(e)}"
+        )
+
+
+def process_chronos_output(raw_output: Dict, prediction_length: int) -> Dict:
+    """
+    Procesa la salida de Chronos para extraer mediana y cuantiles.
+    """
+    # La API de Chronos puede devolver diferentes formatos
+    # Intentamos adaptarnos a ellos
+    
+    if isinstance(raw_output, list):
+        # Si es una lista de valores, asumimos que es la predicción media
+        median = raw_output[:prediction_length]
+        return {
+            "median": median,
+            "quantiles": {
+                "0.1": median,  # Sin cuantiles, usar median
+                "0.5": median,
+                "0.9": median
+            }
+        }
+    
+    # Si tiene estructura más compleja, intentar extraer
+    if "forecast" in raw_output:
+        forecast = raw_output["forecast"]
+        if "median" in forecast:
+            median = forecast["median"][:prediction_length]
+        else:
+            median = forecast.get("mean", [0] * prediction_length)[:prediction_length]
+        
+        quantiles = forecast.get("quantiles", {})
+        return {
+            "median": median,
+            "quantiles": quantiles
+        }
+    
+    # Formato por defecto
+    return {
+        "median": [0] * prediction_length,
+        "quantiles": {
+            "0.1": [0] * prediction_length,
+            "0.5": [0] * prediction_length,
+            "0.9": [0] * prediction_length
+        }
+    }
+
+
+# =========================
+# Endpoints
+# =========================
+
+@app.get("/")
+def root():
+    """Información básica de la API"""
+    return {
+        "name": "Chronos-2 Forecasting API",
+        "version": "1.0.0",
+        "model": MODEL_ID,
+        "status": "running",
+        "docs": "/docs",
+        "health": "/health"
+    }
+
+
+@app.get("/health")
+def health():
+    """Health check del servicio"""
+    return {
+        "status": "ok" if HF_TOKEN else "warning",
+        "model_id": MODEL_ID,
+        "hf_token_configured": HF_TOKEN is not None,
+        "message": "Ready" if HF_TOKEN else "HF_TOKEN not configured"
+    }
+
+
+@app.post("/forecast_univariate", response_model=ForecastUnivariateResponse)
+def forecast_univariate(req: ForecastUnivariateRequest):
+    """
+    Pronóstico para una serie temporal univariada.
+    
+    Compatible con el Excel Add-in.
+    """
+    values = req.series.values
+    n = len(values)
+    
+    if n == 0:
+        raise HTTPException(status_code=400, detail="La serie no puede estar vacía.")
+    
+    if n < 3:
+        raise HTTPException(
+            status_code=400,
+            detail="La serie debe tener al menos 3 puntos históricos."
+        )
+    
+    # Llamar a la API de HuggingFace
+    raw_output = call_chronos_inference(values, req.prediction_length)
+    
+    # Procesar la salida
+    processed = process_chronos_output(raw_output, req.prediction_length)
+    
+    # Generar timestamps
+    timestamps = [f"t+{i+1}" for i in range(req.prediction_length)]
+    
+    return ForecastUnivariateResponse(
+        timestamps=timestamps,
+        median=processed["median"],
+        quantiles=processed["quantiles"]
+    )
+
+
+@app.post("/detect_anomalies", response_model=AnomalyDetectionResponse)
+def detect_anomalies(req: AnomalyDetectionRequest):
+    """
+    Detecta anomalías comparando valores observados con predicciones.
+    """
+    n_hist = len(req.context.values)
+    
+    if n_hist == 0:
+        raise HTTPException(status_code=400, detail="El contexto no puede estar vacío.")
+    
+    if len(req.recent_observed) != req.prediction_length:
+        raise HTTPException(
+            status_code=400,
+            detail="recent_observed debe tener la misma longitud que prediction_length."
+        )
+    
+    # Hacer predicción
+    raw_output = call_chronos_inference(req.context.values, req.prediction_length)
+    processed = process_chronos_output(raw_output, req.prediction_length)
+    
+    # Comparar con valores observados
+    anomalies: List[AnomalyPoint] = []
+    
+    median = processed["median"]
+    # Intentar obtener cuantiles o usar aproximaciones
+    q_low = processed["quantiles"].get(str(req.quantile_low), median)
+    q_high = processed["quantiles"].get(str(req.quantile_high), median)
+    
+    for i, obs in enumerate(req.recent_observed):
+        if i < len(median):
+            lower = q_low[i] if i < len(q_low) else median[i] * 0.8
+            upper = q_high[i] if i < len(q_high) else median[i] * 1.2
+            predicted = median[i]
+            is_anom = (obs < lower) or (obs > upper)
+            
+            anomalies.append(
+                AnomalyPoint(
+                    index=i,
+                    value=obs,
+                    predicted_median=predicted,
+                    lower=lower,
+                    upper=upper,
+                    is_anomaly=is_anom,
+                )
+            )
+    
+    return AnomalyDetectionResponse(anomalies=anomalies)
+
+
+@app.post("/backtest_simple", response_model=BacktestResponse)
+def backtest_simple(req: BacktestRequest):
+    """
+    Backtesting simple: divide la serie en train/test y evalúa métricas.
+    """
+    values = np.array(req.series.values, dtype=float)
+    n = len(values)
+    
+    if n <= req.test_length:
+        raise HTTPException(
+            status_code=400,
+            detail="La serie debe ser más larga que test_length."
+        )
+    
+    # Dividir en train/test
+    train = values[: n - req.test_length].tolist()
+    test = values[n - req.test_length :].tolist()
+    
+    # Hacer predicción
+    raw_output = call_chronos_inference(train, req.test_length)
+    processed = process_chronos_output(raw_output, req.test_length)
+    
+    forecast = np.array(processed["median"], dtype=float)
+    test_arr = np.array(test, dtype=float)
+    
+    # Calcular métricas
+    mae = float(np.mean(np.abs(test_arr - forecast)))
+    rmse = float(np.sqrt(np.mean((test_arr - forecast) ** 2)))
+    
+    eps = 1e-8
+    mape = float(np.mean(np.abs((test_arr - forecast) / (test_arr + eps)))) * 100.0
+    
+    timestamps = [f"test_t{i+1}" for i in range(req.test_length)]
+    
+    metrics = BacktestMetrics(mae=mae, mape=mape, rmse=rmse)
+    
+    return BacktestResponse(
+        metrics=metrics,
+        forecast_median=forecast.tolist(),
+        forecast_timestamps=timestamps,
+        actuals=test,
+    )
+
+
+# =========================
+# Endpoints simplificados para testing
+# =========================
+
+@app.post("/simple_forecast")
+def simple_forecast(series: List[float], prediction_length: int = 7):
+    """
+    Endpoint simplificado para testing rápido.
+    """
+    if not series:
+        raise HTTPException(status_code=400, detail="Serie vacía")
+    
+    raw_output = call_chronos_inference(series, prediction_length)
+    processed = process_chronos_output(raw_output, prediction_length)
+    
+    return {
+        "input_series": series,
+        "prediction_length": prediction_length,
+        "forecast": processed["median"],
+        "model": MODEL_ID
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.getenv("PORT", 7860))
+    uvicorn.run(app, host="0.0.0.0", port=port)

requirements.txt

@@ -0,0 +1,7 @@
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+pandas>=2.0.0
+numpy>=1.24.0
+huggingface_hub>=0.20.0
+pydantic>=2.0.0
+python-dotenv>=1.0.0