Sentiment API

Análisis Inteligente de Feedback de Clientes

Sistema que ayuda a empresas a entender el sentimiento de los comentarios de sus clientes mediante análisis automático de texto con modelos de Machine Learning.

📋 Descripción del Proyecto

Sentiment API es una API simple que recibe textos (comentarios, reseñas o tweets), aplica un modelo de Data Science para clasificar el sentimiento (Positivo / Negativo) y devuelve el resultado en formato JSON, permitiendo que las aplicaciones consuman esta predicción automáticamente.

🎯 Sector de Negocio

Atención al cliente / Marketing / Operaciones — Empresas que recopilan opiniones de clientes (reseñas, comentarios en redes sociales, encuestas de satisfacción) y quieren entender rápidamente si el sentimiento es positivo o negativo.

💼 Necesidad del Cliente

Un cliente (empresa) recibe muchos comentarios y no puede leerlos todos manualmente. Necesita:

✅ Saber rápidamente si los clientes se están quejando o elogiando
✅ Priorizar respuestas a comentarios negativos
✅ Medir la satisfacción a lo largo del tiempo

Este proyecto ofrece una solución automática para clasificar mensajes y generar información accionable.

📊 Validación de Mercado

El análisis de sentimiento es útil para:

Acelerar la atención al cliente: Identificar urgencias y priorizar respuestas
Monitorear campañas de marketing: Evaluar el impacto de estrategias publicitarias
Comparar la imagen de marca: Analizar la percepción a lo largo del tiempo

Incluso una solución simple (modelo básico) tiene valor: las pequeñas y medianas empresas utilizan herramientas similares para entender los feedbacks sin un equipo dedicado.

🎓 Contexto del Hackathon

Organización: NoCountry / Alura LATAM
Equipo: H12-25-L-Equipo 63
Período: Diciembre 2025 – Enero 2026

Objetivo Principal

Entregar un MVP funcional que demuestre la integración entre Data Science y Back-end:

Un microservicio de Data Science (Flask) con el modelo cargado
Una API que consume ese microservicio y responde a las peticiones

Alcance

✨ Características Principales

🔍 Análisis de Sentimiento: Clasificación automática de textos (Positivo/Negativo)
📊 Probabilidad Asociada: Cada análisis incluye un nivel de confianza (0-1)
✅ Validación Robusta: Validación de entrada en capa de API
🌐 API REST: Endpoints versionados bajo /v1
📈 Dashboard Visual: Interfaz React con navegación por páginas
📦 Batch + Analytics: Análisis masivo, historial, filtros y exportación CSV
🤖 Modelo ML: Modelo entrenado con datasets especializados en reseñas de clientes

📦 Entregables

Microservicio DS (Flask): Modelo entrenado serializado (.pkl) y endpoints de predicción
Back-End (Spring Boot): API que consume el modelo, endpoint /v1/sentiment, logs y manejo de errores
Documentación: README con instrucciones de ejecución, ejemplos y dependencias
Demonstración: API en acción (Postman/cURL o dashboard) y explicación del modelo

🎯 Funcionalidades Exigidas (MVP)

✅ Endpoint POST /v1/sentiment que acepta {"text": "..."} y devuelve {"prevision": "Positivo", "probabilidad": 0.87}
✅ Modelo entrenado y cargable (archivo o microservicio DS)
✅ Validación de input (campo text obligatorio, 10–500 caracteres)
✅ Respuesta clara: label + probabilidad (0-1) y mensajes de error amigables
✅ Ejemplos de uso: 2 ejemplos reales (positivo, negativo)

Ver detalles completos del contrato de la API en docs/API-CONTRACT.md.

🛠️ Tecnologías Utilizadas

Backend

Java 21
Spring Boot 4.0.1
Spring Web MVC
Spring Validation
Lombok
Maven

Data Science

Python 3.8+
Pandas: Lectura y limpieza de datos
scikit-learn: TF-IDF + Logistic Regression
joblib: Serialización del modelo
Flask: Microservicio de predicción
NLTK: Preprocesamiento de texto
deep_translator: Traducción automática

Para más detalles sobre tecnologías y arquitectura, consulta docs/ARCHITECTURE.md.

📦 Requisitos Previos

Para Windows

Java 21 o superior
Maven 3.6+ (o usar el wrapper incluido: mvnw.cmd)
Docker Desktop para Windows (para PostgreSQL)
Git
Python 3.8+ (para ejecutar el microservicio DS)

🚀 Instalación y Ejecución

Windows

Paso 1: Levantar servicios con Docker Compose

Abre PowerShell o CMD y navega a la raíz del proyecto:

cd SentimentAPI

Levanta los servicios (Postgres + Backend + Data Science + Dashboard):

docker compose up -d --build

Verifica que los contenedores estén corriendo:

docker ps

Deberías ver sentiment-postgres, sentiment-backend, sentiment-datascience y sentiment-dashboard.

(Opcional) Ver los logs:

docker compose logs -f

(Opcional) Conectarte a PostgreSQL con psql:

docker exec -it sentiment-postgres psql -U postgres -d sentiment_db

Para salir de psql, escribe: \q

Paso 2: Ejecutar la Aplicación Spring Boot (modo local)

Asegúrate de estar en la carpeta backend:

cd backend

Compila el proyecto:

mvnw.cmd clean install

Ejecuta la aplicación:

mvnw.cmd spring-boot:run

La API estará disponible en http://localhost:8080

Dashboard (React)

Si usas Docker, el dashboard estará en http://localhost:3000. Para desarrollo local con recarga en caliente:

cd dashboard
npm install
npm run dev

Data Science

cd datascience/python_service
pip install -r requirements.txt
python app.py

📖 Uso de Endpoints

Todos los endpoints pueden probarse desde el dashboard, con cURL o con Postman. Antes de cada endpoint encontrarás un breve texto con la forma recomendada de probarlo.

`POST /v1/sentiment`

Puedes probarlo desde el dashboard en Inicio, ingresando un texto individual y revisando la predicción. Para pruebas rápidas en consola usa cURL, y en Postman envía un body raw JSON.

curl -X POST http://localhost:8080/v1/sentiment \
  -H "Content-Type: application/json" \
  -d '{"text": "The service was excellent and very helpful"}'

{
  "prevision": "Positivo",
  "probabilidad": 0.87
}

La respuesta puede incluir opcionalmente textoTraducido y palabrasClave cuando el microservicio de Data Science las devuelve.

`POST /v1/sentiment/batch`

Puedes probarlo desde el dashboard en Batch, cargando un CSV o ingresando un conjunto de textos. En cURL/Postman envía el arreglo en texts.

curl -X POST http://localhost:8080/v1/sentiment/batch \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Great service", "Terrible support"]}'

{
  "total": 2,
  "results": [
    { "prevision": "Positivo", "probabilidad": 0.93 },
    { "prevision": "Negativo", "probabilidad": 0.88 }
  ]
}

`GET /v1/stats`

Puedes ver estos valores en el dashboard en Inicio (métricas generales). Para validarlo en consola usa cURL/Postman con una petición GET.

curl http://localhost:8080/v1/stats

{
  "total_analizados": 120,
  "positivos": 80,
  "negativos": 40,
  "porcentaje_positivos": "67%",
  "porcentaje_negativos": "33%",
  "top_words_pos": { "great": 10, "excellent": 8 },
  "top_words_neg": { "bad": 6, "late": 5 }
}

`GET /v1/analytics`

Puedes usar este endpoint como resumen técnico y comparar los totales con lo que muestra el dashboard. Para pruebas directas usa cURL o Postman con un GET.

curl http://localhost:8080/v1/analytics

{
  "totalAnalisis": 120,
  "positivos": 80,
  "negativos": 40,
  "promedioConfianza": 0.86
}

`GET /v1/analytics/range`

En el dashboard puedes probarlo en Historial filtrando por rango y sentimiento. En cURL/Postman envía los query params.

curl "http://localhost:8080/v1/analytics/range?startDate=01-01-2026&endDate=31-01-2026&sentiment=Positivo&page=0&size=15"

{
  "desde": "01-01-2026",
  "hasta": "31-01-2026",
  "total": 120,
  "positivos": 80,
  "negativos": 40,
  "porcentajePositivos": "67%",
  "porcentajeNegativos": "33%",
  "topWordsPos": { "great": 10, "excellent": 8 },
  "topWordsNeg": { "bad": 6, "late": 5 },
  "registros": [],
  "page": 0,
  "size": 15,
  "totalPages": 8
}

`GET /v1/analytics/range/export`

En el dashboard puedes exportar desde Historial usando el botón de descarga. En cURL/Postman usa el endpoint de exportación para bajar el CSV.

curl -O -J "http://localhost:8080/v1/analytics/range/export?startDate=01-01-2026&endDate=31-01-2026"

Para ejemplos completos, validaciones, códigos de error y más detalles, consulta docs/API-CONTRACT.md.

🧭 Navegación del Dashboard

El dashboard está dividido en tres páginas principales:

Inicio: análisis individual y métricas en tiempo real.
Historial: consultas por rango, filtro por sentimiento, exportación CSV y paginación.
Batch: carga CSV y resultados masivos con detalle en modal.

Acceso por defecto: http://localhost:3000

🤖 Explicación del modelo

Luego de que la API valide el comentario, este pasa por el microservicio DS donde:

El texto es limpiado y procesado: hay que normalizar los caracteres especiales (signos, puntuaciones, etc. no son relevantes).
Se traduce al idioma ingles: Se globaliza el idioma para mayor facilidad de análisis.
Se aplica vectorización TF-IDF: El modelo solo entiende números; este proceso convierte el texto en una matriz.
El modelo clasifica: Entrenado con un dataset de calidad en inglés y con ayuda de los pasos anteriores, el modelo entiende datos de forma secuencial a su vez que comprende expresiones, metáforas, etc. para clasificar binariamente y un nivel de confianza en porcentaje (que tan seguro está).
Envia resultados: Una vez que sabe la categoría del comentario y la probabilidad asociada, este envía estos datos a la API para presentar al dasboard. Adicionalmente, envia el texto traducido al inglés y las palabras clave que el modelo detecte (en inglés también).

Para más detalles sobre las decisiones de la arquitectura del modelado, consulta RFC-002.md.

Para más detalles sobre la historia del comentario en el flujo funcional, consulta ARCHITECTURE.md.

📁 Estructura del Proyecto

SentimentAPI/
├── README.md                       # Este archivo
│
├── backend/                        # API REST (Spring Boot)
│   ├── src/
│   │   ├── main/java/com/sentiment/backend/
│   │   │   ├── controller/         # Endpoints REST
│   │   │   ├── service/            # Lógica de negocio
│   │   │   ├── dto/                # Objetos de entrada/salida
│   │   │   ├── domain/             # Entidades de negocio
│   │   │   ├── config/             # Configuraciones
│   │   │   ├── mapper/             # Mappers entre capas
│   │   │   └── exception/          # Manejo de errores
│   │   └── resources/
│   │       └── application.yml
│   └── pom.xml
│
├── datascience/                    # Microservicio DS
│   └── python_service/
│       ├── app.py                  # API Flask (predict/predict_batch)
│       ├── requirements.txt        # Dependencias Python
│       ├── sentiment_model_v1.pkl  # Modelo entrenado serializado
│       └── tfidf_vectorizer_v1.pkl # Vectorizador serializado
│
├── dashboard/                      # Frontend (UI)
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   └── services/
│   └── package.json
│
└── docs/                           # Documentación
    ├── ARCHITECTURE.md             # Arquitectura del sistema
    ├── API-CONTRACT.md             # Contrato de la API
    ├── GITHUB_WORKFLOW.md          # Flujo de trabajo
    ├── RFC-001.md                  # Decisiones arquitectónicas
    └── RFC-002.md                  # Decisiones de Data Science

📚 Documentación

ARCHITECTURE.md: Arquitectura del sistema, flujo de datos y decisiones técnicas
API-CONTRACT.md: Contrato completo de la API, endpoints, validaciones y ejemplos
GITHUB_WORKFLOW.md: Flujo de trabajo, ramas, commits y Pull Requests
RFC-001: Decisiones arquitectónicas y justificaciones
RFC-002: Decisiones del modelado y el equipo de Data Science

👥 Equipo

Proyecto: H12-25-L-Equipo 63
Período: Diciembre 2025 – Enero 2026

Integrante	Rol
Mauricio Flores	Líder general + Data Science
Yazmani Reyes	Data Science
Leandro Díaz	Data Science
Domingo Gálaz	Data Science
Javiera Pulgar	Back-End + Dashboard
Fernanda Fonseca	Back-End

🔄 Flujo de Trabajo

Este proyecto sigue un flujo de trabajo basado en Git Flow. Para más detalles sobre ramas, commits y Pull Requests, consulta docs/GITHUB_WORKFLOW.md.

Regla de oro: ❌ Nunca commits directos a main. Todo debe pasar por Pull Requests y revisión.

Data Science

Los tests del modelo se realizan en el notebook de Jupyter, incluyendo métricas de desempeño (Accuracy, Precision, Recall, F1-score).

⚠️ Especificaciones extras

Idioma: El microservicio DS detecta idioma y traduce a inglés para el análisis
Longitud: Textos entre 10 y 500 caracteres
Modelo: TF-IDF + Logistic Regression

🔗 Enlaces Útiles

Desarrollado con ❤️ por H12-25-L-Equipo 63
Hackathon NoCountry / Alura LATAM - Diciembre 2025 - Enero 2026

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
backend		backend
dashboard		dashboard
datascience		datascience
docs		docs
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

Sentiment API

📋 Descripción del Proyecto

🎯 Sector de Negocio

💼 Necesidad del Cliente

📊 Validación de Mercado

🎓 Contexto del Hackathon

Objetivo Principal

Alcance

✨ Características Principales

📦 Entregables

🎯 Funcionalidades Exigidas (MVP)

🛠️ Tecnologías Utilizadas

Backend

Data Science

📦 Requisitos Previos

Para Windows

🚀 Instalación y Ejecución

Windows

Paso 1: Levantar servicios con Docker Compose

Paso 2: Ejecutar la Aplicación Spring Boot (modo local)

Dashboard (React)

Data Science

📖 Uso de Endpoints

POST /v1/sentiment

POST /v1/sentiment/batch

GET /v1/stats

GET /v1/analytics

GET /v1/analytics/range

GET /v1/analytics/range/export

🧭 Navegación del Dashboard

🤖 Explicación del modelo

📁 Estructura del Proyecto

📚 Documentación

👥 Equipo

🔄 Flujo de Trabajo

Data Science

⚠️ Especificaciones extras

🔗 Enlaces Útiles

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`POST /v1/sentiment`

`POST /v1/sentiment/batch`

`GET /v1/stats`

`GET /v1/analytics`

`GET /v1/analytics/range`

`GET /v1/analytics/range/export`

Packages