Comentarios en parte BD

backend/db.py

@@ -1,21 +1,33 @@
+"""
+Este archivo se encarga de gestionar la conexion con la BD
+así como de crear las tablas iniciales necesarias para almacenar 
+el historial de visionado
+"""
+
 import sqlite3
 
 from config import HISTORY_DB_PATH
 
 
-def get_db_connection() -> sqlite3.Connection:
+def obtener_conexion_bd() -> sqlite3.Connection:
+    """
+    Crea la conexión con la base de datos SQLite
+    """
     # Cada conexion usa sqlite3.Row para acceder por nombre de columna.
-    conn = sqlite3.connect(HISTORY_DB_PATH)
-    conn.row_factory = sqlite3.Row
+    conn = sqlite3.connect(HISTORY_DB_PATH) # Se conecta a la BD en la ruta configurada
+    conn.row_factory = sqlite3.Row # Permite acceder a las filas como diccionarios por nombre de columna
     return conn
 
 
-def init_history_db() -> None:
-    with get_db_connection() as conn:
+def iniciar_historial_usuario() -> None:
+    """
+    Inicia la BD creando todas las tablas necesarias 
+    """
+    with obtener_conexion_bd() as conn:
         # Historial de visionado con rating opcional por usuario.
         conn.execute(
             """
-            CREATE TABLE IF NOT EXISTS view_history (
+            CREATE TABLE IF NOT EXISTS historial_peliculas (
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
                 user_id TEXT NOT NULL,
                 movie_id TEXT NOT NULL,
@@ -28,21 +40,23 @@ def init_history_db() -> None:
             """
         )
         # Compatibilidad con BDs existentes creadas sin columna de valoracion.
-        columns = conn.execute("PRAGMA table_info(view_history)").fetchall()
+        columns = conn.execute("PRAGMA table_info(historial_peliculas)").fetchall()
         column_names = {row[1] for row in columns}
         if "user_rating" not in column_names:
-            conn.execute("ALTER TABLE view_history ADD COLUMN user_rating REAL")
+            conn.execute("ALTER TABLE historial_peliculas ADD COLUMN user_rating REAL")
 
         # Indices para lecturas frecuentes por usuario + fecha.
         conn.execute(
             """
-            CREATE INDEX IF NOT EXISTS idx_view_history_user_viewed_at
-            ON view_history (user_id, viewed_at DESC)
+            CREATE INDEX IF NOT EXISTS idx_historial_peliculas_user_viewed_at
+            ON historial_peliculas (user_id, viewed_at DESC)
             """
         )
+        # Crea una tabla para eventos de emocion detectada con texto analizado.
+        # Tiene para los distintos usuarios un registro del texto a analizar, la emocion detectada y cuando se hizo
         conn.execute(
             """
-            CREATE TABLE IF NOT EXISTS emotion_events (
+            CREATE TABLE IF NOT EXISTS eventos_emociones (
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
                 user_id TEXT NOT NULL,
                 text TEXT,
@@ -53,13 +67,14 @@ def init_history_db() -> None:
         )
         conn.execute(
             """
-            CREATE INDEX IF NOT EXISTS idx_emotion_events_user_analyzed_at
-            ON emotion_events (user_id, analyzed_at DESC)
+            CREATE INDEX IF NOT EXISTS idx_eventos_emociones_user_analyzed_at
+            ON eventos_emociones (user_id, analyzed_at DESC)
             """
         )
+        # Tabla para ciclos de recomendacion con datos pre y post recomendacion.
         conn.execute(
             """
-            CREATE TABLE IF NOT EXISTS recommendation_cycles (
+            CREATE TABLE IF NOT EXISTS ciclos_recomendaciones (
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
                 user_id TEXT NOT NULL,
                 pre_text TEXT,
@@ -78,8 +93,8 @@ def init_history_db() -> None:
         )
         conn.execute(
             """
-            CREATE INDEX IF NOT EXISTS idx_recommendation_cycles_user_created_at
-            ON recommendation_cycles (user_id, created_at DESC)
+            CREATE INDEX IF NOT EXISTS idx_ciclos_recomendaciones_user_created_at
+            ON ciclos_recomendaciones (user_id, created_at DESC)
             """
         )
         conn.commit()

backend/repositories/__init__.py

@@ -0,0 +1,2 @@
+#Se utiliza para marcar el paquete de Python
+#Asi los imports relativos dentro del backend funcionan

backend/repositories/history_repository.py

@@ -1,45 +1,85 @@
-from db import get_db_connection
-
-
-def delete_user_history(user_id: str) -> int:
-    with get_db_connection() as conn:
+"""
+Este archivo contiene funciones para realizar sobre la BD operaciones sobre el 
+historial de visionado del usuario y el seguimiento del ciclo de recomendacion
+siguiendo eventos emocionales del usuario antes y despues de la recomendacion.
+
+Solo hay funciones que acceden a la informacion de las tablas de la BD
+"""
+
+# Se importan la funcion que conecta con la BD de Sqlite para ejecutar las consultas
+from db import obtener_conexion_bd
+
+def borrar_historial_usuario(user_id: str) -> int:
+    """
+    Borra el historial de visionado de un usuario.
+
+    Args:
+        - user_id: El ID del usuario cuyo historial se desea borrar.
+    Returns:
+        - El número de registros eliminados del historial.
+    """
+    with obtener_conexion_bd() as conn:
         # Se ejecuta DELETE para borrar historial de visionado del usuario.
         cur = conn.execute(
             """
-            DELETE FROM view_history
+            DELETE FROM historial_peliculas
             WHERE user_id = ?
             """,
             (user_id,),
         )
-        conn.commit()
+        conn.commit() # Se hace commit para confirmar cambios con insert, update o delete
         return int(cur.rowcount or 0)
 
 
-def get_user_history_rows(user_id: str, limit: int = 200) -> list[dict]:
-    with get_db_connection() as conn:
+def obtener_historial_usuario(user_id: str, limit: int = 200) -> list[dict]:
+    """
+    Obtiene las filas del historial de visionado de un usuario.
+
+    Args:
+        - user_id: El ID del usuario cuyo historial se desea obtener.
+        - limit: El número máximo de registros a obtener.
+
+    Returns:
+        - Una lista de diccionarios con los registros del historial.
+    """
+    with obtener_conexion_bd() as conn:
         # Consulta base para perfilar recomendaciones con movie_id y user_rating.
-        rows = conn.execute(
+        filas = conn.execute(
             """
             SELECT movie_id, user_rating
-            FROM view_history
+            FROM historial_peliculas
             WHERE user_id = ?
             ORDER BY viewed_at DESC
             LIMIT ?
             """,
             (user_id, limit),
         ).fetchall()
-    return [dict(row) for row in rows]
+    
+    # Devuelve un diccionario con (movie_id, user_rating) para cada fila del historial del usuario
+    return [dict(fila) for fila in filas]
+
 
+def añadir_evento_emocional(user_id: str, text: str, emotion: str, analyzed_at: str) -> int | None:
+    """
+    Añade cuando se le detecta una emocion al usuario
+
+    Args:
+        - user_id: El ID del usuario al que se le detecta la emocion.
+        - text: El texto analizado para detectar la emocion.
+        - emotion: La emocion detectada.
+        - analyzed_at: La fecha y hora en formato ISO cuando se analizo el texto.
+    Returns:
+        - El ID del evento emocional insertado o None si no se pudo insertar.
+    """
 
-def save_emotion_event(user_id: str, text: str, emotion: str, analyzed_at: str) -> int | None:
     if not user_id:
         return None
 
-    with get_db_connection() as conn:
+    with obtener_conexion_bd() as conn:
         # Registro temporal de cada analisis emocional del usuario.
         cur = conn.execute(
             """
-            INSERT INTO emotion_events (user_id, text, emotion, analyzed_at)
+            INSERT INTO eventos_emociones (user_id, text, emotion, analyzed_at)
             VALUES (?, ?, ?, ?)
             """,
             (user_id, text, emotion, analyzed_at),
@@ -48,7 +88,7 @@ def save_emotion_event(user_id: str, text: str, emotion: str, analyzed_at: str)
         return cur.lastrowid
 
 
-def create_recommendation_cycle(
+def crear_ciclo_recomendacion(
     user_id: str,
     pre_text: str,
     pre_emotion: str,
@@ -56,14 +96,30 @@ def create_recommendation_cycle(
     recommendation_mode: str,
     created_at: str,
 ) -> int | None:
+    """
+    Crea un nuevo ciclo de recomendacion para seguimiento posterior.
+    Un ciclo de recomendacion contiene el estado emocional previo a la recomendacion, el modo de recomendacion aplicado,
+    y luego se actualiza con el estado posterior y pelicula elegida por el usuario.
+
+    Args:
+        - user_id: El ID del usuario para el que se crea el ciclo de recomendacion
+        - pre_text: El texto analizado para detectar la emocion previa a la recomendacion
+        - pre_emotion: La emocion detectada previa a la recomendacion
+        - pre_valence: La valencia detectada previa a la recomendacion
+        - recommendation_mode: El modo de recomendacion aplicado (exploracion o zona conocida)
+        - created_at: La fecha y hora en formato ISO cuando se creo el ciclo de recomendación
+    Returns:
+        - El ID del ciclo de recomendacion creado o None si no se pudo crear
+
+    """
     if not user_id:
         return None
 
-    with get_db_connection() as conn:
+    with obtener_conexion_bd() as conn:
         # Se guarda el estado previo a la recomendacion para seguimiento posterior.
         cur = conn.execute(
             """
-            INSERT INTO recommendation_cycles (
+            INSERT INTO ciclos_recomendaciones (
                 user_id,
                 pre_text,
                 pre_emotion,
@@ -79,23 +135,33 @@ def create_recommendation_cycle(
         return cur.lastrowid
 
 
-def get_recommendation_cycle(cycle_id: int, user_id: str) -> dict | None:
-    with get_db_connection() as conn:
-        row = conn.execute(
+def obtener_ciclo_recomendacion(cycle_id: int, user_id: str) -> dict | None:
+    """
+    Funcion que devuelve un ciclo de recomendacion de la BD
+
+    Args:   
+        - cycle_id: El ID del ciclo de recomendacion a obtener
+        - user_id: El ID del usuario al que pertenece el ciclo de recomendacion
+    Returns:
+        - Un diccionario con los datos del ciclo de recomendacion o None si no se encuentra
+    """
+
+    with obtener_conexion_bd() as conn:
+        fila = conn.execute(
             """
             SELECT id, user_id, pre_text, pre_emotion, pre_valence, recommendation_mode,
                    created_at, selected_movie_id, selected_movie_title,
                    post_text, post_emotion, post_valence, post_analyzed_at
-            FROM recommendation_cycles
+            FROM ciclos_recomendaciones
             WHERE id = ? AND user_id = ?
             LIMIT 1
             """,
             (cycle_id, user_id),
-        ).fetchone()
-    return dict(row) if row else None
+        ).fetchone() # Se usa fetchone porque solo hay un ciclo correspondiente
+    return dict(fila) if fila else None
 
 
-def save_post_recommendation_state(
+def guardar_estado_posterior(
     cycle_id: int,
     user_id: str,
     post_text: str,
@@ -105,11 +171,28 @@ def save_post_recommendation_state(
     movie_id: str,
     movie_title: str,
 ) -> None:
-    with get_db_connection() as conn:
+    """
+    Funcion que añade a un ciclo de recomendacion el estado posterior a la recomendacion
+    Se le preguntara al usuario que introduzca un rating de la pelicula vista
+    Asi como que exprese su emocion una vez vista la pelicula, para medir el cambio emocional y de valencia
+
+    Args:
+        - cycle_id: El ID del ciclo de recomendacion a actualizar
+        - user_id: El ID del usuario al que pertenece el ciclo de recomendacion
+        - post_text: El texto analizado para detectar la emocion posterior a la recomendacion
+        - post_emotion: La emocion detectada posterior a la recomendacion
+        - post_valence: La valencia detectada posterior a la recomendacion
+        - post_analyzed_at: La fecha y hora en formato ISO cuando se analizo el texto posterior a la recomendacion
+        - movie_id: El ID de la pelicula vista que se le pregunta al usuario
+        - movie_title: El titulo de la pelicula vista que se le pregunta al usuario
+    Returns:
+        - None (es un update de una instancia ya creada en la BD)
+    """
+    with obtener_conexion_bd() as conn:
         # Actualiza el ciclo con pelicula elegida y estado emocional posterior.
         conn.execute(
             """
-            UPDATE recommendation_cycles
+            UPDATE ciclos_recomendaciones
             SET selected_movie_id = ?,
                 selected_movie_title = ?,
                 post_text = ?,
@@ -123,15 +206,26 @@ def save_post_recommendation_state(
         conn.commit()
 
 
-def get_last_emotion_event(user_id: str) -> dict | None:
+def obtener_ultima_emocion(user_id: str) -> dict | None:
+    """
+    Funcion que devuelve el ultimo evento emocional registrado para un usuario
+    Se utiliza para detectar la emocion previa a una recomendacion y medir transiciones emocionales
+
+    Args: 
+        - user_id: El ID del usuario del que se desea obtener el ultimo evento emocional
+    Returns:
+        - Un diccionario con los datos del ultimo evento emocional o None si no se encuentra. El diccionario contiene las claves: id, user_id, text, emotion, analyzed_at
+    """
+
     if not user_id:
         return None
 
-    with get_db_connection() as conn:
-        row = conn.execute(
+    with obtener_conexion_bd() as conn:
+        # Se realiza la consulta, se ordena descendentemente por fecha y nos quedamos con la ultima instancia
+        fila = conn.execute(
             """
             SELECT id, user_id, text, emotion, analyzed_at
-            FROM emotion_events
+            FROM eventos_emociones
             WHERE user_id = ?
             ORDER BY analyzed_at DESC
             LIMIT 1
@@ -139,15 +233,26 @@ def get_last_emotion_event(user_id: str) -> dict | None:
             (user_id,),
         ).fetchone()
 
-    return dict(row) if row else None
+    return dict(fila) if fila else None
+
 
+def obtener_pelicula_vista_entre(user_id: str, start_iso: str, end_iso: str) -> dict | None:
+    """
+    Funcion que obtiene la pelicula vista por el usuario entre dos momentos determinados
+    Se usa para detectar la pelicula vista entre dos eventos de recogida de estado emocional
 
-def get_last_viewed_between(user_id: str, start_iso: str, end_iso: str) -> dict | None:
-    with get_db_connection() as conn:
-        row = conn.execute(
+    Args:
+        - user_id: El ID del usuario del que se desea obtener la pelicula vista
+        - start_iso: El momento inicial en formato ISO entre el que se desea obtener la pelicula vista
+        - end_iso: El momento final en formato ISO entre el que se desea obtener la pelicula vista
+    Returns:
+        - Un diccionario con los datos de la pelicula vista entre ambos momentos o None si no se encuentra. El diccionario contiene las claves: movie_id, title, viewed_at
+    """
+    with obtener_conexion_bd() as conn:
+        fila = conn.execute(
             """
             SELECT movie_id, title, viewed_at
-            FROM view_history
+            FROM historial_peliculas
             WHERE user_id = ?
               AND viewed_at > ?
               AND viewed_at <= ?
@@ -157,10 +262,10 @@ def get_last_viewed_between(user_id: str, start_iso: str, end_iso: str) -> dict
             (user_id, start_iso, end_iso),
         ).fetchone()
 
-    return dict(row) if row else None
-
+    return dict(fila) if fila else None
+    
 
-def insert_view_history(
+def añadir_pelicula_a_historial(
     user_id: str,
     movie_id: str,
     title: str,
@@ -169,10 +274,24 @@ def insert_view_history(
     session_text: str,
     viewed_at: str,
 ) -> int:
-    with get_db_connection() as conn:
+    """
+    Funcion que añade al historial de visualizaciones una nueva pelicula, junto con su valoracion y emocion
+
+    Args:
+        - user_id: El ID del usuario al que se le añade la pelicula al historial
+        - movie_id: El ID de la pelicula vista
+        - title: El titulo de la pelicula vista
+        - emotion: La emocion asociada a la pelicula vista (puede ser la emocion detectada en el texto del usuario)
+        - user_rating: La valoracion que el usuario da a la pelicula vista (puede ser None si no se proporciona)
+        - session_text: El texto de la sesion que se asocia a la pelicula vista
+        - viewed_at: La fecha y hora en formato ISO cuando se visualizo la pelicula
+    Returns:
+        - El ID del registro insertado en el historial de visualizaciones
+    """
+    with obtener_conexion_bd() as conn:
         cur = conn.execute(
             """
-            INSERT INTO view_history (user_id, movie_id, title, emotion, user_rating, session_text, viewed_at)
+            INSERT INTO historial_peliculas (user_id, movie_id, title, emotion, user_rating, session_text, viewed_at)
             VALUES (?, ?, ?, ?, ?, ?, ?)
             """,
             (user_id, movie_id, title, emotion, user_rating, session_text, viewed_at),
@@ -181,28 +300,51 @@ def insert_view_history(
         return int(cur.lastrowid)
 
 
-def get_history_items(user_id: str, limit: int) -> list[dict]:
-    with get_db_connection() as conn:
-        rows = conn.execute(
+def obtener_peliculas_del_historial(user_id: str, limit: int) -> list[dict]:
+    """
+    Funcion que devuelve las ultimas peliculas vistas por el usuario junto con su emocion asociada
+    Se utiliza para detectar transiciones emocionales entre peliculas vistas y medir su frecuencia
+
+    Args:
+        - user_id: El ID del usuario del que se desea obtener las peliculas vistas
+        - limit: El número máximo de registros a obtener
+
+    Returns:
+        - Una lista de diccionarios con los datos de las peliculas vistas por el usuario. Cada diccionario contiene las claves: movie_id, title, emotion, viewed_at; ordenado por fecha de visualizacion empezando por la mas reciente
+    """
+    with obtener_conexion_bd() as conn:
+        filas = conn.execute(
             """
             SELECT id, user_id, movie_id, title, emotion, user_rating, session_text, viewed_at
-            FROM view_history
+            FROM historial_peliculas
             WHERE user_id = ?
             ORDER BY viewed_at DESC
             LIMIT ?
             """,
             (user_id, limit),
         ).fetchall()
-    return [dict(row) for row in rows]
+    return [dict(fila) for fila in filas]
+
 
+def obtener_relacion_pelicula_emocion(user_id: str, limit: int) -> list[dict]:
+    """
+    Funcion que calcula que peliculas han sido vistas por el usuario entre eventos emocionales con cambio de emocion
+    De esta manera se detecta que peliculas estan asociadas a que transiciones emocionales y con que frecuencia
 
-def get_transition_items(user_id: str, limit: int) -> list[dict]:
-    with get_db_connection() as conn:
-        # Se toman eventos y vistas en orden cronologico para detectar transiciones.
-        event_rows = conn.execute(
+    Args: 
+    - user_id: El ID del usuario del que se desea obtener las transiciones emocionales asociadas a peliculas vistas
+    - limit: El número máximo de registros a obtener
+
+    Returns:
+        - Una lista de diccionarios con los datos de las transiciones emocionales asociadas a peliculas vistas por el usuario. Cada diccionario contiene las claves: movie_id, title, from_emotion, to_emotion, count; ordenado por frecuencia de la transicion empezando por la mas frecuente
+    """
+
+    with obtener_conexion_bd() as conn:
+        # Se obtiene el historial de eventos emocionales (texto y emocion asociada)
+        filas_emociones = conn.execute(
             """
             SELECT id, user_id, text, emotion, analyzed_at
-            FROM emotion_events
+            FROM eventos_emociones
             WHERE user_id = ?
             ORDER BY analyzed_at ASC
             LIMIT 500
@@ -210,10 +352,11 @@ def get_transition_items(user_id: str, limit: int) -> list[dict]:
             (user_id,),
         ).fetchall()
 
-        view_rows = conn.execute(
+        # Se obtiene el historial de peliculas vistas (movie_id, title y momento del visionado)
+        filas_peliculas = conn.execute(
             """
             SELECT movie_id, title, viewed_at
-            FROM view_history
+            FROM historial_peliculas
             WHERE user_id = ?
             ORDER BY viewed_at ASC
             LIMIT 1000
@@ -221,40 +364,50 @@ def get_transition_items(user_id: str, limit: int) -> list[dict]:
             (user_id,),
         ).fetchall()
 
-    events = [dict(row) for row in event_rows]
-    views = [dict(row) for row in view_rows]
+    emociones = [dict(fila) for fila in filas_emociones]
+    peliculas = [dict(fila) for fila in filas_peliculas]
 
+    # Se recorren los eventos emocionales buscando transiciones de emocion entre eventos consecutivos
     # (movie_id, title, emocion_origen, emocion_destino) -> conteo.
     transition_counter: dict[tuple[str, str, str, str], int] = {}
 
-    for idx in range(1, len(events)):
-        prev_event = events[idx - 1]
-        curr_event = events[idx]
-        if prev_event.get("emotion") == curr_event.get("emotion"):
+    for idx in range(1, len(emociones)):
+        emocion_previa = emociones[idx - 1]
+        emocion_actual = emociones[idx]
+        
+        #Si son la misma emocion no se ha transicionado
+        if emocion_previa.get("emotion") == emocion_actual.get("emotion"):
             continue
-
-        start = prev_event.get("analyzed_at", "")
-        end = curr_event.get("analyzed_at", "")
-
+        
+        #En caso de haber cambiado de estado emocional se obtiene el momento de ambos eventos para buscar la pelicula vista
+        #entre ambos momentos
+        momento_inicio = emocion_previa.get("analyzed_at", "")
+        momento_fin = emocion_actual.get("analyzed_at", "")
+        
+        # Se busca la pelicula vista en ese momento en especifico
         matched_movie = None
-        for view in reversed(views):
-            viewed_at = view.get("viewed_at", "")
-            if start < viewed_at <= end:
-                matched_movie = view
+        for pelicula in reversed(peliculas):
+            viewed_at = pelicula.get("viewed_at", "")
+            if momento_inicio < viewed_at <= momento_fin:
+                matched_movie = pelicula
                 break
 
         if not matched_movie:
             continue
-
+        
+        # Si se encuentra una pelicula vista entre ambos eventos emocionales
+        # se cuenta la transicion emocional asociada a esa pelicula, para detectar 
+        # que peliculas estan mas asociadas a que transiciones emocionales
         key = (
             str(matched_movie.get("movie_id", "")),
             matched_movie.get("title") or "",
-            prev_event.get("emotion", ""),
-            curr_event.get("emotion", ""),
+            emocion_previa.get("emotion", ""),
+            emocion_actual.get("emotion", ""),
         )
         transition_counter[key] = transition_counter.get(key, 0) + 1
 
     items = []
+    # Se construye la lista de diccionarios con los datos de las peliculas asociadas a transiciones emocionales y su frecuencia
     for (movie_id, title, from_emotion, to_emotion), count in transition_counter.items():
         items.append(
             {

backend/services/__init__.py

@@ -0,0 +1,2 @@
+#Se utiliza para marcar el paquete de Python
+#Asi los imports relativos dentro del backend funcionan