README.md

metadata

title: Chronos2 Excel Forecasting API
emoji: 📊
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
license: mit

📊 Chronos2 Excel Forecasting API

API de pronósticos con IA para Microsoft Excel usando Amazon Chronos-2.

🔗 Ú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

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:

{
  "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

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

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
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

// 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
• Framework: FastAPI
• Inference: Hugging Face Inference API
• 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
• API de HuggingFace Inference
• FastAPI Docs
• Tutorial de Office 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 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.

---

Desarrollado con ❤️ usando Chronos-2 y FastAPI

🌟 Si te gusta este proyecto, ¡dale una estrella en GitHub!