Sobre el proyecto

# Nebula Cafe — Sistema de Armonía Predictiva de Afluencia e Inventario Nebula Cafe es un panel analítico de código abierto construido con Streamlit, diseñado para dueños y gerentes de cafeterías que desean ir más allá de los informes históricos hacia la toma de decisiones predictiva. El proyecto se posiciona como un "motor de decisiones" que pronostica la afluencia de clientes, optimiza el reabastecimiento de ingredientes y equilibra la eficiencia operativa con una interfaz cálida y acogedora. ## Propósito Principal A diferencia de las herramientas analíticas tradicionales para cafeterías que simplemente informan ventas pasadas, Nebula Cafe utiliza pronósticos de series temporales (específicamente modelos LSTM) para predecir el tráfico de clientes hasta 7 días por adelantado. Esto permite a los usuarios: - Programar personal de manera inteligente según los períodos ocupados previstos - Pedir inventario justo a tiempo para reducir el desperdicio perecedero (se afirma una reducción de hasta el 30%) - Identificar períodos lentos para programar eventos o promociones - Comparar patrones en múltiples ubicaciones (para gerentes regionales) ## Características Clave ### Mapeo Predictivo de Afluencia - Modelo de series temporales basado en LSTM para pronósticos de recuento de clientes a 7 días - Línea de tiempo visual con intervalos de confianza (visualizados como "bandas nubladas") - Ajustes dinámicos basados en datos de días festivos y clima (integración API opcional) ### Asesor de Inventario Inteligente - Cruza las ventas previstas con los niveles de stock actuales - Genera listas de reorden codificadas por colores: verde (en stock), ámbar (pedir en 2 días), rojo (pedir ahora) - Aprende de errores pasados de exceso de stock para mejorar recomendaciones futuras ### Experiencia de Usuario - Diseño de widgets de arrastrar y soltar que se adapta a pantallas de tableta o teléfono - Interfaz multilingüe que admite inglés, español, mandarín y árabe - Bot de soporte/FAQ integrado (basado en reglas, sin necesidad de claves API externas) - Editor de temas sin código para personalizar colores y fuentes - Modo sin conexión para funcionalidad completa sin internet ### Privacidad y Manejo de Datos - Todos los datos se procesan localmente por defecto; cero cargas a la nube - No se requieren claves de autenticación - La agregación anónima garantiza que no se almacene PII de clientes - Generador de datos sintéticos opcional para pruebas y experimentación ## Pila Tecnológica - **Frontend:** Streamlit con CSS personalizado (sin bibliotecas JavaScript) - **Backend:** Python 3.10+ con Pandas, NumPy y Prophet para pronósticos - **Almacenamiento de Datos:** Archivos CSV/JSON locales (soporte SQLite opcional) - **Visualización:** Plotly para gráficos interactivos, Matplotlib para exportaciones estáticas - **Pruebas:** PyTest para pruebas unitarias y de integración ## Casos de Uso - **Dueño de Cafetería Individual:** Planificar eventos durante períodos lentos previstos - **Gerente Regional:** Comparar afluencia entre ubicaciones para redistribuir personal - **Socio de Tostador:** Usar el asesor de inventario para determinar envíos semanales de granos - **Inversor:** Exportar informes semanales con métricas de ROI y tendencias de densidad de clientes ## Hoja de Ruta (2026) - **Q1 2026:** Lanzamiento v1.0 con módulos principales de pronóstico e inventario - **Q2 2026:** Seguimiento opcional de precios de competidores mediante raspado de menús públicos - **Q3 2026:** Integración con POS Square/Toast mediante API abierta - **Q4 2026:** Aplicación complementaria móvil (Flutter) para alertas instantáneas de afluencia ## Instalación y Uso Los usuarios pueden descargar el repositorio como archivo ZIP desde la página de GitHub o clonarlo usando un cliente git. El proyecto requiere Python 3.10+ y las dependencias listadas en el repositorio. No se necesitan asistentes de instalación—solo código Python puro. ## Comunidad y Contribución Las contribuciones son bienvenidas, incluyendo: - Agregar nuevos modelos de pronóstico (por ejemplo, ARIMA, Facebook Prophet) - Traducir la interfaz a idiomas adicionales - Diseñar nuevos widgets para métricas ambientales (ruido ambiente, temperatura) El proyecto incluye documentación en una carpeta `docs/` y utiliza issues y discusiones de GitHub para soporte comunitario. ## Licencia Licenciado bajo la Licencia MIT, permitiendo uso, modificación y distribución gratuitos para fines comerciales o no comerciales. ## Aviso Legal El software se proporciona "tal cual" sin garantía. Los modelos predictivos dependen de datos de entrenamiento sintéticos para demostración y pueden no reflejar precisión del mundo real sin calibración. El desarrollador no asume responsabilidad por decisiones comerciales tomadas basadas en los resultados del panel. El bot de soporte es un asistente de FAQ programado, no un agente humano en vivo. Los usuarios siempre deben validar las recomendaciones de inventario con recuentos físicos.