Hugging Face's logo

Spaces:
iagofp
/
ValorSentimental
Running

App Files Community
ValorSentimental / README.md
iagofp's picture
iagofp
chore: configurar despliegue en HF Spaces
5a2a43a
preview code
|
raw
history blame contribute delete
7.3 kB
metadata 
title: Valor Sentimental
emoji: 🎬
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

Valor Sentimental

Valor Sentimental es una aplicacion web de recomendacion de peliculas basada en el estado emocional del usuario. El sistema analiza un texto escrito por la persona, identifica su emocion dominante y recomienda peliculas teniendo en cuenta su historial, sus valoraciones y distintas estrategias de exploracion o zona de confort.

El proyecto combina un backend en Flask, una interfaz en Vue 3 con Vuetify, una base de datos SQLite local y datos de MovieLens para construir el catalogo de peliculas.

Caracteristicas principales

  • Analisis emocional de texto en espanol mediante pysentimiento/robertuito-emotion-analysis.
  • Recomendacion de peliculas segun emocion, historial y calidad global.
  • Tres estrategias de recomendacion (v1, v2, v3) implementadas con patron Strategy.
  • Registro, login, logout, cambio de contrasena y eliminacion de cuenta.
  • Historial de peliculas vistas con valoracion de 1 a 5.
  • Seguimiento emocional antes y despues de ver una recomendacion.
  • Onboarding inicial para indicar peliculas ya vistas.
  • Busqueda de peliculas y listado de populares usando MovieLens.
  • Obtencion opcional de posters mediante OMDb.
  • Persistencia local en SQLite.

Tecnologias

Backend

  • Python
  • Flask
  • Flask-CORS
  • SQLite
  • Transformers
  • PyTorch
  • Hugging Face Inference Providers
  • OMDb API opcional

Frontend

  • Vue 3
  • Vue Router
  • Vuetify
  • Vite
  • Sass
  • Material Design Icons

Datos

  • MovieLens ml-latest

Estructura del proyecto 

ValorSentimental/
|-- backend/
|   |-- aplicacion.py              # Rutas Flask y configuracion principal de la API
|   |-- main.py                    # Punto de entrada del servidor
|   |-- base_datos.py              # Creacion de tablas SQLite
|   |-- conexion_bd.py             # Singleton de conexion a BD
|   |-- config.py                  # Constantes, rutas y variables de entorno
|   |-- dao/                       # Acceso a datos
|   `-- services/                  # Logica de analisis, recomendacion y chatbot
|-- chatbot/
|   |-- src/                       # Aplicacion Vue
|   |-- package.json
|   `-- vite.config.js
|-- data/
|   |-- ml-latest/                 # CSV de MovieLens
|   |-- procesado/                 # Datasets procesados
|   |-- download_movielens_large.py
|   `-- script.py                  # Generacion del dataset emocional
|-- docs/                          # Diagramas y documentacion auxiliar
|-- DIAGRAMAS_PATRONES.md          # Patrones y arquitectura
|-- requirements.txt
`-- README.md

Requisitos previos

  • Python 3.10 o superior recomendado.
  • Node.js 18 o superior recomendado.
  • npm.
  • Conexion a internet en el primer arranque si el modelo de Hugging Face no esta descargado localmente.

Variables de entorno

El backend carga variables desde backend/.env.

Crea un archivo backend/.env con el siguiente contenido si quieres activar las funciones externas:

HF_TOKEN=tu_token_de_huggingface
OMDB_API_KEY=tu_api_key_de_omdb

HF_TOKEN se usa para generar respuestas de chatbot con Hugging Face. Si falla o no existe, la aplicacion usa una respuesta de respaldo basada en plantilla.

OMDB_API_KEY es opcional y permite recuperar posters de peliculas desde OMDb.

Instalacion

1. Clonar el repositorio 

git clone <url-del-repositorio>
cd ValorSentimental

2. Instalar dependencias del backend 

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

En Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

3. Instalar dependencias del frontend 

cd chatbot
npm install

Preparacion de datos

El recomendador usa los CSV de MovieLens en data/ml-latest. Si no estan presentes, se pueden descargar con:

python data/download_movielens_large.py

Tambien se puede generar el dataset procesado de 100 peliculas con emociones inferidas por genero:

python data/script.py

El backend intenta cargar primero data/ml-latest/movies.csv, ratings.csv y links.csv. Si no encuentra el dataset completo, usa como alternativa data/procesado/peliculas_100_emociones.csv.

Ejecucion

Backend

Desde la raiz del proyecto:

cd backend
python main.py

La API queda disponible en:

http://localhost:5000

En el primer arranque puede tardar porque se carga o descarga el modelo de emociones.

Frontend

En otra terminal:

cd chatbot
npm run dev

Vite mostrara la URL local, normalmente:

http://localhost:5173

El frontend esta configurado para llamar al backend en http://localhost:5000.

Flujo de uso

  1. El usuario se registra o inicia sesion.
  2. Durante el registro puede anadir peliculas ya vistas para construir un historial inicial.
  3. En el chat escribe como se siente.
  4. El backend analiza el texto y calcula emocion dominante, valencia y arousal.
  5. El recomendador propone peliculas segun el historial y la estrategia seleccionada.
  6. El usuario puede marcar una pelicula como vista y valorarla.
  7. Despues puede indicar como se siente, cerrando un ciclo pre/post recomendacion.

Estrategias de recomendacion

Las estrategias estan en backend/services/estrategias_recomendacion.py.

  • v1: logica binaria. Si la emocion es positiva, recomienda fuera de la zona de confort; si es negativa, recomienda dentro.
  • v2: pondera de forma continua el grado de confort y la calidad de la pelicula.
  • v3: calcula un objetivo de confort adaptativo usando valencia y arousal.

Si el usuario no tiene historial, el sistema recomienda peliculas de calidad global usando una puntuacion bayesiana suavizada.

API principal

Autenticacion

  • POST /auth/register
  • POST /auth/login
  • POST /auth/logout
  • POST /auth/password
  • POST /auth/verify
  • DELETE /auth/account

Analisis y recomendacion

  • POST /analizar
  • POST /recomendacion/seguimiento

Historial

  • POST /historial/visto
  • GET /historial
  • DELETE /historial
  • GET /historial/transiciones

Catalogo

  • GET /peliculas/populares
  • GET /peliculas/buscar?q=<texto>
  • POST /onboarding/historial
  • GET /poster/<imdb_id>

Base de datos

La base de datos se crea automaticamente en:

backend/history.db

Tablas principales:

  • Usuarios
  • Peliculas
  • Emociones
  • Historial_Peliculas
  • Ciclo_Recomendacion

La arquitectura usa DAOs para separar el acceso a datos de la logica de negocio y un Singleton para centralizar la conexion SQLite.

Documentacion adicional

El repositorio incluye documentacion de apoyo:

  • DIAGRAMAS_PATRONES.md: patrones de diseno y arquitectura por capas.
  • docs/diagrama_er.md: diagrama entidad-relacion.
  • docs/login_seq.md: secuencia de login.

Notas

  • El modelo de emociones se ejecuta localmente mediante Transformers.
  • La generacion textual del chatbot intenta usar Hugging Face y, si no esta disponible, cae a una plantilla local.
  • OMDb solo es necesario para mostrar posters; el recomendador funciona sin esa clave.
  • history.db es una base local generada en ejecucion y no deberia versionarse.